AuthRocket for PHP

This document covers broad usage of the authrocket PHP library. If you’re just getting started, you may want to read the Quickstart or PHP Integration Guide first.

If you’ve already been through the Quickstart and have AuthRocket working in your app, you may want to jump down to the General Usage section.

The authrocket PHP library covers all of our Core API. It also covers select portions of the Extended API. If something you need isn’t present, let us know.

Installation

The library is designed to be installed using composer. It should also be usable using any other method typically supported by composer-compatible packages.

For installation, run php composer.phar require authrocket/authrocket=^1.

Alternatively, add "authrocket/authrocket": "^1" to the require section of your composer.json and run php composer.phar install.

Client Basics

Using environment variables

If you are using environment variables to manage external services like AuthRocket, then it’s very easy to initialize the AuthRocket client:

$client = \AuthRocket\AuthRocket::autoConfigure();

Ensure these environment variables are set:

AUTHROCKET_API_KEY    = ko_SAMPLE
AUTHROCKET_URL        = https://api-e1.authrocket.com/v1
AUTHROCKET_REALM      = rl_SAMPLE   # optional
AUTHROCKET_JWT_SECRET = jsk_SAMPLE  # optional

AUTHROCKET_URL must be updated based on what cluster your account is provisioned on.

AUTHROCKET_REALM and AUTHROCKET_JWT_SECRET are optional. If you are using multiple realms, we recommend building a new client for each realm, just setting realm and jwtSecret:

$client = \AuthRocket\AuthRocket::autoConfigure([
  'realm'     => 'rl_SAMPLE',
  'jwtSecret' => 'jsk_SAMPLE'
]);

Direct configuration

It’s also possible to configure the AuthRocket client instance directly:

$client = new \AuthRocket\AuthRocket([
  'apiKey'    => 'ko_SAMPLE',
  'url'       => 'https://api-e1.authrocket.com/v1',
  'realm'     => 'rl_SAMPLE',
  'jwtSecret' => 'jsk_SAMPLE'
]);

General Usage

Retrieving all records

$users = $client->users()->all();
var_dump($users->results);
// returns: an array of user records

AuthRocket doesn’t use pages of results, as these can change quickly as records are added and deleted. Instead, bulk requests include metadata about if there are more records remaining.

$more = $users.hasMore();
// returns: true || false

To query for more, simply pass the same request with an after parameter containing the ID of the last user seen.

$users = $client->users()->all([
  'after' => $last_user_id
]);

Retrieving the first record

$user = $client->users()->first();
// if no users found, returns null

This is effectively the same as calling $client->users()->all(['max_results'=> 1]) (and supports the same parameters).

Retrieving a single record

Retrieve a single record by its ID. Some resources (such as User) also support an alternate, unique ID; in this case, you may use the two interchangeably.

Note that while our PHP library uses camelCase for method names, the API itself uses snake_case. This means that attribute and parameter names must use snake_case.

$user = $client->users()->find('usr_0v1zUpWdE4IiFc2w5ynShf');

By default, the API response returned inside the fields attribute. There is also a shortcut for first level attributes. These are both the same:

$firstName = $client->users()->fields['first_name'];
$firstName = $client->users()->first_name;

Second level attributes, such as custom attributes, must still be accessed as an array:

$customField = $client->users()->fields['custom']['phone'];
$customField = $client->users()->custom['phone'];

Many resources return more fields when queried as a single record (using find()) than they do when queried in bulk (using all()).

Creating records

$user = $client->users()->create([
  'invalid'=>'data'
]);
echo($user->hasErrors());
// returns: true

var_dump($user->errors);
// returns: array of error messages

echo($user->errorMessages());
// returns: one string with all error messages joined together

$org = $client->orgs()->create([
  'name' => 'Group Foo'
]);
echo($org->hasErrors());
// returns: false
var_dump($org->fields);

Updating records

$user = $client->users()->update('usr_0v1zUpWdE4IiFc2w5ynShf', [
  'first_name' => 'Stig',
  'last_name' => null
]);

Only changed attributes need to be sent.

Deleting records

$client->users->delete('usr_0v1zUpWdE4IiFc2w5ynShf');

Other methods

Some resources have other resource-specific methods that are outlined in the API docs.

Not all resources support all methods. Again, see the API docs.

What’s next

From here we recommend the following:

• Quickstart - if you haven’t worked through it already
• API methods - be sure to toggle the examples over to PHP