Declaration Id Laravel Package

Getting Started

Minimal Steps

1. Installation:

   composer require typhoon/declaration-id
   

   Ensure your project uses PHP 8.1+ (required by the package).

2. First Use Case: Generate a unique ID for a Laravel service class:

   use Typhoon\DeclarationId\DeclarationId;
   
   $id = DeclarationId::of(\App\Services\UserService::class);
   // Output: e.g., "a1b2c3d4e5" (a stable hash for the class)
   

3. Where to Look First:

   • API Reference: Focus on DeclarationId::of() for classes, functions, and constants.
   • Examples: Check the Typhoon monorepo releases for usage patterns.
   • Testing: Run php vendor/bin/phpunit to verify the package’s core functionality.

Implementation Patterns

Core Workflows

1. Service Binding in Laravel

Replace hardcoded binding strings with generated IDs:

// Traditional binding
$this->app->bind('user_service', \App\Services\UserService::class);

// With DeclarationId
$this->app->bind(
    DeclarationId::of(\App\Services\UserService::class),
    \App\Services\UserService::class
);

2. Macroable Classes

Use IDs to register macros dynamically:

$id = DeclarationId::of(\Illuminate\Support\Str::class);
\Illuminate\Support\Str::macro($id, function () {
    return 'Dynamic macro for Str';
});

3. Event Listeners

Generate stable IDs for event classes:

$eventId = DeclarationId::of(\App\Events\UserRegistered::class);
event(new UserRegistered());
// Later, resolve the event by its ID (if needed).

4. Blade Template Integration

Create a helper to generate IDs for views:

function bladeTemplateId(string $view): string {
    return DeclarationId::of(\Illuminate\View\View::make($view));
}

Use in Blade:

@inject('templateId', 'bladeTemplateId', ['view' => 'dashboard'])

5. Dependency Injection

Resolve services by ID in constructors:

class UserController {
    public function __construct(
        private readonly string $userServiceId
    ) {
        $this->userServiceId = DeclarationId::of(\App\Services\UserService::class);
    }
}

Integration Tips

• Cache IDs: Store generated IDs in app() or a static cache to avoid recomputation:

  $cache = app()->make('cache');
  $id = $cache->remember(
      "declaration_id:{$class}",
      now()->addHours(1),
      fn() => DeclarationId::of($class)
  );
  

• Laravel Service Provider: Register a helper class to centralize ID generation:

  $this->app->singleton('declaration-id', function () {
      return new class {
          public function generate(string $class): string {
              return DeclarationId::of($class);
          }
      };
  });
  

• Testing: Mock IDs in unit tests to avoid flakiness:

  $mockId = 'test_user_service';
  DeclarationId::shouldReceive('of')
      ->with(\App\Services\UserService::class)
      ->andReturn($mockId);
  

Gotchas and Tips

Pitfalls

1. Namespace Sensitivity: IDs are namespace-sensitive. A class App\User and Vendor\User will generate different IDs.

   • Fix: Use fully qualified names (e.g., \App\Services\UserService).

2. Anonymous Classes: Anonymous classes may produce unpredictable IDs.

   • Fix: Avoid using them in critical bindings or document their usage.

3. PHP 8.1+ Requirement: The package will not work on PHP 8.0 or lower.

   • Fix: Upgrade PHP or use a polyfill (if available).

4. ID Collisions: While rare, collisions can occur with custom naming strategies.

   • Fix: Append a suffix (e.g., DeclarationId::of($class) . '_service').

5. Blade Template Limitations: Blade components (e.g., @component) may not generate stable IDs.

   • Fix: Use a wrapper class or custom logic to generate IDs for views.

Debugging

• Log Generated IDs: Add a debug method to log IDs during development:

  DeclarationId::debug(\App\Services\UserService::class);
  // Output: "UserService => a1b2c3d4e5"
  

• Validate IDs: Ensure IDs are consistent across requests:

  $id1 = DeclarationId::of(\App\Services\UserService::class);
  $id2 = DeclarationId::of(\App\Services\UserService::class);
  assert($id1 === $id2, 'ID generation is not deterministic!');
  

• Check for Typos: Typos in class names will produce unexpected IDs. Use IDE autocompletion to verify.

Configuration Quirks

• No Built-in Laravel Hooks: The package has no Laravel-specific configuration. You must manually integrate it (e.g., in AppServiceProvider).

• Custom Naming Strategies: The default hash may not suit all use cases. Extend the package:

  class CustomDeclarationId {
      public static function of(string $class): string {
          return strtolower(str_replace('\\', '.', $class));
      }
  }
  

Extension Points

1. Support for Templates: Extend to handle Blade templates or custom view logic:

   DeclarationId::extend('blade', function ($view) {
       return DeclarationId::of(\Illuminate\View\View::make($view));
   });
   

2. Integration with Typhoon Framework: If using Typhoon, leverage its DI container for seamless ID resolution:

   use Typhoon\DependencyInjection\Container;
   
   $container->bind(
       DeclarationId::of(\App\Services\UserService::class),
       \App\Services\UserService::class
   );
   

3. Performance Optimization: Precompute IDs during class registration (e.g., in a BootstrapServiceProvider):

   $this->app->when(\App\Services\UserService::class)
       ->needs('$id')
       ->give(DeclarationId::of(\App\Services\UserService::class));
   

4. Fallback for Unsupported Declarations: Handle edge cases (e.g., anonymous functions) with a fallback:

   $id = DeclarationId::of($anonymousFunction) ?? 'anonymous_' . uniqid();