Ultipro Sdk Php Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require brianfreytag/ultipro-sdk-php
   

   Verify the package loads in config/app.php under providers.

2. Configuration Copy .env.example to .env and set:

   ULTRAPRO_CLIENT_ID=your_client_id
   ULTRAPRO_CLIENT_SECRET=your_secret
   ULTRAPRO_BASE_URL=https://api.ultipro.com
   

3. First Use Case: Authentication

   use BrianFreytag\UltiproSdk\Ultipro;
   
   $client = new Ultipro(config('ultipro.client_id'), config('ultipro.client_secret'));
   $token = $client->authenticate(); // Returns OAuth2 token
   

4. Key Files to Review

   • config/ultipro.php (default config)
   • src/Ultipro.php (core client class)
   • src/Exceptions/ (custom exceptions)

Implementation Patterns

Workflow: CRUD Operations

Employees Example

$client = new Ultipro(config('ultipro.client_id'), config('ultipro.client_secret'));
$client->authenticate();

// Fetch all employees
$employees = $client->get('/employees');

// Create a new employee
$newEmployee = $client->post('/employees', [
    'first_name' => 'John',
    'last_name' => 'Doe',
    'email' => 'john@example.com'
]);

// Update an employee
$client->put("/employees/{$employeeId}", [
    'email' => 'john.doe@example.com'
]);

// Delete an employee
$client->delete("/employees/{$employeeId}");

Integration with Laravel Services

Service Provider Binding

// app/Providers/AppServiceProvider.php
public function register()
{
    $this->app->singleton('ultipro', function ($app) {
        $client = new Ultipro(config('ultipro.client_id'), config('ultipro.client_secret'));
        $client->authenticate();
        return $client;
    });
}

Usage in Controllers

public function getEmployees(Request $request)
{
    $employees = app('ultipro')->get('/employees');
    return response()->json($employees);
}

Pagination Handling

$employees = $client->get('/employees', [
    'page' => 1,
    'per_page' => 50
]);

// Process paginated results
foreach ($employees['data'] as $employee) {
    // ...
}

Gotchas and Tips

Common Pitfalls

1. Token Expiry

   • The SDK does not auto-refresh tokens. Handle TokenExpiredException:

     try {
         $data = $client->get('/employees');
     } catch (\BrianFreytag\UltiproSdk\Exceptions\TokenExpiredException $e) {
         $client->authenticate(); // Re-authenticate
         $data = $client->get('/employees');
     }
     

2. Rate Limiting

   • Ulitpro may throttle requests. Implement exponential backoff:

     use BrianFreytag\UltiproSdk\Exceptions\RateLimitException;
     
     try {
         $client->get('/employees');
     } catch (RateLimitException $e) {
         sleep($e->getRetryAfter());
         $client->get('/employees');
     }
     

3. Endpoint Quirks

   • Some endpoints require snake_case for parameters (e.g., first_name instead of firstName).
   • Use config('ultipro.endpoints') to override default paths if needed.

Debugging Tips

• Enable Guzzle Debugging

  $client->setDebug(true); // Logs raw HTTP requests/responses
  

• Check Response Headers

  $response = $client->get('/employees');
  $headers = $response->getHeaders(); // Inspect for errors/warnings
  

Extension Points

1. Custom Requests Override the default GuzzleHttp\Client:

   $client = new Ultipro(
       config('ultipro.client_id'),
       config('ultipro.client_secret'),
       new \GuzzleHttp\Client(['timeout' => 30])
   );
   

2. Middleware Add request/response middleware:

   $client->getClient()->getEmitter()->attach(
       \GuzzleHttp\Middleware::tap(function ($request) {
           // Modify request (e.g., add headers)
           $request = $request->withHeader('X-Custom-Header', 'value');
           return $request;
       })
   );
   

3. Mocking for Tests Use Mockery or GuzzleHttp\HandlerStack to mock API calls:

   $stack = HandlerStack::create();
   $stack->push(Middleware::mock(function ($request) {
       return new Response(200, [], json_encode(['data' => []]));
   }));
   
   $client = new Ultipro(..., new \GuzzleHttp\Client(['handler' => $stack]));