{"id":22316499,"url":"https://github.com/cmatosbc/hephaestus","last_synced_at":"2026-02-27T22:02:00.149Z","repository":{"id":263808735,"uuid":"891439090","full_name":"cmatosbc/hephaestus","owner":"cmatosbc","description":"God-like error handling library for modern PHP programmers. A new eye on PHP exceptions and good features from other programming languages adapted.","archived":false,"fork":false,"pushed_at":"2024-12-10T02:11:35.000Z","size":1160,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-10-14T06:32:52.653Z","etag":null,"topics":["error-handler","error-handling","exception-handling","php","php-cli","php-debug","php-errors","php-exception","php-exceptions","php-library","php-packages","php-utility","php8","php80","php81","symfony-bundle"],"latest_commit_sha":null,"homepage":"","language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/cmatosbc.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2024-11-20T10:37:54.000Z","updated_at":"2024-12-10T02:10:57.000Z","dependencies_parsed_at":"2024-11-20T12:36:05.427Z","dependency_job_id":"60d52638-6be5-44b8-b942-e069fb06f82d","html_url":"https://github.com/cmatosbc/hephaestus","commit_stats":null,"previous_names":["cmatosbc/hephaestus"],"tags_count":5,"template":false,"template_full_name":null,"purl":"pkg:github/cmatosbc/hephaestus","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cmatosbc%2Fhephaestus","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cmatosbc%2Fhephaestus/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cmatosbc%2Fhephaestus/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cmatosbc%2Fhephaestus/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/cmatosbc","download_url":"https://codeload.github.com/cmatosbc/hephaestus/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cmatosbc%2Fhephaestus/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29917207,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-27T19:37:42.220Z","status":"ssl_error","status_checked_at":"2026-02-27T19:37:41.463Z","response_time":57,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["error-handler","error-handling","exception-handling","php","php-cli","php-debug","php-errors","php-exception","php-exceptions","php-library","php-packages","php-utility","php8","php80","php81","symfony-bundle"],"created_at":"2024-12-03T23:06:47.332Z","updated_at":"2026-02-27T22:02:00.126Z","avatar_url":"https://github.com/cmatosbc.png","language":"PHP","funding_links":[],"categories":["Libraries"],"sub_categories":["Error Handling"],"readme":"# Hephaestus\n\n[![PHP Lint](https://github.com/cmatosbc/hephaestus/actions/workflows/lint.yml/badge.svg)](https://github.com/cmatosbc/hephaestus/actions/workflows/lint.yml) [![PHPUnit Tests](https://github.com/cmatosbc/hephaestus/actions/workflows/phpunit.yml/badge.svg)](https://github.com/cmatosbc/hephaestus/actions/workflows/phpunit.yml)\n\nGod-like error handling library for modern PHP programmers. Hephaestus provides a comprehensive set of tools for elegant error handling, combining functional programming concepts with robust exception management.\n\n## Features\n\n- **Option Type**: Rust-inspired `Some/None` type for safe handling of nullable values\n- **Enhanced Exceptions**: Advanced error handling with state tracking and exception history\n- **Retry Mechanism**: Built-in retry capabilities for transient failures\n- **Symfony Integration**: Seamless integration with Symfony framework (optional)\n- **Type Safety**: Full PHP 8.1+ type system support\n\n## Requirements\n\n- PHP 8.1 or higher\n- Symfony 7.1 or higher (optional, for bundle integration)\n\n## Installation\n\n### Basic Installation\n\n```bash\ncomposer require cmatosbc/hephaestus\n```\n\n### Symfony Bundle Installation\n\n1. Install the package as shown above\n2. Register the bundle in `config/bundles.php`:\n```php\nreturn [\n    // ...\n    Hephaestus\\Bundle\\HephaestusBundle::class =\u003e ['all' =\u003e true],\n];\n```\n\n3. Configure the bundle in `config/packages/hephaestus.yaml`:\n```yaml\nhephaestus:\n    max_retries: 3\n    retry_delay: 1\n    logging:\n        enabled: true\n        channel: 'hephaestus'\n```\n\n## Core Components\n\n### Option Type\n\nThe Option type provides a safe way to handle potentially null values:\n\n```php\nuse function Hephaestus\\Some;\nuse function Hephaestus\\None;\n\n// Basic usage\n$user = Some(['name' =\u003e 'Zeus']);\n$name = $user-\u003emap(fn($u) =\u003e $u['name'])\n            -\u003egetOrElse('Anonymous'); // Returns \"Zeus\"\n\n// Pattern matching\n$greeting = $user-\u003ematch(\n    some: fn($u) =\u003e \"Welcome, {$u['name']}!\",\n    none: fn() =\u003e \"Welcome, stranger!\"\n);\n\n// Chaining operations\n$drinking_age = Some(['name' =\u003e 'Dionysus', 'age' =\u003e 21])\n    -\u003efilter(fn($u) =\u003e $u['age'] \u003e= 21)\n    -\u003emap(fn($u) =\u003e \"{$u['name']} can drink!\")\n    -\u003egetOrElse(\"Not old enough\");\n```\n\n### Enhanced Exception Handling\n\nThe `EnhancedException` class provides state tracking and exception history management:\n\n```php\nuse Hephaestus\\EnhancedException;\n\nclass DatabaseException extends EnhancedException {}\n\ntry {\n    throw new DatabaseException(\n        \"Query failed\",\n        0,\n        new \\PDOException(\"Connection lost\")\n    );\n} catch (DatabaseException $e) {\n    // Track exception history\n    $history = $e-\u003egetExceptionHistory();\n    $lastError = $e-\u003egetLastException();\n    \n    // Add context\n    $e-\u003esaveState(['query' =\u003e 'SELECT * FROM users'])\n      -\u003eaddToHistory(new \\Exception(\"Additional context\"));\n    \n    // Type-specific error handling\n    if ($e-\u003ehasExceptionOfType(\\PDOException::class)) {\n        $pdoErrors = $e-\u003egetExceptionsOfType(\\PDOException::class);\n    }\n}\n```\n\n### Retry Mechanism\n\nBuilt-in retry capabilities for handling transient failures:\n\n```php\nuse function Hephaestus\\withRetryBeforeFailing;\n\n// Retry an operation up to 3 times\n$result = withRetryBeforeFailing(3)(function() {\n    return file_get_contents('https://api.example.com/data');\n});\n\n// Combine with Option type for safer error handling\nfunction fetchDataSafely($url): Option {\n    return withRetryBeforeFailing(3)(function() use ($url) {\n        $response = file_get_contents($url);\n        return $response === false ? None() : Some(json_decode($response, true));\n    });\n}\n\n$data = fetchDataSafely('https://api.example.com/data')\n    -\u003emap(fn($d) =\u003e $d['value'])\n    -\u003egetOrElse('default');\n```\n\n## Symfony Integration\n\n### Option Factory Service\n\nThe bundle provides an `OptionFactory` service with built-in retry capabilities:\n\n```php\nuse Hephaestus\\Bundle\\Service\\OptionFactory;\n\nclass UserService\n{\n    public function __construct(private OptionFactory $optionFactory)\n    {}\n\n    public function findUser(int $id): Option\n    {\n        return $this-\u003eoptionFactory-\u003efromCallable(\n            fn() =\u003e $this-\u003euserRepository-\u003efind($id)\n        );\n    }\n}\n```\n\n### HTTP-Aware Exceptions\n\nThe `SymfonyEnhancedException` class provides HTTP-specific error handling:\n\n```php\nuse Hephaestus\\Bundle\\Exception\\SymfonyEnhancedException;\n\nclass UserNotFoundException extends SymfonyEnhancedException\n{\n    public function __construct(int $userId)\n    {\n        parent::__construct(\n            \"User not found\",\n            Response::HTTP_NOT_FOUND\n        );\n        $this-\u003esaveState(['user_id' =\u003e $userId]);\n    }\n}\n\nclass UserController\n{\n    public function show(int $id): Response\n    {\n        return $this-\u003eoptionFactory\n            -\u003efromCallable(fn() =\u003e $this-\u003euserRepository-\u003efind($id))\n            -\u003ematch(\n                some: fn($user) =\u003e $this-\u003ejson($user),\n                none: fn() =\u003e throw new UserNotFoundException($id)\n            );\n    }\n}\n```\n\n## Key Benefits\n\n- **Type Safety**: Leverage PHP 8.1+ type system for safer code\n- **Functional Approach**: Chain operations with map, filter, and match\n- **Explicit Error Handling**: Make potential failures visible in method signatures\n- **State Tracking**: Capture and maintain error context and history\n- **Resilient Operations**: Built-in retry mechanism for transient failures\n- **Framework Integration**: Seamless Symfony integration when needed\n\n## Contributing\n\nContributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.\n\n## License\n\nThis project is licensed under the GNU General Public License v3.0 or later - see the [LICENSE](LICENSE) file for details. This means you are free to use, modify, and distribute this software, but any modifications must also be released under the GPL-3.0-or-later license.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcmatosbc%2Fhephaestus","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcmatosbc%2Fhephaestus","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcmatosbc%2Fhephaestus/lists"}