Download the PHP package gosuccess/easybill-api without Composer

easybill API – PHP Client

A modern, strongly-typed, dependency-free PHP client for the easybill REST API, built for PHP 8.4+ with first-class rate-limit handling.

Features

• PHP 8.4+, fully typed final readonly DTOs and native enums for every API model.
• Zero Composer dependencies — ships with a self-contained cURL transport (only the ext-curl and ext-json PHP extensions are required).
• Pluggable transport: implement the small HttpClient interface to route requests through your own HTTP stack (e.g. Guzzle) — without the library depending on it.
• Built-in rate limiting. easybill currently allows 10 or 60 requests/minute and does not reliably advertise the limit in response headers. The client therefore throttles requests proactively and the limit is freely configurable.
• Automatic retry with exponential backoff on 429 / transient errors, honoring Retry-After when the API provides it.
• Typed exception hierarchy for every documented HTTP error.
• Lazy pagination over all result pages.

Requirements

• PHP 8.4 or higher
• ext-curl and ext-json

Installation

Quick start

Partial updates and clearing fields

Models serialize only what you actually passed, so an update touches nothing else. Because of that, a field you leave out and a field you set to null must mean two different things:

To make a field conditional, fall back to the Undefined sentinel — the default of every writable parameter — instead of null:

Reading is unaffected: properties stay plainly typed (?string, list<string>), never sentinel-valued. A model returned by the API carries no intent to clear anything, so passing one straight back never nulls out fields.

Pagination

Each list endpoint offers list() for a single page and all() for a lazy iterator over every page (each page request is rate-limited automatically). Filters are strongly typed per endpoint:

Rate limiting

The request limit is configured via ClientConfig::$requestsPerMinute. The default SlidingWindowRateLimiter keeps the client below that threshold so you avoid 429 responses entirely. You can swap in your own implementation of the RateLimiter interface (for example a Redis-backed limiter shared across processes):

Error handling

Every error thrown by the library implements GoSuccess\Easybill\Exception\EasybillException:

Custom transport

Bring your own HTTP client by implementing HttpClient:

Documentation & examples

• docs/ — a reference page for every resource method (endpoint, signature, parameters and a usage example).
• examples/ — runnable example scripts (CRUD, pagination, documents, error handling, rate limiting, custom transport).

Available resources

customers, contacts, customerGroups, documents, documentPayments, positions, positionGroups, discountPositions, discountPositionGroups, projects, tasks, textTemplates, timeTrackings, attachments, postBoxes, sepaPayments, serialNumbers, stocks, logins, webhooks, pdfTemplates.

Development

The data models, enums and filter objects are generated from a committed snapshot of the official Swagger specification (resources/swagger.json), and the plain resource classes from a declarative config:

To refresh against the live API, update the snapshot first and then rerun the generators above:

CI regenerates everything and fails if the committed output is out of date.

Running the test suite additionally requires the dom, xml, xmlwriter, mbstring and tokenizer PHP extensions (PHPUnit dependencies).

License

MIT