Deprecation Contracts Laravel Package

Technical Evaluation

Architecture Fit

• Pros:
  • Laravel Compatibility: Aligns with Laravel’s Symfony ecosystem (e.g., Symfony\Component\ErrorHandler), requiring minimal architectural disruption.
  • Dependency-Free: Zero runtime overhead when unused; integrates cleanly with existing error-handling pipelines.
  • Standardized Deprecation Signals: Enables consistent, versioned warnings across libraries (e.g., Laravel core, third-party packages, or internal services).
  • Extensibility: Works with Laravel’s monolithic or microservice architectures via centralized error handlers (e.g., App\Exceptions\Handler or Symfony\ErrorHandler).
• Cons:
  • No Native Laravel Integration: Requires manual setup (e.g., wiring ErrorHandler) if not already present.
  • Silent by Default: Deprecations are invisible without explicit error-handler configuration, risking undetected usage in production.

Integration Feasibility

• High: Single composer require + minimal configuration (e.g., adding Symfony\ErrorHandler to config/app.php).
• Prerequisites:
  • Laravel 8.0+ (for Symfony component compatibility) or explicit symfony/error-handler dependency.
  • Custom error handler (e.g., ErrorRenderer) to log E_USER_DEPRECATED notices.
• Risk Areas:
  • False Sense of Security: Developers may assume deprecations are logged without verifying error-handler setup.
  • Version Skew: Mismatched package versions (e.g., symfony/deprecation-contracts vs. symfony/error-handler) could break notice visibility.

Technical Risk

• Low to Medium:
  • Implementation Risk: Minimal (1–2 lines of config + trigger_deprecation() calls).
  • Runtime Risk: Zero if unused; negligible if overridden (via function_exists() guard).
  • Debugging Risk: High if error handlers are misconfigured (e.g., deprecations silently ignored in CI).
• Mitigations:
  • CI Gate: Add a test to verify deprecations are captured (e.g., assert log output or error handler events).
  • Documentation: Clearly call out error-handler requirements in README.md or UPGRADING.md.

Key Questions

1. Error Handling Infrastructure:
   • Does the Laravel app already use Symfony\ErrorHandler or a custom handler (e.g., Sentry, Monolog)?
   • If not, what’s the effort to add one (e.g., symfony/error-handler + log channel)?
2. Deprecation Visibility Needs:
   • Should deprecations trigger immediate errors (e.g., E_USER_DEPRECATED → E_USER_WARNING in dev)?
   • Is centralized logging (e.g., ELK, Datadog) required for production monitoring?
3. Adoption Scope:
   • Will this be used only in core Laravel packages or across all internal libraries?
   • Are there legacy codebases that lack error-handler support?
4. Versioning Strategy:
   • How will deprecation version strings (e.g., 4.2.0) align with Laravel’s release cadence?
   • Should deprecations include removal timelines (e.g., "Removed in 10.0")?

Integration Approach

Stack Fit

• Laravel Native: Works seamlessly with:
  • Symfony Components: ErrorHandler, HttpKernel (for HTTP-based deprecation headers).
  • Monolog: Route E_USER_DEPRECATED to a dedicated deprecations channel.
  • Pest/Laravel Tests: Use expectDeprecation() assertions (via custom test helpers).
• Non-Laravel Stacks:
  • Standalone PHP: Requires manual ErrorHandler setup (higher effort).
  • Other Frameworks: Symfony, Lumen, or custom apps with error-handler support.

Migration Path

1. Phase 1: Pilot in a Single Package
   • Start with a non-critical Laravel package (e.g., laravel/legacy-auth).
   • Add trigger_deprecation() to 2–3 deprecated methods.
   • Verify notices appear in logs/tests.
2. Phase 2: Core Integration
   • Add symfony/error-handler to composer.json (if missing).
   • Configure App\Exceptions\Handler to log deprecations (e.g., to storage/logs/deprecations.log).
   • Update UPGRADING.md with deprecation policies.
3. Phase 3: Enforce via CI
   • Add a deprecation scan to CI (e.g., fail builds with >X new deprecations).
   • Example: GitHub Action.

Compatibility

• Backward: Zero breaking changes; trigger_deprecation() is a no-op without error handlers.
• Forward:
  • Laravel 10.0+: May integrate this natively (reduce need for manual setup).
  • PHP 8.2+: Leverages named arguments for clearer deprecation messages.
• Conflicts:
  • Other Deprecation Libraries: Avoid mixing with custom E_USER_DEPRECATED triggers.
  • Error Handler Overrides: Ensure no global trigger_deprecation() stubs exist.

Sequencing

Operational Impact

Maintenance

• Pros:
  • Low Overhead: No runtime cost when unused; minimal boilerplate (trigger_deprecation() calls).
  • Self-Documenting: Deprecations are versioned and logged, reducing "why was this removed?" support tickets.
• Cons:
  • Log Bloat: High-volume deprecations may clutter logs (mitigate with log levels or retention policies).
  • Version Management: Requires discipline to update deprecation versions (e.g., 4.2.0 → 5.0.0).

Support

• Developer Experience:
  • Clear Warnings: Users see deprecations in logs/console during upgrades.
  • Actionable: Messages include alternatives (e.g., "Use NewHelper instead").
• Support Burden:
  • Reduced: Proactive deprecation notices lower "it worked yesterday!" incidents.
  • Increased: Initial setup may require support for teams unfamiliar with error handlers.

Scaling

• Performance: Zero impact in production (no-ops when overridden or unused).
• Log Volume:
  • High-Traffic Apps: May generate thousands of deprecation logs/day (solution: aggregate by package/method).
  • Microservices: Centralize logs (e.g., ELK) to correlate deprecations across services.
• Database: No storage required unless logging to a DB (e.g., deprecations table).

Failure Modes

Ramp-Up

• For Developers:
  • Training: 30-minute session on:
    • Where/when to use trigger_deprecation() (e.g., "always at the start of deprecated methods").
    • How to test deprecations (e.g., expectDeprecation() in PHPUnit).
  • Documentation:
    • Example patterns (e.g., trait-based helpers, CI integration).
    • Anti-patterns (e.g., overriding globally, vague version strings).
• For Engineers:
  • Onboarding: Add to contributing.md as a required step for breaking changes.
  • Tooling: Provide a deprecation:scan Artisan command to list all active deprecations.
• For Product Managers:
  • Roadmap Alignment: Use deprecation data to prioritize feature removals (e.g., "Drop legacyHelper() in v11.0").
  • Customer Communication: Deprecation notices can be surfaced in changelogs or admin dashboards.