Update logging interfaces Add tests for LoggerAware and LoggerConfigurable interfaces (#20)

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

Author: walmir-silva

.gitignore

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

src/Logging/Behavioral/LoggerConfigurable.php

@@ -0,0 +1,26 @@
+<?php
+
+declare(strict_types=1);
+
+namespace KaririCode\Contract\Logging\Behavioral;
+
+/**
+ * LoggerConfigurable interface.
+ *
+ * This interface defines methods for managing configuration.
+ * Configuration settings can affect the behavior of logging.
+ *
+ * @category  Logging
+ *
+ * @author    Walmir Silva <walmir.silva@kariricode.org>
+ * @license   MIT
+ *
+ * @see       https://kariricode.org/
+ */
+interface LoggerConfigurable
+{
+    /**
+     * Configures the logger.
+     */
+    public function configure(array $config): void;
+}

src/Logging/LogFormatter.php

@@ -31,4 +31,13 @@ interface LogFormatter
      * @return string the formatted log record as a string
      */
     public function format(ImmutableValue $record): string;
+
+    /**
+     * Formats a set of log records.
+     *
+     * @param ImmutableValue[] $records
+     *
+     * @return string The formatted log records
+     */
+    public function formatBatch(array $records): string;
 }

src/Logging/LogHandler.php

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

src/Logging/LogProcessor.php

@@ -4,6 +4,8 @@
 
 namespace KaririCode\Contract\Logging;
 
+use KaririCode\Contract\ImmutableValue;
+
 /**
  * Interface LogProcessor.
  *
@@ -32,5 +34,5 @@ interface LogProcessor
      *
      * @return array the processed log record
      */
-    public function process(array $record): array;
+    public function process(ImmutableValue $record): ImmutableValue;
 }

src/Logging/Logger.php

@@ -0,0 +1,21 @@
+<?php
+
+declare(strict_types=1);
+
+namespace KaririCode\Contract\Logging;
+
+use KaririCode\Contract\Logging\Behavioral\Loggable;
+
+/**
+ * Interface Logger.
+ *
+ * @category  Logging
+ *
+ * @author    Walmir Silva <walmir.silva@kariricode.org>
+ * @license   MIT
+ *
+ * @see       https://kariricode.org/
+ */
+interface Logger extends Loggable
+{
+}

src/Logging/LoggerExtended.php

@@ -0,0 +1,42 @@
+<?php
+
+declare(strict_types=1);
+
+namespace KaririCode\Contract\Logging;
+
+use KaririCode\Contract\Logging\Structural\FormatterAware;
+use KaririCode\Contract\Logging\Structural\HandlerAware;
+use KaririCode\Contract\Logging\Structural\ProcessorAware;
+
+/**
+ * Interface Logger.
+ *
+ * @category  Logging
+ *
+ * @author    Walmir Silva <walmir.silva@kariricode.org>
+ * @license   MIT
+ *
+ * @see       https://kariricode.org/
+ */
+interface LoggerExtendedInterface extends Logger
+{
+    /**
+     * Adds a new handler to the logger.
+     */
+    public function addHandler(HandlerAware $handler): self;
+
+    /**
+     * Adds a new processor to the logger.
+     */
+    public function addProcessor(ProcessorAware $processor): self;
+
+    /**
+     * Sets a formatter for the logger.
+     */
+    public function setFormatter(FormatterAware $formatter): self;
+
+    /**
+     * Gets the name of the logger.
+     */
+    public function getName(): string;
+}

src/Logging/Structural/LoggerAware.php

@@ -0,0 +1,25 @@
+<?php
+
+declare(strict_types=1);
+
+namespace KaririCode\Contract\Logging\Structural;
+
+use KaririCode\Contract\Logging\Logger;
+
+/**
+ * LoggerAware interface.
+ *
+ * @category  Logging
+ *
+ * @author    Walmir Silva <walmir.silva@kariricode.org>
+ * @license   MIT
+ *
+ * @see       https://kariricode.org/
+ */
+interface LoggerAware
+{
+    /**
+     * Sets a logger instance on the object.
+     */
+    public function setLogger(Logger $logger): void;
+}

tests/Logging/Behavioral/LoggerConfigurableTest.php

@@ -0,0 +1,23 @@
+<?php
+
+declare(strict_types=1);
+
+namespace KaririCode\Contract\Tests\Logging\Behavioral;
+
+use KaririCode\Contract\Logging\Behavioral\LoggerConfigurable;
+use PHPUnit\Framework\TestCase;
+
+class LoggerConfigurableTest extends TestCase
+{
+    public function testConfigure(): void
+    {
+        $config = ['level' => 'debug', 'format' => 'json'];
+        $loggerConfigurableMock = $this->createMock(LoggerConfigurable::class);
+
+        $loggerConfigurableMock->expects($this->once())
+            ->method('configure')
+            ->with($this->equalTo($config));
+
+        $loggerConfigurableMock->configure($config);
+    }
+}

tests/Logging/LogFormatterTest.php

@@ -23,4 +23,21 @@ public function testFormat(): void
 
         $this->assertSame($formattedRecord, $formatterMock->format($recordMock));
     }
+
+    public function testFormatBatch(): void
+    {
+        $recordMock1 = $this->createMock(ImmutableValue::class);
+        $recordMock2 = $this->createMock(ImmutableValue::class);
+        $records = [$recordMock1, $recordMock2];
+        $formattedRecords = 'Formatted log records';
+
+        $formatterMock = $this->createMock(LogFormatter::class);
+
+        $formatterMock->expects($this->once())
+            ->method('formatBatch')
+            ->with($this->equalTo($records))
+            ->willReturn($formattedRecords);
+
+        $this->assertSame($formattedRecords, $formatterMock->formatBatch($records));
+    }
 }