Protocol Buffers

suggest change

Protocol Buffers (protobuf) is Google's language-neutral format for structured data. You describe messages once in a .proto file, run the protoc compiler to generate classes for each language, and use those classes to encode data into a compact binary form (or into JSON).

Compared to JSON or PHP's own serialize():

PHP needs two things: the protoc compiler (to generate code) and the google/protobuf runtime library (to encode and decode).

Setup

Install the runtime with Composer:

composer require google/protobuf

This installs a pure PHP implementation. For production you can also install the C extension (pecl install protobuf, then extension=protobuf in php.ini). It implements the same API and is much faster; when it's loaded, the extension is used and the PHP classes from the package are ignored.

Get protoc from your package manager (apt install protobuf-compiler, brew install protobuf) or download a release from https://github.com/protocolbuffers/protobuf/releases. The examples here were run with protoc 36.2 and google/protobuf 5.36.2 on PHP 8.5.

Defining messages

Save this as proto/acme/shop/v1/order.proto:

syntax = "proto3";

package acme.shop.v1;

import "google/protobuf/timestamp.proto";

enum OrderStatus {
  ORDER_STATUS_UNSPECIFIED = 0;
  ORDER_STATUS_PENDING = 1;
  ORDER_STATUS_PAID = 2;
  ORDER_STATUS_SHIPPED = 3;
}

message LineItem {
  string sku = 1;
  int32 quantity = 2;
  int64 price_cents = 3;
}

message Order {
  int64 id = 1;
  string customer_email = 2;
  OrderStatus status = 3;
  repeated LineItem items = 4;
  map<string, string> labels = 5;
  google.protobuf.Timestamp created_at = 6;
  optional string coupon_code = 7;

  oneof payment {
    string card_token = 10;
    string invoice_number = 11;
  }
}

The number after each field (= 1, = 2) is the field's identity on the wire. Names can be changed freely later, numbers can't.

Generating PHP code

protoc --proto_path=proto --php_out=gen proto/acme/shop/v1/order.proto

This creates one class per message and enum, plus a metadata class that holds the compiled schema:

gen/Acme/Shop/V1/LineItem.php
gen/Acme/Shop/V1/Order.php
gen/Acme/Shop/V1/OrderStatus.php
gen/GPBMetadata/Acme/Shop/V1/Order.php

The PHP namespace is derived from the package (acme.shop.v1 becomes Acme\Shop\V1). To choose it yourself, add option php_namespace = "MyApp\\Proto"; and option php_metadata_namespace = "MyApp\\Proto\\Meta"; to the .proto file (backslashes are escaped inside proto strings).

google/protobuf/timestamp.proto is a well-known type: protoc ships it, and its PHP class Google\Protobuf\Timestamp is part of the runtime package, so nothing is generated for it.

The generated files follow PSR-4, so register them in composer.json and run composer dump-autoload:

{
    "require": {
        "google/protobuf": "^5.36"
    },
    "autoload": {
        "psr-4": {
            "Acme\\": "gen/Acme/",
            "GPBMetadata\\": "gen/GPBMetadata/"
        }
    }
}

Generated code is a build artifact. Either commit it, or regenerate it in CI; just don't edit it by hand.

Building and serializing a message

Each field gets a getter and a setter. Setters return $this, so they can be chained:

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

use Acme\Shop\V1\LineItem;
use Acme\Shop\V1\Order;
use Acme\Shop\V1\OrderStatus;
use Google\Protobuf\Timestamp;

$created = new Timestamp();
$created->fromDateTime(new DateTime('2026-10-17 09:30:00', new DateTimeZone('UTC')));

$order = new Order();
$order->setId(1001)
    ->setCustomerEmail('ann@example.com')
    ->setStatus(OrderStatus::ORDER_STATUS_PAID)
    ->setItems([
        new LineItem(['sku' => 'BOOK-PHP', 'quantity' => 1, 'price_cents' => 2999]),
        new LineItem(['sku' => 'MUG', 'quantity' => 2, 'price_cents' => 1250]),
    ])
    ->setLabels(['channel' => 'web', 'region' => 'eu'])
    ->setCreatedAt($created)
    ->setCardToken('tok_4242');

$bytes = $order->serializeToString();
echo "binary size: ", strlen($bytes), " bytes\n";
echo "hex: ", bin2hex(substr($bytes, 0, 24)), "...\n";

$json = $order->serializeToJsonString();
echo "json size: ", strlen($json), " bytes\n";
echo $json, "\n";

Output:

binary size: 99 bytes
hex: 08e907120f616e6e406578616d706c652e636f6d1802220f...
json size: 284 bytes
{"id":"1001","customerEmail":"ann@example.com","status":"ORDER_STATUS_PAID","items":[{"sku":"BOOK-PHP","quantity":1,"priceCents":"2999"},{"sku":"MUG","quantity":2,"priceCents":"1250"}],"labels":{"channel":"web","region":"eu"},"createdAt":"2026-10-17T09:30:00Z","cardToken":"tok_4242"}

Things to notice:

Most of the following examples reuse that order, through a makeOrder() helper that builds it with the array constructor.

Parsing a message

Create an empty message and merge bytes into it:

<?php
require __DIR__ . '/vendor/autoload.php';
require __DIR__ . '/make_order.php';

use Acme\Shop\V1\Order;
use Acme\Shop\V1\OrderStatus;

$bytes = makeOrder()->serializeToString();

$order = new Order();
$order->mergeFromString($bytes);

echo "id:     ", $order->getId(), "\n";
echo "email:  ", $order->getCustomerEmail(), "\n";
echo "status: ", OrderStatus::name($order->getStatus()), "\n";

$total = 0;
foreach ($order->getItems() as $item) {
    $line = $item->getQuantity() * $item->getPriceCents();
    $total += $line;
    printf("  %-8s x%d  %6.2f\n", $item->getSku(), $item->getQuantity(), $line / 100);
}
printf("total:  %.2f\n", $total / 100);

foreach ($order->getLabels() as $key => $value) {
    echo "label $key = $value\n";
}

echo "items count: ", count($order->getItems()), "\n";
echo "created: ", $order->getCreatedAt()->toDateTime()->format(DATE_ATOM), "\n";
var_dump($order->getId());

Output:

id:     1001
email:  ann@example.com
status: ORDER_STATUS_PAID
  BOOK-PHP x1   29.99
  MUG      x2   25.00
total:  54.99
label channel = web
label region = eu
items count: 2
created: 2026-10-17T09:30:00+00:00
int(1001)

As the name says, mergeFromString() merges: scalar fields are overwritten, but repeated fields are appended to. Always parse into a fresh object (or call clear() first).

Enums are plain integer constants. OrderStatus::name() turns a value into its name and OrderStatus::value('ORDER_STATUS_PAID') does the reverse. Both throw UnexpectedValueException for unknown input. Code that receives messages from a newer client should be prepared for enum values it doesn't know.

On 64-bit PHP, int64 fields are returned as int. On 32-bit builds they come back as numeric strings, which is why the setters accept int|string.

Default values and field presence

proto3 has no null for scalars. A field that was never set returns its default value: 0, "", false, or the enum value 0. That's why every enum should start with an ..._UNSPECIFIED = 0 entry.

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

use Acme\Shop\V1\Order;

$order = new Order();

// Scalars without "optional" have no presence: unset means default
var_dump($order->getId(), $order->getCustomerEmail(), $order->getStatus());

// Message fields and "optional" scalars track presence
var_dump($order->hasCreatedAt(), $order->getCreatedAt());
var_dump($order->hasCouponCode(), $order->getCouponCode());

$order->setCouponCode('');          // explicitly set to empty string
var_dump($order->hasCouponCode());  // still true
$order->clearCouponCode();
var_dump($order->hasCouponCode());

// Default values are not written to the wire at all
echo "empty order: ", strlen($order->serializeToString()), " bytes\n";
$order->setId(0)->setCustomerEmail('');
echo "zeros set:   ", strlen($order->serializeToString()), " bytes\n";

Output:

int(0)
string(0) ""
int(0)
bool(false)
NULL
bool(false)
string(0) ""
bool(true)
bool(false)
empty order: 0 bytes
zeros set:   0 bytes

Rules worth remembering:

oneof

At most one field of a oneof group is set at a time. The generated getPayment() method returns the name of the field that is set, or an empty string:

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

use Acme\Shop\V1\Order;

$order = new Order();
echo "payment: '", $order->getPayment(), "'\n";

$order->setCardToken('tok_4242');
echo "payment: ", $order->getPayment(), " card=", $order->getCardToken(), "\n";

// Setting another member of the oneof clears the previous one
$order->setInvoiceNumber('INV-2026-0042');
echo "payment: ", $order->getPayment(), "\n";
var_dump($order->hasCardToken(), $order->getCardToken());

switch ($order->getPayment()) {
    case 'card_token':
        echo "charge card ", $order->getCardToken(), "\n";
        break;
    case 'invoice_number':
        echo "send invoice ", $order->getInvoiceNumber(), "\n";
        break;
    default:
        echo "no payment method\n";
}

Output:

payment: ''
payment: card_token card=tok_4242
payment: invoice_number
bool(false)
string(0) ""
send invoice INV-2026-0042

Repeated and map fields

repeated fields are Google\Protobuf\RepeatedField objects and map fields are MapField objects. Both implement ArrayAccess, IteratorAggregate and Countable, but they are not PHP arrays and they check the types of their elements:

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

use Acme\Shop\V1\LineItem;
use Acme\Shop\V1\Order;

$order = new Order();

// RepeatedField and MapField behave like arrays
$order->getItems()[] = new LineItem(['sku' => 'PEN', 'quantity' => 3, 'price_cents' => 150]);
$order->getItems()[] = new LineItem(['sku' => 'INK', 'quantity' => 1, 'price_cents' => 900]);
$order->getLabels()['gift'] = 'yes';

echo get_class($order->getItems()), " with ", count($order->getItems()), " items\n";
echo "first sku: ", $order->getItems()[0]->getSku(), "\n";
unset($order->getLabels()['gift']);
echo "labels: ", count($order->getLabels()), "\n";

// Convert to a plain PHP array when you need array functions
$skus = array_map(fn(LineItem $i) => $i->getSku(), iterator_to_array($order->getItems()));
echo implode(', ', $skus), "\n";

// Wrong element type is rejected
try {
    $order->getItems()[] = 'not a line item';
} catch (Throwable $e) {
    echo get_class($e), ": ", $e->getMessage(), "\n";
}

// Setters have typed parameters
try {
    (new LineItem())->setQuantity('five');
} catch (TypeError $e) {
    echo "TypeError: ", strtok($e->getMessage(), ','), "\n";
}

Output:

Google\Protobuf\RepeatedField with 2 items
first sku: PEN
labels: 0
PEN, INK
Exception: Expect Acme\Shop\V1\LineItem.
TypeError: Acme\Shop\V1\LineItem::setQuantity(): Argument #1 ($var) must be of type int

Functions like array_map(), array_filter() or usort() need a real array, hence iterator_to_array(). The setters (setItems(), setLabels()) accept plain arrays and convert them.

JSON

Every message can also be read and written as JSON using the standard proto3 JSON mapping. This is useful for debugging, logging and for APIs that offer both formats:

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

use Acme\Shop\V1\Order;

$json = <<<'JSON'
{
  "id": "2002",
  "customerEmail": "bob@example.com",
  "status": "ORDER_STATUS_SHIPPED",
  "items": [{"sku": "MUG", "quantity": 4, "priceCents": 1250}],
  "createdAt": "2026-10-16T18:05:00Z",
  "invoiceNumber": "INV-77"
}
JSON;

$order = new Order();
$order->mergeFromJsonString($json);
echo $order->getId(), " ", $order->getCustomerEmail(), " ", $order->getPayment(), "\n";
echo "binary: ", strlen($order->serializeToString()), " bytes, json: ", strlen($json), " bytes\n";

// Unknown JSON fields are an error by default...
$withExtra = '{"id": "1", "giftWrap": true}';
try {
    (new Order())->mergeFromJsonString($withExtra);
} catch (Exception $e) {
    echo get_class($e), ": ", $e->getMessage(), "\n";
}

// ...unless you ask the parser to ignore them
$o = new Order();
$o->mergeFromJsonString($withExtra, true);
echo "parsed id ", $o->getId(), "\n";

// Field names in snake_case (proto names) are accepted too
$o = new Order();
$o->mergeFromJsonString('{"customer_email": "c@example.com"}');
echo $o->getCustomerEmail(), "\n";

Output:

2002 bob@example.com invoice_number
binary: 50 bytes, json: 224 bytes
Google\Protobuf\Internal\GPBDecodeException: Error occurred during parsing: Error occurred during parsing: giftWrap is unknown.
parsed id 1
c@example.com

The output format can be adjusted with Google\Protobuf\PrintOptions flags:

<?php
require __DIR__ . '/vendor/autoload.php';
require __DIR__ . '/make_order.php';

use Google\Protobuf\PrintOptions;

$order = makeOrder();
$order->setCustomerEmail('');

echo $order->serializeToJsonString(PrintOptions::PRESERVE_PROTO_FIELD_NAMES), "\n\n";
echo $order->serializeToJsonString(
    PrintOptions::ALWAYS_PRINT_ENUMS_AS_INTS | PrintOptions::EMIT_DEFAULTS
), "\n";

Output:

{"id":"1001","status":"ORDER_STATUS_PAID","items":[{"sku":"BOOK-PHP","quantity":1,"price_cents":"2999"},{"sku":"MUG","quantity":2,"price_cents":"1250"}],"labels":{"channel":"web","region":"eu"},"created_at":"2026-10-17T09:30:00Z","card_token":"tok_4242"}

{"id":"1001","customerEmail":"","status":2,"items":[{"sku":"BOOK-PHP","quantity":1,"priceCents":"2999"},{"sku":"MUG","quantity":2,"priceCents":"1250"}],"labels":{"channel":"web","region":"eu"},"createdAt":"2026-10-17T09:30:00Z","cardToken":"tok_4242"}

Without EMIT_DEFAULTS the empty customerEmail is left out, just like in the binary format.

Handling invalid input

Both mergeFromString() and mergeFromJsonString() throw Google\Protobuf\Internal\GPBDecodeException (a subclass of Exception) on malformed data. Always catch it when the bytes come from the network:

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

use Acme\Shop\V1\Order;

try {
    (new Order())->mergeFromString("\x0a\xff\xff");
} catch (Exception $e) {
    echo get_class($e), ": ", $e->getMessage(), "\n";
}

Output:

Google\Protobuf\Internal\GPBDecodeException: Error occurred during parsing: Unexpected EOF inside length.

A successful parse doesn't mean the data is meaningful, though. Protobuf has no "required" fields in proto3, so an empty string parses into a valid, all-defaults message. Validate business rules (non-empty email, positive quantity) yourself after parsing.

Schema evolution and unknown fields

The main reason to use protobuf over ad-hoc formats is that schemas can change without breaking existing clients, as long as you follow a few rules:

message Order {
  reserved 8, 9;
  reserved "gift_wrap";
  // ...
}

Here old code receives bytes from a newer version of the schema that added string gift_message = 8;. To keep the example self-contained, the extra field is appended by hand: a tag byte (field number shifted left by 3, OR-ed with wire type 2 for length-delimited data), a length, then the payload.

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

use Acme\Shop\V1\Order;

// Bytes produced by a newer client whose schema has an extra field:
//   string gift_message = 8;
$old = new Order(['id' => 7, 'customer_email' => 'dan@example.com']);
$gift = 'Happy birthday!';
$newerBytes = $old->serializeToString()
    . chr((8 << 3) | 2)        // tag: field 8, wire type 2 (length-delimited)
    . chr(strlen($gift))       // length
    . $gift;                   // payload

// Older code parses it without complaint
$order = new Order();
$order->mergeFromString($newerBytes);
echo $order->getId(), " ", $order->getCustomerEmail(), "\n";

// The unknown field is kept and written back out
$roundTrip = $order->serializeToString();
var_dump($roundTrip === $newerBytes);

// discardUnknownFields() drops it
$order->discardUnknownFields();
echo strlen($newerBytes), " -> ", strlen($order->serializeToString()), " bytes\n";

Output:

7 dan@example.com
bool(true)
36 -> 19 bytes

Because unknown fields are preserved, a PHP service in the middle of a pipeline can read a message, change a field and pass it on without losing data added by newer services.

This only works for the binary format. In JSON, field names are the identity, so renaming a field breaks JSON clients, and unknown fields are rejected unless you pass true as the second argument of mergeFromJsonString().

Sending protobuf over HTTP

Protobuf doesn't define a transport. A common choice is a plain HTTP POST with Content-Type: application/x-protobuf. The server reads the raw body from php://input (see Reading raw POST data):

<?php
// server.php
require __DIR__ . '/vendor/autoload.php';

use Acme\Shop\V1\Order;
use Acme\Shop\V1\OrderStatus;

if ($_SERVER['REQUEST_METHOD'] !== 'POST'
    || ($_SERVER['CONTENT_TYPE'] ?? '') !== 'application/x-protobuf') {
    http_response_code(415);
    exit;
}

$order = new Order();
try {
    $order->mergeFromString(file_get_contents('php://input'));
} catch (Exception $e) {
    http_response_code(400);
    header('Content-Type: text/plain');
    echo "bad protobuf: ", $e->getMessage();
    exit;
}

$order->setStatus(OrderStatus::ORDER_STATUS_PENDING);

header('Content-Type: application/x-protobuf');
echo $order->serializeToString();

A client using only PHP's stream functions:

<?php
// client.php
require __DIR__ . '/vendor/autoload.php';

use Acme\Shop\V1\Order;
use Acme\Shop\V1\OrderStatus;

function postProto(string $url, Order $request): Order
{
    $context = stream_context_create(['http' => [
        'method' => 'POST',
        'header' => "Content-Type: application/x-protobuf\r\nAccept: application/x-protobuf",
        'content' => $request->serializeToString(),
        'ignore_errors' => true,
    ]]);
    $body = file_get_contents($url, false, $context);
    $status = (int) explode(' ', http_get_last_response_headers()[0])[1];
    if ($status !== 200) {
        throw new RuntimeException("HTTP $status: $body");
    }
    $response = new Order();
    $response->mergeFromString($body);
    return $response;
}

$reply = postProto('http://127.0.0.1:8080/server.php', new Order(['id' => 55, 'customer_email' => 'eve@example.com']));
echo $reply->getId(), " ", OrderStatus::name($reply->getStatus()), "\n";

Start the server with php -S 127.0.0.1:8080 and run the client:

55 ORDER_STATUS_PENDING

http_get_last_response_headers() is new in PHP 8.4; on older versions use the $http_response_header variable. For gRPC (protobuf over HTTP/2 with generated service stubs), install the grpc PECL extension and the grpc/grpc Composer package and generate client code with protoc --grpc_out using the grpc_php_plugin. Note that PHP can only act as a gRPC client; serving gRPC needs a long-running server such as RoadRunner.

Storing many messages in one file

A serialized message doesn't record where it ends, so you can't just concatenate messages. The usual convention (used by Java's writeDelimitedTo() and C++'s SerializeDelimitedToOstream()) is to prefix each message with its length encoded as a varint:

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

use Acme\Shop\V1\Order;

function writeVarint($fp, int $n): void
{
    $out = '';
    while ($n > 0x7f) {
        $out .= chr(($n & 0x7f) | 0x80);
        $n >>= 7;
    }
    fwrite($fp, $out . chr($n));
}

function readVarint($fp): ?int
{
    $n = 0;
    $shift = 0;
    while (true) {
        $c = fgetc($fp);
        if ($c === false) {
            return $shift === 0 ? null : throw new RuntimeException('truncated varint');
        }
        $b = ord($c);
        $n |= ($b & 0x7f) << $shift;
        if ($b < 0x80) {
            return $n;
        }
        $shift += 7;
    }
}

function writeDelimited($fp, Order $msg): void
{
    $bytes = $msg->serializeToString();
    writeVarint($fp, strlen($bytes));
    fwrite($fp, $bytes);
}

/** @return Generator<Order> */
function readDelimited($fp): Generator
{
    while (($len = readVarint($fp)) !== null) {
        $msg = new Order();
        $msg->mergeFromString($len > 0 ? fread($fp, $len) : '');
        yield $msg;
    }
}

$path = tempnam(sys_get_temp_dir(), 'orders');
$fp = fopen($path, 'wb');
for ($i = 1; $i <= 3; $i++) {
    writeDelimited($fp, new Order(['id' => $i, 'customer_email' => "user$i@example.com"]));
}
fclose($fp);
echo "file size: ", filesize($path), " bytes\n";

$fp = fopen($path, 'rb');
foreach (readDelimited($fp) as $order) {
    echo $order->getId(), " ", $order->getCustomerEmail(), "\n";
}
fclose($fp);
unlink($path);

Output:

file size: 66 bytes
1 user1@example.com
2 user2@example.com
3 user3@example.com

The generator reads one message at a time, so even a large file never has to fit in memory.

Tips

Feedback about page:

Feedback:
Optional: your email if you want me to get back to you:



Table Of Contents