feat(di): Add new Dependency Injection interfaces

.gitignore

@@ -59,4 +59,5 @@ temp/
 tmp/
 .vscode/launch.json
 .vscode/extensions.json
-tests/lista_de_arquivos.php
+tests/lista_de_arquivos.php
+/composer.lock

src/DI/Compiler.php

@@ -0,0 +1,42 @@
+<?php
+
+declare(strict_types=1);
+
+namespace KaririCode\Contract\DI;
+
+/**
+ * Interface Compiler.
+ *
+ * Defines the contract for compiling container definitions and handling caching mechanisms.
+ *
+ * @category  DependencyInjection
+ *
+ * @author    Walmir Silva <walmir.silva@kariricode.org>
+ */
+interface Compiler
+{
+    /**
+     * Compiles the container definitions.
+     *
+     * @param Container $container The container to compile
+     *
+     * @return Container Compiled container
+     */
+    public function compile(Container $container): Container;
+
+    /**
+     * Writes compiled container to a file.
+     *
+     * @param string $path Path to the file where compiled container will be written
+     */
+    public function writeToFile(string $path): void;
+
+    /**
+     * Loads compiled container definitions from a file.
+     *
+     * @param string $path Path to the file containing compiled container definitions
+     *
+     * @return Container Loaded container instance
+     */
+    public function loadFromFile(string $path): Container;
+}

src/DI/Container.php

@@ -0,0 +1,122 @@
+<?php
+
+declare(strict_types=1);
+
+namespace KaririCode\Contract\DI;
+
+/**
+ * Interface Container.
+ *
+ * Defines the contract for a dependency injection container that manages the creation and resolution of services.
+ *
+ * @category  DependencyInjection
+ *
+ * @author    Walmir Silva <walmir.silva@kariricode.org>
+ */
+interface Container
+{
+    /**
+     * Sets a service in the container.
+     *
+     * @param string $id Identifier of the service
+     * @param callable $service The callable that returns the service instance
+     */
+    public function set(string $id, callable $service): void;
+
+    /**
+     * Retrieves a service by its identifier.
+     *
+     * @param string $id Identifier of the service to retrieve
+     *
+     * @return mixed The service instance
+     */
+    public function get(string $id): mixed;
+
+    /**
+     * Checks if the container can return a service for the given identifier.
+     *
+     * @param string $id Identifier of the service to check
+     *
+     * @return bool True if the service is found, false otherwise
+     */
+    public function has(string $id): bool;
+
+    /**
+     * Resolves and returns an instance of the given abstract type.
+     *
+     * @param string $abstract The abstract type or identifier to resolve
+     *
+     * @return object Resolved instance of the given abstract
+     */
+    public function resolve(string $abstract): object;
+
+    /**
+     * Binds a concrete implementation to an abstract type with optional parameters.
+     *
+     * @param string $abstract The abstract type or identifier
+     * @param mixed $concrete The concrete implementation (class name or closure)
+     * @param array $parameters Optional parameters for instantiation
+     */
+    public function bind(string $abstract, mixed $concrete, array $parameters = []): void;
+
+    /**
+     * Registers a singleton binding, ensuring the instance is created only once.
+     *
+     * @param string $abstract The abstract type or identifier
+     * @param mixed $concrete The concrete implementation (class name or closure)
+     * @param array $parameters Optional parameters
+     */
+    public function singleton(string $abstract, mixed $concrete, array $parameters = []): void;
+
+    /**
+     * Registers a factory binding, creating a new instance upon each resolution.
+     *
+     * @param string $abstract The abstract type or identifier
+     * @param mixed $concrete The concrete implementation (class name or closure)
+     * @param array $parameters Optional parameters
+     */
+    public function factory(string $abstract, mixed $concrete, array $parameters = []): void;
+
+    /**
+     * Assigns multiple abstracts to a specific tag.
+     *
+     * @param string $tag Tag name
+     * @param array $abstracts List of abstract identifiers
+     */
+    public function tag(string $tag, array $abstracts): void;
+
+    /**
+     * Retrieves abstracts associated with a specific tag.
+     *
+     * @param string $tag Tag name
+     *
+     * @return array Abstract identifiers tagged
+     */
+    public function tagged(string $tag): array;
+
+    /**
+     * Executes a callable or method with provided parameters.
+     *
+     * @param callable|string $callback The callable or method name
+     * @param array $parameters Parameters to pass
+     *
+     * @return mixed Result of the callable execution
+     */
+    public function call(callable|string $callback, array $parameters = []): mixed;
+
+    /**
+     * Extends an existing binding.
+     *
+     * @param string $abstract Abstract identifier to extend
+     * @param \Closure $extender Closure to extend functionality
+     */
+    public function extend(string $abstract, \Closure $extender): void;
+
+    /**
+     * Creates an alias for an abstract identifier.
+     *
+     * @param string $abstract Original abstract identifier
+     * @param string $alias Alias to use
+     */
+    public function alias(string $abstract, string $alias): void;
+}

src/DI/Definition.php

@@ -0,0 +1,52 @@
+<?php
+
+declare(strict_types=1);
+
+namespace KaririCode\Contract\DI;
+
+/**
+ * Interface Definition.
+ *
+ * Defines the contract for service definitions managed by the dependency injection container.
+ *
+ * @category  DependencyInjection
+ *
+ * @author    Walmir Silva <walmir.silva@kariricode.org>
+ */
+interface Definition
+{
+    /**
+     * Gets the concrete implementation.
+     *
+     * @return mixed The concrete implementation of the service
+     */
+    public function getConcrete(): mixed;
+
+    /**
+     * Gets the instantiation parameters.
+     *
+     * @return array Parameters used for service instantiation
+     */
+    public function getParameters(): array;
+
+    /**
+     * Gets tags associated with the definition.
+     *
+     * @return array List of tags associated with this definition
+     */
+    public function getTags(): array;
+
+    /**
+     * Checks if definition is a singleton.
+     *
+     * @return bool True if the definition is a singleton, false otherwise
+     */
+    public function isSingleton(): bool;
+
+    /**
+     * Checks if definition is a factory.
+     *
+     * @return bool True if the definition is a factory, false otherwise
+     */
+    public function isFactory(): bool;
+}

src/DI/Provider.php

@@ -0,0 +1,31 @@
+<?php
+
+declare(strict_types=1);
+
+namespace KaririCode\Contract\DI;
+
+/**
+ * Interface Provider.
+ *
+ * Defines the contract for service providers responsible for registering and bootstrapping services.
+ *
+ * @category  DependencyInjection
+ *
+ * @author    Walmir Silva <walmir.silva@kariricode.org>
+ */
+interface Provider
+{
+    /**
+     * Registers services into the container.
+     *
+     * @param Container $container The dependency injection container
+     */
+    public function register(Container $container): void;
+
+    /**
+     * Boots services after registration.
+     *
+     * @param Container $container The dependency injection container
+     */
+    public function boot(Container $container): void;
+}