This library serves as a convenient wrapper around Pipeliner’s REST API. You can also view the API documentation for the individual classes or sources in our GitHub repository.
The recommended way to install this library is via composer. Add “pipelinersales/pipeliner-api-client”: “~1.0” to your dependencies in composer.json.
An alternative way is to manually download the sources and include the manual/pipeliner.php file. This will use a bundled autoloader to load all the library’s classes.
The library requires PHP >= 5.3 with the cURL extension.
PHP SDK on Github
The Pipeliner SDK for PHP is an open source project hosted on Github. You can get the latest version of the SDK or contribute to it via Github:
Creating the client object
The API client object is created like this:
The API token and password for a particular pipeline can be found in the Sales Pipeline → API Access section of customer portal.
The create method sends a HTTP request in order to obtain the pipeline version.
For queries with no explicitly specified limit, up to 25 items will be returned.
The method returns an object. See the Working with entities section to read about how to work with these objects. The method returns an object, which can be accessed like a regular PHP array.
The library throws a or one of its subclasses on errors. For more information, see the Error handling section of this document.
Types of data in the system
The types of entities that the system consists of depend on the version of the pipeline that’s being worked with. Versions 9 to 15 are supported by the current version of the library. The version of the pipeline can be obtained by calling $pipeliner->getPipelineVersion().
A full list of entities can also be obtained in code, by calling the $pipeliner->getEntityTypes().
In code, entities are obtained by using repositories available as properties of the client object. Name of such a property is usually the plural of the entity name in camel case, so entities of type Account can be accessed via $pipeliner->accounts, etc. You can also obtain the repository with the getRepository method.
The criteria for which items should be retrieved consist of properties described in the server API docs Building the query strings manually is a hassle. The library offers several convenience classes to make it easier and your code more readable. These are available in the namespace.
You can specify the query criteria in one of several ways. Full list is available in the get method documentation.
Working with entities
- Using the field name directly, with the and methods. Please note that all standard fields have names in upper case, while custom fields can contain lower case letters and other characters.
- Using the magic getters/setters. These map the method name onto field name by converting the camel case part into upper case and adding underscores where necessary.
- Using the array access operators, e.g. $entity[‘OWNER_ID’] = 3454;
The magic getters/setters are generally the preferred way of accessing fields. Custom fields should be set with the getField/setField methods.
In addition to strings and numbers, all of these methods will automatically convert DateTime objects into a format expected by the server. The date/time will also be converted to UTC if it isn’t already.
Modifying and saving data
By default, only fields which have been modified in the code will be sent to the server. This behavior can be changed with the second argument of the method. After a successful save, all fields will be reset to not modified.
If you have an entity object that you don’t know the type of, you can obtain the proper repository by calling $pipeliner->getRepository($entity).
Creating new entities
After a successful save, the ID field of the entity object will be set to the new entity’s ID. You can also create entities by simply providing an associative array with all the fields and values.
When loading multiple entities at once using the get method, its return value will be a EntityCollection object. For most purposes, it works like a regular PHP array (it extends PHP’s ArrayObject class), but compared to arrays, it contains some extra information about the query.
One important difference is that EntityCollection objects are immutable (even though the elements inside them are themselves mutable).
If you need a mutable array, you can obtain a copy of the collection’s underlying array with the getArrayCopy method.
Full range iterators
When loading multiple entities, Pipeliner’s REST API allows you to limit the retrieved data to only parts of the results by specifying the limit and offset query parameters.
This class implements the interface, which allows you to arbitrarily move through the result set. Data will be fetched from the server as needed. Currently loaded data is thrown away when new data is loaded, so it is a good idea to use this class in a way that minimizes the number of issued HTTP requests.
In case of an error response from the server, a is thrown. If the response contained error information from the server, it can be read using the and methods. This information will also be part of the standard exception message.