Merge pull request #1190 from spiral/issue/1064

feature: PHP Attributes for Bootloader Methods

Author: roxblnfk

src/Boot/src/AbstractKernel.php

@@ -9,6 +9,8 @@
 use Spiral\Boot\Bootloader\BootloaderRegistry;
 use Spiral\Boot\Bootloader\BootloaderRegistryInterface;
 use Spiral\Boot\Bootloader\CoreBootloader;
+use Spiral\Boot\BootloadManager\AttributeResolver;
+use Spiral\Boot\BootloadManager\AttributeResolverRegistryInterface;
 use Spiral\Boot\BootloadManager\StrategyBasedBootloadManager;
 use Spiral\Boot\BootloadManager\DefaultInvokerStrategy;
 use Spiral\Boot\BootloadManager\Initializer;
@@ -119,9 +121,12 @@ final public static function create(
             $exceptionHandler->register();
         }
 
+        $container->bind(AttributeResolverRegistryInterface::class, AttributeResolver::class);
+
         if (!$container->has(InitializerInterface::class)) {
             $container->bind(InitializerInterface::class, Initializer::class);
         }
+
         if (!$container->has(InvokerStrategyInterface::class)) {
             $container->bind(InvokerStrategyInterface::class, DefaultInvokerStrategy::class);
         }

src/Boot/src/Attribute/AbstractMethod.php

@@ -0,0 +1,32 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Spiral\Boot\Attribute;
+
+/**
+ * Abstract base class for method attributes used in bootloaders.
+ * 
+ * This abstract class serves as a base for all method-level attributes in the bootloader system,
+ * providing common functionality for managing binding aliases.
+ *
+ * @internal This class is for internal use within the framework and should not be used directly by application code.
+ */
+abstract class AbstractMethod
+{
+    /**
+     * @param non-empty-string|null $alias Alias for the method. If not provided, the return type of the method will be used as the alias.
+     * @param bool $aliasesFromReturnType Add aliases from the return type of the method even if the method has an alias.
+     */
+    public function __construct(
+        /**
+         * Alias for the method.
+         * If not provided, the return type of the method will be used as the alias.
+         */
+        public readonly ?string $alias = null,
+        /**
+         * Add aliases from the return type of the method even if the method has an alias.
+         */
+        public readonly bool $aliasesFromReturnType = false,
+    ) {}
+}

src/Boot/src/Attribute/BindAlias.php

@@ -0,0 +1,46 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Spiral\Boot\Attribute;
+
+/**
+ * Attribute to define additional aliases for a method.
+ * 
+ * This attribute allows defining multiple aliases for a method in a bootloader class.
+ * It can be used to bind a method's return value to multiple interface or class names.
+ * 
+ * This attribute can be applied multiple times to the same method.
+ * 
+ * Example usage:
+ * ```php
+ * class MyBootloader extends Bootloader
+ * {
+ *     #[BindAlias(LoggerInterface::class, PsrLoggerInterface::class)]
+ *     #[BindAlias(MonologLoggerInterface::class)]
+ *     public function createLogger(): Logger
+ *     {
+ *         return new Logger();
+ *     }
+ * }
+ * ```
+ * 
+ * The above example binds the returned Logger instance to LoggerInterface, 
+ * PsrLoggerInterface, and MonologLoggerInterface.
+ */
+#[\Attribute(\Attribute::TARGET_METHOD | \Attribute::IS_REPEATABLE)]
+final class BindAlias
+{
+    /**
+     * @param non-empty-string[] $aliases List of class or interface names to bind the returned value to.
+     */
+    public readonly array $aliases;
+
+    /**
+     * @param non-empty-string ...$aliases List of class or interface names to bind the returned value to.
+     */
+    public function __construct(string ...$aliases)
+    {
+        $this->aliases = $aliases;
+    }
+}

src/Boot/src/Attribute/BindMethod.php

@@ -0,0 +1,51 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Spiral\Boot\Attribute;
+
+/**
+ * Attribute for marking methods that provide container bindings.
+ * 
+ * Methods marked with this attribute will be invoked each time the container
+ * needs to resolve the dependency, creating a new instance each time.
+ * The return value of the method will be bound to the specified alias
+ * or to all interfaces/classes in the return type.
+ * 
+ * Example usage:
+ * ```php
+ * class MyBootloader extends Bootloader
+ * {
+ *     // Method will be called each time the container resolves HttpClientInterface
+ *     #[BindMethod]
+ *     public function createHttpClient(): HttpClientInterface
+ *     {
+ *         return new HttpClient();
+ *     }
+ *     
+ *     // Method will be called each time the container resolves DbFactory
+ *     // instead of its return type (DatabaseFactory)
+ *     #[BindMethod(alias: DbFactory::class)]
+ *     public function createDatabaseFactory(): DatabaseFactory
+ *     {
+ *         return new DatabaseFactory();
+ *     }
+ *     
+ *     // Method will be called each time the container resolves either
+ *     // LogManagerInterface or its return type (LogManager)
+ *     #[BindMethod(alias: LogManagerInterface::class, aliasesFromReturnType: true)]
+ *     public function createLogManager(): LogManager
+ *     {
+ *         return new LogManager();
+ *     }
+ * }
+ * ```
+ * 
+ * This attribute is similar to defining bindings via the `defineBindings()` method,
+ * but with a more expressive and type-safe approach.
+ * 
+ * @see SingletonMethod For binding singleton instances
+ * @see InjectorMethod For binding injector methods
+ */
+#[\Attribute(\Attribute::TARGET_METHOD)]
+final class BindMethod extends AbstractMethod {}

src/Boot/src/Attribute/BindScope.php

@@ -0,0 +1,54 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Spiral\Boot\Attribute;
+
+/**
+ * Attribute to bind a method's result to a specific container scope.
+ *
+ * This attribute allows defining a specific scope for the binding created
+ * by method attributes such as BindMethod or SingletonMethod.
+ *
+ * Example usage:
+ * ```php
+ * class MyBootloader extends Bootloader
+ * {
+ *     // Bind to the 'http' scope
+ *     #[BindMethod]
+ *     #[BindScope('http')]
+ *     public function createHttpClient(): HttpClientInterface
+ *     {
+ *         return new HttpClient();
+ *     }
+ *
+ *     // Bind to the 'console' scope using an enum
+ *     #[SingletonMethod]
+ *     #[BindScope(ScopeEnum::Console)]
+ *     public function createConsoleOutput(): OutputInterface
+ *     {
+ *         return new ConsoleOutput();
+ *     }
+ * }
+ * ```
+ *
+ * When using a scope, the binding will only be available when the container
+ * is running within that scope.
+ */
+#[\Attribute(\Attribute::TARGET_METHOD | \Attribute::IS_REPEATABLE)]
+final class BindScope
+{
+    /**
+     * The scope name to bind to.
+     */
+    public readonly string $scope;
+
+    /**
+     * @param string|\BackedEnum $scope The scope name or enum value to bind to.
+     *                                  If an enum is provided, its value will be used as the scope name.
+     */
+    public function __construct(string|\BackedEnum $scope)
+    {
+        $this->scope = \is_object($scope) ? (string) $scope->value : $scope;
+    }
+}

src/Boot/src/Attribute/BootMethod.php

@@ -0,0 +1,58 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Spiral\Boot\Attribute;
+
+/**
+ * Attribute for marking methods that should be called during the boot phase.
+ * 
+ * Methods marked with this attribute will be called during the bootloader's
+ * boot phase, after all initialization methods have been called.
+ * The boot phase is where you typically configure services, register event listeners,
+ * or perform other setup tasks.
+ * 
+ * The priority parameter determines the order in which boot methods are called.
+ * Higher priority values are executed first.
+ * 
+ * Example usage:
+ * ```php
+ * class MyBootloader extends Bootloader
+ * {
+ *     // Called during boot phase with default priority (0)
+ *     #[BootMethod]
+ *     public function configureRoutes(RouterInterface $router): void
+ *     {
+ *         $router->addRoute('home', '/');
+ *     }
+ *     
+ *     // Called during boot phase with high priority (10)
+ *     #[BootMethod(priority: 10)]
+ *     public function configureDatabase(DatabaseInterface $db): void
+ *     {
+ *         $db->setDefaultConnection('default');
+ *     }
+ *     
+ *     // Called during boot phase with low priority (-10)
+ *     #[BootMethod(priority: -10)]
+ *     public function registerEventListeners(EventDispatcherInterface $dispatcher): void
+ *     {
+ *         $dispatcher->addListener(ApplicationStarted::class, fn() => $this->onStart());
+ *     }
+ * }
+ * ```
+ * 
+ * Boot methods are executed after all bootloaders' init methods have been called.
+ * 
+ * @see InitMethod For methods to be called during initialization phase
+ */
+#[\Attribute(\Attribute::TARGET_METHOD)]
+final class BootMethod
+{
+    /**
+     * @param int $priority The priority of this boot method. Higher values are executed first.
+     */
+    public function __construct(
+        public readonly int $priority = 0,
+    ) {}
+}

src/Boot/src/Attribute/BootloadConfig.php

@@ -4,11 +4,62 @@
 
 namespace Spiral\Boot\Attribute;
 
-use Spiral\Attributes\NamedArgumentConstructor;
-
-#[\Attribute(\Attribute::TARGET_CLASS), NamedArgumentConstructor]
+/**
+ * Attribute to configure bootloader behavior.
+ * 
+ * This attribute allows defining configuration for bootloaders, including
+ * constructor arguments, enabling/disabling based on environment variables,
+ * and controlling how configuration overrides work.
+ * 
+ * Example usage:
+ * ```php
+ * // Basic configuration with constructor arguments
+ * #[BootloadConfig(args: ['defaultConnection' => 'sqlite'])]
+ * class DatabaseBootloader extends Bootloader
+ * {
+ *     public function __construct(
+ *         private readonly string $defaultConnection
+ *     ) {}
+ *     
+ *     // ...
+ * }
+ * 
+ * // Conditionally enable based on environment
+ * #[BootloadConfig(
+ *     allowEnv: ['APP_ENV' => ['local', 'development']],
+ *     denyEnv: ['TESTING' => [true, 1, 'true']]
+ * )]
+ * class DevToolsBootloader extends Bootloader
+ * {
+ *     // Only loaded in local or development environments
+ *     // And not when TESTING is true
+ * }
+ * 
+ * // Prevent runtime configuration from overriding attribute configuration
+ * #[BootloadConfig(args: ['debug' => true], override: false)]
+ * class DebugBootloader extends Bootloader
+ * {
+ *     // The 'debug' argument will always be true, even if different
+ *     // configuration is provided at runtime
+ * }
+ * ```
+ * 
+ * When a bootloader has both runtime configuration and a BootloadConfig attribute,
+ * the override parameter controls which configuration takes precedence.
+ */
+#[\Attribute(\Attribute::TARGET_CLASS)]
 class BootloadConfig
 {
+    /**
+     * @param array $args Arguments to pass to the bootloader's constructor.
+     * @param bool $enabled Whether this bootloader is enabled.
+     * @param array $allowEnv Environment conditions that must be satisfied for the bootloader to be enabled.
+     *                        Format: ['ENV_VAR' => ['allowed_value1', 'allowed_value2']]
+     * @param array $denyEnv Environment conditions that must not be satisfied for the bootloader to be enabled.
+     *                       Format: ['ENV_VAR' => ['denied_value1', 'denied_value2']]
+     * @param bool $override Whether runtime configuration should override the attribute configuration.
+     *                       If false, attribute configuration takes precedence.
+     */
     public function __construct(
         public array $args = [],
         public bool $enabled = true,

src/Boot/src/Attribute/InitMethod.php

@@ -0,0 +1,57 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Spiral\Boot\Attribute;
+
+/**
+ * Attribute for marking methods that should be called during the initialization phase.
+ * 
+ * Methods marked with this attribute will be called during the bootloader's
+ * initialization phase, before the boot phase begins. This is where you typically
+ * set up container bindings, register services, or perform other initialization tasks.
+ * 
+ * The priority parameter determines the order in which init methods are called.
+ * Higher priority values are executed first.
+ * 
+ * Example usage:
+ * ```php
+ * class MyBootloader extends Bootloader
+ * {
+ *     // Called during initialization phase with default priority (0)
+ *     #[InitMethod]
+ *     public function registerServices(Container $container): void
+ *     {
+ *         $container->bindSingleton(MyService::class, MyServiceImplementation::class);
+ *     }
+ *     
+ *     // Called during initialization phase with high priority (10)
+ *     #[InitMethod(priority: 10)]
+ *     public function setupCore(): void
+ *     {
+ *         // Setup core components first
+ *     }
+ *     
+ *     // Called during initialization phase with low priority (-10)
+ *     #[InitMethod(priority: -10)]
+ *     public function setupExtensions(): void
+ *     {
+ *         // Setup extensions after core components
+ *     }
+ * }
+ * ```
+ * 
+ * Init methods are executed before any bootloader's boot methods are called.
+ * 
+ * @see BootMethod For methods to be called during boot phase
+ */
+#[\Attribute(\Attribute::TARGET_METHOD)]
+final class InitMethod
+{
+    /**
+     * @param int $priority The priority of this init method. Higher values are executed first.
+     */
+    public function __construct(
+        public readonly int $priority = 0,
+    ) {}
+}