README

PHP extension that maps PostgreSQL result rows straight into typed PHP objects. PHP 8.5+, ext/pgsql results.

Features

• Typed values — int, float, bool, DateTimeImmutable and backed enums, not strings
• JSON and arrays — jsonb and int4[]/text[]… straight into PHP arrays, 3.6–16.0x faster than decoding in PHP
• Nested objects — "address.city" columns fill $row->address->city
• Constructors — promoted-only constructors cost 100 ns/row vs 88 ns/row for a plain DTO
• Speed — 88 ns/row vs 524 ns/row for the same mapping in PHP

Install

bash build-install.sh

Needs gcc, make, PHP dev headers, libpq and yyjson headers, and ext/pgsql. The script names any missing package for your distro (yyjson-devel / libyyjson-dev).

IDE stubs:

composer require --dev fluffydiscord/fast-pgsql-mapper-stubs

Usage

1. src/AccountRow.php

   readonly class AccountRow
   {
       public int $id;
       public string $login;
       public ?DateTimeImmutable $updatedAt;
   }

2. Query and map:

   $result = pg_query($connection, 'SELECT id, login, update_ts AS "updatedAt" FROM account');
   
   /** @var list<AccountRow> $rows */
   $rows = pg_fast_query($result, AccountRow::class);

Columns match properties by name. Public, protected and private all work, at the same speed.

Type mapping

Some types depend on the property type. Otherwise they stay string:

A property that also accepts string (string|array, untyped) gets the raw string.

Value doesn't fit the property → normal PHP assignment (coercive mode):

Datetime

Type a property as a DateTimeImmutable subclass to get that class:

public ?\Carbon\CarbonImmutable $createdAt; // CarbonImmutable, not DateTimeImmutable

• The subclass constructor isn't called.
• Subclass with its own required typed property and no default → that property stays uninitialized. Don't use one here.
• Internal subclass with a different object layout → plain DateTimeImmutable.

date → midnight UTC, whatever date.timezone says: 2025-01-02 → 2025-01-02T00:00:00+00:00.

Unparsed values → null (TypeError on a non-nullable property): infinity, -infinity, BC timestamp without zone, any DateStyle other than ISO.

timestamptz in ISO DateStyle (the default) skips PHP's generic date parser: 6.8x faster than new DateTimeImmutable() (benchmark).

Backed enums

Type a property as a backed enum to get the case:

enum Status: string { case Active = 'active'; case Ended = 'ended'; }

readonly class Row
{
    public Status $status;   // 'active' → Status::Active
    public ?Status $maybe;   // NULL → null
}

• String-backed ← text columns. Int-backed ← integer columns. Other pairs → raw value.
• Unknown value → ValueError, same as Status::from().
• Pure (non-backed) enums aren't mapped.

JSON and arrays

Type the property as array:

readonly class Product
{
    public array $attributes;  // jsonb '{"color": "red", "sizes": [1, 2]}' → ['color' => 'red', 'sizes' => [1, 2]]
    public array $tagIds;      // int4[] '{1,2,NULL}' → [1, 2, null]
    public ?array $labels;     // text[] '{"a b",c}' → ['a b', 'c']
}

• json/jsonb → same as json_decode($value, true, 512, JSON_THROW_ON_ERROR). Invalid JSON (e.g. non-UTF-8 client_encoding) or 512+ levels deep → JsonException, even on a nullable property.
• JSON scalar ("text", 42) → TypeError.
• Elements convert like columns: int4[] → int, float8[] → float, bool[] → bool, timestamptz[] → DateTimeImmutable, anything else → string.
• Multi-dimensional → nested lists. Custom bounds ([0:2]={…}) → 0-based list.
• text column holding '{a,b}' → ['a', 'b'].
• Unions like bool|array keep scalar columns as they are.

Nested objects

Name columns with a dot path:

SELECT id, price AS "nested.price", created_at AS "nested.createdAt" FROM orders

readonly class Nested
{
    public int $price;
    public ?DateTimeImmutable $createdAt;
}

readonly class Order
{
    public int $id;
    public Nested $nested;
}

• Up to 8 levels. Deeper → column ignored.
• Nested objects are created without calling their constructor.
• Interface or abstract-class properties aren't created; the column goes through normal assignment.

Single-value objects need no dot path. A column named after a class-typed property fills that class's first declared property:

readonly class Email
{
    private ?string $email;

    public function isValid(): bool
    {
        return $this->email !== null;
    }
}

readonly class User
{
    public Email $email;   // SELECT email FROM users → $user->email->isValid()
}

Constructors

Constructor args get raw values: enum, date, JSON, array and DateTimeImmutable subclass mapping don't apply. Columns the constructor doesn't take are written after it runs.

Not covered:

• Nesting, enum or subclass mapping through union or intersection types
• JSON objects as stdClass (always arrays)
• box[] (uses ; between elements) → raw string
• Nesting below a class with __set or a custom object handler

Benchmark

php test_performance.php: 5000 rows, best of 10 runs, PHP 8.5.12 CLI without opcache. Every PHP baseline calls pg_fetch_assoc per row inside the timed loop.

Mapping into a plain DTO is faster than pg_fetch_assoc returning plain arrays.

Real project

wrk -t4 -c12 -d20s --latency, baseline raw-pg.

Measured with v1.1.0 or earlier.

• raw-pg — pg_query_params() + pg_fetch_all(), plain arrays.
• raw-dto — pg_fetch_assoc() loop, each row mapped through a PHP constructor.
• pg-fast — pg_query() + pg_fast_query().
• pg-fast-inh — same, into a child class; both classes have constructors.
• cycle — Cycle ORM Select + fetchAll(), identity map.
• doctrine — Doctrine findBy(), lazy loading and identity map.