Dream Apply SDK
Dream Apply SDK is a client tool for the Dream Apply API
Requirements
PHP 5.5, 7.x or later.
This library uses Guzzle 6.2 and later and Stringy 2.0 and later. Please make sure that it won't conflict with your dependencies.
Initialization
<?php
$client = new \Dream\DreamApply\Client\Client('https://instance.dreamapply.com/api/', 'abcdefghijklmnopqrstuvwxyz123456');
Structure
The object hierarchy tries to stay as close to API uri structure as possible
<?php
$client->applicants[1]->documents[2]; // /applications/1/documents/2
$client->applications->offers->types; // /applications/offers/types
snake_case in fields and dash-case in urls correspond to the camelCase for objects and properties
<?php
$client->applications[1]->academicTerm; // 'academic_term' from /applications/1
$client->academicTerms; // /academic-terms
Work with collections
Collections work like properties of $client
or parent collections/records. Collections implement
array access and are traversable.
<?php
$client->applicants[1];
foreach ($client->applicants as $applicantId => $applicant) {
print "{$applicantId} email is {$applicant->email}";
}
$client->applicants->count(); // count items (sends HEAD request)
$client->applicants->exists(1); // existence check (sends HEAD request)
$client->applicants->toArray(); // convert to array
To use filter, get collection by method call. Please note that record obtaining and record existence check ignore current filter for the collection
<?php
// filters are required to iterate over applications
$applications = $client->applications(['byCommenceYear' => 2016, 'byStatuses' => 'Submitted']);
$inactive = $applications->filter(['byStatuses' => 'Inactive']); // add or override conditions in filter
$inactive->count(); // count filtered
$inactive->toArray(); // array of filtered items
Records and associations
<?php
// returned fields are properties
$client->applicants[1]->email;
$client->applicants[1]->name['given'];
// all links between records are automatically resolved
$client->applicants[1]->trackers[1]->assigned; // get field of tracker association
$client->applicants[1]->trackers[1]->tracker; // get actual tracker from association
// when iterating over collections, object properties are lazy loaded
// please note when calculating API request count
$applications = $client->applications(['byCommenceYear' => 2016, 'byStatuses' => 'Submitted']);
// one request
foreach ($applications as $id => $app) {
var_dump($app->revised); // 'revised' is returned in collection
}
// collection request + 1 request per object
foreach ($applications as $id => $app) {
var_dump($app->profile); // 'profile' is not returned in collection, we have to request it
}
Binary records
Some requests like applicant's photo and documents return files. Files are returned as Binary Records which behave just like normal records but contain predefined fields.
<?php
$photo = $client->applicants[1]->photo;
$photo->name; // file name
$photo->mime; // mime type
$photo->size; // file size
$photo->uploaded; // file uploaded timestamp
$photo->content; // file content, an instance of StreamInterface from PSR-7
$photo->expires; // expiration timestamp (is set for reports)
file_put_contents("/tmp/{$photo->name}", $photo->content);
Special actions
Creating (POST)
Flags, Trackers, and Applicants can be created in API
<?php
$newTracker = $client->applicants->trackers->create('tracker code', 'notes');
$newFlag = $client->applications->flags->create('flag name');
$newApplicant = $client->applicants->create([
'email' => 'email@example.com',
'name_given' => 'Name',
'name_family' => 'Surname',
]);
Adding association
Flag and Tracker associations can be created in API
<?php
$client->applicants[1]->trackers->add($newTracker); // add by associated object
$flagAssoc = $client->applications[1]->flags->add(123); // add by associated object id, get assoc instance
Deleting
Flags, Trackers, their associations, and Invoices can be deleted in API
<?php
$client->applications[1]->flags->delete(123); // delete by id
$client->applications[1]->flags->delete($flagAssoc); // delete by association object
$client->applications[1]->flags->delete($newFlag); // delete by associated record
Settable fields
API allows to set some fields like type for offer and task status
<?php
use Dream\DreamApply\Client\Models\Offer;
$client->applications[21]->tasks[4]->setStatus('This is an example status of a task.');
$client->applications[32]->offers[76]->setType(Offer::TYPE_ACCEPTED);
Other special cases
Simple arrays
Some requests return simple arrays, work with them as with plain php arrays
<?php
$client->applications->statuses;
$client->applications->offers->types;
$client->classificators;
$client->invoices->series;
Reports
Reports object has two methods:
<?php
// list all available reports
$client->reports->available();
// get report as binary record
$client->reports->report('ReportStatus', ['regions' => 1, 'academicTerm' => 1, 'institutions' => 1]);