GRPC PHP
1.71.0
|
This directory contains source code for PHP implementation of gRPC layered on shared C library. The same installation guides with more examples and tutorials can be seen at grpc.io. gRPC PHP installation instructions for Google Cloud Platform is in cloud.google.com.
php
: version 7.0 or above (PHP 5.x support is deprecated from Sep 2020).pecl
composer
phpunit
(optional)There are two ways to install the grpc
extension.
pecl
or specific version
Please make sure your gcc
version satisfies the minimum requirement as specified here.
You can download the pre-compiled grpc.dll
extension from the PECL website.
Clone this repository at the latest stable release tag.
Compile the grpc
extension from source
This will compile and install the grpc
extension into the standard PHP extension directory. You should be able to run the unit tests, with the grpc
extension installed.
After installing the grpc
extension, make sure you add this line to your php.ini
file, depending on where your PHP installation is, to enable the grpc
extension.
In addition to the grpc
extension, you will need to install the grpc/grpc
composer package as well. Add this to your project's composer.json
file.
To run tests with generated stub code from .proto
files, you will also need the composer
and protoc
binaries. You can find out how to get these below.
gRPC PHP supports protocol buffers out-of-the-box. You will need the following things to get started:
protoc
: the protobuf compiler binary to generate PHP classes for your messages and service definition.grpc_php_plugin
: a plugin for protoc
to generate the service stub classes.protobuf.so
: the protobuf
extension runtime library.If you don't have it already, you need to install the protobuf compiler protoc
, version 3.5.0+ (the newer the better) for the current gRPC version. If you installed already, make the protobuf version is compatible to the grpc version you installed. If you build grpc.so from the souce, you can check the version of grpc inside package.xml file.
The compatibility between the grpc and protobuf version is listed as table below:
grpc | protobuf | grpc | protobuf | grpc | protobuf |
---|---|---|---|---|---|
v1.0.0 | 3.0.0(GA) | v1.12.0 | 3.5.2 | v1.22.0 | 3.8.0 |
v1.0.1 | 3.0.2 | v1.13.1 | 3.5.2 | v1.23.1 | 3.8.0 |
v1.1.0 | 3.1.0 | v1.14.2 | 3.5.2 | v1.24.0 | 3.8.0 |
v1.2.0 | 3.2.0 | v1.15.1 | 3.6.1 | v1.25.0 | 3.8.0 |
v1.2.0 | 3.2.0 | v1.16.1 | 3.6.1 | v1.26.0 | 3.8.0 |
v1.3.4 | 3.3.0 | v1.17.2 | 3.6.1 | v1.27.3 | 3.11.2 |
v1.3.5 | 3.2.0 | v1.18.0 | 3.6.1 | v1.28.1 | 3.11.2 |
v1.4.0 | 3.3.0 | v1.19.1 | 3.6.1 | v1.29.0 | 3.11.2 |
v1.6.0 | 3.4.0 | v1.20.1 | 3.7.0 | v1.30.0 | 3.12.2 |
v1.8.0 | 3.5.0 | v1.21.3 | 3.7.0
If protoc
hasn't been installed, you can download the protoc
binary from the protocol buffers Github repository. Then unzip this file and update the environment variable PATH
to include the path to the protoc binary file.
If you really must compile protoc
from source, you can run the following commands, but this is risky because there is no easy way to uninstall / upgrade to a newer release.
You need the grpc_php_plugin
to generate the PHP client stub classes. This plugin works with the main protoc
binary to generate classes that you can import into your project.
You can build grpc_php_plugin
with cmake
:
The commands above will make protoc
and grpc_php_plugin
available in cmake/build/third_party/protobuf/protoc
and cmake/build/grpc_php_plugin
.
Alternatively, you can also build the grpc_php_plugin
with bazel
:
The protoc
binary will be found in bazel-bin/external/com_google_protobuf/protoc
. The grpc_php_plugin
binary will be found in bazel-bin/src/compiler/grpc_php_plugin
.
Plugin may use the new feature of the new protobuf version, thus please also make sure that the protobuf version installed is compatible with the grpc version you build this plugin.
There are two protobuf
runtime libraries to choose from. They are identical in terms of APIs offered. The C implementation provides better performance, while the native implementation is easier to install.
Install the protobuf
extension from PECL:
or specific version
And add this to your php.ini
file:
Or require the google/protobuf
composer package. Add this to your composer.json
file:
With all the above done, now you can define your message and service definition in a .proto
file and generate the corresponding PHP classes, which you can import into your project, with a command similar to the following:
You will need the source code to run tests
Run unit tests
This section specifies the prerequisites for running the generated code tests, as well as how to run the tests themselves.
Install the runtime dependencies via composer install
.
The generate client stub classes have already been generated from .proto
files by the ./bin/generate_proto_php.sh
script.
Run a local server serving the Math
service.
Run the generated code tests
For more information on how you can run the grpc
library with Apache, PHP-FPM and Nginx, you can check out this guide. There you will find a series of Docker images where you can quickly run an end-to-end example.
Here's how you can specify SSL credentials when creating your PHP client:
To make sure the grpc
extension works with pcntl_fork()
and related functions, add the following lines to your php.ini
file:
To turn on gRPC tracing, add the following lines to your php.ini
file. For all possible values of the grpc.grpc.trace
option, please check this doc.
Make sure the log file above is writable, by doing the following:
$ sudo touch /var/log/grpc.log$ sudo chmod 666 /var/log/grpc.logNote: The log file does grow pretty quickly depending on how much logs are being printed out. Make sure you have other mechanisms (perhaps another cronjob) to zero out the log file from time to time, e.g.
cp /dev/null /var/log/grpc.log
, or turn these off when logs or tracing are not necessary for debugging purposes.
You can customize the user agent string for your gRPC PHP client by specifying this grpc.primary_user_agent
option when constructing your PHP client:
To change the default maximum message size, specify this grpc.max_receive_message_length
option when constructing your PHP client:
You can customize the compression behavior on the client side, by specifying the following options when constructing your PHP client.
Possible values for grpc.default_compression_algorithm
:
Possible values for grpc.default_compression_level
: