Documentation

README.md

@@ -4,60 +4,75 @@
 
 ## FEATURES
 
-- use OAuth 2.0
-- Read objects from API, XAPI and Overpass-API.
-- Write objects to API.
-- Authenticate with Basic or OAuth.
-- The class instance and its osm objects are serializable.
-- A bit of geometry stuff (is node inside/outside polygon)
+- Read (query) objects from **API**, **XAPI** and **Overpass**.
+- Write (create, update, delete) objects on **API**.
+- Authenticate with Basic or **OAuth 2**.
+- Class for osm objects are **serializable**.
+- A bit of **geometry** stuff are available locally (on query result)
+  - is node inside/outside polygon
+  - get gravity center for relation or way
 - ...
 
-## REQUIREMENTS
+## TUTORIALS / EXAMPLES
 
-Requirements are covered in `composer.json`.
+- install dependencies
+  - `composer install`
 
-Php extensions:
+By default:
+  - API operations are done on Osm developement instance at `master.apis.dev.openstreetmap.org` ;
+    - Write operations are carried out in "simulation" mode, so that no queries are made.
+  - Overpass queries are done on `overpass-api.de` ;
+  - XAPI  queries are done on `overpass-api.de`.
 
-- [SimpleXml](https://www.php.net/manual/en/book.simplexml.php)
+To overide those default behaviors, create file `.env` and set
+  - `simulation=false` to really write on API
+  - `osm_api_url = https://api.openstreetmap.org/api/0.6` to query and update on production OSM instance
 
-Php libraries:
+Read `.env.example` to know more about configuration.
 
-- [psr/log](https://github.com/php-fig/log)
-- [vlucas/phpdotenv](https://github.com/vlucas/phpdotenv)
-- [jbelien/oauth2-openstreetmap](https://github.com/jbelien/oauth2-openstreetmap)
-  - which is a provider for [league/oauth2-client](https://github.com/thephpleague/oauth2-client)
+### Generate an Access Token
 
-## TUTORIALS / EXAMPLES
+The command-line `oauth/oauth-console.php` will drive you on getting an OAuth2 Access Token, launch it and read the instructions.
+the command consists of several stages:
+1. choose the OSM server instance
+2. choose the permissions you need
+3. enter Application ID and Secret, with help to create one if needed
+4. get an authorization code
+5. finally, get the precious Access Token you need to access some services as an authenticated user.
 
-- install dependencies
-  - `composer install`
-- create file `.env` and set
-  - osm_api_url = https://master.apis.dev.openstreetmap.org/api/0.6
-  - oauth_url = https://master.apis.dev.openstreetmap.org
-  - simulation=false
-  - read `.env.example` to know more about configuration
+To facilitate the procedure for obtaining the token, a Web page is **currently under construction** at `oatuh/OAuthRequestAccess.php`
 
-- Use the provided web page to create an OAuth Access Token
-  - change directory `cd examples-web`
-  - launch the php webserver `php -S localhost:8000`
-  - then open a browser at  `http://localhost:8000/OAuthRequestAccess.php`
+### examples-console
 
-- Explore command-line examples in `examples-console`
+Look at the code to learn more abour Yapafo.
 
 ### examples-web
 
-- the tool examples/OAuthRequestAccess.php is an easy way to get OAuth Access Token (and understand the protocol phases ;-)
-- Overpass-API requests are shown in examples/OApiQuery.php and ApiOApiQuery.php
+Work in progress
 
 ## BUG and Request
 
 - https://github.com/Cyrille37/yapafo/issues
 
-## References
+## REQUIREMENTS
 
-- https://wiki.openstreetmap.org/wiki/OAuth
+Requirements are covered by `composer.json`.
 
-- The OAuth 1.0 Protocol : http://tools.ietf.org/html/rfc5849
+Php >=7.4 et <8.3.
+
+Php extensions:
+
+- [SimpleXml](https://www.php.net/manual/en/book.simplexml.php)
+
+Php libraries:
+
+- [psr/log](https://github.com/php-fig/log)
+- [vlucas/phpdotenv](https://github.com/vlucas/phpdotenv)
+- [jbelien/oauth2-openstreetmap](https://github.com/jbelien/oauth2-openstreetmap)
+  - which is a provider for [league/oauth2-client](https://github.com/thephpleague/oauth2-client)
+
+## References
+
+- The OAuth 2 Protocol : https://oauth.net/2/ and https://datatracker.ietf.org/doc/html/rfc6749
 - OSM OAuth doc : http://wiki.openstreetmap.org/wiki/OAuth
 - [PSR-3: Logger Interface](https://www.php-fig.org/psr/psr-3/)
-