Feature/listener configuration (#408)

* Initial skeleton for supporting configured listeners

* Organize bootstrap code into better sub-namespaces

* Add Listeners to config, fix various psalm issues

* Add phploc to tools

* Add support for listener option

Author: cspray

Justfile

@@ -4,7 +4,7 @@ _default:
     just --list --unsorted
 
 # Install all dependencies necesesary to run Annotated Container tools
-install: _install_labrador_cs _install_phpunit _install_psalm _install_ac
+install: _install_labrador_cs _install_phpunit _install_psalm _install_phploc _install_ac
 
 _install_ac:
     composer install
@@ -18,6 +18,9 @@ _install_phpunit:
 _install_psalm:
     cd tools/psalm && composer install
 
+_install_phploc:
+    cd tools/phploc && composer install
+
 # Run unit tests
 test *FLAGS:
     @XDEBUG_MODE=coverage ./tools/phpunit/vendor/bin/phpunit {{FLAGS}}
@@ -47,6 +50,9 @@ code-lint:
 code-lint-fix:
     @./tools/labrador-cs/vendor/bin/phpcbf -p --standard=./tools/labrador-cs/vendor/cspray/labrador-coding-standard/ruleset.xml --exclude=Generic.Files.LineLength src test
 
+loc:
+    @./tools/phploc/vendor/bin/phploc src
+
 # Run all CI checks. ALL checks will run, regardless of failures
 ci-check:
     -@just test

annotated-container.xsd

@@ -32,6 +32,7 @@
 
       <xs:element name="definitionProviders" type="definitionProvidersType" minOccurs="0" maxOccurs="1" />
       <xs:element name="parameterStores" type="parameterStoresType" minOccurs="0" maxOccurs="1" />
+      <xs:element name="listeners" type="listenersType" minOccurs="0" maxOccurs="1" />
     </xs:all>
     <xs:attribute name="version" type="xs:string" use="required" />
   </xs:complexType>
@@ -86,5 +87,10 @@
     </xs:sequence>
   </xs:complexType>
 
+  <xs:complexType name="listenersType">
+    <xs:sequence minOccurs="0" maxOccurs="unbounded">
+      <xs:element name="listener" type="xs:token" />
+    </xs:sequence>
+  </xs:complexType>
 
 </xs:schema>

docs/how-to/02-bootstrap-your-container.md

@@ -224,7 +224,7 @@ By default, boostrapping expects all the path fragments in your configuration to
 
 namespace Acme\Demo;
 
-use Cspray\AnnotatedContainer\Bootstrap\Bootstrap;use Cspray\AnnotatedContainer\Bootstrap\DefaultDefinitionProviderFactory;use Cspray\AnnotatedContainer\Bootstrap\DefaultParameterStoreFactory;use Cspray\AnnotatedContainer\ContainerFactory\PhpDiContainerFactory;use Cspray\AnnotatedContainer\Event\Emitter;
+use Cspray\AnnotatedContainer\Bootstrap\Bootstrap;use Cspray\AnnotatedContainer\Bootstrap\Configuration\DefaultDefinitionProviderFactory;use Cspray\AnnotatedContainer\Bootstrap\Configuration\DefaultParameterStoreFactory;use Cspray\AnnotatedContainer\ContainerFactory\PhpDiContainerFactory;use Cspray\AnnotatedContainer\Event\Emitter;
 
 // This method is an implementation provided by the reader
 $directoryResolver = MyDirectoryResolver::create();
@@ -252,12 +252,7 @@ Setting up caching is something that you must explicitly opt into during your bo
 
 namespace Acme\Demo;
 
-use Cspray\AnnotatedContainer\Bootstrap\Bootstrap;
-use Cspray\AnnotatedContainer\Bootstrap\CacheAwareBootstrappingConfigurationProvider;
-use Cspray\AnnotatedContainer\Bootstrap\DefaultDefinitionProviderFactory;
-use Cspray\AnnotatedContainer\Bootstrap\DefaultParameterStoreFactory;
-use Cspray\AnnotatedContainer\Bootstrap\XmlBootstrappingConfigurationProvider;use Cspray\AnnotatedContainer\ContainerFactory\PhpDiContainerFactory;
-use Cspray\AnnotatedContainer\Definition\Cache\FileBackedContainerDefinitionCache;use Cspray\AnnotatedContainer\Definition\Serializer\XmlContainerDefinitionSerializer;use Cspray\AnnotatedContainer\Event\Emitter;
+use Cspray\AnnotatedContainer\Bootstrap\Bootstrap;use Cspray\AnnotatedContainer\Bootstrap\CacheAwareBootstrappingConfigurationProvider;use Cspray\AnnotatedContainer\Bootstrap\XmlBootstrappingConfigurationProvider;use Cspray\AnnotatedContainer\Definition\Cache\FileBackedContainerDefinitionCache;use Cspray\AnnotatedContainer\Definition\Serializer\XmlContainerDefinitionSerializer;use Cspray\AnnotatedContainer\Event\Emitter;
 
 $container = Bootstrap::from(new Emitter())
     ->bootstrapContainer(

known-issues.xml

@@ -1,6 +1,11 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <files psalm-version="5.24.0@462c80e31c34e58cc4f750c656be3927e80e550e">
-  <file src="src/Bootstrap/ServiceWiringListener.php">
+  <file src="src/Bootstrap/Configuration/ContainerDefinitionAnalysisOptionsFromBootstrappingConfiguration.php">
+    <ArgumentTypeCoercion>
+      <code><![CDATA[$scanPaths]]></code>
+    </ArgumentTypeCoercion>
+  </file>
+  <file src="src/Bootstrap/Listener/ServiceWiringListener.php">
     <MixedArgument>
       <code><![CDATA[$service]]></code>
     </MixedArgument>
@@ -66,7 +71,7 @@
                         [$serviceDelegateDefinition->classMethod()->class()->name(), $serviceDelegateDefinition->classMethod()->methodName()],
                         $this->parametersForServiceDelegateToArray($injector, $state, $serviceDelegateDefinition),
                     )]]></code>
-      <code><![CDATA[$value]]></code>
+      <code><![CDATA[$this->injector->make($id)]]></code>
     </MixedReturnStatement>
   </file>
   <file src="src/ContainerFactory/ContainerFactoryOptionsBuilder.php">
@@ -234,11 +239,8 @@
     </InvalidArgument>
   </file>
   <file src="src/StaticAnalysis/ContainerDefinitionAnalysisOptionsBuilder.php">
-    <LessSpecificReturnStatement>
+    <InvalidArgument>
       <code><![CDATA[$this->directories]]></code>
-    </LessSpecificReturnStatement>
-    <MoreSpecificReturnType>
-      <code><![CDATA[array]]></code>
-    </MoreSpecificReturnType>
+    </InvalidArgument>
   </file>
 </files>

psalm.xml

@@ -36,7 +36,7 @@
         <MissingTemplateParam>
             <errorLevel type="suppress">
                 <!-- This anonymous class is 100% documented with the appropriate template param but it is not getting picked up properly -->
-                <file name="src/Bootstrap/ServiceWiringListener.php" />
+                <file name="src/Bootstrap/Listener/ServiceWiringListener.php" />
             </errorLevel>
         </MissingTemplateParam>
     </issueHandlers>

src/Bootstrap/Bootstrap.php

@@ -3,6 +3,17 @@
 namespace Cspray\AnnotatedContainer\Bootstrap;
 
 use Cspray\AnnotatedContainer\AnnotatedContainer;
+use Cspray\AnnotatedContainer\Bootstrap\Configuration\BootstrappingConfiguration;
+use Cspray\AnnotatedContainer\Bootstrap\Configuration\ContainerDefinitionAnalysisOptionsFromBootstrappingConfiguration;
+use Cspray\AnnotatedContainer\Bootstrap\Configuration\DefaultDefinitionProviderFactory;
+use Cspray\AnnotatedContainer\Bootstrap\Configuration\DefaultListenerFactory;
+use Cspray\AnnotatedContainer\Bootstrap\Configuration\DefaultParameterStoreFactory;
+use Cspray\AnnotatedContainer\Bootstrap\Configuration\DefinitionProviderFactory;
+use Cspray\AnnotatedContainer\Bootstrap\Configuration\ListenerFactory;
+use Cspray\AnnotatedContainer\Bootstrap\Configuration\ParameterStoreFactory;
+use Cspray\AnnotatedContainer\Bootstrap\Configuration\XmlBootstrappingConfiguration;
+use Cspray\AnnotatedContainer\Bootstrap\DirectoryResolver\BootstrappingDirectoryResolver;
+use Cspray\AnnotatedContainer\Bootstrap\DirectoryResolver\VendorPresenceBasedBootstrappingDirectoryResolver;
 use Cspray\AnnotatedContainer\ContainerFactory\ContainerFactory;
 use Cspray\AnnotatedContainer\ContainerFactory\ContainerFactoryOptionsBuilder;
 use Cspray\AnnotatedContainer\Definition\ContainerDefinition;
@@ -33,6 +44,7 @@ public static function fromAnnotatedContainerConventions(
         ContainerFactory $containerFactory,
         Emitter $emitter,
         ParameterStoreFactory $parameterStoreFactory = new DefaultParameterStoreFactory(),
+        ListenerFactory $listenerFactory = new DefaultListenerFactory(),
         DefinitionProviderFactory $definitionProviderFactory = new DefaultDefinitionProviderFactory(),
         BootstrappingDirectoryResolver $directoryResolver = new VendorPresenceBasedBootstrappingDirectoryResolver(),
         Filesystem $filesystem = new PhpFunctionsFilesystem()
@@ -41,7 +53,8 @@ public static function fromAnnotatedContainerConventions(
             $filesystem,
             $directoryResolver->configurationPath('annotated-container.xml'),
             $parameterStoreFactory,
-            $definitionProviderFactory
+            $definitionProviderFactory,
+            $listenerFactory
         );
 
         return self::fromCompleteSetup(
@@ -75,6 +88,10 @@ public function bootstrapContainer(
 
         $this->stopwatch->start();
 
+        foreach ($this->bootstrappingConfiguration->listeners() as $listener) {
+            $this->emitter->addListener($listener);
+        }
+
         $analysisOptions = $this->analysisOptions($this->bootstrappingConfiguration);
 
         $this->emitter->emitBeforeBootstrap($this->bootstrappingConfiguration);

src/Bootstrap/BootstrappingConfiguration.php renamed to src/Bootstrap/Configuration/BootstrappingConfiguration.php

@@ -1,11 +1,12 @@
 <?php declare(strict_types=1);
 
-namespace Cspray\AnnotatedContainer\Bootstrap;
+namespace Cspray\AnnotatedContainer\Bootstrap\Configuration;
 
 use Cspray\AnnotatedContainer\ArchitecturalDecisionRecords\SingleEntrypointDefinitionProvider;
+use Cspray\AnnotatedContainer\ContainerFactory\ParameterStore;
 use Cspray\AnnotatedContainer\Definition\Cache\ContainerDefinitionCache;
+use Cspray\AnnotatedContainer\Event\Listener;
 use Cspray\AnnotatedContainer\StaticAnalysis\DefinitionProvider;
-use Cspray\AnnotatedContainer\ContainerFactory\ParameterStore;
 
 interface BootstrappingConfiguration {
 
@@ -23,4 +24,9 @@ public function containerDefinitionProvider() : ?DefinitionProvider;
      * @return list<ParameterStore>
      */
     public function parameterStores() : array;
+
+    /**
+     * @return list<Listener>
+     */
+    public function listeners() : array;
 }

src/Bootstrap/CacheAwareBootstrappingConfiguration.php renamed to src/Bootstrap/Configuration/CacheAwareBootstrappingConfiguration.php

@@ -1,6 +1,6 @@
 <?php declare(strict_types=1);
 
-namespace Cspray\AnnotatedContainer\Bootstrap;
+namespace Cspray\AnnotatedContainer\Bootstrap\Configuration;
 
 use Cspray\AnnotatedContainer\ArchitecturalDecisionRecords\SingleEntrypointDefinitionProvider;
 use Cspray\AnnotatedContainer\Definition\Cache\ContainerDefinitionCache;
@@ -30,4 +30,8 @@ public function containerDefinitionProvider() : ?DefinitionProvider {
     public function parameterStores() : array {
         return $this->configuration->parameterStores();
     }
+
+    public function listeners() : array {
+        return $this->configuration->listeners();
+    }
 }

src/Bootstrap/ContainerDefinitionAnalysisOptionsFromBootstrappingConfiguration.php renamed to src/Bootstrap/Configuration/ContainerDefinitionAnalysisOptionsFromBootstrappingConfiguration.php

@@ -1,7 +1,8 @@
 <?php declare(strict_types=1);
 
-namespace Cspray\AnnotatedContainer\Bootstrap;
+namespace Cspray\AnnotatedContainer\Bootstrap\Configuration;
 
+use Cspray\AnnotatedContainer\Bootstrap\DirectoryResolver\BootstrappingDirectoryResolver;
 use Cspray\AnnotatedContainer\StaticAnalysis\ContainerDefinitionAnalysisOptions;
 use Cspray\AnnotatedContainer\StaticAnalysis\ContainerDefinitionAnalysisOptionsBuilder;
 

src/Bootstrap/DefaultDefinitionProviderFactory.php renamed to src/Bootstrap/Configuration/DefaultDefinitionProviderFactory.php

@@ -1,6 +1,6 @@
 <?php declare(strict_types=1);
 
-namespace Cspray\AnnotatedContainer\Bootstrap;
+namespace Cspray\AnnotatedContainer\Bootstrap\Configuration;
 
 use Cspray\AnnotatedContainer\Exception\InvalidDefinitionProvider;
 use Cspray\AnnotatedContainer\StaticAnalysis\DefinitionProvider;