README

A simple, robust PHP library for interacting with the Octo.travel API. This library provides an object-oriented interface to easily consume the API, including functionality for retrieving suppliers, managing products, and checking availability.

Features

Fully typed classes and value objects for a safer and clearer interface.
Built-in support for all API endpoints.
Easy-to-extend architecture using mappers and API call abstractions.
Guzzle HTTP client for efficient and reliable HTTP requests.

Installation

Install the library using Composer:

composer require kostaschasiotis/octotravel-php

Usage

Setup

Create an instance of the OctoClient with your API base URL and optional headers.

indlude('/path-to/vendor/autoload.php');

use KostasChasiotis\OctoTravel\Application\ApiClient\OctoClient;

$client = new OctoClient(
    baseUri: 'https://www.example.com/api_url/',
    headers: [
        'Authorization' => 'Bearer YOUR_API_KEY',
        'Content-Type' => 'application/json'
    ]
);

Endpoints

Get Supplier

Returns the supplier and associated contact details.

$supplier = $client->getSupplier();

Get Products

Fetch the list of products.

$products = $client->getProducts();

Get Single Product

Fetch the product for the given id.

$products = $client->getProduct('PRODUCT_ID');

Get Availability Calendar

This endpoint is highly optimised and will return a single object per day. It's designed to be queried for large date ranges and the result is used to populate an availability calendar.

use KostasChasiotis\OctoTravel\Domain\Entities\AvailabilityUnit;
use KostasChasiotis\OctoTravel\Domain\Entities\AvailabilityUnits;

$availabilityCalendar = $client->availabilityCalendar(
    'PRODUCT_ID',
    'OPTION_ID',
    new DateTimeImmutable('START_DATE'),
    new DateTimeImmutable('END_DATE'),
    new AvailabilityUnits(
        new AvailabilityUnit(AVAILABILITY_
            //... AvailabilityUnit Details
        ),
        ...
    )
);

Check Availability

This endpoint is slightly slower as it will return an object for each individual departure time (or day).

You have to perform this step to retrieve an availabilityId in order to confirm a sale, so if you just want to use this endpoint and skip the calendar endpoint then that's perfectly ok.

use KostasChasiotis\OctoTravel\Domain\Entities\AvailabilityUnit;
use KostasChasiotis\OctoTravel\Domain\Entities\AvailabilityUnits;

$availabilityCheck = $client->availabilityCheck(
    'PRODUCT_ID',
    'OPTION_ID',
    new DateTimeImmutable('START_DATE'),
    new DateTimeImmutable('END_DATE'),
    ['AVAILABILITY_ID'],
    new AvailabilityUnits(
        new AvailabilityUnit(
            //... Unit Details
        ),
        ...
    )
);

Booking Reservation

Reserving availability when making a booking.

use KostasChasiotis\OctoTravel\Domain\Entities\BookingReservationUnitItem;
use KostasChasiotis\OctoTravel\Domain\Entities\BookingReservationUnitItems;
use KostasChasiotis\OctoTravel\Domain\ValueObjects\Uuid;

$bookingReservations = $client->bookingReservation(
    new Uuid('UUID'),
    'PRODUCT_ID',
    'OPTION_ID',
    'AVAILABIITY_ID',
    EXPIRATION_MINUTES,
    'NOTES',
    new BookingReservationUnitItems(
        new BookingReservationUnitItem(
            new Uuid('UUID'),
            'UNIT_ID'
        ),
        ...
    )
);

Get Bookings

This endpoint will fetch the bookings you have made for the given filters.

When using this endpoint you must include one of the following query parameters:

resellerReference
supplierReference
localDate
localDateStart and localDateEnd

$bookings = $client->getBookings(
    'RESELLER_REFERENCE',
    'SUPPLIER_REFERENCE',
    new DateTimeImmutable('LOCAL_DATE'),
    new DateTimeImmutable('START_DATE'),
    new DateTimeImmutable('END_DATE'),
    'PRODUCT_ID',
    'OPTION_ID'
);

Booking Confirmation

This endpoint confirms the booking so it's ready to be used.

use KostasChasiotis\OctoTravel\Domain\Entities\BookingConfirmationUnitItem;
use KostasChasiotis\OctoTravel\Domain\Entities\BookingConfirmationUnitItems;
use KostasChasiotis\OctoTravel\Domain\ValueObjects\Uuid;

$bookingConfirmation = $client->bookingConfirmation(
    new Uuid('UUID'),
    EMAIL_RECEIPT_TRUE_FALSE,
    'RESELLER_REFERENCE',
    new Contact(CONTACT_DETAILS),
    new BookingConfirmationUnitItems(
        new BookingConfirmationUnitItem(BOOKING_CONFIRMATION_UNIT_ITEM_DETAILS),
        ...
    )
);

Booking Cancellation

For cancelling bookings. You can only cancel a booking if booking.cancellable is TRUE, and is within the booking cancellation cut-off window.

use KostasChasiotis\OctoTravel\Domain\ValueObjects\Uuid;

$bookingCancellation = $client->bookingCancellation(
    new Uuid('UUID'),
    'REASON',
    FORCE_TRUE_OR_FALSE
);

Get Booking

Fetch the status of an existing booking.

use KostasChasiotis\OctoTravel\Domain\ValueObjects\Uuid;

$booking = $client->getBooking(new Uuid('UUID'));

Booking Update

Updates a booking before and after it has been confirmed as long as it hasn't been redeemed or within the cancellation cutoff window.

use KostasChasiotis\OctoTravel\Domain\Entities\BookingConfirmationUnitItem;
use KostasChasiotis\OctoTravel\Domain\Entities\BookingConfirmationUnitItems;
use KostasChasiotis\OctoTravel\Domain\Entities\Contact;
use KostasChasiotis\OctoTravel\Domain\ValueObjects\Uuid;

$bookingUpdate = $client->bookingUpdate(
    new Uuid('UUID'),
    'RESELLER_REFERENCE',
    'PRODUCT_ID',
    'OPTION_ID',
    'AVAILABILITY_ID',
    'EXPIRATION_MINUTES',
    'NOTES',
    SEND_EMAIL_RECEIPT_TRUE_OR_FALSE,
    new BookingConfirmationUnitItems(
        new BookingConfirmationUnitItem(BOOKING_CONFIRMATION_UNIT_ITEM_DETAILS),
        ...
    ),
    new Contact(CONTACT_DETAILS)
);

Extend Reservation

Use this endpoint to hold the availability for a booking longer if the status is ON_HOLD.

use KostasChasiotis\OctoTravel\Domain\ValueObjects\Uuid;

$bookingUpdate = $client->extendReservation(
    new Uuid('UUID'),
    EXPIRATION_MINUTES
);

Extending the Library

This library uses a mapper-based architecture to map raw API responses to domain entities. You can easily add new endpoints or extend the functionality:

Create a New API Call Class Implement the ApiCallInterface for your custom API endpoint logic.
Add Mappers Map raw data to your domain entities using static mapper classes.
Register the Call Add the new call to OctoClient for easy access.

Contributing

Contributions are welcome! To contribute:

Fork the repository.
Create a new feature branch: git checkout -b feature/your-feature-name.
Commit your changes: git commit -m "Add your message here".
Push the branch: git push origin feature/your-feature-name.
Open a pull request.

License

This library is open-sourced under the MIT license.

Acknowledgments

Special thanks to the Octo.travel team for providing the inspiration and API documentation for this library.

kostaschasiotis / octotravel-php

Maintainers

Details