add Transformer interface (#36)

* 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.

---------

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

Author: walmir-silva

src/Transformer/Transformer.php

@@ -0,0 +1,29 @@
+<?php
+
+declare(strict_types=1);
+
+namespace KaririCode\Contract\Transformer;
+
+/**
+ * Interface Transformer.
+ *
+ * Defines the contract for a transformer that can transform input data.
+ *
+ * @category  Transformer
+ *
+ * @author    Walmir Silva <walmir.silva@kariricode.org>
+ * @license   MIT
+ *
+ * @see       https://kariricode.org/
+ */
+interface Transformer
+{
+    /**
+     * Transforms the provided object using registered transformers.
+     *
+     * @param mixed $object The object to be transformed
+     *
+     * @return mixed The result of the transformation process
+     */
+    public function transform(mixed $object): mixed;
+}

tests/Transformer/TransformerTest.php

@@ -0,0 +1,24 @@
+<?php
+
+declare(strict_types=1);
+
+namespace KaririCode\Contract\Tests\Transformer;
+
+use KaririCode\Contract\Transformer\Transformer;
+use PHPUnit\Framework\MockObject\MockObject;
+use PHPUnit\Framework\TestCase;
+
+final class TransformerTest extends TestCase
+{
+    public function testTransform(): void
+    {
+        /** @var Transformer|MockObject */
+        $transformer = $this->createMock(Transformer::class);
+        $transformer->expects($this->once())
+            ->method('transform')
+            ->with('sampleInput')
+            ->willReturn('transformedOutput');
+
+        $this->assertEquals('transformedOutput', $transformer->transform('sampleInput'));
+    }
+}