Task/v3 release docs

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
 

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!

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

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",

src/Autowire/AutowireableInvoker.php

@@ -8,8 +8,6 @@
 interface AutowireableInvoker {
 
     /**
-     *
-     *
      * @param callable $callable
      * @param AutowireableParameterSet|null $parameters
      * @return mixed

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;

src/Bootstrap/BootstrappingConfiguration.php

@@ -1,4 +1,4 @@
-<?php
+<?php declare(strict_types=1);
 
 namespace Cspray\AnnotatedContainer\Bootstrap;
 

src/Bootstrap/BootstrappingDirectoryResolver.php

@@ -1,4 +1,4 @@
-<?php
+<?php declare(strict_types=1);
 
 namespace Cspray\AnnotatedContainer\Bootstrap;
 

src/Bootstrap/ServiceFromServiceDefinition.php

@@ -1,4 +1,4 @@
-<?php
+<?php declare(strict_types=1);
 
 namespace Cspray\AnnotatedContainer\Bootstrap;
 

src/Bootstrap/ServiceGatherer.php

@@ -1,4 +1,4 @@
-<?php
+<?php declare(strict_types=1);
 
 namespace Cspray\AnnotatedContainer\Bootstrap;
 

src/Bootstrap/ServiceWiringListener.php

@@ -1,4 +1,4 @@
-<?php
+<?php declare(strict_types=1);
 
 namespace Cspray\AnnotatedContainer\Bootstrap;
 

src/Bootstrap/ThirdPartyInitializer.php

@@ -1,4 +1,4 @@
-<?php
+<?php declare(strict_types=1);
 
 namespace Cspray\AnnotatedContainer\Bootstrap;
 

src/Bootstrap/ThirdPartyInitializerProvider.php

@@ -1,4 +1,4 @@
-<?php
+<?php declare(strict_types=1);
 
 namespace Cspray\AnnotatedContainer\Bootstrap;
 

src/Bootstrap/XmlBootstrappingConfiguration.php

@@ -1,4 +1,4 @@
-<?php
+<?php declare(strict_types=1);
 
 namespace Cspray\AnnotatedContainer\Bootstrap;
 

src/Cli/Command/Command.php

@@ -1,4 +1,4 @@
-<?php
+<?php declare(strict_types=1);
 
 namespace Cspray\AnnotatedContainer\Cli\Command;
 

src/Cli/Command/CommandExecutor.php

@@ -1,4 +1,4 @@
-<?php
+<?php declare(strict_types=1);
 
 namespace Cspray\AnnotatedContainer\Cli\Command;
 

src/Cli/Command/InitCommand.php

@@ -5,7 +5,6 @@
 use Cspray\AnnotatedContainer\AnnotatedContainerVersion;
 use Cspray\AnnotatedContainer\Bootstrap\BootstrappingDirectoryResolver;
 use Cspray\AnnotatedContainer\Bootstrap\ThirdPartyInitializerProvider;
-use Cspray\AnnotatedContainer\Cli\Command\Service\ConfigFileNameDecider;
 use Cspray\AnnotatedContainer\Cli\Exception\ComposerConfigurationNotFound;
 use Cspray\AnnotatedContainer\Cli\Exception\InvalidOptionType;
 use Cspray\AnnotatedContainer\Cli\Exception\PotentialConfigurationOverwrite;

src/Cli/Exception/CliException.php

@@ -3,7 +3,6 @@
 namespace Cspray\AnnotatedContainer\Cli\Exception;
 
 use Cspray\AnnotatedContainer\Exception\Exception;
-use Throwable;
 
 abstract class CliException extends Exception {
 

src/Cli/Exception/OptionNotFound.php

@@ -1,4 +1,4 @@
-<?php
+<?php declare(strict_types=1);
 
 namespace Cspray\AnnotatedContainer\Cli\Exception;
 

src/ContainerFactory/AbstractContainerFactory.php

@@ -23,28 +23,25 @@
  */
 abstract class AbstractContainerFactory implements ContainerFactory {
 
-    private readonly ?ContainerFactoryEmitter $emitter;
-
     /**
      * @var array<non-empty-string, ParameterStore>
      */
     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;
     }

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;

src/Definition/InjectDefinition.php

@@ -1,11 +1,9 @@
-<?php
+<?php declare(strict_types=1);
 
 namespace Cspray\AnnotatedContainer\Definition;
 
 use Cspray\AnnotatedContainer\Attribute\InjectAttribute;
 use Cspray\AnnotatedContainer\Reflection\Type;
-use Cspray\AnnotatedContainer\Reflection\TypeIntersect;
-use Cspray\AnnotatedContainer\Reflection\TypeUnion;
 
 /**
  * A definition that provides details on values that should be injected into method parameters or Configuration properties

src/Definition/Serializer/SerializedContainerDefinition.php

@@ -2,8 +2,6 @@
 
 namespace Cspray\AnnotatedContainer\Definition\Serializer;
 
-use DOMDocument;
-
 final class SerializedContainerDefinition {
 
     /**

test/Unit/Bootstrap/ComposerRuntimePackagesComposerJsonPathProviderTest.php

@@ -18,7 +18,6 @@ public function testCorrectPathsAreReturnedBasedOnInstalledPackages() : void {
             $vendorDir . '/cspray/precision-stopwatch/composer.json',
             $vendorDir . '/illuminate/container/composer.json',
             $vendorDir . '/illuminate/contracts/composer.json',
-            $vendorDir . '/jetbrains/phpstorm-attributes/composer.json',
             $vendorDir . '/laravel/serializable-closure/composer.json',
             $vendorDir . '/nikic/php-parser/composer.json',
             $vendorDir . '/php-di/invoker/composer.json',