README

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.

Installation
Usage
- Using a Single Simpro Connection
- Using Multiple Simpro Connections
Available Requests
Useful Methods
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 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:

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 john@stitch-digital.co instead of using the issue tracker.

Credits

License

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

stitch-digital / laravel-simpro-api

Maintainers

Details