PHPackages                             passendo/openrtb-php - 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. passendo/openrtb-php

ActiveLibrary[API Development](/categories/api)

passendo/openrtb-php
====================

A modern, PSR-4 compliant PHP library for OpenRTB specifications 2.5, 2.6, and 3.0.

v3.0.6(6mo ago)1428↑13.3%GPL-3.0-or-laterPHPPHP >=8.1CI passing

Since Oct 13Pushed 6mo agoCompare

[ Source](https://github.com/pssndo/openrtb-php)[ Packagist](https://packagist.org/packages/passendo/openrtb-php)[ RSS](/packages/passendo-openrtb-php/feed)WikiDiscussions master Synced today

READMEChangelog (9)Dependencies (3)Versions (12)Used By (0)

OpenRTB for PHP
===============

[](#openrtb-for-php)

[![Latest Version](https://camo.githubusercontent.com/94b33e523f85cc0de6e03a00263c927a17539065d787eebaff0285e76198b4a2/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f70617373656e646f2f6f70656e7274622d7068702e737667)](https://packagist.org/packages/passendo/openrtb-php)[![Run PHPUnit Tests](https://github.com/pssndo/openrtb-php/actions/workflows/ci.yml/badge.svg)](https://github.com/pssndo/openrtb-php/actions/workflows/ci.yml)[![Code Coverage](.github/badges/coverage.svg?v=2)](.github/badges/coverage.svg?v=2)[![License: GPL v3](https://camo.githubusercontent.com/48bf9b56d44f38db53ce21294cf0b9487d0a3734ab3ba1fe4c69858ae20db2c1/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f4c6963656e73652d47504c76332d626c75652e737667)](https://www.gnu.org/licenses/gpl-3.0)

A modern, PSR-4 compliant PHP library for the OpenRTB 2.5, 2.6, and 3.0 specifications. This library provides an intuitive, object-oriented interface for building and parsing OpenRTB requests and responses, complete with robust validation and a fluent API.

Key Features
------------

[](#key-features)

- **Fluent Builder Pattern**: Construct complex OpenRTB requests and responses with an expressive, chainable API.
- **Object-Oriented**: Maps all OpenRTB entities to clean, well-structured PHP objects.
- **JSON Serialization**: Easily serialize request and response objects to JSON.
- **JSON Deserialization**: Hydrate JSON strings back into their corresponding PHP objects with a powerful `Parser`.
- **Request/Response Validation**: A `Validator` utility to ensure your objects conform to the OpenRTB specification before serialization.
- **Modern PHP**: Built for PHP 8.0+ with strict typing and modern development practices.
- **PSR-4 Autoloading**: Compliant with modern PHP standards for easy integration.

Installation
------------

[](#installation)

Install the library via [Composer](https://getcomposer.org/):

```
composer require passendo/openrtb-php
```

Usage
-----

[](#usage)

The library uses a Factory pattern for clean, version-agnostic code. This is the recommended approach.

> **Note:** For more detailed and advanced use cases, please refer to the [Examples](#examples) section below.

### Creating a Bid Request (Recommended: Factory Pattern)

[](#creating-a-bid-request-recommended-factory-pattern)

Use `OpenRTBFactory` to automatically handle version-specific builders and parsers:

```
use OpenRTB\Factory\OpenRTBFactory;
use OpenRTB\v25\Context\Site;
use OpenRTB\v25\Context\Device;
use OpenRTB\v25\Impression\Imp;
use OpenRTB\v25\Impression\Banner;
use OpenRTB\v25\Enums\AuctionType;

// Create factory for your OpenRTB version
$factory = new OpenRTBFactory('2.5'); // or '2.6', '3.0'

// Build request using fluent API
$request = $factory
    ->createRequestBuilder()
    ->setId(uniqid('', true))
    ->setTest(0)
    ->setAt(AuctionType::FIRST_PRICE)
    ->setTmax(250)
    ->setCur(['USD'])
    ->setBcat(['IAB25', 'IAB26'])
    ->setSite((new Site())
        ->setId('site-123')
        ->setDomain('example.com'))
    ->setDevice((new Device())
        ->setUa('Mozilla/5.0...')
        ->setIp('192.168.1.1'))
    ->addImp((new Imp())
        ->setId('imp-1')
        ->setBanner((new Banner())
            ->setW(300)
            ->setH(250))
        ->setBidfloor(1.50))();  // Call __invoke() to get the request

// Serialize to JSON
$jsonRequest = $request->toJson();
echo $jsonRequest;
```

**Complex Example with Context:**

```
use OpenRTB\v3\Util\RequestBuilder;
use OpenRTB\v3\Impression\Item;
use OpenRTB\v3\Impression\Spec;
use OpenRTB\v3\Placement\Placement;
use OpenRTB\v3\Placement\VideoPlacement;
use OpenRTB\v3\Enums\Placement\Linearity;
use OpenRTB\v3\Context\Context;
use OpenRTB\v3\Context\Device;

// Define a video placement
$videoPlacement = (new VideoPlacement())
    ->setLinear(Linearity::LINEAR)
    ->setMindur(5)
    ->setMaxdur(30);

$placement = (new Placement())->setVideo($videoPlacement);
$spec = (new Spec())->setPlacement($placement);
$item = (new Item())->setId('video-item-1')->setSpec($spec);

// Define device and user context
$device = (new Device())->setIp('192.168.1.1')->setUa('Mozilla/5.0...');
$context = (new Context())->setDevice($device);

// Build the request
$builder = new RequestBuilder();
$request = $builder
    ->setId('complex-request-789')
    ->addItem($item)
    ->setContext($context)
    ->build();

echo $request->toJson();
```

### Parsing Bid Responses

[](#parsing-bid-responses)

Use the Factory's parser to convert JSON responses into typed objects:

```
// Parse response from exchange/SSP
$responseJson = file_get_contents('php://input');
$response = $factory->createParser()->parseBidResponse($responseJson);

// Access typed data
foreach ($response->getSeatbid() as $seatbid) {
    foreach ($seatbid->getBid() as $bid) {
        echo "Bid Price: " . $bid->getPrice() . "\n";
        echo "Creative ID: " . $bid->getCrid() . "\n";
    }
}
```

### Version Detection by Provider

[](#version-detection-by-provider)

Automatically use the correct OpenRTB version for your exchange:

```
// Automatically uses OpenRTB 3.0 for Epom
$factory = OpenRTBFactory::forProvider('epom');

// Automatically uses OpenRTB 2.6 for Google
$factory = OpenRTBFactory::forProvider('google');

// Build request with the right version automatically
$request = $factory
    ->createRequestBuilder()
    ->setId(uniqid('', true))
    // ... your configuration
    ();
```

### Validation

[](#validation)

Validate requests before sending:

```
$validator = $factory->createValidator();

if (!$validator->validateBidRequest($request)) {
    $errors = $validator->getErrors();
    foreach ($errors as $error) {
        echo "Error: $error\n";
    }
}
```

Examples
--------

[](#examples)

The `examples/v3` directory contains a variety of scripts demonstrating how to use the library for common use cases.

- **Building Requests:**
    - [Simple App Banner Request](examples/v3/build_app_banner_request.php)
    - [Display Banner Request](examples/v3/build_display_banner_request.php)
    - [Video Request](examples/v3/build_video_request.php)
    - [DOOH Request](examples/v3/build_dooh_request.php)
    - [Multi-Item Request](examples/v3/build_multi_item_request.php)
    - [Native Ad Request](examples/v3/build_native_ad_request_and_response.php)
- **Building Responses:**
    - [Simple Bid Response](examples/v3/build_bid_response.php)
    - [Video Response](examples/v3/build_video_response.php)
    - [No-Bid Response](examples/v3/build_no_bid_response.php)
- **Parsing and Validation:**
    - [Parse and Validate a Request](examples/v3/parse_and_validate_request.php)
- **Integration Example:**
    - [Full SSP Integration Example](examples/v3/ssp_integration_example.php)

Project Structure
-----------------

[](#project-structure)

The project is organized by OpenRTB specification version. All classes for a specific version are located within their own versioned namespace and directory.

- `src/v3/`: Contains all classes for OpenRTB 3.0
- `src/v26/`: Contains all classes for OpenRTB 2.6
- `src/v25/`: Contains all classes for OpenRTB 2.5
- `tests/`: Contains the unit tests, mirroring the `src` directory structure
- `examples/`: Contains comprehensive usage examples for all versions

Running Tests
-------------

[](#running-tests)

To ensure the library is working correctly, run the full PHPUnit test suite from the project root:

```
./vendor/bin/phpunit
```

Contributing
------------

[](#contributing)

Contributions are welcome! Please feel free to submit a pull request.

1. Fork the repository.
2. Create a new feature branch (`git checkout -b feature/my-new-feature`).
3. Commit your changes (`git commit -am 'Add some feature'`).
4. Push to the branch (`git push origin feature/my-new-feature`).
5. Create a new Pull Request.

License
-------

[](#license)

This library is open-source software licensed under the **GNU General Public License v3.0**. See the [LICENSE](LICENSE) file for more details.

###  Health Score

39

—

LowBetter than 84% of packages

Maintenance66

Regular maintenance activity

Popularity18

Limited adoption so far

Community9

Small or concentrated contributor base

Maturity51

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 91.4% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~7 days

Recently: every ~0 days

Total

10

Last Release

199d ago

Major Versions

v1.0.1 → v2.02025-11-05

v2.0 → v3.02025-11-10

v2.5.x-dev → v3.0.62025-12-15

PHP version history (2 changes)v1.0.0PHP >=8.0

v2.0PHP >=8.1

### Community

Maintainers

![](https://www.gravatar.com/avatar/54aa8753ce0c28bbf8712f271eabbb4694130cc99c0d0cb8806d15d9838a3223?d=identicon)[darkopassendo](/maintainers/darkopassendo)

---

Top Contributors

[![darkopassendo](https://avatars.githubusercontent.com/u/116717302?v=4)](https://github.com/darkopassendo "darkopassendo (64 commits)")[![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?v=4)](https://github.com/github-actions[bot] "github-actions[bot] (5 commits)")[![actions-user](https://avatars.githubusercontent.com/u/65916846?v=4)](https://github.com/actions-user "actions-user (1 commits)")

###  Code Quality

TestsPHPUnit

Static AnalysisPHPStan

Code StylePHP CS Fixer

Type Coverage Yes

### Embed Badge

![Health badge](/badges/passendo-openrtb-php/health.svg)

```
[![Health](https://phpackages.com/badges/passendo-openrtb-php/health.svg)](https://phpackages.com/packages/passendo-openrtb-php)
```

###  Alternatives

[exsyst/swagger

A php library to manipulate Swagger specifications

35916.4M7](/packages/exsyst-swagger)[hubspot/api-client

Hubspot API client

24016.2M20](/packages/hubspot-api-client)[pocketmine/bedrock-protocol

An implementation of the Minecraft: Bedrock Edition protocol in PHP

172445.0k13](/packages/pocketmine-bedrock-protocol)[botman/driver-telegram

Telegram driver for BotMan

93459.5k6](/packages/botman-driver-telegram)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)