protobuf-php - The framework
<?php
require_once 'DrSlump\Protobuf.php';
use DrSlump\Protobuf;
$data = file_get_contents('data.pb');
$person = new Tutorial\Person($data);
echo $person->getName();
Protobuf-PHP is a library to generate, parse and serialize data structures compatible with Google's Protocol Buffers using the PHP language.
The library is designed to work with a pluggable mechanism for encoding and decoding messages, allowing it to be used not only to communicate using the standard binary format but also with Json or XML based formats.
You can create your own codecs by either extending a provided one or implementing the
Protobuf\CodecInterface. Creating custom codecs offers the possibility to use
Protobuf-PHP code generation tool to work with legacy formats or even as a simple
way to interact with database adapters.
This is the standard binary format supported by the official libraries distributed by Google. It's pretty much compatible with the official implementations although there are some known issues, mostly regarding big integer numbers, which are documented in the readme file that comes with the library.
The official libraries also support a text based format for debugging purposes. The current implementation of this codec only supports encoding or serialization.
This is more of an internal codec to ease the implementation of some others. It is able to serializa message objects to PHP's associative arrays and intantiate message objects from them.
Since most serialization libraries in PHP will natively support associative arrays, this codec can be used as an easy way to incorporate those formats for their use with Protobuf messages. The Json and XML codecs are examples of this use case.
It allows to generate or consume JSON formatted strings, which is a very popular format for REST based web services for example. This codec can be used to communicate with JavaScript in the browser or with third party REST web services.
ProtoJson allows to apply some payload minification strategies when working with JSON formatted messages. Taking advantatge of Protobuf's property names mapping to a integer number, it offers two encoding variants (TagMap and Indexed) that use that number instead of the field name as key in the messages to reduce the total size of the payload.
A very simple codec to work with XML based messages. It has no knowledge of namespaces and other advanced XML features but should be enough to integrate with third parties that are restricted to simple XML payloads. It can also serve as a base for more customized integrations, by extendind this codec to consume and generate XML messages specific to your service.
While the most common use case is to use the protoc-gen-php(1) protoc plugin to
generate source code representing the messages defined in .proto files, it's also
possible to define messages at runtime without the code generation step.
An easy way to define messages directly in your code is to use the Protobuf\AnnotatedMessage
abstract class, which allows to annotate your classes so that the codecs know how
to parse and serialize those messages.
class Person extends \DrSlump\Protobuf\AnnotatedMessage {
/** @protobuf(tag=1, type=string, required) */
public $name;
/** @protobuf(tag=2, type=int32, required) */
public $id;
/** @protobuf(tag=3, type=string, optional) */
public $email;
/** @protobuf(tag=4, repeated, type=message, reference=Person) */
public $friends = array();
}
Please report bugs using GitHub's issue tracker at http://github.com/drslump/protobuf-php/issues
Protobuf for PHP is Copyright (C) 2011 Ivan -DrSlump- Montes http://pollinimini.net
protoc-gen-php(1), protobuf-php(5), http://github.com/drslump/protobuf-php