Deprecation Contracts Laravel Package

Product Decisions This Supports

• Standardized Deprecation Lifecycle: Enables a consistent, version-controlled process for phasing out legacy features in PHP/Laravel applications, reducing friction during major upgrades (e.g., Laravel 10+ migrations).
• Proactive Roadmap Communication: Provides a mechanism to signal upcoming changes to developers/users (e.g., "This API endpoint will be removed in v5.0"), aligning with Laravel’s commitment to backward compatibility.
• Build vs. Buy Tradeoff: Eliminates the need to reinvent deprecation logic (e.g., custom error handlers or logging systems) while offering a lightweight, framework-agnostic solution.
• Open-Source Ecosystem Health: Critical for Laravel packages (e.g., spatie/laravel-activitylog) to maintain compatibility during transitions, ensuring smoother adoption for end users.
• CI/CD Enforcement: Supports automated deprecation tracking (e.g., failing builds if deprecated code paths exceed thresholds), accelerating cleanup of technical debt.

When to Consider This Package

• Adopt when:

  • Building Laravel packages or monolithic apps where feature deprecation is part of the release cycle (e.g., migrating from Route::controller() to Route::resource()).
  • Centralizing deprecation notices across microservices or a monorepo (e.g., shared Laravel services).
  • Using Symfony’s ErrorHandler or a compatible system (e.g., Laravel’s built-in error handling) to log/alert on deprecations.
  • Prioritizing developer experience by reducing "surprise breakages" during upgrades (e.g., Laravel 9→10).

• Avoid when:

  • Your project has no plans to deprecate features (e.g., a one-off script or static site).
  • Using a framework with native deprecation support (e.g., Symfony components already include this).
  • Lacking infrastructure to process E_USER_DEPRECATED notices (e.g., no custom error handler or logging pipeline).
  • Preferring runtime exceptions over warnings (this package is not for breaking changes).

How to Pitch It (Stakeholders)

Executives: "This package future-proofs our Laravel ecosystem by standardizing how we communicate deprecated features—reducing support costs from unexpected breakages and keeping our roadmap transparent. For example, when we deprecate Auth::login() in favor of Auth::attempt(), developers get clear, versioned warnings before the change, not after. It’s a zero-cost investment that directly improves upgrade reliability and customer trust."

Engineering (Devs): "A single trigger_deprecation() call replaces ad-hoc trigger_error() hacks or undocumented Slack posts. It integrates with Laravel’s error handling to log usage in production (e.g., ‘legacy User::findById() called 42 times this month’), so we can proactively clean up tech debt. No dependencies, no overhead—just add it to your deprecation workflow."

Engineering (PMs/Architects): "This is the missing piece for Laravel’s gradual API evolution. Imagine deprecating Blade@if() in favor of @isset(): with this package, we can log every usage instance, set a deprecation timeline, and even automate CI checks to block deprecated paths. It’s like GitHub’s deprecation policy, but for PHP."