Home

Awesome

Protobuf for PHP

Build Status Coverage Status

Protobuf for PHP is an implementation of Google's Protocol Buffers for the PHP language, supporting its binary data serialization and including a protoc plugin to generate PHP classes from .proto files.

Installation

If you wish to compile .proto definitions to PHP, you will need to install Google's Protocol Buffers from your favorite package manager or from source. This plugin currently supports protobuf 2.3.0. or later.

Note: Google's Protocol Buffers and proto is not a runtime requirement for protobuf-php/protobuf, It is only necessary if you wish to compile your definitions to PHP using protobuf-php/protobuf-plugin.

Installing Google's Protocol Buffers

$ brew install protobuf

$ sudo apt-get install -y protobuf

Make sure you have protoc available in the user's path:

$ protoc --version
$ # libprotoc 2.6.1

Note: For more information on how to install/compile Google's Protocol Buffers see : https://github.com/google/protobuf

Composer install

To install the PHP plugin run the following composer commands:

$ composer require "protobuf-php/protobuf-plugin"

Defining Your Protocol Format

To create your address book application, you'll need to start with a .proto file. The definitions in a .proto file are simple: you add a message for each data structure you want to serialize, then specify a name and a type for each field in the message. Here is the .proto file that defines your messages, addressbook.proto.

package tutorial;
import "php.proto";
option (php.package) = "Tutorial.AddressBookProtos";

message Person {
  required string name = 1;
  required int32 id = 2;
  optional string email = 3;

  enum PhoneType {
    MOBILE = 0;
    HOME = 1;
    WORK = 2;
  }

  message PhoneNumber {
    required string number = 1;
    optional PhoneType type = 2 [default = HOME];
  }

  repeated PhoneNumber phone = 4;
}

message AddressBook {
  repeated Person person = 1;
}

As you can see, the syntax is similar to C++ or Java. Let's go through each part of the file and see what it does. The .proto file starts with a package declaration, which helps to prevent naming conflicts between different projects. In PHP, the package name is used as the PHP namespace unless you have explicitly specified a (php.package), as we have here. Even if you do provide a (php.package), you should still define a normal package as well to avoid name collisions in the Protocol Buffers name space as well as in non PHP languages.

You'll find a complete guide to writing .proto files – including all the possible field types – in the Protocol Buffer Language Guide. Don't go looking for facilities similar to class inheritance, though – protocol buffers don't do that.

Compiling Your Protocol Buffers

Now that you have a .proto, the next thing you need to do is generate the classes you'll need to read and write AddressBook (and hence Person and PhoneNumber) messages. To do this, you need to run the protocol buffer plugin on your .proto.

In this case:

php ./vendor/bin/protobuf --include-descriptors -i . -o ./src/ ./addressbook.proto

This generates the following PHP classes in your specified destination directory

src/
└── Tutorial
    └── AddressBookProtos
        ├── AddressBook.php
        ├── Person
        │   ├── PhoneNumber.php
        │   └── PhoneType.php
        └── Person.php

Note: For more information on how to use the generated code see : protobuf-php/protobuf