Add logging interfaces and corresponding tests (#19)

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

Author: walmir-silva

src/ImmutableValue.php

@@ -0,0 +1,22 @@
+<?php
+
+declare(strict_types=1);
+
+namespace KaririCode\Contract;
+
+/**
+ * ImmutableValue interface.
+ *
+ * This interface is used to mark a class as an immutable value object.
+ *
+ * @category  Logging
+ *
+ * @author    Walmir Silva <walmir.silva@kariricode.org>
+ * @license   MIT
+ *
+ * @see       https://kariricode.org/
+ */
+interface ImmutableValue
+{
+    // No methods needed; this interface serves as a marker.
+}

src/Logging/Behavioral/Configurable.php

@@ -0,0 +1,46 @@
+<?php
+
+declare(strict_types=1);
+
+namespace KaririCode\Contract\Logging\Behavioral;
+
+use KaririCode\Contract\ImmutableValue;
+
+/**
+ * Configurable interface.
+ *
+ * This interface defines methods for managing configuration.
+ * Configuration settings can affect the behavior of logging.
+ *
+ * Obs.:
+ * ```
+ * class LoggerConfig implements ImmutableValue {
+ *     // Implementation details
+ * }
+ * ```
+ *
+ * @category  Logging
+ *
+ * @author    Walmir Silva <walmir.silva@kariricode.org>
+ * @license   MIT
+ *
+ * @see       https://kariricode.org/
+ */
+interface Configurable
+{
+    /**
+     * Retrieves the current configuration.
+     *
+     * @return ImmutableValue the current configuration object
+     */
+    public function getConfig(): ImmutableValue;
+
+    /**
+     * Sets a new configuration.
+     *
+     * @param ImmutableValue $config the new configuration object
+     *
+     * @return Configurable the current instance for method chaining
+     */
+    public function setConfig(ImmutableValue $config): Configurable;
+}

src/Logging/Behavioral/Loggable.php

@@ -0,0 +1,96 @@
+<?php
+
+declare(strict_types=1);
+
+namespace KaririCode\Contract\Logging\Behavioral;
+
+use KaririCode\Contract\Logging\LogLevel;
+
+/**
+ * Loggable interface.
+ *
+ * This interface defines the logging methods for various log levels.
+ * Implementers can log messages at different severity levels.
+ *
+ * @category  Logging
+ *
+ * @author    Walmir Silva <walmir.silva@kariricode.org>
+ * @license   MIT
+ *
+ * @see       https://kariricode.org/
+ */
+interface Loggable
+{
+    /**
+     * Logs with an arbitrary level.
+     *
+     * @param LogLevel $level the log level
+     * @param string|\Stringable $message the log message
+     * @param array $context additional context for the log message
+     */
+    public function log(LogLevel $level, string|\Stringable $message, array $context = []): void;
+
+    /**
+     * Logs a debug message.
+     *
+     * @param string|\Stringable $message the log message
+     * @param array $context additional context for the log message
+     */
+    public function debug(string|\Stringable $message, array $context = []): void;
+
+    /**
+     * Logs an info message.
+     *
+     * @param string|\Stringable $message the log message
+     * @param array $context additional context for the log message
+     */
+    public function info(string|\Stringable $message, array $context = []): void;
+
+    /**
+     * Logs a notice message.
+     *
+     * @param string|\Stringable $message the log message
+     * @param array $context additional context for the log message
+     */
+    public function notice(string|\Stringable $message, array $context = []): void;
+
+    /**
+     * Logs a warning message.
+     *
+     * @param string|\Stringable $message the log message
+     * @param array $context additional context for the log message
+     */
+    public function warning(string|\Stringable $message, array $context = []): void;
+
+    /**
+     * Logs an error message.
+     *
+     * @param string|\Stringable $message the log message
+     * @param array $context additional context for the log message
+     */
+    public function error(string|\Stringable $message, array $context = []): void;
+
+    /**
+     * Logs a critical message.
+     *
+     * @param string|\Stringable $message the log message
+     * @param array $context additional context for the log message
+     */
+    public function critical(string|\Stringable $message, array $context = []): void;
+
+    /**
+     * Logs an alert message.
+     *
+     * @param string|\Stringable $message the log message
+     * @param array $context additional context for the log message
+     */
+    public function alert(string|\Stringable $message, array $context = []): void;
+
+    /**
+     * Logs an emergency message.
+     *
+     * @param string|\Stringable $message the log message
+     * @param array $context additional context for the log message
+     */
+    public function emergency(string|\Stringable $message, array $context = []): void;
+}

src/Logging/LogFormatter.php

@@ -0,0 +1,34 @@
+<?php
+
+declare(strict_types=1);
+
+namespace KaririCode\Contract\Logging;
+
+use KaririCode\Contract\ImmutableValue;
+
+/**
+ * Interface Formatter.
+ *
+ * Defines the contract for log formatters.
+ * Log formatters are responsible for formatting log records into a specific string format.
+ *
+ * @category  Logging
+ *
+ * @author    Walmir Silva <walmir.silva@kariricode.org>
+ * @license   MIT
+ *
+ * @see       https://kariricode.org/
+ */
+interface LogFormatter
+{
+    /**
+     * Formats a log record.
+     *
+     * This method is responsible for formatting the log record into a specific string format.
+     *
+     * @param ImmutableValue $record the log record to be formatted
+     *
+     * @return string the formatted log record as a string
+     */
+    public function format(ImmutableValue $record): string;
+}

src/Logging/LogHandler.php

@@ -0,0 +1,37 @@
+<?php
+
+declare(strict_types=1);
+
+namespace KaririCode\Contract\Logging;
+
+use KaririCode\Contract\ImmutableValue;
+
+/**
+ * Interface LogHandler.
+ *
+ * Defines the contract for log handlers.
+ * Log handlers are responsible for processing log records and implementing specific
+ * logging behavior, such as writing log entries to files, sending them to remote servers,
+ * or displaying them on the console.
+ *
+ * Implementations of this interface should focus on the `handle` method, which
+ * processes a single log record represented as an array.
+ *
+ * @category  Logging
+ *
+ * @license   MIT License
+ *
+ * @see      https://kariricode.org/
+ */
+interface LogHandler
+{
+    /**
+     * Processes a log record.
+     *
+     * This method is responsible for handling the log record, performing tasks such as
+     * writing it to a file, sending it over the network, or any other logging behavior.
+     *
+     * @param array $record the log record to be processed, represented as an associative array
+     */
+    public function handle(ImmutableValue $record): void;
+}

src/Logging/LogLevel.php

@@ -0,0 +1,28 @@
+<?php
+
+declare(strict_types=1);
+
+namespace KaririCode\Contract\Logging;
+
+/**
+ * Interface LogLevel.
+ *
+ * Defines the contract for log levels.
+ * Log levels indicate the severity or importance of a log record.
+ *
+ * @category  Logging
+ *
+ * @author    Walmir Silva <walmir.silva@kariricode.org>
+ * @license   MIT
+ *
+ * @see       https://kariricode.org/
+ */
+interface LogLevel
+{
+    /**
+     * Gets the log level as a string.
+     *
+     * @return string the log level
+     */
+    public function getLevel(): string;
+}

src/Logging/LogProcessor.php

@@ -0,0 +1,36 @@
+<?php
+
+declare(strict_types=1);
+
+namespace KaririCode\Contract\Logging;
+
+/**
+ * Interface LogProcessor.
+ *
+ * Defines the contract for log processors.
+ * Log processors are responsible for processing log records before they are handled.
+ * This can include adding additional information, modifying existing information,
+ * or filtering out certain log records.
+ *
+ * @category  Logging
+ *
+ * @author    Walmir Silva <walmir.silva@kariricode.org>
+ * @license   MIT
+ *
+ * @see       https://kariricode.org/
+ */
+interface LogProcessor
+{
+    /**
+     * Processes a log record.
+     *
+     * This method is responsible for processing the log record, performing tasks such as
+     * adding additional information, modifying existing information, or filtering out
+     * certain log records.
+     *
+     * @param array $record the log record to be processed, represented as an associative array
+     *
+     * @return array the processed log record
+     */
+    public function process(array $record): array;
+}

src/Logging/LogRotator.php

@@ -0,0 +1,32 @@
+<?php
+
+declare(strict_types=1);
+
+namespace KaririCode\Contract\Logging;
+
+/**
+ * Interface Rotator.
+ *
+ * Defines the contract for log rotators.
+ * Log rotators are responsible for rotating log files, ensuring that logs do not
+ * grow indefinitely and are managed efficiently.
+ *
+ * @category  Logging
+ *
+ * @author    Walmir Silva <walmir.silva@kariricode.org>
+ * @license   MIT
+ *
+ * @see       https://kariricode.org/
+ */
+interface LogRotator
+{
+    /**
+     * Rotates a log file.
+     *
+     * This method is responsible for rotating the specified log file, such as renaming
+     * it and creating a new file for future log entries.
+     *
+     * @param string $filename the name of the log file to be rotated
+     */
+    public function rotate(string $filename): void;
+}

src/Logging/LoggingManager.php

@@ -0,0 +1,42 @@
+<?php
+
+declare(strict_types=1);
+
+namespace KaririCode\Contract\Logging;
+
+use KaririCode\Contract\Logging\Behavioral\Configurable;
+use KaririCode\Contract\Logging\Behavioral\Loggable;
+use KaririCode\Contract\Logging\Structural\ContextAware;
+use KaririCode\Contract\Logging\Structural\FormatterAware;
+use KaririCode\Contract\Logging\Structural\HandlerAware;
+use KaririCode\Contract\Logging\Structural\ProcessorAware;
+
+/**
+ * Interface LoggingManager.
+ *
+ * Combines various logging functionalities, including logging methods, handler management,
+ * processor management, formatter management, context management, and configuration.
+ * This interface serves as a comprehensive manager for all aspects of logging.
+ *
+ * @category  Logging
+ *
+ * @author    Walmir Silva <walmir.silva@kariricode.org>
+ * @license   MIT
+ *
+ * @see       https://kariricode.org/
+ */
+interface LoggingManager extends
+    Loggable,
+    HandlerAware,
+    ProcessorAware,
+    FormatterAware,
+    ContextAware,
+    Configurable
+{
+    /**
+     * Gets the name of the logger.
+     *
+     * @return string the name of the logger
+     */
+    public function getName(): string;
+}