feat: Create Container interface and add unit tests (#18)

walmir-silva · web-flow · commit 5a6cc89fc23f · 2024-07-05T11:00:50.000-03:00
* 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
diff --git a/src/DataStructure/Behavioral/Comparable.php b/src/DataStructure/Behavioral/Comparable.php
@@ -9,7 +9,7 @@
  *
  * Defines the contract for objects that can be compared.
  *
- * @category  Interfaces
+ * @category  DataStructure\Behavioral
  *
  * @author    Walmir Silva <walmir.silva@kariricode.org>
  * @license   MIT
diff --git a/src/DataStructure/Behavioral/Countable.php b/src/DataStructure/Behavioral/Countable.php
@@ -9,7 +9,7 @@
  *
  * Defines the contract for counting elements.
  *
- * @category  Interfaces
+ * @category  DataStructure\Behavioral
  *
  * @author    Walmir Silva <walmir.silva@kariricode.org>
  * @license   MIT
diff --git a/src/DataStructure/Behavioral/Indexable.php b/src/DataStructure/Behavioral/Indexable.php
@@ -9,7 +9,7 @@
  *
  * Defines the contract for indexed access to elements.
  *
- * @category  Interfaces
+ * @category  DataStructure\Behavioral
  *
  * @author    Walmir Silva <walmir.silva@kariricode.org>
  * @license   MIT
diff --git a/src/DataStructure/Behavioral/IterableCollection.php b/src/DataStructure/Behavioral/IterableCollection.php
@@ -9,7 +9,7 @@
  *
  * Provides the ability to iterate over a collection.
  *
- * @category  Interfaces
+ * @category  DataStructure\Behavioral
  *
  * @author    Walmir Silva <walmir.silva@kariricode.org>
  * @license   MIT
diff --git a/src/DataStructure/Behavioral/Iterator.php b/src/DataStructure/Behavioral/Iterator.php
@@ -9,7 +9,7 @@
  *
  * Defines the contract for iterating over a collection of elements.
  *
- * @category  Interfaces
+ * @category  DataStructure\Behavioral
  *
  * @author    Walmir Silva <walmir.silva@kariricode.org>
  * @license   MIT
diff --git a/src/DataStructure/Behavioral/Modifiable.php b/src/DataStructure/Behavioral/Modifiable.php
@@ -9,7 +9,7 @@
  *
  * Defines the contract for modifying elements in a collection.
  *
- * @category  Interfaces
+ * @category  DataStructure\Behavioral
  *
  * @author    Walmir Silva <walmir.silva@kariricode.org>
  * @license   MIT
diff --git a/src/DataStructure/Behavioral/Searchable.php b/src/DataStructure/Behavioral/Searchable.php
@@ -9,7 +9,7 @@
  *
  * Defines the contract for searching elements in a collection.
  *
- * @category  Interfaces
+ * @category  DataStructure\Behavioral
  *
  * @author    Walmir Silva <walmir.silva@kariricode.org>
  * @license   MIT
diff --git a/src/DataStructure/Behavioral/Sortable.php b/src/DataStructure/Behavioral/Sortable.php
@@ -11,7 +11,7 @@
  * Classes implementing this interface should provide an implementation
  * for the sort method to allow sorting of their elements.
  *
- * @category  Interfaces
+ * @category  DataStructure\Behavioral
  *
  * @author    Walmir Silva <walmir.silva@kariricode.org>
  * @license   MIT
diff --git a/src/DataStructure/Deque.php b/src/DataStructure/Deque.php
@@ -10,7 +10,7 @@
  * Extends the Queue interface to define the contract for double-ended queue data structures,
  * which allow elements to be added and removed from both ends.
  *
- * @category  Interfaces
+ * @category  DataStructure
  *
  * @author    Walmir Silva <walmir.silva@kariricode.org>
  * @license   MIT
diff --git a/src/DataStructure/Heap.php b/src/DataStructure/Heap.php
@@ -10,7 +10,7 @@
  * Defines the contract for heap data structures.
  * A heap is a specialized tree-based data structure that satisfies the heap property.
  *
- * @category  Interfaces
+ * @category  DataStructure
  *
  * @author    Walmir Silva <walmir.silva@kariricode.org>
  * @license   MIT
diff --git a/src/DataStructure/Map.php b/src/DataStructure/Map.php
@@ -12,7 +12,7 @@
  *
  * Defines the contract for map data structures, which store key-value pairs.
  *
- * @category  Interfaces
+ * @category  DataStructure
  *
  * @author    Walmir Silva <walmir.silva@kariricode.org>
  * @license   MIT
diff --git a/src/DataStructure/Queue.php b/src/DataStructure/Queue.php
@@ -11,7 +11,7 @@
  *
  * Defines the contract for queue data structures, which follow the FIFO (First-In-First-Out) principle.
  *
- * @category  Interfaces
+ * @category  DataStructure
  *
  * @author    Walmir Silva <walmir.silva@kariricode.org>
  * @license   MIT
diff --git a/src/DataStructure/Set.php b/src/DataStructure/Set.php
@@ -12,7 +12,7 @@
  *
  * Defines the contract for set data structures, which do not allow duplicate elements.
  *
- * @category  Interfaces
+ * @category  DataStructure
  *
  * @author    Walmir Silva <walmir.silva@kariricode.org>
  * @license   MIT
diff --git a/src/DataStructure/Stack.php b/src/DataStructure/Stack.php
@@ -9,7 +9,7 @@
  *
  * Defines the contract for stack data structures, which follow the LIFO (Last-In-First-Out) principle.
  *
- * @category  Interfaces
+ * @category  DataStructure
  *
  * @author    Walmir Silva <walmir.silva@kariricode.org>
  * @license   MIT
diff --git a/src/DataStructure/Structural/BPlusTreeCollection.php b/src/DataStructure/Structural/BPlusTreeCollection.php
@@ -12,7 +12,7 @@
  *
  * Defines the contract for B+ Tree data structures.
  *
- * @category  Interfaces
+ * @category  DataStructure\Structural
  *
  * @author    Walmir Silva <walmir.silva@kariricode.org>
  * @license   MIT
diff --git a/src/DataStructure/Structural/Collection.php b/src/DataStructure/Structural/Collection.php
@@ -14,7 +14,7 @@
  *
  * Defines the contract for a collection of elements.
  *
- * @category  Interfaces
+ * @category  DataStructure\Structural
  *
  * @author    Walmir Silva <walmir.silva@kariricode.org>
  * @license   MIT
diff --git a/src/DataStructure/Tree.php b/src/DataStructure/Tree.php
@@ -12,7 +12,7 @@
  *
  * Defines the contract for tree data structures.
  *
- * @category  Interfaces
+ * @category  DataStructure
  *
  * @author    Walmir Silva <walmir.silva@kariricode.org>
  * @license   MIT
diff --git a/src/DependencyInjection/Container.php b/src/DependencyInjection/Container.php
@@ -0,0 +1,46 @@
+<?php
+
+declare(strict_types=1);
+
+namespace KaririCode\Contract\DependencyInjection;
+
+/**
+ * Interface ContainerInterface.
+ *
+ * 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>
+ * @license   MIT
+ *
+ * @see       https://kariricode.org/
+ */
+interface Container
+{
+    /**
+     * Registers a service with the container.
+     *
+     * @param string $id identifier of the service to register
+     * @param callable $service a 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;
+}
diff --git a/tests/DependencyInjection/ContainerTest.php b/tests/DependencyInjection/ContainerTest.php
@@ -0,0 +1,43 @@
+<?php
+
+declare(strict_types=1);
+
+namespace KaririCode\Contract\Tests\DependencyInjection;
+
+use KaririCode\Contract\DependencyInjection\Container;
+use PHPUnit\Framework\TestCase;
+
+final class ContainerTest extends TestCase
+{
+    public function testSet(): void
+    {
+        $mock = $this->createMock(Container::class);
+        $mock->expects($this->once())
+            ->method('set')
+            ->with($this->equalTo('service.id'), $this->isType('callable'));
+
+        $mock->set('service.id', function () {
+            return new \stdClass();
+        });
+    }
+
+    public function testGet(): void
+    {
+        $mock = $this->createMock(Container::class);
+        $mock->method('get')
+            ->with('service.id')
+            ->willReturn(new \stdClass());
+
+        $this->assertInstanceOf(\stdClass::class, $mock->get('service.id'));
+    }
+
+    public function testHas(): void
+    {
+        $mock = $this->createMock(Container::class);
+        $mock->method('has')
+            ->with('service.id')
+            ->willReturn(true);
+
+        $this->assertTrue($mock->has('service.id'));
+    }
+}

Original file line number	Diff line number	Diff line change
`@@ -9,7 +9,7 @@`
`9`	`9`	`*`
`10`	`10`	`* Defines the contract for objects that can be compared.`
`11`	`11`	`*`
`12`		`- * @category Interfaces`
	`12`	`+ * @category DataStructure\Behavioral`
`13`	`13`	`*`
`14`	`14`	`* @author Walmir Silva <walmir.silva@kariricode.org>`
`15`	`15`	`* @license MIT`
Original file line number	Diff line number	Diff line change
`@@ -11,7 +11,7 @@`
`11`	`11`	`* Classes implementing this interface should provide an implementation`
`12`	`12`	`* for the sort method to allow sorting of their elements.`
`13`	`13`	`*`
`14`		`- * @category Interfaces`
	`14`	`+ * @category DataStructure\Behavioral`
`15`	`15`	`*`
`16`	`16`	`* @author Walmir Silva <walmir.silva@kariricode.org>`
`17`	`17`	`* @license MIT`
Original file line number	Diff line number	Diff line change
`@@ -10,7 +10,7 @@`
`10`	`10`	`* Extends the Queue interface to define the contract for double-ended queue data structures,`
`11`	`11`	`* which allow elements to be added and removed from both ends.`
`12`	`12`	`*`
`13`		`- * @category Interfaces`
	`13`	`+ * @category DataStructure`
`14`	`14`	`*`
`15`	`15`	`* @author Walmir Silva <walmir.silva@kariricode.org>`
`16`	`16`	`* @license MIT`