Employee Management Package Laravel Package

Getting Started

First Steps

1. Installation

   composer require codingmatters/employee-management-package
   php artisan vendor:publish --provider="CodingMatters\EmployeeManagement\EmployeeManagementServiceProvider" --tag="config"
   php artisan migrate
   

   • Verify the config/employee-management.php file is published and configured (e.g., default_locale, timezone).

2. Basic Usage

   • Create an Employee

     use CodingMatters\EmployeeManagement\Models\Employee;
     
     $employee = Employee::create([
         'first_name' => 'John',
         'last_name'  => 'Doe',
         'email'      => 'john.doe@example.com',
         'department' => 'Engineering',
         'salary'     => 75000,
     ]);
     

   • Retrieve Employees

     $employees = Employee::all(); // Eloquent collection
     $activeEmployees = Employee::where('status', 'active')->get();
     

3. Artisan Commands

   • List available commands:

     php artisan employee:list
     

   • Generate a report (if included):

     php artisan employee:report --department=Engineering
     

Implementation Patterns

Core Workflows

1. CRUD Operations

   • Use Eloquent for standard operations (e.g., Employee::find($id)->update(...)).
   • Leverage package-provided scopes (if any) for filtering:

     $engineers = Employee::byDepartment('Engineering')->get();
     

2. Validation

   • Extend the package’s validation rules (if custom rules are needed):

     use CodingMatters\EmployeeManagement\Rules\ValidSalary;
     
     $request->validate([
         'salary' => ['required', 'numeric', new ValidSalary],
     ]);
     

3. Events & Listeners

   • Subscribe to employee lifecycle events (e.g., EmployeeCreated):

     // In EventServiceProvider
     protected $listen = [
         'CodingMatters\EmployeeManagement\Events\EmployeeCreated' => [
             'App\Listeners\SendWelcomeEmail',
         ],
     ];
     

4. API Integration

   • Use Laravel’s API resources to format responses:

     php artisan make:resource EmployeeResource
     

     // app/Http/Resources/EmployeeResource.php
     public function toArray($request) {
         return [
             'id' => $this->id,
             'name' => $this->fullName,
             'email' => $this->email,
         ];
     }
     

5. Scheduling Jobs

   • Schedule monthly salary reviews (if the package includes job classes):

     // app/Console/Kernel.php
     $schedule->job(new \CodingMatters\EmployeeManagement\Jobs\ReviewSalaries)->monthly();
     

Integration Tips

• Database Seeding Use Laravel’s seeder to populate test data:

  // database/seeders/EmployeesTableSeeder.php
  public function run() {
      \CodingMatters\EmployeeManagement\Models\Employee::factory()->count(10)->create();
  }
  

• Policy Integration Attach policies for authorization:

  // app/Policies/EmployeePolicy.php
  public function update(User $user, Employee $employee) {
      return $user->isAdmin() || $user->id === $employee->manager_id;
  }
  

• Testing Use Laravel’s testing helpers:

  $response = $this->post('/employees', [
      'first_name' => 'Test',
      'last_name'  => 'User',
  ]);
  $response->assertCreated();
  

Gotchas and Tips

Common Pitfalls

1. Missing Config

   • Forgetting to publish the config (php artisan vendor:publish) may lead to undefined settings (e.g., default_locale).
   • Fix: Run the publish command and check config/employee-management.php.

2. Model Not Found

   • If Employee model isn’t autoloaded, manually import it:

     use CodingMatters\EmployeeManagement\Models\Employee;
     

   • Fix: Ensure the Employee model is registered in config/app.php under aliases.

3. Migration Conflicts

   • If the package’s migrations conflict with existing tables, rename the package’s tables in the migration files or use a custom table name:

     // In Employee model
     protected $table = 'custom_employees';
     

4. Artisan Command Errors

   • Commands may fail if dependencies (e.g., spatie/laravel-permission) aren’t installed.
   • Fix: Install missing packages via Composer.

5. Soft Deletes

   • If the package uses soft deletes, ensure your queries account for it:

     $employees = Employee::withTrashed()->get(); // Include soft-deleted records
     

Debugging Tips

• Log Employee Actions Use Laravel’s logging to track changes:

  \Log::info('Employee created', ['employee' => $employee->toArray()]);
  

• DD() for Inspection Quickly inspect objects:

  $employee = Employee::find(1);
  dd($employee->toArray());
  

• Package Debugging Enable debug mode in the config:

  // config/employee-management.php
  'debug' => env('EMPLOYEE_MANAGEMENT_DEBUG', false),
  

Extension Points

1. Custom Fields Add extra attributes to the Employee model:

   // app/Models/Employee.php
   protected $casts = [
       'is_manager' => 'boolean',
       'hire_date'  => 'date',
   ];
   

2. Observers Extend default behavior with observers:

   // app/Observers/EmployeeObserver.php
   public function saving(Employee $employee) {
       $employee->email = strtolower($employee->email);
   }
   

   Register in AppServiceProvider:

   Employee::observe(EmployeeObserver::class);
   

3. API Resources Override default serialization:

   // app/Http/Resources/EmployeeResource.php
   public function toArray($request) {
       return [
           'id' => $this->id,
           'name' => "{$this->first_name} {$this->last_name}",
           'department' => $this->department->name, // If relationship exists
       ];
   }
   

4. Service Providers Bind custom implementations:

   // app/Providers/AppServiceProvider.php
   public function register() {
       $this->app->bind(
           \CodingMatters\EmployeeManagement\Contracts\SalaryCalculator::class,
           \App\Services\CustomSalaryCalculator::class
       );
   }
   

5. Views & Blade Share employee data with views:

   // In a controller
   return view('employees.index', ['employees' => $employees]);
   

   @foreach($employees as $employee)
       <tr>
           <td>{{ $employee->fullName }}</td>
           <td>{{ $employee->department }}</td>
       </tr>
   @endforeach