Deprecation Contracts Laravel Package

Product Decisions This Supports

• Standardized Deprecation Lifecycle: Enables a consistent, version-controlled approach to deprecating legacy features in Laravel applications or libraries, reducing friction during major upgrades (e.g., PHP 8.x migrations, framework version bumps).
• Proactive Roadmap Alignment: Provides visibility into deprecated feature usage, allowing PMs to prioritize deprecation timelines based on adoption data (e.g., "Deprecate Auth::old() in v10.0 after 6 months of warnings").
• Build vs. Buy Tradeoff: Eliminates the need to reinvent deprecation logic (e.g., custom error handlers, logging systems) while offering a lightweight, framework-agnostic solution that integrates with Laravel’s Symfony stack.
• Open-Source Ecosystem Trust: Critical for Laravel packages to signal backward-incompatible changes without breaking existing integrations, improving maintainability and adoption (e.g., spatie/laravel-permission deprecating old auth methods).
• CI/CD Enforcement: Supports automated deprecation monitoring in pipelines (e.g., failing builds if new deprecations exceed a threshold), ensuring technical debt is addressed proactively.

When to Consider This Package

• Adopt if:
  • Your Laravel application or package has legacy code paths slated for removal (e.g., old API endpoints, deprecated helpers).
  • You need cross-team visibility into deprecated feature usage (e.g., shared libraries used by multiple services).
  • Your team uses Symfony’s ErrorHandler or a compatible error handler (e.g., whoops, laravel-debugbar) to log notices.
  • You’re building a reusable Laravel package where deprecation warnings must align with semantic versioning (e.g., v1.x → v2.0 transitions).
• Avoid if:
  • Your project has no planned deprecations (e.g., greenfield apps with no legacy tech debt).
  • You’re using a framework with built-in deprecation tools (e.g., Symfony’s native Deprecation component in full Symfony apps).
  • Your error handling stack cannot process E_USER_DEPRECATED (e.g., default PHP error reporting without custom handlers).
  • You lack infrastructure to monitor deprecations (e.g., no logging, alerting, or CI/CD integration).

How to Pitch It (Stakeholders)

Executives: "This package future-proofs our Laravel ecosystem by giving us a standardized way to phase out old features without disrupting users. It’s a zero-cost insurance policy: by logging deprecation warnings early, we can identify which features to sunset first, reduce support costs from broken upgrades, and maintain trust in our roadmap. For example, if we deprecate Auth::once() in v11, we’ll know exactly which customers are still using it—letting us plan migrations or offer alternatives proactively."

Engineering (Devs/Architects): "A single, dependency-free function to replace our ad-hoc trigger_error() calls for deprecations. It integrates seamlessly with Laravel’s error handlers to surface warnings in dev and log them in prod—no extra work. We can even fail CI builds if new deprecations pop up unexpectedly, forcing us to clean up tech debt before it bites us. Best part? It’s a one-liner to add to any method, and it’s already battle-tested by Symfony."

Product/Tech Leads: "This lets us signal intent to developers early—e.g., ‘This API endpoint will be removed in v3.0’—while giving us data to decide when to actually remove it. For example, if we see 90% of users have migrated off oldAuthSystem(), we can confidently deprecate it sooner. It’s a force multiplier for our roadmap planning."