src/php/README.md

   1
   2 # Overview
   3
   4 This directory contains source code for PHP implementation of gRPC layered on
   5 shared C library. The same installation guides with more examples and
   6 tutorials can be seen at [grpc.io](https://grpc.io/docs/languages/php/quickstart).
   7 gRPC 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
  22 There 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
  32 or specific version
  33
  34 ```sh
  35 $ [sudo] pecl install grpc-1.30.0
  36 ```
  37
  38 Please make sure your `gcc` version satisfies the minimum requirement as
  39 specified [here](https://grpc.io/docs/languages/#official-support).
  40
  41
  42 ### Install on Windows
  43
  44 You 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
  49 Clone 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
  65 Compile 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
  76 This will compile and install the `grpc` extension into the
  77 standard PHP extension directory. You should be able to run
  78 the [unit tests](#unit-tests), with the `grpc` extension installed.
  79
  80
  81 ### Update php.ini
  82
  83 After 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
  88 extension=grpc.so
  89 ```
  90
  91 ## Composer package
  92
  93 In addition to the `grpc` extension, you will need to install the `grpc/grpc`
  94 composer 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
 102 To run tests with generated stub code from `.proto` files, you will also
 103 need the `composer` and `protoc` binaries. You can find out how to get these
 104 below.
 105
 106 ## Protocol Buffers
 107
 108 gRPC PHP supports
 109 [protocol buffers](https://developers.google.com/protocol-buffers)
 110 out-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
 113 messages and service definition.
 114 * `grpc_php_plugin`: a plugin for `protoc` to generate the service stub
 115 classes.
 116 * `protobuf.so`: the `protobuf` extension runtime library.
 117
 118 ### `protoc` compiler
 119
 120 If 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.
 122 If you installed already, make the protobuf version is compatible to the
 123 grpc version you installed. If you build grpc.so from the souce, you can check
 124 the version of grpc inside package.xml file.
 125
 126 The compatibility between the grpc and protobuf version is listed as table
 127 below:
 128
 129 grpc | protobuf | grpc | protobuf | grpc | protobuf
 130 --- | --- | --- | --- | --- | ---
 131 v1.0.0 | 3.0.0(GA) | v1.12.0 | 3.5.2 | v1.22.0 | 3.8.0
 132 v1.0.1 | 3.0.2 | v1.13.1 | 3.5.2 | v1.23.1 | 3.8.0
 133 v1.1.0 | 3.1.0  | v1.14.2 | 3.5.2 | v1.24.0 | 3.8.0
 134 v1.2.0 | 3.2.0  | v1.15.1 | 3.6.1 | v1.25.0 | 3.8.0
 135 v1.2.0 | 3.2.0  | v1.16.1 | 3.6.1 | v1.26.0 | 3.8.0
 136 v1.3.4 | 3.3.0  | v1.17.2 | 3.6.1 | v1.27.3 | 3.11.2
 137 v1.3.5 | 3.2.0 | v1.18.0 | 3.6.1 | v1.28.1 | 3.11.2
 138 v1.4.0 | 3.3.0  | v1.19.1 | 3.6.1 | v1.29.0 | 3.11.2
 139 v1.6.0 | 3.4.0 | v1.20.1 | 3.7.0 | v1.30.0 | 3.12.2
 140 v1.8.0 | 3.5.0 | v1.21.3 | 3.7.0
 141
 142 If `protoc` hasn't been installed, you can download the `protoc` binary from
 143 the protocol buffers
 144 [Github repository](https://github.com/google/protobuf/releases).
 145 Then unzip this file and update the environment variable `PATH` to include the
 146 path to the protoc binary file.
 147
 148 If you really must compile `protoc` from source, you can run the following
 149 commands, but this is risky because there is no easy way to uninstall /
 150 upgrade 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
 160 You need the `grpc_php_plugin` to generate the PHP client stub classes. This
 161 plugin works with the main `protoc` binary to generate classes that you can
 162 import into your project.
 163
 164 It should already been compiled when you run `make` from the root directory
 165 of this repo. The plugin can be found in the `bins/opt` directory. We are
 166 planning to provide a better way to download and install the plugin
 167 in the future.
 168
 169 You 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
 178 Alternatively, 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
 185 The `protoc` binary will be found in
 186 `bazel-bin/external/com_google_protobuf/protoc`.
 187 The `grpc_php_plugin` binary will be found in
 188 `bazel-bin/src/compiler/grpc_php_plugin`.
 189
 190 Plugin may use the new feature of the new protobuf version, thus please also
 191 make sure that the protobuf version installed is compatible with the grpc
 192 version you build this plugin.
 193
 194 ### `protobuf` runtime library
 195
 196 There are two `protobuf` runtime libraries to choose from. They are identical
 197 in terms of APIs offered. The C implementation provides better performance,
 198 while the native implementation is easier to install.
 199
 200 #### C implementation (for better performance)
 201
 202 Install the `protobuf` extension from PECL:
 203
 204 ``` sh
 205 $ [sudo] pecl install protobuf
 206 ```
 207 or specific version
 208
 209 ``` sh
 210 $ [sudo] pecl install protobuf-3.12.2
 211 ```
 212
 213 And add this to your `php.ini` file:
 214
 215 ```sh
 216 extension=protobuf.so
 217 ```
 218
 219 #### PHP implementation (for easier installation)
 220
 221 Or 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
 232 With all the above done, now you can define your message and service defintion
 233 in a `.proto` file and generate the corresponding PHP classes, which you can
 234 import 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
 243 You 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
 251 Run unit tests
 252
 253 ```sh
 254 $ cd grpc/src/php
 255 $ ./bin/run_tests.sh
 256 ```
 257
 258 ## Generated Code Tests
 259
 260 This section specifies the prerequisites for running the generated code tests,
 261 as well as how to run the tests themselves.
 262
 263 ### Composer
 264
 265 Install the runtime dependencies via `composer install`.
 266
 267 ```sh
 268 $ cd grpc/src/php
 269 $ composer install
 270 ```
 271
 272
 273 ### Client Stub
 274
 275 The generate client stub classes have already been generated from `.proto` files
 276 by the `./bin/generate_proto_php.sh` script.
 277
 278 ### Run test server
 279
 280 Run 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
 291 Run 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
 300 For more information on how you can run the `grpc` library with Apache,
 301 PHP-FPM and Nginx, you can check out
 302 [this guide](https://github.com/grpc/grpc/tree/master/examples/php/echo).
 303 There you will find a series of Docker images where you can quickly run an
 304 end-to-end example.
 305
 306 ## Misc Config Options
 307
 308 ### SSL credentials
 309
 310 Here'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
 321 To make sure the `grpc` extension works with `pcntl_fork()` and related
 322 functions, add the following lines to your `php.ini` file:
 323
 324 ```
 325 grpc.enable_fork_support = 1
 326 grpc.poll_strategy = epoll1
 327 ```
 328
 329 ### Tracing and Logging
 330
 331 To turn on gRPC tracing, add the following lines to your `php.ini` file. For
 332 all 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 ```
 336 grpc.grpc_verbosity=debug
 337 grpc.grpc_trace=all,-polling,-polling_api,-pollable_refcount,-timer,-timer_check
 338 grpc.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
 354 You can customize the user agent string for your gRPC PHP client by specifying
 355 this `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
 366 To 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
 378 You 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
 388 Possible values for `grpc.default_compression_algorithm`:
 389
 390 ```
 391 0: No compression
 392 1: Compress with DEFLATE algorithm
 393 2: Compress with GZIP algorithm
 394 3: Stream compression with GZIP algorithm
 395 ```
 396
 397 Possible values for `grpc.default_compression_level`:
 398
 399 ```
 400 0: None
 401 1: Low level
 402 2: Medium level
 403 3: High level
 404 ```