Task/improve container factory namespace

CHANGELOG.md

@@ -2,9 +2,10 @@
 
 All notable changes to this project will be documented in this file.
 
-The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## [v3.0.0](https://github.com/cspray/annotated-container/tree/v3.0.0) - 2024-12-15
+## [v3.0.0](https://github.com/cspray/annotated-container/tree/v3.0.0)
 
 The v3.0 release represents a substantial improvement in several areas of the project, but also includes several backwards compatability breaks; particularly if you were using container caching, providing Definitions via a DefinitionProvider, or utilizing the Bootstrap observer system.
 
@@ -27,14 +28,14 @@ The v3.0 release represents a substantial improvement in several areas of the pr
 - Updated the version of `nikic/php-parser` used to 5.3.
 - All interactions with the `Bootstrap` object are available through named, static methods. The `Bootstrap` constructor is now private and the `new` construct cannot be used. Generally speaking, you should make use of the new `Bootstrap::fromAnnotatedContainerConventions` method.
 - Container factory to use is no longer implicit and must be explicitly provided during your bootstrapping.
-- `AnnotatedContainer::getBackingContainer` was renamed to `backingContainer`.
 - All Definitions that had a nullable `attribute` method were changed to require a non-null Attribute value. Please see the ADR "Require Definitions To Provide Attribute" for more information.
 - Improved the `XmlContainerDefinitionSerializer` and corresponding XSD to remove redundant information being stored in the Attribute.
 - The `AnnotatedContainerVersion` class was updated to use the `composer/runtime` dependency directly, instead of using `ocramius/package-versions`.
 - Added template parameters to the `AutowireableFactory::make` method, allowing more type information to be conveyed.
 - Several implementations had their `get` prefix removed, as it was redundant and not necessary.
 - Moved test code that was in `fixture_src` under `test/Fixture`.
 - When utilizing the `composer.json` configuration for configuring third-party initializers, more checks are made to ensure that a valid data structure has been passed. Previously, this had undefined behavior when invalid data types or values were present.
+- Refactored the `ContainerFactoryOptions` interface into a value object.
 
 ### Fixed
 
@@ -58,6 +59,8 @@ The v3.0 release represents a substantial improvement in several areas of the pr
   - `Cspray\AnnotatedContainer\Definition\ConfigurationDefinitionBuilder`
   - `Cspray\AnnotatedContainer\Attribute\ConfigurationAttribute`
   - `Cspray\AnnotatedContainer\Attribute\Configuration`
+- Removed the `Cspray\AnnotatedContainer\ContainerFactory\ContainerFactoryOptionsBuilder` object. Please use the `ContainerFactoryOptions` value object directly instead.
+- Removed the `Cspray\AnnotatedContainer\StaticAnalysis\ContainerDefinitionAnalysisOptionsBuilder`. Please use the `ContainerFactoryOptions` value object directly instead.
 - Removed built-in file caching used in bootstrapping. This functionality is replaced by implementing your own `ContainerDefinitionCache` implementation, or explicitly using the `FileBackedContainerDefinitionCache` provided out-of-the-box.
 - Removed built-in logging used throughout the library. This functionality will be replaced at a future date with a set of listeners that will log the same information. These listeners will require installing a separate repo and explicitly opting in.
 - Removed the following Composer dependencies:
@@ -71,7 +74,7 @@ The v3.0 release represents a substantial improvement in several areas of the pr
 ### Added
 
 - Added the ability to inject a collection of services as an array or a custom collection by passing an implementation of `Cspray\AnnotatedContainer\ContainerFactory\ListOf` to an `#[Inject]` attribute.
-- Added `Cspray\AnnotatedContainer\ContainerFactory\ListOfAsArray` implementation of to allow implementing a collection of services as an array out-of-the-box 
+- Added `Cspray\AnnotatedContainer\ContainerFactory\ListOfAsArray` implementation of to allow implementing a collection of services as an array out-of-the-box
 
 ### Deprecated
 
@@ -117,14 +120,14 @@ In v3 caching functionality is drastically improved and much more control is pro
 ### Changed
 
 - Changed static analysis step to no longer throw an error if a ServiceDelegate is encountered without an explicitly
-defined Service. Now, a ServiceDefinition will be implicitly added as if the corresponding class was added with all 
-default parameters using the functional API.
+  defined Service. Now, a ServiceDefinition will be implicitly added as if the corresponding class was added with all
+  default parameters using the functional API.
 
 ### Deprecated
 
 - All observers have been deprecated. They will be replaced in 3.0.0. Please see our ADR document for more details.
-- All implementations in Cspray\AnnotatedContainer\Profiles have been deprecated. They will be replaced with a single 
-value object in 3.0.0. Please see our ADR document for more details.
+- All implementations in Cspray\AnnotatedContainer\Profiles have been deprecated. They will be replaced with a single
+  value object in 3.0.0. Please see our ADR document for more details.
 
 ## [v2.2.0](https://github.com/cspray/annotated-container/tree/v2.2.0) - 2023-05-29
 
@@ -330,7 +333,7 @@ This release only deprecates code constructs replaced in v2.
 
 ## [v1.3.0](https://github.com/cspray/annotated-container/tree/v1.3.0) - 2022-08-06
 
-### Added 
+### Added
 
 - Added an event system for programmatic access to the ContainerDefinition and Container before and after each is created.
 
@@ -415,7 +418,7 @@ This release only deprecates code constructs replaced in v2.
 ### Removed
 
 - Removed the ability to mark a `#[Service]` as shared or not. All services are shared by default, and you cannot "unshare" a service. This functionality has a lot of odd behavior around it and other mechanisms should be used to gain this functionality.
-- Removed the `AnnotatedTarget`, `AnnotatatedTargetParser`, and `StaticAnalysisAnnotatedTargetParser`. 
+- Removed the `AnnotatedTarget`, `AnnotatatedTargetParser`, and `StaticAnalysisAnnotatedTargetParser`.
 
 ### Changed
 
@@ -432,7 +435,7 @@ This release only deprecates code constructs replaced in v2.
 
 - A new `fixture_src/` directory that stores example source code used for the automated test suite.
 - Several improvements to the way that Fixtures are handled in the test suite such that the code examples in `fixture_src/` have a first-class representation in the test suite through the `Cspray\AnnotatedContainerFixture\Fixtures` class.
-- Implementations for 
+- Implementations for
 
 ### Changed
 
@@ -490,7 +493,7 @@ This release only deprecates code constructs replaced in v2.
 - An error in the README documentation referencing an incorrect variable.
 - Directory paths in all tests point to new directory structure.
 - A dev-only dependency, `mikey179/vfsStream` was inadvertently included in the `require` section. This dependency is now properly a `require-dev` dependency.
-- Arguments passed to Attributes better differentiates between compile and runtime values by introducing an AnnotationValue. Many 
+- Arguments passed to Attributes better differentiates between compile and runtime values by introducing an AnnotationValue. Many
 
 ### Removed
 
@@ -532,7 +535,7 @@ This release only deprecates code constructs replaced in v2.
   on a `Service` constructor or `ServicePrepare` method.
 - `InjectorDefinitionCompiler` to turn annotated PHP source code in a directory into an `InjectorDefinition` which defines how to construct
   the corresponding `Injector`. An implementation using PHP-Parser is also provided.
-- `InjectorFactory` to take an `InjectorDefinition` and turn it into a DI container. An implementation that 
+- `InjectorFactory` to take an `InjectorDefinition` and turn it into a DI container. An implementation that
   wires an Auryn `Injector` is also provided.
 
 

README.md

@@ -2,7 +2,8 @@
 
 [![Unit Tests](https://github.com/cspray/annotated-container/actions/workflows/php.yml/badge.svg)](https://github.com/cspray/annotated-container/actions/workflows/php.yml)
 
-A Dependency Injection framework for creating an autowired, feature-rich, [PSR-11](https://www.php-fig.org/psr/psr-11/) compatible Container using PHP 8 Attributes!
+A Dependency Injection framework for creating an autowired, feature-rich, [PSR-11](https://www.php-fig.org/psr/psr-11/) compatible Container using
+PHP 8 Attributes!
 
 - Designate an interface as a Service and easily configure which concrete implementations to use
 - Delegate service construction to a factory
@@ -15,7 +16,9 @@ A Dependency Injection framework for creating an autowired, feature-rich, [PSR-1
 
 ## Quick Start
 
-This quick start is intended to get you familiar with Annotated Container's core functionality and get a working Container created. First, a simple example showing how an interface can be aliased to a concrete Service. After that we'll show you how to get a Container to create the Service.
+This quick start is intended to get you familiar with Annotated Container's core functionality and get a working 
+Container created. First, a simple example showing how an interface can be aliased to a concrete Service. After that 
+we'll show you how to get a Container to create the Service.
 
 ### Code Example
 
@@ -54,19 +57,28 @@ This example is built upon in the docs. Check out the tutorials for more example
 
 ### Bootstrapping Your Container
 
-Annotated Container ships with a built-in CLI tool to easily create a configuration detailing how to build your Container and a corresponding `Cspray\AnnotatedContainer\Bootstrap\Bootstrap` implementation to create your Container using that configuration. It is highly recommended to use the provided tooling to create your Container.
+Annotated Container ships with a built-in CLI tool to easily create a configuration detailing how to build your 
+Container and a corresponding `Cspray\AnnotatedContainer\Bootstrap\Bootstrap` implementation to create your Container 
+using that configuration. It is highly recommended to use the provided tooling to create your Container.
 
-> The CLI tool offers extensive documentation detailing how to run commands and what options are available. If you're ever looking for more info run: `./vendor/bin/annotated-container help`
+> The CLI tool offers extensive documentation detailing how to run commands and what options are available. If you're 
+> ever looking for more info run: `./vendor/bin/annotated-container help`
 
-The first step is to create the configuration. By default, the tooling will look at your `composer.json` to determine what directories to scan and create a directory that the ContainerDefinition can be cached in. Run the following command to complete this step. 
+The first step is to create the configuration. By default, the tooling will look at your `composer.json` to determine 
+what directories to scan and create a directory that the ContainerDefinition can be cached in. Run the following 
+command to complete this step. 
 
 ```
 ./vendor/bin/annotated-container init
 ```
 
-The configuration file will be created in the root of your project named "annotated-container.xml". The cache directory will also be created in the root of your project named ".annotated-container-cache". Check out the command's help documentation for available options, including how to customize these values.
+The configuration file will be created in the root of your project named "annotated-container.xml". The cache directory 
+will also be created in the root of your project named ".annotated-container-cache". Check out the command's help 
+documentation for available options, including how to customize these values.
 
-Be sure to review the generated configuration! A "normal" Composer setup might result in a configuration that looks like the following. If there are any directories that should be scanned but aren't listed in `<source></source>` be sure to include them. Conversely, if there are directories included that _shouldn't_ be scanned be sure to remove them.
+Be sure to review the generated configuration! A "normal" Composer setup might result in a configuration that looks 
+like the following. If there are any directories that should be scanned but aren't listed in `<source></source>` be
+sure to include them. Conversely, if there are directories included that _shouldn't_ be scanned be sure to remove them.
 
 ```xml
 <?xml version="1.0" encoding="UTF-8" ?>
@@ -89,10 +101,7 @@ have `php-di/php-di` installed.
 // app bootstrap in __DIR__ . '/app.php'
 require __DIR__ . '/vendor/autoload.php';
 
-use Cspray\AnnotatedContainer\Bootstrap\Bootstrap;
-use Cspray\AnnotatedContainer\Event\Emitter;
-use Cspray\AnnotatedContainer\Profiles;
-use Cspray\AnnotatedContainer\ContainerFactory\PhpDiContainerFactory;
+use Cspray\AnnotatedContainer\Bootstrap\Bootstrap;use Cspray\AnnotatedContainer\ContainerFactory\PhpDi\PhpDiContainerFactory;use Cspray\AnnotatedContainer\Event\Emitter;use Cspray\AnnotatedContainer\Profiles;
 
 $emitter = new Emitter();
 
@@ -122,7 +131,9 @@ composer require cspray/annotated-container
 
 ### Choose a Backing Container
 
-AnnotatedContainer does not provide any of the actual Container functionality. We provide Attributes and definition objects that can determine how actual implementations are intended to be setup. AnnotatedContainer currently supports the following backing Containers:
+AnnotatedContainer does not provide any of the actual Container functionality. We provide Attributes and definition 
+objects that can determine how actual implementations are intended to be setup. AnnotatedContainer currently supports
+the following backing Containers:
 
 #### [rdlowrey/auryn](https://github.com/rdlowrey/auryn)
 
@@ -144,13 +155,20 @@ composer require illuminate/container
 
 ## Documentation
 
-This library is thoroughly documented in-repo under the `/docs` directory. The documentation is split into three parts; Tutorials, How Tos, and References.
+This library is thoroughly documented in-repo under the `/docs` directory. The documentation is split into three parts; 
+Tutorials, How Tos, and References.
 
-**Tutorials** are where you'll want to start. It'll expand on the examples in the "Quick Start" and teach you how to do most of the things you'll want to do with the library. This documentation tends to split the difference between the amount of code and the amount of explanation.
+**Tutorials** are where you'll want to start. It'll expand on the examples in the "Quick Start" and teach you how to do
+most of the things you'll want to do with the library. This documentation tends to split the difference between the 
+amount of code and the amount of explanation.
 
-**How Tos** are where you'll go to get step-by-step guides on how to achieve specific functionality. These documents tend to be more code and less explanation. We assume you've gotten an understanding of the library and have questions on how to do something beyond the "normal" use cases. 
+**How Tos** are where you'll go to get step-by-step guides on how to achieve specific functionality. These documents 
+tend to be more code and less explanation. We assume you've gotten an understanding of the library and have questions 
+on how to do something beyond the "normal" use cases. 
 
-**References** are where you can get into the real internal, technical workings of the library. List of APIs and more technically-explicit documentation can be found here. References may be a lot of code, a lot of explanation, or a split between the two depending on the context.
+**References** are where you can get into the real internal, technical workings of the library. List of APIs and more 
+technically-explicit documentation can be found here. References may be a lot of code, a lot of explanation, or a split 
+between the two depending on the context.
 
 ## Roadmap
 

docs/README.md

@@ -1,23 +1,28 @@
-# AnnotatedContainer Docs Table of Contents
+# AnnotatedContainer Docs 
 
-## Tutorials
+
+
+## Table of Contents
+
+### Tutorials
 
 1. [Getting Started](./tutorials/01-getting-started.md)
 2. [Alias Resolution with Profiles](./tutorials/02-alias-resolution-with-profiles.md)
 3. [Alias Resolution with Attributes](./tutorials/03-alias-resolution-with-attributes.md)
 4. [Using Service Factories](./tutorials/04-using-service-factories.md)
 5. [Calling Post Construct Methods](./tutorials/05-calling-post-construct-methods.md)
 6. [Injecting Scalar Values](./tutorials/06-injecting-scalar-values.md)
-7. [Autowire Aware Factory](./tutorials/08-autowire-aware-factory.md)
-8. [Autowire aware Invoker](./tutorials/09-autowire-aware-invoker.md)
-9. [Annotated Container Observer](./tutorials/10-annotated-container-observers.md)
+7. [Autowire Aware Factory](tutorials/07-autowire-aware-factory.md)
+8. [Autowire aware Invoker](tutorials/08-autowire-aware-invoker.md)
+9. [Annotated Container Observer](./tutorials/09-annotated-container-events)
 
-## How To
+### How To
 
 1. [Add Third-Party Services](./how-to/01-add-third-party-services.md)
 2. [Bootstrap Your Container](./how-to/02-bootstrap-your-container.md)
 
-## References
+### References
 
 1. [Attributes List](./references/01-attributes-list.md)
-2. [Functional API](./references/02-functional-api.md)
+2. [Functional API](./references/02-functional-api.md)
+3. [Event Listeners](./references/03-event-listeners.md)