God-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.
- Option Type: Rust-inspired
Some/Nonetype for safe handling of nullable values - Enhanced Exceptions: Advanced error handling with state tracking and exception history
- Retry Mechanism: Built-in retry capabilities for transient failures
- Symfony Integration: Seamless integration with Symfony framework (optional)
- Type Safety: Full PHP 8.1 type system support
- PHP 8.1 or higher
- Symfony 7.1 or higher (optional, for bundle integration)
composer require cmatosbc/hephaestus- Install the package as shown above
- Register the bundle in
config/bundles.php:
return [
// ...
Hephaestus\Bundle\HephaestusBundle::class => ['all' => true],
];- Configure the bundle in
config/packages/hephaestus.yaml:
hephaestus:
max_retries: 3
retry_delay: 1
logging:
enabled: true
channel: 'hephaestus'The Option type provides a safe way to handle potentially null values:
use function Hephaestus\Some;
use function Hephaestus\None;
// Basic usage
$user = Some(['name' => 'Zeus']);
$name = $user->map(fn($u) => $u['name'])
->getOrElse('Anonymous'); // Returns "Zeus"
// Pattern matching
$greeting = $user->match(
some: fn($u) => "Welcome, {$u['name']}!",
none: fn() => "Welcome, stranger!"
);
// Chaining operations
$drinking_age = Some(['name' => 'Dionysus', 'age' => 21])
->filter(fn($u) => $u['age'] >= 21)
->map(fn($u) => "{$u['name']} can drink!")
->getOrElse("Not old enough");The EnhancedException class provides state tracking and exception history management:
use Hephaestus\EnhancedException;
class DatabaseException extends EnhancedException {}
try {
throw new DatabaseException(
"Query failed",
0,
new \PDOException("Connection lost")
);
} catch (DatabaseException $e) {
// Track exception history
$history = $e->getExceptionHistory();
$lastError = $e->getLastException();
// Add context
$e->saveState(['query' => 'SELECT * FROM users'])
->addToHistory(new \Exception("Additional context"));
// Type-specific error handling
if ($e->hasExceptionOfType(\PDOException::class)) {
$pdoErrors = $e->getExceptionsOfType(\PDOException::class);
}
}Built-in retry capabilities for handling transient failures:
use function Hephaestus\withRetryBeforeFailing;
// Retry an operation up to 3 times
$result = withRetryBeforeFailing(3)(function() {
return file_get_contents('https://api.example.com/data');
});
// Combine with Option type for safer error handling
function fetchDataSafely($url): Option {
return withRetryBeforeFailing(3)(function() use ($url) {
$response = file_get_contents($url);
return $response === false ? None() : Some(json_decode($response, true));
});
}
$data = fetchDataSafely('https://api.example.com/data')
->map(fn($d) => $d['value'])
->getOrElse('default');The bundle provides an OptionFactory service with built-in retry capabilities:
use Hephaestus\Bundle\Service\OptionFactory;
class UserService
{
public function __construct(private OptionFactory $optionFactory)
{}
public function findUser(int $id): Option
{
return $this->optionFactory->fromCallable(
fn() => $this->userRepository->find($id)
);
}
}The SymfonyEnhancedException class provides HTTP-specific error handling:
use Hephaestus\Bundle\Exception\SymfonyEnhancedException;
class UserNotFoundException extends SymfonyEnhancedException
{
public function __construct(int $userId)
{
parent::__construct(
"User not found",
Response::HTTP_NOT_FOUND
);
$this->saveState(['user_id' => $userId]);
}
}
class UserController
{
public function show(int $id): Response
{
return $this->optionFactory
->fromCallable(fn() => $this->userRepository->find($id))
->match(
some: fn($user) => $this->json($user),
none: fn() => throw new UserNotFoundException($id)
);
}
}- Type Safety: Leverage PHP 8.1 type system for safer code
- Functional Approach: Chain operations with map, filter, and match
- Explicit Error Handling: Make potential failures visible in method signatures
- State Tracking: Capture and maintain error context and history
- Resilient Operations: Built-in retry mechanism for transient failures
- Framework Integration: Seamless Symfony integration when needed
Contributions 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.
This project is licensed under the GNU General Public License v3.0 or later - see the 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.