stitch-digital / laravel-simpro-api
Laravel package for working with the Simpro API
Fund package maintenance!
Stitch Digital Limited
Requires
- php: ^8.2
- illuminate/contracts: ^10.0||^11.0
- saloonphp/cache-plugin: ^3.0
- saloonphp/pagination-plugin: ^2.0
- saloonphp/rate-limit-plugin: ^2.0
- saloonphp/saloon: ^3.0
- spatie/laravel-package-tools: ^1.16
Requires (Dev)
- larastan/larastan: ^2.9
- laravel/pint: ^1.14
- nunomaduro/collision: ^8.1.1||^7.10.0
- orchestra/testbench: ^9.0.0||^8.22.0
- pestphp/pest: ^2.35
- pestphp/pest-plugin-arch: ^2.7
- pestphp/pest-plugin-laravel: ^2.3
- phpstan/extension-installer: ^1.3
- phpstan/phpstan-deprecation-rules: ^1.1
- phpstan/phpstan-phpunit: ^1.3
This package is auto-updated.
Last update: 2024-11-05 11:19:11 UTC
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.
Table of Contents
- Installation
- Usage
- 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();
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
- John Trickett
- Anthony Elleray
- Sam Carré - The Creator of Saloon
- All Contributors
License
The MIT License (MIT). Please see License File for more information.