Download the PHP package stitch-digital/uptick-php-sdk without Composer

Uptick PHP SDK

This package is an unofficial PHP SDK for the Uptick API, built with Saloon v3.

⚠️ Active Development Notice

This package is under active development. The API, features, and internal structure may change at any time.

A stable, production-ready release has not yet been tagged. Until a v1.0.0 (or similar) release is published, this SDK should be considered experimental and used with caution in production environments.

About Uptick

Uptick is a cloud-based field service and compliance platform designed specifically for fire protection, security, HVAC and related maintenance businesses, helping them manage inspections, scheduling, asset maintenance and reporting in one place. It replaces paper and manual processes with a mobile-friendly system that lets technicians capture data, photos and defect details on site while office teams handle job scheduling, quoting, invoicing and customer communication more efficiently, all backed by built-in standards and integrations with tools like accounting software.

• Website: https://www.uptickhq.com/
• GitHub: https://github.com/uptick

Installation

Quick Start

Behind the scenes, the SDK uses Saloon to make the HTTP requests.

Usage

Authentication

The SDK handles OAuth2 authentication automatically. You provide your credentials when creating the SDK instance:

The SDK will automatically:

• Obtain an access token using the password grant
• Refresh the token when it expires
• Include the token in all API requests

Setting a timeout

By default, the SDK waits 10 seconds for a response. Override via the constructor:

Handling errors

The SDK uses Saloon's AlwaysThrowOnErrors trait on the connector, which means exceptions will automatically be thrown whenever a request fails (4xx or 5xx response status codes). You don't need to manually check if a request failed or call throw() on responses - exceptions are thrown automatically.

Saloon's built-in exceptions are used for most errors, with a custom exception for validation errors (422 status codes).

Exception Hierarchy

The SDK uses Saloon's exception hierarchy:

Validation Errors

For validation errors (422 status code), the SDK throws a custom ValidationException which extends Saloon's UnprocessableEntityException. This exception provides additional methods to access validation error details:

Connection Errors

If Saloon cannot connect to the API, it will throw a FatalRequestException:

Resources

The SDK provides resource-based APIs for working with different entities. Each resource is accessed through a method on the main SDK instance.

Client Resource

The client resource provides methods for working with clients. Access it through the clients() method:

Methods that return lists of clients (like list(), findById(), etc.) return a UptickPaginator instance. See the Pagination section for details on working with paginated results. Future methods like create(), update(), and delete() will return different response types.

Listing Clients

The following methods return a UptickPaginator instance:

List all clients:

List active clients:

List inactive clients:

Finding Clients

Find by ID:

Find by name:

Search clients:

Filtering Clients

The client resource provides many filtering methods. All filtering methods return a UptickPaginator instance. You can chain multiple filters together, or pass filters directly to the list() method for better performance.

Filtering by Account Manager:

Filtering by Billing Card:

Filtering by Date:

Filtering by Sector:

Filtering by Price Tier:

Filtering by Active Status:

Filtering by Report Settings:

Filtering by Billing Settings:

Filtering by Quoting Settings:

Filtering by Properties:

Filtering by Duplicate Status:

Filtering by Client Group:

Filtering by Branch:

Filtering by Account:

Filtering by Tags:

Filtering by Business Hours:

Filtering by Phone Number:

Filtering by Extra Fields:

Custom Filters:

You can pass custom filters directly to the list() method for better performance when using multiple filters:

Chaining Filters:

You can also chain filter methods together, though using list() with an array is more efficient:

Client Object Structure

Each client returned from listing methods is a Client DTO with the following structure:

Pagination

Many resource methods return a UptickPaginator instance for working with paginated API responses. The SDK uses Saloon's pagination plugin to handle pagination automatically. The Uptick API uses limit/offset pagination, where results are divided into pages. The SDK's paginator handles all of this for you, allowing you to iterate through every result across every page in one loop.

The paginator is a custom PHP iterator, meaning it can be used in foreach loops. It's also memory efficient - it only keeps one page in memory at a time, so you can iterate through thousands of pages and millions of results without running out of memory.

Iterating Over Items

The simplest way to use the paginator is to iterate over items using the items() method. This will give you each item across multiple pages:

Using Laravel Collections

If you're using Laravel (or have illuminate/collections installed), you can use the collect() method to get a LazyCollection. This allows you to use powerful collection methods like filter(), map(), sort(), and more while keeping memory consumption low:

Collecting All Items

You can collect all items into an array if you need to work with the complete dataset:

Accessing Pagination Metadata

The paginator provides methods to access pagination information:

Controlling Page Size

By default, 50 items are fetched per page. You can control pagination by setting the per-page limit:

The paginator will automatically handle fetching subsequent pages as you iterate through the results. You don't need to worry about managing page numbers or offsets - just iterate and the SDK handles the rest.

Using Saloon requests directly

You can use the request classes directly for full control:

Security

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

Credits

• Stitch Digital

License

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