diff --git a/CHANGELOG.md b/CHANGELOG.md index 4f328ecb..e78d5903 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,8 +2,69 @@ 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 + +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. + +### Added + +- Version attribute to the `annotated-container.xml` XML configuration. In future iterations work may be done to ensure versions for your configuration are compatible with the version of the library installed. +- A more complete event system with informative events being emitted throughout the entire Annotated Container lifecycle. Previously, this functionality was much more limited and provided by Bootstrap observers. +- A Definition factory that allows creating all definitions, except for a `ContainerDefinition`, in a more complete, concise manner. Previously, this functionality was provided by Definition Builders using a Fluent API. +- More feature-complete caching system for a `ContainerDefinition`. Previously, this was powered by direct calls to PHP's filesystem functions. Now a purpose-built interface, `Cspray\AnnotatedContainer\Definition\Cache\ContainerDefinitionCache`, allows whatever caching strategy is most appropriate. +- A `Cspray\AnnotatedContainer\Filesystem\Filesystem` interface and implementation that allows for executing common tasks on a file. Previously, the native PHP functions for accessing a filesystem were being used. This change was primarily implemented to improve testability without requiring for a heavyweight abstraction from a third-party library. +- `Cspray\AnnotatedContainer\Profiles` value object that indicates what profiles are active when a container is created. +- Normalized the conventions around setting up the Annotated Container CLI tool. You can now use `Cspray\AnnotatedContainer\Cli\AnnotatedContainerCliRunner` in your own scripts, allowing you to easily customize caching, among other things. +- A bootstrapping utility class, `Cspray\AnnotatedContainer\Bootstrap\ContainerDefinitionAnalysisOptionsFromBootstrappingConfiguration` that allows consistently creating the `ContainerDefinitionAnalysisOptions` to be used. +- A discrete interface, `Cspray\AnnotatedContainer\Bootstrap\PackagesComposerJsonPathProvider`, to determine what path should be used when scanning a `composer.json` for third-party dependencies. This is utilized by the CLI tool to generate the appropriate configuration file. +- A discrete `DefaultDefinitionProviderFactory` implementation, previously this functionality was inlined into the bootstrap. + +### Changed + +- **Updated the required PHP version to 8.2!** +- 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. + +### Fixed + +- Several places where `declare(strict_types=1)` was not properly set. +- Fixed an error where the interface `AutowireableParameterSet` was implementing a template instead of extending it. + +### Removed + +- All code associated with Bootstrap observers, including but not limited to: + - `Cspray\AnnotatedContainer\Bootstrap\ObserverFactory` + - `Cspray\AnnotatedContainer\Bootstrap\ContainerAnalyticsObserver` + - `Cspray\AnnotatedContainer\Bootstrap\ContainerCreatedObserver` + - `Cspray\AnnotatedContainer\Bootstrap\PostAnalysisObserver` + - `Cspray\AnnotatedContainer\Bootstrap\PreAnalysisObserver` + - `Cspray\AnnotatedContainer\Bootstrap\ServiceWiringObserver` (See `ServiceWiringListener`) + - `Cspray\AnnotatedContainer\Bootstrap\ThirdPartyInitializer::getObserverClasses` +- All Definition builder objects, except for the `ContainerDefinitionBuilder`. See the new `DefinitionFactory` for equivalent functionality. +- The `ActiveProfiles` value object. See the new `Profiles` value object for a replacement. +- All code associated with Configuration, including but not limited to: + - `Cspray\AnnotatedContainer\Definition\ConfigurationDefinition` + - `Cspray\AnnotatedContainer\Definition\ConfigurationDefinitionBuilder` + - `Cspray\AnnotatedContainer\Attribute\ConfigurationAttribute` + - `Cspray\AnnotatedContainer\Attribute\Configuration` +- 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: + - brick/varexporter + - cspray/typiphy + - ocramius/package-versions + - psr/log ## [v2.4.0](https://github.com/cspray/annotated-container/tree/v2.4.0) - 2024-06-08 diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 412775af..b40c3b9e 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -8,10 +8,7 @@ For changes to the codebase you should generally create an Issue first. The API Exceptions to this guideline are if the changes fix a bug, is strictly documentation, or is a security problem. For security related problems, please review the [SECURITY.md](./SECURITY.md) file. -## Tests, Oh Glorious Tests! +## Implement Tests This codebase is well tested. While we don't necessarily strictly enforce 100% code coverage that is the goal we're striving towards. If you fix a bug, implement a new feature, or otherwise add logical lines of code you should also add the appropriate testing. -## Review Project Roadmap - -Beyond reviewing the documentation found in-repo I also recommend that you check out the [Annotated Container Project and Roadmap](https://github.com/users/cspray/projects/1). The future of Annotated Container has been fairly well planned out. If you'd like to contribute but aren't sure where to get started reviewing and picking up one of the issues in the Roadmap would be fantastic! diff --git a/README.md b/README.md index 55a30764..4685b6dc 100644 --- a/README.md +++ b/README.md @@ -98,13 +98,20 @@ $emitter = new Emitter(); // Add whatever Listeners are required for your application +// Create your Bootstrap, using your desired ContainerFactory implementation +// The php-di/php-di library is the preferred implementation, demonstrated here +$boostrap = Bootstrap::fromAnnotatedContainerConventions( + new PhpDiContainerFactory($emitter), + $emitter, +); + // Include other active profiles in this list // If the only active profile is default you can call this method without any arguments -$container = Bootstrap::fromAnnotatedContainerConventions( - new PhpDiContainerFactory($emitter), $emitter -)->bootstrapContainer(Profiles::fromList(['default'])); +$container = $bootstrap->bootstrapContainer( + Profiles::fromList(['default']) +); -$storage = $container->get(BlobStorage::class); // instanceof FilesystemStorage +$storage = $container->get(BlobStorage::class); // instanceof FilesystemStorage ``` ## Installation diff --git a/composer.json b/composer.json index a1972d6c..73097fde 100644 --- a/composer.json +++ b/composer.json @@ -26,7 +26,6 @@ }, "require-dev": { "illuminate/container": "^10.11", - "jetbrains/phpstorm-attributes": "^1.1", "php-di/php-di": "^7.0", "psr/log": "^3.0", "rdlowrey/auryn": "^1.4", diff --git a/src/Autowire/AutowireableInvoker.php b/src/Autowire/AutowireableInvoker.php index e73b1aa3..45ab63b3 100644 --- a/src/Autowire/AutowireableInvoker.php +++ b/src/Autowire/AutowireableInvoker.php @@ -8,8 +8,6 @@ interface AutowireableInvoker { /** - * - * * @param callable $callable * @param AutowireableParameterSet|null $parameters * @return mixed diff --git a/src/Bootstrap/Bootstrap.php b/src/Bootstrap/Bootstrap.php index 3d2666e8..beffab3b 100644 --- a/src/Bootstrap/Bootstrap.php +++ b/src/Bootstrap/Bootstrap.php @@ -5,7 +5,6 @@ use Cspray\AnnotatedContainer\AnnotatedContainer; use Cspray\AnnotatedContainer\ContainerFactory\ContainerFactory; use Cspray\AnnotatedContainer\ContainerFactory\ContainerFactoryOptionsBuilder; -use Cspray\AnnotatedContainer\ContainerFactory\PhpDiContainerFactory; use Cspray\AnnotatedContainer\Definition\ContainerDefinition; use Cspray\AnnotatedContainer\Event\Emitter; use Cspray\AnnotatedContainer\Filesystem\Filesystem; diff --git a/src/Bootstrap/BootstrappingConfiguration.php b/src/Bootstrap/BootstrappingConfiguration.php index 6db629cf..d2bc6830 100644 --- a/src/Bootstrap/BootstrappingConfiguration.php +++ b/src/Bootstrap/BootstrappingConfiguration.php @@ -1,4 +1,4 @@ - */ private array $parameterStores = []; public function __construct( - ContainerFactoryEmitter $emitter, + private readonly ContainerFactoryEmitter $emitter, private readonly AliasDefinitionResolver $aliasDefinitionResolver = new StandardAliasDefinitionResolver(), ) { // Injecting environment variables is something we have supported since early versions. // We don't require adding this parameter store explicitly to continue providing this functionality // without the end-user having to change how they construct their ContainerFactory. $this->addParameterStore(new EnvironmentParameterStore()); - $this->emitter = $emitter; } final public function createContainer(ContainerDefinition $containerDefinition, ContainerFactoryOptions $containerFactoryOptions = null) : AnnotatedContainer { $activeProfiles = $containerFactoryOptions?->profiles() ?? Profiles::defaultOnly(); - $this->emitter?->emitBeforeContainerCreation($activeProfiles, $containerDefinition); + $this->emitter->emitBeforeContainerCreation($activeProfiles, $containerDefinition); $state = new ContainerFactoryState( new ProfilesAwareContainerDefinition($containerDefinition, $activeProfiles), @@ -54,7 +51,7 @@ final public function createContainer(ContainerDefinition $containerDefinition, ); $container = $this->createAnnotatedContainer($state); - $this->emitter?->emitAfterContainerCreation($activeProfiles, $containerDefinition, $container); + $this->emitter->emitAfterContainerCreation($activeProfiles, $containerDefinition, $container); return $container; } diff --git a/src/Definition/Cache/FileBackedContainerDefinitionCache.php b/src/Definition/Cache/FileBackedContainerDefinitionCache.php index 68dc21aa..5b5dbc45 100644 --- a/src/Definition/Cache/FileBackedContainerDefinitionCache.php +++ b/src/Definition/Cache/FileBackedContainerDefinitionCache.php @@ -5,7 +5,6 @@ use Cspray\AnnotatedContainer\Definition\ContainerDefinition; use Cspray\AnnotatedContainer\Definition\Serializer\ContainerDefinitionSerializer; use Cspray\AnnotatedContainer\Definition\Serializer\SerializedContainerDefinition; -use Cspray\AnnotatedContainer\Definition\Serializer\XmlContainerDefinitionSerializer; use Cspray\AnnotatedContainer\Exception\CacheDirectoryNotFound; use Cspray\AnnotatedContainer\Exception\CacheDirectoryNotWritable; use Cspray\AnnotatedContainer\Exception\MismatchedContainerDefinitionSerializerVersions; diff --git a/src/Definition/InjectDefinition.php b/src/Definition/InjectDefinition.php index db3a33d5..46db8ff4 100644 --- a/src/Definition/InjectDefinition.php +++ b/src/Definition/InjectDefinition.php @@ -1,11 +1,9 @@ -