Download the PHP package timatic/php-sdk without Composer

Timatic PHP SDK

A Laravel package for the Timatic API, built with Saloon and automatically generated from OpenAPI specifications.

Requirements

• PHP 8.2 or higher
• Laravel 10.x or higher

Installation

Configuration

The package automatically registers itself via Laravel auto-discovery.

Publish the config file:

Add your API credentials to .env:

Usage

Using Dependency Injection

The SDK connector is automatically registered in Laravel's service container, making it easy to inject into your controllers, commands, and other classes:

In Console Commands:

Testing

When testing code that uses the Timatic SDK, you can mock the connector and its responses using factories. The SDK includes factory classes for all DTOs that make it easy to generate test data.

Here's an example of testing the BudgetController from the example above:

Factory Methods

Every DTO in the SDK has a corresponding factory class with the following methods:

For more information on mocking Saloon requests, see the Saloon Mocking Documentation.

Pagination

The SDK supports automatic pagination for all collection endpoints using Saloon's pagination plugin:

The paginator:

• Automatically handles JSON:API pagination (page[number] and page[size])
• Detects the last page via links.next
• Works with all GET collection requests (GetBudgets, GetCustomers, GetUsers, etc.)

Custom Response Methods

All responses are instances of TimaticResponse which extends Saloon's Response with JSON:API convenience methods:

HTTP Methods

This SDK follows REST best practices and does not support PUT requests. Instead:

• POST - Create new resources
• PATCH - Partially update existing resources
• GET - Retrieve resources
• DELETE - Remove resources

PUT is intentionally excluded because resources are never completely replaced by Timatic.

Available Resources

The SDK provides access to the following resources:

• Budgets - Manage budgets and budget entries
• Customers - Customer management
• Users - User management
• Teams - Team management
• Entries - Time entry management
• Incidents - Incident tracking
• Changes - Change tracking
• Overtimes - Overtime management
• Events - Event logging
• And more...

JSON:API Support

This SDK uses a custom JSON:API DTO Generator that automatically flattens JSON:API attributes into proper Model properties. Instead of having generic $attributes, $type, and $relationships objects, each model has specific typed properties.

Example

Instead of:

You get:

Model Features

• Extends Model base class with JSON:API support
• Property attributes via #[Property] for serialization
• DateTime handling with Carbon instances
• Type safety with PHP 8.1+ type hints
• HasAttributes trait for easy attribute manipulation

Regenerating the SDK

This SDK is automatically generated from the Timatic API OpenAPI specification using a custom JSON:API generator. To regenerate the SDK with the latest API changes:

This will:

1. Download the latest OpenAPI specification from the API
2. Generate Models with flattened JSON:API attributes
3. Update the autoloader
4. Format the code with Laravel Pint

How It Works

The SDK uses a custom JsonApiDtoGenerator that:

1. Detects JSON:API schemas in the OpenAPI specification
2. Extracts properties from the attributes object
3. Generates proper Model classes with specific properties
4. Adds #[Property] and #[DateTime] attributes
5. Uses Carbon for datetime fields

Development

Running Tests

License

This package is licensed under the Elastic License 2.0 (ELv2).

Credits

• Built with Saloon
• Generated using Saloon SDK Generator