1This directory contains the Protocol Buffers runtime implementation via both a 2pure PHP package and a native c extension. The pure PHP package is intended to 3provide usability to wider range of PHP platforms, while the c extension is 4intended to provide higher performance. Both implementations provide the same 5runtime APIs and share the same generated code. Users don’t need to re-generate 6code for the same proto definition when they want to switch the implementation 7later. 8 9Both implementations make use of generated PHP code that defines message and 10enum types in PHP. We strongly recommend using protoc's PHP generation support 11with .proto files. The build process in this directory only installs the 12extension/package; you need to install protoc as well to have PHP code 13generation functionality. 14 15## Requirements 16 17For information on supported language versions and how the support levels for 18PHP versions will change over time, see 19[Supported PHP versions](https://cloud.google.com/php/getting-started/supported-php-versions). 20 21## Installation 22 23### C Extension 24 25#### Prerequirements 26 27To install the c extension, the following tools are needed: 28* libtool 29* make 30* gcc 31* pear 32* pecl 33 34On Ubuntu, you can install them with: 35``` 36sudo apt-get install -y php-pear php-dev libtool make gcc 37``` 38On other platforms, please use the corresponding package managing tool to 39install them before proceeding. 40 41#### Installation from Source (Building extension) 42 43To build the c extension, run the following command: 44``` 45cd ext/google/protobuf 46pear package 47sudo pecl install protobuf-{VERSION}.tgz 48``` 49 50#### Installation from PECL 51 52When we release a version of Protocol Buffers, we will upload the extension to 53[PECL](https://pecl.php.net/). To use this pre-packaged extension, simply 54install it as you would any other extension: 55 56``` 57sudo pecl install protobuf-{VERSION} 58``` 59 60### PHP Package 61 62#### Installation from composer 63 64Simply add "google/protobuf" to the 'require' section of composer.json in your 65project. 66 67To use the pure PHP implementation, you need to install bcmath. 68 69### Protoc 70 71Once the extension or package is installed, if you wish to generate PHP code 72from a `.proto` file, you will also want to install the Protocol Buffers 73compiler (protoc), as described in this repository's main `README` file. The 74version of `protoc` included in the latest release supports the `--php_out` 75option to generate PHP code: 76``` 77protoc --php_out=out_dir test.proto 78``` 79 80## Usage 81 82For generated code: 83 https://developers.google.com/protocol-buffers/docs/reference/php-generated 84 85Known Issues 86------------ 87 88* Missing native support for well known types. 89* Missing support for proto2. 90* No API provided for clear/copy messages. 91* No API provided for encoding/decoding with stream. 92* Map fields may not be garbage-collected if there is cycle reference. 93* No debug information for messages in c extension. 94* HHVM not tested. 95* C extension not tested on windows, mac, php 7.0. 96* Message name cannot be Empty. 97 98## Development 99 100### Test Native PHP 101 102``` 103# Install Dependencies (Linux) 104apt-get install bazel composer php-dev 105 106# Download protobuf 107git clone https://github.com/protocolbuffers/protobuf.git 108cd protobuf 109 110# Build protoc 111bazel build :protoc 112 113# Test native php 114cd php 115composer install 116composer test 117``` 118 119### Test C Extension 120 121After you have finished testing the native php, you can test the c extension: 122``` 123cd tests 124./test.sh 5.6 # The php runtime version. 125 # We provide 5.5, 5.5-zts, 5.6, 5.6-zts, 7.0, 7.0-zts, 7.1, 7.1-zts, 7.2, 7.2-zts, 7.3 and 7.3-zts 126 # ls /usr/local for more details 127``` 128 129If you want to use gdb to debug the c extension, you can do: 130``` 131./gdb_test.sh 132``` 133