Third Party Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require chill-project/third-party
   

   Publish the package configuration and migrations:

   php artisan vendor:publish --provider="ChillProject\ThirdParty\ThirdPartyServiceProvider" --tag="config"
   php artisan vendor:publish --provider="ChillProject\ThirdParty\ThirdPartyServiceProvider" --tag="migrations"
   php artisan migrate
   

2. First Use Case Define a third-party category via the ThirdPartyCategory model:

   use ChillProject\ThirdParty\Models\ThirdPartyCategory;
   
   $category = ThirdPartyCategory::create([
       'name' => 'Marketing Agency',
       'description' => 'External marketing partners',
       'slug' => 'marketing-agency',
   ]);
   

3. Key Files to Review

   • config/third-party.php: Default settings (e.g., allowed fields, validation rules).
   • app/Models/ThirdPartyCategory.php: Model logic (extend if needed).
   • routes/third-party.php: Predefined API/web routes (publishable).

Implementation Patterns

Core Workflows

1. CRUD Operations Use Eloquent for standard operations:

   // Create
   $thirdParty = $category->thirdParties()->create([
       'name' => 'Acme Corp',
       'contact_email' => '[email protected]',
       'notes' => 'Preferred vendor',
   ]);
   
   // Query
   $partners = ThirdPartyCategory::find(1)->thirdParties()->with('contacts')->get();
   

2. Validation Leverage the package’s built-in validation (extend via config):

   // config/third-party.php
   'validation' => [
       'third_parties' => [
           'name' => 'required|string|max:255',
           'contact_email' => 'required|email',
       ],
   ];
   

3. API Integration Use the pre-defined routes (/api/third-parties) or extend with custom controllers:

   Route::get('/custom-partners', [ThirdPartyController::class, 'customIndex']);
   

4. Event Listeners Subscribe to package events (e.g., ThirdPartyCreated):

   // app/Providers/EventServiceProvider.php
   protected $listen = [
       'ChillProject\ThirdParty\Events\ThirdPartyCreated' => [
           'App\Listeners\LogThirdPartyCreation',
       ],
   ];
   

Advanced Patterns

• Policy Integration Attach policies to the ThirdParty model for authorization:

  use ChillProject\ThirdParty\Models\ThirdParty;
  use Illuminate\Auth\Access\HandlesAuthorization;
  
  class ThirdPartyPolicy
  {
      use HandlesAuthorization;
  
      public function viewAny($user) { ... }
  }
  

• Custom Fields Extend the ThirdParty model to add dynamic fields:

  class ThirdParty extends \ChillProject\ThirdParty\Models\ThirdParty
  {
      protected $casts = [
          'custom_metadata' => 'array',
      ];
  }
  

Gotchas and Tips

Common Pitfalls

1. Migration Conflicts

   • If extending the third_parties table, always run:

     php artisan vendor:publish --tag="migrations" --force
     

     Then merge changes manually.

2. Slug Uniqueness The package auto-generates slugs from name, but collisions may occur. Override the getRouteKeyName() in your model if needed:

   public function getRouteKeyName()
   {
       return 'uuid'; // Use UUID instead of slug
   }
   

3. Soft Deletes The ThirdParty model uses soft deletes by default. To disable:

   use Illuminate\Database\Eloquent\SoftDeletes;
   
   class ThirdParty extends \ChillProject\ThirdParty\Models\ThirdParty
   {
       use SoftDeletes;
       // ...
       protected $dates = []; // Disable soft deletes
   }
   

Debugging Tips

• Log Queries Enable Laravel’s query logging in config/debugbar.php or use:

  \DB::enableQueryLog();
  $partners = ThirdParty::all();
  \Log::info(\DB::getQueryLog());
  

• Event Debugging Listen for events in Tinker:

  php artisan tinker
  >> event(new \ChillProject\ThirdParty\Events\ThirdPartyCreated($thirdParty));
  

Extension Points

1. Custom Models Override the default models by binding them in AppServiceProvider:

   public function register()
   {
       $this->app->bind(
           \ChillProject\ThirdParty\Models\ThirdParty::class,
           \App\Models\CustomThirdParty::class
       );
   }
   

2. API Resources Extend the default ThirdPartyResource:

   namespace App\Http\Resources;
   
   use ChillProject\ThirdParty\Http\Resources\ThirdPartyResource as BaseResource;
   
   class CustomThirdPartyResource extends BaseResource
   {
       public function toArray($request)
       {
           $array = parent::toArray($request);
           $array['custom_field'] = $this->custom_field;
           return $array;
       }
   }
   

3. Service Providers Override the package’s service provider to add custom logic:

   class AppServiceProvider extends \ChillProject\ThirdParty\ThirdPartyServiceProvider
   {
       public function register()
       {
           parent::register();
           // Add custom bindings
       }
   }