Add Processor Interfaces and Tests to KaririCode\Contract (#23)

* 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

Author: walmir-silva

src/Logging/LogHandler.php

@@ -37,6 +37,7 @@ public function handle(ImmutableValue $record): void;
 
     /**
      * Checks whether the handler is handling the given log level.
+     *
      * @param ImmutableValue $record the log record to be processed, represented as an associative array
      */
     public function isHandling(ImmutableValue $record): bool;

src/Logging/LogRotator.php

@@ -21,6 +21,7 @@
 interface LogRotator
 {
     public function shouldRotate(string $filePath): bool;
+
     /**
      * Rotates a log file.
      *
@@ -30,5 +31,4 @@ public function shouldRotate(string $filePath): bool;
      * @param string $filename the name of the log file to be rotated
      */
     public function rotate(string $filename): void;
-
 }

src/Processor/ConfigurableProcessor.php

@@ -0,0 +1,27 @@
+<?php
+
+declare(strict_types=1);
+
+namespace KaririCode\Contract\Processor;
+
+/**
+ * Interface ConfigurableProcessor.
+ *
+ * Extends the Processor interface to allow configuration of the processor.
+ *
+ * @category  Processor
+ *
+ * @author    Walmir Silva <walmir.silva@kariricode.org>
+ * @license   MIT
+ *
+ * @see       https://kariricode.org/
+ */
+interface ConfigurableProcessor extends Processor
+{
+    /**
+     * Configures the processor with the provided options.
+     *
+     * @param array $options The configuration options
+     */
+    public function configure(array $options): void;
+}

src/Processor/Pipeline.php

@@ -0,0 +1,36 @@
+<?php
+
+declare(strict_types=1);
+
+namespace KaririCode\Contract\Processor;
+
+/**
+ * Interface Pipeline.
+ *
+ * Defines the contract for a pipeline that can execute a series of processors.
+ *
+ * @category  Processor
+ *
+ * @author    Walmir Silva <walmir.silva@kariricode.org>
+ * @license   MIT
+ *
+ * @see       https://kariricode.org/
+ */
+interface Pipeline
+{
+    /**
+     * Adds a processor to the pipeline.
+     *
+     * @param Processor $processor The processor to be added
+     */
+    public function addProcessor(Processor $processor): self;
+
+    /**
+     * Executes the processing pipeline on the provided input.
+     *
+     * @param mixed $input The value to be processed by the pipeline
+     *
+     * @return mixed The final result after passing through all processors
+     */
+    public function process(mixed $input): mixed;
+}

src/Processor/Processor.php

@@ -0,0 +1,29 @@
+<?php
+
+declare(strict_types=1);
+
+namespace KaririCode\Contract\Processor;
+
+/**
+ * Interface Processor.
+ *
+ * Defines the contract for a processor that can transform or validate input data.
+ *
+ * @category  Processor
+ *
+ * @author    Walmir Silva <walmir.silva@kariricode.org>
+ * @license   MIT
+ *
+ * @see       https://kariricode.org/
+ */
+interface Processor
+{
+    /**
+     * Processes the provided input and returns the result.
+     *
+     * @param mixed $input The value to be processed
+     *
+     * @return mixed The result of the processing
+     */
+    public function process(mixed $input): mixed;
+}

tests/Processor/ConfigurableProcessorTest.php

@@ -0,0 +1,32 @@
+<?php
+
+declare(strict_types=1);
+
+namespace KaririCode\Contract\Tests\Processor;
+
+use KaririCode\Contract\Processor\ConfigurableProcessor;
+use PHPUnit\Framework\TestCase;
+
+final class ConfigurableProcessorTest extends TestCase
+{
+    public function testConfigure(): void
+    {
+        $mock = $this->createMock(ConfigurableProcessor::class);
+        $mock->expects($this->once())
+            ->method('configure')
+            ->with(['option' => 'value']);
+
+        $mock->configure(['option' => 'value']);
+    }
+
+    public function testProcess(): void
+    {
+        $mock = $this->createMock(ConfigurableProcessor::class);
+        $mock->expects($this->once())
+            ->method('process')
+            ->with('input')
+            ->willReturn('output');
+
+        $this->assertSame('output', $mock->process('input'));
+    }
+}

tests/Processor/PipelineTest.php

@@ -0,0 +1,36 @@
+<?php
+
+declare(strict_types=1);
+
+namespace KaririCode\Contract\Tests\Processor;
+
+use KaririCode\Contract\Processor\Pipeline;
+use KaririCode\Contract\Processor\Processor;
+use PHPUnit\Framework\TestCase;
+
+final class PipelineTest extends TestCase
+{
+    public function testAddProcessor(): void
+    {
+        $mock = $this->createMock(Pipeline::class);
+        $processor = $this->createMock(Processor::class);
+
+        $mock->expects($this->once())
+            ->method('addProcessor')
+            ->with($processor)
+            ->willReturnSelf();
+
+        $this->assertSame($mock, $mock->addProcessor($processor));
+    }
+
+    public function testProcess(): void
+    {
+        $mock = $this->createMock(Pipeline::class);
+        $mock->expects($this->once())
+            ->method('process')
+            ->with('input')
+            ->willReturn('output');
+
+        $this->assertSame('output', $mock->process('input'));
+    }
+}

tests/Processor/ProcessorTest.php

@@ -0,0 +1,22 @@
+<?php
+
+declare(strict_types=1);
+
+namespace KaririCode\Contract\Tests\Processor;
+
+use KaririCode\Contract\Processor\Processor;
+use PHPUnit\Framework\TestCase;
+
+final class ProcessorTest extends TestCase
+{
+    public function testProcess(): void
+    {
+        $mock = $this->createMock(Processor::class);
+        $mock->expects($this->once())
+            ->method('process')
+            ->with('input')
+            ->willReturn('output');
+
+        $this->assertSame('output', $mock->process('input'));
+    }
+}