home / skills / hoangnguyen0403 / agent-skills-standard / error-handling

error-handling skill

safe

This skill enforces PHP error handling best practices with exception-driven flow, global handlers, and PSR-3 logging to improve reliability and maintainability.

npx playbooks add skill hoangnguyen0403/agent-skills-standard --skill error-handling

Review the files below or copy the command above to add this skill to your agents.

Files (2)

SKILL.md

1.3 KB

---
name: PHP Error Handling
description: Modern PHP error and exception handling standards.
metadata:
  labels: [php, exceptions, error-handling, psr-3]
  triggers:
    files: ['**/*.php']
    keywords: [try, catch, finally, Throwable, set_exception_handler]
---

# PHP Error Handling

## **Priority: P0 (CRITICAL)**

## Structure

```text
src/
└── Exceptions/
    ├── {Domain}Exception.php
    └── Handler.php
```

## Implementation Guidelines

- **Exception-Driven**: Prefer throwing exceptions over returning `false`.
- **Throwable Interface**: Catch `Throwable` for both Errors and Exceptions.
- **Custom Exceptions**: Extend `RuntimeException` for domain-specific errors.
- **Multi-catch**: Use `catch (TypeA | TypeB $e)` for identical handling.
- **Finally Cleanup**: Use `finally` to ensure resource release.
- **Global Handling**: Set `set_exception_handler` in entry points.
- **PSR-3 Logging**: Log critical faults using standard loggers.

## Anti-Patterns

- **Error Suppression**: **No @**: Avoid suppressing errors with `@`.
- **Silent Catch**: **No Empty Catches**: Log or handle all caught exceptions.
- **Logic Flow**: **No Flow Control**: Don't use exceptions for expected logic.
- **Panic Display**: **No display_errors**: Log to file, never to production screen.

## References

- [Exception & Logging Patterns](references/implementation.md)

Overview

This skill codifies modern PHP error and exception handling standards to help agents enforce reliable, maintainable error management. It emphasizes exception-driven design, global handlers, and PSR-3 logging to ensure consistent behavior across applications. The guidance targets production safety, developer clarity, and predictable error flows.

How this skill works

The skill inspects code structure and runtime entry points to ensure a dedicated Exceptions folder and a global exception handler are present. It checks for use of Throwable-based catching, recommends custom domain exceptions extending RuntimeException, and verifies logging integration following PSR-3. It also flags anti-patterns like error suppression, empty catches, and display_errors in production.

When to use it

When standardizing error handling across a PHP codebase or team.
During code reviews to detect anti-patterns and missing global handlers.
When migrating legacy code that returns false or uses error suppression.
When implementing domain-specific exceptions and centralized logging.
Before deploying to production to ensure safe error reporting and cleanup.

Best practices

Prefer throwing domain-specific exceptions over returning false to improve clarity and stack traces.
Catch Throwable at high-level entry points to handle both Errors and Exceptions uniformly.
Extend RuntimeException for custom domain exceptions to keep semantic consistency.
Use multi-catch (catch (TypeA | TypeB $e)) when handling different exceptions identically.
Always log critical faults via a PSR-3 compatible logger and avoid displaying errors in production.
Use finally blocks to guarantee resource cleanup regardless of success or failure.

Example use cases

Enforcing an Exceptions/Handler.php global handler that wires set_exception_handler in bootstrap files.
Replacing legacy functions that return false with thrown domain exceptions for clearer error paths.
Detecting and removing error suppression operators (@) and replacing with explicit checks or exceptions.
Adding PSR-3 logging calls in catch blocks and ensuring no empty catch blocks remain.
Creating domain-specific exceptions (e.g., PaymentException) that extend RuntimeException for business logic errors.

FAQ

Should I catch Exception or Throwable?

Use Throwable at top-level handlers to cover both Error and Exception; catch specific exception classes in localized code for targeted handling.

Are empty catch blocks acceptable?

No. Always handle or log exceptions. Empty catches hide problems and make debugging and observability impossible.