Download the PHP package vt-parhomenko/olx-ua-api-sdk without Composer

OLX Partner API — PHP SDK

A lightweight PHP client for the OLX Partner REST API. It wraps authentication (OAuth2), request signing, response parsing and error handling behind a small, fluent facade.

Supports OLX in Ukraine, Poland, Bulgaria, Romania, Kazakhstan and Portugal.

Requirements

• PHP 8.1+
• guzzlehttp/guzzle ^7.5

Installation

Quick start

OlxFactory::get() accepts either a Country enum case (recommended) or a plain country code string ('ua', 'pl', 'bg', 'ro', 'kz', 'pt'). An unknown country throws Parhomenko\Olx\Exceptions\UnknownCountryException.

The third argument, $update_token, when true, checks the token on construction and transparently refreshes it via the refresh token if it is expired.

HTTP client options

The optional fourth argument, $httpOptions (since 3.1), is passed to the underlying Guzzle client and applies to every request — resource calls as well as the OAuth token requests. By default no options are set, and Guzzle then waits indefinitely for a response, so setting at least timeout and connect_timeout is strongly recommended for queue workers and other long-running processes.

The same array can be passed to new Api($baseUri, $credentials, $update_token, $httpOptions). A base_uri key in the options is ignored: the base URI of the selected country (or the $baseUri argument of Api) always wins. A timeout surfaces as GuzzleHttp\Exception\ConnectException (a GuzzleException), not as an OLX exception.

Authentication (OAuth2)

Only client_id and client_secret are strictly required. The full credential set is:

Note: store expires_in whenever you store an access_token. If you supply an access_token and updated_at but omit expires_in, the token is treated as already expired and refreshed on the first call (which needs a valid refresh_token). Prefer persisting the value returned by Authenticator::getTokenUpdatedAt() for updated_at — it is offset-aware, so expiry is evaluated correctly even when tokens are stored and read on hosts with different timezones.

Authorization code flow

Refreshing tokens

A failed refresh throws Parhomenko\Olx\Exceptions\RefreshTokenException (use getError() / getErrorDescription() for OLX error details).

Client credentials (no user context)

For read-only access to public catalog data (categories, cities, currencies, …) without a user, authenticate with the client_credentials grant:

Note: this grant cannot create or manage adverts — use the authorization code flow for user-scoped actions.

Resources

Every resource is reached through the facade, e.g. $olx->adverts(). List endpoints return the decoded data payload as an array; command endpoints return void and throw a Parhomenko\Olx\Exceptions\BaseOlxException on failure.

Adverts — $olx->adverts()

Categories — $olx->categories()

Locations

Reference data

Users — $olx->users()

Packets — $olx->packets()

Paid features — $olx->paidFeatures()

Business profile — $olx->usersBusiness()

Threads & messages

Payments & error handling

To avoid the payment errors described in the OLX docs (insufficient credits, invalid payment method, missing packet variant), check state before purchasing:

Error handling

Every HTTP error is mapped to a typed exception. All of them extend Parhomenko\Olx\Exceptions\BaseOlxException and expose getTitle() and getDetail().

Supported countries

The Parhomenko\Olx\Country enum is the single source of truth:

Upgrading from 2.x to 3.0

3.0 is a breaking release. The most common migrations:

1. PHP 8.1+ is now required

The minimum supported version moved from PHP 7.0 to 8.1 (the Country enum relies on it).

2. OlxFactory::get() signature

The first parameter was renamed $country_code → $country and is now typed string|Country. Only named-argument calls (get(country_code: 'ua')) need updating to get(country: 'ua').

3. Typed exceptions everywhere

In 2.x several resources (categories, cities, regions, districts, currencies, languages, users, threads, messages) let raw GuzzleHttp\Exception\* propagate. In 3.0 all resources throw the typed Parhomenko\Olx\Exceptions\* hierarchy (see the table above). Replace any catch (GuzzleHttp\Exception\ClientException ...) around these calls with the relevant OLX exception (or the BaseOlxException base type).

4. Advert deletion changed

delete_notactive() was removed; delete() now performs a single DELETE request and no longer deactivates the advert first.

5. Thread methods renamed to camelCase

The snake_case thread methods mark_as_read(), set_favourite() and unset_favourite() were removed. Use the camelCase equivalents markAsRead(), setFavourite() and unsetFavourite().

6. Messages::get() now paginates

offset / limit arguments were previously ignored and are now sent to the API. If you relied on always receiving the first page, pass the arguments explicitly.

7. New facade accessors

$olx->threads() and $olx->messages() are now reachable from the facade (the classes existed in 2.x but could not be obtained through Api).

8. Authentication via authenticator()

The OAuth/token class is Parhomenko\Olx\Api\Authenticator (it handles authentication, not user data — that is the separate Users resource), reached through $olx->authenticator():

9. OlxApiInterface

The facade interface is OlxApiInterface (no Hungarian I prefix). Replace any IOlxApi type hints with OlxApiInterface.

10. Command methods return void

Methods that signal success/failure (and previously returned an always-true bool) now return void and throw a BaseOlxException on failure: Adverts::activate/deactivate/delete/deleteStatistic/deleteLogo, all Threads command methods, and UsersBusiness::deleteLogo/deleteBanner.

11. Credentials value object (optional)

Credentials may be passed as a typed Parhomenko\Olx\Credentials object; the associative-array form still works (normalised via Credentials::fromArray()):

Development

License

MIT