> ## Documentation Index
> Fetch the complete documentation index at: https://docs.perscom.io/llms.txt
> Use this file to discover all available pages before exploring further.

# 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.

<Card title="View on GitHub" icon="github" href="https://github.com/deschutesdesigngroupllc/perscom-php-sdk">
  Explore the official PERSCOM PHP SDK repository.
</Card>

## Installation

Install the SDK using Composer:

```bash theme={"system"}
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.

```php theme={"system"}
// 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' => 'user1@email.com'
]);

// 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' => 'user1@email.com'
    ]),
    new ResourceObject(data: [
        'name' => 'User 2',
        'email' => 'user2@email.com'
    ])
]);

// 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](#promise-support) approach.

```php theme={"system"}
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.

```php theme={"system"}
// 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();
```