feat(di): Add new Dependency Injection interfaces (#37)

* add size method

* feat: Normalize Interfaces

- Refined and standardized interface definitions across the project
- Applied Single Responsibility Principle (SRP) to ensure each interface has a clear, singular purpose
- Consistent naming conventions were implemented for better readability and maintainability
- Added thorough documentation for each interface, including method descriptions and expected behaviors
- Organized interfaces within appropriate namespaces to prevent naming collisions and maintain a logical structure
- Ensured parameter names in interface methods are consistent with implementing classes
- Avoided including constructors in interfaces to maintain flexibility

These changes enhance the overall clarity, maintainability, and professional quality of the codebase.

* Refactor and Normalize Collection Interface and Implementation

- Refactored `Collection` interface for consistency and adherence to best practices.
- Ensured all tests are comprehensive and validate the expected behavior.

* feat: Add BinaryHeap implementation and comprehensive tests

- Implemented BinaryHeap class with support for both min-heap and max-heap operations.
  - Methods include: add, poll, peek, size, isEmpty, heapifyUp, heapifyDown, swap, and compare.
- Created unit tests for BinaryHeap class ensuring 100% coverage.
  - Tested all key operations: add, poll, peek, heapifyUp, heapifyDown, swap, and compare.
  - Included edge case tests for min-heap and max-heap scenarios.
- Ensured compliance with type safety and PHP 8.0+ features.
- Added comprehensive documentation and examples for BinaryHeap usage.

This commit enhances the KaririCode Framework by providing a robust, type-safe, and efficient BinaryHeap data structure with extensive unit tests.

* docs: Update README files in English and Portuguese

- Enhanced the overview and key features sections for clarity and completeness.
- Added detailed descriptions for all implemented data structures:
  - TreeSet
  - ArrayDeque
  - ArrayQueue
  - TreeMap
  - LinkedList
  - BinaryHeap
  - HashMap
- Included complexity analysis and key methods for each data structure.
- Provided usage examples for each data structure to demonstrate functionality.
- Updated installation instructions and requirements.
- Updated acknowledgments and roadmap sections.

* style: Normalize code formatting and style

* feat: Create Container interface and add unit tests

- Define the Container interface with methods: `set`, `get`, and `has`.
- Implement unit tests for `set` method to ensure services are registered correctly.
- Add unit tests for `get` method to verify correct retrieval of services by identifier.
- Include unit tests for `has` method to check existence of services in the container.
- Normalize the `@category` comments in the interface documentation for consistency.

These changes establish a foundational contract for dependency injection within the KaririCode project and ensure robust and reliable functionality through comprehensive testing

* feat: Add logging interfaces and corresponding tests

- Created Configurable interface for managing configuration settings.
- Created Loggable interface to define logging methods for various log levels.
- Created ContextAware interface for managing context information in logs.
- Created FormatterAware interface for handling log formatter settings.
- Created HandlerAware interface for managing log handlers.
- Created ProcessorAware interface for managing log processors.
- Created LoggingManager interface that combines various logging functionalities.
- Created LogFormatter interface for defining log formatters.
- Created LogHandler interface for handling log records.
- Created LogLevel interface for defining log levels.
- Created LogProcessor interface for processing log records before handling.
- Created LogRotator interface for managing log file rotation.

- Added unit tests for each interface to ensure correct functionality:
  - ConfigurableTest: Tests for setConfig and getConfig methods.
  - LoggableTest: Tests for various logging level methods.
  - ContextAwareTest: Tests for withContext and getContext methods.
  - FormatterAwareTest: Tests for setFormatter and getFormatter methods.
  - HandlerAwareTest: Tests for addHandler, pushHandler, popHandler, and getHandlers methods.
  - ProcessorAwareTest: Tests for addProcessor and getProcessors methods.
  - LoggingManagerTest: Comprehensive tests for all LoggingManager methods.
  - LogFormatterTest: Test for the format method.
  - LogHandlerTest: Test for the handle method.
  - LogLevelTest: Test for the getLevel method.
  - LogProcessorTest: Test for the process method.
  - LogRotatorTest: Test for the rotate method.

* feat: Update logging interfaces Add tests for LoggerAware and LoggerConfigurable interfaces

- Revised and enhanced logging interfaces for better consistency and flexibility.
- Implemented new methods to support asynchronous logging.
- Improved documentation of the interfaces to facilitate integration.
- Added unit tests to ensure the robustness of the new implementations.
- Added unit test for LoggerAware interface to verify setLogger method.
- Added unit test for LoggerConfigurable interface to verify configure method.
- Ensured proper mock setup and expectations in tests.

* feat(logging): improve log rotation and update log handler

- Removed .phpcs-cache for cleaner repository
- Updated src/Logging/LogHandler.php to enhance log handling capabilities
- Modified src/Logging/LogLevel.php for better log level management
- Enhanced src/Logging/LogRotator.php with improved file rotation logic
- Updated src/Logging/Logger.php to integrate changes in log handling and rotation

* Refactor:Indexable interface and LogLevel class

- Modified the Indexable.php interface to enhance functionality.
- Updated the LogLevel.php class to add new log levels.
- Made lint adjustments in LogRotator class.

* feat(contract): Add Processor interfaces and tests

- Introduce new interfaces: Processor, ConfigurableProcessor, Pipeline
- Add comprehensive PHPUnit tests for each interface
- Enhance code documentation with detailed PHP DocBlocks
- Ensure consistency with existing KaririCode coding standards

* feat: add ProcessorRegistry interface and unit tests

- Introduced `ProcessorRegistry` interface to standardize processor registration and retrieval across contexts.
- Added `ProcessorRegistryTest` class to ensure correctness of the new interface, covering scenarios like processor registration, retrieval, and error handling.

* feat(processor): add ProcessorBuilder interface and test suite

- Add ProcessorBuilder interface in KaririCode\Contract\Processor namespace
  - Define build() method for constructing individual processors
  - Define buildPipeline() method for assembling processor pipelines

- Create ProcessorBuilderTest class in KaririCode\Contract\Tests\Processor namespace
  - Implement tests for build() and buildPipeline() methods
  - Cover success scenarios and exception handling
  - Ensure proper interaction with ProcessorRegistry

* feat(contract): add PHPDoc for ProcessableAttribute interface and create unit tests

- Add PHPDoc comments for ProcessableAttribute interface, including method descriptions and author/license information
- Create unit tests for ProcessableAttribute interface, testing `getProcessors` and `getFallbackValue` methods

* feat(contract): add Sanitizer, Serializer, and Validator interfaces with unit tests

- Add `Sanitizer` interface for sanitizing input data in `src/Sanitizer/`
- Add `Validator` interface for validating input data in `src/Validator/`
- Add `Serializer` interface for serializing and deserializing data in `src/Serializer/`
- Create unit tests for each interface to ensure expected behavior

* fix(validator): correct return type of Validator interface

* feat(contract): add CustomizableMessageAttribute interface

- Introduce CustomizableMessageAttribute interface in KaririCode\Contract\Processor\Attribute namespace
- Add method getMessage(string $validatorName): ?string to the interface
- Create unit tests for CustomizableMessageAttribute in CustomizableMessageAttributeTest
- Update existing ProcessableAttribute interface documentation for consistency

* feat: add BaseProcessorAttribute abstract class

* refactor: adjusty filterValidProcessors in BaseProcessorAttribute

* feat(processor): add ProcessorValidator and ValidatableProcessor interfaces with unit tests

- Added ProcessorValidator interface to define contract for validating processors in a pipeline.
- Added ValidatableProcessor interface to define contract for processors with validation capabilities.
- Created unit tests for ProcessorValidator and ValidatableProcessor to ensure proper validation behavior.

* feat(validator): Add reset method to ValidatableProcessor interface

The reset method is added to ensure proper state reset between validations.
This change helps prevent state leakage between multiple validation cycles
by allowing processors to clear their validation state before reuse.

- Add reset() method with proper PHPDoc
- Maintain consistent documentation style
- Keep backward compatibility with existing implementations

* feat(validator): Add reset method to ValidatableProcessor interface

The reset method is added to ensure proper state reset between validations.
This change helps prevent state leakage between multiple validation cycles
by allowing processors to clear their validation state before reuse.

- Add reset() method with proper PHPDoc
- Maintain consistent documentation style
- Keep backward compatibility with existing implementations

* test(processor): add unit tests for ProcessingResult interface

- Add test cases for all ProcessingResult interface methods
- Include setUp with mock creation
- Validate error handling and data processing
- Ensure proper type declarations

* refactor: add professional comments to BaseProcessorAttribute and update register return in ProcessorRegistry

- Change `register` method in `ProcessorRegistry` interface to return `self` instead of `void` for fluent interface support
- Add professional comments to `BaseProcessorAttribute` abstract class, clarifying property roles and method responsibilities
- Document `filterValidProcessors` and other methods for clearer functionality understanding

* feat: add Transformer interface and initial test

- Created `Transformer` interface in `src/Contract/Transformer/Transformer.php`:
  - Defines the `transform` method for transforming input data, ensuring consistent implementation across transformers.

- Added `TransformerTest` in `tests/Contract/Transformer/TransformerTest.php`:
  - Includes a test for the `transform` method using a mock object.
  - Verifies that the method is called correctly and returns the expected output.

* feat: extend Container with resolve, bind, and singleton methods

test: enhance Container unit tests for clarity and conciseness

* feat(di): standardize interface docs and add unit tests

- Standardize PHPDoc comments across all DI interfaces
- Complete Container interface tests
- Add unit tests for Definition, Provider and Compiler interfaces
- Ensure consistent documentation style and test coverage

---------

Co-authored-by: GrowthCode <142913591+growthcodeoficial@users.noreply.github.com>

Author: walmir-silva

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;
+}

src/DependencyInjection/Container.php

@@ -0,0 +1,96 @@
+<?php
+
+declare(strict_types=1);
+
+namespace KaririCode\Contract\Tests\DI;
+
+use KaririCode\Contract\DI\Compiler;
+use KaririCode\Contract\DI\Container;
+use PHPUnit\Framework\MockObject\MockObject;
+use PHPUnit\Framework\TestCase;
+
+final class CompilerTest extends TestCase
+{
+    private Compiler|MockObject $compiler;
+    private Container|MockObject $container;
+
+    protected function setUp(): void
+    {
+        $this->compiler = $this->createMock(Compiler::class);
+        $this->container = $this->createMock(Container::class);
+    }
+
+    public function testCompile(): void
+    {
+        $compiledContainer = $this->createMock(Container::class);
+
+        $this->compiler->expects($this->once())
+            ->method('compile')
+            ->with($this->container)
+            ->willReturn($compiledContainer);
+
+        $result = $this->compiler->compile($this->container);
+
+        $this->assertInstanceOf(Container::class, $result);
+        $this->assertSame($compiledContainer, $result);
+    }
+
+    public function testWriteToFile(): void
+    {
+        $path = '/path/to/compiled/container.php';
+
+        $this->compiler->expects($this->once())
+            ->method('writeToFile')
+            ->with($path);
+
+        $this->compiler->writeToFile($path);
+    }
+
+    public function testLoadFromFile(): void
+    {
+        $path = '/path/to/compiled/container.php';
+        $loadedContainer = $this->createMock(Container::class);
+
+        $this->compiler->expects($this->once())
+            ->method('loadFromFile')
+            ->with($path)
+            ->willReturn($loadedContainer);
+
+        $result = $this->compiler->loadFromFile($path);
+
+        $this->assertInstanceOf(Container::class, $result);
+        $this->assertSame($loadedContainer, $result);
+    }
+
+    public function testCompileAndWriteWorkflow(): void
+    {
+        $compiledContainer = $this->createMock(Container::class);
+        $path = '/path/to/compiled/container.php';
+
+        // Usando um array para rastrear a ordem das chamadas
+        $callOrder = [];
+
+        $this->compiler->expects($this->once())
+            ->method('compile')
+            ->with($this->container)
+            ->willReturnCallback(function () use ($compiledContainer, &$callOrder) {
+                $callOrder[] = 'compile';
+
+                return $compiledContainer;
+            });
+
+        $this->compiler->expects($this->once())
+            ->method('writeToFile')
+            ->with($path)
+            ->willReturnCallback(function () use (&$callOrder) {
+                $callOrder[] = 'writeToFile';
+            });
+
+        $result = $this->compiler->compile($this->container);
+        $this->compiler->writeToFile($path);
+
+        // Verifica se os métodos foram chamados na ordem correta
+        $this->assertEquals(['compile', 'writeToFile'], $callOrder);
+        $this->assertSame($compiledContainer, $result);
+    }
+}