API reference

Client

Darvis\BullhornApi\Client. In Laravel: the Bullhorn facade, or app(Client::class).

Construct

Method	What it does
`new Client(Config $config, ?Transport $transport = null, ?TokenStore $store = null)`	Defaults: `CurlTransport` and `MemoryTokenStore`. Calls nothing.
`Client::fromEnv(?TokenStore $store = null)`	A client with `Config::fromEnv()`.
`config(): Config`	The settings of this client.

Any endpoint

The path is relative to the REST URL of the session, such as entity/Candidate/1. A full URL is refused. $query is added to the URL, booleans as true and false.

Method	Sends
`get(string $path, array $query = [])`	`GET`
`post(string $path, array $data = [], array $query = [])`	`POST` with `$data` as JSON. Updates an entity.
`put(string $path, array $data = [], array $query = [])`	`PUT` with `$data` as JSON. Creates an entity.
`delete(string $path, array $query = [])`	`DELETE`
`upload(string $method, string $path, string $filename, string $contents, string $mimeType = 'application/octet-stream', array $query = [])`	One file as `multipart/form-data`, in the field `file`.

Each returns the decoded JSON answer, null for an empty answer, or the raw body when it is not JSON.

Entities

Method	Sends
`entity(string $type, int\\|string\\|array $ids, string\\|array $fields = 'id', array $query = [])`	`GET entity/{type}/{ids}?fields=...`
`createEntity(string $type, array $data)`	`PUT entity/{type}`
`updateEntity(string $type, int\\|string $id, array $data)`	`POST entity/{type}/{id}`
`deleteEntity(string $type, int\\|string $id)`	`DELETE entity/{type}/{id}`
`search(string $type, string $lucene, string\\|array $fields = 'id', array $query = [])`	`GET search/{type}?query=...&fields=...`
`query(string $type, string $where, string\\|array $fields = 'id', array $query = [])`	`GET query/{type}?where=...&fields=...`
`meta(string $type, array $query = ['fields' => '*'])`	`GET meta/{type}`

$fields is a comma separated string or a list. Pass start and count in $query to page.

Session

Method	What it does
`ping(): array`	`GET ping`. Logs in when there is no session. `sessionExpires` is in milliseconds.
`isAlive(): bool`	Logs in when needed and pings. `true` when Bullhorn answers, `false` on any failure; never throws a `BullhornException`. Costs a login without a session: cache the answer.
`forgetSession(): void`	Drops the session here and in the store. The next call logs in.

Config

Darvis\BullhornApi\Config, immutable. Every default is a constant on the class.

Argument	`fromArray()` key	Default
`clientId`	`client_id`	empty
`clientSecret`	`client_secret`	empty
`username`	`username`	empty
`password`	`password`	empty
`loginInfoUrl`	`login_info_url`	`Config::LOGIN_INFO_URL`
`oauthUrl`	`oauth_url`	empty: from loginInfo
`restUrl`	`rest_url`	empty: from loginInfo
`apiVersion`	`api_version`	`*`
`sessionTtl`	`session_ttl`	`60` minutes
`timeout`	`timeout`	`30.0` seconds
`connectTimeout`	`connect_timeout`	`10.0` seconds

Config::fromArray(array $values) trims strings and falls back to the default for an empty or unusable value; a password is kept as it is. Config::fromEnv() reads BULLHORN_ plus the key in capitals. missing() lists the credentials that are empty.

Token stores

All implement Darvis\BullhornApi\Token\TokenStore.

Class	Keeps the session
`Darvis\BullhornApi\Token\MemoryTokenStore`	on the instance, for one process
`Darvis\BullhornApi\Token\FileTokenStore`	in a file per API user, in an absolute directory outside the web root
`Darvis\BullhornApi\Laravel\CacheTokenStore`	in Laravel’s cache, encrypted with `APP_KEY`, with a cache lock

Transports

All implement Darvis\BullhornApi\Http\Transport and return a Darvis\BullhornApi\Http\Response with status, body, headers and header($name).

Class	Sends with
`Darvis\BullhornApi\Http\CurlTransport`	PHP’s cURL extension
`Darvis\BullhornApi\Laravel\HttpTransport`	Laravel’s HTTP client, so `Http::fake()` works
`Darvis\BullhornApi\Testing\FakeTransport`	nothing: answers from a list, see Testing

Exceptions

Class	Thrown when
`Darvis\BullhornApi\Exceptions\BullhornException`	A call failed. `status()` is the HTTP status or `0`, `errorKey()` is Bullhorn’s `errorMessageKey`, `invalidFields()` the `propertyName`s from its `errors`.
`Darvis\BullhornApi\Exceptions\AuthenticationException`	The login failed with a 4xx, or the config is incomplete. Extends `BullhornException`.

Laravel

What	Name
Facade	`Darvis\BullhornApi\Laravel\Facades\Bullhorn`, alias `Bullhorn`
Container	`Client` (alias `bullhorn`), `Transport` and `TokenStore`, all singletons
Config	`config/bullhorn.php`, publish tag `bullhorn-config`
Command	`php artisan bullhorn:test`, `--fresh` to log in again