Aliaser Laravel Package

Getting Started

Minimal Steps

1. Installation:

   composer require sindyko/aliaser
   php artisan aliaser:install
   

   This publishes the config file and creates default migrations for morph map sync.

2. Register Aliases (in AppServiceProvider::boot()):

   use App\Models\User;
   use Sindyko\Aliaser\Facades\Entity;
   
   modelsMap(['user' => User::class]);
   

3. First Use Case: Replace User::find(1) with Entity::user(1) in your controllers/views.

Where to Look First

• Facade Usage: app/Facades/Entity.php (or Sindyko\Aliaser\Facades\Entity)
• Artisan Commands: php artisan aliaser:help for quick reference
• Config: config/aliaser.php for morph map and overwrite settings

Implementation Patterns

Core Workflows

1. Model Access Patterns

// Query Builder
$users = Entity::user()->where('active', true)->get();

// Static Methods
$count = Entity::user()->count();
$newUser = Entity::user()->create(['name' => 'Alice']);

// Finders
$user = Entity::user(1); // Single
$users = Entity::user([1, 2, 3]); // Multiple
$user = Entity::user(1, ['id', 'name']); // With columns

2. Livewire Integration

// Component property
public User $user; // Automatically serialized as 'user' alias

// Form handling
public PostForm $form; // Serialized as 'postForm'

3. Polymorphic Relations

// Migration (auto-handled by Aliaser)
$table->morphs('commentable'); // Stores 'post' instead of 'App\Models\Post'

// Usage
$comment->commentable_type; // Returns 'post'

4. DTO/Collection Handling

// DTO in Livewire
public UserFilterDTO $filters; // Serialized as 'userFilter'

// Eloquent Collection
public Collection $posts; // Serialized as 'elqn_clctn' with model alias

Integration Tips

1. Service Provider Setup

// app/Providers/AppServiceProvider.php
public function boot(): void
{
    // Group related models
    modelsMap([
        'user' => User::class,
        'admin' => Admin::class,
        'client' => Client::class,
    ]);

    // Livewire forms
    formsMap([
        'userForm' => UserForm::class,
        'postForm' => PostForm::class,
    ]);

    // DTOs/Value Objects
    objectsMap([
        'money' => Money::class,
        'userFilter' => UserFilterDTO::class,
    ]);
}

2. Dynamic Alias Registration

// Dynamic registration in a service
ModelRegistry::register('tempUser', TempUser::class);

// Clear after use
ModelRegistry::forget('tempUser');

3. Testing Patterns

// Clear caches before tests
ModelProxy::clearStaticMethodsCache();
ModelRegistry::clear();

// Reset morph map
Relation::enforceMorphMap([]); // Clear all

4. CLI-Driven Development

# List all aliases
php artisan aliaser:list --json | jq

# Check if an alias exists
php artisan aliaser:list --models | grep 'user'

# Get help for a specific registry
php artisan aliaser:help forms

Gotchas and Tips

Pitfalls

1. Morph Map Conflicts

• Issue: If you manually set Relation::enforceMorphMap() elsewhere, aliases may not sync.
• Fix: Disable use_morph_map in config if needed, or ensure Aliaser runs last in boot().

2. Overwrite Protection

• Issue: Default behavior throws exceptions on duplicate aliases.
• Fix: Set 'allow_overwrite' => true in config (not recommended for production).

3. Livewire Serialization Quirks

• Issue: Custom properties in DTOs/Value Objects won’t serialize unless public.
• Fix: Use protected properties with fillable or guarded arrays.

4. Static Method Caching

• Issue: Cached Reflection results may cause stale behavior in tests.
• Fix: Clear cache with ModelProxy::clearStaticMethodsCache() before tests.

Debugging Tips

1. Verify Alias Registration

php artisan aliaser:list --json

Check for typos or missing registrations.

2. Check Morph Map Sync

// Dump current morph map
dd(Relation::getMorphMap());

// Force sync
Relation::enforceMorphMap(ModelRegistry::getMorphMap());

3. Livewire Snapshot Issues

• Tool: Use Livewire’s --debug flag:

  php artisan serve --debug
  

• Check: Inspect network requests for serialized data.

4. Performance Bottlenecks

• Profile: Use ModelProxy::clearStaticMethodsCache() to measure Reflection overhead.
• Optimize: Register aliases early (e.g., in AppServiceProvider).

Extension Points

1. Custom Registries

// Extend AbstractAliasRegistry
class CustomRegistry extends AbstractAliasRegistry
{
    protected $key = 'custom';
    protected $aliasPrefix = 'custom_';
}

// Register globally
app()->singleton('customRegistry', fn() => new CustomRegistry());

2. Custom Synthesizers

// Extend AbstractSynthesizer
class CustomSynth extends AbstractSynthesizer
{
    public function canHandle($value): bool
    {
        return $value instanceof CustomClass;
    }

    public function synthesize($value)
    {
        return ['custom', $value->toArray()];
    }
}

// Register with Livewire
Livewire::synthesize('custom', CustomSynth::class);

3. Dynamic Alias Generation

// Hook into registration
ModelRegistry::register('dynamic_'.Str::uuid(), DynamicModel::class);

4. Conditional Registration

// Register only in specific environments
if (app()->environment('local')) {
    modelsMap(['debugUser' => DebugUser::class]);
}

Pro Tips

• Naming Conventions: Use kebab-case (user-post) for nested aliases.
• CLI Workflow: Alias management via php artisan aliaser:list + IDE autocomplete.
• Testing: Mock Entity facade in tests:

  $this->app->instance('aliaser', fn() => new MockEntity());
  

• Livewire: Combine with wire:model.live for reactive forms with aliases.