Client Management Package Laravel Package

Getting Started

First Steps

1. Installation

   composer require codingmatters/client-management-package
   

   Publish the package configuration and migrations:

   php artisan vendor:publish --provider="CodingMatters\ClientManagement\ClientManagementServiceProvider" --tag="config"
   php artisan vendor:publish --provider="CodingMatters\ClientManagement\ClientManagementServiceProvider" --tag="migrations"
   php artisan migrate
   

2. Key Classes

   • Client model (app/Models/Client.php): Core model for managing clients/partners.
   • ClientService facade (Client::class): Primary interface for CRUD operations.
   • ClientRepository: Handles data persistence (extendable for custom logic).

3. First Use Case Create a client via Tinker:

   use CodingMatters\ClientManagement\Facades\Client;
   
   $client = Client::create([
       'name' => 'Acme Corp',
       'email' => 'contact@acme.com',
       'contract_start_date' => now(),
       'contract_end_date' => now()->addYear(),
       'status' => 'active', // or 'pending', 'terminated'
       'partner_type' => 'premium', // or 'standard', 'trial'
   ]);
   

Implementation Patterns

Core Workflows

1. Client Lifecycle Management

   • Creation: Use Client::create() with required fields (name, email, status).
   • Updates: Patch updates with Client::update($id, ['field' => 'value']).
   • Status Transitions: Use Client::changeStatus($id, 'terminated') with validation hooks.
   • Deletion: Soft-deletes via Client::destroy($id) (check hasGlobalScope for soft-deletes).

2. Data Retrieval

   • Basic Queries:

     $activeClients = Client::where('status', 'active')->get();
     $premiumClients = Client::premium()->get(); // Uses package scope
     

   • Eager Loading:

     $clientsWithContracts = Client::with('contracts')->get();
     

   • Search:

     $searchResults = Client::search('Acme')->get(); // Uses Laravel Scout if configured.
     

3. Integration with Existing Systems

   • Events: Listen to ClientCreated, ClientStatusUpdated via Event::listen().
   • Notifications: Trigger ClientWelcomeEmail after creation:

     event(new \CodingMatters\ClientManagement\Events\ClientCreated($client));
     

   • APIs: Use ClientResource (if included) for API responses:

     return new ClientResource(Client::find($id));
     

4. Custom Logic

   • Extend Repository: Override ClientRepository methods in a service provider:

     $this->app->bind(
         \CodingMatters\ClientManagement\Repositories\ClientRepository::class,
         \App\Repositories\CustomClientRepository::class
     );
     

   • Add Scopes: Register custom query scopes in Client model:

     public function scopeByPartnerType($query, $type) {
         return $query->where('partner_type', $type);
     }
     

Gotchas and Tips

Common Pitfalls

1. Missing Required Fields

   • The Client model enforces name, email, and status as required. Validate inputs before creation:

     $validated = $request->validate([
         'name' => 'required|string|max:255',
         'email' => 'required|email',
         'status' => 'required|in:active,pending,terminated',
     ]);
     

2. Date Validation

   • contract_end_date must be after contract_start_date. Add custom validation:

     use Illuminate\Validation\Rule;
     
     $request->validate([
         'contract_end_date' => [
             'required',
             'after:contract_start_date',
             Rule::exists('clients')->ignore($client->id),
         ],
     ]);
     

3. Soft Deletes

   • The model uses SoftDeletes. Ensure queries account for this:

     // Returns all clients, including soft-deleted
     $allClients = Client::withTrashed()->get();
     

4. Scout Indexing

   • If using search(), ensure Laravel Scout is configured. Test with:

     php artisan scout:import "App\Models\Client"
     

Debugging Tips

• Log Repository Calls: Temporarily add logging to ClientRepository methods to trace data flow.
• Check Events: Verify events fire by listening to them in AppServiceProvider:

  public function boot() {
      ClientCreated::dump(); // Dump event payloads for debugging
  }
  

Extension Points

1. Custom Attributes

   • Add computed properties to the Client model:

     public function getContractDurationAttribute() {
         return $this->contract_end_date->diffInDays($this->contract_start_date);
     }
     

2. Policy Integration

   • Attach policies for authorization:

     use CodingMatters\ClientManagement\Models\Client;
     use Illuminate\Auth\Access\HandlesAuthorization;
     
     class ClientPolicy {
         use HandlesAuthorization;
     
         public function update(User $user, Client $client) {
             return $user->can('manage_clients') && $client->status !== 'terminated';
         }
     }
     

3. API Resources

   • Extend ClientResource to include custom fields:

     public function toArray($request) {
         return array_merge(parent::toArray($request), [
             'contract_duration' => $this->contract_duration,
         ]);
     }
     

4. Testing

   • Use factory for testing:

     $client = Client::factory()->create(['status' => 'active']);
     

   • Mock the repository in unit tests:

     $this->partialMock(ClientRepository::class, function ($mock) {
         $mock->shouldReceive('find')->andReturn($client);
     });