Quick start guide PHP

This guide will show you how to use our API and get the minimal data to make requests to our API. This guide assumes you’re already authenticated and have a valid access token. A guide on authentication and retrieving tokens can be found here.

Generating a PHP client

More information on creating a PHP client can be found here. Important! After creating a PHP client read the included readme.md file, it holds information about fetching all dependencies via Composer (http://getcomposer.org).

Setting default configuration

All requests start with setting the default configuration for Swagger:

$access_token = 'your_retreived_access_token';
$swagger = \Swagger\Client\Configuration::getDefaultConfiguration();
$swagger->setAccessToken($access_token);

You should make the swagger variable globally available.

Fetching minimal data

Almost every request we make requires a valid realEstateAgencyId, so one of the first calls we’ll be making is retrieving the accountSettings. This call also requires a valid personId which is available when JWT decoding your access token. The decoded token should have a property called pid, use this as your personId (a.k.a. employeeId).

Example: account settings request
$account_settings_client = new \Swagger\Client\Api\AccountSettingsApi(
  new GuzzleHttp\Client(),
  $swagger
);

try {
  $request = new \Swagger\Client\Model\AccountSettingsReadByPersonIdRequest();
  $request->setPersonId('your_retrieved_person_id');
  $result = $client->accountSettingsReadByEmployeeId($request);
} catch (Exception $e) {
  echo $e->getMessage(), PHP_EOL;
}

The result variable should hold an valid accountSettings object, see the swagger documentation for all available properties. Now we should have all minimal data required to make valid request, let’s try creating a Task, changing some properties and then saving it.

Creating your first entity

Just as we mentioned in the previous step we’ll be creating a Task entity, when creating a new entity always check if the request has required fields, in case of our Task it has a required employeeId.

Example: define new task request
$client = new \Swagger\Client\Api\TasksApi(
  new GuzzleHttp\Client(),
  $swagger
);

try {
  $request = new \Swagger\Client\Model\TasksDefineNewRequest();
  $request->setEmployeeId('your_retrieved_person_id');
  $result = $client->tasksDefineNew($request, $realestate_agency_id);
} catch (Exception $e) {
  echo $e->getMessage(), PHP_EOL;
}

This should create an empty task with some default properties for you that is not persisted to the database yet.

Updating a entity

Using the result fetched above we can retrieve the actual task and make changes to it.

Example: get task and update properties
$task = $result->getTask();
$task->setSubject('My first task');
$task->setDescription('This is great! My first task ever created with the Kolibri API.');

Okay we made changes to our local copy of the Task, let’s persist them.

Example: save updated task and output result
$task_save_request = new \Swagger\Client\Model\TasksSaveRequest();
$task_save_request->setTask($task);
$result = $client->tasksSave($request, $realestate_agency_id);

echo '<pre>';
var_dump($result->getTask());
echo '</pre>';

Using array instead of arrow notation

Above examples all show setting and updating properties via getters and setters. It is however possible to use array notation for this. For example let’s change the define new request of the task to use array notation.

Example: Array notation
try {
  /**
   * Previous arrow notation  
   * $request = new \Swagger\Client\Model\TasksDefineNewRequest();
   * $request->setEmployeeId('your_retrieved_person_id');
   */

  $request = new \Swagger\Client\Model\TasksDefineNewRequest(
    array(
      'employee_id' => 'your_retrieved_person_id'
    )
  );
  $result = $client->tasksDefineNew($request, $realestate_agency_id);
} catch (Exception $e) {
  echo $e->getMessage(), PHP_EOL;
}

One thing to notice here is that when using setters the method names are always in camelcase while the array notation are all in snakecase, this is also true when reading a response and accessing the props directly vs using the getter.