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
$ [sudo] pecl install grpc
or specific version
$ [sudo] pecl install grpc-1.30.0
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.
$ git clone -b RELEASE_TAG_HERE https://github.com/grpc/grpc $ cd grpc
$ git submodule update --init $ EXTRA_DEFINES=GRPC_POSIX_FORK_ALLOW_PTHREAD_ATFORK make
grpc
extensionCompile the grpc
extension from source
$ grpc_root="$(pwd)" $ cd src/php/ext/grpc $ phpize $ GRPC_LIB_SUBDIR=libs/opt ./configure --enable-grpc="${grpc_root}" $ make $ [sudo] make install
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.
extension=grpc.so
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.
"require": { "grpc/grpc": "~1.30.0" }
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.protoc
compilerIf 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.
$ cd grpc/third_party/protobuf $ ./autogen.sh && ./configure && make $ [sudo] make install
grpc_php_plugin
protoc pluginYou 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
:
$ git clone -b RELEASE_TAG_HERE https://github.com/grpc/grpc $ cd grpc $ git submodule update --init $ mkdir -p cmake/build $ cd cmake/build $ cmake ../.. $ make protoc grpc_php_plugin
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
:
$ bazel build @com_google_protobuf//:protoc $ bazel build src/compiler:grpc_php_plugin
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.
protobuf
runtime libraryThere 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:
$ [sudo] pecl install protobuf
or specific version
$ [sudo] pecl install protobuf-3.12.2
And add this to your php.ini
file:
extension=protobuf.so
Or require the google/protobuf
composer package. Add this to your composer.json
file:
"require": { "google/protobuf": "~v3.12.2" }
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:
$ protoc -I=. echo.proto --php_out=. --grpc_out=. \ --plugin=protoc-gen-grpc=<path to grpc_php_plugin>
You will need the source code to run tests
$ git clone -b RELEASE_TAG_HERE https://github.com/grpc/grpc $ cd grpc $ git submodule update --init
Run unit tests
$ cd grpc/src/php $ ./bin/run_tests.sh
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
.
$ cd grpc/src/php $ 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.
$ cd grpc/src/php/tests/generated_code $ npm install $ node math_server.js
Run the generated code tests
$ cd grpc/src/php $ ./bin/run_gen_code_test.sh
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:
$client = new Helloworld\GreeterClient('localhost:50051', [ 'credentials' => Grpc\ChannelCredentials::createSsl( file_get_contents('<path to certificate>')) ]);
To make sure the grpc
extension works with pcntl_fork()
and related functions, add the following lines to your php.ini
file:
grpc.enable_fork_support = 1 grpc.poll_strategy = epoll1
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.
grpc.grpc_verbosity=debug grpc.grpc_trace=all,-polling,-polling_api,-pollable_refcount,-timer,-timer_check grpc.log_filename=/var/log/grpc.log
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:
$client = new Helloworld\GreeterClient('localhost:50051', [ 'credentials' => Grpc\ChannelCredentials::createInsecure(), 'grpc.primary_user_agent' => 'my-user-agent-identifier', ]);
To change the default maximum message size, specify this grpc.max_receive_message_length
option when constructing your PHP client:
$client = new Helloworld\GreeterClient('localhost:50051', [ 'credentials' => Grpc\ChannelCredentials::createInsecure(), 'grpc.max_receive_message_length' => 8*1024*1024, ]);
You can customize the compression behavior on the client side, by specifying the following options when constructing your PHP client.
$client = new Helloworld\GreeterClient('localhost:50051', [ 'credentials' => Grpc\ChannelCredentials::createInsecure(), 'grpc.default_compression_algorithm' => 2, 'grpc.default_compression_level' => 2, ]);
Possible values for grpc.default_compression_algorithm
:
0: No compression 1: Compress with DEFLATE algorithm 2: Compress with GZIP algorithm 3: Stream compression with GZIP algorithm
Possible values for grpc.default_compression_level
:
0: None 1: Low level 2: Medium level 3: High level