Id Contracts Laravel Package

Technical Evaluation

Architecture Fit

• Domain Alignment: The package appears to define ID contract interfaces (e.g., Id, IdContract, IdGenerator), suggesting it enforces a consistent ID schema across applications (e.g., UUID, ULID, or custom formats). This aligns well with:
  • Domain-Driven Design (DDD) projects requiring strict ID typing.
  • Microservices needing interoperable entity identifiers.
  • Event-driven architectures where IDs must be serializable/deserializable.
• Separation of Concerns: The subtree split from boson-php/boson implies this is a low-level dependency for ID handling, decoupled from business logic. This reduces coupling if the broader boson framework is not used.
• Laravel Compatibility: Laravel’s Eloquent already uses string/int IDs by default, but this package could enforce strong typing (e.g., Id objects) or custom ID generation (e.g., ULID for time-sorted IDs).

Integration Feasibility

• Minimal Overhead: The package is interfaces-only (no concrete implementations), meaning it can be adopted incrementally:
  • Start by typing existing IDs (e.g., Id wrapper for Eloquent models).
  • Later, replace Laravel’s default ID generation with IdGenerator implementations.
• Laravel-Specific Hooks:
  • Model Casting: Use Laravel’s CastsAttributes to convert Id objects to/from DB storage.
  • Query Scoping: Extend Builder macros to filter by Id objects.
  • API Responses: Transform Id objects to strings in JSON responses (via JsonSerializable or API resources).
• Database Impact: If using non-string IDs (e.g., ULID), ensure the DB schema supports the format (e.g., CHAR(26) for ULID).

Technical Risk

• Adoption Friction:
  • Breaking Changes: Replacing Laravel’s native id field with a custom Id type requires schema migrations and model updates.
  • Performance: Overhead of ID object instantiation vs. raw strings/ints (mitigated by Laravel’s caching).
• Dependency Isolation:
  • If boson-php/boson is later adopted, this package’s interfaces must remain backward-compatible.
  • No active maintenance (0 stars) introduces long-term risk (e.g., PHP 8.2+ compatibility).
• Testing Gaps:
  • No visible tests or examples → assume zero-downtime rollout with thorough unit/integration tests.
  • Edge cases (e.g., ID collisions, serialization) must be validated.

Key Questions

1. Why IDs as Objects?
   • Is the goal strong typing, immutability, or behavioral extensions (e.g., validation)?
   • Could Laravel’s existing HasUuids or HasUlids packages suffice?
2. ID Generation Strategy
   • Will this replace Laravel’s auto-increment IDs? If so, how will IdGenerator be seeded?
3. Database Schema
   • What storage format is assumed (e.g., string, binary)? Does it conflict with Laravel’s defaults?
4. Performance Tradeoffs
   • Will Id objects be cached in memory (e.g., via Laravel’s app() container)?
5. Future-Proofing
   • How will this interact if boson-php/boson adds ID-related features later?

Integration Approach

Stack Fit

• Laravel Ecosystem:
  • Models: Use CastsAttributes to serialize Id objects to DB storage.

    use Boson\IdContracts\Id;
    use Illuminate\Database\Eloquent\Casts\Attribute;
    
    protected function id(): Attribute {
        return Attribute::make(
            get: fn (Id $id) => $id->value(),
            set: fn (string $value) => new Id($value),
        );
    }
    

  • APIs: Leverage Laravel’s JsonSerializable or API resources to expose IDs as strings.
  • Queries: Add Builder macros for Id-based filtering:

    use Illuminate\Database\Eloquent\Builder;
    
    Builder::macro('whereId', function (Builder $query, Id $id) {
        return $query->where('id', $id->value());
    });
    

• Alternatives Considered:
  • Laravel Packages: spatie/laravel-activitylog (for UUIDs) or nWidart/absolutepath (for path-based IDs).
  • Custom Solutions: Roll your own Id trait if the package’s abstractions are overkill.

Migration Path

1. Phase 1: Typed IDs (No Schema Change)
   • Wrap existing IDs in Id objects in application logic (e.g., DTOs, services).
   • Use CastsAttributes to read/write Id objects without altering the DB.
   • Example:

     class User extends Model {
         protected $casts = ['id' => Id::class];
     }
     

2. Phase 2: Generation & Validation
   • Replace Model::incrementing(false) and use IdGenerator for new records.
   • Add validation (e.g., Id::fromString()) in API controllers.
3. Phase 3: Full Adoption
   • Migrate DB schema to store IDs as strings/binary (if needed).
   • Update all queries to use Id-aware macros.

Compatibility

• Laravel Versions:
  • Tested with Laravel 9+ (PHP 8.0+). May need adjustments for older versions.
  • Assumes PHP 8.0+ features (e.g., named arguments, union types).
• Database:
  • MySQL/PostgreSQL: Supports CHAR/VARCHAR for ULID/UUID.
  • SQLite: May require type casting for binary IDs.
• Third-Party Packages:
  • Conflict risk with packages that assume raw int/string IDs (e.g., laravel-debugbar).
  • Check for Id serialization in cached/queued jobs.

Sequencing

Operational Impact

Maintenance

• Pros:
  • Consistent ID Handling: Centralized validation/generation logic.
  • Type Safety: Catch ID-related bugs early (e.g., invalid formats).
• Cons:
  • Debugging Complexity: Stack traces may show Id objects instead of raw values.
  • Tooling Gaps: IDE autocompletion may lag for custom Id types.
• Mitigations:
  • Document Id usage patterns (e.g., "always use ->value() for DB queries").
  • Add custom error handlers for Id parsing failures.

Support

• Common Issues:
  • Serialization Errors: JSON/API responses may fail if Id isn’t JsonSerializable.
  • Migration Failures: Schema changes could break existing queries.
• Troubleshooting:
  • Log Id objects with ->value() for debugging.
  • Use Laravel’s app()->bind() to mock IdGenerator in tests.
• Documentation Needs:
  • Example: How to debug Id validation failures.
  • Example: Migrating from auto-increment to ULID.

Scaling

• Performance:
  • Positive: Strong typing may reduce runtime errors (e.g., passing null as an ID).
  • Negative: Object instantiation overhead (mitigated by Laravel’s service container).
• Database:
  • Indexing: Ensure Id fields are indexed (e.g., ULID can be indexed as CHAR).
  • Replication: No impact if IDs are generated client-side (e.g., ULID).
• Distributed Systems:
  • Idempotency: Id objects can enforce unique request IDs in queues.
  • Event Sourcing: Works well with Id-based event headers.

Failure Modes