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/google/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 164It should already been compiled when you run `make` from the root directory 165of this repo. The plugin can be found in the `bins/opt` directory. We are 166planning to provide a better way to download and install the plugin 167in the future. 168 169You can also just build the `grpc_php_plugin` by running: 170 171```sh 172$ git clone -b RELEASE_TAG_HERE https://github.com/grpc/grpc 173$ cd grpc 174$ git submodule update --init 175$ make grpc_php_plugin 176``` 177 178Alternatively, you can also build the `grpc_php_plugin` with `bazel` now: 179 180```sh 181$ bazel build @com_google_protobuf//:protoc 182$ bazel build src/compiler:grpc_php_plugin 183``` 184 185The `protoc` binary will be found in 186`bazel-bin/external/com_google_protobuf/protoc`. 187The `grpc_php_plugin` binary will be found in 188`bazel-bin/src/compiler/grpc_php_plugin`. 189 190Plugin may use the new feature of the new protobuf version, thus please also 191make sure that the protobuf version installed is compatible with the grpc 192version you build this plugin. 193 194### `protobuf` runtime library 195 196There are two `protobuf` runtime libraries to choose from. They are identical 197in terms of APIs offered. The C implementation provides better performance, 198while the native implementation is easier to install. 199 200#### C implementation (for better performance) 201 202Install the `protobuf` extension from PECL: 203 204``` sh 205$ [sudo] pecl install protobuf 206``` 207or specific version 208 209``` sh 210$ [sudo] pecl install protobuf-3.12.2 211``` 212 213And add this to your `php.ini` file: 214 215```sh 216extension=protobuf.so 217``` 218 219#### PHP implementation (for easier installation) 220 221Or require the `google/protobuf` composer package. Add this to your 222`composer.json` file: 223 224```json 225 "require": { 226 "google/protobuf": "~v3.12.2" 227 } 228``` 229 230### Generate PHP classes from your service definition 231 232With all the above done, now you can define your message and service defintion 233in a `.proto` file and generate the corresponding PHP classes, which you can 234import into your project, with a command similar to the following: 235 236``` 237$ protoc -I=. echo.proto --php_out=. --grpc_out=. \ 238--plugin=protoc-gen-grpc=<path to grpc_php_plugin> 239``` 240 241## Unit Tests 242 243You will need the source code to run tests 244 245```sh 246$ git clone -b RELEASE_TAG_HERE https://github.com/grpc/grpc 247$ cd grpc 248$ git submodule update --init 249``` 250 251Run unit tests 252 253```sh 254$ cd grpc/src/php 255$ ./bin/run_tests.sh 256``` 257 258## Generated Code Tests 259 260This section specifies the prerequisites for running the generated code tests, 261as well as how to run the tests themselves. 262 263### Composer 264 265Install the runtime dependencies via `composer install`. 266 267```sh 268$ cd grpc/src/php 269$ composer install 270``` 271 272 273### Client Stub 274 275The generate client stub classes have already been generated from `.proto` files 276by the `./bin/generate_proto_php.sh` script. 277 278### Run test server 279 280Run a local server serving the `Math` 281[service](https://github.com/grpc/grpc/blob/master/src/proto/math/math.proto#L42). 282 283```sh 284$ cd grpc/src/php/tests/generated_code 285$ npm install 286$ node math_server.js 287``` 288 289### Run test client 290 291Run the generated code tests 292 293```sh 294$ cd grpc/src/php 295$ ./bin/run_gen_code_test.sh 296``` 297 298## Apache, PHP-FPM and Nginx 299 300For more information on how you can run the `grpc` library with Apache, 301PHP-FPM and Nginx, you can check out 302[this guide](https://github.com/grpc/grpc/tree/master/examples/php/echo). 303There you will find a series of Docker images where you can quickly run an 304end-to-end example. 305 306## Misc Config Options 307 308### SSL credentials 309 310Here's how you can specify SSL credentials when creating your PHP client: 311 312```php 313$client = new Helloworld\GreeterClient('localhost:50051', [ 314 'credentials' => Grpc\ChannelCredentials::createSsl( 315 file_get_contents('<path to certificate>')) 316]); 317``` 318 319### pcntl_fork() support 320 321To make sure the `grpc` extension works with `pcntl_fork()` and related 322functions, add the following lines to your `php.ini` file: 323 324``` 325grpc.enable_fork_support = 1 326grpc.poll_strategy = epoll1 327``` 328 329### Tracing and Logging 330 331To turn on gRPC tracing, add the following lines to your `php.ini` file. For 332all possible values of the `grpc.grpc.trace` option, please check 333[this doc](https://github.com/grpc/grpc/blob/master/doc/environment_variables.md). 334 335``` 336grpc.grpc_verbosity=debug 337grpc.grpc_trace=all,-polling,-polling_api,-pollable_refcount,-timer,-timer_check 338grpc.log_filename=/var/log/grpc.log 339``` 340 341> Make sure the log file above is writable, by doing the following: 342> ``` 343> $ sudo touch /var/log/grpc.log 344> $ sudo chmod 666 /var/log/grpc.log 345> ``` 346> Note: The log file does grow pretty quickly depending on how much logs are 347> being printed out. Make sure you have other mechanisms (perhaps another 348> cronjob) to zero out the log file from time to time, 349> e.g. `cp /dev/null /var/log/grpc.log`, or turn these off when logs or tracing 350> are not necessary for debugging purposes. 351 352### User agent string 353 354You can customize the user agent string for your gRPC PHP client by specifying 355this `grpc.primary_user_agent` option when constructing your PHP client: 356 357```php 358$client = new Helloworld\GreeterClient('localhost:50051', [ 359 'credentials' => Grpc\ChannelCredentials::createInsecure(), 360 'grpc.primary_user_agent' => 'my-user-agent-identifier', 361]); 362``` 363 364### Maximum message size 365 366To change the default maximum message size, specify this 367`grpc.max_receive_message_length` option when constructing your PHP client: 368 369```php 370$client = new Helloworld\GreeterClient('localhost:50051', [ 371 'credentials' => Grpc\ChannelCredentials::createInsecure(), 372 'grpc.max_receive_message_length' => 8*1024*1024, 373]); 374``` 375 376### Compression 377 378You can customize the compression behavior on the client side, by specifying the following options when constructing your PHP client. 379 380```php 381$client = new Helloworld\GreeterClient('localhost:50051', [ 382 'credentials' => Grpc\ChannelCredentials::createInsecure(), 383 'grpc.default_compression_algorithm' => 2, 384 'grpc.default_compression_level' => 2, 385]); 386``` 387 388Possible values for `grpc.default_compression_algorithm`: 389 390``` 3910: No compression 3921: Compress with DEFLATE algorithm 3932: Compress with GZIP algorithm 3943: Stream compression with GZIP algorithm 395``` 396 397Possible values for `grpc.default_compression_level`: 398 399``` 4000: None 4011: Low level 4022: Medium level 4033: High level 404``` 405