PHP

Build PERSCOM integrations with the official PHP SDK.

PERSCOM offers an official PHP SDK to help developers integrate with the PERSCOM API. The SDK provides a fluent interface for all API operations.

View on GitHub

Explore the official PERSCOM PHP SDK repository.

Installation

Install the SDK using Composer:

composer require deschutesdesigngroupllc/perscom-php-sdk

Getting Started

The SDK follows the same naming conventions as the PERSCOM API. The examples below demonstrate common operations that apply to all available resources.

// The following are examples on the user resource, but the same principles
// can be applied to any PERSCOM resource. 
$perscom = new PerscomConnection('YOUR_API_KEY');

// Get a list of a specific resource
$response = $perscom->users()->all();

// Get a specific resource
$response = $perscom->users()->get(id: 1);

// Create a resource
$response = $perscom->users()->create(data: [
    'name' => 'User 1',
    'email' => '[e-mail]'
]);

// Update a resource
$response = $perscom->users()->update(id: 1, data: [
    'name' => 'User 1 New Name'
]);

// Delete a resource
$response = $perscom->users()->delete(id: 1);

// Search for a resource
$response = $perscom->users()->search(
    value: 'foobar', 
    sort: new SortObject('first_name', 'asc'), 
    filter: new FilterObject('created_at', '<', '2024-01-01')
);

// Batch create a resource
$response = $perscom->users()->batchCreate([
    new ResourceObject(data: [
        'name' => 'User 1',
        'email' => '[e-mail]'
    ]),
    new ResourceObject(data: [
        'name' => 'User 2',
        'email' => '[e-mail]'
    ])
]);

// Batch update a resource
$response = $perscom->users()->batchUpdate([
    new ResourceObject(id: 1, data: [
        'name' => 'User 1 New Name'
    ]),
    new ResourceObject(id: 2, data: [
        'name' => 'User 2 New Name'
    ])
]);

// Batch delete a resource
$response = $perscom->users()->batchDelete([
    new ResourceObject(id: 1),
    new ResourceObject(id: 2)
]);

// Uploading an attachment
$response = $perscom->users()->attachments(id: 1)->create(data: [
    'name' => 'Attachment 1',
    'file' => fopen('/../file.pdf', 'r')
]);

// Other examples
$response = $perscom->users()->profile_photo(id: 1)->create(filePath: 'image.jpg');
$response = $perscom->users()->assignment_records(id: 1)->delete();

// Parse the response into a usable array
$data = $response->json();

Error Handling

The PERSCOM SDK throws exceptions when an API error occurs. Catch these exceptions with a standard try/catch block. For a more elegant approach, consider using the promise-based approach.

try {
  $perscom = new PerscomConnection('YOUR_API_KEY');

  $response = $perscom->users()->all()->json();
} catch (AuthenticationException $exception) {
  Log::error('The provided API key is invalid');
}

Promise Support

The PERSCOM SDK supports asynchronous requests using a promise-based approach. This allows you to handle successful and failed requests more fluently.

// Create a PERSCOM instance
$perscom = new PerscomConnection('YOUR_API_KEY');

// Create a promise
$promise = $perscom->sendAsync(new GetAllUsersRequest());

// Send the request
$promise
    ->then(function (Response $response) {
        // Handle successful response
    })
    ->otherwise(function (RequestException $exception) {
        // Handle failed request
    });

// Resolve the promise
$promise->wait();