Declaration Id Laravel Package

Product Decisions This Supports

• Standardization of Laravel Service Identifiers: Enables consistent, machine-generated IDs for classes, functions, and services, reducing ambiguity in dependency injection (DI) and improving maintainability. Aligns with Laravel’s principle of explicit bindings while adding a layer of automation.
• Tooling & Ecosystem Expansion: Foundational for building advanced Laravel tools (e.g., auto-generated DI bindings, smart IDE helpers, or debugging utilities) that rely on stable, unique identifiers for declarations. Example: Replace manual bind('App\Services\Foo', Foo::class) with bind(DeclarationId::of(Foo::class), Foo::class).
• Build vs. Buy: Justifies building custom Laravel-specific tooling (e.g., a dynamic service resolver or Blade template ID generator) on top of this package rather than reinventing identifier logic or relying on fragile string literals.
• Use Cases:
  • Dependency Injection: Auto-generate stable service IDs for Laravel’s container, reducing manual binding errors.
  • Code Generation: Stable identifiers for dynamically created classes (e.g., event listeners, commands) to avoid collisions.
  • Debugging/Profiling: Unique IDs for cross-referencing stack traces, performance metrics, or logs (e.g., DeclarationId::of(Foo::class) in Laravel\Log).
  • Security Scanning: Track declarations in static analysis tools (e.g., phpstan, psalm) with unambiguous references.
  • Laravel-Specific Enhancements:
    • Blade Templates: Generate IDs for dynamic views (e.g., @inject('view_id', DeclarationId::of(View::make('foo')))).
    • Macros/Traits: Stable IDs for macroable classes (e.g., Str::macro() registrations).
    • Event Listeners: Auto-bind listeners using DeclarationId::of(FooListener::class).

When to Consider This Package

• Adopt if:

  • Your Laravel project has complex DI bindings (e.g., 50+ services) and you want to reduce manual binding errors or enable auto-generation.
  • You’re building tooling that requires stable, unique identifiers (e.g., a custom debugger, static analyzer, or IDE plugin).
  • You need interoperability between PHP tools (e.g., linking errors to source declarations in laravel/ide-helper).
  • Your team uses code generation (e.g., dynamic classes, events, or commands) and needs to avoid ID collisions.
  • You’re aligned with Typhoon’s ecosystem (e.g., using Typhoon Framework or planning future integration).
  • You’re on PHP 8.1+ (Laravel 9/10+) and can adopt the package with minimal risk.

• Look elsewhere if:

  • Your project uses basic DI bindings (e.g., <20 services) and manual strings are sufficient.
  • You don’t need persistent, unique IDs (e.g., simple logging or one-off scripts).
  • You’re constrained by PHP < 8.1 (package requires PHP 8.1+).
  • The package’s maturity (0 stars, no dependents) is a blocker for mission-critical systems (mitigate by starting with a pilot).
  • You prefer Laravel-native solutions (e.g., app:bind with string literals) and don’t want to introduce a third-party dependency.

How to Pitch It (Stakeholders)

For Executives: *"This package solves a hidden pain point in Laravel: manual dependency binding errors and ambiguous service identifiers. By adopting it, we can:

• Automate DI bindings, reducing boilerplate and human error in AppServiceProvider.
• Future-proof tooling (e.g., debugging, security scanning) with stable, machine-readable IDs.
• Align with modern PHP practices (PHP 8.1+, Typhoon ecosystem) while keeping the MIT license risk-free. Ask: Should we pilot this for [specific high-impact service] to validate its ROI before wider adoption?"*

For Engineering: *"Typhoon’s declaration-id gives us a battle-tested way to generate unique, collision-free IDs for Laravel classes/services. Here’s why it’s worth adopting:

• For DI: Replace bind('App\Services\Foo', Foo::class) with bind(DeclarationId::of(Foo::class), Foo::class) to eliminate string typos.
• For Tooling: Enable stable references for debuggers, IDE helpers, or security scanners.
• For Code Gen: Safe IDs for dynamic classes (e.g., event listeners, commands). Proposal:

1. Pilot: Test ID generation for 3–5 critical services in a feature branch.
2. Integrate: Build a DeclarationIdResolver service to auto-bind classes in AppServiceProvider.
3. Expand: Use IDs in Blade templates, macros, or logging as needed. Risk: Low (MIT license, PHP 8.1+ compatible, minimal overhead). Let’s start with [specific use case] to prove value."*

For Developers: *"This package lets us stop guessing service names and let the computer generate them. For example:

// Before: Manual binding (error-prone)
bind('App\Services\AnalyticsService', AnalyticsService::class);

// After: Auto-generated ID (stable, no typos)
bind(DeclarationId::of(AnalyticsService::class), AnalyticsService::class);

Why it matters:

• No more ClassNotFoundException from typos.
• Works seamlessly with Laravel’s DI container.
• Enables future tooling (e.g., smarter debugging). How to start:

1. Install: composer require typhoon/declaration-id.
2. Test: DeclarationId::of(Foo::class) → outputs a unique hash.
3. Replace 1–2 bindings manually to validate. Questions? Let’s pair on a PR!"*