PHPackages                             mintopia/flights - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [API Development](/categories/api)
4. /
5. mintopia/flights

ActiveLibrary[API Development](/categories/api)

mintopia/flights
================

Library for searching Google Flights

v1.0.0(5mo ago)231↓50%1MITPHPPHP ^8.4|^8.5CI passing

Since Dec 16Pushed 5mo agoCompare

[ Source](https://github.com/mintopia/flights)[ Packagist](https://packagist.org/packages/mintopia/flights)[ Docs](https://github.com/mintopia/flights)[ RSS](/packages/mintopia-flights/feed)WikiDiscussions develop Synced 1mo ago

READMEChangelog (1)Dependencies (14)Versions (3)Used By (0)

PHP Flight Search Library
=========================

[](#php-flight-search-library)

[![codecov](https://camo.githubusercontent.com/d3aa64bf4bcaf96b44c40afa611a0da470ee1a0df9ab94fe870cf3b291631a58/68747470733a2f2f636f6465636f762e696f2f67682f6d696e746f7069612f666c69676874732f6272616e63682f6d61696e2f67726170682f62616467652e7376673f746f6b656e3d57334b4d55344d5a3950)](https://codecov.io/gh/mintopia/flights)[![GitHub Actions Workflow Status](https://camo.githubusercontent.com/232267be9811b3d4b89622b4b0d5f340c232ca6ea8faa1256f894ebba3475b0d/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f616374696f6e732f776f726b666c6f772f7374617475732f6d696e746f7069612f666c69676874732f636f64652d7175616c6974792e796d6c3f6272616e63683d6d61696e)](https://camo.githubusercontent.com/232267be9811b3d4b89622b4b0d5f340c232ca6ea8faa1256f894ebba3475b0d/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f616374696f6e732f776f726b666c6f772f7374617475732f6d696e746f7069612f666c69676874732f636f64652d7175616c6974792e796d6c3f6272616e63683d6d61696e)[![Packagist Version](https://camo.githubusercontent.com/00bfeecb967988e49b39f7e2db8d9e2e8e51e5db99cb85e8233ee2ecdf668552/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f6d696e746f7069612f666c6967687473)](https://packagist.org/packages/mintopia/flights)[![GitHub Sponsors](https://camo.githubusercontent.com/d71c0ef1d56e16df226817ae6549f2840d5b041503fc9b0fdd00cdfd617e175a/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f73706f6e736f72732f6d696e746f706961)](https://github.com/sponsors/mintopia)

Introduction
------------

[](#introduction)

This is a PHP library for looking up flight information with Google Flights. There isn't an official free API so instead this uses the same endpoints that the Google Flights website does.

The Google Flights endpoint is a mix of protobuf and nested JSON arrays. This library will encode and decode the requests and extract the JSON from the HTML pages.

Why would I use this?
---------------------

[](#why-would-i-use-this)

Google Flights and ITA Matrix is great, but it doesn't cover all use-cases. It will only do certain return flights with certain airlines; it won't show layovers shorter than recommended minimums and sometimes you have a problem to solve that is harder than you can easily do on Google Flights/ITA Matrix.

Being able to script your searches and make decisions based on your own logic has so much potential. I've used this for such things as:

- Working out the cheapest way to get from one small domestic airport to another small domestic airport in a different country on 4 different airlines; where travel times are after working hours on a Friday, unless its a public holiday.
- Finding an efficient and low cost route for obtaining airline tier points.
- Sending a weekly summary email of affordable flights that fit in around my working hours.

One you can script these searches and do the lookups yourself, you can do all sorts of fun and complex things - it's the reason I wrote this library!

Requirements
------------

[](#requirements)

- PHP 8.4
- Either [`ext-protobuf`](https://pecl.php.net/package/protobuf)or the[`google/protobuf`](https://packagist.org/packages/google/protobuf) package.

Terminology
-----------

[](#terminology)

There's some terminology used in the library that is helpful to understand.

- `Flight` - An individual flight, with a flight number, a departure and arrival time.
- `Journey` - 1 or more flights that make up a particular segment of trip, eg. Outbound or Return. It can contain multiple flights if there are connections. Each journey does have a price. You can add these using the `addSegment`method on the Search class.
- `Itinerary` - A collection of journeys that make up a single ticketed and priced trip. This would include both the outbound and return flights.

Airports are represented by their 3-digit IATA codes, eg. `LHR` for London Heathrow or `LON` for all airports in the London area.

Airlines are represented by their 2-digit IATA codes, eg. `BA` for British Airways or `VS` for Virgin Atlantic.

Usage
-----

[](#usage)

The main entrypoint is the `\Mintopia\Flights\FlightService` class. From here you can configure your search parameters and then fetch all trips that meet those parameters.

### Instantiating the Library

[](#instantiating-the-library)

The library requires a PSR 18 compatible HTTP client and a Request Factory. A library like Guzzle is able to provide this. It can be passed in to the constructor or a service container can provide these.

```
$client = new GuzzleHttp\Client();
$requestFactory = new GuzzleHttp\Psr7\HttpFactory();

$search = new Mintopia\Flights\FlightService(requestFactory: $requestFactory, httpClient: $client);
```

You can also specify a PSR-3 compatible logging interface to either the constructor or via the `setLogger` method. If one isn't supplied then a null logger is used instead. An example using Monolog is:

```
// Our HTTP client and request factory from Guzzle
use GuzzleHttp\Client;
use GuzzleHttp\Psr7\HttpFactory;

$client = new Client();
$requestFactory = new Psr7\HttpFactory();

// Create a logger using Monolog
use Monolog\Level;
use Monolog\Logger;
use Monolog\Handler\StreamHandler;

// Create a log channel to write to flights.log
$log = new Logger('flights');
$log->pushHandler(new StreamHandler('flights.log', Level::Debug));

// Now create the flight search
use Mintopia\Flights\FlightService;
$search = new QueryBuilder(requestFactory: $requestFactory, httpClient: $client, logger: $log);
```

### Searching for flights

[](#searching-for-flights)

Once you have a client, you can start a query and add segments to it, then when done call `getItineraries()`. The library will then use Google Flights to fetch possible itineraries.

The query builder is immutable, so it will return new instance of itself on every mutable method call.

```
use GuzzleHttp\Client;
use GuzzleHttp\Psr7\HttpFactory;
use Mintopia\Flights\FlightService;

// Our dependencies
$client = new Client();
$requestFactory = new Psr7\HttpFactory();

// Create our search client
$flightService = new FlightService($requestFactory, $client);
$itineraries = $flightService->query()->addSegment(
    from: ['LHR', 'LGW'],
    to: 'JFK',
    date: '2025-12-10',
    maxStops: 0,
    airlines: ['BA', 'VS']
)->get();
```

This would perform a search for all flights on 10th December 2025 from London Heathrow and London Gatwick, to New York's JFK with no stops and limited to Virgin Atlantic.

```
$flightService = new FlightService($requestFactory, $client);
$flightService->query()->addSegment('LHR', 'FAO')->get();
```

You can leave out most of the options, it'll default to tomorrow for the date with 0 stops and any airline. Airports can be specified either as an array for multiple or the single airport code.

To search for a return flight, add another segment:

```
$flightService = new FlightService($requestFactory, $client)
$itineraries = $flightService
    ->query()
    ->addSegment('LGW', 'FAO', '+1 day')
    ->addSegment('FAO', 'LGW', '+3 days')
    ->get();
```

By default, it searches for flights for one passenger, but you can add more:

```
use Mintopia\Flights\Enums\PassengerType;

$flightService = new FlightService($requestFactory, $client)
$itineraries = $flightService
    ->query()
    ->addSegment('LGW', 'FAO')
    ->addPassenger(PassengerType::Adult)
    ->get();
```

You can also set passengers in a single call:

```
$flightService = new FlightService($requestFactory, $client)
$itineraries = $flightService
    ->query()
    ->addSegment('LGW', 'FAO')
    ->setPassengers([
        PassengerType::Adult,
        PassengerType::Adult,
        PassengderType::Child,
    ])
    ->get();
```

If you want to search for a different class, eg. Business or Premium Economy, you can also specify it:

```
use Mintopia\Flights\Enums\BookingClass;

$flightService = new FlightService($requestFactory, $client)
$itineraries = $flightService
    ->query()
    ->addSegment('LGW', 'FAO')
    ->setBookingClass(BookingClass::Business)
    ->get();
```

Finally, you can sort the results by adding the `sortOrder()` call to the search.

```
use Mintopia\Flights\Enums\SortOrder;

$flightService = new FlightService($requestFactory, $client)
$itineraries = $flightService
    ->query()
    ->addSegment('LGW', 'FAO')
    ->sortOrder(SortOrder::Price)
    ->get();
```

### Caching

[](#caching)

The library supports a PSR16 compatible cache. To use it, either pass it in as a constructor argument or into the `setCache` method. All HTTP requests that result in a 200 OK response will be cached for the TTL. You can set the TTL with the `setCacheTTL` method which can take either a DateInterval object, a date interval string or a number of seconds. The default is 1 hour.

```
use Mintopia\Flights\FlightService;
use Symfony\Component\Cache\Psr16Cache;
use Symfony\Component\Cache\Adapter\FilesystemAdapter

// Use Symfony's filesystem cache, but pass it through their PSR16 translation first
$cache = new Psr16Cache(new FilesystemAdapter());

$flightService = new FlightService();
$flightService->setCache($fileCache);
```

### Putting it all together

[](#putting-it-all-together)

So let's see a full implementation of the library:

```