v3 base

src/StaticPHP/Exception/BuildFailureException.php

@@ -0,0 +1,13 @@
+<?php
+
+declare(strict_types=1);
+
+namespace StaticPHP\Exception;
+
+/**
+ * BuildFailureException is thrown when a build process failed with other reasons.
+ *
+ * This exception indicates that the build operation did not complete successfully,
+ * which may be due to various reasons such as missing built-files, incorrect configurations, etc.
+ */
+class BuildFailureException extends SPCException {}

src/StaticPHP/Exception/DownloaderException.php

@@ -0,0 +1,13 @@
+<?php
+
+declare(strict_types=1);
+
+namespace StaticPHP\Exception;
+
+/**
+ * Exception thrown when an error occurs during the downloading process.
+ *
+ * This exception is used to indicate that a download operation has failed,
+ * typically due to network issues, invalid URLs, or other related problems.
+ */
+class DownloaderException extends SPCException {}

src/StaticPHP/Exception/EnvironmentException.php

@@ -0,0 +1,25 @@
+<?php
+
+declare(strict_types=1);
+
+namespace StaticPHP\Exception;
+
+/**
+ * EnvironmentException is thrown when there is an issue with the environment setup,
+ * such as missing dependencies or incorrect configurations.
+ */
+class EnvironmentException extends SPCException
+{
+    public function __construct(string $message, private readonly ?string $solution = null)
+    {
+        parent::__construct($message);
+    }
+
+    /**
+     * Returns the solution for the environment issue.
+     */
+    public function getSolution(): ?string
+    {
+        return $this->solution;
+    }
+}

src/StaticPHP/Exception/ExceptionHandler.php

@@ -0,0 +1,228 @@
+<?php
+
+declare(strict_types=1);
+
+namespace StaticPHP\Exception;
+
+use SPC\builder\BuilderBase;
+use SPC\builder\freebsd\BSDBuilder;
+use SPC\builder\linux\LinuxBuilder;
+use SPC\builder\macos\MacOSBuilder;
+use SPC\builder\windows\WindowsBuilder;
+use StaticPHP\DI\ApplicationContext;
+use ZM\Logger\ConsoleColor;
+
+class ExceptionHandler
+{
+    public const array KNOWN_EXCEPTIONS = [
+        BuildFailureException::class,
+        DownloaderException::class,
+        EnvironmentException::class,
+        ExecutionException::class,
+        FileSystemException::class,
+        InterruptException::class,
+        PatchException::class,
+        SPCInternalException::class,
+        ValidationException::class,
+        WrongUsageException::class,
+    ];
+
+    public const array MINOR_LOG_EXCEPTIONS = [
+        InterruptException::class,
+        WrongUsageException::class,
+    ];
+
+    /** @var null|BuilderBase Builder binding */
+    private static ?BuilderBase $builder = null;
+
+    /** @var array<string, mixed> Build PHP extra info binding */
+    private static array $build_php_extra_info = [];
+
+    public static function handleSPCException(SPCException $e): void
+    {
+        // XXX error: yyy
+        $head_msg = match ($class = get_class($e)) {
+            BuildFailureException::class => "✗ Build failed: {$e->getMessage()}",
+            DownloaderException::class => "✗ Download failed: {$e->getMessage()}",
+            EnvironmentException::class => "⚠ Environment check failed: {$e->getMessage()}",
+            ExecutionException::class => "✗ Command execution failed: {$e->getMessage()}",
+            FileSystemException::class => "✗ File system error: {$e->getMessage()}",
+            InterruptException::class => "⚠ Build interrupted by user: {$e->getMessage()}",
+            PatchException::class => "✗ Patch apply failed: {$e->getMessage()}",
+            SPCInternalException::class => "✗ SPC internal error: {$e->getMessage()}",
+            ValidationException::class => "⚠ Validation failed: {$e->getMessage()}",
+            WrongUsageException::class => $e->getMessage(),
+            default => "✗ Unknown SPC exception {$class}: {$e->getMessage()}",
+        };
+        self::logError($head_msg);
+
+        // ----------------------------------------
+        $minor_logs = in_array($class, self::MINOR_LOG_EXCEPTIONS, true);
+
+        if ($minor_logs) {
+            return;
+        }
+
+        self::logError("----------------------------------------\n");
+
+        // get the SPCException module
+        if ($lib_info = $e->getLibraryInfo()) {
+            self::logError('Failed module: ' . ConsoleColor::yellow("library {$lib_info['library_name']} builder for {$lib_info['os']}"));
+        } elseif ($ext_info = $e->getExtensionInfo()) {
+            self::logError('Failed module: ' . ConsoleColor::yellow("shared extension {$ext_info['extension_name']} builder"));
+        } elseif (self::$builder) {
+            $os = match (get_class(self::$builder)) {
+                WindowsBuilder::class => 'Windows',
+                MacOSBuilder::class => 'macOS',
+                LinuxBuilder::class => 'Linux',
+                BSDBuilder::class => 'FreeBSD',
+                default => 'Unknown OS',
+            };
+            self::logError('Failed module: ' . ConsoleColor::yellow("Builder for {$os}"));
+        } elseif (!in_array($class, self::KNOWN_EXCEPTIONS)) {
+            self::logError('Failed From: ' . ConsoleColor::yellow('Unknown SPC module ' . $class));
+        }
+
+        // get command execution info
+        if ($e instanceof ExecutionException) {
+            self::logError('');
+            self::logError('Failed command: ' . ConsoleColor::yellow($e->getExecutionCommand()));
+            if ($cd = $e->getCd()) {
+                self::logError('Command executed in: ' . ConsoleColor::yellow($cd));
+            }
+            if ($env = $e->getEnv()) {
+                self::logError('Command inline env variables:');
+                foreach ($env as $k => $v) {
+                    self::logError(ConsoleColor::yellow("{$k}={$v}"), 4);
+                }
+            }
+        }
+
+        // validation error
+        if ($e instanceof ValidationException) {
+            self::logError('Failed validation module: ' . ConsoleColor::yellow($e->getValidationModuleString()));
+        }
+
+        // environment error
+        if ($e instanceof EnvironmentException) {
+            self::logError('Failed environment check: ' . ConsoleColor::yellow($e->getMessage()));
+            if (($solution = $e->getSolution()) !== null) {
+                self::logError('Solution: ' . ConsoleColor::yellow($solution));
+            }
+        }
+
+        // get patch info
+        if ($e instanceof PatchException) {
+            self::logError("Failed patch module: {$e->getPatchModule()}");
+        }
+
+        // get internal trace
+        if ($e instanceof SPCInternalException) {
+            self::logError('Internal trace:');
+            self::logError(ConsoleColor::gray("{$e->getTraceAsString()}\n"), 4);
+        }
+
+        // get the full build info if possible
+        if ($info = ExceptionHandler::$build_php_extra_info) {
+            self::logError('', output_log: ApplicationContext::isDebug());
+            self::logError('Build PHP extra info:', output_log: ApplicationContext::isDebug());
+            self::printArrayInfo($info);
+        }
+
+        // get the full builder options if possible
+        if ($e->getBuildPHPInfo()) {
+            $info = $e->getBuildPHPInfo();
+            self::logError('', output_log: ApplicationContext::isDebug());
+            self::logError('Builder function: ' . ConsoleColor::yellow($info['builder_function']), output_log: ApplicationContext::isDebug());
+        }
+
+        self::logError("\n----------------------------------------\n");
+
+        // convert log file path if in docker
+        $spc_log_convert = get_display_path(SPC_OUTPUT_LOG);
+        $shell_log_convert = get_display_path(SPC_SHELL_LOG);
+        $spc_logs_dir_convert = get_display_path(SPC_LOGS_DIR);
+
+        self::logError('⚠ The ' . ConsoleColor::cyan('console output log') . ConsoleColor::red(' is saved in ') . ConsoleColor::cyan($spc_log_convert));
+        if (file_exists(SPC_SHELL_LOG)) {
+            self::logError('⚠ The ' . ConsoleColor::cyan('shell output log') . ConsoleColor::red(' is saved in ') . ConsoleColor::cyan($shell_log_convert));
+        }
+        if ($e->getExtraLogFiles() !== []) {
+            foreach ($e->getExtraLogFiles() as $key => $file) {
+                self::logError("⚠ Log file [{$key}] is saved in: " . ConsoleColor::cyan("{$spc_logs_dir_convert}/{$file}"));
+            }
+        }
+        if (!ApplicationContext::isDebug()) {
+            self::logError('⚠ If you want to see more details in console, use `--debug` option.');
+        }
+    }
+
+    public static function handleDefaultException(\Throwable $e): void
+    {
+        $class = get_class($e);
+        $file = $e->getFile();
+        $line = $e->getLine();
+        self::logError("✗ Unhandled exception {$class} on {$file} line {$line}:\n\t{$e->getMessage()}\n");
+        self::logError('Stack trace:');
+        self::logError(ConsoleColor::gray($e->getTraceAsString()) . PHP_EOL, 4);
+        self::logError('⚠ Please report this exception to: https://github.com/crazywhalecc/static-php-cli/issues');
+    }
+
+    public static function bindBuilder(?BuilderBase $bind_builder): void
+    {
+        self::$builder = $bind_builder;
+    }
+
+    public static function bindBuildPhpExtraInfo(array $build_php_extra_info): void
+    {
+        self::$build_php_extra_info = $build_php_extra_info;
+    }
+
+    private static function logError($message, int $indent_space = 0, bool $output_log = true): void
+    {
+        $spc_log = fopen(SPC_OUTPUT_LOG, 'a');
+        $msg = explode("\n", (string) $message);
+        foreach ($msg as $v) {
+            $line = str_pad($v, strlen($v) + $indent_space, ' ', STR_PAD_LEFT);
+            fwrite($spc_log, strip_ansi_colors($line) . PHP_EOL);
+            if ($output_log) {
+                echo ConsoleColor::red($line) . PHP_EOL;
+            }
+        }
+    }
+
+    /**
+     * Print array info to console and log.
+     */
+    private static function printArrayInfo(array $info): void
+    {
+        $log_output = ApplicationContext::isDebug();
+        $maxlen = 0;
+        foreach ($info as $k => $v) {
+            $maxlen = max(strlen($k), $maxlen);
+        }
+        foreach ($info as $k => $v) {
+            if (is_string($v)) {
+                if ($v === '') {
+                    self::logError($k . ': ' . str_pad('', $maxlen - strlen($k)) . ConsoleColor::yellow('""'), 4, $log_output);
+                } else {
+                    self::logError($k . ': ' . str_pad('', $maxlen - strlen($k)) . ConsoleColor::yellow($v), 4, $log_output);
+                }
+            } elseif (is_array($v) && !is_assoc_array($v)) {
+                if ($v === []) {
+                    self::logError($k . ': ' . str_pad('', $maxlen - strlen($k)) . ConsoleColor::yellow('[]'), 4, $log_output);
+                    continue;
+                }
+                $first = array_shift($v);
+                self::logError($k . ': ' . str_pad('', $maxlen - strlen($k)) . ConsoleColor::yellow($first), 4, $log_output);
+                foreach ($v as $vs) {
+                    self::logError(str_pad('', $maxlen + 2) . ConsoleColor::yellow($vs), 4, $log_output);
+                }
+            } elseif (is_bool($v) || is_null($v)) {
+                self::logError($k . ': ' . str_pad('', $maxlen - strlen($k)) . ConsoleColor::cyan($v === true ? 'true' : ($v === false ? 'false' : 'null')), 4, $log_output);
+            } else {
+                self::logError($k . ': ' . str_pad('', $maxlen - strlen($k)) . ConsoleColor::yellow(json_encode($v, JSON_PRETTY_PRINT)), 4, $log_output);
+            }
+        }
+    }
+}

src/StaticPHP/Exception/ExecutionException.php

@@ -0,0 +1,58 @@
+<?php
+
+declare(strict_types=1);
+
+namespace StaticPHP\Exception;
+
+use SPC\util\shell\UnixShell;
+use SPC\util\shell\WindowsCmd;
+
+/**
+ * Exception thrown when an error occurs during execution of shell command.
+ *
+ * This exception is used to indicate that a command executed by the SPC framework
+ * has failed, typically due to an error in the command itself or an issue with the environment
+ * in which it was executed.
+ */
+class ExecutionException extends SPCException
+{
+    public function __construct(
+        private readonly string|UnixShell|WindowsCmd $cmd,
+        $message = '',
+        $code = 0,
+        private readonly ?string $cd = null,
+        private readonly array $env = [],
+        ?\Exception $previous = null
+    ) {
+        parent::__construct($message, $code, $previous);
+    }
+
+    /**
+     * Returns the command that caused the execution error.
+     *
+     * @return string the command that was executed when the error occurred
+     */
+    public function getExecutionCommand(): string
+    {
+        if ($this->cmd instanceof UnixShell || $this->cmd instanceof WindowsCmd) {
+            return $this->cmd->getLastCommand();
+        }
+        return $this->cmd;
+    }
+
+    /**
+     * Returns the directory in which the command was executed.
+     */
+    public function getCd(): ?string
+    {
+        return $this->cd;
+    }
+
+    /**
+     * Returns the environment variables that were set during the command execution.
+     */
+    public function getEnv(): array
+    {
+        return $this->env;
+    }
+}

src/StaticPHP/Exception/FileSystemException.php

@@ -0,0 +1,7 @@
+<?php
+
+declare(strict_types=1);
+
+namespace StaticPHP\Exception;
+
+class FileSystemException extends SPCException {}

src/StaticPHP/Exception/InterruptException.php

@@ -0,0 +1,10 @@
+<?php
+
+declare(strict_types=1);
+
+namespace StaticPHP\Exception;
+
+/**
+ * Exception caused by manual intervention.
+ */
+class InterruptException extends SPCException {}

src/StaticPHP/Exception/PatchException.php

@@ -0,0 +1,25 @@
+<?php
+
+declare(strict_types=1);
+
+namespace StaticPHP\Exception;
+
+/**
+ * PatchException is thrown when there is an issue applying a patch,
+ * such as a failure in the patch process or conflicts during patching.
+ */
+class PatchException extends SPCException
+{
+    public function __construct(private readonly string $patch_module, $message, $code = 0, ?\Exception $previous = null)
+    {
+        parent::__construct($message, $code, $previous);
+    }
+
+    /**
+     * Returns the name of the patch module that caused the exception.
+     */
+    public function getPatchModule(): string
+    {
+        return $this->patch_module;
+    }
+}

src/StaticPHP/Exception/SPCException.php

@@ -0,0 +1,147 @@
+<?php
+
+declare(strict_types=1);
+
+namespace StaticPHP\Exception;
+
+use SPC\builder\BuilderBase;
+use SPC\builder\freebsd\library\BSDLibraryBase;
+use SPC\builder\LibraryBase;
+use SPC\builder\linux\library\LinuxLibraryBase;
+use SPC\builder\macos\library\MacOSLibraryBase;
+use SPC\builder\windows\library\WindowsLibraryBase;
+
+/**
+ * Base class for SPC exceptions.
+ *
+ * This class serves as the base for all exceptions thrown by the SPC framework.
+ * It extends the built-in PHP Exception class, allowing for custom exception handling
+ * and categorization of SPC-related errors.
+ */
+abstract class SPCException extends \Exception
+{
+    private ?array $library_info = null;
+
+    private ?array $extension_info = null;
+
+    private ?array $build_php_info = null;
+
+    private array $extra_log_files = [];
+
+    public function __construct(string $message = '', int $code = 0, ?\Throwable $previous = null)
+    {
+        parent::__construct($message, $code, $previous);
+        $this->loadStackTraceInfo();
+    }
+
+    public function bindExtensionInfo(array $extension_info): void
+    {
+        $this->extension_info = $extension_info;
+    }
+
+    public function addExtraLogFile(string $key, string $filename): void
+    {
+        $this->extra_log_files[$key] = $filename;
+    }
+
+    /**
+     * Returns an array containing information about the SPC module.
+     *
+     * This method can be overridden by subclasses to provide specific module information.
+     *
+     * @return null|array{
+     *     library_name: string,
+     *     library_class: string,
+     *     os: string,
+     *     file: null|string,
+     *     line: null|int,
+     * } an array containing module information
+     */
+    public function getLibraryInfo(): ?array
+    {
+        return $this->library_info;
+    }
+
+    /**
+     * Returns an array containing information about the PHP build process.
+     *
+     * @return null|array{
+     *     builder_function: string,
+     *     file: null|string,
+     *     line: null|int,
+     * } an array containing PHP build information
+     */
+    public function getBuildPHPInfo(): ?array
+    {
+        return $this->build_php_info;
+    }
+
+    /**
+     * Returns an array containing information about the SPC extension.
+     *
+     * This method can be overridden by subclasses to provide specific extension information.
+     *
+     * @return null|array{
+     *     extension_name: string,
+     *     extension_class: string,
+     *     file: null|string,
+     *     line: null|int,
+     * } an array containing extension information
+     */
+    public function getExtensionInfo(): ?array
+    {
+        return $this->extension_info;
+    }
+
+    public function getExtraLogFiles(): array
+    {
+        return $this->extra_log_files;
+    }
+
+    private function loadStackTraceInfo(): void
+    {
+        $trace = $this->getTrace();
+        foreach ($trace as $frame) {
+            if (!isset($frame['class'])) {
+                continue;
+            }
+
+            // Check if the class is a subclass of LibraryBase
+            if (!$this->library_info && is_a($frame['class'], LibraryBase::class, true)) {
+                try {
+                    $reflection = new \ReflectionClass($frame['class']);
+                    if ($reflection->hasConstant('NAME')) {
+                        $name = $reflection->getConstant('NAME');
+                        if ($name !== 'unknown') {
+                            $this->library_info = [
+                                'library_name' => $name,
+                                'library_class' => $frame['class'],
+                                'os' => match (true) {
+                                    is_a($frame['class'], BSDLibraryBase::class, true) => 'BSD',
+                                    is_a($frame['class'], LinuxLibraryBase::class, true) => 'Linux',
+                                    is_a($frame['class'], MacOSLibraryBase::class, true) => 'macOS',
+                                    is_a($frame['class'], WindowsLibraryBase::class, true) => 'Windows',
+                                    default => 'Unknown',
+                                },
+                                'file' => $frame['file'] ?? null,
+                                'line' => $frame['line'] ?? null,
+                            ];
+                            continue;
+                        }
+                    }
+                } catch (\ReflectionException) {
+                    continue;
+                }
+            }
+
+            // Check if the class is a subclass of BuilderBase and the method is buildPHP
+            if (!$this->build_php_info && is_a($frame['class'], BuilderBase::class, true)) {
+                $this->build_php_info = [
+                    'builder_function' => $frame['function'],
+                    'file' => $frame['file'] ?? null,
+                    'line' => $frame['line'] ?? null,
+                ];
+            }
+        }
+    }
+}

src/StaticPHP/Exception/SPCInternalException.php

@@ -0,0 +1,12 @@
+<?php
+
+declare(strict_types=1);
+
+namespace StaticPHP\Exception;
+
+/**
+ * Exception for internal errors or vendor wrong usage in SPC.
+ *
+ * This exception is thrown when an unexpected internal error or vendor wrong usage occurs within the SPC framework.
+ */
+class SPCInternalException extends SPCException {}

src/StaticPHP/Exception/ValidationException.php

@@ -0,0 +1,61 @@
+<?php
+
+declare(strict_types=1);
+
+namespace StaticPHP\Exception;
+
+use SPC\builder\Extension;
+
+/**
+ * Exception thrown for validation errors in SPC.
+ *
+ * This exception is used to indicate that a validation error has occurred,
+ * typically when input data does not meet the required criteria.
+ */
+class ValidationException extends SPCException
+{
+    private array|string|null $validation_module = null;
+
+    public function __construct(string $message = '', int $code = 0, ?\Throwable $previous = null, array|string|null $validation_module = null)
+    {
+        parent::__construct($message, $code, $previous);
+
+        // init validation module
+        if ($validation_module === null) {
+            foreach ($this->getTrace() as $trace) {
+                // Extension validate() => "Extension validator"
+                if (is_a($trace['class'] ?? null, Extension::class, true) && $trace['function'] === 'validate') {
+                    $this->validation_module = 'Extension validator';
+                    break;
+                }
+
+                // Other => "ClassName::functionName"
+                $this->validation_module = [
+                    'class' => $trace['class'] ?? null,
+                    'function' => $trace['function'],
+                ];
+                break;
+            }
+        } else {
+            $this->validation_module = $validation_module;
+        }
+    }
+
+    /**
+     * Returns the validation module string.
+     */
+    public function getValidationModuleString(): string
+    {
+        if ($this->validation_module === null) {
+            return 'Unknown';
+        }
+        if (is_string($this->validation_module)) {
+            return $this->validation_module;
+        }
+        $str = $this->validation_module['class'] ?? null;
+        if ($str !== null) {
+            $str .= '::';
+        }
+        return ($str ?? '') . $this->validation_module['function'];
+    }
+}

src/StaticPHP/Exception/WrongUsageException.php

@@ -0,0 +1,13 @@
+<?php
+
+declare(strict_types=1);
+
+namespace StaticPHP\Exception;
+
+/**
+ * Exception thrown for incorrect usage of SPC.
+ *
+ * This exception is used to indicate that the SPC is being used incorrectly.
+ * Such as when a command is not supported or an invalid argument is provided.
+ */
+class WrongUsageException extends SPCException {}