README

Lightweight PHP client for the Propstack API v1.

Requirements

PHP: >= 7.2 (PHP 8 supported)
Extensions: PHP-JSON, cURL
Dependencies: Guzzle 6.3, 7 or 8 (installed via Composer)

Install

composer:
composer require pdir/propstack-api

Usage

Search for the official API Documentation here.
You need an API key - ask support or visit the account settings in Propstack.

Authentication

The API key is taken from the apiKey credential or, if not given, from the environment variable PROPSTACK_API_KEY. It is sent as X-API-KEY header, so it does not show up in URLs, server logs or proxies.

// key from environment variable PROPSTACK_API_KEY
$api = new Pdir\Propstack\Api();

// or pass the key explicitly
$api = new Pdir\Propstack\Api([
    'apiKey' => 'PROPSTACK_API_KEY',
]);

If no key is configured, every request throws a PropstackApiException.

Basic

// get all projects
$projects = $api->getProjects();

// get one page of saved queries (Suchprofile)
$savedQueries = $api->getSavedQueries(['page' => 1, 'per' => 100]);

// get all saved queries (walks through all pages)
$allSavedQueries = $api->getAllSavedQueries();
// $allSavedQueries['data']               => all saved queries
// $allSavedQueries['meta']['total_count'] => number of loaded saved queries

// optional: filter and page size (default 100, Propstack recommends max. 500)
$allSavedQueries = $api->getAllSavedQueries(['client' => 42], 500);

// get a single contact
$contact = $api->getContact(123);

// get a single contact with related data
$contact = $api->getContact(123, ['include' => 'children,documents,relationships,owned_properties']);

All getters accept an optional array of query parameters that is passed to the Propstack API.

Methods

Getters return the decoded JSON as array, or null if the API answers with a status code other than 200.

Error handling

Failed requests (network errors, 4xx/5xx responses, invalid JSON) throw a Pdir\Propstack\Exceptions\PropstackApiException. The original Guzzle exception is available via getPrevious().

use Pdir\Propstack\Exceptions\PropstackApiException;

try {
    $contact = $api->getContact(123);
} catch (PropstackApiException $e) {
    // e.g. log $e->getMessage(), $e->getCode()
}

Custom HTTP client

You can inject your own Guzzle client, e.g. for different timeouts, proxies, middleware or tests. The default client uses a timeout of 30 seconds.

$client = new GuzzleHttp\Client([
    'timeout' => 60,
    'headers' => ['Accept' => 'application/json'],
]);

$api = new Pdir\Propstack\Api(['apiKey' => 'PROPSTACK_API_KEY'], $client);

Upgrade from 0.1.0

• The API key is now sent as X-API-KEY header instead of the api_key query parameter.
• getContacts() is deprecated, use getContact() instead.
• A missing API key now throws a PropstackApiException instead of sending unauthenticated requests.

Changelog

See CHANGELOG.md.

License

MIT, see LICENSE.