Lara Asp Eloquent Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require lastdragon-ru/lara-asp-eloquent
   

   Ensure your composer.json meets the package's PHP/Laravel version constraints (e.g., Laravel 10+ for modern features).

2. Publish Config (if needed):

   php artisan vendor:publish --provider="LastDragon\LaraAspEloquent\LaraAspEloquentServiceProvider" --tag="config"
   

   (Check if the package includes default config; likely minimal or none.)

3. First Use Case: Use the hasManyThrough or morphToMany traits directly in your Eloquent models. Example:

   use LastDragon\LaraAspEloquent\Traits\HasManyThrough;
   
   class User extends Model
   {
       use HasManyThrough;
   
       public function roles()
       {
           return $this->hasManyThrough(Role::class, UserRole::class, 'user_id', 'id');
       }
   }
   

Where to Look First

• Traits: Browse src/Traits/ for available extensions (e.g., HasManyThrough, MorphToMany, SoftDeletes).
• Documentation: Check the GitHub README for trait-specific examples.
• Tests: Review tests/ for real-world usage patterns (if available).

Implementation Patterns

Common Workflows

1. Enhancing Relationships:

   • HasManyThrough: Simplify multi-table relationships without manual joins.

     // User → UserRole → Role
     $user->roles; // Direct access to roles via UserRole pivot.
     

   • MorphToMany: Polymorphic many-to-many relationships.

     class Taggable extends Model
     {
         use MorphToMany;
     
         public function tags()
         {
             return $this->morphToMany(Tag::class, 'taggable');
         }
     }
     

2. Soft Deletes:

   • Extend SoftDeletes trait for global soft-delete behavior:

     use LastDragon\LaraAspEloquent\Traits\SoftDeletes;
     
     class Post extends Model
     {
         use SoftDeletes;
         protected $dates = ['deleted_at'];
     }
     

3. Query Scopes:

   • Use provided scopes (if any) like scopeActive():

     Post::active()->get(); // Filters soft-deleted records.
     

4. Model Events:

   • Hook into events (e.g., deleting) to trigger custom logic:

     protected static function bootSoftDeletes()
     {
         static::deleting(function ($model) {
             // Custom logic before soft delete.
         });
     }
     

Integration Tips

• Avoid Overriding Core Methods: Prefer extending traits over overriding Eloquent’s built-in methods (e.g., save(), delete()).
• Type Safety: Use PHP 8.1+ attributes (if supported) for better IDE autocompletion:

  #[HasManyThrough(Role::class, UserRole::class)]
  public function roles() {}
  

• Testing: Mock traits in unit tests:

  $user = new User();
  $user->setRelation('roles', collect([new Role()]));
  

Gotchas and Tips

Pitfalls

1. Version Mismatches:

   • The package supports Laravel 8–13 but may have quirks in older versions (e.g., PHP 8.0’s match expressions).
   • Fix: Pin Laravel/PHP versions in composer.json to avoid silent failures.

2. Trait Conflicts:

   • If using Laravel’s native HasManyThrough or MorphToMany, ensure you’re not duplicating logic.
   • Fix: Check the package’s trait source code for differences (e.g., additional query modifiers).

3. Soft Deletes Ambiguity:

   • The SoftDeletes trait might conflict with Laravel’s built-in SoftDeletes if not namespaced properly.
   • Fix: Use fully qualified trait names:

     use LastDragon\LaraAspEloquent\Traits\SoftDeletes as LaraAspSoftDeletes;
     

4. Missing Documentation:

   • The package lacks detailed trait-specific docs. Reverse-engineer usage from tests or examples.

Debugging

• Query Logs: Enable Laravel’s query logging to verify trait-generated SQL:

  DB::enableQueryLog();
  $user->roles; // Inspect DB::getQueryLog().
  

• Trait Overrides: Temporarily replace a trait with a class to debug:

  class DebugHasManyThrough {
      public function __call($method, $args) { dd($method, $args); }
  }
  

Extension Points

1. Custom Traits:

   • Fork the package to add your own traits (e.g., HasOneThrough):

     namespace App\Traits;
     use LastDragon\LaraAspEloquent\Traits\HasManyThrough as BaseTrait;
     
     trait HasOneThrough extends BaseTrait { ... }
     

2. Macros:

   • Extend Eloquent’s query builder via macros (if the package supports it):

     QueryBuilder::macro('withTrashed', function () {
         return $this->with(['trashed' => function ($query) {
             $query->whereNull('deleted_at');
         }]);
     });
     

3. Event Listeners:

   • Attach listeners to trait events (e.g., deleting):

     event(new Deleting($model));
     

Pro Tips

• Performance: For HasManyThrough, cache the intermediate model’s IDs to reduce queries:

  protected function getThroughModelIds()
  {
      return $this->relationLoaded('userRole') ? $this->userRole->pluck('role_id') : [];
  }
  

• Laravel 11+: Leverage the package’s support for Laravel’s new Model::newQueryWithoutScopes():

  $query = $this->newQueryWithoutScopes()->withTrashed();
  

• API Resources: Use traits to simplify serialization:

  public function toArray($request)
  {
      return [
          'roles' => $this->roles->pluck('name'),
      ];
  }