Laravel Hashid Laravel Package

Technical Evaluation

Architecture Fit

• Use Case Alignment: Ideal for systems requiring obfuscated, non-sequential IDs (e.g., user-facing URLs, API endpoints, or security-sensitive identifiers). Fits well in Laravel-based microservices, SaaS platforms, or e-commerce where ID predictability is a risk.
• ORM Integration: Seamlessly integrates with Eloquent, leveraging Laravel’s query builder without breaking existing migrations or relationships. Supports customizable hash configurations (e.g., alphabet, salt, length).
• Performance Considerations:
  • Hash generation is CPU-bound (HashId algorithm). Benchmark impact on high-throughput systems (e.g., >10K writes/sec).
  • Database index implications: Hashes are non-sequential; ensure queries using hashed IDs (e.g., where('hashed_id', '...')) are optimized with composite indexes or full-text search if needed.

Integration Feasibility

• Laravel Version Support: Compatible with Laravel 9+ (check composer.json for exact versions). Verify compatibility with your PHP version (8.1+ recommended).
• Database Agnostic: Works with MySQL, PostgreSQL, SQLite, SQL Server (via Eloquent). No schema changes required beyond adding the hashed_id column.
• Existing Workflows:
  • Migrations: Supports auto-generation during model creation or via mutators.
  • APIs: Enables hash-based endpoints (e.g., /users/{hashed_id}) while preserving internal DB IDs.
  • Legacy Systems: Can coexist with existing ID schemes (e.g., UUIDs) if configured per-model.

Technical Risk

• Collision Risk: HashId is not cryptographically secure; collisions are possible but mitigated by:
  • Configurable alphabet length (default: 22 chars).
  • Salt per-model to reduce cross-model collisions.
  • Risk: Low for most use cases, but validate with load testing if IDs are user-generated.
• Backward Compatibility:
  • Breaking Changes: None in recent releases (MIT license, active maintenance).
  • Deprecations: Monitor for Laravel version drops (e.g., if Laravel 10+ introduces breaking changes).
• Security:
  • No encryption: Hashes are deterministic (same input → same output). Not suitable for PII or sensitive data.
  • Timing Attacks: Mitigated by default, but ensure no side-channel leaks in custom implementations.
• Testing Gaps:
  • Edge Cases: Limited documentation on concurrent writes or very large datasets (e.g., >1B records).
  • Mitigation: Unit test hash generation under load; validate with property-based testing (e.g., using PestPHP).

Key Questions

1. Use Case Justification:
   • Why obfuscate IDs? (Security? UX? Compliance?)
   • Are hashed IDs required for all models, or only specific ones (e.g., public-facing)?
2. Performance:
   • What’s the expected write volume? Benchmark hash generation vs. DB writes.
   • Will hashed IDs be used in frequent queries? (Impact on indexing.)
3. Migration Strategy:
   • How will existing IDs (e.g., UUIDs, auto-increments) transition to hashes?
   • Need for dual-write periods (old + new IDs)?
4. Customization:
   • Are default hash parameters (alphabet, salt) sufficient, or needed per-model?
   • Will custom hash formats (e.g., base62) be required?
5. Monitoring:
   • How will collisions or generation failures be detected/alerted?
   • Need for audit logs of hash generation?

Integration Approach

Stack Fit

• Laravel Ecosystem:
  • Native Support: Works with Eloquent models, relationships, and query builder.
  • APIs: Integrates with Laravel Sanctum/Passport for hash-based auth endpoints.
  • Frontend: Enables clean URLs (e.g., /products/aB3#xyz) without exposing DB IDs.
• Non-Laravel Components:
  • Database: No changes needed beyond adding a hashed_id column (e.g., string or varchar).
  • Caching: Hashes are cache-friendly (immutable per-ID), but avoid caching generation logic.
  • Third-Party Services: If IDs are shared externally (e.g., payment gateways), ensure they support non-sequential IDs.

Migration Path

1. Assessment Phase:
   • Audit models requiring hashed IDs. Prioritize by public exposure and security needs.
   • Identify query patterns using current IDs (e.g., where('id', $userId)) to plan replacements.
2. Implementation:
   • Step 1: Add hashed_id column to target tables (e.g., via migration):

     Schema::table('users', function (Blueprint $table) {
         $table->string('hashed_id')->unique()->after('id');
     });
     

   • Step 2: Apply the package to models:

     use Veelasky\HashId\HashIdTrait;
     
     class User extends Model {
         use HashIdTrait;
         protected $hashId = 'hashed_id'; // Custom column name
     }
     

   • Step 3: Update API routes/controllers to use hashed IDs:

     Route::get('/users/{hashed_id}', [UserController::class, 'show']);
     

   • Step 4: For existing data, backfill hashes via:

     User::chunk(1000, function ($users) {
         foreach ($users as $user) {
             $user->hashed_id = $user->getHashId();
             $user->save();
         }
     });
     

3. Deprecation:
   • Gradually phase out old ID usage in APIs, UI, and internal services.
   • Use feature flags to toggle hash generation for testing.

Compatibility

• Laravel Features:
  • Relationships: Works with belongsTo, hasMany, etc., but ensure foreign keys reference original IDs.
  • Scopes/Queries: Custom scopes using hashed IDs require indexing (e.g., whereHas('posts', fn($q) => $q->whereHashedId($hash))).
  • Events/Observers: Hash generation can be triggered in creating or saving events.
• Third-Party Packages:
  • Laravel Nova: Supports hashed IDs in detail views/lists if configured.
  • Laravel Cashier: May need custom logic for subscription IDs.
  • Testing: Use HashId::encode()/decode() in feature tests to mock hashes.

Sequencing

1. Critical Path:
   • API Layer: Update routes/controllers first to avoid breaking changes.
   • Database: Migrate hashed_id columns in a low-traffic window.
   • Frontend: Update UI links/API calls last (to minimize user impact).
2. Rollback Plan:
   • Keep original IDs until hashed IDs are fully adopted.
   • Implement a fallback mechanism (e.g., try hashed ID, fall back to original).
3. Phased Rollout:
   • Phase 1: Non-critical models (e.g., internal logs).
   • Phase 2: Public-facing models (e.g., products, users).
   • Phase 3: Core models (e.g., orders, payments) with dual-write support.

Operational Impact

Maintenance

• Package Updates:
  • Monitor GitHub releases for Laravel version support.
  • Test updates in staging for breaking changes (e.g., new config options).
• Custom Logic:
  • Override getHashId() or setHashId() for model-specific rules.
  • Extend with traits/mixins for reusable hash logic.
• Documentation:
  • Update API specs to reflect hash-based endpoints.
  • Document hash generation rules for developers (e.g., "User IDs use alphabet X").

Support

• Troubleshooting:
  • Common Issues:
    • Collisions: Log and retry with new salt.
    • Performance: Optimize hash length or batch generation.
    • Query failures: Ensure indexes exist for hashed columns.
  • Debugging Tools:
    • Add a HashId::decode($hash) helper to logs for validation.
    • Use tinker to test hash generation:

      $user = new User; $user->id = 123; echo $user->hashed_id;
      

• Support Matrix:
  • L1: Handle basic hash generation queries.
  • L2: Debug collisions or performance issues.
  • L3: Custom hash algorithm changes (rare