140 lines
3.7 KiB
Markdown
140 lines
3.7 KiB
Markdown
|
This directory contains the Protocol Buffers runtime implementation via both a
|
|||
|
|
pure PHP package and a native c extension. The pure PHP package is intended to
|
|||
|
|
provide usability to wider range of PHP platforms, while the c extension is
|
|||
|
|
intended to provide higher performance. Both implementations provide the same
|
|||
|
|
runtime APIs and share the same generated code. Users don’t need to re-generate
|
|||
|
|
code for the same proto definition when they want to switch the implementation
|
|||
|
|
later.
|
|||
|
|
|
|||
|
|
Both implementations make use of generated PHP code that defines message and
|
|||
|
|
enum types in PHP. We strongly recommend using protoc's PHP generation support
|
|||
|
|
with .proto files. The build process in this directory only installs the
|
|||
|
|
extension/package; you need to install protoc as well to have PHP code
|
|||
|
|
generation functionality.
|
|||
|
|
|
|||
|
|
## Requirements
|
|||
|
|
|
|||
|
|
To use PHP runtime library requires:
|
|||
|
|
|
|||
|
|
- C extension: PHP 7.x, 8.0
|
|||
|
|
- [PHP package](http://php.net/downloads.php): PHP 5.5, 5.6, 7.x, or 8.0.
|
|||
|
|
|
|||
|
|
## Installation
|
|||
|
|
|
|||
|
|
### C Extension
|
|||
|
|
|
|||
|
|
#### Prerequirements
|
|||
|
|
|
|||
|
|
To install the c extension, the following tools are needed:
|
|||
|
|
* autoconf
|
|||
|
|
* automake
|
|||
|
|
* libtool
|
|||
|
|
* make
|
|||
|
|
* gcc
|
|||
|
|
* pear
|
|||
|
|
* pecl
|
|||
|
|
|
|||
|
|
On Ubuntu, you can install them with:
|
|||
|
|
```
|
|||
|
|
sudo apt-get install -y php-pear php5-dev autoconf automake libtool make gcc
|
|||
|
|
```
|
|||
|
|
On other platforms, please use the corresponding package managing tool to
|
|||
|
|
install them before proceeding.
|
|||
|
|
|
|||
|
|
#### Installation from Source (Building extension)
|
|||
|
|
|
|||
|
|
To build the c extension, run the following command:
|
|||
|
|
```
|
|||
|
|
cd ext/google/protobuf
|
|||
|
|
pear package
|
|||
|
|
sudo pecl install protobuf-{VERSION}.tgz
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
#### Installation from PECL
|
|||
|
|
|
|||
|
|
When we release a version of Protocol Buffers, we will upload the extension to
|
|||
|
|
[PECL](https://pecl.php.net/). To use this pre-packaged extension, simply
|
|||
|
|
install it as you would any other extension:
|
|||
|
|
|
|||
|
|
```
|
|||
|
|
sudo pecl install protobuf-{VERSION}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### PHP Package
|
|||
|
|
|
|||
|
|
#### Installation from composer
|
|||
|
|
|
|||
|
|
Simply add "google/protobuf" to the 'require' section of composer.json in your
|
|||
|
|
project.
|
|||
|
|
|
|||
|
|
### Protoc
|
|||
|
|
|
|||
|
|
Once the extension or package is installed, if you wish to generate PHP code
|
|||
|
|
from a `.proto` file, you will also want to install the Protocol Buffers
|
|||
|
|
compiler (protoc), as described in this repository's main `README` file. The
|
|||
|
|
version of `protoc` included in the latest release supports the `--php_out`
|
|||
|
|
option to generate PHP code:
|
|||
|
|
```
|
|||
|
|
protoc --php_out=out_dir test.proto
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
## Usage
|
|||
|
|
|
|||
|
|
For generated code:
|
|||
|
|
https://developers.google.com/protocol-buffers/docs/reference/php-generated
|
|||
|
|
|
|||
|
|
Known Issues
|
|||
|
|
------------
|
|||
|
|
|
|||
|
|
* Missing native support for well known types.
|
|||
|
|
* Missing support for proto2.
|
|||
|
|
* No API provided for clear/copy messages.
|
|||
|
|
* No API provided for encoding/decoding with stream.
|
|||
|
|
* Map fields may not be garbage-collected if there is cycle reference.
|
|||
|
|
* No debug information for messages in c extension.
|
|||
|
|
* HHVM not tested.
|
|||
|
|
* C extension not tested on windows, mac, php 7.0.
|
|||
|
|
* Message name cannot be Empty.
|
|||
|
|
|
|||
|
|
## Development
|
|||
|
|
|
|||
|
|
### Docker Image
|
|||
|
|
|
|||
|
|
We provide a docker image for php development, which is also used in our automatic tests:
|
|||
|
|
```
|
|||
|
|
docker run --security-opt seccomp=unconfined -it protobuftesting/php_8dbe419c6df1a8b3af0ae3a267c112efb436b45c
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### Test Native PHP
|
|||
|
|
|
|||
|
|
```
|
|||
|
|
# Download protobuf
|
|||
|
|
git clone https://github.com/protocolbuffers/protobuf.git
|
|||
|
|
cd protobuf
|
|||
|
|
|
|||
|
|
# Build protoc
|
|||
|
|
./autogen.sh
|
|||
|
|
./configure
|
|||
|
|
make -j4
|
|||
|
|
|
|||
|
|
# Test native php
|
|||
|
|
cd php
|
|||
|
|
composer install
|
|||
|
|
composer test
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### Test C Extension
|
|||
|
|
|
|||
|
|
After you have finished testing the native php, you can test the c extension:
|
|||
|
|
```
|
|||
|
|
cd tests
|
|||
|
|
./test.sh 5.6 # The php runtime version.
|
|||
|
|
# 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
|
|||
|
|
# ls /usr/local for more details
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
If you want to use gdb to debug the c extension, you can do:
|
|||
|
|
```
|
|||
|
|
./gdb_test.sh
|
|||
|
|
```
|