Merge pull request #39 from dotkernel/issue-37-v4

Issue #37: Added documentation for v4

Author: arhimede

docs/book/index.md

@@ -0,0 +1 @@
+../../README.md

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']);
+    }
+}
+```

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,
+

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.

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,
+            ],
+        ];
+    }
+}
+```

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,
+            ],
+        ];
+    }
+}
+```

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

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.

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)

mkdocs.yml

@@ -0,0 +1,28 @@
+docs_dir: docs/book
+site_dir: docs/html
+extra:
+  project: Packages
+  current_version: v4
+  versions:
+    - v4
+nav:
+  - Home: index.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: v4/overview.md
+        install.md: v4/installation.md
+        usage.md: v4/usage.md