psalm-types for complex service/extension/factory type hints. (#46)

* introduce psalm-types for complex service/extension/factory callables type hints.

Author: Chrico

src/Container/ContainerConfigurator.php

@@ -3,13 +3,16 @@
 
 namespace Inpsyde\Modularity\Container;
 
-use Psr\Container\ContainerExceptionInterface;
 use Psr\Container\ContainerInterface;
 
+/**
+ * @psalm-import-type Service from \Inpsyde\Modularity\Module\ServiceModule
+ * @psalm-import-type ExtendingService from \Inpsyde\Modularity\Module\ExtendingModule
+ */
 class ContainerConfigurator
 {
     /**
-     * @var array<string, callable(ContainerInterface $container):mixed>
+     * @var array<string, Service>
      */
     private $services = [];
 
@@ -56,7 +59,7 @@ public function addContainer(ContainerInterface $container): void
 
     /**
      * @param string $id
-     * @param callable(ContainerInterface $container):mixed $factory
+     * @param Service $factory
      */
     public function addFactory(string $id, callable $factory): void
     {
@@ -68,7 +71,7 @@ public function addFactory(string $id, callable $factory): void
 
     /**
      * @param string $id
-     * @param callable(ContainerInterface $container):mixed $service
+     * @param Service $service
      *
      * @return void
      */
@@ -110,7 +113,7 @@ public function hasService(string $id): bool
 
     /**
      * @param string $id
-     * @param callable(mixed $service, ContainerInterface $container):mixed $extender
+     * @param ExtendingService $extender
      *
      * @return void
      */

src/Container/ReadOnlyContainer.php

@@ -7,10 +7,14 @@
 use Psr\Container\ContainerInterface;
 use Psr\Container\NotFoundExceptionInterface;
 
+/**
+ * @psalm-import-type Service from \Inpsyde\Modularity\Module\ServiceModule
+ * @psalm-import-type ExtendingService from \Inpsyde\Modularity\Module\ExtendingModule
+ */
 class ReadOnlyContainer implements ContainerInterface
 {
     /**
-     * @var array<string, callable(\Psr\Container\ContainerInterface $container):mixed>
+     * @var array<string, Service>
      */
     private $services;
 
@@ -39,7 +43,7 @@ class ReadOnlyContainer implements ContainerInterface
     /**
      * ReadOnlyContainer constructor.
      *
-     * @param array<string, callable(ContainerInterface $container):mixed> $services
+     * @param array<string, Service> $services
      * @param array<string, bool> $factoryIds
      * @param ServiceExtensions|array $extensions
      * @param ContainerInterface[] $containers
@@ -149,7 +153,7 @@ private function configureServiceExtensions($extensions): ServiceExtensions
         foreach ($extensions as $id => $callback) {
             /**
              * @var string $id
-             * @var callable(mixed,ContainerInterface):mixed $callback
+             * @var ExtendingService $callback
              */
             $servicesExtensions->add($id, $callback);
         }

src/Container/ServiceExtensions.php

@@ -6,14 +6,17 @@
 
 use Psr\Container\ContainerInterface as Container;
 
+/**
+ * @psalm-import-type ExtendingService from \Inpsyde\Modularity\Module\ExtendingModule
+ */
 class ServiceExtensions
 {
     private const SERVICE_TYPE_NOT_CHANGED = 1;
     private const SERVICE_TYPE_CHANGED = 2;
     private const SERVICE_TYPE_NOT_OBJECT = 0;
 
     /**
-     * @var array<string, list<callable>>
+     * @var array<string, list<ExtendingService>>
      */
     protected $extensions = [];
 
@@ -28,7 +31,7 @@ final public static function typeId(string $type): string
 
     /**
      * @param string $extensionId
-     * @param callable $extender
+     * @param ExtendingService $extender
      * @return static
      */
     public function add(string $extensionId, callable $extender): ServiceExtensions
@@ -94,7 +97,7 @@ protected function resolveByType(
 
         $extendedClasses[] = $className;
 
-        /** @var array<class-string, list<callable>> $allCallbacks */
+        /** @var array<class-string, list<ExtendingService>> $allCallbacks */
         $allCallbacks = [];
 
         // 1st group of extensions: targeting exact class
@@ -147,7 +150,7 @@ protected function resolveByType(
      * @param class-string $type
      * @param object $service
      * @param Container $container
-     * @param array $extenders
+     * @param list<ExtendingService> $extenders
      * @return array{mixed, int}
      */
     private function extendByType(

src/Module/ExtendingModule.php

@@ -4,6 +4,11 @@
 
 namespace Inpsyde\Modularity\Module;
 
+use Psr\Container\ContainerInterface;
+
+/**
+ * @psalm-type ExtendingService = callable(mixed $service, ContainerInterface $container):mixed
+ */
 interface ExtendingModule extends Module
 {
 
@@ -18,7 +23,7 @@ interface ExtendingModule extends Module
      * That is done by using as ID (array key in the `extensions` method) the target module ID
      * and the service ID.
      *
-     * @return array<string, callable(mixed $service, \Psr\Container\ContainerInterface $container):mixed>
+     * @return array<string, ExtendingService>
      */
     public function extensions(): array;
 }

src/Module/FactoryModule.php

@@ -4,6 +4,9 @@
 
 namespace Inpsyde\Modularity\Module;
 
+/**
+ * @psalm-import-type Service from ServiceModule
+ */
 interface FactoryModule extends Module
 {
     /**
@@ -12,7 +15,7 @@ interface FactoryModule extends Module
      * Similar to `services`, but object created by given factories are not "cached", but a *new*
      * instance is returned everytime `get()` is called in the container.
      *
-     * @return array<string, callable(\Psr\Container\ContainerInterface $container):mixed>
+     * @return array<string, Service>
      */
     public function factories(): array;
 }

src/Module/ServiceModule.php

@@ -4,6 +4,11 @@
 
 namespace Inpsyde\Modularity\Module;
 
+use Psr\Container\ContainerInterface;
+
+/**
+ * @psalm-type Service = callable(ContainerInterface $container):mixed
+ */
 interface ServiceModule extends Module
 {
 
@@ -15,7 +20,7 @@ interface ServiceModule extends Module
      * Services are "cached", so the given factory is called once the first time `get()` is called
      * in the container, and on subsequent `get()` the same instance is returned again and again.
      *
-     * @return array<string, callable(\Psr\Container\ContainerInterface $container):mixed>
+     * @return array<string, Service>
      */
     public function services(): array;
 }

src/Package.php

@@ -14,6 +14,10 @@
 use Inpsyde\Modularity\Properties\Properties;
 use Psr\Container\ContainerInterface;
 
+/**
+ * @psalm-import-type Service from \Inpsyde\Modularity\Module\ServiceModule
+ * @psalm-import-type ExtendingService from \Inpsyde\Modularity\Module\ExtendingModule
+ */
 class Package
 {
     /**
@@ -507,7 +511,7 @@ private function addModuleServices(Module $module, string $status): bool
         array_walk(
             $services,
             static function (callable $service, string $id) use ($addCallback, &$ids) {
-                /** @var callable(string, callable) $addCallback */
+                /** @var callable(string, Service|ExtendingService) $addCallback */
                 $addCallback($id, $service);
                 /** @var list<string> $ids */
                 $ids[] = $id;