felixfever / tripleseat
Tripleseat API interface for PHP 8
Requires
- php: >=8
- ext-json: *
- api-clients/psr7-oauth1: ^3.0
- php-http/client-implementation: ^1.0
- php-http/discovery: ^1.0
- psr/http-factory: ^1.0
Requires (Dev)
- guzzlehttp/guzzle: 7.0.1
- guzzlehttp/psr7: ^1.6
- http-interop/http-factory-guzzle: ^1.0
- php-http/guzzle7-adapter: 0.1.1
- phpunit/phpunit: ^8.5
- symfony/var-dumper: 5.2.x-dev
Suggests
- guzzlehttp/guzzle: Use Guzzle ^7 as HTTP client
- http-interop/http-factory-guzzle: Factory for guzzlehttp/guzzle
README
A simple PHP wrapper around Tripleseat's API.
Requires at least PHP 8
Until v1 there may be backward incompatible changes with every minor version (0.x).
How is this fork different
- Compatible with PHP 8
- Adds a method to get total page count to make it possible to build a pager.
Getting started
First, create a new instance of the Tripleseat client and provide the API keys for authentication.
$ composer require bonroyage/tripleseat
use Tripleseat\Tripleseat; $tripleseat = new Tripleseat([ 'api_key' => '', 'secret_key' => '', 'public_key' => '' ]);
API keys
You'll need to attain your Tripleseat account's API keys. These can be found by logging in to your Tripleseat account and going to Settings -> Tripleseat API.
There is a public and secret key that is used for the majority of the API calls. These values are configured as the api_key
and secret_key
respectively.
A second public key is shown separately and is used for some lead operations. This is configured as public_key
.
Services
The following services are supported
Service | Documentation | Schema |
---|---|---|
Account | Tripleseat documentation | Schema |
Booking | Tripleseat documentation | Schema |
Contact | Tripleseat documentation | Schema |
Event | Tripleseat documentation | Schema |
Lead | Tripleseat documentation | Schema |
Location | Tripleseat documentation | Schema |
Site | Tripleseat documentation | Schema |
User | Tripleseat documentation | Schema |
Sites
A site represents a group of venues. Sites can have multiple locations.
You will most likely only need to retrieve or alter data for a single site, this is also enforced by Tripleseat. For example, you cannot create a contact that belongs to an account in a different site.
An InvalidSite
exception will be thrown if the site is not in the list of sites that your API keys give you access to.
// Create a new client for Site with ID 1 $mySite = $tripleseat[1]; // Search accounts in this site $mySite->account->search(['query' => 'tripleseat']); // is the same as $tripleseat->account->search(['query' => 'tripleseat', 'site_id' => 1]);
What does it do in the background?
When you call an offset on the Tripleseat class, it first checks that the site ID is returned by the sites endpoint and then created a new instance of the Tripleseat class with the site_id
passed as additional property in the $auth
array.
Every request made with through this class will have site_id
added to the query parameters of each request.
$sites = $tripleseat->site->all(); $mySite = new Tripleseat([ 'api_key' => '', 'secret_key' => '', 'public_key' => '', 'site_id' => 1 ]);
What about endpoints that don't use site_id?
Endpoints like site
, location
, and user
don't support the site_id
parameter. They will always return the same result regardless of what site ID is passed.
all
and search
operations
When querying one of the all
or search
endpoints, the client will return a Generator that you can iterate through. These endpoints are paged and return 50 results per page. The client will check the total_pages
property in the first response and make sure every page gets loaded. The next page will only get loaded once the iterator gets to that point.
Call iterator_to_array
(?) to convert the Generator to an array and load all pages immediately.
Additionally, you may provide a $firstPage
or $untilPage
on these operations to change from which page on and/or until which page the data should be loaded (provided it's less than the total number of pages).
Note: The site
and location
services are not paged and do not feature the $firstPage
or $untilPage
arguments.
$bookings = $tripleseat->booking->search([ 'query' => 'Birthday', 'order' => 'created_by' ]); foreach($bookings as $booking) { // do something with $booking } // convert from Generator to array $bookingsArray = iterator_to_array($bookings);
count
operation
For services that return a Generator for paginated results a method exists to get the total number of pages.
$pageCount = $tripleseat->lead->pageCount();
Other operations
Service | get(id) |
create(payload) |
update(id, payload) |
delete(id) |
---|---|---|---|---|
Account | ✅ | ✅ | ✅ | ✅ |
Booking | ✅ | ✅ | ✅ | ✅ |
Contact | ✅ | ✅ | ✅ | ✅ |
Event | ✅ | ✅ | ✅ | ✅ |
Lead | ✅ | ✅ (?) | ❌ | ✅ |
Location | ❌ | ❌ | ❌ | ❌ |
Site | ❌ | ❌ | ❌ | ❌ |
User | ✅ | ❌ | ❌ | ❌ |
$user = $tripleseat->user->get(1); $tripleseat->lead->create([ 'first_name' => 'john', 'last_name' => 'doe', 'email_address' => 'johndoe@example.com', 'phone_number' => '123-123-1234', 'company' => 'Example Inc.', 'event_description' => 'the event desc', 'event_date' => '11/19/2020', 'start_time' => '3pm', 'end_time' => '5pm', 'guest_count' => '50', 'additional_information' => 'some more info', 'location_id' => '1', ]); $leadForms = $tripleseat->lead->forms();
Create and update payloads
Pass in the actual payload and the client will automatically wrap this with the correct key for the type. You can also provide an array with the payload already wrapped, this will not be wrapped again.
// Calling ... $tripleseat->contact->create([ 'account_id' => '', 'first_name' => 'John', 'last_name' => 'Doe', 'email_addresses' => [ [ 'address' => 'johndoe@example.com' ] ] ]); // will send the request as ... [ 'contact' => [ 'account_id' => '', 'first_name' => 'John', 'last_name' => 'Doe', 'email_addresses' => [ [ 'address' => 'johndoe@example.com' ] ] ] ]
Exceptions
All exceptions thrown by this library implement the Tripleseat\Exceptions\TripleseatException
interface.
HTTP Client Compatibilities
You could use any PSR-18 compatible client to use with this library. No additional configurations are required. A list of compatible HTTP clients and client adapters can be found at php-http.org.
$httpClient = // some class implementing Psr\Http\Client\ClientInterface $tripleseat = new Tripleseat($auth, $httpClient);