1 2# Overview 3 4This directory contains source code for PHP implementation of gRPC layered on 5shared C library. The same installation guides with more examples and 6tutorials can be seen at [grpc.io](https://grpc.io/docs/languages/php/quickstart). 7gRPC PHP installation instructions for Google Cloud Platform is in 8[cloud.google.com](https://cloud.google.com/php/grpc). 9 10## Environment 11 12### Prerequisites 13 14* `php`: version 7.0 or above (PHP 5.x support is deprecated from Sep 2020). 15* `pecl` 16* `composer` 17* `phpunit` (optional) 18 19 20## Install the _grpc_ extension 21 22There are two ways to install the `grpc` extension. 23* Via `pecl` 24* Build from source 25 26### Install from PECL 27 28```sh 29$ [sudo] pecl install grpc 30``` 31 32or specific version 33 34```sh 35$ [sudo] pecl install grpc-1.30.0 36``` 37 38Please make sure your `gcc` version satisfies the minimum requirement as 39specified [here](https://grpc.io/docs/languages/#official-support). 40 41 42### Install on Windows 43 44You can download the pre-compiled `grpc.dll` extension from the PECL 45[website](https://pecl.php.net/package/grpc). 46 47### Build from source 48 49Clone this repository at the [latest stable release tag](https://github.com/grpc/grpc/releases). 50 51```sh 52$ git clone -b RELEASE_TAG_HERE https://github.com/grpc/grpc 53$ cd grpc 54``` 55 56#### Build the gRPC C core library 57 58```sh 59$ git submodule update --init 60$ EXTRA_DEFINES=GRPC_POSIX_FORK_ALLOW_PTHREAD_ATFORK make 61``` 62 63#### Build and install the `grpc` extension 64 65Compile the `grpc` extension from source 66 67```sh 68$ grpc_root="$(pwd)" 69$ cd src/php/ext/grpc 70$ phpize 71$ GRPC_LIB_SUBDIR=libs/opt ./configure --enable-grpc="${grpc_root}" 72$ make 73$ [sudo] make install 74``` 75 76This will compile and install the `grpc` extension into the 77standard PHP extension directory. You should be able to run 78the [unit tests](#unit-tests), with the `grpc` extension installed. 79 80 81### Update php.ini 82 83After installing the `grpc` extension, make sure you add this line to your 84`php.ini` file, depending on where your PHP installation is, to enable the 85`grpc` extension. 86 87```sh 88extension=grpc.so 89``` 90 91## Composer package 92 93In addition to the `grpc` extension, you will need to install the `grpc/grpc` 94composer package as well. Add this to your project's `composer.json` file. 95 96```json 97 "require": { 98 "grpc/grpc": "~1.30.0" 99 } 100``` 101 102To run tests with generated stub code from `.proto` files, you will also 103need the `composer` and `protoc` binaries. You can find out how to get these 104below. 105 106## Protocol Buffers 107 108gRPC PHP supports 109[protocol buffers](https://developers.google.com/protocol-buffers) 110out-of-the-box. You will need the following things to get started: 111 112* `protoc`: the protobuf compiler binary to generate PHP classes for your 113messages and service definition. 114* `grpc_php_plugin`: a plugin for `protoc` to generate the service stub 115classes. 116* `protobuf.so`: the `protobuf` extension runtime library. 117 118### `protoc` compiler 119 120If you don't have it already, you need to install the protobuf compiler 121`protoc`, version 3.5.0+ (the newer the better) for the current gRPC version. 122If you installed already, make the protobuf version is compatible to the 123grpc version you installed. If you build grpc.so from the souce, you can check 124the version of grpc inside package.xml file. 125 126The compatibility between the grpc and protobuf version is listed as table 127below: 128 129grpc | protobuf | grpc | protobuf | grpc | protobuf 130--- | --- | --- | --- | --- | --- 131v1.0.0 | 3.0.0(GA) | v1.12.0 | 3.5.2 | v1.22.0 | 3.8.0 132v1.0.1 | 3.0.2 | v1.13.1 | 3.5.2 | v1.23.1 | 3.8.0 133v1.1.0 | 3.1.0 | v1.14.2 | 3.5.2 | v1.24.0 | 3.8.0 134v1.2.0 | 3.2.0 | v1.15.1 | 3.6.1 | v1.25.0 | 3.8.0 135v1.2.0 | 3.2.0 | v1.16.1 | 3.6.1 | v1.26.0 | 3.8.0 136v1.3.4 | 3.3.0 | v1.17.2 | 3.6.1 | v1.27.3 | 3.11.2 137v1.3.5 | 3.2.0 | v1.18.0 | 3.6.1 | v1.28.1 | 3.11.2 138v1.4.0 | 3.3.0 | v1.19.1 | 3.6.1 | v1.29.0 | 3.11.2 139v1.6.0 | 3.4.0 | v1.20.1 | 3.7.0 | v1.30.0 | 3.12.2 140v1.8.0 | 3.5.0 | v1.21.3 | 3.7.0 141 142If `protoc` hasn't been installed, you can download the `protoc` binary from 143the protocol buffers 144[Github repository](https://github.com/protocolbuffers/protobuf/releases). 145Then unzip this file and update the environment variable `PATH` to include the 146path to the protoc binary file. 147 148If you really must compile `protoc` from source, you can run the following 149commands, but this is risky because there is no easy way to uninstall / 150upgrade to a newer release. 151 152```sh 153$ cd grpc/third_party/protobuf 154$ ./autogen.sh && ./configure && make 155$ [sudo] make install 156``` 157 158### `grpc_php_plugin` protoc plugin 159 160You need the `grpc_php_plugin` to generate the PHP client stub classes. This 161plugin works with the main `protoc` binary to generate classes that you can 162import into your project. 163 164You can build `grpc_php_plugin` with `cmake`: 165 166```sh 167$ git clone -b RELEASE_TAG_HERE https://github.com/grpc/grpc 168$ cd grpc 169$ git submodule update --init 170$ mkdir -p cmake/build 171$ cd cmake/build 172$ cmake ../.. 173$ make protoc grpc_php_plugin 174``` 175 176The commands above will make `protoc` and `grpc_php_plugin` available 177in `cmake/build/third_party/protobuf/protoc` and `cmake/build/grpc_php_plugin`. 178 179Alternatively, you can also build the `grpc_php_plugin` with `bazel`: 180 181```sh 182$ bazel build @com_google_protobuf//:protoc 183$ bazel build src/compiler:grpc_php_plugin 184``` 185 186The `protoc` binary will be found in 187`bazel-bin/external/com_google_protobuf/protoc`. 188The `grpc_php_plugin` binary will be found in 189`bazel-bin/src/compiler/grpc_php_plugin`. 190 191Plugin may use the new feature of the new protobuf version, thus please also 192make sure that the protobuf version installed is compatible with the grpc 193version you build this plugin. 194 195### `protobuf` runtime library 196 197There are two `protobuf` runtime libraries to choose from. They are identical 198in terms of APIs offered. The C implementation provides better performance, 199while the native implementation is easier to install. 200 201#### C implementation (for better performance) 202 203Install the `protobuf` extension from PECL: 204 205``` sh 206$ [sudo] pecl install protobuf 207``` 208or specific version 209 210``` sh 211$ [sudo] pecl install protobuf-3.12.2 212``` 213 214And add this to your `php.ini` file: 215 216```sh 217extension=protobuf.so 218``` 219 220#### PHP implementation (for easier installation) 221 222Or require the `google/protobuf` composer package. Add this to your 223`composer.json` file: 224 225```json 226 "require": { 227 "google/protobuf": "~v3.12.2" 228 } 229``` 230 231### Generate PHP classes from your service definition 232 233With all the above done, now you can define your message and service definition 234in a `.proto` file and generate the corresponding PHP classes, which you can 235import into your project, with a command similar to the following: 236 237``` 238$ protoc -I=. echo.proto --php_out=. --grpc_out=. \ 239--plugin=protoc-gen-grpc=<path to grpc_php_plugin> 240``` 241 242## Unit Tests 243 244You will need the source code to run tests 245 246```sh 247$ git clone -b RELEASE_TAG_HERE https://github.com/grpc/grpc 248$ cd grpc 249$ git submodule update --init 250``` 251 252Run unit tests 253 254```sh 255$ cd grpc/src/php 256$ ./bin/run_tests.sh 257``` 258 259## Generated Code Tests 260 261This section specifies the prerequisites for running the generated code tests, 262as well as how to run the tests themselves. 263 264### Composer 265 266Install the runtime dependencies via `composer install`. 267 268```sh 269$ cd grpc/src/php 270$ composer install 271``` 272 273 274### Client Stub 275 276The generate client stub classes have already been generated from `.proto` files 277by the `./bin/generate_proto_php.sh` script. 278 279### Run test server 280 281Run a local server serving the `Math` 282[service](https://github.com/grpc/grpc/blob/master/src/proto/math/math.proto#L42). 283 284```sh 285$ cd grpc/src/php/tests/generated_code 286$ npm install 287$ node math_server.js 288``` 289 290### Run test client 291 292Run the generated code tests 293 294```sh 295$ cd grpc/src/php 296$ ./bin/run_gen_code_test.sh 297``` 298 299## Apache, PHP-FPM and Nginx 300 301For more information on how you can run the `grpc` library with Apache, 302PHP-FPM and Nginx, you can check out 303[this guide](https://github.com/grpc/grpc/tree/master/examples/php/echo). 304There you will find a series of Docker images where you can quickly run an 305end-to-end example. 306 307## Misc Config Options 308 309### SSL credentials 310 311Here's how you can specify SSL credentials when creating your PHP client: 312 313```php 314$client = new Helloworld\GreeterClient('localhost:50051', [ 315 'credentials' => Grpc\ChannelCredentials::createSsl( 316 file_get_contents('<path to certificate>')) 317]); 318``` 319 320### pcntl_fork() support 321 322To make sure the `grpc` extension works with `pcntl_fork()` and related 323functions, add the following lines to your `php.ini` file: 324 325``` 326grpc.enable_fork_support = 1 327grpc.poll_strategy = epoll1 328``` 329 330### Tracing and Logging 331 332To turn on gRPC tracing, add the following lines to your `php.ini` file. For 333all possible values of the `grpc.grpc.trace` option, please check 334[this doc](https://github.com/grpc/grpc/blob/master/doc/environment_variables.md). 335 336``` 337grpc.grpc_verbosity=debug 338grpc.grpc_trace=all,-polling,-polling_api,-pollable_refcount,-timer,-timer_check 339grpc.log_filename=/var/log/grpc.log 340``` 341 342> Make sure the log file above is writable, by doing the following: 343> ``` 344> $ sudo touch /var/log/grpc.log 345> $ sudo chmod 666 /var/log/grpc.log 346> ``` 347> Note: The log file does grow pretty quickly depending on how much logs are 348> being printed out. Make sure you have other mechanisms (perhaps another 349> cronjob) to zero out the log file from time to time, 350> e.g. `cp /dev/null /var/log/grpc.log`, or turn these off when logs or tracing 351> are not necessary for debugging purposes. 352 353### User agent string 354 355You can customize the user agent string for your gRPC PHP client by specifying 356this `grpc.primary_user_agent` option when constructing your PHP client: 357 358```php 359$client = new Helloworld\GreeterClient('localhost:50051', [ 360 'credentials' => Grpc\ChannelCredentials::createInsecure(), 361 'grpc.primary_user_agent' => 'my-user-agent-identifier', 362]); 363``` 364 365### Maximum message size 366 367To change the default maximum message size, specify this 368`grpc.max_receive_message_length` option when constructing your PHP client: 369 370```php 371$client = new Helloworld\GreeterClient('localhost:50051', [ 372 'credentials' => Grpc\ChannelCredentials::createInsecure(), 373 'grpc.max_receive_message_length' => 8*1024*1024, 374]); 375``` 376 377### Compression 378 379You can customize the compression behavior on the client side, by specifying the following options when constructing your PHP client. 380 381```php 382$client = new Helloworld\GreeterClient('localhost:50051', [ 383 'credentials' => Grpc\ChannelCredentials::createInsecure(), 384 'grpc.default_compression_algorithm' => 2, 385 'grpc.default_compression_level' => 2, 386]); 387``` 388 389Possible values for `grpc.default_compression_algorithm`: 390 391``` 3920: No compression 3931: Compress with DEFLATE algorithm 3942: Compress with GZIP algorithm 3953: Stream compression with GZIP algorithm 396``` 397 398Possible values for `grpc.default_compression_level`: 399 400``` 4010: None 4021: Low level 4032: Medium level 4043: High level 405``` 406