chore: update Postgres version in test configuration from 17 to 18

Reviewed-on: #21
Co-authored-by: Ron Rise <ron@siteworxpro.com>
Co-committed-by: Ron Rise <ron@siteworxpro.com>

.gitea/workflows/tests.yml

@@ -38,7 +38,7 @@ jobs:
             -e POSTGRES_PASSWORD=postgres \
             -e POSTGRES_DB=postgres \
             -p 5432 \
-            -d postgres:17
+            -d postgres:18
           
           echo "Waiting for Postgres to start"
           sleep 10

.run/ Compose Deployment.run.xml

@@ -0,0 +1,10 @@
+<component name="ProjectRunConfigurationManager">
+  <configuration default="false" name=" Compose Deployment" type="docker-deploy" factoryName="docker-compose.yml" server-name="Docker">
+    <deployment type="docker-compose.yml">
+      <settings>
+        <option name="sourceFilePath" value="docker-compose.yml" />
+      </settings>
+    </deployment>
+    <method v="2" />
+  </configuration>
+</component>

.run/All.run.xml

@@ -0,0 +1,8 @@
+<component name="ProjectRunConfigurationManager">
+  <configuration default="false" name="All" type="ComposerRunConfigurationType" factoryName="Composer Script">
+    <option name="commandLineParameters" value="" />
+    <option name="pathToComposerJson" value="$PROJECT_DIR$/composer.json" />
+    <option name="script" value="tests:all" />
+    <method v="2" />
+  </configuration>
+</component>

.run/Lint_fix.run.xml

@@ -0,0 +1,8 @@
+<component name="ProjectRunConfigurationManager">
+  <configuration default="false" name="Lint:fix" type="ComposerRunConfigurationType" factoryName="Composer Script">
+    <option name="commandLineParameters" value="" />
+    <option name="pathToComposerJson" value="$PROJECT_DIR$/composer.json" />
+    <option name="script" value="tests:lint:fix" />
+    <method v="2" />
+  </configuration>
+</component>

.run/Main.run.xml

@@ -0,0 +1,11 @@
+<component name="ProjectRunConfigurationManager">
+  <configuration default="false" name="Main" type="PHPUnitRunConfigurationType" factoryName="PHPUnit">
+    <CommandLine>
+      <PhpTestInterpreterSettings>
+        <option name="interpreterName" value="composer-runtime" />
+      </PhpTestInterpreterSettings>
+    </CommandLine>
+    <TestRunner configuration_file="$PROJECT_DIR$/phpunit.xml" coverage_engine="PCov" scope="XML" use_alternative_configuration_file="true" />
+    <method v="2" />
+  </configuration>
+</component>

Dockerfile

@@ -14,12 +14,23 @@ RUN composer install --optimize-autoloader --ignore-platform-reqs --no-dev
 # Use the official PHP CLI image with Alpine Linux for the second stage
 FROM php:8.4.14-alpine AS php
 
+ARG KAFKA_ENABLED=0
+
 # Move the production PHP configuration file to the default location
 RUN mv /usr/local/etc/php/php.ini-production /usr/local/etc/php/php.ini \
     && apk add libpq-dev linux-headers --no-cache \
     && docker-php-ext-install pdo_pgsql sockets pcntl \
     && rm -rf /var/cache/apk/*
 
+RUN if [ "$KAFKA_ENABLED" -eq 1 ] ; then \
+        echo "Kafka support enabled" ; \
+        apk add autoconf g++ librdkafka-dev make --no-cache ; \
+        pecl install rdkafka && docker-php-ext-enable rdkafka ; \
+    else \
+        echo "Kafka support disabled" ; \
+        exit 0 ; \
+    fi
+
 # Set the working directory to /app
 WORKDIR /app
 

composer.json

@@ -21,14 +21,18 @@
     "lcobucci/jwt": "^5.6",
     "adhocore/cli": "^1.9",
     "robinvdvleuten/ulid": "^5.0",
-    "monolog/monolog": "^3.9"
+    "monolog/monolog": "^3.9",
+    "react/promise": "^3",
+    "react/async": "^4",
+    "guzzlehttp/guzzle": "^7.10"
   },
   "require-dev": {
     "phpunit/phpunit": "^12.4",
     "mockery/mockery": "^1.6",
-    "squizlabs/php_codesniffer": "^3.12",
+    "squizlabs/php_codesniffer": "^4.0",
     "lendable/composer-license-checker": "^1.2",
-    "phpstan/phpstan": "^2.1.31"
+    "phpstan/phpstan": "^2.1.31",
+    "kwn/php-rdkafka-stubs": "^2.2"
   },
   "scripts": {
     "tests:all": [

config.php

@@ -4,6 +4,10 @@ use Siteworxpro\App\Helpers\Env;
 
 return [
 
+    'app' => [
+        'log_level' => Env::get('LOG_LEVEL', 'debug'),
+    ],
+
     /**
      * The server configuration.
      */
@@ -47,7 +51,7 @@ return [
         'signing_key' => Env::get('JWT_SIGNING_KEY', 'a_super_secret_key'),
         'audience' => Env::get('JWT_AUDIENCE', 'my_audience'),
         'issuer' => Env::get('JWT_ISSUER', 'my_issuer'),
-        'strict_validation' => Env::get('JWT_STRICT_VALIDATION', true, 'bool'),
+        'strict_validation' => Env::get('JWT_STRICT_VALIDATION', false, 'bool'),
     ],
 
     'queue' => [
@@ -60,8 +64,8 @@ return [
             ],
 
             'kafka' => [
-                'brokers' => Env::get('QUEUE_KAFKA_BROKERS', 'localhost:9092'),
+                'brokers' => Env::get('QUEUE_KAFKA_BROKERS', 'kafka:9092'),
-                'topic' => Env::get('QUEUE_KAFKA_TOPIC', 'my_topic'),
+                'consumerGroup' => Env::get('QUEUE_KAFKA_CONSUMER_GROUP', 'default_group'),
             ],
 
             'rabbitmq' => [

docker-compose.yml

@@ -68,6 +68,8 @@ services:
     volumes:
       - .:/app
     build:
+      args:
+        KAFKA_ENABLED: "1"
       context: .
       dockerfile: Dockerfile
     entrypoint: "/bin/sh -c 'while true; do sleep 30; done;'"
@@ -81,12 +83,49 @@ services:
       postgres:
           condition: service_healthy
     environment:
+      JWT_ISSUER: https://auth.siteworxpro.com/application/o/postman/
+      JWT_AUDIENCE: 1RWyqJFlyA4hmsDzq6kSxs0LXvk7UgEAfgmBCpQ9
+      JWT_SIGNING_KEY: https://auth.siteworxpro.com/application/o/postman/.well-known/openid-configuration
+      QUEUE_BROKER: redis
       PHP_IDE_CONFIG: serverName=localhost
       WORKERS: 1
       DEBUG: 1
       REDIS_HOST: redis
       DB_HOST: postgres
-      JWT_SIGNING_KEY: a-string-secret-at-least-256-bits-long
+
+  ## Kafka and Zookeeper for local development
+  kafka-ui:
+    image: kafbat/kafka-ui:latest # Or kafbat/kafka-ui:latest for newer Kafka
+    container_name: kafka-ui
+    ports:
+      - "8080:8080" # Expose the UI port
+    environment:
+      KAFKA_CLUSTERS_0_NAME: local-kafka-cluster
+      KAFKA_CLUSTERS_0_BOOTSTRAPSERVERS: kafka:9092
+    depends_on:
+        kafka:
+            condition: service_started
+        zookeeper:
+            condition: service_started
+  zookeeper:
+    image: ubuntu/zookeeper:latest
+    environment:
+      ALLOW_ANONYMOUS_LOGIN: "yes"
+    ports:
+      - "2181:2181"
+  kafka:
+    image: ubuntu/kafka:latest
+    environment:
+      KAFKA_BROKER_ID: 1
+      KAFKA_LISTENERS: PLAINTEXT://kafka:9092
+      KAFKA_ADVERTISED_LISTENERS: PLAINTEXT://kafka:9092
+      KAFKA_ZOOKEEPER_CONNECT: zookeeper:2181
+      ALLOW_PLAINTEXT_LISTENER: "yes"
+    ports:
+      - "9092:9092"
+    depends_on:
+      zookeeper:
+        condition: service_started
 
   redis:
     image: redis:latest

src/Annotations/Async/HandlesMessage.php

@@ -1,24 +0,0 @@
-<?php
-
-declare(strict_types=1);
-
-namespace Siteworxpro\App\Annotations\Async;
-
-use Attribute;
-
-#[Attribute(Attribute::TARGET_CLASS | Attribute::IS_REPEATABLE)]
-readonly class HandlesMessage
-{
-    public function __construct(
-        public string $messageClass,
-    ) {
-    }
-
-    /**
-     * @return string
-     */
-    public function getMessageClass(): string
-    {
-        return $this->messageClass;
-    }
-}

src/Annotations/Events/ListensFor.php

@@ -1,15 +0,0 @@
-<?php
-
-declare(strict_types=1);
-
-namespace Siteworxpro\App\Annotations\Events;
-
-use Attribute;
-
-#[Attribute(Attribute::TARGET_CLASS | Attribute::IS_REPEATABLE)]
-readonly class ListensFor
-{
-    public function __construct(public string $eventClass)
-    {
-    }
-}

src/Annotations/Guards/Jwt.php

@@ -1,44 +0,0 @@
-<?php
-
-declare(strict_types=1);
-
-namespace Siteworxpro\App\Annotations\Guards;
-
-use Attribute;
-use Siteworxpro\App\Services\Facades\Config;
-
-#[Attribute(Attribute::TARGET_CLASS | Attribute::TARGET_METHOD)]
-readonly class Jwt
-{
-    public function __construct(
-        private string $issuer = '',
-        private string $audience = '',
-    ) {
-    }
-
-    public function getRequiredAudience(): string
-    {
-        return Config::get('jwt.audience') ?? '';
-    }
-
-    /**
-     * @return string
-     */
-    public function getAudience(): string
-    {
-        if ($this->audience === '') {
-            return Config::get('jwt.audience') ?? '';
-        }
-
-        return $this->audience;
-    }
-
-    public function getIssuer(): string
-    {
-        if ($this->issuer === '') {
-            return Config::get('jwt.issuer') ?? '';
-        }
-
-        return $this->issuer;
-    }
-}

src/Annotations/Guards/Scope.php

@@ -1,21 +0,0 @@
-<?php
-
-declare(strict_types=1);
-
-namespace Siteworxpro\App\Annotations\Guards;
-
-use Attribute;
-
-#[Attribute(Attribute::TARGET_CLASS | Attribute::TARGET_METHOD)]
-readonly class Scope
-{
-    public function __construct(
-        private array $scopes = []
-    ) {}
-
-
-    public function getScopes(): array
-    {
-        return $this->scopes;
-    }
-}

src/Async/Brokers/Kafka.php

@@ -4,33 +4,91 @@ declare(strict_types=1);
 
 namespace Siteworxpro\App\Async\Brokers;
 
+use RdKafka\Conf;
+use RdKafka\Exception;
+use RdKafka\KafkaConsumer;
+use RdKafka\Producer;
 use Siteworxpro\App\Async\Queues\Queue;
 use Siteworxpro\App\Async\Messages\Message;
 
 class Kafka extends Broker
 {
-    public function publish(Queue $queue, Message $message, ?int $delay = null): void
+    private Producer $producer;
+
+    private KafkaConsumer $consumer;
+
+    public function __construct($config = [])
     {
-        // TODO: Implement publish() method.
+        parent::__construct($config);
+
+
+        $conf = new Conf();
+        $conf->set('bootstrap.servers', $config['brokers'] ?? 'localhost:9092');
+
+        $this->producer = new Producer($conf);
+        $this->producer->addBrokers($config['brokers'] ?? 'localhost:9092');
+
+        $conf->set('group.id', $config['consumerGroup'] ?? 'default');
+        $conf->set('auto.offset.reset', 'earliest');
+        $this->consumer = new KafkaConsumer($conf);
     }
 
-    public function consume(Queue $queue): Message | null
+    public function __destruct()
     {
+        $this->producer->flush(1000);
+    }
+
+    /**
+     * @throws \Exception
+     */
+    public function publish(Queue $queue, Message $message, ?int $delay = null): void
+    {
+        $topic = $this->producer->newTopic($queue->queueName());
+        $topic->produce(RD_KAFKA_PARTITION_UA, 0, $message->serialize(), $message->getId());
+        $this->producer->flush(1000);
+    }
+
+    /**
+     * @throws Exception
+     */
+    public function consume(Queue $queue): Message|null
+    {
+        $this->consumer->subscribe([$queue->queueName()]);
+        $kafkaMessage = $this->consumer->consume(1000);
+
+        if ($kafkaMessage->err === RD_KAFKA_RESP_ERR__TIMED_OUT) {
+            return null;
+        }
+
+        if ($kafkaMessage->err === RD_KAFKA_RESP_ERR_UNKNOWN_TOPIC_OR_PART) {
+            throw new \RuntimeException(
+                "Topic '{$queue->queueName()}' or partition does not exist. Kafka does not auto-create topics" .
+                " unless configured to do so."
+            );
+        }
+
+        /** @var string | null $messageData */
+        $messageData = $kafkaMessage->payload;
+        if ($messageData !== null) {
+            /** @var Message $message */
+            $message = unserialize($messageData, ['allowed_classes' => true]);
+            $message->setId((string)$kafkaMessage->offset);
+
+            return $message;
+        }
+
         return null;
     }
 
     public function acknowledge(Queue $queue, Message $message): void
     {
-        // TODO: Implement acknowledge() method.
     }
 
     public function reject(Queue $queue, Message $message, bool $requeue = false): void
     {
-        // TODO: Implement reject() method.
     }
 
     public function purge(Queue $queue): void
     {
-        // TODO: Implement purge() method.
     }
 }

src/Async/Consumer.php

@@ -4,73 +4,97 @@ declare(ticks=1);
 
 namespace Siteworxpro\App\Async;
 
-use Siteworxpro\App\Annotations\Async\HandlesMessage;
+use Siteworxpro\App\Attributes\Async\HandlesMessage;
+use Siteworxpro\App\Async\Messages\Message;
 use Siteworxpro\App\Async\Queues\Queue;
+use Siteworxpro\App\Services\Facades\Broker;
 use Siteworxpro\App\Services\Facades\Logger;
 
+/**
+ * Long-running process that listens to queues, pops messages, and dispatches them to handlers.
+ */
 class Consumer
 {
     private static bool $shutDown = false;
 
+    /** @var array<string,string> */
     private const array QUEUES = [
-        Queues\DefaultQueue::class,
+        'default' => Queues\DefaultQueue::class,
     ];
 
+    /** @var Queue[] */
     private array $queues = [];
 
+    /** @var array<string, string[]> message FQCN => handler FQCNs */
     private array $handlers = [];
 
     private const string HANDLER_NAMESPACE = 'Siteworxpro\\App\\Async\\Handlers\\';
 
-    public function __construct()
+    /**
+     * @param string[] $queues Optional list of queue names (keys from self::QUEUES)
+     */
+    public function __construct(array $queues = [])
     {
-        foreach (self::QUEUES as $queueClass) {
+        $queueClasses = $queues === []
-            $this->queues[] = new $queueClass();
+            ? array_values(self::QUEUES)
+            : array_map(
+                static function (string $name): string {
+                    if (!isset(self::QUEUES[$name])) {
+                        throw new \InvalidArgumentException("Queue '$name' is not defined.");
+                    }
+                    return self::QUEUES[$name];
+                },
+                $queues
+            );
+
+        foreach ($queueClasses as $class) {
+            $this->queues[] = new $class();
         }
 
         $this->registerHandlers();
     }
 
+    /**
+     * Discover handler classes under `Handlers` and register them via HandlesMessage attributes.
+     */
     private function registerHandlers(): void
     {
-        $recursiveIterator = new \RecursiveIteratorIterator(
+        $it = new \RecursiveIteratorIterator(
             new \RecursiveDirectoryIterator(__DIR__ . '/Handlers/')
         );
 
-        foreach ($recursiveIterator as $file) {
+        /** @var \SplFileInfo $file */
-            if ($file->isFile() && $file->getExtension() === 'php') {
+        foreach ($it as $file) {
-                $relativePath = str_replace(__DIR__ . '/Handlers/', '', $file->getPathname());
+            if (!$file->isFile() || $file->getExtension() !== 'php') {
-                $className = self::HANDLER_NAMESPACE . str_replace('/', '\\', substr($relativePath, 0, -4));
+                continue;
+            }
 
+            $relative = str_replace(__DIR__ . '/Handlers/', '', $file->getPathname());
+            $class = self::HANDLER_NAMESPACE . str_replace('/', '\\', substr($relative, 0, -4));
 
-                if (class_exists($className)) {
+            if (!class_exists($class)) {
-                    $reflection = new \ReflectionClass($className);
+                continue;
-                    $attributes = $reflection->getAttributes(HandlesMessage::class);
+            }
-                    foreach ($attributes as $attribute) {
+
-                        $instance = $attribute->newInstance();
+            $ref = new \ReflectionClass($class);
-                        $messageClass = $instance->getMessageClass();
+            foreach ($ref->getAttributes(HandlesMessage::class) as $attr) {
-                        $this->handlers[$messageClass][] = $className;
+                $messageClass = $attr->newInstance()->getMessageClass();
-                    }
+                $this->handlers[$messageClass][] = $class;
-                }
             }
         }
     }
 
     /**
-     * @param $signal
+     * Signal handler used to initiate graceful or immediate shutdown.
      */
-    public static function handleSignal($signal): void
+    public static function handleSignal(int $signal): void
     {
         switch ($signal) {
-            // Graceful
             case SIGINT:
             case SIGTERM:
             case SIGHUP:
                 self::$shutDown = true;
-
+                return;
-                break;
-
-            // Not Graceful
             case SIGKILL:
                 exit(9);
         }
@@ -81,6 +105,9 @@ class Consumer
         return self::$shutDown;
     }
 
+    /**
+     * Start the consumer main loop.
+     */
     public function start(): void
     {
         if (!\function_exists('pcntl_signal')) {
@@ -88,10 +115,11 @@ class Consumer
         }
 
         Logger::info('Starting queue consumer...');
+        Logger::info('Using Broker: ' . Broker::getFacadeRoot()::class);
 
-        \pcntl_signal(SIGINT, [self::class, 'handleSignal']);
+        foreach ([SIGINT, SIGTERM, SIGHUP] as $sig) {
-        \pcntl_signal(SIGTERM, [self::class, 'handleSignal']);
+            \pcntl_signal($sig, [self::class, 'handleSignal']);
-        \pcntl_signal(SIGHUP, [self::class, 'handleSignal']);
+        }
 
         while (true) {
             if ($this->shouldShutDown()) {
@@ -103,40 +131,43 @@ class Consumer
             foreach ($this->queues as $queue) {
                 Logger::info('Listening to queue: ' . $queue->queueName());
                 $message = $queue->pop();
-                if ($message) {
+                if (!$message) {
-                    Logger::info('Processing message of type: ' . get_class($message));
+                    continue;
-
-                    $handlers = $this->getHandlerForMessage($message);
-
-                    foreach ($handlers as $handler) {
-                        $handler($message);
-                    }
                 }
+
+                Logger::info('Processing message of type: ' . get_class($message));
+
+                foreach ($this->getHandlersForMessage($message) as $handler) {
+                    $handler($message);
+                }
+
+                // Continue polling from the top of the loop after processing a message.
+                continue 2;
             }
 
+            // Avoid busy-looping when no messages are available.
             sleep(1);
         }
     }
 
-    private function getHandlerForMessage($message): array
+    /**
+     * @return callable[] Handler instances invokable with the message
+     */
+    private function getHandlersForMessage(Message $message): array
     {
-        $callables = [];
-
         $messageClass = get_class($message);
-        if (isset($this->handlers[$messageClass])) {
-            $handlerClasses = $this->handlers[$messageClass];
 
-            foreach ($handlerClasses as $handlerClass) {
+        if (!isset($this->handlers[$messageClass])) {
-                if (class_exists($handlerClass)) {
+            throw new \RuntimeException("No handler found for message class: $messageClass");
-                    $handlerInstance = new $handlerClass();
-
-                    $callables[] = $handlerInstance;
-                }
-            }
-
-            return $callables;
         }
 
-        throw new \RuntimeException("No handler found for message class: $messageClass");
+        $callables = [];
+        foreach ($this->handlers[$messageClass] as $handlerClass) {
+            if (class_exists($handlerClass)) {
+                $callables[] = new $handlerClass();
+            }
+        }
+
+        return $callables;
     }
 }

src/Async/Handlers/SayHelloHandler.php

@@ -4,7 +4,7 @@ declare(strict_types=1);
 
 namespace Siteworxpro\App\Async\Handlers;
 
-use Siteworxpro\App\Annotations\Async\HandlesMessage;
+use Siteworxpro\App\Attributes\Async\HandlesMessage;
 use Siteworxpro\App\Async\Messages\Message;
 use Siteworxpro\App\Async\Messages\SayHelloMessage;
 use Siteworxpro\App\Services\Facades\Logger;

src/Attributes/Async/HandlesMessage.php

@@ -0,0 +1,36 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Siteworxpro\App\Attributes\Async;
+
+use Attribute;
+
+/**
+ * Attribute to mark a class as a handler for a specific message class in an async workflow.
+ *
+ * Repeatable: attach multiple times to handle multiple message classes.
+ */
+#[Attribute(Attribute::TARGET_CLASS | Attribute::IS_REPEATABLE)]
+readonly class HandlesMessage
+{
+    /**
+     * Create a new HandlesMessage attribute.
+     *
+     * @param class-string $messageClass Fully-qualified class name of the message handled.
+     */
+    public function __construct(
+        public string $messageClass,
+    ) {
+    }
+
+    /**
+     * Get the fully-qualified message class this handler processes.
+     *
+     * @return class-string
+     */
+    public function getMessageClass(): string
+    {
+        return $this->messageClass;
+    }
+}

src/Attributes/Events/ListensFor.php

@@ -0,0 +1,28 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Siteworxpro\App\Attributes\Events;
+
+use Attribute;
+
+/**
+ * Attribute to mark a class as an event listener for a specific event class.
+ *
+ * Apply this attribute to classes that subscribe to domain or application events.
+ * Repeatable: can be attached multiple times to the same class to listen for multiple events.
+ *
+ * Targets: class only.
+ */
+#[Attribute(Attribute::TARGET_CLASS | Attribute::IS_REPEATABLE)]
+readonly class ListensFor
+{
+    /**
+     * Initialize the ListensFor attribute.
+     *
+     * @param class-string $eventClass Fully-qualified class name of the event to listen for.
+     */
+    public function __construct(public string $eventClass)
+    {
+    }
+}

src/Attributes/Guards/Jwt.php

@@ -0,0 +1,66 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Siteworxpro\App\Attributes\Guards;
+
+use Attribute;
+use Siteworxpro\App\Services\Facades\Config;
+
+/**
+ * Attribute to guard classes or methods with JWT claim requirements.
+ *
+ * Apply this attribute to a class or method to declare the expected JWT issuer and/or audience.
+ * If either the issuer or audience is an empty string, the value will be resolved from configuration:
+ * - `jwt.issuer`
+ * - `jwt.audience`
+ *
+ * Targets: class or method.
+ */
+#[Attribute(Attribute::TARGET_CLASS | Attribute::TARGET_METHOD)]
+readonly class Jwt
+{
+    /**
+     * Initialize the Jwt attribute with optional overrides for expected JWT claims.
+     *
+     * @param string $issuer   Optional expected JWT issuer (`iss`). Empty string uses `Config::get('jwt.issuer')`.
+     * @param string $audience Optional expected JWT audience (`aud`). Empty string uses `Config::get('jwt.audience')`.
+     */
+    public function __construct(
+        private string $issuer = '',
+        private string $audience = '',
+    ) {
+    }
+
+    /**
+     * Get the expected audience for validation.
+     *
+     * Returns the constructor-provided audience when non-empty; otherwise falls back to `jwt.audience` config.
+     *
+     * @return string The audience value to enforce.
+     */
+    public function getAudience(): string
+    {
+        if ($this->audience === '') {
+            return Config::get('jwt.audience') ?? '';
+        }
+
+        return $this->audience;
+    }
+
+    /**
+     * Get the expected issuer for validation.
+     *
+     * Returns the constructor-provided issuer when non-empty; otherwise falls back to `jwt.issuer` config.
+     *
+     * @return string The issuer value to enforce.
+     */
+    public function getIssuer(): string
+    {
+        if ($this->issuer === '') {
+            return Config::get('jwt.issuer') ?? '';
+        }
+
+        return $this->issuer;
+    }
+}

src/Attributes/Guards/RequireAllScopes.php

@@ -0,0 +1,12 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Siteworxpro\App\Attributes\Guards;
+
+use Attribute;
+
+#[Attribute(Attribute::TARGET_CLASS | Attribute::TARGET_METHOD)]
+readonly class RequireAllScopes
+{
+}

src/Attributes/Guards/Scope.php

@@ -0,0 +1,38 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Siteworxpro\App\Attributes\Guards;
+
+use Attribute;
+
+#[Attribute(Attribute::TARGET_CLASS | Attribute::TARGET_METHOD | Attribute::IS_REPEATABLE)]
+readonly class Scope
+{
+    /**
+     * @param array<int, string> $scopes the required scopes
+     * @param string $claim the claim to check for scopes
+     * @param string $separator the separator used to split scopes in the claim
+     */
+    public function __construct(
+        private array $scopes = [],
+        private string $claim = 'scope',
+        private string $separator = ' '
+    ) {
+    }
+
+    public function getScopes(): array
+    {
+        return $this->scopes;
+    }
+
+    public function getClaim(): string
+    {
+        return $this->claim;
+    }
+
+    public function getSeparator(): string
+    {
+        return $this->separator;
+    }
+}

src/Cli/App.php

@@ -7,6 +7,7 @@ namespace Siteworxpro\App\Cli;
 use Ahc\Cli\Application;
 use Siteworxpro\App\Cli\Commands\DemoCommand;
 use Siteworxpro\App\Cli\Commands\Queue\Start;
+use Siteworxpro\App\Cli\Commands\Queue\TestJob;
 use Siteworxpro\App\Kernel;
 use Siteworxpro\App\Services\Facades\Config;
 
@@ -24,6 +25,7 @@ class App
 
         $this->app->add(new DemoCommand());
         $this->app->add(new Start());
+        $this->app->add(new TestJob());
     }
 
     public function run(): int

src/Cli/Commands/Queue/Start.php

@@ -6,6 +6,7 @@ namespace Siteworxpro\App\Cli\Commands\Queue;
 
 use Ahc\Cli\Input\Command;
 use Siteworxpro\App\Async\Consumer;
+use Siteworxpro\App\Async\Messages\SayHelloMessage;
 use Siteworxpro\App\Cli\Commands\CommandInterface;
 
 class Start extends Command implements CommandInterface
@@ -13,14 +14,17 @@ class Start extends Command implements CommandInterface
     public function __construct()
     {
         parent::__construct('queue:start', 'Start the queue consumer to process messages.');
-
+        $this->argument('[queues]', 'The name of the queue to consume from. ex. "first_queue,second_queue"');
-        $this->argument('[name]', 'Your name')
-            ->option('-g, --greet', 'Include a greeting message');
     }
 
     public function execute(): int
     {
-        $consumer = new Consumer();
+        $queues = [];
+        if ($this->values()['queues'] !== null) {
+            $queues = explode(',', $this->values()['queues']);
+        }
+
+        $consumer = new Consumer($queues);
         $consumer->start();
 
         return 0;

src/Cli/Commands/Queue/TestJob.php

@@ -0,0 +1,34 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Siteworxpro\App\Cli\Commands\Queue;
+
+use Ahc\Cli\Input\Command;
+use Siteworxpro\App\Async\Messages\SayHelloMessage;
+use Siteworxpro\App\Cli\Commands\CommandInterface;
+
+/**
+ * Class TestJob
+ *
+ * A CLI command to schedule a demo job that dispatches a SayHelloMessage.
+ */
+class TestJob extends Command implements CommandInterface
+{
+    public function __construct()
+    {
+        parent::__construct('queue:demo', 'Schedule a demo job.');
+    }
+
+    /**
+     * Execute the command to dispatch a SayHelloMessage.
+     *
+     * @return int Exit code
+     */
+    public function execute(): int
+    {
+        SayHelloMessage::dispatch('World from TestJob Command!');
+
+        return 0;
+    }
+}

src/Controllers/Controller.php

@@ -8,6 +8,13 @@ use League\Route\Http\Exception\NotFoundException;
 use Nyholm\Psr7\ServerRequest;
 use Psr\Http\Message\ResponseInterface;
 
+/**
+ * Class Controller
+ *
+ * An abstract base controller providing default implementations for HTTP methods.
+ *
+ * @package Siteworxpro\App\Controllers
+ */
 abstract class Controller implements ControllerInterface
 {
     /**

src/Controllers/ControllerInterface.php

@@ -7,6 +7,11 @@ namespace Siteworxpro\App\Controllers;
 use Nyholm\Psr7\ServerRequest;
 use Psr\Http\Message\ResponseInterface;
 
+/**
+ * Interface ControllerInterface
+ *
+ * Defines the contract for handling HTTP requests in a controller.
+ */
 interface ControllerInterface
 {
     /**

src/Controllers/HealthcheckController.php

@@ -12,6 +12,13 @@ use Siteworxpro\App\Models\Model;
 use Siteworxpro\App\Services\Facades\Redis;
 use Siteworxpro\HttpStatus\CodesEnum;
 
+/**
+ * Class HealthcheckController
+ *
+ * Handles health check requests to verify database and cache connectivity.
+ *
+ * @package Siteworxpro\App\Controllers
+ */
 class HealthcheckController extends Controller
 {
     /**

src/Controllers/IndexController.php

@@ -6,7 +6,7 @@ namespace Siteworxpro\App\Controllers;
 
 use Nyholm\Psr7\ServerRequest;
 use Psr\Http\Message\ResponseInterface;
-use Siteworxpro\App\Annotations\Guards;
+use Siteworxpro\App\Attributes\Guards;
 use Siteworxpro\App\Http\JsonResponseFactory;
 
 /**
@@ -22,7 +22,8 @@ class IndexController extends Controller
      * @throws \JsonException
      */
     #[Guards\Jwt]
-    #[Guards\Scope(['get.index'])]
+    #[Guards\Scope(['get.index', 'status.check'])]
+    #[Guards\RequireAllScopes]
     public function get(ServerRequest $request): ResponseInterface
     {
         return JsonResponseFactory::createJsonResponse(['status_code' => 200, 'message' => 'Server is running']);

src/Events/Dispatcher.php

@@ -7,7 +7,10 @@ namespace Siteworxpro\App\Events;
 use Illuminate\Contracts\Events\Dispatcher as DispatcherContract;
 use Illuminate\Contracts\Support\Arrayable;
 use Illuminate\Support\Collection;
-use Siteworxpro\App\Annotations\Events\ListensFor;
+use Siteworxpro\App\Attributes\Events\ListensFor;
+
+use function React\Async\await;
+use function React\Async\coroutine;
 
 /**
  * Class Dispatcher
@@ -29,6 +32,8 @@ class Dispatcher implements DispatcherContract, Arrayable
      */
     private Collection $pushed;
 
+    private array $subscribers = [];
+
     /**
      * @var string LISTENERS_NAMESPACE The namespace where listeners are located
      */
@@ -99,7 +104,7 @@ class Dispatcher implements DispatcherContract, Arrayable
      */
     public function subscribe($subscriber): void
     {
-        $this->listeners = array_merge($this->listeners, (array) $subscriber);
+        $this->subscribers[] = $subscriber;
     }
 
     /**
@@ -108,6 +113,7 @@ class Dispatcher implements DispatcherContract, Arrayable
      * @param $event
      * @param array $payload
      * @return array|null
+     * @throws \Throwable
      */
     public function until($event, $payload = []): array|null
     {
@@ -121,6 +127,7 @@ class Dispatcher implements DispatcherContract, Arrayable
      * @param array $payload
      * @param bool $halt
      * @return array|null
+     * @throws \Throwable
      */
     public function dispatch($event, $payload = [], $halt = false): array|null
     {
@@ -130,23 +137,46 @@ class Dispatcher implements DispatcherContract, Arrayable
             $eventClass = $event;
         }
 
+        // Handle subscribers as a coroutine
+        $promise = coroutine(function () use ($event, $payload, $halt, $eventClass, &$responses) {
+            foreach ($this->subscribers as $subscriber) {
+                if (method_exists($subscriber, 'handle')) {
+                    $response = $subscriber->handle($event, $payload);
+                    $responses[$eventClass] = $response;
+
+                    if ($halt && $response !== null) {
+                        return $responses;
+                    }
+                }
+            }
+
+            return null;
+        });
+
         $listeners = $this->listeners[$eventClass] ?? null;
 
+        // If no listeners, just await the subscriber promise
         if ($listeners === null) {
-            return null;
+            return await($promise);
         }
 
         $responses = [];
-
         foreach ($listeners as $listener) {
             $response = $listener($event, $payload);
-            $responses[] = $response;
+            $responses[$eventClass] = $response;
 
             if ($halt && $response !== null) {
                 return $response;
             }
         }
 
+        // Await the subscriber promise and merge responses
+        $promiseResponses = await($promise);
+
+        if (is_array($promiseResponses)) {
+            $responses = array_merge($responses, $promiseResponses);
+        }
+
         return $responses;
     }
 
@@ -167,6 +197,7 @@ class Dispatcher implements DispatcherContract, Arrayable
      *
      * @param $event
      * @return void
+     * @throws \Throwable
      */
     public function flush($event): void
     {

src/Events/Listeners/Database/Connected.php

@@ -6,20 +6,27 @@ namespace Siteworxpro\App\Events\Listeners\Database;
 
 use Illuminate\Database\Events\ConnectionEstablished;
 use Illuminate\Database\Events\ConnectionEvent;
-use Siteworxpro\App\Annotations\Events\ListensFor;
+use Siteworxpro\App\Attributes\Events\ListensFor;
 use Siteworxpro\App\Events\Listeners\Listener;
 use Siteworxpro\App\Services\Facades\Logger;
 
+/**
+ * Class Connected
+ * @package Siteworxpro\App\Events\Listeners\Database
+ */
 #[ListensFor(ConnectionEstablished::class)]
 class Connected extends Listener
 {
     /**
-     * @param ConnectionEvent $event
+     * @param mixed $event
      * @param array $payload
      * @return null
      */
-    public function __invoke($event, array $payload = []): null
+    public function __invoke(mixed $event, array $payload = []): null
     {
+        if (!($event instanceof ConnectionEvent)) {
+            throw new \TypeError("Invalid event type passed to listener " . static::class);
+        }
 
         Logger::info("Database connection event", [get_class($event), $event->connectionName]);
 

src/Events/Listeners/Listener.php

@@ -4,6 +4,11 @@ declare(strict_types=1);
 
 namespace Siteworxpro\App\Events\Listeners;
 
+/**
+ * Class Listener
+ *
+ * @package Siteworxpro\App\Events\Listeners
+ */
 abstract class Listener implements ListenerInterface
 {
 }

src/Events/Listeners/ListenerInterface.php

@@ -4,7 +4,16 @@ declare(strict_types=1);
 
 namespace Siteworxpro\App\Events\Listeners;
 
+/**
+ * Interface ListenerInterface
+ * @package Siteworxpro\App\Events\Listeners
+ */
 interface ListenerInterface
 {
+    /**
+     * @param mixed $event
+     * @param array $payload
+     * @return mixed
+     */
     public function __invoke(mixed $event, array $payload = []): mixed;
 }

src/Helpers/Env.php

@@ -4,6 +4,10 @@ declare(strict_types=1);
 
 namespace Siteworxpro\App\Helpers;
 
+/**
+ * Class Env
+ * @package Siteworxpro\App\Helpers
+ */
 abstract class Env
 {
     /**

src/Helpers/Ulid.php

@@ -4,8 +4,17 @@ declare(strict_types=1);
 
 namespace Siteworxpro\App\Helpers;
 
+/**
+ * Class Ulid
+ * @package Siteworxpro\App\Helpers
+ */
 class Ulid
 {
+    /**
+     * Generate a ULID string
+     *
+     * @return string
+     */
     public static function generate(): string
     {
         return \Ulid\Ulid::generate()->getRandomness();

src/Http/Middleware/JwtMiddleware.php

@@ -6,8 +6,11 @@ namespace Siteworxpro\App\Http\Middleware;
 
 use Carbon\Carbon;
 use Carbon\WrapperClock;
+use GuzzleHttp\Client;
+use GuzzleHttp\Exception\GuzzleException;
 use Lcobucci\JWT\JwtFacade;
 use Lcobucci\JWT\Signer\Hmac\Sha256 as Hmac256;
+use Lcobucci\JWT\Signer\Key;
 use Lcobucci\JWT\Signer\Key\InMemory;
 use Lcobucci\JWT\Signer\Rsa\Sha256;
 use Lcobucci\JWT\Token\InvalidTokenStructure;
@@ -21,24 +24,51 @@ use League\Route\Dispatcher;
 use Psr\Http\Message\ResponseInterface;
 use Psr\Http\Message\ServerRequestInterface;
 use Psr\Http\Server\RequestHandlerInterface;
-use Siteworxpro\App\Annotations\Guards\Jwt;
+use Siteworxpro\App\Attributes\Guards\Jwt;
 use Siteworxpro\App\Controllers\Controller;
 use Siteworxpro\App\Http\JsonResponseFactory;
 use Siteworxpro\App\Services\Facades\Config;
+use Siteworxpro\App\Services\Facades\Redis;
 use Siteworxpro\HttpStatus\CodesEnum;
 
+/**
+ * JWT authorization middleware.
+ *
+ * Applies JWT validation to controller actions annotated with `Jwt` attribute.
+ * Flow:
+ * - Resolve the targeted controller and method for the current route.
+ * - If the method has `Jwt`, read the `Authorization` header and parse the Bearer token.
+ * - Validate signature, time constraints, issuer\(\) and audience\(\) based on attribute and config.
+ * - On success, attach all token claims to the request as attributes.
+ * - On failure, return a 401 JSON response with validation errors.
+ *
+ * Configuration:
+ * - `jwt.signing_key`: key material or `file://` path to key.
+ * - `jwt.strict_validation`: bool toggling strict vs loose time validation.
+ */
 class JwtMiddleware extends Middleware
 {
     /**
-     * @throws \JsonException
+     * Process the incoming request.
-     * @throws \Exception
+     *
+     * If the matched controller method is annotated with `Jwt`, validates the token and
+     * augments the request with claims on success. Otherwise, just delegates to the next handler.
+     *
+     * @param ServerRequestInterface $request PSR-7 request instance.
+     * @param RequestHandlerInterface|Dispatcher $handler Next middleware or route dispatcher.
+     *
+     * @return ResponseInterface Response produced by the next handler or a 401 JSON response.
+     *
+     * @throws \JsonException On JSON error response encoding issues.
+     * @throws \Exception On unexpected reflection or JWT parsing issues.
      */
     public function process(
         ServerRequestInterface $request,
         RequestHandlerInterface|Dispatcher $handler
     ): ResponseInterface {
 
-        $callable = $this->extractRouteCallable($request, $handler);
+        // Resolve the callable \[Controller, method] for the current route.
+        $callable = $this->extractRouteCallable($handler);
         if ($callable === null) {
             return $handler->handle($request);
         }
@@ -51,12 +81,15 @@ class JwtMiddleware extends Middleware
 
             if ($reflectionClass->hasMethod($method)) {
                 $reflectionMethod = $reflectionClass->getMethod($method);
+                // Read `Jwt` attribute on the controller method.
                 $attributes = $reflectionMethod->getAttributes(Jwt::class);
 
+                // If no `Jwt` attribute, do not enforce auth here.
                 if (empty($attributes)) {
                     return $handler->handle($request);
                 }
 
+                // Extract Bearer token from Authorization header.
                 $token = str_replace('Bearer ', '', $request->getHeaderLine('Authorization'));
 
                 if (empty($token)) {
@@ -66,6 +99,7 @@ class JwtMiddleware extends Middleware
                     ], CodesEnum::UNAUTHORIZED);
                 }
 
+                // Aggregate required issuers and audience from attributes.
                 $requiredIssuers = [];
                 $requiredAudience = '';
 
@@ -73,7 +107,7 @@ class JwtMiddleware extends Middleware
                     /** @var Jwt $jwtInstance */
                     $jwtInstance = $attribute->newInstance();
 
-                    if ($jwtInstance->getRequiredAudience() !== '') {
+                    if ($jwtInstance->getAudience() !== '') {
                         $requiredAudience = $jwtInstance->getAudience();
                     }
 
@@ -81,9 +115,10 @@ class JwtMiddleware extends Middleware
                 }
 
                 try {
+                    // Parse and validate the token with signature, time, issuer and audience constraints.
                     $jwt = new JwtFacade()->parse(
                         $token,
-                        $this->getSignedWith(),
+                        $this->getSignedWith($token),
                         Config::get('jwt.strict_validation') ?
                             new StrictValidAt(new WrapperClock(Carbon::now())) :
                             new LooseValidAt(new WrapperClock(Carbon::now())),
@@ -91,6 +126,7 @@ class JwtMiddleware extends Middleware
                         new PermittedFor($requiredAudience)
                     );
                 } catch (RequiredConstraintsViolated $exception) {
+                    // Collect human-readable violations to return to the client.
                     $violations = [];
                     foreach ($exception->violations() as $violation) {
                         $violations[] = $violation->getMessage();
@@ -102,12 +138,19 @@ class JwtMiddleware extends Middleware
                         'errors' => $violations
                     ], CodesEnum::UNAUTHORIZED);
                 } catch (InvalidTokenStructure) {
+                    // Token could not be parsed due to malformed structure.
                     return JsonResponseFactory::createJsonResponse([
                         'status_code' => 401,
                         'message' => 'Unauthorized: Invalid token',
                     ], CodesEnum::UNAUTHORIZED);
+                } catch (GuzzleException) {
+                    return JsonResponseFactory::createJsonResponse([
+                        'status_code' => 501,
+                        'message' => 'Token validation service unavailable',
+                    ], CodesEnum::UNAUTHORIZED);
                 }
 
+                // Expose all token claims as request attributes for downstream consumers.
                 foreach ($jwt->claims()->all() as $item => $value) {
                     $request = $request->withAttribute($item, $value);
                 }
@@ -117,24 +160,168 @@ class JwtMiddleware extends Middleware
         return $handler->handle($request);
     }
 
-    private function getSignedWith(): SignedWith
+    /**
+     * Build the signature validation constraint from configured key.
+     *
+     * - If the configured key content includes the string `PUBLIC KEY`, use RSA SHA-256.
+     * - Otherwise assume an HMAC SHA-256 shared secret.
+     * - Supports raw key strings or `file://` paths.
+     *
+     * @return SignedWith Signature constraint used during JWT parsing.
+     *
+     * @throws \RuntimeException When no signing key is configured.
+     * @throws GuzzleException On JWKS key retrieval issues.
+     * @throws \JsonException
+     */
+    private function getSignedWith(string $token): SignedWith
     {
-        $key = Config::get('jwt.signing_key');
+        $keyConfig = Config::get('jwt.signing_key');
 
-        if ($key === null) {
+        if ($keyConfig === null) {
             throw new \RuntimeException('JWT signing key is not configured.');
         }
 
-        if (str_starts_with($key, 'file://')) {
+        // file:// path to key
-            $key = InMemory::file(substr($key, 7));
+        if (str_starts_with($keyConfig, 'file://')) {
+            $key = InMemory::file(substr($keyConfig, 7));
+            // openid jwks url
+        } elseif (str_contains($keyConfig, '.well-known/')) {
+            $jwt = explode('.', $token);
+            if (count($jwt) !== 3) {
+                throw new \RuntimeException('Invalid JWT structure for JWKS key retrieval.');
+            }
+            $header = json_decode(base64_decode($jwt[0]), true, 512, JSON_THROW_ON_ERROR);
+            $keyId = $header['kid'] ?? '0'; // Default to '0' if no kid present
+            $key = $this->getJwksKey($keyConfig, $keyId);
         } else {
-            $key = InMemory::plainText($key);
+            $key = InMemory::plainText($keyConfig);
         }
 
+        // Heuristic: if PEM public key content is detected, use RSA; otherwise use HMAC.
         if (str_contains($key->contents(), 'PUBLIC KEY')) {
             return new SignedWith(new Sha256(), $key);
         }
 
         return new SignedWith(new Hmac256(), $key);
     }
+
+    /**
+     * @throws GuzzleException
+     */
+    private function getJwksKey(string $url, string $keyId): Key
+    {
+        $cached = Redis::get('jwks_key_' . $keyId);
+        if ($cached !== null) {
+            return InMemory::plainText($cached);
+        }
+
+        $client = new Client();
+        $openIdConfig = $client->get($url);
+        $body = json_decode($openIdConfig->getBody()->getContents(), true, JSON_THROW_ON_ERROR);
+        $jwksUri = $body['jwks_uri'] ?? '';
+        if (empty($jwksUri)) {
+            throw new \RuntimeException('JWKS URI not found in OpenID configuration.');
+        }
+
+        $jwksResponse = $client->get($jwksUri);
+        $jwksBody = json_decode(
+            $jwksResponse->getBody()->getContents(),
+            true,
+            JSON_THROW_ON_ERROR
+        );
+
+        // For simplicity, we take the first key in the JWKS.
+        $firstKey = array_filter(
+            $jwksBody['keys'],
+            fn($key) => $key['kid'] === $keyId
+        )[0] ?? null;
+
+        if (empty($firstKey)) {
+            throw new \RuntimeException('No matching key found in JWKS for key ID: ' . $keyId);
+        }
+
+        $n = $firstKey['n'];
+        $e = $firstKey['e'];
+        $publicKeyPem = "-----BEGIN PUBLIC KEY-----\n" .
+            chunk_split(base64_encode($this->convertJwkToPem($n, $e)), 64) .
+            "-----END PUBLIC KEY-----\n";
+
+        Redis::set('jwks_key_' . $keyId, $publicKeyPem, 'EX', 3600);
+
+        return InMemory::plainText($publicKeyPem);
+    }
+
+    /**
+     * Build a DER-encoded SubjectPublicKeyInfo from JWK 'n' and 'e'.
+     * Returns raw DER bytes; caller base64-encodes and wraps with PEM headers.
+     */
+    private function convertJwkToPem(string $n, string $e): string
+    {
+        $modulus = $this->base64UrlDecode($n);
+        $exponent = $this->base64UrlDecode($e);
+
+        $derN = $this->derEncodeInteger($modulus);
+        $derE = $this->derEncodeInteger($exponent);
+
+        // RSAPublicKey (PKCS#1): SEQUENCE { n INTEGER, e INTEGER }
+        $rsaPublicKey = $this->derEncodeSequence($derN . $derE);
+
+        // AlgorithmIdentifier for rsaEncryption: 1.2.840.113549.1.1.1 with NULL
+        $algId = hex2bin('300d06092a864886f70d0101010500');
+
+        // SubjectPublicKey (SPKI) BIT STRING, 0 unused bits + RSAPublicKey
+        $subjectPublicKey = $this->derEncodeBitString($rsaPublicKey);
+
+        // SubjectPublicKeyInfo: SEQUENCE { algorithm AlgorithmIdentifier, subjectPublicKey BIT STRING }
+        return $this->derEncodeSequence($algId . $subjectPublicKey);
+    }
+
+    private function base64UrlDecode(string $data): string
+    {
+        $data = strtr($data, '-_', '+/');
+        $pad = strlen($data) % 4;
+        if ($pad) {
+            $data .= str_repeat('=', 4 - $pad);
+        }
+        return base64_decode($data);
+    }
+
+    private function derEncodeLength(int $len): string
+    {
+        if ($len < 0x80) {
+            return chr($len);
+        }
+        $bytes = '';
+        while ($len > 0) {
+            $bytes = chr($len & 0xFF) . $bytes;
+            $len >>= 8;
+        }
+        return chr(0x80 | strlen($bytes)) . $bytes;
+    }
+
+    private function derEncodeInteger(string $bytes): string
+    {
+        // Remove leading zeroes
+        $bytes = ltrim($bytes, "\x00");
+        if ($bytes === '') {
+            $bytes = "\x00";
+        }
+        // Ensure positive INTEGER (prepend 0x00 if MSB set)
+        if ((ord($bytes[0]) & 0x80) !== 0) {
+            $bytes = "\x00" . $bytes;
+        }
+        return "\x02" . $this->derEncodeLength(strlen($bytes)) . $bytes;
+    }
+
+    private function derEncodeSequence(string $bytes): string
+    {
+        return "\x30" . $this->derEncodeLength(strlen($bytes)) . $bytes;
+    }
+
+    private function derEncodeBitString(string $bytes): string
+    {
+        // 0 unused bits + data
+        $payload = "\x00" . $bytes;
+        return "\x03" . $this->derEncodeLength(strlen($payload)) . $payload;
+    }
 }

src/Http/Middleware/Middleware.php

@@ -9,30 +9,60 @@ use League\Route\Route;
 use Psr\Http\Server\MiddlewareInterface;
 use Psr\Http\Server\RequestHandlerInterface;
 
+/**
+ * Base middleware helper for extracting route callables.
+ *
+ * This abstract middleware provides a utility method to inspect a League\Route
+ * dispatcher and obtain the underlying route callable as a [class, method] tuple.
+ *
+ * @package Siteworxpro\App\Http\Middleware
+ */
 abstract class Middleware implements MiddlewareInterface
 {
-
+    /**
-    protected function extractRouteCallable($request, RequestHandlerInterface | Dispatcher $handler): array|null
+     * Extract the route callable [class, method] from a League\Route dispatcher.
-    {
+     *
+     * When the provided handler is a League\Route\Dispatcher, this inspects its
+     * middleware stack, looks at the last segment (the resolved Route), and
+     * attempts to normalize its callable into a [class, method] pair.
+     *
+     * Supported callable forms:
+     * - array callable: [object|class-string, method-string]
+     * - string callable: "ClassName::methodName"
+     *
+     * Returns null when the handler is not a Dispatcher, the stack is empty,
+     * or the callable cannot be parsed.
+     *
+     * @param RequestHandlerInterface|Dispatcher $handler The downstream handler or dispatcher.
+     *
+     * @return array{0: class-string|object|null, 1: string|null}|null Tuple of [class|object, method] or null.
+     */
+    protected function extractRouteCallable(
+        RequestHandlerInterface|Dispatcher $handler
+    ): array|null {
+        // Only proceed if this is a League\Route dispatcher.
         if (!$handler instanceof Dispatcher) {
             return null;
         }
 
         /** @var Route | null $lastSegment */
+        // Retrieve the last middleware in the stack, which should be the Route.
         $lastSegment = array_last($handler->getMiddlewareStack());
 
         if ($lastSegment === null) {
             return null;
         }
 
+        // Obtain the callable associated with the route.
         $callable = $lastSegment->getCallable();
         $class = null;
         $method = null;
 
+        // Handle array callable: [object|class-string, 'method']
         if (is_array($callable) && count($callable) === 2) {
             [$class, $method] = $callable;
         } elseif (is_string($callable)) {
-            // Handle the case where the callable is a string (e.g., 'ClassName::methodName')
+            // Handle string callable: 'ClassName::methodName'
             [$class, $method] = explode('::', $callable);
         }
 

src/Http/Middleware/ScopeMiddleware.php

@@ -8,57 +8,110 @@ use League\Route\Dispatcher;
 use Psr\Http\Message\ResponseInterface;
 use Psr\Http\Message\ServerRequestInterface;
 use Psr\Http\Server\RequestHandlerInterface;
-use Siteworxpro\App\Annotations\Guards\Scope;
+use Siteworxpro\App\Attributes\Guards\RequireAllScopes;
+use Siteworxpro\App\Attributes\Guards\Scope;
 use Siteworxpro\App\Controllers\Controller;
 use Siteworxpro\App\Http\JsonResponseFactory;
 use Siteworxpro\HttpStatus\CodesEnum;
 
+/**
+ * Middleware that enforces scope-based access control on controller actions.
+ *
+ * It inspects PHP 8 attributes of type \`Scope\` applied to the resolved controller method,
+ * compares the required scopes with the user scopes provided on the request attribute \`scopes\`,
+ * and returns a 403 JSON response when any required scope is missing.
+ *
+ * If the route callable cannot be resolved, or no scope is required, the request is passed through.
+ *
+ * @see Scope
+ */
 class ScopeMiddleware extends Middleware
 {
     /**
-     * @throws \JsonException
+     * Resolve the route callable, read any \`Scope\` attributes, and enforce required scopes.
+     *
+     * Expected user scopes are provided on the request under the attribute name \`scopes\`
+     * as an array of strings.
+     *
+     * @param ServerRequestInterface $request Incoming PSR-7 request (expects \`scopes\` attribute).
+     * @param RequestHandlerInterface|Dispatcher $handler Next handler or League\Route dispatcher.
+     *
+     * @return ResponseInterface A 403 JSON response when scopes are insufficient; otherwise the handler response.
+     *
+     * @throws \JsonException       If encoding the JSON error response fails.
+     * @throws \ReflectionException If reflection on the controller or method fails.
      */
     public function process(
         ServerRequestInterface $request,
-        RequestHandlerInterface | Dispatcher $handler
+        RequestHandlerInterface|Dispatcher $handler
     ): ResponseInterface {
-        $callable = $this->extractRouteCallable($request, $handler);
+        // Attempt to resolve the route's callable [Controller instance, method name].
+        $callable = $this->extractRouteCallable($handler);
         if ($callable === null) {
+            // If no callable is available, delegate to the next handler.
             return $handler->handle($request);
         }
 
-        /** @var Controller $class */
+        /** @var Controller $class Controller instance resolved from the route. */
         [$class, $method] = $callable;
 
+        // Ensure the controller exists and the method is defined before reflecting.
         if (class_exists($class::class)) {
             $reflectionClass = new \ReflectionClass($class);
+
             if ($reflectionClass->hasMethod($method)) {
                 $reflectionMethod = $reflectionClass->getMethod($method);
+
+                // Fetch all Scope attributes declared on the method.
                 $attributes = $reflectionMethod->getAttributes(Scope::class);
+                $requireAllAttributes = $reflectionMethod->getAttributes(RequireAllScopes::class);
+
+                if (empty($attributes)) {
+                    // No scope attributes; delegate to the next handler.
+                    return $handler->handle($request);
+                }
+
+                $requiredScopes = [];
+                $userScopes = [];
+                $requireAll = false;
 
                 foreach ($attributes as $attribute) {
-                    /** @var Scope $scopeInstance */
+                    /** @var Scope $scopeInstance Concrete Scope attribute instance. */
                     $scopeInstance = $attribute->newInstance();
-                    $requiredScopes = $scopeInstance->getScopes();
+                    $requiredScopes = array_merge($requiredScopes, $scopeInstance->getScopes());
 
-                    $userScopes = $request->getAttribute('scopes', []);
+                    // If any attribute requires all scopes, set the flag.
+                    $requireAll = $requireAll || !empty($requireAllAttributes);
 
-                    if (
+                    $scopes = $request->getAttribute($scopeInstance->getClaim());
-                        array_any(
+                    if (!is_array($scopes)) {
-                            $requiredScopes,
+                        // If user scopes are not an array, treat as no scopes provided.
-                            fn($requiredScope) => !in_array($requiredScope, $userScopes, true)
+                        $scopes = explode($scopeInstance->getSeparator(), (string) $scopes);
-                        )
-                    ) {
-                        return JsonResponseFactory::createJsonResponse([
-                            'error' => 'insufficient_scope',
-                            'error_description' =>
-                                'The request requires higher privileges than provided by the access token.'
-                        ], CodesEnum::FORBIDDEN);
                     }
+
+                    $userScopes = array_merge(
+                        $userScopes,
+                        $scopes
+                    );
+                }
+
+                $userScopes = array_unique($userScopes);
+
+                // Deny if any required scope is missing from the user's scopes.
+                if (
+                    (!$requireAll && array_intersect($userScopes, $requiredScopes) === []) ||
+                    ($requireAll && array_diff($requiredScopes, $userScopes) !== [])
+                ) {
+                    return JsonResponseFactory::createJsonResponse([
+                        'error' => 'insufficient_scope',
+                        'error_description' =>
+                            'The request requires higher privileges than provided by the access token.'
+                    ], CodesEnum::FORBIDDEN);
                 }
             }
         }
 
+        // All checks passed; continue down the middleware pipeline.
         return $handler->handle($request);
     }
 }

src/Kernel.php

@@ -14,8 +14,21 @@ use Siteworxpro\App\Services\ServiceProviders\DispatcherServiceProvider;
 use Siteworxpro\App\Services\ServiceProviders\LoggerServiceProvider;
 use Siteworxpro\App\Services\ServiceProviders\RedisServiceProvider;
 
+/**
+ * Class Kernel
+ *
+ * The Kernel class is responsible for bootstrapping the application by
+ * initializing service providers and setting up the database connection.
+ *
+ * @package Siteworxpro\App
+ */
 class Kernel
 {
+    /**
+     * List of service providers to be registered during bootstrapping.
+     *
+     * @var array
+     */
     private static array $serviceProviders = [
         LoggerServiceProvider::class,
         RedisServiceProvider::class,

src/Log/Logger.php

@@ -6,17 +6,51 @@ namespace Siteworxpro\App\Log;
 
 use Monolog\Formatter\JsonFormatter;
 use Monolog\Handler\StreamHandler;
+use Psr\Container\ContainerExceptionInterface;
+use Psr\Container\NotFoundExceptionInterface;
 use Psr\Log\LoggerInterface;
 use Psr\Log\LogLevel;
 use RoadRunner\Logger\Logger as RRLogger;
-use Spiral\Goridge\RPC\RPC;
+use Siteworxpro\App\Services\Facades\RoadRunnerLogger;
 
+/**
+ * Logger implementation that conforms to PSR-3 (`Psr\Log\LoggerInterface`).
+ *
+ * Behavior:
+ * - If environment indicates RoadRunner RPC (`$_SERVER['RR_RPC']`), logs are forwarded
+ *   to a RoadRunner RPC logger (`RoadRunner\Logger\Logger`) created via Goridge RPC.
+ * - Otherwise, logs are written to `php://stdout` using Monolog with a JSON formatter.
+ * - Messages below the configured threshold are ignored (level filtering).
+ *
+ * Supported PSR-3 levels are mapped to an internal numeric ordering in `$levels`.
+ * When using the RPC logger, levels are translated to the respective RPC methods
+ * (debug, info, warning, error). When using Monolog, the numeric mapping is used
+ * as the numeric level passed to Monolog's `log` method.
+ */
 class Logger implements LoggerInterface
 {
-    private ?RRLogger $rpcLogger = null;
+    /**
+     * RoadRunner RPC logger instance when running under RoadRunner.
+     *
+     * @var RRLogger | LoggerInterface | null
+     */
+    private RRLogger | LoggerInterface | null $rpcLogger = null;
 
+    /**
+     * Monolog logger used as a fallback to write JSON-formatted logs to stdout.
+     *
+     * @var \Monolog\Logger
+     */
     private \Monolog\Logger $monologLogger;
 
+    /**
+     * Numeric ordering for PSR-3 log levels.
+     *
+     * Lower numbers represent higher severity. This mapping is used for filtering
+     * messages according to the configured minimum level and for Monolog numeric level.
+     *
+     * @var array<string,int>
+     */
     private array $levels = [
         LogLevel::EMERGENCY => 0,
         LogLevel::ALERT     => 1,
@@ -28,61 +62,146 @@ class Logger implements LoggerInterface
         LogLevel::DEBUG     => 7,
     ];
 
-    public function __construct(private readonly string $level = LogLevel::DEBUG)
+    /**
-    {
+     * Create a new Logger.
+     *
+     * @param string $level Minimum level to log (PSR-3 level string). Messages with
+     *                      a higher numeric value in `$levels` will be ignored.
+     *
+     * @param resource | null $streamOutput Optional stream handler for Monolog.
+     *
+     * The default is `LogLevel::DEBUG` (log everything).
+     *
+     * If `$_SERVER['RR_RPC']` is set, an RPC connection will be attempted at
+     *  $_SERVER['RR_RPC'] and a RoadRunner RPC logger will be used.
+     *
+     * @throws ContainerExceptionInterface
+     * @throws NotFoundExceptionInterface
+     */
+    public function __construct(
+        private readonly string $level = LogLevel::DEBUG,
+        $streamOutput = null,
+    ) {
         if (isset($_SERVER['RR_RPC'])) {
-            $rpc = RPC::create('tcp://127.0.0.1:6001');
+            $this->rpcLogger = RoadRunnerLogger::getFacadeRoot();
-            $this->rpcLogger = new RRLogger($rpc);
         }
 
         $this->monologLogger = new \Monolog\Logger('app_logger');
         $formatter = new JsonFormatter();
-        $this->monologLogger->pushHandler(new StreamHandler('php://stdout')->setFormatter($formatter));
+        $stream = $streamOutput ?? 'php://stdout';
+        $this->monologLogger->pushHandler(new StreamHandler($stream)->setFormatter($formatter));
     }
 
+    /**
+     * System is unusable.
+     *
+     * @param \Stringable|string $message
+     * @param array $context
+     */
     public function emergency(\Stringable|string $message, array $context = []): void
     {
         $this->log(LogLevel::EMERGENCY, $message, $context);
     }
 
+    /**
+     * Action must be taken immediately.
+     *
+     * @param \Stringable|string $message
+     * @param array $context
+     */
     public function alert(\Stringable|string $message, array $context = []): void
     {
         $this->log(LogLevel::ALERT, $message, $context);
     }
 
+    /**
+     * Critical conditions.
+     *
+     * @param \Stringable|string $message
+     * @param array $context
+     */
     public function critical(\Stringable|string $message, array $context = []): void
     {
         $this->log(LogLevel::CRITICAL, $message, $context);
     }
 
+    /**
+     * Runtime errors that do not require immediate action but should typically be logged and monitored.
+     *
+     * @param \Stringable|string $message
+     * @param array $context
+     */
     public function error(\Stringable|string $message, array $context = []): void
     {
         $this->log(LogLevel::ERROR, $message, $context);
     }
 
+    /**
+     * Exceptional occurrences that are not errors.
+     *
+     * @param \Stringable|string $message
+     * @param array $context
+     */
     public function warning(\Stringable|string $message, array $context = []): void
     {
         $this->log(LogLevel::WARNING, $message, $context);
     }
 
+    /**
+     * Normal but significant events.
+     *
+     * @param \Stringable|string $message
+     * @param array $context
+     */
     public function notice(\Stringable|string $message, array $context = []): void
     {
         $this->log(LogLevel::NOTICE, $message, $context);
     }
 
+    /**
+     * Interesting events.
+     *
+     * @param \Stringable|string $message
+     * @param array $context
+     */
     public function info(\Stringable|string $message, array $context = []): void
     {
         $this->log(LogLevel::INFO, $message, $context);
     }
 
+    /**
+     * Detailed debug information.
+     *
+     * @param \Stringable|string $message
+     * @param array $context
+     */
     public function debug(\Stringable|string $message, array $context = []): void
     {
         $this->log(LogLevel::DEBUG, $message, $context);
     }
 
+    /**
+     * Logs with an arbitrary level.
+     *
+     * Behavior details:
+     * - If the provided `$level` maps to a numeric value greater than the configured
+     *   minimum level, the message is discarded (filtered).
+     * - If an RPC logger is available, the message is forwarded to the RPC logger
+     *   using a method chosen by level (debug, info, warning, error).
+     * - Otherwise, the message is written to Monolog using the numeric mapping.
+     *
+     * Notes:
+     * - `$level` should be a PSR-3 level string (values defined in `Psr\Log\LogLevel`).
+     * - If an unknown level string is passed, accessing `$this->levels[$level]` may
+     *   trigger a PHP notice or undefined index. Ensure callers use valid PSR-3 levels.
+     *
+     * @param mixed $level PSR-3 log level (string)
+     * @param \Stringable|string $message
+     * @param array $context
+     */
     public function log($level, \Stringable|string $message, array $context = []): void
     {
-        if ($this->levels[$level] > $this->levels[$this->level]) {
+        if (isset($this->levels[$level]) && $this->levels[$level] > $this->levels[$this->level]) {
             return;
         }
 
@@ -105,7 +224,7 @@ class Logger implements LoggerInterface
                     $this->rpcLogger->error((string)$message, $context);
                     break;
                 default:
-                    $this->rpcLogger->log((string)$message, $context);
+                    $this->rpcLogger->log($level, (string)$message, $context);
                     break;
             }
 

src/Services/Facade.php

@@ -5,6 +5,7 @@ declare(strict_types=1);
 namespace Siteworxpro\App\Services;
 
 use Illuminate\Contracts\Container\Container;
+use Illuminate\Support\HigherOrderTapProxy;
 use Illuminate\Support\Testing\Fakes\Fake;
 use Mockery;
 use Mockery\Expectation;
@@ -57,9 +58,9 @@ class Facade
     /**
      * Convert the facade into a Mockery spy.
      *
-     * @return MockInterface
+     * @return HigherOrderTapProxy | MockInterface
      */
-    public static function spy(): MockInterface
+    public static function spy(): HigherOrderTapProxy | MockInterface
     {
         if (! static::isMock()) {
             $class = static::getMockableClass();

src/Services/Facades/Config.php

@@ -14,6 +14,7 @@ use Siteworxpro\App\Services\Facade;
  * It extends the Facade class from the Illuminate\Support\Facades namespace.
  *
  * @method static array | bool | string | int | null  get(string $key) Retrieve the configuration value for the given key. // @codingStandardsIgnoreStart
+ * @method static void                             set(string $key, mixed $value) Set the configuration value for the given key. // @codingStandardsIgnoreEnd
  *
  * @package Siteworx\App\Facades
  */

src/Services/Facades/RoadRunnerLogger.php

@@ -0,0 +1,39 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Siteworxpro\App\Services\Facades;
+
+use Psr\Container\ContainerExceptionInterface;
+use Psr\Container\NotFoundExceptionInterface;
+use RoadRunner\Logger\Logger;
+use Siteworxpro\App\Services\Facade;
+use Spiral\Goridge\RPC\RPC;
+
+class RoadRunnerLogger extends Facade
+{
+    /**
+     * @throws ContainerExceptionInterface
+     * @throws NotFoundExceptionInterface
+     */
+    public static function getFacadeRoot(): mixed
+    {
+        $container = static::getFacadeContainer();
+        if ($container && $container->has(Logger::class) === false) {
+            $rpc = RPC::create($_SERVER['RR_RPC']);
+            $logger = new Logger($rpc);
+            $container->bind(static::getFacadeAccessor(), function () use ($logger) {
+                return $logger;
+            });
+
+            return $logger;
+        }
+
+        return $container->get(Logger::class);
+    }
+
+    protected static function getFacadeAccessor(): string
+    {
+        return Logger::class;
+    }
+}

src/Services/ServiceProviders/BrokerServiceProvider.php

@@ -8,13 +8,30 @@ use Illuminate\Support\ServiceProvider;
 use Siteworxpro\App\Async\Brokers\Broker;
 use Siteworxpro\App\Services\Facades\Config;
 
+/**
+ * Class BrokerServiceProvider
+ *
+ * This service provider is responsible for binding the Broker implementation
+ * to the Laravel service container based on configuration settings.
+ *
+ * @package Siteworxpro\App\Services\ServiceProviders
+ */
 class BrokerServiceProvider extends ServiceProvider
 {
+    /**
+     * Register services.
+     *
+     * This method binds the Broker interface to a specific implementation
+     * based on the configuration defined in 'queue.broker' and 'queue.broker_config'.
+     *
+     * @return void
+     * @throws \RuntimeException if the specified broker class does not exist.
+     */
     public function register(): void
     {
         $this->app->singleton(Broker::class, function (): Broker {
             $configName = Config::get('queue.broker');
-            $brokerConfig = Config::get('queue.' . $configName) ?? [];
+            $brokerConfig = Config::get('queue.broker_config.' . $configName) ?? [];
 
             $brokerClass = Broker::BROKER_TYPES[$configName] ?? null;
 

src/Services/ServiceProviders/DispatcherServiceProvider.php

@@ -7,6 +7,11 @@ namespace Siteworxpro\App\Services\ServiceProviders;
 use Illuminate\Support\ServiceProvider;
 use Siteworxpro\App\Events\Dispatcher;
 
+/**
+ * Class DispatcherServiceProvider
+ *
+ * @package Siteworxpro\App\Services\ServiceProviders
+ */
 class DispatcherServiceProvider extends ServiceProvider
 {
     public function register(): void

src/Services/ServiceProviders/LoggerServiceProvider.php

@@ -6,13 +6,19 @@ namespace Siteworxpro\App\Services\ServiceProviders;
 
 use Illuminate\Support\ServiceProvider;
 use Siteworxpro\App\Log\Logger;
+use Siteworxpro\App\Services\Facades\Config;
 
+/**
+ * Class LoggerServiceProvider
+ *
+ * @package Siteworxpro\App\Services\ServiceProviders
+ */
 class LoggerServiceProvider extends ServiceProvider
 {
     public function register(): void
     {
         $this->app->singleton(Logger::class, function () {
-            return new Logger();
+            return new Logger(Config::get('app.log_level'));
         });
     }
 }

src/Services/ServiceProviders/RedisServiceProvider.php

@@ -8,6 +8,13 @@ use Illuminate\Support\ServiceProvider;
 use Predis\Client;
 use Siteworxpro\App\Services\Facades\Config;
 
+/**
+ * Class RedisServiceProvider
+ *
+ * This service provider registers a Redis client as a singleton in the application container.
+ *
+ * @package Siteworxpro\App\Services\ServiceProviders
+ */
 class RedisServiceProvider extends ServiceProvider
 {
     public function register(): void

tests/Attributes/Guards/JwtTest.php

@@ -0,0 +1,49 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Siteworxpro\Tests\Attributes\Guards;
+
+use Siteworxpro\App\Attributes\Guards\Jwt;
+use Siteworxpro\App\Services\Facades\Config;
+use Siteworxpro\Tests\Unit;
+
+class JwtTest extends Unit
+{
+    public function testGetsClassFromConfig(): void
+    {
+        Config::set('jwt.issuer', 'default-issuer');
+        Config::set('jwt.audience', 'default-audience');
+
+        $reflection = new \ReflectionClass(TestClass::class);
+        $attributes = $reflection->getAttributes(Jwt::class);
+        $this->assertCount(1, $attributes);
+
+        /** @var Jwt $instance */
+        $instance = $attributes[0]->newInstance();
+        $this->assertEquals('default-audience', $instance->getAudience());
+        $this->assertEquals('default-issuer', $instance->getIssuer());
+    }
+
+    public function testGetsClassFromCustom(): void
+    {
+        $reflection = new \ReflectionClass(TestClassSpecific::class);
+        $attributes = $reflection->getAttributes(Jwt::class);
+        $this->assertCount(1, $attributes);
+
+        /** @var Jwt $instance */
+        $instance = $attributes[0]->newInstance();
+        $this->assertEquals('custom-audience', $instance->getAudience());
+        $this->assertEquals('custom-issuer', $instance->getIssuer());
+    }
+}
+
+#[Jwt]
+class TestClass // @codingStandardsIgnoreLine
+{
+}
+
+#[Jwt('custom-issuer', 'custom-audience')]
+class TestClassSpecific // @codingStandardsIgnoreLine
+{
+}

tests/Attributes/Guards/ScopeTest.php

@@ -0,0 +1,43 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Siteworxpro\Tests\Attributes\Guards;
+
+use Siteworxpro\App\Attributes\Guards\Scope;
+use Siteworxpro\Tests\Unit;
+
+class ScopeTest extends Unit
+{
+    public function testGetsClassSingle(): void
+    {
+        $reflection = new \ReflectionClass(TestClassSingle::class);
+        $attributes = $reflection->getAttributes(Scope::class);
+        $this->assertCount(1, $attributes);
+
+        /** @var Scope $instance */
+        $instance = $attributes[0]->newInstance();
+        $this->assertEquals(['read:users'], $instance->getScopes());
+    }
+
+    public function testGetsClassFromCustom(): void
+    {
+        $reflection = new \ReflectionClass(TestClassMultiple::class);
+        $attributes = $reflection->getAttributes(Scope::class);
+        $this->assertCount(1, $attributes);
+
+        /** @var Scope $instance */
+        $instance = $attributes[0]->newInstance();
+        $this->assertEquals(['read:users', 'write:users'], $instance->getScopes());
+    }
+}
+
+#[Scope(['read:users', 'write:users'])]
+class TestClassMultiple // @codingStandardsIgnoreLine
+{
+}
+
+#[Scope(['read:users'])]
+class TestClassSingle // @codingStandardsIgnoreLine
+{
+}

tests/Attributes/HandlesMessageTest.php

@@ -0,0 +1,25 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Siteworxpro\Tests\Attributes;
+
+use Siteworxpro\App\Attributes\Async\HandlesMessage;
+use Siteworxpro\Tests\Unit;
+
+class HandlesMessageTest extends Unit
+{
+    public function testGetsClass(): void
+    {
+        $class = new #[HandlesMessage('Siteworxpro\Tests\Attributes\TestClass')] class {
+        };
+
+        $reflection = new \ReflectionClass($class);
+        $attributes = $reflection->getAttributes(HandlesMessage::class);
+        $this->assertCount(1, $attributes);
+
+        /** @var HandlesMessage $instance */
+        $instance = $attributes[0]->newInstance();
+        $this->assertEquals('Siteworxpro\Tests\Attributes\TestClass', $instance->getMessageClass());
+    }
+}

tests/Controllers/IndexControllerTest.php

@@ -22,4 +22,19 @@ class IndexControllerTest extends AbstractController
         $this->assertEquals(200, $response->getStatusCode());
         $this->assertEquals('{"status_code":200,"message":"Server is running"}', (string)$response->getBody());
     }
+
+    /**
+     * @throws \JsonException
+     */
+    public function testPost(): void
+    {
+        $this->assertTrue(true);
+
+        $controller = new IndexController();
+
+        $response = $controller->post($this->getMockRequest());
+
+        $this->assertEquals(200, $response->getStatusCode());
+        $this->assertEquals('{"status_code":200,"message":"Server is running"}', (string)$response->getBody());
+    }
 }

tests/Events/Listeners/ConnectedTest.php

@@ -0,0 +1,47 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Siteworxpro\Tests\Events\Listeners;
+
+use Illuminate\Database\Events\ConnectionEstablished;
+use Psr\Container\ContainerExceptionInterface;
+use Psr\Container\NotFoundExceptionInterface;
+use Psr\Log\LogLevel;
+use Siteworxpro\App\Events\Listeners\Database\Connected;
+use Siteworxpro\App\Log\Logger;
+use Siteworxpro\Tests\Unit;
+
+class ConnectedTest extends Unit
+{
+    /**
+     * @throws ContainerExceptionInterface
+     * @throws \ReflectionException
+     * @throws NotFoundExceptionInterface
+     */
+    protected function setUp(): void
+    {
+        parent::setUp();
+
+        $inputBuffer = fopen('php://memory', 'r+');
+        $logger = new Logger(LogLevel::DEBUG, $inputBuffer);
+        \Siteworxpro\App\Services\Facades\Logger::getFacadeContainer()->bind(Logger::class, fn() => $logger);
+    }
+
+    public function testHandlesEvent()
+    {
+        $this->expectNotToPerformAssertions();
+
+        $connectedEvent = $this->createMock(ConnectionEstablished::class);
+        $listener = new Connected();
+
+        $listener->__invoke($connectedEvent);
+    }
+
+    public function testThrowsException()
+    {
+        $this->expectException(\TypeError::class);
+        $listener = new Connected();
+        $listener->__invoke(new \stdClass());
+    }
+}

tests/Facades/DispatcherTest.php

@@ -0,0 +1,20 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Siteworxpro\Tests\Facades;
+
+use Siteworxpro\App\Services\Facades\Dispatcher;
+
+class DispatcherTest extends AbstractFacade
+{
+    protected function getFacadeClass(): string
+    {
+        return Dispatcher::class;
+    }
+
+    protected function getConcrete(): string
+    {
+        return \Siteworxpro\App\Events\Dispatcher::class;
+    }
+}

tests/Facades/LoggerTest.php

@@ -0,0 +1,20 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Siteworxpro\Tests\Facades;
+
+use Siteworxpro\App\Services\Facades\Logger;
+
+class LoggerTest extends AbstractFacade
+{
+    protected function getFacadeClass(): string
+    {
+        return Logger::class;
+    }
+
+    protected function getConcrete(): string
+    {
+        return \Siteworxpro\App\Log\Logger::class;
+    }
+}

tests/Helpers/UlidTest.php

@@ -0,0 +1,19 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Siteworxpro\Tests\Helpers;
+
+use Siteworxpro\App\Helpers\Env;
+use Siteworxpro\App\Helpers\Ulid;
+use Siteworxpro\Tests\Unit;
+
+class UlidTest extends Unit
+{
+    public function testGetString(): void
+    {
+        $ulid = Ulid::generate();
+        $this->assertIsString($ulid);
+        $this->assertEquals(16, strlen($ulid));
+    }
+}

tests/Http/Middleware/CorsMiddlewareTest.php

@@ -11,7 +11,7 @@ use Siteworxpro\App\Http\Middleware\CorsMiddleware;
 use Siteworxpro\App\Services\Facades\Config;
 use Siteworxpro\Tests\Unit;
 
-class CorsMiddlewareTest extends Unit
+class CorsMiddlewareTest extends Middleware
 {
     public function testAllowsConfiguredOrigin(): void
     {
@@ -80,22 +80,4 @@ class CorsMiddlewareTest extends Unit
 
         $this->assertEquals('true', $response->getHeaderLine('Access-Control-Allow-Credentials'));
     }
-
-    private function mockHandler(Response $response): RequestHandlerInterface
-    {
-        return new class ($response) implements RequestHandlerInterface {
-            private Response $response;
-
-            public function __construct(Response $response)
-            {
-                $this->response = $response;
-            }
-
-            public function handle(
-                \Psr\Http\Message\ServerRequestInterface $request
-            ): \Psr\Http\Message\ResponseInterface {
-                return $this->response;
-            }
-        };
-    }
 }

tests/Http/Middleware/JwtMiddlewareTest.php

@@ -0,0 +1,230 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Siteworxpro\Tests\Http\Middleware;
+
+use DateTimeImmutable;
+use Lcobucci\JWT\JwtFacade;
+use Lcobucci\JWT\Signer\Hmac\Sha256;
+use Lcobucci\JWT\Signer\Key\InMemory;
+use Lcobucci\JWT\Token\Builder;
+use League\Route\Dispatcher;
+use Nyholm\Psr7\Response;
+use Nyholm\Psr7\ServerRequest;
+use Siteworxpro\App\Attributes\Guards\Jwt;
+use Siteworxpro\App\Http\Middleware\JwtMiddleware;
+use Siteworxpro\App\Services\Facades\Config;
+use Siteworxpro\HttpStatus\CodesEnum;
+
+class JwtMiddlewareTest extends Middleware
+{
+    private const string TEST_SIGNING_KEY = 'test_signing_key_123456444478901234';
+
+    public function getClass(): object
+    {
+        return new class {
+            public function getCallable(): array
+            {
+                return [$this, 'index'];
+            }
+
+            #[Jwt]
+            public function index()
+            {
+                // Dummy method for testing
+            }
+        };
+    }
+
+    protected function setUp(): void
+    {
+        parent::setUp();
+        Config::set('jwt.signing_key', self::TEST_SIGNING_KEY);
+    }
+
+    /**
+     * @throws \JsonException
+     */
+    public function testIgnoresNoJwtAttribute()
+    {
+        $class = new class {
+            public function getCallable(): array
+            {
+                return [ $this, 'index' ];
+            }
+
+            public function index()
+            {
+                // Dummy method for testing
+            }
+        };
+
+        $handler = \Mockery::mock(Dispatcher::class);
+        $handler->shouldReceive('getMiddlewareStack')
+            ->andReturn([$class]);
+
+        $handler
+            ->shouldReceive('handle')
+            ->once()
+            ->andReturn(new Response(200));
+
+        $request = new ServerRequest('GET', '/');
+        $middleware = new JwtMiddleware();
+        $response = $middleware->process($request, $handler);
+        $this->assertEquals(CodesEnum::OK->value, $response->getStatusCode());
+    }
+
+    /**
+     * @throws \JsonException
+     */
+    public function testIgnoresJwtAttributeButNoToken()
+    {
+        $class = $this->getClass();
+
+        $handler = \Mockery::mock(Dispatcher::class);
+        $handler->shouldReceive('getMiddlewareStack')
+            ->andReturn([$class]);
+
+        $request = new ServerRequest('GET', '/');
+        $middleware = new JwtMiddleware();
+        $response = $middleware->process($request, $handler);
+        $this->assertEquals(CodesEnum::UNAUTHORIZED->value, $response->getStatusCode());
+    }
+
+    /**
+     * @throws \JsonException
+     */
+    public function testInvalidToken()
+    {
+        $class = $this->getClass();
+
+        $handler = \Mockery::mock(Dispatcher::class);
+        $handler->shouldReceive('getMiddlewareStack')
+            ->andReturn([$class]);
+
+        $request = new ServerRequest('GET', '/');
+        $request = $request->withHeader('Authorization', 'Bearer ' . 'invalid_token_string');
+        $middleware = new JwtMiddleware();
+        $response = $middleware->process($request, $handler);
+        $this->assertEquals(CodesEnum::UNAUTHORIZED->value, $response->getStatusCode());
+        $this->assertStringContainsString(
+            'Unauthorized: Invalid token',
+            $response->getBody()->getContents()
+        );
+    }
+
+    /**
+     * @throws \JsonException
+     */
+    public function testJwtAttributeWithTokenButWrongAud()
+    {
+        $class = $this->getClass();
+
+        $handler = \Mockery::mock(Dispatcher::class);
+        $handler->shouldReceive('getMiddlewareStack')
+            ->andReturn([$class]);
+
+        $request = new ServerRequest('GET', '/');
+        $request = $request->withHeader('Authorization', 'Bearer ' . $this->getJwt());
+        $middleware = new JwtMiddleware();
+        $response = $middleware->process($request, $handler);
+        $this->assertEquals(CodesEnum::UNAUTHORIZED->value, $response->getStatusCode());
+        $this->assertStringContainsString(
+            'The token is not allowed to be used by this audience',
+            $response->getBody()->getContents()
+        );
+    }
+
+    /**
+     * @throws \JsonException
+     */
+    public function testJwtAttributeWithTokenButWrongIss()
+    {
+        Config::set('jwt.audience', 'https://client-app.io');
+
+        $class = $this->getClass();
+
+        $handler = \Mockery::mock(Dispatcher::class);
+        $handler->shouldReceive('getMiddlewareStack')
+            ->andReturn([$class]);
+
+        $request = new ServerRequest('GET', '/');
+        $request = $request->withHeader('Authorization', 'Bearer ' . $this->getJwt());
+        $middleware = new JwtMiddleware();
+        $response = $middleware->process($request, $handler);
+        $this->assertEquals(CodesEnum::UNAUTHORIZED->value, $response->getStatusCode());
+        $this->assertStringContainsString(
+            'The token was not issued by the given issuers',
+            $response->getBody()->getContents()
+        );
+    }
+
+    /**
+     * @throws \JsonException
+     */
+    public function testJwtAttributeWithTokenWithDiffIssuer()
+    {
+        Config::set('jwt.audience', 'https://client-app.io');
+        Config::set('jwt.issuer', 'https://different-issuer.io');
+
+        $class = $this->getClass();
+
+        $handler = \Mockery::mock(Dispatcher::class);
+        $handler->shouldReceive('getMiddlewareStack')
+            ->andReturn([$class]);
+
+        $request = new ServerRequest('GET', '/');
+        $request = $request->withHeader('Authorization', 'Bearer ' . $this->getJwt());
+        $middleware = new JwtMiddleware();
+        $response = $middleware->process($request, $handler);
+        $this->assertEquals(CodesEnum::UNAUTHORIZED->value, $response->getStatusCode());
+        $this->assertStringContainsString(
+            'The token was not issued by the given issuers',
+            $response->getBody()->getContents()
+        );
+    }
+
+    public function testJwtAttributeWithToken()
+    {
+        Config::set('jwt.audience', 'https://client-app.io');
+        Config::set('jwt.issuer', 'https://api.my-awesome-app.io');
+
+        $class = $this->getClass();
+
+        $handler = \Mockery::mock(Dispatcher::class);
+        $handler->shouldReceive('getMiddlewareStack')
+            ->andReturn([$class]);
+
+        $handler
+            ->shouldReceive('handle')
+            ->once()
+            ->andReturn(new Response(200));
+
+        $request = new ServerRequest('GET', '/');
+        $request = $request->withHeader('Authorization', 'Bearer ' . $this->getJwt());
+        $middleware = new JwtMiddleware();
+        $response = $middleware->process($request, $handler);
+        $this->assertEquals(CodesEnum::OK->value, $response->getStatusCode());
+    }
+
+    private function getJwt(): string
+    {
+        $key = InMemory::plainText(self::TEST_SIGNING_KEY);
+        $signer = new Sha256();
+
+        $token = new JwtFacade()->issue(
+            $signer,
+            $key,
+            static fn (
+                Builder $builder,
+                DateTimeImmutable $issuedAt
+            ): Builder => $builder
+                ->issuedBy('https://api.my-awesome-app.io')
+                ->permittedFor('https://client-app.io')
+                ->expiresAt($issuedAt->modify('+10 minutes'))
+        );
+
+        return $token->toString();
+    }
+}

tests/Http/Middleware/Middleware.php

@@ -0,0 +1,32 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Siteworxpro\Tests\Http\Middleware;
+
+use Nyholm\Psr7\Response;
+use Psr\Http\Message\ResponseInterface;
+use Psr\Http\Message\ServerRequestInterface;
+use Psr\Http\Server\RequestHandlerInterface;
+use Siteworxpro\Tests\Unit;
+
+abstract class Middleware extends Unit
+{
+    protected function mockHandler(Response $response): RequestHandlerInterface
+    {
+        return new class ($response) implements RequestHandlerInterface {
+            private Response $response;
+
+            public function __construct(Response $response)
+            {
+                $this->response = $response;
+            }
+
+            public function handle(
+                ServerRequestInterface $request
+            ): ResponseInterface {
+                return $this->response;
+            }
+        };
+    }
+}

tests/Http/Middleware/ScopeMiddlewareTest.php

@@ -0,0 +1,111 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Siteworxpro\Tests\Http\Middleware;
+
+use League\Route\Dispatcher;
+use Nyholm\Psr7\Response;
+use Nyholm\Psr7\ServerRequest;
+use Siteworxpro\App\Attributes\Guards\Scope;
+use Siteworxpro\App\Http\Middleware\ScopeMiddleware;
+use Siteworxpro\HttpStatus\CodesEnum;
+
+class ScopeMiddlewareTest extends Middleware
+{
+    /**
+     * @throws \ReflectionException
+     * @throws \JsonException
+     */
+    public function testHandlesNoScopes()
+    {
+        $class = new class {
+            public function getCallable(): array
+            {
+                return [ $this, 'index' ];
+            }
+
+            public function index()
+            {
+                // Dummy method for testing
+            }
+        };
+
+        $handler = \Mockery::mock(Dispatcher::class);
+        $handler->shouldReceive('getMiddlewareStack')
+            ->andReturn([$class]);
+
+        $handler
+            ->shouldReceive('handle')
+            ->once()
+            ->andReturn(new Response(200));
+
+        $request = new ServerRequest('GET', '/');
+        $middleware = new ScopeMiddleware();
+        $response = $middleware->process($request, $handler);
+        $this->assertEquals(200, $response->getStatusCode());
+    }
+
+    /**
+     * @throws \ReflectionException
+     * @throws \JsonException
+     */
+    public function testAllowsWithScope()
+    {
+        $class = new class {
+            public function getCallable(): array
+            {
+                return [ $this, 'index' ];
+            }
+
+            #[Scope(['admin'])]
+            public function index()
+            {
+                // Dummy method for testing
+            }
+        };
+
+        $handler = \Mockery::mock(Dispatcher::class);
+        $handler->shouldReceive('getMiddlewareStack')
+            ->andReturn([$class]);
+
+        $handler
+            ->shouldReceive('handle')
+            ->once()
+            ->andReturn(new Response(200));
+
+        $request = new ServerRequest('GET', '/')->withAttribute('scope', ['admin', 'user']);
+        $middleware = new ScopeMiddleware();
+        $response = $middleware->process($request, $handler);
+        $this->assertEquals(CodesEnum::OK->value, $response->getStatusCode());
+    }
+
+    /**
+     * @throws \ReflectionException
+     * @throws \JsonException
+     */
+    public function testDisallowsWithScope()
+    {
+        $class = new class {
+            public function getCallable(): array
+            {
+                return [ $this, 'index' ];
+            }
+
+            #[Scope(['admin'])]
+            public function index()
+            {
+                // Dummy method for testing
+            }
+        };
+
+        $handler = \Mockery::mock(Dispatcher::class);
+        $handler->shouldReceive('getMiddlewareStack')
+            ->andReturn([$class]);
+
+        $request = new ServerRequest('GET', '/');
+        $middleware = new ScopeMiddleware();
+        $response = $middleware->process($request, $handler);
+        $this->assertEquals(CodesEnum::FORBIDDEN->value, $response->getStatusCode());
+    }
+}

tests/Log/LoggerRpcTest.php

@@ -0,0 +1,161 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Siteworxpro\Tests\Log;
+
+use Mockery;
+use Psr\Container\ContainerExceptionInterface;
+use Psr\Container\NotFoundExceptionInterface;
+use Psr\Log\LoggerInterface;
+use Psr\Log\LogLevel;
+use Siteworxpro\App\Log\Logger;
+use Siteworxpro\Tests\Unit;
+
+class LoggerRpcTest extends Unit
+{
+    protected function tearDown(): void
+    {
+        parent::tearDown();
+        unset($_SERVER['RR_RPC']);
+    }
+
+    /**
+     * @throws ContainerExceptionInterface
+     * @throws NotFoundExceptionInterface
+     * @throws \Throwable
+     */
+    public function testLogsDebugMessageWhenLevelIsDebug(): void
+    {
+        $this->expectNotToPerformAssertions();
+
+        $_SERVER['RR_RPC'] = 'tcp://127.0.0.1:6001';
+
+        $mock = Mockery::mock(LoggerInterface::class);
+        $mock->expects('debug')
+            ->with('message', ['key' => 'value'])
+            ->times(1);
+
+        \Siteworxpro\App\Services\Facades\Logger::getFacadeContainer()
+            ->bind(\RoadRunner\Logger\Logger::class, function () use ($mock) {
+                return $mock;
+            });
+
+        $inputBuffer = fopen('php://memory', 'r+');
+        $logger = new Logger(LogLevel::DEBUG, $inputBuffer);
+        $logger->debug('message', ['key' => 'value']);
+
+        $mock->shouldHaveReceived('debug');
+    }
+
+    /**
+     * @throws ContainerExceptionInterface
+     * @throws NotFoundExceptionInterface
+     */
+    public function testLogsDebugMessageWhenLevelIsInfoNotice(): void
+    {
+        $this->expectNotToPerformAssertions();
+
+        $_SERVER['RR_RPC'] = 'tcp://127.0.0.1:6001';
+
+        $mock = Mockery::mock(LoggerInterface::class);
+        $mock->expects('info')
+            ->with('message', ['key' => 'value'])
+            ->times(2);
+
+        \Siteworxpro\App\Services\Facades\Logger::getFacadeContainer()
+            ->bind(\RoadRunner\Logger\Logger::class, function () use ($mock) {
+                return $mock;
+            });
+
+        $inputBuffer = fopen('php://memory', 'r+');
+        $logger = new Logger(LogLevel::DEBUG, $inputBuffer);
+        $logger->info('message', ['key' => 'value']);
+        $logger->notice('message', ['key' => 'value']);
+
+        $mock->shouldHaveReceived('info')->times(2);
+    }
+
+    /**
+     * @throws ContainerExceptionInterface
+     * @throws NotFoundExceptionInterface
+     */
+    public function testLogsDebugMessageWhenLevelIsInfoWarning(): void
+    {
+        $this->expectNotToPerformAssertions();
+
+        $_SERVER['RR_RPC'] = 'tcp://127.0.0.1:6001';
+
+        $mock = Mockery::mock(LoggerInterface::class);
+        $mock->expects('warning')
+            ->with('message', ['key' => 'value'])
+            ->times(1);
+
+        \Siteworxpro\App\Services\Facades\Logger::getFacadeContainer()
+            ->bind(\RoadRunner\Logger\Logger::class, function () use ($mock) {
+                return $mock;
+            });
+
+        $inputBuffer = fopen('php://memory', 'r+');
+        $logger = new Logger(LogLevel::DEBUG, $inputBuffer);
+        $logger->warning('message', ['key' => 'value']);
+
+        $mock->shouldHaveReceived('warning');
+    }
+
+    /**
+     * @throws ContainerExceptionInterface
+     * @throws NotFoundExceptionInterface
+     */
+    public function testLogsDebugMessageWhenLevelIsInfoError(): void
+    {
+        $this->expectNotToPerformAssertions();
+
+        $_SERVER['RR_RPC'] = 'tcp://127.0.0.1:6001';
+
+        $mock = Mockery::mock(LoggerInterface::class);
+        $mock->expects('error')
+            ->with('message', ['key' => 'value'])
+            ->times(4);
+
+        \Siteworxpro\App\Services\Facades\Logger::getFacadeContainer()
+            ->bind(\RoadRunner\Logger\Logger::class, function () use ($mock) {
+                return $mock;
+            });
+
+        $inputBuffer = fopen('php://memory', 'r+');
+        $logger = new Logger(LogLevel::DEBUG, $inputBuffer);
+        $logger->error('message', ['key' => 'value']);
+        $logger->critical('message', ['key' => 'value']);
+        $logger->alert('message', ['key' => 'value']);
+        $logger->emergency('message', ['key' => 'value']);
+
+        $mock->shouldHaveReceived('error')->times(4);
+    }
+
+    /**
+     * @throws ContainerExceptionInterface
+     * @throws NotFoundExceptionInterface
+     */
+    public function testLogsLog(): void
+    {
+        $this->expectNotToPerformAssertions();
+
+        $_SERVER['RR_RPC'] = 'tcp://127.0.0.1:6001';
+
+        $mock = Mockery::mock(LoggerInterface::class);
+        $mock->expects('log')
+            ->with('notaloglevel', 'message', ['key' => 'value']);
+
+        \Siteworxpro\App\Services\Facades\Logger::getFacadeContainer()
+            ->bind(\RoadRunner\Logger\Logger::class, function () use ($mock) {
+                return $mock;
+            });
+
+        $inputBuffer = fopen('php://memory', 'r+');
+        $logger = new Logger(LogLevel::DEBUG, $inputBuffer);
+        $logger->log('notaloglevel', 'message', ['key' => 'value']);
+
+        $mock->shouldHaveReceived('log')->times(1);
+    }
+}

tests/Log/LoggerTest.php

@@ -0,0 +1,229 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Siteworxpro\Tests\Log;
+
+use Psr\Container\ContainerExceptionInterface;
+use Psr\Container\NotFoundExceptionInterface;
+use Psr\Log\LogLevel;
+use Siteworxpro\App\Log\Logger;
+use Siteworxpro\Tests\Unit;
+
+class LoggerTest extends Unit
+{
+    /**
+     * @throws ContainerExceptionInterface
+     * @throws NotFoundExceptionInterface
+     */
+    private function getLoggerWithBuffer(string $logLevel): array
+    {
+        $inputBuffer = fopen('php://memory', 'r+');
+        return [new Logger($logLevel, $inputBuffer), $inputBuffer];
+    }
+
+    private function getContents($inputBuffer): string
+    {
+        return stream_get_contents($inputBuffer, -1, 0);
+    }
+
+    /**
+     * @throws ContainerExceptionInterface
+     * @throws NotFoundExceptionInterface
+     */
+    private function testLogLevel(string $level): void
+    {
+        [$logger, $inputBuffer] = $this->getLoggerWithBuffer($level);
+        $logger->$level('message', ['key' => 'value']);
+        $output = $this->getContents($inputBuffer);
+
+        $this->assertNotEmpty($output);
+        $decoded = json_decode($output, true);
+        $this->assertEquals('message', $decoded['message']);
+        $this->assertEquals('value', $decoded['context']['key']);
+    }
+
+    /**
+     * @throws ContainerExceptionInterface
+     * @throws NotFoundExceptionInterface
+     */
+    private function testLogLevelEmpty(string $configLevel, string $logLevel): void
+    {
+        [$logger, $inputBuffer] = $this->getLoggerWithBuffer($configLevel);
+        $logger->$logLevel('message', ['key' => 'value']);
+        $output = $this->getContents($inputBuffer);
+
+        $this->assertEmpty($output);
+    }
+
+    /**
+     * @throws ContainerExceptionInterface
+     * @throws NotFoundExceptionInterface
+     */
+    public function testLogsDebugMessageWhenLevelIsDebug(): void
+    {
+        $this->testLogLevel(LogLevel::DEBUG);
+    }
+
+    /**
+     * @throws ContainerExceptionInterface
+     * @throws NotFoundExceptionInterface
+     */
+    public function testLogsInfoMessageWhenLevelIsInfo(): void
+    {
+        $this->testLogLevel(LogLevel::INFO);
+    }
+
+    /**
+     * @throws ContainerExceptionInterface
+     * @throws NotFoundExceptionInterface
+     */
+    public function testLogsWarningMessageWhenLevelIsWarning(): void
+    {
+        $this->testLogLevel(LogLevel::WARNING);
+    }
+
+    /**
+     * @throws ContainerExceptionInterface
+     * @throws NotFoundExceptionInterface
+     */
+    public function testLogsErrorMessageWhenLevelIsError(): void
+    {
+        $this->testLogLevel(LogLevel::ERROR);
+    }
+
+    /**
+     * @throws ContainerExceptionInterface
+     * @throws NotFoundExceptionInterface
+     */
+    public function testLogsCriticalMessageWhenLevelIsCritical(): void
+    {
+        $this->testLogLevel(LogLevel::CRITICAL);
+    }
+
+    /**
+     * @throws ContainerExceptionInterface
+     * @throws NotFoundExceptionInterface
+     */
+    public function testLogsAlertMessageWhenLevelIsAlert(): void
+    {
+        $this->testLogLevel(LogLevel::ALERT);
+    }
+
+    /**
+     * @throws ContainerExceptionInterface
+     * @throws NotFoundExceptionInterface
+     */
+    public function testLogsEmergencyMessageWhenLevelIsEmergency(): void
+    {
+        $this->testLogLevel(LogLevel::EMERGENCY);
+    }
+
+    /**
+     * @throws ContainerExceptionInterface
+     * @throws NotFoundExceptionInterface
+     */
+    public function testLogsNoticeMessageWhenLevelIsNotice(): void
+    {
+        $this->testLogLevel(LogLevel::NOTICE);
+    }
+
+    /**
+     * @throws ContainerExceptionInterface
+     * @throws NotFoundExceptionInterface
+     */
+    public function testDoesNotLogWhenMinimumLevelIsInfo(): void
+    {
+        $this->testLogLevelEmpty(LogLevel::INFO, LogLevel::DEBUG);
+    }
+
+    /**
+     * @throws ContainerExceptionInterface
+     * @throws NotFoundExceptionInterface
+     */
+    public function testDoesNotLogWhenMinimumLevelIsWarning(): void
+    {
+        $this->testLogLevelEmpty(LogLevel::WARNING, LogLevel::INFO);
+        $this->testLogLevelEmpty(LogLevel::WARNING, LogLevel::DEBUG);
+    }
+
+    /**
+     * @throws NotFoundExceptionInterface
+     * @throws ContainerExceptionInterface
+     */
+    public function testDoesNotLogWhenMinimumLevelIsError(): void
+    {
+        $this->testLogLevelEmpty(LogLevel::ERROR, LogLevel::DEBUG);
+        $this->testLogLevelEmpty(LogLevel::ERROR, LogLevel::INFO);
+        $this->testLogLevelEmpty(LogLevel::ERROR, LogLevel::WARNING);
+    }
+
+    /**
+     * @throws ContainerExceptionInterface
+     * @throws NotFoundExceptionInterface
+     */
+    public function testDoesNotLogWhenMinimumLevelIsNotice(): void
+    {
+        $this->testLogLevelEmpty(LogLevel::NOTICE, LogLevel::DEBUG);
+        $this->testLogLevelEmpty(LogLevel::NOTICE, LogLevel::INFO);
+    }
+
+    /**
+     * @throws ContainerExceptionInterface
+     * @throws NotFoundExceptionInterface
+     */
+    public function testLogsMessageWithEmptyContext(): void
+    {
+        [$logger, $buffer] = $this->getLoggerWithBuffer(LogLevel::INFO);
+
+        $logger->info('Message without context');
+        $output = $this->getContents($buffer);
+
+        $this->assertNotEmpty($output);
+        $decoded = json_decode($output, true);
+        $this->assertEquals('Message without context', $decoded['message']);
+    }
+
+    /**
+     * @throws ContainerExceptionInterface
+     * @throws NotFoundExceptionInterface
+     */
+    public function testLogsMessageWithComplexContext(): void
+    {
+        [$logger, $buffer] = $this->getLoggerWithBuffer(LogLevel::INFO);
+
+        $logger->info('Complex context', [
+            'user_id' => 123,
+            'nested' => ['key' => 'value'],
+            'array' => [1, 2, 3]
+        ]);
+        $output = $this->getContents($buffer);
+
+        $this->assertNotEmpty($output);
+        $decoded = json_decode($output, true);
+        $this->assertEquals(123, $decoded['context']['user_id']);
+        $this->assertEquals('value', $decoded['context']['nested']['key']);
+    }
+
+    /**
+     * @throws ContainerExceptionInterface
+     * @throws NotFoundExceptionInterface
+     */
+    public function testLogsStringableMessage(): void
+    {
+        [$logger, $buffer] = $this->getLoggerWithBuffer(LogLevel::INFO);
+
+        $stringable = new class implements \Stringable {
+            public function __toString(): string
+            {
+                return 'Stringable message';
+            }
+        };
+
+        $logger->info($stringable);
+        $output = $this->getContents($buffer);
+        $this->assertNotEmpty($output);
+        $decoded = json_decode($output, true);
+        $this->assertEquals('Stringable message', $decoded['message']);
+    }
+}

tests/Unit.php

@@ -5,6 +5,7 @@ declare(strict_types=1);
 namespace Siteworxpro\Tests;
 
 use Illuminate\Container\Container;
+use Mockery;
 use PHPUnit\Framework\TestCase;
 use Siteworx\Config\Config as SWConfig;
 use Siteworxpro\App\Services\Facade;
@@ -29,5 +30,6 @@ abstract class Unit extends TestCase
     {
         Config::clearResolvedInstances();
         Facade::setFacadeContainer(null);
+        Mockery::close();
     }
 }