PHPackages                             thesis/protobuf - 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. [Parsing & Serialization](/categories/parsing)
4. /
5. thesis/protobuf

ActiveLibrary[Parsing & Serialization](/categories/parsing)

thesis/protobuf
===============

A modern strictly typed full-featured serializer for Google's protocol buffers.

0.1.10(2mo ago)42.3k8MITPHPPHP ^8.4CI passing

Since Jan 3Pushed 2mo agoCompare

[ Source](https://github.com/thesis-php/protobuf)[ Packagist](https://packagist.org/packages/thesis/protobuf)[ Fund](https://www.tinkoff.ru/cf/5MqZQas2dk7)[ RSS](/packages/thesis-protobuf/feed)WikiDiscussions 0.1.x Synced 3d ago

READMEChangelog (10)Dependencies (15)Versions (18)Used By (8)

Native PHP protobuf implementation
----------------------------------

[](#native-php-protobuf-implementation)

### Installation

[](#installation)

```
composer require thesis/protobuf
```

### Usage

[](#usage)

First of all, you should remember that the intended way to use this library is through the [protoc plugin](https://github.com/thesis-php/protoc-plugin), which you should use to generate PHP code from your proto schema. While it is possible to write such code manually, it is not recommended.

Although the library provides a low-level API for building other tools, such as reflection, it is recommended to use the `Encoder/Decoder` from this library. They use attributes from `Thesis\Protobuf\Reflection` to locate the necessary information, such as the field number and its type in protobuf.

Let's look at encoding and decoding using a simple protobuf message as an example:

```
use Thesis\Protobuf\Reflection;

final readonly class CreateUserRequest
{
    /**
     * @param list $roles
     */
    public function __construct(
        #[Reflection\Field(1, Reflection\Int32T::T)]
        public int $id = 0,
        #[Reflection\Field(2, Reflection\StringT::T)]
        public string $name = '',
        #[Reflection\Field(3, new Reflection\ListT(Reflection\StringT::T))]
        public array $roles = [],
    ) {}
}
```

#### Encoding

[](#encoding)

To encode such an object in protobuf format, you need to create an `Encoder` using the `Encoder\Builder`:

```
use Thesis\Protobuf\Encoder;

$encoder = Encoder\Builder::buildDefault();
```

Or using `PSR-16` cache implementation to cache the reflection:

```
use Thesis\Protobuf\Encoder;

$encoder = new Encoder\Builder()
    ->withCache(/** cache implementation */)
    ->build();
```

By default, simple `InMemoryPsr16Cache` implementation will be used.

Now we are ready to encode the message:

```
$encoder->encode(new CreateUserRequest(1, 'kafkiansky', ['developer']));
```

You will get a ready-to-use protobuf message that can be used to store in files, in queues (for example, messages in Kafka are often stored as protobuf messages for better compression), and, of course, for transmission over the network within the [gRPC](https://github.com/thesis-php/grpc) protocol.

#### Decoding

[](#decoding)

To decode a protobuf message into a class (and only into a class: enums cannot be a top-level type, but they can be part of message fields), use the `Decoder`. Creating it is just as simple as creating an `Encoder`:

```
use Thesis\Protobuf\Decoder;

$decoder = Decoder\Builder::buildDefault();
```

Since the `Decoder` also uses reflection, you can configure caching yourself or leave the default in-memory implementation, which is already efficient enough for long-running applications.

```
use Thesis\Protobuf\Decoder;

$decoder = new Decoder\Builder()
    ->withCache(/** cache implementation */)
    ->build();
```

And now you are ready to decode the message:

```
$request = $decoder->decode(/** protobuf buffer here */, CreateUserRequest::class);

echo $request->name;
```

### Required fields

[](#required-fields)

`Reflector::map()` maps missing fields using property defaults when they exist. If a property is non-nullable and has no default value, it is treated as required.

When one or more required properties are missing, decoding fails with `Thesis\Protobuf\Reflection\Exception\MappingError`. The exception contains all reasons in `->reasons` (each reason is typically `PropertyRequired`).

This behavior is aligned with other protobuf implementations/plugins: messages missing required fields are treated as invalid during decode.

A field is considered required when either:

- it is defined as `required` in `proto2`;
- it is defined in editions with `features.field_presence = LEGACY_REQUIRED`.

```
use Thesis\Protobuf\Decoder;
use Thesis\Protobuf\Reflection;

$decoder = Decoder\Builder::buildDefault();

try {
    $message = $decoder->decode($buffer, CreateUserRequest::class);
} catch (Reflection\Exception\MappingError $e) {
    foreach ($e->reasons as $reason) {
        if ($reason instanceof Reflection\Exception\PropertyRequired) {
            echo $reason->class . "::$" . $reason->property . PHP_EOL;
        }
    }
}
```

Both `Encoder::encode()` and `Decoder::decode()` throw `Thesis\Protobuf\ProtobufException`. Domain protobuf exceptions are preserved and are not wrapped into generic runtime errors.

### Unknown fields

[](#unknown-fields)

When a protobuf message is decoded, it may contain fields that are not defined in the target class. This happens when the sender uses a newer version of the schema, but the receiver has not been updated yet.

By default, unknown fields are silently skipped during decoding. However, you can configure the `Decoder` to capture them, which is useful for logging, debugging, or forwarding messages without data loss.

#### Storing unknown fields in memory

[](#storing-unknown-fields-in-memory)

The `UnknownFields` handler stores unknown fields in a `WeakMap` attached to the decoded object. Once the object is garbage collected, the unknown fields are automatically cleaned up.

```
use Thesis\Protobuf\Decoder;
use Thesis\Protobuf\UnknownFields;

$decoder = new Decoder\Builder()
    ->withUnknownHandler(UnknownFields::handler())
    ->build();

$request = $decoder->decode($buffer, CreateUserRequest::class);

// Get unknown fields for a specific object.
$unknowns = UnknownFields::of($request);

foreach ($unknowns as $field) {
    echo "Field #{$field->tag->num}, wire type: {$field->tag->type->name}\n";
}
```

Each decoded object tracks its own unknown fields independently. If `CreateUserRequest` has a nested message with unknown fields, you can inspect them separately:

```
$unknowns = UnknownFields::of($request->nested);
```

#### Using a callback

[](#using-a-callback)

The `UnknownFieldsCallback` handler calls a user-defined function each time unknown fields are detected. This is convenient for logging without keeping the data in memory:

```
use Thesis\Protobuf\Decoder;
use Thesis\Protobuf\UnknownFields;

$decoder = new Decoder\Builder()
    ->withUnknownHandler(new UnknownFields\UnknownFieldsCallback(
        static function (object $message, array $unknowns): void {
            $logger->warning('Unknown fields detected', [
                'class' => $message::class,
                'fields' => array_map(
                    static fn(UnknownFields\UnknownField $f) => $f->tag->num,
                    $unknowns,
                ),
            ]);
        },
    ))
    ->build();
```

#### Custom handler

[](#custom-handler)

You can implement the `UnknownFields\Handler` interface to define your own strategy:

```
use Thesis\Protobuf\UnknownFields;

final readonly class MyHandler implements UnknownFields\Handler
{
    #[\Override]
    public function handle(object $message, array $unknowns): void
    {
        // your logic here
    }
}
```

###  Health Score

45

—

FairBetter than 91% of packages

Maintenance84

Actively maintained with recent releases

Popularity22

Limited adoption so far

Community16

Small or concentrated contributor base

Maturity51

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 100% 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 ~9 days

Recently: every ~3 days

Total

12

Last Release

80d ago

### Community

Maintainers

![](https://avatars.githubusercontent.com/u/2552865?v=4)[Valentin Udaltsov](/maintainers/vudaltsov)[@vudaltsov](https://github.com/vudaltsov)

---

Top Contributors

[![kafkiansky](https://avatars.githubusercontent.com/u/37590388?v=4)](https://github.com/kafkiansky "kafkiansky (83 commits)")

---

Tags

protobufprotocol-buffers

###  Code Quality

TestsPHPUnit

### Embed Badge

![Health badge](/badges/thesis-protobuf/health.svg)

```
[![Health](https://phpackages.com/badges/thesis-protobuf/health.svg)](https://phpackages.com/packages/thesis-protobuf)
```

###  Alternatives

[laravel/framework

The Laravel Framework.

34.8k543.8M20.1k](/packages/laravel-framework)[illuminate/contracts

The Illuminate Contracts package.

706130.3M13.4k](/packages/illuminate-contracts)[algolia/algoliasearch-client-php

API powering the features of Algolia.

69735.1M159](/packages/algolia-algoliasearch-client-php)[moonshine/moonshine

Laravel administration panel

1.3k253.1k81](/packages/moonshine-moonshine)[flow-php/flow

PHP ETL - Extract Transform Load - Data processing framework

85036.3k](/packages/flow-php-flow)[civicrm/civicrm-core

Open source constituent relationship management for non-profits, NGOs and advocacy organizations.

751291.4k43](/packages/civicrm-civicrm-core)

PHPackages © 2026

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