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 +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 + $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 + $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/mkdocs.yml b/mkdocs.yml new file mode 100644 index 0000000..83f6345 --- /dev/null +++ b/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