+ Release 5.1.0

CHANGELOG.md

@@ -0,0 +1,31 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [5.1.0] - 2024-10-27
+
+### Added
+
+- Added interface `Throwable` to `BaseExceptionInterface`.
+- Class `Error` was extended from `ErrorException`.
+- Added `MonologProcessor` for Monolog.
+
+### Fixed
+
+- Fixed the PHPDoc type hints for `PHPStan`.
+- Fixed the `ResourceException` class and sibling classes.
+
+### Changed
+
+- Rename method `BaseExceptionInterface::template()` to `BaseExceptionInterface::getTemplate()`.
+- Update documentation (English and Russian).
+- Exceptions are no longer added to the `exception registry`. 
+This functionality is disabled by default.
+
+### Removed
+

README.md

@@ -2,8 +2,8 @@ BaseException [![PHP Composer](https://github.com/EdmondDantes/amphp-pool/action
 
 =============
 
-Base Exception Library for PHP 8.2+
-(The latest version: 5.0.0)
+Base Exception Library for PHP 8.3+
+(The latest version: 5.1.0)
 
 Missions:
 
@@ -87,6 +87,29 @@ List of parameters:
 
 ```
 
+## Monolog integration
+
+The processor for `Monolog` allows populating exception metadata in the log.
+
+```php
+<?php
+
+use Monolog\Level;
+use Monolog\Logger;
+use Monolog\Handler\StreamHandler;
+use IfCastle\Exceptions\LoggableException;
+use IfCastle\Exceptions\MonologProcessor;
+
+$log = new Logger('name');
+$log->pushProcessor(new MonologProcessor());
+
+// Put some records to the log
+$log->error(
+    'this is a loggable exception', 
+    ['exception' => new LoggableException('this is a loggable exception')]
+);
+```
+
 ## Exception Container
 
 ```php

composer.json

@@ -27,7 +27,8 @@
         "phpunit/phpunit": "^11.2",
         "rector/rector": "^1.2",
         "ifcastle/codestyle": "^0.1.7",
-        "phpstan/phpstan": "^1.12"
+        "phpstan/phpstan": "^1.12",
+        "monolog/monolog": "^3.7"
     },
     "scripts": {
         "test": "vendor/bin/phpunit --coverage-clover=coverage/clover.xml --coverage-filter=src ./tests",

src/BaseException.php

@@ -224,7 +224,7 @@ public function __construct(BaseExceptionInterface|\Throwable|array|string $exce
      * Returns template message.
      */
     #[\Override]
-    public function template(): string
+    public function getTemplate(): string
     {
         return $this->template;
     }
@@ -413,14 +413,14 @@ public function toArray(): array
         }
 
         // override the exception message if the template was defined
-        $message = $this->template() !== '' ? $this->getExceptionData()['message'] ?? '' : $this->getMessage();
+        $message = $this->getTemplate() !== '' ? $this->getExceptionData()['message'] ?? '' : $this->getMessage();
 
         return
         [
             'type'      => static::class,
             'source'    => $this->getSource(),
             'message'   => $message,
-            'template'  => $this->template(),
+            'template'  => $this->getTemplate(),
             'tags'      => $this->getTags(),
             'code'      => $this->getCode(),
             'data'      => $this->getExceptionData(),

src/BaseExceptionInterface.php

@@ -81,7 +81,7 @@ public function getTraceAsString(): string;
     /**
      * Template message.
      */
-    public function template(): string;
+    public function getTemplate(): string;
 
     /**
      * @return string[]

src/Errors/Error.php

@@ -230,7 +230,7 @@ public function appendData(array $data): static
     }
 
     #[\Override]
-    public function template(): string
+    public function getTemplate(): string
     {
         return '';
     }

src/MonologProcessor.php

@@ -0,0 +1,27 @@
+<?php
+declare(strict_types=1);
+
+namespace IfCastle\Exceptions;
+
+use Monolog\LogRecord;
+use Monolog\Processor\ProcessorInterface;
+
+final class MonologProcessor implements ProcessorInterface
+{
+    #[\Override]
+    public function __invoke(LogRecord $record)
+    {
+        if(false === $record->context['exception'] instanceof BaseExceptionInterface) {
+            return $record;
+        }
+
+        $exception                  = $record->context['exception'];
+
+        $record->extra['exception_template']    = $exception->getTemplate();
+        $record->extra['exception_data']        = $exception->getExceptionData();
+        $record->extra['exception_debug']       = $exception->getDebugData();
+        $record->extra['tags']                  = array_merge($record->extra['tags'] ?? [], $exception->getTags());
+
+        return $record;
+    }
+}

src/Registry.php

@@ -19,7 +19,6 @@ class Registry
 {
     /**
      * Flag for global handler.
-     * @var bool
      */
     public static bool $isActive = false;
 

src/Resource/FileSystem/FileCloseError.php

@@ -9,7 +9,11 @@
 class FileCloseError extends ResourceCloseError implements FileSystemExceptionInterface
 {
     protected string $system   = self::SYSTEM;
-
+
+    /**
+     * @param string|object|resource|array<string, scalar|scalar[]> $resource
+     * @param string $type
+     */
     public function __construct(mixed $resource, string $type = 'file')
     {
         parent::__construct($resource, $type);

src/Resource/FileSystem/FileLockFailed.php

@@ -9,8 +9,12 @@
 class FileLockFailed extends ResourceLockFailed implements FileSystemExceptionInterface
 {
     protected string $system   = self::SYSTEM;
-
-    public function __construct($resource, $type = 'file')
+
+    /**
+     * @param string|object|resource|array<string, scalar|scalar[]> $resource
+     * @param string $type
+     */
+    public function __construct(mixed $resource, string $type = 'file')
     {
         parent::__construct($resource, $type);
     }

src/Resource/FileSystem/FileNotExists.php

@@ -9,8 +9,12 @@
 class FileNotExists extends ResourceNotExists implements FileSystemExceptionInterface
 {
     protected string $system   = self::SYSTEM;
-
-    public function __construct($resource, $type = 'file')
+
+    /**
+     * @param string|object|resource|array<string, scalar|scalar[]> $resource
+     * @param string $type
+     */
+    public function __construct(mixed $resource, string $type = 'file')
     {
         parent::__construct($resource, $type);
     }

src/Resource/FileSystem/FileNotReadable.php

@@ -9,8 +9,12 @@
 class FileNotReadable extends ResourceNotReadable implements FileSystemExceptionInterface
 {
     protected string $system   = self::SYSTEM;
-
-    public function __construct($resource, string $type = 'file')
+
+    /**
+     * @param string|object|resource|array<string, scalar|scalar[]> $resource
+     * @param string $type
+     */
+    public function __construct(mixed $resource, string $type = 'file')
     {
         parent::__construct($resource, $type);
     }

src/Resource/FileSystem/FileNotWritable.php

@@ -9,8 +9,12 @@
 class FileNotWritable extends ResourceNotWritable implements FileSystemExceptionInterface
 {
     protected string $system   = self::SYSTEM;
-
-    public function __construct($resource, string $type = 'file')
+
+    /**
+     * @param string|object|resource|array<string, scalar|scalar[]> $resource
+     * @param string $type
+     */
+    public function __construct(mixed $resource, string $type = 'file')
     {
         parent::__construct($resource, $type);
     }

src/Resource/FileSystem/FileOpenError.php

@@ -9,8 +9,12 @@
 class FileOpenError extends ResourceOpenError implements FileSystemExceptionInterface
 {
     protected string $system   = self::SYSTEM;
-
-    public function __construct($resource, string $type = 'file')
+
+    /**
+     * @param string|object|resource|array<string, scalar|scalar[]> $resource
+     * @param string $type
+     */
+    public function __construct(mixed $resource, string $type = 'file')
     {
         parent::__construct($resource, $type);
     }

src/Resource/FileSystem/FileReadError.php

@@ -9,8 +9,12 @@
 class FileReadError extends ResourceReadError implements FileSystemExceptionInterface
 {
     protected string $system   = self::SYSTEM;
-
-    public function __construct($resource, string $type = 'file')
+
+    /**
+     * @param string|object|resource|array<string, scalar|scalar[]> $resource
+     * @param string $type
+     */
+    public function __construct(mixed $resource, string $type = 'file')
     {
         parent::__construct($resource, $type);
     }

src/Resource/FileSystem/FileUnLockFailed.php

@@ -9,8 +9,12 @@
 class FileUnLockFailed extends ResourceUnLockFailed implements FileSystemExceptionInterface
 {
     protected string $system   = self::SYSTEM;
-
-    public function __construct($resource, $type = 'file')
+
+    /**
+     * @param string|object|resource|array<string, scalar|scalar[]> $resource
+     * @param string $type
+     */
+    public function __construct(mixed $resource, string $type = 'file')
     {
         parent::__construct($resource, $type);
     }