Deprecation Contracts Laravel Package

Technical Evaluation

Architecture Fit

• Pros:

  • Laravel/Symfony Synergy: Aligns perfectly with Laravel’s existing Symfony ErrorHandler (or similar) for centralized deprecation logging. No architectural disruption; integrates as a lightweight utility.
  • Dependency-Free: Zero runtime overhead when unused (via function_exists() guards) and minimal footprint when active. Ideal for libraries/frameworks where deprecation consistency is critical.
  • Standardized Signals: Enables versioned, actionable deprecation notices (e.g., "Removed in vX.Y") across monorepos or microservices, reducing upgrade friction.
  • Extensibility: Works alongside Laravel’s built-in deprecation tools (e.g., Deprecates trait in Symfony components) or custom error handlers (e.g., Sentry, Monolog).

• Cons:

  • No Built-in Storage: Requires external infrastructure (e.g., ErrorHandler, Sentry) to capture notices—useless without logging/monitoring.
  • PHP-Only Scope: Limited to PHP; cross-language projects (e.g., Go/Python services) need separate solutions.
  • Manual Adoption: Teams must proactively opt into deprecation tracking (e.g., configure ErrorHandler, update CI/CD).

Integration Feasibility

• Laravel-Specific:

  • Symfony ErrorHandler: Laravel’s symfony/error-handler package (or whoops) can intercept E_USER_DEPRECATED notices. Example:

    use Symfony\Component\ErrorHandler\ErrorHandler;
    
    ErrorHandler::register(); // Captures deprecations in all environments
    

  • Monolog Integration: Route deprecations to a dedicated log channel:

    ErrorHandler::setErrorRenderer(new MonologErrorRenderer(new Logger('deprecations')));
    

  • Laravel Debugbar: Display deprecations in the Debugbar panel via a custom collector.

• Migration Path:

  1. Phase 1 (Dev): Add symfony/deprecation-contracts and configure ErrorHandler to log deprecations to storage/logs/deprecations.log.
  2. Phase 2 (Prod): Enable in staging to validate notice volume/quality; integrate with monitoring (e.g., Datadog, Sentry).
  3. Phase 3 (CI/CD): Fail builds if new deprecations exceed thresholds (e.g., via custom GitHub Action).

• Compatibility:

  • PHP 8.0+: Required for E_USER_DEPRECATED (PHP 8.1+). Laravel 9+ supports this natively.
  • No Framework Lock-in: Works in vanilla PHP, Lumen, or Symfony apps, but Laravel’s ErrorHandler provides the easiest on-ramp.
  • Avoid Redundancy: Skip if using Symfony’s Deprecates trait (e.g., in Symfony bundles) or Laravel’s Deprecates facade (if available).

Technical Risk

• Critical Gaps:

  • No Visibility Without Setup: Deprecations are silently ignored unless ErrorHandler is configured. Risk of "invisible" deprecations in production.
  • Version String Precision: Incorrect versions (e.g., "next") break semantic expectations. Requires discipline in teams.

• Mitigation Strategies:

  • Guard Clauses: Wrap trigger_deprecation() in if (app()->bound('deprecation.enabled')) for feature flags.
  • Testing: Add a DeprecationTestCase to assert notices are triggered in CI:

    public function testDeprecationIsTriggered() {
        $this->expectDeprecation('my/package', '1.0', 'Old method is deprecated');
        oldMethod();
    }
    

  • Fallback: Provide a polyfill for PHP <8.1 using trigger_error(E_USER_DEPRECATED, ...).

• Key Questions for TPM:

  1. Monitoring: How will deprecations be surfaced to developers/ops? (e.g., Slack alerts, dashboard widgets).
  2. Ownership: Who will maintain the ErrorHandler configuration and log analysis?
  3. Deprecation Lifecycle: What’s the SLA for removing deprecated code after notices are issued?
  4. Cross-Team Impact: Are other services (e.g., Go microservices) affected? If so, how will deprecations be synchronized?

Integration Approach

Stack Fit

• Laravel Ecosystem:
  • Primary Use Case: Libraries/frameworks (e.g., custom packages, service containers) where API evolution requires backward compatibility.
  • Secondary Use Case: Monolithic apps with legacy codebases needing gradual cleanup signals.
• Non-Laravel PHP: Works anywhere with Symfony ErrorHandler or a compatible error renderer (e.g., whoops).
• Anti-Patterns:
  • Overuse in CLI Apps: Deprecations add noise in scripts where upgrades are infrequent.
  • Production-Only Ignoring: Silencing deprecations in prod without logging defeats the purpose.

Migration Path

Compatibility

• Laravel Versions:
  • Laravel 9+: Native PHP 8.1+ support for E_USER_DEPRECATED.
  • Laravel 8.x: Requires PHP 8.0 + manual polyfill for E_USER_DEPRECATED.
• Error Handlers:
  • Symfony ErrorHandler: Recommended (built into Laravel via symfony/error-handler).
  • Whoops: Supports deprecations via Whoops\Handler\PlainTextHandler.
  • Custom: Extend Symfony\Component\ErrorHandler\ErrorRendererInterface.
• CI/CD:
  • GitHub Actions: Use php -d error_reporting=E_USER_DEPRECATED in test jobs.
  • GitLab CI: Configure error_reporting in .gitlab-ci.yml.

Sequencing

1. Short-Term (0–2 Weeks):
   • Install package and ErrorHandler.
   • Add 1–2 deprecation notices in high-impact legacy code.
   • Verify notices appear in logs.
2. Medium-Term (2–6 Weeks):
   • Integrate with monitoring (e.g., Sentry, Datadog).
   • Automate deprecation threshold checks in CI.
   • Document the deprecation process for the team.
3. Long-Term (6+ Weeks):
   • Deprecate and remove legacy features based on usage data.
   • Sunset the package if Laravel/Symfony adopts a native solution.

Operational Impact

Maintenance

• Proactive:
  • Deprecation Logs: Require teams to review deprecations.log weekly (e.g., via Slack alerts).
  • Automated Cleanup: Use a cron job to parse logs and notify maintainers of unused deprecations:

    # Example: Find deprecations with zero usage in the last 30 days
    grep "Since my/package" storage/logs/deprecations.log | awk '{print $NF}' | sort | uniq -c | grep -v "[0-9]"
    

• Reactive:
  • ErrorHandler Updates: Monitor Symfony ErrorHandler releases for breaking changes.
  • Deprecation Backlog: Track Jira tickets for deprecated features with removal timelines.

Support

• Developer Experience:
  • Clear Messaging: Deprecation notices should include:
    • Action Required: "Use X instead of Y."
    • Timeline: "Removed in v2.0 (6 months)."
    • Impact: "Affects API endpoints /legacy."
  • Debugging: Provide a DeprecationDebugger facade to list active deprecations in Tinker:

    DeprecationDebugger::listActive(); // Returns array of triggered deprecations
    

• Support Overhead:
  • Initial Burden: Teams must update error handlers and CI/CD pipelines