Initial Version

shared/lib/Exception/BaseException.php

@@ -0,0 +1,175 @@
+<?php
+
+namespace KTXF\Exception;
+
+use Throwable;
+
+/**
+ * Exception is the base class for
+ * all Exceptions.
+ * @link https://php.net/manual/en/class.exception.php
+ */
+class BaseException implements Throwable
+{
+    /** The error message */
+    protected string $message = '';
+
+    /** The error code */
+    protected int $code = 0;
+
+    /** The filename where the error happened  */
+    protected string $file = '';
+
+    /** The line where the error happened */
+    protected int $line = 0;
+
+    /** Previous throwable in chain */
+    protected ?Throwable $previous = null;
+
+    /** Captured stack trace frames (excluding constructor frame) */
+    protected array $trace = [];
+
+    /**
+     * Construct the exception. Note: The message is NOT binary safe.
+     * @link https://php.net/manual/en/exception.construct.php
+     * @param string $message [optional] The Exception message to throw.
+     * @param int $code [optional] The Exception code.
+     * @param null|Throwable $previous [optional] The previous throwable used for the exception chaining.
+     */
+    public function __construct(string $message = "", int $code = 0, ?Throwable $previous = null)
+    {
+        $this->message = $message;
+        $this->code = $code;
+        $this->previous = $previous;
+
+        // Capture backtrace; first element is this constructor call site
+        $bt = debug_backtrace(DEBUG_BACKTRACE_IGNORE_ARGS);
+        if (!empty($bt)) {
+            $first = $bt[0];
+            $this->file = $first['file'] ?? 'unknown';
+            $this->line = $first['line'] ?? 0;
+        }
+        // Exclude current frame for readability
+        $this->trace = array_slice($bt, 1);
+    }
+
+    /**
+     * Clone the exception
+     * Tries to clone the Exception, which results in Fatal error.
+     * @link https://php.net/manual/en/exception.clone.php
+     * @return void
+     */
+    public function __clone(): void
+    {
+        // Mimic internal Exception behavior: cloning not allowed.
+        trigger_error('Trying to clone an uncloneable object of class ' . static::class, E_USER_ERROR);
+    }
+    
+    /**
+     * String representation of the exception
+     * @link https://php.net/manual/en/exception.tostring.php
+     * @return string the string representation of the exception.
+     */
+    public function __toString(): string
+    {
+        return sprintf(
+            "%s: %s in %s:%d\nStack trace:\n%s",
+            static::class,
+            $this->getMessage(),
+            $this->getFile(),
+            $this->getLine(),
+            $this->getTraceAsString()
+        );
+    }
+
+    public function __wakeup(): void
+    {
+        // On wakeup we don't have original trace; reset trace to empty
+        $this->trace = [];
+    }
+
+    /**
+     * Gets the Exception message
+     * @link https://php.net/manual/en/exception.getmessage.php
+     * @return string the Exception message as a string.
+     */
+    final public function getMessage(): string
+    {
+        return $this->message;
+    }
+
+    /**
+     * Gets the Exception code
+     * @link https://php.net/manual/en/exception.getcode.php
+     * @return mixed|int the exception code as integer in
+     * <b>Exception</b> but possibly as other type in
+     * <b>Exception</b> descendants (for example as
+     * string in <b>PDOException</b>).
+     */
+    final public function getCode(): int
+    {
+        return $this->code;
+    }
+
+    /**
+     * Gets the file in which the exception occurred
+     * @link https://php.net/manual/en/exception.getfile.php
+     * @return string the filename in which the exception was created.
+     */
+    final public function getFile(): string
+    {
+        return $this->file;
+    }
+
+    /**
+     * Gets the line in which the exception occurred
+     * @link https://php.net/manual/en/exception.getline.php
+     * @return int the line number where the exception was created.
+     */
+    final public function getLine(): int
+    {
+        return $this->line;
+    }
+
+    /**
+     * Gets the stack trace
+     * @link https://php.net/manual/en/exception.gettrace.php
+     * @return array the Exception stack trace as an array.
+     */
+    final public function getTrace(): array
+    {
+        return $this->trace;
+    }
+
+    /**
+     * Returns previous Exception
+     * @link https://php.net/manual/en/exception.getprevious.php
+     * @return null|Throwable Returns the previous {@see Throwable} if available, or <b>NULL</b> otherwise.
+     * or null otherwise.
+     */
+    final public function getPrevious(): ?Throwable
+    {
+        return $this->previous;
+    }
+
+    /**
+     * Gets the stack trace as a string
+     * @link https://php.net/manual/en/exception.gettraceasstring.php
+     * @return string the Exception stack trace as a string.
+     */
+    final public function getTraceAsString(): string
+    {
+        $lines = [];
+        foreach ($this->trace as $i => $frame) {
+            $file = $frame['file'] ?? '[internal function]';
+            $line = $frame['line'] ?? 0;
+            $func = $frame['function'] ?? '';
+            $class = $frame['class'] ?? '';
+            $type = $frame['type'] ?? '';
+            $lines[] = sprintf('#%d %s(%s): %s%s%s()', $i, $file, $line, $class, $type, $func);
+        }
+        $lines[] = sprintf('#%d {main}', count($lines));
+        return implode("\n", $lines);
+    }
+
+}

shared/lib/Exception/RuntimeException.php

@@ -0,0 +1,9 @@
+<?php
+
+namespace KTXF\Exception;
+
+/**
+ * Exception thrown if an error which can only be found on runtime occurs.
+ * @link https://php.net/manual/en/class.runtimeexception.php
+ */
+class RuntimeException extends BaseException {}