Download the PHP package thesis/protobuf without Composer

Native PHP protobuf implementation

Installation

Usage

First of all, you should remember that the intended way to use this library is through the 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:

Encoding

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

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

By default, simple InMemoryPsr16Cache implementation will be used.

Now we are ready to encode the message:

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 protocol.

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:

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.

And now you are ready to decode the message:

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.

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

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

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.

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

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:

Custom handler

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