From 76cc5d3b986bcdc6222b8bb6b07cb7fc2fc295c2 Mon Sep 17 00:00:00 2001 From: alexmerlin Date: Wed, 23 Oct 2024 08:52:32 +0300 Subject: [PATCH] Issue #52: v4 active mode and bump PHP 8.4 Signed-off-by: alexmerlin --- .github/workflows/codecov.yml | 1 - .github/workflows/continuous-integration.yml | 11 +++ .github/workflows/cs-tests.yml | 47 ------------ .github/workflows/static-analysis.yml | 47 ------------ .github/workflows/unit-test.yml | 48 ------------ .laminas-ci.json | 6 ++ OSSMETADATA | 2 +- README.md | 48 ++++++------ SECURITY.md | 40 ++++++++++ composer.json | 6 +- docs/book/index.md | 2 +- docs/book/v4/cache.md | 15 ++-- docs/book/v4/configuration.md | 5 +- docs/book/v4/factories.md | 25 +++--- docs/book/v4/factories/repository.md | 2 - docs/book/v4/factories/service.md | 2 - docs/book/v4/installation.md | 4 +- docs/book/v4/overview.md | 2 +- docs/book/v4/usage.md | 5 +- docs/book/v5/configuration.md | 5 ++ docs/book/v5/factories.md | 30 ++++++++ docs/book/v5/factories/repository.md | 55 ++++++++++++++ docs/book/v5/factories/service.md | 80 ++++++++++++++++++++ docs/book/v5/installation.md | 5 ++ docs/book/v5/overview.md | 9 +++ docs/book/v5/usage.md | 8 ++ mkdocs.yml | 13 +++- 27 files changed, 321 insertions(+), 202 deletions(-) create mode 100644 .github/workflows/continuous-integration.yml delete mode 100644 .github/workflows/cs-tests.yml delete mode 100644 .github/workflows/static-analysis.yml delete mode 100644 .github/workflows/unit-test.yml create mode 100644 .laminas-ci.json create mode 100644 SECURITY.md mode change 100644 => 120000 docs/book/index.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 diff --git a/.github/workflows/codecov.yml b/.github/workflows/codecov.yml index 190b4da..184fa62 100644 --- a/.github/workflows/codecov.yml +++ b/.github/workflows/codecov.yml @@ -15,7 +15,6 @@ jobs: - ubuntu-latest php: - - "8.1" - "8.2" - "8.3" diff --git a/.github/workflows/continuous-integration.yml b/.github/workflows/continuous-integration.yml new file mode 100644 index 0000000..26c5802 --- /dev/null +++ b/.github/workflows/continuous-integration.yml @@ -0,0 +1,11 @@ +name: "Continuous Integration" + +on: + pull_request: + push: + branches: + tags: + +jobs: + ci: + uses: laminas/workflow-continuous-integration/.github/workflows/continuous-integration.yml@1.x diff --git a/.github/workflows/cs-tests.yml b/.github/workflows/cs-tests.yml deleted file mode 100644 index e8bbade..0000000 --- a/.github/workflows/cs-tests.yml +++ /dev/null @@ -1,47 +0,0 @@ -on: - - push - -name: Run phpcs checks - -jobs: - mutation: - name: PHP ${{ matrix.php }}-${{ matrix.os }} - - runs-on: ${{ matrix.os }} - - strategy: - matrix: - os: - - ubuntu-latest - - php: - - "8.1" - - "8.2" - - "8.3" - - steps: - - name: Checkout - uses: actions/checkout@v3 - - - name: Install PHP - uses: shivammathur/setup-php@v2 - with: - php-version: "${{ matrix.php }}" - tools: composer:v2, cs2pr - coverage: none - - - name: Determine composer cache directory - run: echo "COMPOSER_CACHE_DIR=$(composer config cache-dir)" >> $GITHUB_ENV - - - name: Cache dependencies installed with composer - uses: actions/cache@v3 - with: - path: ${{ env.COMPOSER_CACHE_DIR }} - key: php${{ matrix.php }}-composer-${{ hashFiles('**/composer.json') }} - restore-keys: | - php${{ matrix.php }}-composer- - - name: Install dependencies with composer - run: composer install --prefer-dist --no-interaction --no-progress --optimize-autoloader --ansi - - - name: Run phpcs checks - run: vendor/bin/phpcs diff --git a/.github/workflows/static-analysis.yml b/.github/workflows/static-analysis.yml deleted file mode 100644 index 6f7452d..0000000 --- a/.github/workflows/static-analysis.yml +++ /dev/null @@ -1,47 +0,0 @@ -on: - - push - -name: Run static analysis - -jobs: - mutation: - name: PHP ${{ matrix.php }}-${{ matrix.os }} - - runs-on: ${{ matrix.os }} - - strategy: - matrix: - os: - - ubuntu-latest - - php: - - "8.1" - - "8.2" - - "8.3" - - steps: - - name: Checkout - uses: actions/checkout@v3 - - - name: Install PHP - uses: shivammathur/setup-php@v2 - with: - php-version: "${{ matrix.php }}" - tools: composer:v2, cs2pr - coverage: none - - - name: Determine composer cache directory - run: echo "COMPOSER_CACHE_DIR=$(composer config cache-dir)" >> $GITHUB_ENV - - - name: Cache dependencies installed with composer - uses: actions/cache@v3 - with: - path: ${{ env.COMPOSER_CACHE_DIR }} - key: php${{ matrix.php }}-composer-${{ hashFiles('**/composer.json') }} - restore-keys: | - php${{ matrix.php }}-composer- - - name: Install dependencies with composer - run: composer install --prefer-dist --no-interaction --no-progress --optimize-autoloader --ansi - - - name: Run static analysis - run: vendor/bin/psalm --no-cache --output-format=github --show-info=false --threads=4 diff --git a/.github/workflows/unit-test.yml b/.github/workflows/unit-test.yml deleted file mode 100644 index 7f5f333..0000000 --- a/.github/workflows/unit-test.yml +++ /dev/null @@ -1,48 +0,0 @@ -on: - - push - -name: Run PHPUnit tests - -jobs: - mutation: - name: PHP ${{ matrix.php }}-${{ matrix.os }} - - runs-on: ${{ matrix.os }} - - strategy: - matrix: - os: - - ubuntu-latest - - php: - - "8.1" - - "8.2" - - "8.3" - - steps: - - name: Checkout - uses: actions/checkout@v3 - - - name: Install PHP - uses: shivammathur/setup-php@v2 - with: - php-version: "${{ matrix.php }}" - tools: composer:v2, cs2pr - coverage: none - - - name: Determine composer cache directory - run: echo "COMPOSER_CACHE_DIR=$(composer config cache-dir)" >> $GITHUB_ENV - - - name: Cache dependencies installed with composer - uses: actions/cache@v3 - with: - path: ${{ env.COMPOSER_CACHE_DIR }} - key: php${{ matrix.php }}-composer-${{ hashFiles('**/composer.json') }} - restore-keys: | - php${{ matrix.php }}-composer- - - - name: Install dependencies with composer - run: composer install --prefer-dist --no-interaction --no-progress --optimize-autoloader --ansi - - - name: Run PHPUnit tests - run: vendor/bin/phpunit --colors=always diff --git a/.laminas-ci.json b/.laminas-ci.json new file mode 100644 index 0000000..82cd446 --- /dev/null +++ b/.laminas-ci.json @@ -0,0 +1,6 @@ +{ + "ignore_php_platform_requirements": { + "8.4": true + }, + "backwardCompatibilityCheck": true +} diff --git a/OSSMETADATA b/OSSMETADATA index 6c7e106..b96d4a4 100644 --- a/OSSMETADATA +++ b/OSSMETADATA @@ -1 +1 @@ -osslifecycle=active \ No newline at end of file +osslifecycle=active diff --git a/README.md b/README.md index 0508e5e..295b0b4 100644 --- a/README.md +++ b/README.md @@ -1,29 +1,27 @@ # dot-annotated-services -DotKernel component used to create services through [Laminas Service Manager](https://github.com/laminas/laminas-servicemanager) and inject them with dependencies just using method annotations. It can also create services without the need to write factories. Annotation parsing can be cached, to improve performance. +Dotkernel component used to create services through [Laminas Service Manager](https://github.com/laminas/laminas-servicemanager) and inject them with dependencies just using method annotations. It can also create services without the need to write factories. Annotation parsing can be cached, to improve performance. This package can clean up your code, by getting rid of all the factories you write, sometimes just to inject a dependency or two. -![OSS Lifecycle](https://img.shields.io/osslifecycle/dotkernel/dot-annotated-services) -![PHP from Packagist (specify version)](https://img.shields.io/packagist/php-v/dotkernel/dot-annotated-services/4.1.7) +![OSS Lifecycle](https://img.shields.io/osslifecycle?file_url=https%3A%2F%2Fgithub.com%2Fdotkernel%2Fdot-annotated-services%2Fblob%2F4.0%2FOSSMETADATA) +![PHP from Packagist (specify version)](https://img.shields.io/packagist/php-v/dotkernel/dot-annotated-services/4.2.0) [![GitHub issues](https://img.shields.io/github/issues/dotkernel/dot-annotated-services)](https://github.com/dotkernel/dot-annotated-services/issues) [![GitHub forks](https://img.shields.io/github/forks/dotkernel/dot-annotated-services)](https://github.com/dotkernel/dot-annotated-services/network) [![GitHub stars](https://img.shields.io/github/stars/dotkernel/dot-annotated-services)](https://github.com/dotkernel/dot-annotated-services/stargazers) [![GitHub license](https://img.shields.io/github/license/dotkernel/dot-annotated-services)](https://github.com/dotkernel/dot-annotated-services/blob/4.0/LICENSE.md) -[![Build Static](https://github.com/dotkernel/dot-annotated-services/actions/workflows/static-analysis.yml/badge.svg?branch=4.0)](https://github.com/dotkernel/dot-annotated-services/actions/workflows/static-analysis.yml) +[![Build Static](https://github.com/dotkernel/dot-annotated-services/actions/workflows/continuous-integration.yml/badge.svg?branch=4.0)](https://github.com/dotkernel/dot-annotated-services/actions/workflows/continuous-integration.yml) [![codecov](https://codecov.io/gh/dotkernel/dot-annotated-services/graph/badge.svg?token=ZBZDEA3LY8)](https://codecov.io/gh/dotkernel/dot-annotated-services) -[![SymfonyInsight](https://insight.symfony.com/projects/a0d7016e-fc3f-46b8-9b36-571ff060d744/big.svg)](https://insight.symfony.com/projects/a0d7016e-fc3f-46b8-9b36-571ff060d744) - - ## Installation Run the following command in your project directory - composer require dotkernel/dot-annotated-services - +```shell +composer require dotkernel/dot-annotated-services +``` After installing, add the `ConfigProvider` class to your configuration aggregate. @@ -31,7 +29,8 @@ After installing, add the `ConfigProvider` class to your configuration aggregate ### Using the AnnotatedServiceFactory -You can register services in the service manager using the `AnnotatedServiceFactory` as below +You can register services in the service manager using the `AnnotatedServiceFactory` as below. + ```php return [ 'factories' => [ @@ -40,10 +39,10 @@ return [ ]; ``` -### NOTE -> You can use only the fully qualified class name as the service key +> You can use only the fully qualified class name as the service key. + +The next step is to annotate the service constructor or setters with the service names to inject. -The next step is to annotate the service constructor or setters with the service names to inject ```php use Dot\AnnotatedServices\Annotation\Inject; @@ -65,7 +64,8 @@ public function __construct( The annotation `@Inject` is telling the factory to inject the services between curly braces. 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 +To inject an array value from the service manager, you can use dot notation as below, + ```php use Dot\AnnotatedServices\Annotation\Inject; @@ -76,13 +76,14 @@ use Dot\AnnotatedServices\Annotation\Inject; which will inject `$container->get('config')['debug'];` -### NOTE -> Even if using dot annotation, the annotated factory will check first if a service name exists with that name +> Even if using dot annotation, the annotated factory will check first if a service name exists with that name. You can use the inject annotation on setters too, they will be called at creation time and injected with the configured dependencies. -### Using the AnnotatedRepositoryFactory -You can register doctrine repositories and inject them using the AnnotatedRepositoryFactory as below: +### Using the AnnotatedRepositoryFactory + +You can register doctrine repositories and inject them using the AnnotatedRepositoryFactory as below. + ```php return [ 'factories' => [ @@ -96,6 +97,7 @@ The next step is to add the `@Entity` annotation in the repository class. The `name` field has to be the fully qualified class name. Every repository should extend `Doctrine\ORM\EntityRepository`. + ```php use Doctrine\ORM\EntityRepository; use Dot\AnnotatedServices\Annotation\Entity; @@ -105,16 +107,15 @@ use Dot\AnnotatedServices\Annotation\Entity; */ class ExampleRepository extends EntityRepository { - } ``` - ### Using the abstract factory 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 use Dot\AnnotatedServices\Annotation\Service; @@ -129,13 +130,14 @@ class ServiceClass And that's it, you don't need to configure the service manager with this class, creation will happen automatically. - ## Cache annotations This package is built on top of `doctrine/annotation` and `doctrine/cache`. -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/master/lib/Doctrine/Common/Cache) for available implementations offered by doctrine. +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/master/lib/Doctrine/Common/Cache) for available implementations offered by doctrine. + +Below, we give an example, as defined in our frontend and admin starter applications: -Below, we give an example, as defined in our frontend and admin starter applications ```php return [ 'annotations_cache_dir' => __DIR__ . '/../../data/cache/annotations', diff --git a/SECURITY.md b/SECURITY.md new file mode 100644 index 0000000..4fd00df --- /dev/null +++ b/SECURITY.md @@ -0,0 +1,40 @@ +# Security Policy + +## Supported Versions + + +| Version | Supported | PHP Version | +|---------|--------------------|------------------------------------------------------------------------------------------------------------------------| +| 5.x | :white_check_mark: | ![PHP from Packagist (specify version)](https://img.shields.io/packagist/php-v/dotkernel/dot-annotated-services/5.2.0) | +| 4.x | :white_check_mark: | ![PHP from Packagist (specify version)](https://img.shields.io/packagist/php-v/dotkernel/dot-annotated-services/4.2.0) | +| <= 3.x | :x: | | + + +## Reporting Potential Security Issues + +If you have encountered a potential security vulnerability in this project, +please report it to us at . We will work with you to +verify the vulnerability and patch it. + +When reporting issues, please provide the following information: + +- Component(s) affected +- A description indicating how to reproduce the issue +- A summary of the security vulnerability and impact + +We request that you contact us via the email address above and give the +project contributors a chance to resolve the vulnerability and issue a new +release prior to any public exposure; this helps protect the project's +users, and provides them with a chance to upgrade and/or update in order to +protect their applications. + + +## Policy + +If we verify a reported security vulnerability, our policy is: + +- We will patch the current release branch, as well as the immediate prior minor + release branch. + +- After patching the release branches, we will immediately issue new security + fix releases for each patched release branch. diff --git a/composer.json b/composer.json index 6195b20..1cafef9 100644 --- a/composer.json +++ b/composer.json @@ -20,16 +20,16 @@ "service-manager" ], "require": { - "php": "~8.1.0 || ~8.2.0 || ~8.3.0", + "php": "~8.2.0 || ~8.3.0 || ~8.4.0", "laminas/laminas-servicemanager": "^3.22.1", "doctrine/annotations": "^1.14.3", "doctrine/cache": "^1.12.1 || ^2.1.1", - "doctrine/orm" : "^2.17.3" + "doctrine/orm" : "^2.20" }, "require-dev": { "phpunit/phpunit": "^10.5.9", "vimeo/psalm": "^5.20", - "laminas/laminas-coding-standard": "^2.5" + "laminas/laminas-coding-standard": "^3.0" }, "autoload": { "psr-4": { diff --git a/docs/book/index.md b/docs/book/index.md deleted file mode 100644 index ae42a26..0000000 --- a/docs/book/index.md +++ /dev/null @@ -1 +0,0 @@ -../../README.md diff --git a/docs/book/index.md b/docs/book/index.md new file mode 120000 index 0000000..fe84005 --- /dev/null +++ b/docs/book/index.md @@ -0,0 +1 @@ +../../README.md \ No newline at end of file diff --git a/docs/book/v4/cache.md b/docs/book/v4/cache.md index 9bbf51a..4d6e6f4 100644 --- a/docs/book/v4/cache.md +++ b/docs/book/v4/cache.md @@ -2,7 +2,6 @@ `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. @@ -12,14 +11,16 @@ See below an example on how you can configure `dot-annotated-services` to cache 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, - ], - ]; +'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 $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..c8ad182 --- /dev/null +++ b/docs/book/v5/factories/service.md @@ -0,0 +1,80 @@ +# 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 + $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..06a23f1 --- /dev/null +++ b/docs/book/v5/overview.md @@ -0,0 +1,9 @@ +# 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. + +> `dot-annotated-services` v5 has been abandoned in favor of [dot-dependency-injection](https://github.com/dotkernel/dot-dependency-injection), which uses PHP attributes instead of annotations. +> +> Going forward, if you want to use annotations in your projects, use [dot-annotated-services v4](../v4/overview.md), else use `dot-dependency-injection`. diff --git a/docs/book/v5/usage.md b/docs/book/v5/usage.md new file mode 100644 index 0000000..d2702b4 --- /dev/null +++ b/docs/book/v5/usage.md @@ -0,0 +1,8 @@ +# 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 index 806b681..60afd92 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -4,12 +4,23 @@ extra: project: Packages current_version: v4 versions: + - v5 - v4 nav: - Home: index.md + - v5: + - Overview: v5/overview.md + - Installation: v5/installation.md + - Configuration: v5/configuration.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 + - Configuration: v4/configuration.md - Usage: v4/usage.md - Factories: v4/factories.md - Cache: v4/cache.md @@ -17,7 +28,7 @@ nav: - "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" +site_description: "Dotkernel's dependency injection service, based on Doctrine annotations" repo_url: "https://github.com/dotkernel/dot-annotated-services" plugins: - search