From d98fd2c2952113a072060086481d2241d72d728d Mon Sep 17 00:00:00 2001
From: Clemens Schwaighofer <clemens.schwaighofer@egplusww.com>
Date: Fri, 1 Sep 2023 08:52:37 +0900
Subject: [PATCH] Extended Exceptions interface

For more detailed Exception handling and reporting
---
 .gitignore                                    |  2 +
 composer.json                                 | 24 ++++++
 src/Exceptions/Abstracts/CustomException.php  | 43 +++++++++++
 .../Abstracts/Interface/IException.php        | 77 +++++++++++++++++++
 4 files changed, 146 insertions(+)
 create mode 100644 .gitignore
 create mode 100644 composer.json
 create mode 100644 src/Exceptions/Abstracts/CustomException.php
 create mode 100644 src/Exceptions/Abstracts/Interface/IException.php

diff --git a/.gitignore b/.gitignore
new file mode 100644
index 0000000..7579f74
--- /dev/null
+++ b/.gitignore
@@ -0,0 +1,2 @@
+vendor
+composer.lock
diff --git a/composer.json b/composer.json
new file mode 100644
index 0000000..b1c8db5
--- /dev/null
+++ b/composer.json
@@ -0,0 +1,24 @@
+{
+    "name": "egrajp/exceptions-extended",
+    "description": "Extended Exceptions based on the default PHP Exceptions",
+    "type": "library",
+    "license": "MIT",
+    "keywords": [
+        "exceptions"
+    ],
+    "authors": [
+        {
+            "name": "Clemens Schwaighofer",
+            "email": "clemens.schwaighofer@egplusww.com"
+        }
+    ],
+    "autoload": {
+        "classmap": [
+            "src/"
+        ]
+    },
+    "minimum-stability": "dev",
+    "require": {
+		"php": ">=8.2",
+	},
+}
diff --git a/src/Exceptions/Abstracts/CustomException.php b/src/Exceptions/Abstracts/CustomException.php
new file mode 100644
index 0000000..414586d
--- /dev/null
+++ b/src/Exceptions/Abstracts/CustomException.php
@@ -0,0 +1,43 @@
+<?php
+
+namespace Exceptions\Abstracts;
+
+abstract class CustomException extends \Exception implements Interface\IException
+{
+	/**
+	 * constructor that creates empty basic message if no message is set
+	 *
+	 * @param  string          $message
+	 * @param  int             $code
+	 * @param  \Throwable|null $previous
+	 */
+	public function __construct(string $message = '', int $code = 0, ?\Throwable $previous = null)
+	{
+		if (empty($message)) {
+			throw new $this('Unknown ' . get_class($this), $code, $previous);
+		}
+		parent::__construct($message, $code, $previous);
+	}
+
+	/**
+	 * add more information to the return exception besides basic info
+	 *
+	 * @return string
+	 */
+	public function __toString()
+	{
+		// chain previous ones (message/code/file/etc)
+		$previous = $this->getPrevious();
+		return get_class($this)
+			. " '{$this->getMessage()}' ({$this->getCode()}) in "
+			. "{$this->getFile()}:{$this->getLine()}\n"
+			. "{$this->getTraceAsString()}"
+			. ($previous !== null ?
+				"\n"
+				. "Previous:\n{$this->getPrevious()}" :
+				''
+			);
+	}
+}
+
+// __END__;
diff --git a/src/Exceptions/Abstracts/Interface/IException.php b/src/Exceptions/Abstracts/Interface/IException.php
new file mode 100644
index 0000000..528edb6
--- /dev/null
+++ b/src/Exceptions/Abstracts/Interface/IException.php
@@ -0,0 +1,77 @@
+<?php
+
+namespace Exceptions\Abstracts\Interface;
+
+interface IException
+{
+	/* Protected methods inherited from Exception class */
+
+	/**
+	 * Exception message
+	 *
+	 * @return string
+	 */
+	public function getMessage(): string;
+
+	/**
+	 * Get previous exceptions
+	 *
+	 * @return \Throwable|null
+	 */
+	public function getPrevious(): ?\Throwable;
+
+	/**
+	 * User-defined Exception code
+	 *
+	 * @return int
+	 */
+	public function getCode(): int;
+
+	/**
+	 * Source filename
+	 *
+	 * @return string
+	 */
+	public function getFile(): string;
+
+	/**
+	 * Source line
+	 *
+	 * @return int
+	 */
+	public function getLine(): int;
+
+	/**
+	 * An array of the backtrace()
+	 *
+	 * @return array<array<mixed>>
+	 */
+	public function getTrace(): array;
+
+	/**
+	 * Formated string of trace
+	 *
+	 * @return string
+	 */
+	public function getTraceAsString(): string;
+
+	/* Overrideable methods inherited from Exception class */
+
+	/**
+	 * formated string for display
+	 *
+	 * @return string
+	 */
+	public function __toString(): string;
+
+	/**
+	 * Undocumented function
+	 *
+	 * @param  string          $message
+	 * @param  int             $code
+	 * @param  \Throwable|null $previous
+	 */
+	public function __construct(string $message = '', int $code = 0, ?\Throwable $previous = null);
+}
+
+// __END__