From a9ee6369ad7bb38cb56a236d0833f19ed67d97d2 Mon Sep 17 00:00:00 2001
From: alexmerlin <alex.merlin.1985@gmail.com>
Date: Tue, 19 Mar 2024 17:35:22 +0200
Subject: [PATCH] Issue #37: Added documentation for v4 and v5

Signed-off-by: alexmerlin <alex.merlin.1985@gmail.com>
---
 README.md                            | 18 +++---
 docs/book/index.md                   |  1 +
 docs/book/v4/cache.md                | 37 ++++++++++++
 docs/book/v4/configuration.md        |  6 ++
 docs/book/v4/factories.md            | 69 ++++++++++++++++++++++
 docs/book/v4/factories/repository.md | 59 +++++++++++++++++++
 docs/book/v4/factories/service.md    | 86 ++++++++++++++++++++++++++++
 docs/book/v4/installation.md         |  5 ++
 docs/book/v4/overview.md             |  5 ++
 docs/book/v4/usage.md                |  7 +++
 docs/book/v5/configuration.md        |  6 ++
 docs/book/v5/factories.md            | 31 ++++++++++
 docs/book/v5/factories/repository.md | 57 ++++++++++++++++++
 docs/book/v5/factories/service.md    | 82 ++++++++++++++++++++++++++
 docs/book/v5/installation.md         |  5 ++
 docs/book/v5/overview.md             |  5 ++
 docs/book/v5/usage.md                |  7 +++
 mkdocs.yml                           | 37 ++++++++++++
 18 files changed, 514 insertions(+), 9 deletions(-)
 create mode 100644 docs/book/index.md
 create mode 100644 docs/book/v4/cache.md
 create mode 100644 docs/book/v4/configuration.md
 create mode 100644 docs/book/v4/factories.md
 create mode 100644 docs/book/v4/factories/repository.md
 create mode 100644 docs/book/v4/factories/service.md
 create mode 100644 docs/book/v4/installation.md
 create mode 100644 docs/book/v4/overview.md
 create mode 100644 docs/book/v4/usage.md
 create mode 100644 docs/book/v5/configuration.md
 create mode 100644 docs/book/v5/factories.md
 create mode 100644 docs/book/v5/factories/repository.md
 create mode 100644 docs/book/v5/factories/service.md
 create mode 100644 docs/book/v5/installation.md
 create mode 100644 docs/book/v5/overview.md
 create mode 100644 docs/book/v5/usage.md
 create mode 100644 mkdocs.yml

diff --git a/README.md b/README.md
index 7d1dac5..75f8acf 100644
--- a/README.md
+++ b/README.md
@@ -32,14 +32,14 @@ After installing, register `dot-annotated-services` in your project by adding th
 
 ## Usage
 
-### Using the AnnotatedServiceFactory
+### Using the AttributedServiceFactory
 
-You can register services in the service manager using `AnnotatedServiceFactory` as seen in the below example:
+You can register services in the service manager using `AttributedServiceFactory` as seen in the below example:
 
 ```php
 return [
     'factories' => [
-        ServiceClass::class => AnnotatedServiceFactory::class,
+        ServiceClass::class => AttributedServiceFactory::class,
     ],
 ];
 ```
@@ -54,19 +54,19 @@ The next step is to add the `#[Inject]` attribute to the service constructor wit
 use Dot\AnnotatedServices\Attribute\Inject;
 
 #[Inject(
-    Dependency1::class,
-    Dependency2::class,
+    App\Srevice\Dependency1::class,
+    App\Srevice\Dependency2::class,
     "config",
 )]
 public function __construct(
-    protected Dependency1 $dep1,
-    protected Dependency2 $dep2,
+    protected App\Srevice\Dependency1 $dep1,
+    protected App\Srevice\Dependency2 $dep2,
     protected array $config
 ) {
 }
 ```
 
-The `#[Inject]` attribute is telling `AnnotatedServiceFactory` to inject the services specified as parameters.
+The `#[Inject]` attribute is telling `AttributedServiceFactory` to inject the services specified as parameters.
 Valid service names should be provided, as registered in the service manager.
 
 To inject an array value from the service manager, you can use dot notation as below
@@ -82,7 +82,7 @@ which will inject `$container->get('config')['debug'];`.
 
 
 ### NOTE 
-> Even if using dot notation, `AnnotatedServiceFactory` will check first if a service name exists with that name.
+> Even if using dot notation, `AttributedServiceFactory` will check first if a service name exists with that name.
 
 
 ### Using the AttributedRepositoryFactory 
diff --git a/docs/book/index.md b/docs/book/index.md
new file mode 100644
index 0000000..ae42a26
--- /dev/null
+++ b/docs/book/index.md
@@ -0,0 +1 @@
+../../README.md
diff --git a/docs/book/v4/cache.md b/docs/book/v4/cache.md
new file mode 100644
index 0000000..9bbf51a
--- /dev/null
+++ b/docs/book/v4/cache.md
@@ -0,0 +1,37 @@
+# Caching the annotations
+
+`dot-annotated-services` reads class annotations using [doctrine/annotations](https://github.com/doctrine/annotations) and caches them using [doctrine/cache](https://github.com/doctrine/cache).
+
+
+## Configuration
+
+In order to cache annotations, you should register a service factory at key `AbstractAnnotatedFactory::CACHE_SERVICE` that should return a valid `Doctrine\Common\Cache\Cache` cache driver.
+See [Cache Drivers](https://github.com/doctrine/cache/tree/1.13.x/lib/Doctrine/Common/Cache) for available implementations offered by doctrine.
+
+See below an example on how you can configure `dot-annotated-services` to cache annotations.
+You can add this configuration values to your application's Doctrine config file:
+
+```php
+    'annotations_cache_dir' => __DIR__ . '/../../data/cache/annotations',
+    'dependencies' => [
+        'factories' => [
+            Dot\AnnotatedServices\Factory\AbstractAnnotatedFactory::CACHE_SERVICE => YourApp\Factory\AnnotationsCacheFactory::class,
+        ],
+    ];
+```
+where `AnnotationsCacheFactory` is a custom factory that needs to return a [Doctrine Cache Driver](https://github.com/doctrine/cache/tree/1.13.x/lib/Doctrine/Common/Cache):
+```php
+<?php
+
+declare(strict_types=1);
+
+namespace YourApp\Factory;
+
+class AnnotationsCacheFactory
+{
+    public function __invoke(Psr\Container\ContainerInterface $container)
+    {
+        return new Doctrine\Common\Cache\FilesystemCache($container->get('config')['annotations_cache_dir']);
+    }
+}
+```
diff --git a/docs/book/v4/configuration.md b/docs/book/v4/configuration.md
new file mode 100644
index 0000000..c8f6f52
--- /dev/null
+++ b/docs/book/v4/configuration.md
@@ -0,0 +1,6 @@
+# Configuration
+
+After installation, register `dot-annotated-services` in your project by adding the below line to your configuration aggregator (usually: `config/config.php`):
+
+     Dot\AnnotatedServices\ConfigProvider::class,
+
diff --git a/docs/book/v4/factories.md b/docs/book/v4/factories.md
new file mode 100644
index 0000000..5bdfe12
--- /dev/null
+++ b/docs/book/v4/factories.md
@@ -0,0 +1,69 @@
+# Factories
+
+`dot-annotated-services` is based on 3 reusable factories - `AnnotatedRepositoryFactory`, `AnnotatedServiceFactory` and `AnnotatedServiceAbstractFactory` - able to inject any dependency into a class.
+
+## AttributedRepositoryFactory
+
+Injects entity repositories into a class.
+
+
+### Exceptions thrown
+- `Dot\AnnotatedServices\Exception\RuntimeException` if repository does not exist
+- `Dot\AnnotatedServices\Exception\RuntimeException` if repository does not extend `Doctrine\ORM\EntityRepository`
+- `Dot\AnnotatedServices\Exception\RuntimeException` if repository does not have `@Entity` annotation
+- `Psr\Container\NotFoundExceptionInterface` if `Doctrine\ORM\EntityManagerInterface` does not exist in the service container
+- `Psr\Container\ContainerExceptionInterface` if service manager is unable to provide an instance of `Doctrine\ORM\EntityManagerInterface`
+
+
+## AttributedServiceFactory
+
+Injects class dependencies into classes.
+
+If a dependency is specified using the dot notation, `AttributedServiceFactory` will try to load a service having that specific alias.
+If it does not find one, it will try to load the dependency as a config tree, checking each segment if it's available in the service container.
+
+You can use the inject annotation on setters too, they will be called at creation time and injected with the configured dependencies.
+
+
+### Exceptions thrown
+- `Dot\AnnotatedServices\Exception\RuntimeException` if service does not exist
+- `Dot\AnnotatedServices\Exception\RuntimeException` if service does not have `@Inject` annotation on it's constructor
+- `ReflectionException` on failure of creating a ReflectionClass of the dependency
+- `Psr\Container\NotFoundExceptionInterface` if a dependency does not exist in the service container
+- `Psr\Container\ContainerExceptionInterface` if service manager is unable to provide an instance of a dependency
+
+
+## AnnotatedServiceAbstractFactory
+
+Using this approach, no service manager configuration is required. It uses the registered abstract factory to create annotated services.
+
+In order to tell the abstract factory which services are to be created, you need to annotate the service class with the `@Service` annotation.
+
+```php
+<?php
+
+declare(strict_types=1);
+
+namespace YourApp\Service;
+
+/**
+ * @Dot\AnnotatedServices\Annotation\Service
+ */
+class Example
+{
+    /**
+     * @Dot\AnnotatedServices\Annotation\Inject({
+     *     YourApp\Repository\Dependency1::class,
+     *     YourApp\Repository\Dependency2::class,
+     *     "config.example"
+     * })
+     */
+    public function __construct(
+        protected YourApp\Repository\Dependency1 $dependency1,
+        protected YourApp\Helper\Dependency2 $dependency2,
+        protected array $exampleConfig,
+    ) {
+    }
+}
+```
+And that's it, you don't need to configure the service manager with this class, creation will happen automatically.
diff --git a/docs/book/v4/factories/repository.md b/docs/book/v4/factories/repository.md
new file mode 100644
index 0000000..e7bdec0
--- /dev/null
+++ b/docs/book/v4/factories/repository.md
@@ -0,0 +1,59 @@
+# Inject entity repositories
+
+
+## Prepare repository
+
+`dot-annotated-services` determines the entity a repository is related to by looking at the `@Entity` annotation, added to the repository class.
+
+```php
+<?php
+
+declare(strict_types=1);
+
+namespace YourApp\Repository;
+
+/**
+ * @Dot\AnnotatedServices\Annotation\Entity(name="YourApp\Entity\Example")
+ */
+class ExampleRepository extends Doctrine\ORM\EntityRepository
+{
+}
+```
+
+Each entity repository must extend `Doctrine\ORM\EntityRepository`.
+
+
+## Register repository
+
+Open the ConfigProvider of the module where your repository resides.
+
+Add a new entry under `factories`, where the key is your repository FQCN and the value is `Dot\AnnotatedServices\Factory\AnnotatedRepositoryFactory::class`.
+
+See below example for a better understanding of the file structure.
+
+```php
+<?php
+
+declare(strict_types=1);
+
+namespace YourApp;
+
+class ConfigProvider
+{
+    public function __invoke(): array
+    {
+        return [
+            'dependencies' => $this->getDependencies(),
+        ];
+    }
+
+    public function getDependencies(): array
+    {
+        return [
+            'factories' => [
+                YourApp\Repository\ExampleRepository::class => Dot\AnnotatedServices\Factory\AnnotatedRepositoryFactory::class,
+            ],
+        ];
+    }
+}
+```
diff --git a/docs/book/v4/factories/service.md b/docs/book/v4/factories/service.md
new file mode 100644
index 0000000..6790658
--- /dev/null
+++ b/docs/book/v4/factories/service.md
@@ -0,0 +1,86 @@
+# Inject class dependencies
+
+
+## Prepare class
+
+`dot-annotated-services` determines the dependencies by looking at the `@Inject` annotation, added to the constructor of a class.
+Dependencies are specified as one parameter, which is an array of FQCNs.
+
+```php
+<?php
+
+declare(strict_types=1);
+
+namespace YourApp\Service;
+
+class Example
+{
+    /**
+     * @Dot\AnnotatedServices\Annotation\Inject({
+     *     YourApp\Repository\Dependency1::class,
+     *     YourApp\Repository\Dependency2::class,
+     *     "config"
+     * })
+     */
+    public function __construct(
+        protected YourApp\Repository\Dependency1 $dependency1,
+        protected YourApp\Helper\Dependency2 $dependency2,
+        protected array $config
+    ) {
+    }
+}
+```
+
+If your class needs the value of a specific configuration key, you can specify the path using dot notation:
+
+```php
+    /**
+     * @Dot\AnnotatedServices\Annotation\Inject({
+     *     YourApp\Repository\Dependency1::class,
+     *     YourApp\Repository\Dependency2::class,
+     *     "config.example"
+     * })
+     */
+    public function __construct(
+        protected YourApp\Repository\Dependency1 $dependency1,
+        protected YourApp\Helper\Dependency2 $dependency2,
+        protected array $exampleConfig,
+    ) {
+    }
+```
+
+
+## Register class
+
+Open the ConfigProvider of the module where your class resides.
+
+Add a new entry under `factories`, where the key is your class FQCN and the value is `Dot\AnnotatedServices\Factory\AnnotatedServiceFactory::class`.
+
+See below example for a better understanding of the file structure.
+
+```php
+<?php
+
+declare(strict_types=1);
+
+namespace YourApp;
+
+class ConfigProvider
+{
+    public function __invoke(): array
+    {
+        return [
+            'dependencies' => $this->getDependencies(),
+        ];
+    }
+    
+    public function getDependencies(): array
+    {
+        return [
+            'factories' => [
+                YourApp\Service\Example::class => Dot\AnnotatedServices\Factory\AnnotatedServiceFactory::class,
+            ],
+        ];
+    }
+}
+```
diff --git a/docs/book/v4/installation.md b/docs/book/v4/installation.md
new file mode 100644
index 0000000..8d628ea
--- /dev/null
+++ b/docs/book/v4/installation.md
@@ -0,0 +1,5 @@
+# Installation
+
+Install `dotkernel/dot-annotated-services` by executing the following Composer command:
+
+    composer require dotkernel/dot-annotated-services
diff --git a/docs/book/v4/overview.md b/docs/book/v4/overview.md
new file mode 100644
index 0000000..801130d
--- /dev/null
+++ b/docs/book/v4/overview.md
@@ -0,0 +1,5 @@
+# Overview
+
+`dot-annotated-services` is DotKernel's dependency injection service.
+
+By providing reusable factories for service and repository injection, it reduces code complexity in projects.
diff --git a/docs/book/v4/usage.md b/docs/book/v4/usage.md
new file mode 100644
index 0000000..cc75407
--- /dev/null
+++ b/docs/book/v4/usage.md
@@ -0,0 +1,7 @@
+# Usage
+
+Version `4.x` of `dot-annotated-services` is the last version that uses [doctrine/annotations](https://github.com/doctrine/annotations) to parse and inject dependencies.
+
+You can use it to:
+- [Inject class dependencies](factories/service.md)
+- [Inject entity repositories](factories/repository.md)
diff --git a/docs/book/v5/configuration.md b/docs/book/v5/configuration.md
new file mode 100644
index 0000000..c8f6f52
--- /dev/null
+++ b/docs/book/v5/configuration.md
@@ -0,0 +1,6 @@
+# Configuration
+
+After installation, register `dot-annotated-services` in your project by adding the below line to your configuration aggregator (usually: `config/config.php`):
+
+     Dot\AnnotatedServices\ConfigProvider::class,
+
diff --git a/docs/book/v5/factories.md b/docs/book/v5/factories.md
new file mode 100644
index 0000000..3fe9386
--- /dev/null
+++ b/docs/book/v5/factories.md
@@ -0,0 +1,31 @@
+# Factories
+
+`dot-annotated-services` is based on 2 reusable factories - `AttributedRepositoryFactory` and `AttributedServiceFactory` - able to inject any dependency into a class.
+
+## AttributedRepositoryFactory
+
+Injects entity repositories into a class.
+
+
+### Exceptions thrown
+- `Dot\AnnotatedServices\Exception\RuntimeException` if repository does not exist
+- `Dot\AnnotatedServices\Exception\RuntimeException` if repository does not extend `Doctrine\ORM\EntityRepository`
+- `Dot\AnnotatedServices\Exception\RuntimeException` if repository does not have `#[Entity]` attribute
+- `Psr\Container\NotFoundExceptionInterface` if `Doctrine\ORM\EntityManagerInterface` does not exist in the service container
+- `Psr\Container\ContainerExceptionInterface` if service manager is unable to provide an instance of `Doctrine\ORM\EntityManagerInterface`
+
+
+## AttributedServiceFactory
+
+Injects class dependencies into classes.
+
+If a dependency is specified using the dot notation, `AttributedServiceFactory` will try to load a service having that specific alias.
+If it does not find one, it will try to load the dependency as a config tree, checking each segment if it's available in the service container.
+
+
+### Exceptions thrown
+- `Dot\AnnotatedServices\Exception\RuntimeException` if service does not exist
+- `Dot\AnnotatedServices\Exception\RuntimeException` if service does not have `#[Inject]` attribute on it's constructor
+- `Dot\AnnotatedServices\Exception\RuntimeException` if service tries to inject itself recursively
+- `Psr\Container\NotFoundExceptionInterface` if a dependency does not exist in the service container
+- `Psr\Container\ContainerExceptionInterface` if service manager is unable to provide an instance of a dependency
diff --git a/docs/book/v5/factories/repository.md b/docs/book/v5/factories/repository.md
new file mode 100644
index 0000000..74ede58
--- /dev/null
+++ b/docs/book/v5/factories/repository.md
@@ -0,0 +1,57 @@
+# Inject entity repositories
+
+
+## Prepare repository
+
+`dot-annotated-services` determines the entity a repository is related to by looking at the `#[Entity]` attribute, added to the repository class.
+
+```php
+<?php
+
+declare(strict_types=1);
+
+namespace YourApp\Repository;
+
+#[Dot\AnnotatedServices\Attribute\Entity(name: YourApp\Entity\Example::class)]
+class ExampleRepository extends Doctrine\ORM\EntityRepository
+{
+}
+```
+
+Each entity repository must extend `Doctrine\ORM\EntityRepository`.
+
+
+## Register repository
+
+Open the ConfigProvider of the module where your repository resides.
+
+Add a new entry under `factories`, where the key is your repository FQCN and the value is `Dot\AnnotatedServices\Factory\AttributedRepositoryFactory::class`.
+
+See below example for a better understanding of the file structure.
+
+```php
+<?php
+
+declare(strict_types=1);
+
+namespace YourApp;
+
+class ConfigProvider
+{
+    public function __invoke(): array
+    {
+        return [
+            'dependencies' => $this->getDependencies(),
+        ];
+    }
+
+    public function getDependencies(): array
+    {
+        return [
+            'factories' => [
+                YourApp\Repository\ExampleRepository::class => Dot\AnnotatedServices\Factory\AttributedRepositoryFactory::class,
+            ],
+        ];
+    }
+}
+```
diff --git a/docs/book/v5/factories/service.md b/docs/book/v5/factories/service.md
new file mode 100644
index 0000000..a30bbfb
--- /dev/null
+++ b/docs/book/v5/factories/service.md
@@ -0,0 +1,82 @@
+# Inject class dependencies
+
+
+## Prepare class
+
+`dot-annotated-services` determines the dependencies by looking at the `#[Inject]` attribute, added to the constructor of a class.
+Dependencies are specified as separate parameters of the #[Inject] attribute.
+
+```php
+<?php
+
+declare(strict_types=1);
+
+namespace YourApp\Service;
+
+class Example
+{
+    #[Dot\AnnotatedServices\Attribute\Inject(
+        YourApp\Repository\Dependency1::class,
+        YourApp\Helper\Dependency2::class,
+        "config",
+    )]
+    public function __construct(
+        protected YourApp\Repository\Dependency1 $dependency1,
+        protected YourApp\Helper\Dependency2 $dependency2,
+        protected array $config
+    ) {
+    }
+}
+```
+
+If your class needs the value of a specific configuration key, you can specify the path using dot notation:
+
+```php
+    #[Dot\AnnotatedServices\Attribute\Inject(
+        YourApp\Repository\Dependency1::class,
+        YourApp\Helper\Dependency2::class,
+        "config.example",
+    )]
+    public function __construct(
+        protected YourApp\Repository\Dependency1 $dependency1,
+        protected YourApp\Helper\Dependency2 $dependency2,
+        protected array $exampleConfig,
+    ) {
+    }
+```
+
+
+## Register class
+
+Open the ConfigProvider of the module where your class resides.
+
+Add a new entry under `factories`, where the key is your class FQCN and the value is `Dot\AnnotatedServices\Factory\AttributedServiceFactory::class`.
+
+See below example for a better understanding of the file structure.
+
+```php
+<?php
+
+declare(strict_types=1);
+
+namespace YourApp;
+
+class ConfigProvider
+{
+    public function __invoke(): array
+    {
+        return [
+            'dependencies' => $this->getDependencies(),
+        ];
+    }
+    
+    public function getDependencies(): array
+    {
+        return [
+            'factories' => [
+                YourApp\Service\Example::class => Dot\AnnotatedServices\Factory\AttributedServiceFactory::class,
+            ],
+        ];
+    }
+}
+```
diff --git a/docs/book/v5/installation.md b/docs/book/v5/installation.md
new file mode 100644
index 0000000..8d628ea
--- /dev/null
+++ b/docs/book/v5/installation.md
@@ -0,0 +1,5 @@
+# Installation
+
+Install `dotkernel/dot-annotated-services` by executing the following Composer command:
+
+    composer require dotkernel/dot-annotated-services
diff --git a/docs/book/v5/overview.md b/docs/book/v5/overview.md
new file mode 100644
index 0000000..801130d
--- /dev/null
+++ b/docs/book/v5/overview.md
@@ -0,0 +1,5 @@
+# Overview
+
+`dot-annotated-services` is DotKernel's dependency injection service.
+
+By providing reusable factories for service and repository injection, it reduces code complexity in projects.
diff --git a/docs/book/v5/usage.md b/docs/book/v5/usage.md
new file mode 100644
index 0000000..0b85062
--- /dev/null
+++ b/docs/book/v5/usage.md
@@ -0,0 +1,7 @@
+# Usage
+
+Starting from version `5.x`, `dot-annotated-services` uses PHP attributes to inject dependencies.
+
+You can use it to:
+- [Inject class dependencies](factories/service.md)
+- [Inject entity repositories](factories/repository.md)
diff --git a/mkdocs.yml b/mkdocs.yml
new file mode 100644
index 0000000..d85e7be
--- /dev/null
+++ b/mkdocs.yml
@@ -0,0 +1,37 @@
+docs_dir: docs/book
+site_dir: docs/html
+extra:
+  project: Packages
+  current_version: v5
+  versions:
+    - v5
+    - v4
+nav:
+  - Home: index.md
+  - v5:
+      - Overview: v5/overview.md
+      - Installation: v5/installation.md
+      - Usage: v5/usage.md
+      - Factories: v5/factories.md
+      - Reference:
+          - "Inject class dependencies": v5/factories/service.md
+          - "Inject entity repositories": v5/factories/repository.md
+  - v4:
+      - Overview: v4/overview.md
+      - Installation: v4/installation.md
+      - Usage: v4/usage.md
+      - Factories: v4/factories.md
+      - Cache: v4/cache.md
+      - Reference:
+          - "Inject class dependencies": v4/factories/service.md
+          - "Inject entity repositories": v4/factories/repository.md
+site_name: dot-annotated-services
+site_description: "DotKernel's dependency injection service"
+repo_url: "https://github.com/dotkernel/dot-annotated-services"
+plugins:
+  - search
+  - redirects:
+      redirect_maps:
+        overview.md: v5/overview.md
+        install.md: v5/installation.md
+        usage.md: v5/usage.md