Pando Employee Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require blackboxcode/pando-employee-bundle
   

   Add to config/bundles.php:

   BlackBoxCode\PandoEmployeeBundle\PandoEmployeeBundle::class => ['all' => true],
   

2. Publish Configuration

   php artisan vendor:publish --provider="BlackBoxCode\PandoEmployeeBundle\PandoEmployeeProvider"
   

   Edit config/pando_employee.php to match your HR system API credentials.

3. First Use Case: Fetch Employee Data Inject the service into a controller or command:

   use BlackBoxCode\PandoEmployeeBundle\Service\EmployeeService;
   
   public function __construct(private EmployeeService $employeeService) {}
   
   public function getEmployeeData(int $employeeId) {
       $employee = $this->employeeService->fetchEmployee($employeeId);
       return view('employee.profile', compact('employee'));
   }
   

4. Environment Setup Ensure .env has:

   PANDO_API_KEY=your_api_key_here
   PANDO_API_SECRET=your_api_secret_here
   PANDO_BASE_URL=https://your-hr-system-api.com
   

Implementation Patterns

Core Workflows

1. CRUD Operations

   // Create
   $newEmployee = $this->employeeService->create([
       'first_name' => 'John',
       'last_name'  => 'Doe',
       'email'      => 'john@example.com',
   ]);
   
   // Read
   $employee = $this->employeeService->fetch(123);
   
   // Update
   $this->employeeService->update(123, ['department' => 'Engineering']);
   
   // Delete
   $this->employeeService->delete(123);
   

2. Bulk Operations

   // Sync departments
   $this->employeeService->syncDepartments([
       ['id' => 1, 'name' => 'Marketing'],
       ['id' => 2, 'name' => 'Sales'],
   ]);
   

3. Event-Driven Integration Listen for employee events in EventServiceProvider:

   protected $listen = [
       'BlackBoxCode\PandoEmployeeBundle\Events\EmployeeCreated' => [
           'App\Listeners\LogEmployeeCreation',
       ],
   ];
   

Integration Tips

• Laravel Eloquent Sync: Use HasMany relationships to link employees to models:

  public function employees() {
      return $this->hasMany(Employee::class)->using(EmployeeModel::class);
  }
  

• API Rate Limiting: Implement middleware to handle API throttling:

  $middleware = [
      \BlackBoxCode\PandoEmployeeBundle\Http\Middleware\RateLimit::class,
  ];
  

• Caching: Cache frequent queries with Cache::remember:

  $employee = Cache::remember("employee_{$id}", now()->addHours(1), function() use ($id) {
      return $this->employeeService->fetch($id);
  });
  

Gotchas and Tips

Common Pitfalls

1. API Key Validation

   • Issue: Silent failures if PANDO_API_KEY is missing.
   • Fix: Validate in AppServiceProvider:

     if (!config('pando_employee.api_key')) {
         throw new \RuntimeException('Pando API key not configured.');
     }
     

2. Data Mismatch

   • Issue: Field names in API response differ from local DB schema.
   • Fix: Use mapResponse in config/pando_employee.php:

     'field_mapping' => [
         'employee_id' => 'id',
         'full_name'   => 'first_name',
     ],
     

3. Webhook Verification

   • Issue: Unverified webhook payloads from Pando.
   • Fix: Implement PandoWebhookMiddleware:

     use BlackBoxCode\PandoEmployeeBundle\Http\Middleware\VerifyPandoSignature;
     
     $middleware = [
         VerifyPandoSignature::class,
     ];
     

Debugging Tips

• Enable API Logging Add to config/pando_employee.php:

  'debug' => env('APP_DEBUG', false),
  

  Logs will appear in storage/logs/pando.log.

• Mock API Responses Use PandoEmployeeBundle's testing trait:

  use BlackBoxCode\PandoEmployeeBundle\Tests\TestCase;
  
  public function testEmployeeFetch() {
      $this->mockPandoResponse('employee', ['id' => 1, 'name' => 'Test']);
      $employee = $this->employeeService->fetch(1);
      $this->assertEquals('Test', $employee['name']);
  }
  

Extension Points

1. Custom Fields Extend the Employee model:

   namespace App\Models;
   
   use BlackBoxCode\PandoEmployeeBundle\Models\Employee as BaseEmployee;
   
   class Employee extends BaseEmployee {
       protected $appends = ['custom_field'];
       public function getCustomFieldAttribute() {
           return $this->attributes['custom_field'] ?? null;
       }
   }
   

2. Custom API Endpoints Create a decorator for EmployeeService:

   namespace App\Services;
   
   use BlackBoxCode\PandoEmployeeBundle\Service\EmployeeService as BaseService;
   
   class EmployeeService extends BaseService {
       public function customEndpoint($params) {
           return $this->client->request('GET', '/custom', $params);
       }
   }
   

   Bind in AppServiceProvider:

   $this->app->bind(
       \BlackBoxCode\PandoEmployeeBundle\Service\EmployeeService::class,
       \App\Services\EmployeeService::class
   );
   

3. Webhook Handlers Register custom handlers in config/pando_employee.php:

   'webhook_handlers' => [
       'employee.created' => \App\Listeners\HandleEmployeeCreated::class,
       'department.updated' => \App\Listeners\SyncDepartmentCache::class,
   ],