README

A framework-agnostic PHP client for the Podio API, built on PSR-18, bring your own HTTP client, everything else is wired for you.

In this example, we build a client and create an item, authentication is handled for you:

use Podio\Client\PodioClient;

$podio = PodioClient::factory()
    ->withClientCredentials($clientId, $clientSecret)
    ->withPasswordAuth($username, $password)
    ->make();

$item = $podio->items()->create($appId, [
    'fields' => ['title' => 'New lead'],
]);

Using Laravel? See podio-labs/podio-laravel.

Installation

Requires PHP 8.3+.

You can install the package via composer:

composer require podio-labs/podio-client

Ensure the php-http/discovery composer plugin is allowed to run, or install a PSR-18 client manually if your project does not already have one:

composer require guzzlehttp/guzzle

Usage

Creating a client

use Podio\Client\PodioClient;

$podio = PodioClient::factory()
    ->withClientCredentials($clientId, $clientSecret) // required
    ->withPasswordAuth($username, $password)          // required (see Authentication for more details)
    ->withBaseUrl('https://api.podio.com')            // optional
    ->withTokenUrl($tokenUrl)                         // optional
    ->withTokenCache($cache)                          // optional (PSR-16)
    ->withEventDispatcher($events)                    // optional (PSR-14)
    ->withHttpClient($client)                         // optional (PSR-18)
    ->make();

Authentication

A client always needs your Podio API credentials plus one authentication method, slotted into the builder above. The token manager fetches, caches and refreshes the token for you.

Method	Builder call	Use when
Password	`->withPasswordAuth($username, $password)`	service account, server-to-server
Authorization code	`->withAuthorizationCodeAuth($code, $redirectUri)`	per-user OAuth2, after the user authorises your app
App	`->withAppAuth($appId, $appToken)`	a single Podio app via its app token
Token	`->withToken($accessToken, $expiresAt, $refreshToken, $baseUrl)`	reuse a token you stored

Read (and persist) the current token:

$token = $podio->authenticate(); // ensure a valid token and return it
$token = $podio->token();        // current token

$token->accessToken();
$token->expiresAt();
$token->refreshToken();
$token->baseUrl();

A token stored with its own base URL sends its calls there instead of the withBaseUrl() of the factory.

Endpoints

// Items
$item = $podio->items()->get($itemId);
$item = $podio->items()->create($appId, ['fields' => ['title' => 'Hello']]);
$item = $podio->items()->update($itemId, ['fields' => ['title' => 'Updated']]);
$total = $podio->items()->getCount($appId);
$items = $podio->items()->lazy($appId, ['limit' => 500]);

// Files
$file = $podio->files()->upload($absolutePath, 'photo.jpg');
$podio->files()->attach($file->file_id, ['ref_type' => 'item', 'ref_id' => $itemId]);
$bytes = $podio->files()->getRaw($fileId);

// Comments
$podio->comments()->create('item', $itemId, ['value' => 'Imported from Dropbox']);

// Embeds
$embed = $podio->embed()->create(['url' => 'https://youtu.be/...']);

// Webhooks
$hooks = $podio->hooks()->getForApp($appId);
$hook = $podio->hooks()->createForApp($appId, ['url' => 'https://example.com/hook', 'type' => 'item.create']);
$podio->hooks()->verify($hook->hook_id);

// Organizations
$organizations = $podio->organizations()->getAll();
$organization = $podio->organizations()->get($orgId);

// Spaces
$space = $podio->spaces()->get($spaceId);

// Apps
$app = $podio->apps()->get($appId);
$apps = $podio->apps()->getForSpace($spaceId);

// Users
$user = $podio->users()->get();
$status = $podio->users()->getStatus();

Request options

$item = $podio->items()->withFields('items.fields(files)')->get($itemId);
$item = $podio->items()->withRetry(3)->get($itemId);
$item = $podio->items()->withTimeout(120)->get($itemId);

Option	What it does
`withFields($fields)`	sets Podio's `fields` parameter
`withRetry($times)`	retries a failed call
`withTimeout($seconds)`	sets the timeout of the call*

*withTimeout() needs an HTTP client that implements Podio\Client\Http\TimeoutClient.

Events

With an event dispatcher, the client dispatches Podio\Client\Events\TokenRefreshed whenever it obtains a token: on the first authentication and on every refresh. Listen to it to store the new token, refresh token included, as soon as Podio issues it:

$event->token->accessToken();
$event->token->refreshToken();
$event->token->expiresAt();

Raw requests

For anything not covered by an endpoint, send a request directly:

$response = $podio->send('GET', '/item/123', ['raw' => true]);

$response->statusCode();
$response->body();
$response->rateLimit();

Rate limit

$podio->rateLimit()->limit();
$podio->rateLimit()->remaining();

How it works

PodioClient wraps a transporter over your PSR-18 client (or one discovered via php-http/discovery) and a token manager that:

authenticates with the configured grant (password, authorization code, app, or a seeded token) and caches the access token when you pass a PSR-16 cache;
refreshes the token automatically: send() retries once on an expired-token response, using the refresh token when there is one, otherwise re-authenticating;
dispatches TokenRefreshed through the PSR-14 event dispatcher, when you pass one, every time it obtains a token.

Every endpoint (items(), files(), …) is a small typed wrapper over send().

Testing

composer test

To test code that uses the client without hitting Podio, inject a stub PSR-18 client:

$podio = PodioClient::factory()
    ->withClientCredentials('id', 'secret')
    ->withPasswordAuth('user', 'pass')
    ->withHttpClient($stubPsr18Client)
    ->make();

License

Podio Client is open-sourced software licensed under the MIT license.

podio-labs / podio-client

Package info

Security

Statistics