feat(exceptions): add new exception classes for various modules

- Created `AbstractException` as the base exception class
- Added `AuthenticationException` and `AuthorizationException` under `Auth`
- Added `CacheException` under `Cache`
- Added `ConfigurationException` under `Config`
- Added `ContainerException` under `Container`
- Added `DatabaseException` under `Database`
- Added `EventException` under `Event`
- Added `ExternalServiceException` under `ExternalService`
- Added `FileException` under `File`
- Added `InputException` under `Input`
- Added `LocalizationException` under `Localization`
- Added `MiddlewareException` under `Middleware`
- Added `NetworkException` and `HttpException` under `Network`
- Added `QueueException` under `Queue`
- Added `RoutingException` under `Routing`
- Added `RuntimeException` under `Runtime`
- Added `SecurityException` and `EncryptionException` under `Security`
- Added `SessionException` under `Session`
- Added `SystemException` under `System`
- Added `TemplateException` under `Template`
- Added `ValidationException` and `RuleViolationException` under `Validation`

Author: walmir-silva

src/AbstractErrorMessage.php

@@ -1,3 +1,31 @@
 <?php
 
 declare(strict_types=1);
+
+namespace KaririCode\Exception;
+
+use KaririCode\Exception\Contract\ErrorMessage;
+use KaririCode\Exception\Contract\Throwable;
+
+abstract class AbstractException extends \Exception implements Throwable
+{
+    protected array $context = [];
+
+    public function __construct(ErrorMessage $errorMessage, ?\Throwable $previous = null, array $context = [])
+    {
+        parent::__construct($errorMessage->getMessage(), 0, $previous);
+        $this->context = $context;
+    }
+
+    public function getContext(): array
+    {
+        return $this->context;
+    }
+
+    protected function addContext(string $key, mixed $value): self
+    {
+        $this->context[$key] = $value;
+
+        return $this;
+    }
+}

src/AbstractException.php

@@ -1,3 +1,26 @@
 <?php
 
 declare(strict_types=1);
+
+namespace KaririCode\Exception\Auth;
+
+use KaririCode\Exception\AbstractException;
+use KaririCode\Exception\ExceptionMessage;
+
+final class AuthenticationException extends AbstractException
+{
+    public static function invalidCredentials(): self
+    {
+        return new self(new ExceptionMessage('INVALID_CREDENTIALS', 'Invalid credentials provided'));
+    }
+
+    public static function accountLocked(): self
+    {
+        return new self(new ExceptionMessage('ACCOUNT_LOCKED', 'Account is locked'));
+    }
+
+    public static function twoFactorRequired(): self
+    {
+        return new self(new ExceptionMessage('TWO_FACTOR_REQUIRED', 'Two-factor authentication is required'));
+    }
+}

src/Auth/AuthenticationException.php

@@ -1,3 +1,21 @@
 <?php
 
 declare(strict_types=1);
+
+namespace KaririCode\Exception\Auth;
+
+use KaririCode\Exception\AbstractException;
+use KaririCode\Exception\ExceptionMessage;
+
+final class AuthorizationException extends AbstractException
+{
+    public static function insufficientPermissions(string $action): self
+    {
+        return new self(new ExceptionMessage('INSUFFICIENT_PERMISSIONS', "Insufficient permissions for action: {$action}"));
+    }
+
+    public static function roleRequired(string $role): self
+    {
+        return new self(new ExceptionMessage('ROLE_REQUIRED', "Required role not present: {$role}"));
+    }
+}

src/Auth/AuthorizationException.php

@@ -1,3 +1,26 @@
 <?php
 
 declare(strict_types=1);
+
+namespace KaririCode\Exception\Cache;
+
+use KaririCode\Exception\AbstractException;
+use KaririCode\Exception\ExceptionMessage;
+
+final class CacheException extends AbstractException
+{
+    public static function itemNotFound(string $key): self
+    {
+        return new self(new ExceptionMessage('CACHE_ITEM_NOT_FOUND', "Cache item not found: {$key}"));
+    }
+
+    public static function storageError(string $details): self
+    {
+        return new self(new ExceptionMessage('CACHE_STORAGE_ERROR', "Cache storage error: {$details}"));
+    }
+
+    public static function invalidTtl(int $ttl): self
+    {
+        return new self(new ExceptionMessage('INVALID_TTL', "Invalid TTL value: {$ttl}"));
+    }
+}

src/Cache/CacheException.php

@@ -1,3 +1,26 @@
 <?php
 
 declare(strict_types=1);
+
+namespace KaririCode\Exception\Config;
+
+use KaririCode\Exception\AbstractException;
+use KaririCode\Exception\ExceptionMessage;
+
+final class ConfigurationException extends AbstractException
+{
+    public static function missingKey(string $key): self
+    {
+        return new self(new ExceptionMessage('MISSING_CONFIG_KEY', "Missing configuration key: {$key}"));
+    }
+
+    public static function invalidValue(string $key, mixed $value): self
+    {
+        return new self(new ExceptionMessage('INVALID_CONFIG_VALUE', "Invalid configuration value for key '{$key}': " . var_export($value, true)));
+    }
+
+    public static function environmentNotSet(string $envVar): self
+    {
+        return new self(new ExceptionMessage('ENVIRONMENT_NOT_SET', "Environment variable not set: {$envVar}"));
+    }
+}

src/CommonErrorMessages.php

@@ -1,3 +1,21 @@
 <?php
 
 declare(strict_types=1);
+
+namespace KaririCode\Exception\Container;
+
+use KaririCode\Exception\AbstractException;
+use KaririCode\Exception\ExceptionMessage;
+
+final class ContainerException extends AbstractException
+{
+    public static function serviceNotFound(string $serviceId): self
+    {
+        return new self(new ExceptionMessage('SERVICE_NOT_FOUND', "Service not found in container: {$serviceId}"));
+    }
+
+    public static function circularDependency(string $serviceId): self
+    {
+        return new self(new ExceptionMessage('CIRCULAR_DEPENDENCY', "Circular dependency detected for service: {$serviceId}"));
+    }
+}

src/Config/ConfigurationException.php

@@ -1,3 +1,12 @@
 <?php
 
 declare(strict_types=1);
+
+namespace KaririCode\Exception\Contract;
+
+interface ErrorMessage
+{
+    public function getCode(): string;
+
+    public function getMessage(): string;
+}

src/Container/ContainerException.php

@@ -1,3 +1,12 @@
 <?php
 
 declare(strict_types=1);
+
+namespace KaririCode\Exception\Contract;
+
+use Throwable as GlobalThrowable;
+
+interface Throwable extends GlobalThrowable
+{
+    public function getContext(): array;
+}