Refactor/Update namespaces and interfaces for clarity and consistency

Author: othercodes

.github/workflows/test.yml

@@ -8,11 +8,12 @@ on:
 
 jobs:
   test:
+    name: Test on PHP ${{ matrix.php-version }}
     runs-on: ubuntu-latest
 
     strategy:
       matrix:
-        php-version: [ '8.1', '8.2', '8.3' ]
+        php-version: [ '8.2', '8.3', '8.4' ]
 
     steps:
       - name: Checkout source code
@@ -28,7 +29,7 @@ jobs:
           tools: composer:v2
 
       - name: Cache dependencies
-        uses: actions/cache@v2
+        uses: actions/cache@v4.3.0
         with:
           path: ~/.composer/cache
           key: php-${{ matrix.php-version }}-composer-${{ hashFiles('**/composer.json') }}
@@ -37,9 +38,15 @@ jobs:
       - name: Validate composer.json and composer.lock
         run: composer validate
 
-      - name: Install dependencies
+      - name: Install Dependencies
         if: steps.composer-cache.outputs.cache-hit != 'true'
-        run: composer install --prefer-dist --no-progress --no-suggest
+        run: composer install --prefer-dist --no-progress
+
+      - name: Check Code Style
+        run: composer pint-test
 
       - name: Execute Static Code analysis
-        run: composer analyse
+        run: composer analyse
+
+      - name: Execute Unit, Integration and Acceptance Tests
+        run: composer test

.gitignore

@@ -1,8 +1,14 @@
 composer.phar
 /vendor/
 .idea/
-/infrastructure
+/infrastructure/
+/coverage/
 *[N|n]o[G|g]it*
-*coverage*
+coverage.xml
+test.xml
 .phpunit.result.cache
 composer.lock
+wiki/Home.md
+/.phpunit.cache
+.phpactor.json
+/.serena/

README.md

@@ -20,27 +20,48 @@ Domain event interfaces following ISP (Interface Segregation Principle):
 - **Event** - Base domain event (eventId, eventName, payload, occurredOn)
 - **Traceable** - Distributed tracing (correlationId, causationId)
 - **Sourceable** - Event sourcing (aggregateId, aggregateType, eventVersion)
+- **EventBus** - Publishes domain events
 
 ## Application Layer
 
 ### Command
 Write operations (CQRS):
 - **Command** - Marker interface for state-changing operations
+- **CommandBus** - Dispatches commands to handlers
+- **CommandHandler** - Executes commands
 
 ### Query
 Read operations (CQRS):
 - **Query** - Marker interface for data retrieval
 - **QueryResponse** - Marker interface for query results
+- **QueryBus** - Routes queries to handlers
+- **QueryHandler** - Executes queries and returns responses
 
 ### Handler
-Message handlers:
-- **CommandHandler** - Executes commands
-- **QueryHandler** - Executes queries and returns responses
+Event handlers:
 - **EventHandler** - Reacts to domain events
 
-### Messaging
-Message bus implementations:
-- **CommandBus** - Dispatches commands
-- **QueryBus** - Asks queries
-- **EventBus** - Publishes events
-- **ServiceBus** - Unified bus facade
+### Service Bus
+Unified message bus facade:
+- **ServiceBus** - Provides access to CommandBus, QueryBus, and EventBus
+
+## Architecture
+
+This library follows Clean Architecture principles with explicit layer separation:
+- **Domain → Application** - Domain layer is independent, Application depends on Domain
+- **Layer-Explicit Namespaces** - Clear architectural boundaries in namespace structure
+- **Interface Segregation** - Compose only needed capabilities (e.g., Event + Traceable + Sourceable)
+
+### Architecture Testing
+
+The project includes automated architecture tests using Pest PHP:
+
+```bash
+composer test
+```
+
+Tests enforce:
+- Domain layer independence (no Application dependencies)
+- Correct interface placement and usage
+- Clean Architecture dependency rules
+- PHP and security best practices (via arch presets)

composer.json

@@ -11,24 +11,29 @@
   ],
   "minimum-stability": "stable",
   "require": {
-    "php": "^8.1"
+    "php": "^8.2"
   },
   "require-dev": {
     "phpstan/phpstan": "^1.0",
     "phpstan/extension-installer": "^1.3",
-    "laravel/pint": "^1.25"
+    "laravel/pint": "^1.25",
+    "pestphp/pest": "^3.8.4",
+    "pestphp/pest-plugin-arch": "^3.1.1"
   },
   "autoload": {
     "psr-4": {
       "ComplexHeart\\": "src/"
     }
   },
   "scripts": {
-    "analyse": "vendor/bin/phpstan analyse src --no-progress --level=9",
-    "pint": "vendor/bin/pint --preset psr12"
+    "test": "vendor/bin/pest --configuration=phpunit.xml --coverage --coverage-clover=coverage.xml --log-junit=test.xml",
+    "analyse": "vendor/bin/phpstan analyse src --no-progress --memory-limit=4G --level=9",
+    "pint-test": "vendor/bin/pint --preset=psr12 --test",
+    "pint": "vendor/bin/pint --preset=psr12"
   },
   "config": {
     "allow-plugins": {
+      "pestphp/pest-plugin": true,
       "phpstan/extension-installer": true
     }
   }

phpunit.xml

@@ -0,0 +1,23 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<phpunit xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+         bootstrap="vendor/autoload.php"
+         colors="true"
+         xsi:noNamespaceSchemaLocation="https://schema.phpunit.de/10.5/phpunit.xsd"
+         cacheDirectory=".phpunit.cache">
+    <coverage>
+        <report>
+            <clover outputFile="./coverage.xml"/>
+        </report>
+    </coverage>
+    <testsuites>
+        <testsuite name="unit">
+            <directory>./tests</directory>
+        </testsuite>
+    </testsuites>
+    <logging/>
+    <source>
+        <include>
+            <directory suffix=".php">./src</directory>
+        </include>
+    </source>
+</phpunit>

src/Application/Command/Command.php

@@ -11,7 +11,6 @@
  * Commands represent the intention to change the system state.
  *
  * @author Unay Santisteban <usantisteban@othercode.io>
- * @package ComplexHeart\Application\Command
  */
 interface Command
 {

src/Application/Messaging/CommandBus.php renamed to src/Application/Command/CommandBus.php

@@ -2,22 +2,17 @@
 
 declare(strict_types=1);
 
-namespace ComplexHeart\Application\Messaging;
-
-use ComplexHeart\Application\Command\Command;
+namespace ComplexHeart\Application\Command;
 
 /**
  * Interface CommandBus
  *
  * @author Unay Santisteban <usantisteban@othercode.io>
- * @package ComplexHeart\Application\Messaging
  */
 interface CommandBus
 {
     /**
      * Dispatch the given command.
-     *
-     * @param  Command  $command
      */
     public function dispatch(Command $command): void;
 }

src/Application/Handler/CommandHandler.php

@@ -10,14 +10,11 @@
  * Interface CommandHandler
  *
  * @author Unay Santisteban <usantisteban@othercode.io>
- * @package ComplexHeart\Application\Handler
  */
 interface CommandHandler
 {
     /**
      * Handle the command execution.
-     *
-     * @param  Command  $command
      */
     public function __invoke(Command $command): void;
 }

src/Application/Handler/EventHandler.php

@@ -10,14 +10,11 @@
  * Interface EventHandler
  *
  * @author Unay Santisteban <usantisteban@othercode.io>
- * @package ComplexHeart\Application\Handler
  */
 interface EventHandler
 {
     /**
      * Handle the event execution.
-     *
-     * @param  Event  $event
      */
     public function __invoke(Event $event): void;
 }

src/Application/Handler/QueryHandler.php

@@ -11,16 +11,11 @@
  * Interface QueryHandler
  *
  * @author Unay Santisteban <usantisteban@othercode.io>
- * @package ComplexHeart\Application\Handler
  */
 interface QueryHandler
 {
     /**
      * Handle the query execution.
-     *
-     * @param  Query  $query
-     *
-     * @return QueryResponse
      */
     public function __invoke(Query $query): QueryResponse;
 }