Trainings Laravel Package

Getting Started

Minimal Steps

1. Installation:

   composer require moox/trainings
   php artisan mooxtrainings:install
   

   • This publishes migrations, config, and sets up the package's database tables.

2. First Use Case:

   • Define a Training:

     use Moox\Trainings\Facades\Training;
     
     Training::create([
         'title' => 'Laravel Best Practices',
         'description' => 'Advanced Laravel techniques',
         'duration_hours' => 8,
     ]);
     

   • Retrieve Trainings:

     $trainings = Training::all();
     

3. Where to Look First:

   • Config: config/trainings.php (published via vendor:publish).
   • Migrations: database/migrations/[timestamp]_create_trainings_tables.php.
   • Facade/API: Moox\Trainings\Facades\Training for fluent queries.
   • Docs: Check the CHANGELOG for breaking changes or new features.

Implementation Patterns

Core Workflows

1. CRUD Operations:

   • Use the Training facade for Eloquent-like operations:

     // Create
     Training::create([...]);
     
     // Read
     Training::find($id);
     Training::where('duration_hours', '>', 4)->get();
     
     // Update
     Training::find($id)->update(['title' => 'New Title']);
     
     // Delete
     Training::destroy($id);
     

2. Event Integration:

   • Listen to training events (e.g., TrainingCreated, TrainingUpdated) via Laravel's event system:

     // In EventServiceProvider
     protected $listen = [
         'Moox\Trainings\Events\TrainingCreated' => [
             'App\Listeners\LogTrainingCreation',
         ],
     ];
     

3. API Resources:

   • Transform trainings into API responses using Laravel's Resource classes:

     php artisan make:resource TrainingResource
     

     // In TrainingResource
     public function toArray($request) {
         return [
             'id' => $this->id,
             'title' => $this->title,
             'duration' => $this->duration_hours,
         ];
     }
     

4. Policy Integration:

   • Attach policies to control access:

     php artisan make:policy TrainingPolicy --model=Training
     

     // In TrainingPolicy
     public function update(User $user, Training $training) {
         return $user->isAdmin();
     }
     

5. Queued Jobs:

   • Dispatch jobs for async operations (e.g., sending training completion emails):

     use Moox\Trainings\Jobs\SendTrainingCompletionEmail;
     
     SendTrainingCompletionEmail::dispatch($training);
     

Integration Tips

• Service Providers: Extend the package's functionality by binding additional services in AppServiceProvider:

  public function register() {
      $this->app->bind(
          'Moox\Trainings\Contracts\TrainingRepository',
          'App\Repositories\CustomTrainingRepository'
      );
  }
  

• Views: Share training data with Blade templates:

  // In a controller
  return view('trainings.show', ['training' => Training::find($id)]);
  

  <!-- resources/views/trainings/show.blade.php -->
  <h1>{{ $training->title }}</h1>
  <p>Duration: {{ $training->duration_hours }} hours</p>
  

• Testing: Use Laravel's testing helpers to mock the facade:

  $this->mock(Moox\Trainings\Facades\Training::class)
       ->shouldReceive('find')
       ->andReturn($mockTraining);
  

Gotchas and Tips

Pitfalls

1. Migration Conflicts:

   • If you manually modify migrations after installation, reset them carefully:

     php artisan migrate:fresh --seed
     

   • Tip: Use php artisan vendor:publish --tag=trainings-migrations to re-publish migrations if needed.

2. Facade vs. Direct Model Access:

   • The facade (Training) may have additional methods not available on the raw Training model. Check the facade's source for undocumented features.

3. Config Overrides:

   • Custom config values in config/trainings.php may not reflect in runtime if the package caches config. Clear the config cache:

     php artisan config:clear
     

4. Event Listeners:

   • Ensure listeners are registered in EventServiceProvider or a service provider. Missing listeners may cause silent failures.

5. Database Seeding:

   • The package may not include seeders. Create your own:

     php artisan make:seeder TrainingsTableSeeder
     

     // In TrainingsTableSeeder
     public function run() {
         \Moox\Trainings\Facades\Training::factory()->count(10)->create();
     }
     

Debugging

1. Query Logs: Enable Laravel's query logging to debug facade queries:

   DB::enableQueryLog();
   $trainings = Training::all();
   dd(DB::getQueryLog());
   

2. Model Events: Use observables to debug model events:

   Training::observe(TrainingObserver::class);
   

   // In TrainingObserver
   public function saved(Training $training) {
       \Log::info("Training saved: {$training->title}");
   }
   

3. Package Logs: Check the package's logs (if configured) or add debug statements:

   \Log::debug('Training data:', ['data' => $training->toArray()]);
   

Extension Points

1. Custom Attributes: Add computed attributes to the Training model:

   // In app/Models/Training.php (if extended)
   public function getFormattedDurationAttribute() {
       return "{$this->duration_hours} hours";
   }
   

2. API Extensions: Extend the facade with custom methods:

   // In AppServiceProvider
   public function boot() {
       \Moox\Trainings\Facades\Training::macro('search', function ($query) {
           return $this->where('title', 'like', "%{$query}%");
       });
   }
   

   Usage:

   Training::search('Laravel')->get();
   

3. Validation Rules: Add custom validation rules for training data:

   use Illuminate\Support\Facades\Validator;
   
   $validator = Validator::make($data, [
       'duration_hours' => ['required', 'integer', 'min:1', 'max:48'],
   ]);
   

4. Testing Facade: Mock the facade in tests to isolate logic:

   $this->partialMock(Moox\Trainings\Facades\Training::class, function ($mock) {
       $mock->shouldReceive('find')->andReturn($mockTraining);
   });
   

5. Localization: Extend the package's language lines by publishing translations:

   php artisan vendor:publish --tag=trainings-translations
   

   Then override in resources/lang/en/trainings.php.