Laravel package for working with the Simpro API

Laravel Simpro is a robust package designed to seamlessly integrate your Laravel application with the Simpro API.

The full Simpro API documentation can be found here.

Table of Contents

• Installation
• Usage
  • Using a Single Simpro Connection
  • Using Multiple Simpro Connections
• Available Requests
• Useful Methods
  • Responses
  • Pagination
  • Rate Limiting
  • Caching
  • Retries
  • Query Parameters
• Changelog
• Contributing
• Security
• Credits
• License

Installation

Laravel Simpro API can be installed using composer:

composer require stitch-digital/laravel-simpro-api

Then publish the config file:

php artisan vendor:publish --tag="simpro-api-config"

This will publish the configuration file to config/simpro-api.php where you can configure your settings.

This package is built using Saloon. Check out their documentation here.

Usage

Using a Single Simpro Connection

If you are using a single Simpro connection, you can add the following environment variables to your .env file:

SIMPRO_BASE_URL=https://your-build-url.simprosuite.com
SIMPRO_API_KEY=your-api-key

To use the package, you can use the Simpro facade to make requests to the API:

use StitchDigital\LaravelSimproApi\Facades\Simpro;
use StitchDigital\LaravelSimproApi\Requests\Info\GetInfo;

$response = Simpro::send(new GetInfo())->json();

If you prefer to use dependency injection over facades then you can do this too:

use StitchDigital\LaravelSimproApi\LaravelSimproApi;
use StitchDigital\LaravelSimproApi\Requests\Info\GetInfo;

$connector = new LaravelSimproApi();
$request = new GetInfo();

$response = $connector->send($request)->json();

Using Multiple Simpro Connections

If you are using multiple Simpro connections, you can pass the base URL and API key to the constructor of the connector:

use StitchDigital\LaravelSimproApi\LaravelSimproApi;
use StitchDigital\LaravelSimproApi\Requests\Info\GetInfo;

$connector = new LaravelSimproApi(
    baseUrl: 'https://custom-api-url.simprosuite.com',
    apiKey: 'custom-api-key'
);

$response = $connector->send(new GetInfo());

$response->json();

Available Requests

For a full list of available requests, use the following command:

php artisan simpro:list-requests

Useful Methods

Responses

After sending a request to the Simpro API, a Response class is returned. In most of the examples, we show the json method that returns a JSON response body. Below are some of the key methods provided by Saloon's Response class:

Method	Description
status	Returns the response status code.
headers	Returns all response headers
header	Returns a given header
body	Returns the raw response body as a string
json	Retrieves a JSON response body and json_decodes it into an array.
array	Alias of json
collect	Retrieves a JSON response body and json_decodes it into a Laravel Collection. Requires illuminate/collections.
object	Retrieves a JSON response body and json_decodes it into an object.
xmlReader	Used for XML responses - returns a XML Wrangler reader. Requires saloonphp/xml-wrangler.
dom	Used for HTML responses - returns a Symfony DOM Crawler instance. Requires symfony/dom-crawler.
stream	Returns the response body as an instance of StreamInterface
saveBodyToFile	Allows you to save the raw body to a file or open file resource.
dto	Converts the response into a data-transfer object.
dtoOrFail	Will work just like dto but will throw an exception if the response is considered "failed".
ok, successful, redirect, failed, clientError, serverError	Methods used to determine if a request was successful or not based on status code. The failed method can be customised.
throw	Will throw an exception if the response is considered "failed".
getPendingRequest	Returns the PendingRequest class that was built up for the request.
getPsrRequest	Returns the PSR-7 request that was built up by Saloon
getPsrResponse	Return the PSR-7 response that was built up by the HTTP client/sender.

Pagination

This package uses the Saloon Paged Paginator for all GET requests that return multiple results.

There are various ways to use the paginator, all well documented in the Saloon docs - here is an example:

Let's say we want to retrieve all customers from Simpro. We can use the 'GetCustomers' request:

use StitchDigital\LaravelSimproApi\Facades\Simpro;
use StitchDigital\LaravelSimproApi\Requests\Customers\GetCustomers;

$companyId = 0;
$response = Simpro::send(new GetCustomers($companyId))->json();

However, Simpro will paginate responses by default to a page size of 30 results. We can see this if we return the headers for the same request:

use StitchDigital\LaravelSimproApi\Facades\Simpro;
use StitchDigital\LaravelSimproApi\Requests\Customers\GetCustomers;

$companyId = 0;
$response = Simpro::send(new GetCustomers($companyId))->headers();

This will return pagination data in the headers:

[
    "Result-Total" => "816",
    "Result-Pages" => "28",
    "Result-Count" => "30",
]

The easiest way to use the paginator is to collect all responses like this:

use StitchDigital\LaravelSimproApi\Facades\Simpro;
use StitchDigital\LaravelSimproApi\Requests\Customers\GetCustomers;

$companyId = 0;
$response = Simpro::paginate(new GetCustomers($companyId))
  ->collect()
  ->all();

When using the paginator, you can override the Simpro default per page limit of 30 by chaining the setPerPageLimit method to the request:

use StitchDigital\LaravelSimproApi\Facades\Simpro;
use StitchDigital\LaravelSimproApi\Requests\Customers\GetCustomers;

$companyId = 0;
$response = Simpro::paginate(new GetCustomers($companyId))
  ->setPerPageLimit(250) // increase the per page limit to 250
  ->collect()
  ->all();

The maximum per page limit is 250.

Warning

Take care when increasing the per page limit. If you are dealing with large datasets and performing complex operations, you may want to keep this at the default to avoid memory issues.

Rate Limiting

This package uses the Saloon Rate Limiter Plugin to rate limit requests to the Simpro API.

You can disable rate limited globally in the config file, as well as set the rate limit, threshold and driver:

    /*
    |--------------------------------------------------------------------------
    | Rate Limit Configuration
    |--------------------------------------------------------------------------
    |
    | Set the rate limit for Simpro requests. The rate limit is set per second
    | and the threshold is the percentage of the rate limit that is accepted.
    | The threshold must be a number between 0 and 1 (e.g. 0.5 for 50%).
    |
    | The default rate limit is as per the Simpro API documentation.
    |
    */

    'rate_limit' => [
        'enabled' => true,
        'per_second' => 10,
        'driver' => 'database',
        'threshold' => 0.8,
    ],

You can also disable rate limiting on a per-request basis by chaining the useRateLimitPlugin(false) method to the request:

use StitchDigital\LaravelSimproApi\Facades\Simpro;
use StitchDigital\LaravelSimproApi\Requests\Info\GetInfo;

$response = Simpro::useRateLimitPlugin(false)
  ->send(new GetInfo())
  ->json();

Caching

This package uses the Saloon Caching Plugin to cache GET requests to the Simpro API.

You can disable caching globally in the config file, as well as set the cache driver and expiry time:

    /*
    |--------------------------------------------------------------------------
    | Cache Configuration
    |--------------------------------------------------------------------------
    |
    | Enable or disable caching for Simpro GET requests. The cache driver can
    | be set to any of the Laravel cache drivers. The cache expiry time is
    | set in seconds.
    |
    */

    'cache' => [
        'enabled' => true,
        'driver' => 'database',
        'expire' => 120,
    ],

Retries

You can control the global retry configuration in the config file:

    /*
    |--------------------------------------------------------------------------
    | Global Retry Configuration
    |--------------------------------------------------------------------------
    |
    | Set the number of retries for all requests. This can still be overridden
    | on a per-request basis, by chaining sendAndRetry() to the request:
    |
    | Example:
    | $response = $connector->sendAndRetry($request, 1);
    |
    */

    'global_retries' => 3, // Set to null to disable global retries

Query Parameters

You can add query parameters to your requests by chaining the query method to the request:

use StitchDigital\LaravelSimproApi\Facades\Simpro;
use StitchDigital\LaravelSimproApi\Requests\Jobs\GetJobs;

$companyId = 0;
$siteId = 123;

$request = new GetJobs($companyId);
$request->query()->add('Site.ID', $siteId);

// Returns all jobs for Site ID 123
$response = Simpro::send($request)->json();

Changelog

Please see CHANGELOG for more information what has changed recently.

Contributing

Contributions are welcome and will be fully credited! Contributions are accepted via Pull Requests on GitHub.

Security

If you discover any security related issues, please email [email protected] instead of using the issue tracker.

Credits

• John Trickett
• Anthony Elleray
• Sam Carré - The Creator of Saloon
• All Contributors

License

The MIT License (MIT). Please see License File for more information.