omnisense/omniticket

Installation

composer require omnisense/omniticket omniticket/billetweb symfony/http-client

Take the providers the organizer sells on: omniticket/weezevent, omniticket/billetweb, omniticket/helloasso, omniticket/eventbrite, omniticket/ticketmaster.

Requirements

• PHP 8.2 or later.
• omnisense/omniticket requires symfony/http-client-contracts (^3.0), interfaces only, and nothing else.
• Each provider requires omnisense/omniticket (1.x) and symfony/http-client-contracts (^3.0). The application gives the HTTP client - symfony/http-client, or any implementation of Symfony\Contracts\HttpClient\HttpClientInterface, a MockHttpClient in a test - to the factory's constructor. A factory built without one throws InvalidConfigException when the provider is built (The "billetweb" provider needs an HTTP client: give one to BilletwebFactory.).
• ext-json (always present since PHP 8.0).

Plain PHP

A whole script, Billetweb answered from recorded answers by the core's RecordedHttpClient:

<?php // bare.php

require __DIR__.'/vendor/autoload.php';

use Omniticket\Billetweb\BilletwebFactory;
use Omniticket\Model\EventQuery;
use Omniticket\Registry;
use Omniticket\Testing\RecordedHttpClient;

// Billetweb's answers, recorded; in production: Symfony\Component\HttpClient\HttpClient::create().
$http = RecordedHttpClient::routes([
    'GET /api/events' => '[{"id":"1235","name":"Retro future shock","start":"2030-12-31 20:00:00","end":"2031-01-01 02:00:00","place":"Paris","shop":"https://www.billetweb.fr/shop.php?event=1235"}]',
    'GET /api/event/1235/avail' => '[{"type":"event","id":"1235","avail":"80","quota":"200","total_sales":"120","status":"available"},{"type":"ticket","id":"124","avail":"80","quota":"100","total_sales":"20"},{"type":"ticket","id":"125","avail":"0","quota":"100","total_sales":"100"}]',
    'GET /api/event/1235/tickets' => '[{"id":"124","name":"Plein tarif","price":"25.00"},{"id":"125","name":"Réduit","price":"18.00"}]',
    'GET /api/event/1235/attendees' => '[{"id":"1","barcode":"4475320","firstname":"Jeanne","name":"Dupont","ticket":"Plein tarif","disabled":"0","used":"0","order_paid":"1"}]',
]);

$registry = new Registry([new BilletwebFactory($http)], [
    'box_office' => ['factory' => 'billetweb', 'options' => ['user' => 'demo', 'key' => 'demo']],
]);

foreach ($registry->catalog('box_office')->events(new EventQuery(limit: 20)) as $event) {
    echo $event->start?->format('Y-m-d H:i'), ' ', $event->title, ', ', $event->venue, "\n";
}

$event = $registry->catalog('box_office')->event('1235');
echo $event->status->value, ', ', $event->availability->remaining, " places left\n";
foreach ($event->rates as $rate) {
    printf("  %s: %s %s, %s left\n", $rate->label, $rate->price?->major(), $rate->price?->currency, $rate->availability->remaining ?? '?');
}

$check = $registry->checker('box_office')->check('1235', '4475320');
echo $check->result->value, ' ', $check->attendee?->name(), "\n";
echo count($http->requests), " calls\n";

$ php bare.php
2030-12-31 20:00 Retro future shock, Paris
on_sale, 80 places left
  Plein tarif: 25.00 EUR, 80 left
  Réduit: 18.00 EUR, 0 left
valid Jeanne Dupont
5 calls

(run on 2026-10-26 in the harness, PHP 8.4)

The pieces:

• a factory per provider (BilletwebFactory, WeezeventFactory...), which takes the HTTP client;
• the registry, built from the factories and the providers' options, by name; catalog(), attendees() and checker() give a provider as each contract, and throw NotSupportedException for one it lacks (Ticketmaster is a catalogue only) - Capabilities says it beforehand;
• the models: Event, Rate, Session, Availability, Money (minor units), Attendee, Check (Concepts).

Five calls: the events, then event()'s three (the event, its availability, its rates), then the check's one (Billetweb looks a barcode up). Building a provider calls nothing; events() calls when the iteration starts. Every failure is an Omniticket\Exception\OmniticketException (Errors).

No class of a framework is loaded on the way: Tests/BareTest.php runs the harness's bare script in a process of its own and checks that nothing but the package and the HTTP client contracts was loaded.

In a framework

There is no Omniticket bundle and no provider in omnibridge/symfony or omnibridge/laravel yet: build the Registry once where the framework builds its services - Symfony, Laravel.

Symfony

There is no Omniticket bundle, and omnibridge/symfony has no Omniticket wiring yet: a Symfony application declares the registry as a service of its own. The factories take the application's http_client by autowiring (Symfony\Contracts\HttpClient\HttpClientInterface).

# config/services.yaml
services:
    _defaults:
        autowire: true

    Omniticket\Billetweb\BilletwebFactory: ~
    Omniticket\Ticketmaster\TicketmasterFactory: ~

    Omniticket\Registry:
        arguments:
            $factories:
                - '@Omniticket\Billetweb\BilletwebFactory'
                - '@Omniticket\Ticketmaster\TicketmasterFactory'
            $config:
                box_office: { factory: billetweb, options: { user: '%env(BILLETWEB_USER)%', key: '%env(BILLETWEB_KEY)%' } }
                concerts: { factory: ticketmaster, options: { api_key: '%env(TICKETMASTER_API_KEY)%', country_code: FR, city: Strasbourg } }

# .env.local, or bin/console secrets:set
BILLETWEB_USER=...
BILLETWEB_KEY=...
TICKETMASTER_API_KEY=...

Then inject the registry:

use Omniticket\Model\EventQuery;
use Omniticket\Registry;
use Symfony\Contracts\Cache\CacheInterface;
use Symfony\Contracts\Cache\ItemInterface;

final class Programme
{
    public function __construct(private readonly Registry $ticketing, private readonly CacheInterface $cache)
    {
    }

    /** @return list<array<string, mixed>> */
    public function upcoming(): array
    {
        return $this->cache->get('programme', function (ItemInterface $item): array {
            $item->expiresAfter(600);

            return array_map(static fn ($e) => $e->toArray(), [...$this->ticketing->catalog('box_office')->events(new EventQuery(limit: 30))]);
        });
    }
}

Nothing is built when the container compiles: a provider is built, and its required options checked, the first time the registry is asked for it. Each provider states rate limits and fair use rules (Capabilities::$limits): cache the catalogue, keep the attendee list on the application's side.

This page was written from the classes' constructors; it was not run in a Symfony kernel.

Laravel

omnibridge/laravel has no Omniticket provider: a service provider of the application builds the registry once, from a config file, with a symfony/http-client client (the providers take a Symfony\Contracts\HttpClient\HttpClientInterface; Laravel's own HTTP client is Guzzle's, which they do not take).

// config/omniticket.php
return [
    'providers' => [
        'festival' => ['factory' => 'weezevent', 'options' => [
            'api_key' => env('WEEZEVENT_API_KEY'),
            'access_token' => env('WEEZEVENT_ACCESS_TOKEN'),
        ]],
    ],
];

// app/Providers/OmniticketServiceProvider.php
namespace App\Providers;

use Illuminate\Support\ServiceProvider;
use Omniticket\Registry;
use Omniticket\Weezevent\WeezeventFactory;
use Symfony\Component\HttpClient\HttpClient;

final class OmniticketServiceProvider extends ServiceProvider
{
    public function register(): void
    {
        $this->app->singleton(Registry::class, fn (): Registry => new Registry(
            [new WeezeventFactory(HttpClient::create(['timeout' => 20]))],
            config('omniticket.providers'),
        ));
    }
}

Register the provider (bootstrap/providers.php on Laravel 11 and later), then:

use Illuminate\Support\Facades\Cache;
use Omniticket\Registry;

$events = Cache::remember('programme', 600, fn () => array_map(
    static fn ($e) => $e->toArray(),
    [...app(Registry::class)->catalog('festival')->events()],
));

Keep arrays in the cache (toArray() on every model). Configuration caching keeps working: the options are plain arrays. This page was written from the registry's API; it was not run in a Laravel application.

Concepts

Provider and its contracts

Omniticket\ProviderInterface is one ticketing service, configured:

The contracts, each extending ProviderInterface:

Capabilities

Omniticket\Capabilities (readonly):

contracts() lists catalog, attendees, check as it has them; toArray() all of it. Each provider's values are in the index and its own page.

Factory and Config

Omniticket\ProviderFactoryInterface: getName(): string, create(array $options = []): ProviderInterface. Every provider extends Omniticket\ProviderFactory:

1. createConfig($options): the options in a Config (an ArrayObject), then the factory's populate() sets omniticket.factory_name, omniticket.factory_title, omniticket.required_options and the defaults of the others;
2. the required options are checked: one missing, '' or [] is an InvalidConfigException listing every missing key (The "billetweb" provider needs: key.);
3. build($config) constructs the provider. Nothing is called.

Config's readers: get($key, $default), string($key) (null when empty), int(), float(), bool() (a bool, or "1", "true", "yes", "on"), validateNotEmpty($keys).

Registry

Omniticket\Registry:

$registry = new Registry([new BilletwebFactory($http), new TicketmasterFactory($http)], [
    'box_office' => ['factory' => 'billetweb', 'options' => ['user' => '...', 'key' => '...']],
    'concerts' => ['factory' => 'ticketmaster', 'options' => ['api_key' => '...']],
]);

An unknown name or factory is an InvalidConfigException (No "x" ticketing provider; configured: ..., No "x" factory for the "y" ticketing provider; installed: ...).

Event

Omniticket\Model\Event (readonly). events() fills what a list gives; event() the whole record.

onSale(): status OnSale and not sold out. soldOut(): status SoldOut or the availability sold out. lowestPrice(): the lowest rate price, or the range's lower end. toArray().

EventStatus: Draft (not published), Upcoming (published, sales not open), OnSale, SoldOut, SalesClosed (sales over, the event not cancelled), Ended, Cancelled, Postponed, Unknown (values in snake_case: on_sale...).

EventQuery

Omniticket\Model\EventQuery (readonly): from, to (?\DateTimeImmutable), keyword (?string), past (bool, default false), limit (?int), now (?\DateTimeImmutable, a test's clock; the real one when null).

A provider passes what its API can filter on, and returns $query->filter(...), which applies the whole query to what comes back:

• not past: an event whose end (else start) is before now is left out;
• from: an event whose end (else start) is before it is left out;
• to: an event that starts after it is left out;
• keyword: kept when the title or the venue contains it, case-insensitive;
• limit: at most that many matching events; the iteration stops there (no further page asked).

An event without dates passes the date tests.

Rate, Session, Availability

Rate (readonly), one price: id, label, price (?Money; null when the provider gives none, or the price is the buyer's to choose), availability, salesStart, salesEnd, minimum (?Money, the least a buyer may pay when the price is theirs), category (?string, Billetweb's category, Weezevent's category path Categorie 1 > Sous Categorie 1).

Session (readonly), one date of an event sold for several: id, start, end, name, venue, availability.

Availability (readonly), as far as the provider says - an unknown remainder is null, not 0:

Money

Omniticket\Model\Money (readonly): int $amount in the currency's minor unit - never a float, so 9.99 stays 999 - and an ISO 4217 currency, upper-cased. fromMajor($major, $currency) from units ("12.50", 9.99, 10); major() back ("12.50", "3000" for JPY); exponent($currency) is 0 for BIF, CLP, DJF, GNF, ISK, JPY, KMF, KRW, PYG, RWF, UGX, VND, VUV, XAF, XOF, XPF and 2 otherwise; isFree(); toArray().

Attendee

Omniticket\Model\Attendee (readonly), one ticket and the person it is for:

name() joins the names; toArray(). AttendeeStatus: Valid (paid or free, not scanned), CheckedIn (scanned), Cancelled, Refunded, Pending (not paid yet).

Check

Omniticket\Model\Check (readonly): code, result (CheckResult), attendee (?Attendee). valid() is result === Valid. CheckResult: Valid, AlreadyUsed (scanned), Void (cancelled, refunded or not paid), Unknown (no ticket of this event holds the code).

• Check::of($code, ?Attendee): the result from the attendee's status - none Unknown, Valid Valid, CheckedIn AlreadyUsed, Cancelled, Refunded and Pending Void.
• Check::among(iterable $attendees, $code): the first attendee whose code equals it (compared in constant time) decides: for providers with no lookup by code.

Support\Data and Http\JsonApi

Omniticket\Support\Data reads a decoded answer with types at a dotted path (venue.city.name): raw(), has(), string() (trimmed, null when empty; a bool as "1"/"0"), int(), float(), bool() (true, 1, "1", "true", "yes"), date($path, $timezone) (a UNIX timestamp or a string PHP reads, in $timezone when it names none; null for 0000-00-00... or unreadable), data(), list(), items().

Omniticket\Http\JsonApi($http, $provider)->request($method, $url, $options, $what): Data calls through the injected client and turns every failure into the family's exceptions (Errors), with the provider's own message when the answer carries one (error_description, error.message, message, detail, errors.0.message, errors.0.detail, fault.faultstring, error).

Events

use Omniticket\Model\EventQuery;

$catalog = $registry->catalog('box_office');

$catalog->events();                                                     // upcoming ones
$catalog->events(new EventQuery(from: new \DateTimeImmutable('first day of next month'), limit: 20));
$catalog->events(new EventQuery(keyword: 'jazz', past: true));

$event = $catalog->event('1235');
foreach ($event->rates as $rate) {
    printf("%s: %s %s, %s left\n", $rate->label, $rate->price?->major() ?? 'free choice', $rate->price?->currency, $rate->availability->remaining ?? '?');
}
echo $event->onSale() ? 'Buy: '.$event->url : $event->status->value;

events() returns an iterable: a provider's calls are made when the iteration starts, and with a limit no page is asked beyond what the limit needs. A failure (a refused key...) is thrown during the iteration. Keep [...$events] or toArray() in a cache: every provider limits its calls.

What each provider reads

Prices: Billetweb and Weezevent give units in a currency they do not name (the currency option); HelloAsso cents in EUR (a price of 0 with a minAmount is the buyer's to choose: no price, a minimum); Eventbrite currency objects in minor units (a free class is 0); Ticketmaster a price range in units.

Showing a programme

use Omniticket\Model\EventQuery;

$events = [];
foreach ($registry->names() as $name) {
    if ($registry->get($name)->capabilities()->catalog) {
        array_push($events, ...$registry->catalog($name)->events(new EventQuery(limit: 50)));
    }
}
usort($events, static fn ($a, $b) => $a->start <=> $b->start);

foreach ($events as $event) {
    printf("%s  %-40s %s %s\n", $event->start?->format('d/m H:i'), $event->title, $event->lowestPrice()?->major() ?? '', $event->soldOut() ? 'complet' : '');
}

Event::$widgetUrl (Billetweb, HelloAsso) is the provider's purchase module, to put in a frame; Event::$url its page. Ticketmaster's terms ask that purchases go through the event's url.

Attendees and checks

Attendees

$list = $registry->attendees('box_office');

// The first read: every ticket, cancelled and refunded ones included.
foreach ($list->attendees('1235') as $attendee) {
    $store->save($attendee->toArray());
}

// Then only what changed, where the provider allows it (Capabilities::$incremental).
$since = $store->lastRead('1235');
foreach ($list->attendees('1235', $since) as $attendee) {
    $store->save($attendee->toArray());
}

The providers ask for it - Billetweb and Weezevent in so many words: keep the list on the application's side and read it incrementally.

Checking a ticket at the door

use Omniticket\Model\CheckResult;

$check = $registry->checker('box_office')->check('1235', $scannedCode);
echo match ($check->result) {
    CheckResult::Valid => 'OK '.$check->attendee?->name().' - '.$check->attendee?->rate,
    CheckResult::AlreadyUsed => 'Already scanned at '.$check->attendee?->checkedInAt?->format('H:i'),
    CheckResult::Void => 'Cancelled, refunded or not paid',
    CheckResult::Unknown => 'Not a ticket of this event',
};

A check reads only: the ticket is not marked as scanned at the provider (the provider's own scanning application does that; Billetweb's check POST, which would, is not used). Two checks of the same code both answer Valid until the provider's own application scans it.

An application that checks many tickets keeps the list itself - attendees() with $updatedSince, then Check::among($attendees, $code) locally - rather than reading the whole list at every scan: Billetweb's attendee calls are limited to 10 a minute, Eventbrite's to 2,000 an hour.

Configuration reference

The registry

new Registry(iterable $factories, array $config);

Options are taken as given: a required option given as null, '' or [] is reported missing; an optional one given as '' reads as not set. Every provider's factory takes the HTTP client in its constructor (?HttpClientInterface $http = null); without one, building the provider is an InvalidConfigException.

weezevent

Neither a token nor a login: InvalidConfigException (The "weezevent" provider needs: access_token, or username and password.).

billetweb

helloasso

Prices are read in EUR.

eventbrite

ticketmaster

fixed

Omniticket\Testing\FixedTicketingFactory(array $events = [], array $attendees = []): no option; the events and the attendees (by event id) are given to the constructor (Testing).

Errors

Every exception Omniticket throws implements Omniticket\Exception\OmniticketException (a \Throwable):

Messages, as JsonApi and the providers write them (run on recorded answers on 2026-10-26):

NotSupportedException (0): The "concerts" provider (Omniticket\Ticketmaster\TicketmasterProvider) does not list attendees.
NotFoundException (404): Ticketmaster has no event "9": Resource not found with provided criteria (locale=en-us, id=9)
InvalidKeyException (401): Billetweb refused the credentials (401) for the events: invalid key
NotSupportedException (0): The "helloasso" provider (Omniticket\HelloAsso\HelloAssoProvider) does not read attendees changed since a moment (its items have no such filter).
ProviderException (429): Eventbrite answered 429 for event "1": Hourly rate limit has been reached for this token.
InvalidConfigException (0): The "weezevent" provider needs: access_token, or username and password.
InvalidConfigException (0): The "weezevent" provider needs an HTTP client: give one to WeezeventFactory.
InvalidConfigException (0): The "billetweb" provider needs: key.
ProviderException (200): Example answered 200 for it: an answer that is not JSON

The provider's own message is taken from the answer under the names APIs give it (Concepts). A 429 (a rate limit) is a ProviderException with code 429. An events() listing throws while it is iterated, not when it is called.

No secret in a failure

An UnreachableException keeps the request's secrets out. The HTTP client's message quotes the URL called: its key parameters (Ticketmaster's apikey), a password in its user part and every secret of the request's options (a bearer token, a key in a header) are masked (apikey=***, Http\Redaction::text()). The previous exception is a copy of the client's (Redaction::copy(): the same class and code, that message), and no trace of the chain keeps its arguments, where the query and headers stood: a log that writes the whole chain, arguments included (zend.exception_ignore_args off), holds no key. Nor does an error answered (a refused key, nothing there, a server error, a body that is not JSON): every exception JsonApi::request() throws leaves its trace's arguments out.

What to catch where

Testing

The fixed provider

Omniticket\Testing\FixedTicketing answers from what it was given, every contract, no network: an application's tests, a demo, the harness's bare script. FixedTicketingFactory gives it to a registry under the name fixed:

use Omniticket\Model\Attendee;
use Omniticket\Model\AttendeeStatus;
use Omniticket\Model\Availability;
use Omniticket\Model\Event;
use Omniticket\Model\EventQuery;
use Omniticket\Model\EventStatus;
use Omniticket\Model\Money;
use Omniticket\Model\Rate;
use Omniticket\Registry;
use Omniticket\Testing\FixedTicketingFactory;

$events = [
    new Event('1235', 'Retro future shock', new \DateTimeImmutable('2026-12-31 20:00:00'), status: EventStatus::OnSale,
        availability: Availability::of(null, 200, 120),
        rates: [new Rate('124', 'Plein tarif', Money::fromMajor('25.00', 'EUR'), Availability::of(90, 100))]),
];
$attendees = ['1235' => [
    new Attendee('1', '1235', '4475320', 'Jeanne', 'Dupont'),
    new Attendee('2', '1235', '4475321', 'Paul', 'Martin', status: AttendeeStatus::CheckedIn),
]];

$registry = new Registry([new FixedTicketingFactory($events, $attendees)], ['box_office' => ['factory' => 'fixed']]);

$registry->catalog('box_office')->events(new EventQuery(now: new \DateTimeImmutable('2026-11-01')));   // the event
$registry->checker('box_office')->check('1235', '4475321')->result;                                     // CheckResult::AlreadyUsed

events() applies the query to the events given (give now for a fixed clock); event() throws NotFoundException for an id not given; check() is Check::among() over the attendees. It is not incremental (capabilities()->incremental false): attendees($eventId, $updatedSince) with a date is a NotSupportedException, as on a provider that cannot read since a moment. The application keeps the name it uses; only the factory changes.

The recorded HTTP client

Omniticket\Testing\RecordedHttpClient implements Symfony's HttpClientInterface, answers from what it was given and keeps every request ($requests: method, URL, options): a provider's calls checked with no network.

use Omniticket\Testing\RecordedHttpClient;

$http = RecordedHttpClient::routes([
    'GET /api/events' => '[{"id":"1235","name":"Retro future shock","start":"2030-12-31 20:00:00"}]',
    'GET /api/private' => [401, '{"error":"invalid key"}'],
]);

routes(): the first route whose method matches and whose path ends the URL's path (the query is ignored) answers its body (status 200), or [status, body]; anything not recorded is a 404 ({"error":"not recorded: GET /path"}). new RecordedHttpClient(fn ($method, $url, $options) => [status, body, headers]) answers anything. It does not stream. The installation script runs Billetweb on it.

The load check

Omniticket\Testing\LoadCheck::run($root, $namespace, $autoload) loads every class of a package in a PHP process of its own (bin/load-all) and reports what came from outside: classes of a framework, an HTTP client or an application (LoadCheck::FOREIGN; Symfony's HTTP client and service contracts are allowed), and files of packages it does not require (outside()). Every package of the family runs it in its BareTest.

Live checks

docker compose run --rm omniticket live runs the live group: only what needs no account - Weezevent's GET /event/categories (WeezeventProvider::eventCategories()).

The Docker harness

docker/ composes this core and every provider (docker/harness/plugins.php) into one installation, PHP 8.4, in the image omnisense/omniticket-harness. docker/harness/setup.php writes the harness's composer.json and phpunit.xml into a volume, and the entrypoint installs them when they change.

cd docker
docker compose run --rm omniticket test       # every package's tests, no network (the live group left out)
docker compose run --rm omniticket live       # the checks that need no account (Weezevent's public endpoint)
docker compose run --rm omniticket bare       # the bare script: plain PHP, and what PHP loaded
docker compose run --rm omniticket phpstan    # PHPStan at the highest level, each package
docker compose run --rm -v "$PWD/scratch:/scratch" omniticket php /scratch/x.php   # a script of your own (autoloader: /harness/vendor/autoload.php)
docker compose down -v                        # the harness's volume gone

With no command the entrypoint runs test; composer, sh and php run as they are. Providers come from GitHub (branch 1.x, github.com/glitchr-omnisense/omniticket-<slug>) unless OMNITICKET_PLUGINS (in docker/.env) points at a directory holding their checkouts - ../.. when this core sits in the workspace beside them, as docker/.env sets it.

Bare

docker/harness/bin/bare uses Omniticket in plain PHP - no bundle, no container, no framework: a registry with the fixed provider, the upcoming events listed (a past one left out, a keyword), one read whole, its attendees, four codes checked at the door; then a JSON API answered through the recorded HTTP client - an answer read with types, a refused key and a missing event turned into the family's exceptions. It prints what happened and every class and file PHP loaded, as JSON; run on 2026-10-26, without the event and loaded parts:

"upcoming": ["1235", "1236"],
"keyword": ["1236"],
"onSale": true,
"lowestPrice": "18.00",
"attendees": [["Jeanne Dupont", "valid"], ["Paul Martin", "checked_in"], ["Ana Lima", "refunded"]],
"checks": {"4475320": "valid", "4475321": "already_used", "4475322": "void", "0000000": "unknown"},
"api": ["Retro future shock", "2026-12-31T20:00:00+01:00"],
"errors": {"/api/private": [true, "Example refused the credentials (401) for it: invalid key"],
           "/api/event/9": [true, "Example has no it: not recorded: GET /api/event/9"]}

Tests/BareTest.php runs it in a process of its own and checks that nothing outside the package was loaded but Symfony's HTTP client contracts. Each provider's BareTest runs Testing\LoadCheck on its own classes.

Writing a provider

A provider is a package omniticket/<name> with a factory and a provider class:

• the factory extends Omniticket\ProviderFactory: populate() names it, lists its required options and their defaults; build() returns the provider. The HTTP client comes through the factory's constructor, never created inside.
• the provider implements the contracts it can answer - EventCatalogInterface, AttendeeListInterface, TicketCheckInterface - and says so in capabilities(), with the terms and the rate limits the service states.
• calls go through Http\JsonApi (failures become the family's exceptions) and answers are read with Support\Data; a listing passes what the API can filter on and returns $query->filter(...), so the core applies the whole query.
• a check reads: it never marks a ticket as scanned. Without a lookup by code, Check::among() over the attendees.
• an Attendee per ticket, cancelled and refunded ones included (their status says so); money in minor units (Money::fromMajor() when the API gives units); an unknown remainder is null.
• tests run in the core's harness (docker/harness/plugins.php lists the providers) with recorded answers - from the service's documentation when it publishes examples, said so in the test - and a BareTest (Testing\LoadCheck); a LiveTest (group live) only for what needs no account.

A skeleton

namespace Omniticket\Example;

use Omniticket\Capabilities;
use Omniticket\Config;
use Omniticket\EventCatalogInterface;
use Omniticket\Exception\InvalidConfigException;
use Omniticket\Http\JsonApi;
use Omniticket\Model\Event;
use Omniticket\Model\EventQuery;
use Omniticket\ProviderFactory;
use Omniticket\ProviderInterface;
use Omniticket\Support\Data;
use Symfony\Contracts\HttpClient\HttpClientInterface;

final class ExampleFactory extends ProviderFactory
{
    public function __construct(private readonly ?HttpClientInterface $http = null)
    {
    }

    protected function populate(Config $c): void
    {
        $c->defaults(['omniticket.factory_name' => 'example', 'omniticket.factory_title' => 'Example', 'omniticket.required_options' => ['api_key']]);
    }

    protected function build(Config $c): ProviderInterface
    {
        return new ExampleProvider($this->http ?? throw new InvalidConfigException('The "example" provider needs an HTTP client.'), (string) $c->string('api_key'));
    }
}

final class ExampleProvider implements EventCatalogInterface
{
    private readonly JsonApi $api;

    public function __construct(HttpClientInterface $http, #[\SensitiveParameter] private readonly string $apiKey)
    {
        $this->api = new JsonApi($http, 'Example');
    }

    public function getName(): string { return 'example'; }

    public function getTitle(): string { return 'Example'; }

    public function capabilities(): Capabilities
    {
        return new Capabilities(catalog: true, terms: ['https://example.org/terms'], limits: ['what the service states']);
    }

    public function events(EventQuery $query = new EventQuery()): iterable
    {
        $answer = $this->api->request('GET', 'https://api.example.org/events', ['query' => ['key' => $this->apiKey]], 'the events');

        return $query->filter(array_map($this->toEvent(...), $answer->list('events')));
    }

    public function event(string $id): Event
    {
        return $this->toEvent($this->api->request('GET', 'https://api.example.org/events/'.rawurlencode($id), ['query' => ['key' => $this->apiKey]], 'event "'.$id.'"'));
    }

    private function toEvent(Data $line): Event
    {
        return new Event((string) $line->string('id'), $line->string('title') ?? '', $line->date('start'), provider: 'example');
    }
}

The address and the fields are placeholders. Each provider's own manual lists its calls, the mapping of its statuses and what it does not read.

What the five providers keep to

• The HTTP client injected, never created: a factory without one refuses to build.
• Credentials as #[\SensitiveParameter] constructor arguments.
• Listings returned through $query->filter(); where the API pages (HelloAsso, Eventbrite, Ticketmaster), pages fetched as the iteration goes (a generator), so a limit stops the paging.
• Dates read in the service's zone when it gives local times (Billetweb, Weezevent: the timezone option); prices in the currency it names, or the currency option.
• Nothing written: no check marks a ticket as scanned.

Verified, and not

What the tests prove

Run on 2026-10-26 in the harness, every package from its checkout, PHP 8.4, the live group left out, no network: 50 tests, 200 assertions, green.

• The core: the models (money in minor units, availability, statuses, checks), the query's filter, the registry and its errors, JsonApi's mapping of statuses to exceptions; in plain PHP, events listed, read, attendees and codes checked through a registry and a recorded JSON API, loading nothing but omniticket and Symfony's HTTP client contracts (BareTest).
• Each provider, every class loading with its requirements alone (BareTest, LoadCheck), and: Billetweb's and Weezevent's calls against the examples of their own documentation, as published; HelloAsso's, Eventbrite's and Ticketmaster's against answers composed from their documented fields, not recorded - each provider's README says which. Events and their statuses, one event whole (rates, sessions, places left), attendees (incrementally where the provider allows), checks valid, already used, refunded and unknown, a refused key.

The examples of this manual (the installation script on Billetweb, the error messages, the testing page, the bare script) were run in the harness on 2026-10-26.

What was run live

Per the READMEs, on 2026-10-24 (docker compose run --rm omniticket live): Weezevent's public endpoint, GET /event/categories, no key - its host and its JSON. Not run again for this manual.

What is not verified

• Every call that needs an account or a key: all five providers' events, attendees and checks.
• Whether Weezevent cuts a very large participant list without paging (max and page are documented without their base).
• Eventbrite's response shapes were not re-read on 2026-10-24, nor its rate figures.
• The Symfony and Laravel pages were written from the classes' constructors, not run in an application.

Responsibility

omnisense/omniticket and its omniticket/* providers are unofficial clients, affiliated with none of the services they reach. The MIT licence covers the code only and grants no right to any service or its data; whoever runs them complies with each service's terms and limits (named in each provider's README and in Capabilities::$terms and $limits). Attendees' names and e-mails are personal data: keep and show them as the organizer's own rules and the law allow.