PHP Protobuf - Google's Protocol Buffers for PHP

Overview

This repository is no longer maintained

Since Google's official Protocol Buffers supports PHP language, it's unjustifiable to maintain this project. Please refer to Protocol Buffers for PHP language support.

PHP Protobuf - Google's Protocol Buffers for PHP

Overview

Protocol Buffers are a way of encoding structured data in an efficient yet extensible format. It might be used in file formats and RPC protocols.

PHP Protobuf is Google's Protocol Buffers implementation for PHP with a goal to provide high performance, including a protoc plugin to generate PHP classes from .proto files. The heavy-lifting (a parsing and a serialization) is done by a PHP extension.

Requirements

  • PHP 7.0 or above (for PHP 5 support refer to php5 branch)
  • Pear's Console_CommandLine (for the protoc plugin)
  • Google's protoc compiler version 2.6 or above

Getting started

Installation

  1. Clone the source code

    git clone https://github.com/allegro/php-protobuf
    
  2. Go to the source code directory

    cd php-protobuf
    
  3. Build and install the PHP extension (follow instructions at php.net)

  4. Install protoc plugin dependencies

    composer install
    

Usage

  1. Assume you have a file foo.proto

    message Foo
    {
        required int32 bar = 1;
        optional string baz = 2;
        repeated float spam = 3;
    }
    
  2. Compile foo.proto

    php protoc-gen-php.php foo.proto
    
  3. Create Foo message and populate it with some data

    require_once 'Foo.php';
    
    $foo = new Foo();
    $foo->setBar(1);
    $foo->setBaz('two');
    $foo->appendSpam(3.0);
    $foo->appendSpam(4.0);
  4. Serialize a message to a string

    $packed = $foo->serializeToString();
  5. Parse a message from a string

    $parsedFoo = new Foo();
    try {
        $parsedFoo->parseFromString($packed);
    } catch (Exception $ex) {
        die('Oops.. there is a bug in this example, ' . $ex->getMessage());
    }
  6. Let's see what we parsed out

    $parsedFoo->dump();

    It should produce output similar to the following:

    Foo {
      1: bar => 1
      2: baz => 'two'
      3: spam(2) =>
        [0] => 3
        [1] => 4
    }
    
  7. If you would like you can reset an object to its initial state

    $parsedFoo->reset();

Guide

Compilation

PHP Protobuf comes with Google's protoc compiler plugin. You can run in directly:

php protoc-gen-php.php -o output_dir foo.proto

or pass it to the protoc:

protoc --plugin=protoc-gen-allegrophp=protoc-gen-php.php --allegrophp_out=output_dir foo.proto

On Windows use protoc-gen-php.bat instead.

Command line options

  • -o out, --out=out - the destination directory for generated files (defaults to the current directory).
  • -I proto_path, --proto_path=proto_path - the directory in which to search for imports.
  • --protoc=protoc - the protoc compiler executable path.
  • -D define, --define=define - define a generator option (i.e. -Dnamespace='Foo\Bar\Baz').

Generator options

  • namespace - the namespace to be used by the generated PHP classes.

Message class

The classes generated during the compilation are PSR-0 compliant (each class is put into it's own file). If namespace generator option is not defined then a package name (if present) is used to create a namespace. If the package name is not set then a class is put into global space.

PHP Protobuf module implements ProtobufMessage class which encapsulates the protocol logic. A message compiled from a proto file extends this class providing message field descriptors. Based on these descriptors ProtobufMessage knows how to parse and serialize a message of a given type.

For each field a set of accessors is generated. The set of methods is different for single value fields (required / optional) and multi-value fields (repeated).

  • required / optional

      get{FIELD}()        // return a field value
      has{FIELD}()        // check whether a field is set
      set{FIELD}($value)  // set a field value to $value
    
  • repeated

      append{FIELD}($value)       // append $value to a field
      clear{FIELD}()              // empty field
      get{FIELD}()                // return an array of field values
      getAt{FIELD}($index)        // return a field value at $index index
      getCount{FIELD}()           // return a number of field values
      has{FIELD}()                // check whether a field is set
      getIterator{FIELD}()        // return an ArrayIterator
    

{FIELD} is a camel cased field name.

Enum

PHP does not natively support enum type. Hence enum is represented by the PHP integer type. For convenience enum is compiled to a class with set of constants corresponding to its possible values.

Type mapping

The range of available build-in PHP types poses some limitations. PHP does not support 64-bit positive integer type. Note that parsing big integer values might result in getting unexpected results.

Protocol Buffers types map to PHP types as follows (x86_64):

| Protocol Buffers | PHP    |
| ---------------- | ------ |
| double           | float  |
| float            |        |
| ---------------- | ------ |
| int32            | int    |
| int64            |        |
| uint32           |        |
| uint64           |        |
| sint32           |        |
| sint64           |        |
| fixed32          |        |
| fixed64          |        |
| sfixed32         |        |
| sfixed64         |        |
| ---------------- | ------ |
| bool             | bool   |
| ---------------- | ------ |
| string           | string |
| bytes            |        |

Protocol Buffers types map to PHP types as follows (x86):

| Protocol Buffers | PHP                         |
| ---------------- | --------------------------- |
| double           | float                       |
| float            |                             |
| ---------------- | --------------------------- |
| int32            | int                         |
| uint32           |                             |
| sint32           |                             |
| fixed32          |                             |
| sfixed32         |                             |
| ---------------- | --------------------------- |
| int64            | if val <= PHP_INT_MAX       |
| uint64           | then value is stored as int |
| sint64           | otherwise as double         |
| fixed64          |                             |
| sfixed64         |                             |
| ---------------- | --------------------------- |
| bool             | bool                        |
| ---------------- | --------------------------- |
| string           | string                      |
| bytes            |                             |

Not set value is represented by null type. To unset value just set its value to null.

Parsing

To parse message create a message class instance and call its parseFromString method passing it a serialized message. The errors encountered are signaled by throwing Exception. Exception message provides detailed explanation. Required fields not set are silently ignored.

$packed = /* serialized FooMessage */;
$foo = new FooMessage();

try {
    $foo->parseFromString($packed);
} catch (Exception $ex) {
    die('Parse error: ' . $e->getMessage());
}

$foo->dump(); // see what you got

Serialization

To serialize a message call serializeToString method. It returns a string containing protobuf-encoded message. The errors encountered are signaled by throwing Exception. Exception message provides detailed explanation. A required field not set triggers an error.

$foo = new FooMessage()
$foo->setBar(1);

try {
    $packed = $foo->serializeToString();
} catch (Exception $ex) {
    die 'Serialize error: ' . $e->getMessage();
}

/* do some cool stuff with protobuf-encoded $packed */

Debugging

There might be situations you need to investigate what an actual content of a given message is. What var_dump gives on a message instance is somewhat obscure.

The ProtobufMessage class comes with dump method which prints out a message content to the standard output. It takes one optional argument specifying whether you want to dump only set fields (by default it dumps only set fields). Pass false as an argument to dump all fields. Format it produces is similar to var_dump.

Alternatively you can use printDebugString() method which produces output in protocol buffers text format.

IDE Helper and Auto-Complete Support

To integrate this extension with your IDE (PhpStorm, Eclipse etc.) and get auto-complete support, simply include stubs\ProtobufMessage.php anywhere under your project root.

Known issues

References

Acknowledgments

Issues
  • Add support for PHP7?

    Add support for PHP7?

    The five RC of PHP has been released, and PHP 7 is likely to be released on Nov 12 this year.

    opened by flashjay 60
  • Php7

    Php7

    Implemented php7 support. It has no backward compatibility so you can keep it a as separate branch. But I think its better to create php5 branch from current master and merge these changes into master.

    opened by serggp 31
  • proto3 default

    proto3 default

    Accodring to https://developers.google.com/protocol-buffers/docs/proto3#default

    When a message is parsed, if the encoded message does not contain a particular singular element, the corresponding field in the parsed object is set to the default value for that field. These defaults are type-specific:

    For strings, the default value is the empty string.
    For bytes, the default value is empty bytes.
    For bools, the default value is false.
    For numeric types, the default value is zero.
    For enums, the default value is the first defined enum value, which must be 0.
    For message fields, the field is not set. Its exact value is langauge-dependent. See the generated code guide for details. 
    

    But in php-protobuf the default value is null , now I have problem with enums Why the default value of enum in php-protobuf is null when google told it must be 0 ?

    bug 
    opened by sm2017 19
  • How to install php-protobuf  in xamp (Window) .

    How to install php-protobuf in xamp (Window) .

    Hi please help me i want to install php-protobuf in xamp on window.but i have no idea how it will be installed .when i run protoc-php.php its show "requires protobuf extension installed to run". how can i install this extension ??

    Thanks

    opened by PunitSaharan 18
  • .proto2 - Files instead of .proto3

    .proto2 - Files instead of .proto3

    Hello,

    I want to Create some php classes with .proto - Files of the Version 2, but php-protobuf only works with Version 3 Files. Is there a workaround to work with .proto 2 Files?

    opened by Booser47 15
  • Big Number Error

    Big Number Error

    I have a big Number (2069643420177269543) which will not be displayed correct. After a "parseFromString", I only get the Number 807..

    Some Ideas why?

    opened by Booser47 13
  • how to deep copy a message object to another message object

    how to deep copy a message object to another message object

    python have the CopyFrom method to copy all the values from another message of the same type as bar. but php assign a object to another object is not deep copy, and php-protobuf have the set{fieldname} function is also not deep copy.

    So How to how to deep copy a message object to another message object

    enhancement 
    opened by crazier 10
  • --allegrophp_out: protoc-gen-allegrophp: Plugin failed with status code 127.

    --allegrophp_out: protoc-gen-allegrophp: Plugin failed with status code 127.

    i run php protoc-gen-php.php foo.proto

    get this error

    /data/www/php-protobuf # php protoc-gen-php.php foo.proto
    ': No such file or directory
    --allegrophp_out: protoc-gen-allegrophp: Plugin failed with status code 127.
    ERROR: protoc exited with an exit status 1 when executed with:
      protoc \
        --plugin=protoc-gen-allegrophp='/data/www/php-protobuf/protoc-gen-php.php' \
        --allegrophp_out=':./' \
        'foo.proto'
    

    i have installed protoc and protocbuf module

    /data/www/php-protobuf # protoc --version
    libprotoc 2.6.1
    
    /data/www/php-protobuf # php -m | grep protobuf
    protobuf
    

    anyone know what should i do to solve the problem?thanks!

    opened by Darkgel 10
  • Error when compiling: requires protobuf extension installed to run

    Error when compiling: requires protobuf extension installed to run

    When executing "php protoc-php.php test.proto", I got such output: protoc-php.php requires protobuf extension installed to run

    opened by sbtdkj1017 9
Releases(v0.11.3)
Owner
Allegro Tech
Allegro Tech Open Source Projects
Allegro Tech
A PHP 5.3+ and PHP 7.3 framework for OpenGraph Protocol

Opengraph Test with Atoum cd Opengraph/ curl -s https://getcomposer.org/installer | php php composer.phar install --dev ./vendor/atoum/atoum/bin/atoum

Axel Etcheverry 89 Dec 1, 2021
A PHP implementation of the Unleash protocol aka Feature Flags in GitLab.

A PHP implementation of the Unleash protocol aka Feature Flags in GitLab. This implementation conforms to the official Unleash standards and implement

Dominik Chrástecký 2 Aug 18, 2021
An implementation of the Minecraft: Bedrock Edition protocol in PHP

BedrockProtocol An implementation of the Minecraft: Bedrock Edition protocol in PHP This library implements all of the packets in the Minecraft: Bedro

PMMP 54 Jan 10, 2022
MajorDoMo is an open-source DIY smarthome automation platform aimed to be used in multi-protocol and multi-services environment.

MajorDoMo (Major Domestic Module) is an open-source DIY smarthome automation platform aimed to be used in multi-protocol and multi-services environment. It is based on web-technologies stack and ready to be delivered to any modern device. It is very flexible in configuration with OOP paradigm used to set up automation rules and scripts. This platform can be installed on almost any personal computer running Windows or Linux OS.

Sergei Jeihala 359 Dec 30, 2021
Spotweb is a decentralized usenet community based on the Spotnet protocol.

Spotweb is a decentralized usenet community based on the Spotnet protocol. Spotweb requires an operational webserver with PHP5.6 installed, it

Spotweb 382 Jan 18, 2022
Spotweb is a decentralized usenet community based on the Spotnet protocol.

Spotweb Spotweb is a decentralized usenet community based on the Spotnet protocol. Spotweb requires an operational webserver with PHP5.6 installed, it

[sCRiPTz-TEAM] 2 Nov 29, 2021
> Create e-wallet, send money, withdraw and check balance all via USSD protocol

Mobile Money USSD solution Create e-wallet, send money, withdraw and check balance all via USSD protocol Create e-wallet Step 1 Step 2 Step 3 Step 4 S

Emmanuel HAKORIMANA 1 Nov 3, 2021
Configure Magento 2 to send email using Google App, Gmail, Amazon Simple Email Service (SES), Microsoft Office365 and many other SMTP (Simple Mail Transfer Protocol) servers

Magento 2 SMTP Extension - Gmail, G Suite, Amazon SES, Office 365, Mailgun, SendGrid, Mandrill and other SMTP servers. For Magento 2.0.x, 2.1.x, 2.2.x

MagePal :: Magento Extensions 294 Jan 8, 2022
Tars is a high-performance RPC framework based on name service and Tars protocol, also integrated administration platform, and implemented hosting-service via flexible schedule.

TARS - A Linux Foundation Project TARS Foundation Official Website TARS Project Official Website WeChat Group: TARS01 WeChat Offical Account: TarsClou

THE TARS FOUNDATION PROJECTS 9.3k Jan 13, 2022
TiDB is an open source distributed HTAP database compatible with the MySQL protocol

What is TiDB? TiDB ("Ti" stands for Titanium) is an open-source NewSQL database that supports Hybrid Transactional and Analytical Processing (HTAP) wo

PingCAP 30.1k Jan 14, 2022
The Current US Version of PHP-Nuke Evolution Xtreme v3.0.1b-beta often known as Nuke-Evolution Xtreme. This is a hardened version of PHP-Nuke and is secure and safe. We are currently porting Xtreme over to PHP 8.0.3

2021 Nightly Builds Repository PHP-Nuke Evolution Xtreme Developers TheGhost - Ernest Allen Buffington (Lead Developer) SeaBeast08 - Sebastian Scott B

Ernest Buffington 6 Jan 11, 2022
A multithreaded application server for PHP, written in PHP.

appserver.io, a PHP application server This is the main repository for the appserver.io project. What is appserver.io appserver.io is a multithreaded

appserver.io 944 Dec 20, 2021
Easy to use utility functions for everyday PHP projects. This is a port of the Lodash JS library to PHP

Lodash-PHP Lodash-PHP is a port of the Lodash JS library to PHP. It is a set of easy to use utility functions for everyday PHP projects. Lodash-PHP tr

Lodash PHP 449 Jan 10, 2022
A status monitor for Elite Dangerous, written in PHP. Designed for 1080p screens in the four-panel-view in panel.php, and for 7 inch screens with a resolution of 1024x600 connected to a Raspberry Pi.

EDStatusPanel A status monitor for Elite Dangerous, written in PHP. Designed for 1080p screens in the four-panel-view in panel.php, and for 7 inch scr

marcus-s 20 Oct 15, 2021
🐘 A probe program for PHP environment (一款精美的 PHP 探針, 又名X探針、劉海探針)

Simplified Chinese | 简体中文 Traditional Chinese(Taiwan) | 正體中文(臺灣) Traditional Chinese(Hong Kong) | 正體中文(香港) Japanese | 日本語 ?? X Prober This is a probe

Km.Van 1.1k Jan 10, 2022
PHP Text Analysis is a library for performing Information Retrieval (IR) and Natural Language Processing (NLP) tasks using the PHP language

php-text-analysis PHP Text Analysis is a library for performing Information Retrieval (IR) and Natural Language Processing (NLP) tasks using the PHP l

null 436 Jan 3, 2022
PHP generics written in PHP

PHP generics written in PHP Require PHP >= 7.4 Composer (PSR-4 Autoload) Table of contents How it works Quick start Example Features Tests How it work

Anton Sukhachev 93 Jan 5, 2022
PHP exercises from my course at ETEC and some of my own play-around with PHP

etec-php-exercises PHP exercises from my course at ETEC and some of my own play-around with PHP Translations: Português (BR) Projects Project Descript

Luis Felipe Santos do Nascimento 5 Jan 8, 2022
GitHub action to set up PHP with extensions, php.ini configuration, coverage drivers, and various tools.

GitHub action to set up PHP with extensions, php.ini configuration, coverage drivers, and various tools.

Shivam Mathur 2k Jan 12, 2022