Issue #12: Drop PHP 8.2, fix attribute/dot-notation resolution bugs, expand docs

.github/workflows/codecov.yml

@@ -15,14 +15,13 @@ jobs:
           - ubuntu-latest
 
         php:
-          - "8.2"
           - "8.3"
           - "8.4"
           - "8.5"
 
     steps:
       - name: Checkout
-        uses: actions/checkout@v4
+        uses: actions/checkout@v7
 
       - name: Install PHP
         uses: shivammathur/setup-php@v2
@@ -36,7 +35,7 @@ jobs:
         run: echo "COMPOSER_CACHE_DIR=$(composer config cache-dir)" >> $GITHUB_ENV
 
       - name: Cache dependencies installed with composer
-        uses: actions/cache@v4
+        uses: actions/cache@v6
         with:
           path: ${{ env.COMPOSER_CACHE_DIR }}
           key: php${{ matrix.php }}-composer-${{ hashFiles('**/composer.json') }}

.github/workflows/static-analysis.yml

@@ -15,14 +15,13 @@ jobs:
           - ubuntu-latest
 
         php:
-          - "8.2"
           - "8.3"
           - "8.4"
           - "8.5"
 
     steps:
       - name: Checkout
-        uses: actions/checkout@v4
+        uses: actions/checkout@v7
 
       - name: Install PHP
         uses: shivammathur/setup-php@v2
@@ -36,7 +35,7 @@ jobs:
         run: echo "COMPOSER_CACHE_DIR=$(composer config cache-dir)" >> $GITHUB_ENV
 
       - name: Cache dependencies installed with composer
-        uses: actions/cache@v4
+        uses: actions/cache@v6
         with:
           path: ${{ env.COMPOSER_CACHE_DIR }}
           key: php${{ matrix.php }}-composer-${{ hashFiles('**/composer.json') }}

README.md

@@ -2,16 +2,27 @@
 
 `dot-dependency-injection` is Dotkernel's dependency injection service.
 
-By providing reusable factories for service and repository injection, it reduces code complexity in projects.
+Instead of a hand-written factory class per service, you declare a class's dependencies with the `#[Inject]` attribute on its constructor - or a repository's entity with `#[Entity]` - and register one of the two reusable factories this package ships.
+That removes an entire category of boilerplate files from a project and keeps the dependency list next to the constructor it feeds.
+
+See [Attributes vs. factories](https://docs.dotkernel.org/dot-dependency-injection/v1/attributes-vs-factories/) for the full comparison and the trade-offs.
 
 ## Documentation
 
-Documentation is available at: https://docs.dotkernel.org/dot-dependency-injection/.
+Documentation is available at: <https://docs.dotkernel.org/dot-dependency-injection/>.
+
+- [Installation](https://docs.dotkernel.org/dot-dependency-injection/v1/installation/)
+- [Configuration](https://docs.dotkernel.org/dot-dependency-injection/v1/configuration/)
+- [Attributes vs. factories](https://docs.dotkernel.org/dot-dependency-injection/v1/attributes-vs-factories/)
+- [Factories](https://docs.dotkernel.org/dot-dependency-injection/v1/factories/)
+- [Inject class dependencies](https://docs.dotkernel.org/dot-dependency-injection/v1/factories/service/)
+- [Inject entity repositories](https://docs.dotkernel.org/dot-dependency-injection/v1/factories/repository/)
+- [FAQ](https://docs.dotkernel.org/dot-dependency-injection/v1/faq/)
 
 ## Badges
 
 ![OSS Lifecycle](https://img.shields.io/osslifecycle/dotkernel/dot-dependency-injection)
-![PHP from Packagist (specify version)](https://img.shields.io/packagist/php-v/dotkernel/dot-dependency-injection/1.3.0)
+![PHP from Packagist (specify version)](https://img.shields.io/packagist/php-v/dotkernel/dot-dependency-injection/1.4.0)
 
 [![GitHub issues](https://img.shields.io/github/issues/dotkernel/dot-dependency-injection)](https://github.com/dotkernel/dot-dependency-injection/issues)
 [![GitHub forks](https://img.shields.io/github/forks/dotkernel/dot-dependency-injection)](https://github.com/dotkernel/dot-dependency-injection/network)
@@ -23,6 +34,12 @@ Documentation is available at: https://docs.dotkernel.org/dot-dependency-injecti
 [![docs-build](https://github.com/dotkernel/dot-dependency-injection/actions/workflows/docs-build.yml/badge.svg)](https://github.com/dotkernel/dot-dependency-injection/actions/workflows/docs-build.yml)
 [![PHPStan](https://github.com/dotkernel/dot-dependency-injection/actions/workflows/static-analysis.yml/badge.svg?branch=1.0)](https://github.com/dotkernel/dot-dependency-injection/actions/workflows/static-analysis.yml)
 
+## Requirements
+
+- PHP 8.3, 8.4 or 8.5
+- a PSR-11 container, usually `laminas/laminas-servicemanager`
+- `doctrine/orm` ^2.9 || ^3.0, if you use `AttributedRepositoryFactory`
+
 ## Installation
 
 Install `dot-dependency-injection` by running the following command in your project directory:
@@ -44,6 +61,8 @@ Dot\DependencyInjection\ConfigProvider::class,
 You can register services in the service manager using `AttributedServiceFactory` as seen in the below example:
 
 ```php
+use Dot\DependencyInjection\Factory\AttributedServiceFactory;
+
 return [
     'factories' => [
         ServiceClass::class => AttributedServiceFactory::class,
@@ -56,39 +75,49 @@ return [
 The next step is to add the `#[Inject]` attribute to the service constructor with the service FQCNs to inject:
 
 ```php
-#[\Dot\DependencyInjection\Attribute\Inject(
-    App\Srevice\Dependency1::class,
-    App\Srevice\Dependency2::class,
-    "config",
+use App\Service\Dependency1;
+use App\Service\Dependency2;
+use Dot\DependencyInjection\Attribute\Inject;
+
+#[Inject(
+    Dependency1::class,
+    Dependency2::class,
+    'config',
 )]
 public function __construct(
-    protected App\Srevice\Dependency1 $dep1,
-    protected App\Srevice\Dependency2 $dep2,
-    protected array $config
+    protected Dependency1 $dep1,
+    protected Dependency2 $dep2,
+    protected array $config,
 ) {
 }
 ```
 
-The `#[Inject]` attribute is telling `AttributedServiceFactory` to inject the services specified as parameters.
+The `#[Inject]` attribute is telling `AttributedServiceFactory` to inject the services specified as parameters, in the same order as the constructor parameters.
 Valid service names should be provided, as registered in the service manager.
+A name that is not registered in the container, but is an existing class, is instantiated directly.
+
+A class without a constructor does not need the attribute.
 
 To inject an array value from the service manager, you can use dot notation as below
 
 ```php
-#[\Dot\DependencyInjection\Attribute\Inject(
-    "config.debug",
+#[Inject(
+    'config.debug',
 )]
 ```
 
 which will inject `$container->get('config')['debug'];`.
 
 > Even if using dot notation, `AttributedServiceFactory` will check first if a service name exists with that name.
+> Only the segment before the first dot is resolved from the container; the rest are array keys, and arrays as well as `ArrayAccess` objects can be traversed.
 
 ### Using the AttributedRepositoryFactory
 
 You can register doctrine repositories and inject them using the `AttributedRepositoryFactory` as below:
 
 ```php
+use Dot\DependencyInjection\Factory\AttributedRepositoryFactory;
+
 return [
     'factories' => [
         ExampleRepository::class => AttributedRepositoryFactory::class,
@@ -103,7 +132,7 @@ The `name` field has to be the fully qualified class name.
 Every repository should extend `Doctrine\ORM\EntityRepository`.
 
 ```php
-use Api\App\Entity\Example;
+use App\Entity\Example;
 use Doctrine\ORM\EntityRepository;
 use Dot\DependencyInjection\Attribute\Entity;
 
@@ -113,6 +142,24 @@ class ExampleRepository extends EntityRepository
 }
 ```
 
-> Dependencies injected via the`#[Entity]`/`#[Inject]` attributes are not cached
+Because Doctrine builds the repository from the entity's mapping, the entity must point back to the repository:
+
+```php
+#[ORM\Entity(repositoryClass: ExampleRepository::class)]
+class Example
+{
+}
+```
+
+> Dependencies injected via the `#[Entity]`/`#[Inject]` attributes are not cached.
+> Injecting dependencies into property setters is not supported.
+
+## Quality assurance
+
+Run the full suite - coding standard, tests and static analysis:
+
+```shell
+composer check
+```
 
-> Injecting dependencies into property setters is not supported
+Individual targets: `composer cs-check`, `composer cs-fix`, `composer test`, `composer static-analysis`.

SECURITY.md

@@ -2,35 +2,26 @@
 
 ## Supported Versions
 
-| Version | Supported          | PHP Version                                                                                                              |
-|---------|--------------------|--------------------------------------------------------------------------------------------------------------------------|
-| 1.x     | :white_check_mark: | ![PHP from Packagist (specify version)](https://img.shields.io/packagist/php-v/dotkernel/dot-dependency-injection/1.3.0) |
+| Version | Supported | PHP Version |
+| --- | --- | --- |
+| 1.x | :white_check_mark: | ![PHP from Packagist (specify version)](https://img.shields.io/packagist/php-v/dotkernel/dot-dependency-injection/1.4.0) |
 
 ## Reporting Potential Security Issues
 
-If you have encountered a potential security vulnerability in this project,
-please report it to us at <security@dotkernel.com>. We will work with you to
-verify the vulnerability and patch it.
+If you have encountered a potential security vulnerability in this project, please report it to us at <security@dotkernel.com>.
+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.
+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.
-
+- 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.

composer.json

@@ -24,7 +24,7 @@
         "service"
     ],
     "require": {
-        "php": "~8.2.0 || ~8.3.0 || ~8.4.0 || ~8.5.0",
+        "php": "~8.3.0 || ~8.4.0 || ~8.5.0",
         "doctrine/orm": "^2.9 || ^3.0",
         "psr/container": "^1.0 || ^2.0"
     },