- How do I install the Ultipro SDK in a Laravel project?
- Run `composer require brianfreytag/ultipro-sdk-php` in your Laravel project directory. The package is fully Composer-compatible and will resolve all dependencies automatically. Ensure your Laravel version (10+) aligns with Symfony 8, as the SDK leverages modern Symfony components.
- Does this SDK support Laravel 9 or older versions?
- The SDK is optimized for Laravel 10+ due to Symfony 8 alignment. For Laravel 9 (Symfony 6), you may need to manually resolve dependency conflicts or use a separate branch if provided. Test thoroughly, as Symfony 8’s PSR-18 compliance could introduce breaking changes.
- Can I authenticate with Ultipro using an array or object?
- Yes, the SDK supports both methods. Use `new Authentication($username, $password, $customerApiKey)` for an object or pass an associative array with keys `username`, `password`, and `customer_api_key` to the `UltiproClient` constructor. Both approaches work identically.
- What Ultipro API endpoints does this SDK cover?
- The SDK includes dedicated clients for organization levels (`/configuration/v1/org-levels`), personnel details (`/personnel/v1/person-details`), employment details (`/personnel/v1/employment-details`), and employee ID lookups (`/personnel/v1/employee-ids`). Additional endpoints can be accessed via the base `UltiproClient`.
- How do I customize the base URI or Guzzle options?
- Pass the `$baseUri` (e.g., `https://service5.ultipro.com`) and `$options` (Guzzle request options) as the second and third arguments to the `UltiproClient` constructor. This overrides defaults like timeout, headers, or SSL verification. Example: `$client = new UltiproClient($auth, 'custom-uri', ['timeout' => 30]).`
- Will this SDK work with Ultipro’s OAuth2 authentication?
- Yes, the SDK handles OAuth2 via the `Authentication` object or array. Under the hood, it uses Guzzle for HTTP requests, which supports OAuth2 tokens. For Laravel 10+, ensure your app’s HTTP client (e.g., `Http::withToken()`) aligns with Symfony 8’s PSR-18 standards if custom middleware is used.
- Are there performance concerns when using this SDK in production?
- The SDK is lightweight and leverages Guzzle for efficient HTTP requests. However, Symfony 8’s HTTP Client (used internally) may introduce minor overhead. Benchmark your Laravel 10+ environment against older versions to confirm stability. Ultipro’s API response times are the primary bottleneck, not the SDK itself.
- How do I handle errors or rate limits from Ultipro’s API?
- The SDK throws exceptions for HTTP errors (e.g., 4xx/5xx) and rate limits. Wrap API calls in a `try-catch` block to handle these gracefully. For rate limits, implement exponential backoff in your Laravel logic or use Guzzle’s middleware to retry failed requests automatically.
- Can I mock the UltiproClient for testing in Laravel?
- Yes, the SDK’s design allows mocking the `UltiproClient` or its specialized clients (e.g., `PersonnelClient`). Use PHPUnit’s mocking capabilities to stub HTTP responses. For Symfony 8’s HTTP Client, create mocks for its `HttpClientInterface` if needed, or use Guzzle’s mocking features for backward compatibility.
- What alternatives exist if this SDK doesn’t meet my needs?
- If the SDK lacks specific Ultipro endpoints, consider building a custom Laravel service using Guzzle directly or Symfony’s HTTP Client. For broader HRIS integrations, evaluate official APIs like UKG’s REST API docs or third-party packages like `spatie/laravel-hris`. However, this SDK remains the most feature-complete unofficial option for Ultipro.