Basics

Autoloading

The easiest way to install the Justimmo PHP-SDK and autoload the classes in you php application is using Composer. The PHP-SDK follows the PSR-0 standards for autoloading.

The API class

The API class handles the communication between the Justimmo API and the PHP-SDK. It has to be injected in every query. Mandatory Requirements for the API class when instancing it is a username and a password for the Justimmo API, a LoggerInterface and a CacheInterface. Optional Attributes are the version (default v1) and the culture (default de). The culture defines the default language in which the API returns values. You can override this per call if needed.

<?php

use Justimmo\Api\JustimmoApi;
use Justimmo\Model\RealtyQuery;

$api = new JustimmoApi('username', 'password');
//.....
$api->setCulture('en');
//.....

Exceptions

The PHP-SDK throws a variety of exceptions you can catch and handle into appropiate messages.

Abstraction

The concept of this PHP-SDK is to abstract the Justimmo API to a point that you just have to change the mapper and wrapper of a query to use a different version of the API. To achieve this the API uses dependency injection. If you don’t want to build you dependencies by hand when using the API, you can use a dependency injection container. An example configuration for the Symfony 2 dependency injection container can be found here.

Queries

Queries are a object oriented way you can use to fetch data from the API. You can find a full list of possibilities in the query documentation.

<?php
//...

$query = new RealtyQuery($api, $wrapper, $mapper);
$realties = $query->filterByPrice(array('min' => 500, 'max' => 1500))
    ->filterByZipCode(1020)
    ->orderByPrice('desc')
    ->find();

Model

Model classes are abstracted representations of a singular data set (example Realty, Employee,…) Instances of model classes are created by wrappers which handle the translation of the output format of a API call (xml, json) into an abstracted model object. By default queries return model instances while API calls return the plain output format as string. Depending on the dataset they come with a variety of different getters. You can find a full list of all properties in the model classes.

<?php
//...

$realty = $query->findPk(12345);
echo $realty->getPurchasePrice();
echo $realty->getTitle();
//...

//information about the contact person of that realty
echo $realty->getContact()->getFirstName();
echo $realty->getContact()->getEmail());

//...

//attachments getPictures() getVideos() getDocuments()
foreach($realty->getPictures() as $picture) {
    echo $picture->getUrl('orig');
}
//abstracted attachments
foreach($realty->getAttachmentsByType('bilder360') as $picture) {
    echo $picture->getUrl('orig');
}

Pagination

Queries return by default a ListPager instance, which is an extension of a PHP array object and only holds a subset of all data and additional methods to build a pager.

<?php
//iterating trough the subset of data
foreach($pager as $realty) {
    //...
}

$pager->haveToPaginate(); //if the pager contains all data of if we have to paginate
$pager->getPage(); //the current page of the pager
$pager->getFirstPage(); //the first page of the pager
$pager->getMaxPerPage(); //how many entries are shown on a page
$pager->getLastPage(); //the last page of the pager
$pager->getNbResults(); //number of all found results not only the number contained on the current page
$pager->getLinks(5);  //gets the numbers of the adjacent pages of the current page if available
$pager->toKeyValue('getId', 'getTitle'); //returns a php array as key/value pair with the passed keyMethodGetter and valueMethodGetter

Errors

The SDK will throw different exceptions on API failures. All SDK related exceptions implement the Justimmo\Exception\JustimmoException to let you catch all SDK exceptions thrown by the SDK.

<?php

try {
    //...
    $query->find();
    //...
} catch (\Justimmo\Exception\InvalidRequestException $e) {
    //bad request format oder filter parameter, example output "zimmer_von ["test" is not a number.]"
    echo $e->getMessage();
} catch (\Justimmo\Exception\JustimmoException $e) {
    //other sdk exception
} catch (\Exception $e) {
    //exception not thrown by SDK if JustimmoException is previously catched
}

Available Exceptions