Improved documentation

Author: rsouverain

Diff for: README.md

@@ -1,32 +1,58 @@
 # php.demo.api.graphql.slim
-Just a DEMO API built around SLIM framework and GraphQL-PHP
 
-## Work in progress
+This project is a demo project aimed to demonstrate a slightly more advanced implementation of GraphQL in PHP than your average demo tutorial, yet still easy to understand. Featuring multi-endpoints, dynamic types, query and mutation, and APQ, a performent caching mecanism for queries.
+
+## :construction: Work in progress
+
+This is a work in progress still in its early stage of infancy. Ultimately, the purpose of this project is educational and hopefully will evolve to adhere to the most relevant best practices available.
+
+I've got a NodeJS implementation already in the pipe, buty will come out later since it was a practical case and not oriented toward an educational purpose.
+
+## :star: Starring:
+
+* [SLIM Framework](https://www.slimframework.com/)
+* [Symfony Cache](https://symfony.com/doc/current/components/cache.html) ([PSR-6](https://symfony.com/doc/current/components/cache.html#basic-usage-psr-6), [Redis](https://symfony.com/doc/current/components/cache/adapters/redis_adapter.html))
+* [GraphQL-PHP](https://webonyx.github.io/graphql-php)
+* [GraphQL Automatic Persisted Queries](https://www.apollographql.com/docs/apollo-server/performance/apq/)
+
+## Documentations
+
+### Transverse
+
+* [Coding Standards](./docs/CodingStandards.md) : Read more about today's more favored Coding style.
+* [GraphQL](./docs/GraphQL.md) : General purpose doc about GQL.
+
+### Classes
+
+* [CacheManager](./docs/CacheManager.md) : For every memoization needs, via Redis persistent connection.
+* [SchemaLoader](./docs/SchemaLoader.md) : Automatically find and load php files related to graphql type definition into a coherent GraphQL Schema.
+* [Endpoint](./docs/Endpoint.md) : Allows for quick endpoint creation using various schema compositions.
+* APQ: @TODO
+* Auth: @TODO
+
+## GraphQL
+
+### Endpoints
+
+* `http://127.0.0.1:9632`
+  * `/graphql/blog` The 'blog' api endpoint and schema.
+  * `/graphql/refs` Another 'refs' api endpoint with another schema
 
 
 ## Docker
 
 From the project main directory:
 
-(on windows, you may want to use `winpty` before `docker exec ...`)
-
 
 ```bash
 docker-compose build
-docker-compose run
 docker-compose up -d
 docker-compose down
 ```
 
 Connect to container as CLI (optional)
+
 ```bash
+# on windows, you may want to consider using the `winpty` command before `docker exec`)
 docker exec -ti gql_slim_api sh
 ```
-
-
-## GraphQL
-
-### Endpoints
-
-* `/graphql/blog` The 'blog' api endpoint and schema.
-* `/graphql/refs` Another 'refs' api endpoint with another schema

Diff for: docs/CacheManager.md

@@ -0,0 +1,47 @@
+# Cache Manager
+
+## Namespace
+
+`App\GraphQL\Boilerplate\CacheManager`
+
+## Description
+
+This class is an utility giving the developer an actionnable API to interract with a performent caching mecanism like Redis.
+
+The basic use will be to store key/value pairs with a Time To Live (TTL) expiration time.
+
+## Usages
+
+### With Symfony Contracts
+
+* [Read more](https://symfony.com/doc/current/components/cache.html#cache-contracts)
+
+```php
+use App\GraphQL\Boilerplate\CacheManager;
+$memoization = CacheManager::getInstance();
+$value = $memoization->get('FOO', function (\Symfony\Contracts\Cache\ItemInterface $item) {
+    $item->expiresAfter(10); //seconds 
+    return 'BAR';
+});
+```
+
+### Without Symfony Contracts (pure PSR-6)
+
+* [Read more](https://symfony.com/doc/current/components/cache.html#generic-caching-psr-6)
+
+```php
+$memoization = CacheManager::getInstance();
+$foo = $memoization->getItem('FOO');
+if (!$foo->isHit()) {
+    // foo item does not exist in the cache
+    $foo->set('BAR')->expiresAfter(10);
+    $memoization->save($foo);
+}
+// retrieve the value stored by the item
+$value = $foo->get();
+```
+
+> TODO: Improving this section of documentation with more detailled and explained use cases.
+
+----
+* Back to [README](../README.md)

Diff for: docs/CodingStandards.md

@@ -0,0 +1,80 @@
+# Coding Standards
+
+The aim is to follow most of [PSR-12 "Extended Coding Style"](https://www.php-fig.org/psr/psr-12/), as well as [Symfony Coding Standards](https://symfony.com/doc/current/contributing/code/standards.html#symfony-coding-standards-in-detail).
+
+> TODO: Work in Progress: PHP-CS Will be used with the developer's IDE as a code linter/fixer
+
+
+## Some other practices should be observed
+
+
+### Equals / Identical comparison
+
+Whenever possible, we SHOULD refrain from using the “equal `==`” operator and use the “Identical `===`” operator instead.
+
+
+* Equal: `$a == $b` is `true` if `$a` is equal to `$b`, after type juggling. bad practice
+* Identical: `$a === $b` is `true` if `$a` is equal to `$b`, and they are of the same type.
+
+[Read more about PHP comparison operators](https://www.php.net/manual/en/language.operators.comparison.php).
+
+
+### Variable and object instance name
+
+We MUST always refrain from prefixing a variable name with its type.
+
+bad:
+```php
+$str_c = ‘red’;
+$o_myobject = new Car(‘toyota’);
+$int_iTab = 0;
+```
+
+good:
+```php
+$color = ‘red’;
+$toyotaCar = new Car(‘toyota’);
+$tabIndex = 0;
+```
+
+When a variable represents an object's Class, it is RECOMMENDED to have PascalCase used. The first letter SHOULD be in uppercase to indicate a complex structure and not a simple scalar value. i.e: `FlyingMachine`
+
+To have a seamless experience reading the code, it is REQUIRED to ease the reading by using variable and constant names that are intuitive and speaking for themselves.
+
+Acronyms should retain their capital letters when placed at the end of a variable’s name:
+```php
+$lastUpdatedDateUTC = ...
+$isAgencyCIA = false;
+```
+
+Boolean constant and variables MUST start with ‘is’, ‘has’, ‘had’, ‘was’, ‘were’:
+```php
+$isBlue = true;
+$wasUpdatedLastWeek = true;
+$hasAlreadyPaidOnce = true;
+$wereBulkImported = false;
+```
+
+### Date, DateTimes and TimeZones
+
+NEVER rely on the default value for the default timezone as it can be changed in php files, php config files, and always fallback to the server’s OS config. Depending on where your code is deployed (server locale), and your level of config optimisation, relying on a default timezone will result in inconsistencies with your saved dates in database and server side logic.
+
+All dates MUST be stored and manipulated as from the UTC timezone.
+UTC dates SHOULD only be converted to a local date format upon being displayed for a specific user.
+
+```php
+$nowUTC = new \DateTime('now', new \DateTimeZone('UTC'));
+$nowFR = clone($nowUTC);
+$nowFR->setTimezone(new \DateTimeZone('Europe/Paris'));
+echo $nowFR->format(\DateTimeInterface::ISO8601);
+```
+
+Dates instantiated from a static source like a database fetch, SHOULD be instances of \DateTimeImmutable
+
+
+### End of file
+
+Each code file must end with an empty new line and not include a closing php tag `?>`
+
+----
+* Back to [README](../README.md)

Diff for: docs/Endpoint.md

@@ -0,0 +1,26 @@
+# Endpoint
+
+## Namespace
+
+`App\GraphQL\Boilerplate\Endpoint`
+
+## Description
+
+This class is an utility giving the developer an actionnable API to create a graphql-php schema resolving endpoint.
+It was built to wrap-up the common code required to resolve a Schema and interact with a [PSR-7](https://www.php-fig.org/psr/psr-7/) compatible Response.
+
+It can be easily integrated with an MVC application featuring Controllers like SLIM and Symfony, but is quite easy to adapt to any kind of application.
+
+## Usages
+
+* Inspect [App\Controller\GraphqlController](../app/src/Controller/GraphqlController.php)
+
+>TODO: Improve this section of the documentation. ( :construction: WiP )
+
+```php
+$endpoint = new Endpoint();
+$endpoint->executeSchema($SchemaOptions);
+```
+
+----
+* Back to [README](../README.md)