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