Weave Code
Deprecation Contracts Laravel Package
symfony/deprecation-contracts
Provides the global trigger_deprecation() helper to emit standardized, silenced deprecation notices with package name and version. Works with custom error handlers (e.g., Symfony ErrorHandler) to catch and log deprecations in dev and production.
A generic function and convention to trigger deprecation notices
Frequently asked questions about Deprecation Contracts
- How do I integrate `symfony/deprecation-contracts` with Laravel’s default error handling?
- Laravel’s default error handling won’t catch `E_USER_DEPRECATED` by default. Install `symfony/error-handler` (`composer require symfony/error-handler`) and register it in `bootstrap/app.php` via `ErrorHandler::register()`. This enables deprecation visibility in both dev and production environments. For Laravel 8+, this is often pre-configured if you’re using Symfony components.
- Can I use this package in Laravel 7 or earlier without Symfony’s ErrorHandler?
- Yes, but you’ll need to manually set up an error handler to capture `E_USER_DEPRECATED`. Use `set_error_handler()` in your bootstrap file to log deprecations to a file or monitoring system. Without this, deprecations will be silently ignored. The package itself is dependency-free and works anywhere PHP runs.
- How do I suppress deprecation notices in production without losing visibility?
- Deprecations are silenced by default but still logged if your error handler is configured. For production, ensure your error handler (e.g., Symfony’s or a custom one) writes logs to a centralized system like Sentry or ELK. Avoid overriding `trigger_deprecation()` globally, as this risks hiding critical upgrade signals entirely.
- Will this package slow down my Laravel application in high-traffic APIs?
- No, the runtime overhead is negligible. The `trigger_deprecation()` function uses conditional checks and can be optimized further by wrapping calls in feature flags for hot paths. It’s designed for performance-sensitive applications, with no impact unless an error handler is actively processing deprecations.
- How can I test deprecation notices in PHPUnit without triggering real errors?
- Mock the `trigger_deprecation()` function in your tests by overriding it globally or using PHPUnit’s `set_error_handler()` to capture deprecations. For example, use `trigger_error()` in tests to simulate deprecations and verify they’re logged correctly. This avoids polluting test output with actual deprecation messages.
- Does this package work with Laravel’s built-in `Deprecates` trait or facade?
- No, this package is independent of Laravel’s `Deprecates` trait (for methods) or any Laravel-specific deprecation tools. It provides a *generic* contract for Composer packages, ensuring consistency across the broader PHP ecosystem. Use both if needed, but this package is better suited for library-wide deprecations.
- How do I dynamically fetch the package version for `trigger_deprecation()` instead of hardcoding it?
- Use `composer.json` to dynamically resolve the version. For example, in PHP, run `json_decode(file_get_contents(__DIR__.'/../../composer.json'), true)['version']` to fetch the current version. This avoids manual updates during major releases and ensures accuracy. Store the version in a constant or service provider for reuse.
- Can I customize where deprecation logs are stored (e.g., database, Slack)?
- No, this package only emits deprecations via `E_USER_DEPRECATED`. You must configure your error handler (e.g., Symfony’s) to route logs to your preferred destination. For databases, extend the error handler to write to a custom table. For Slack, use a logging driver like `monolog` with a Slack handler.
- What’s the best way to enforce deprecation checks in CI/CD pipelines?
- Fail builds on new deprecations by configuring your CI to treat `E_USER_DEPRECATED` as a fatal error during tests. Use a custom error handler that throws exceptions on deprecations, then catch them in PHPUnit. Alternatively, parse logs for deprecation patterns and enforce thresholds (e.g., max 0 deprecations per PR).
- Why choose this over a custom deprecation solution for my Laravel package?
- This package provides a *standardized* contract for deprecations, ensuring consistency across the PHP ecosystem. It integrates seamlessly with Symfony’s tools (used in Laravel 8+) and avoids reinventing the wheel. Custom solutions risk fragmentation, while this offers built-in compatibility with error handlers, logging systems, and downstream consumers.
Weaver
How can I help you explore Laravel packages today?