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/quickstart/php.html). 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### Prerequisite: 13 14* `php` 5.5 or above, 7.0 or above 15* `pecl` 16* `composer` 17* `phpunit` (optional) 18 19**Install PHP and PECL on Ubuntu/Debian:** 20 21For PHP5: 22 23```sh 24$ sudo apt-get install php5 php5-dev php-pear phpunit 25``` 26 27For PHP7: 28 29```sh 30$ sudo apt-get install php7.0 php7.0-dev php-pear phpunit 31``` 32or 33```sh 34$ sudo apt-get install php php-dev php-pear phpunit 35``` 36 37**Install PHP and PECL on CentOS/RHEL 7:** 38```sh 39$ sudo rpm -Uvh https://dl.fedoraproject.org/pub/epel/epel-release-latest-7.noarch.rpm 40$ sudo rpm -Uvh https://mirror.webtatic.com/yum/el7/webtatic-release.rpm 41$ sudo yum install php56w php56w-devel php-pear phpunit gcc zlib-devel 42``` 43 44**Install PHP and PECL on Mac:** 45```sh 46$ brew install homebrew/php/php56-grpc 47$ curl -O http://pear.php.net/go-pear.phar 48$ sudo php -d detect_unicode=0 go-pear.phar 49``` 50 51**Install Composer (Linux or Mac):** 52```sh 53$ curl -sS https://getcomposer.org/installer | php 54$ sudo mv composer.phar /usr/local/bin/composer 55``` 56 57**Install PHPUnit (Linux or Mac):** 58```sh 59$ wget https://phar.phpunit.de/phpunit-old.phar 60$ chmod +x phpunit-old.phar 61$ sudo mv phpunit-old.phar /usr/bin/phpunit 62``` 63 64## Install the gRPC PHP extension 65 66There are two ways to install gRPC PHP extension. 67* `pecl` 68* `build from source` 69 70### Using PECL 71 72```sh 73sudo pecl install grpc 74``` 75 76or specific version 77 78```sh 79sudo pecl install grpc-1.12.0 80``` 81 82Note: for users on CentOS/RHEL 6, unfortunately this step won’t work. 83Please follow the instructions below to compile the PECL extension from source. 84 85#### Install on Windows 86 87You can download the pre-compiled gRPC extension from the PECL 88[website](https://pecl.php.net/package/grpc) 89 90### Build from Source with gRPC C core library 91 92Clone this repository 93 94```sh 95$ git clone -b $(curl -L https://grpc.io/release) https://github.com/grpc/grpc 96``` 97 98#### Build and install the gRPC C core library 99 100```sh 101$ cd grpc 102$ git submodule update --init 103$ make 104$ sudo make install 105``` 106 107#### Build and install gRPC PHP extension 108 109Compile the gRPC PHP extension 110 111```sh 112$ cd grpc/src/php/ext/grpc 113$ phpize 114$ ./configure 115$ make 116$ sudo make install 117``` 118 119This will compile and install the gRPC PHP extension into the 120standard PHP extension directory. You should be able to run 121the [unit tests](#unit-tests), with the PHP extension installed. 122 123 124### Update php.ini 125 126After installing the gRPC extension, make sure you add this line 127to your `php.ini` file, (e.g. `/etc/php5/cli/php.ini`, 128`/etc/php5/apache2/php.ini`, or `/usr/local/etc/php/5.6/php.ini`), 129depending on where your PHP installation is. 130 131```sh 132extension=grpc.so 133``` 134 135**Add the gRPC PHP library as a Composer dependency** 136 137You need to add this to your project's `composer.json` file. 138 139``` 140 "require": { 141 "grpc/grpc": "v1.12.0" 142 } 143``` 144 145To run tests with generated stub code from `.proto` files, you will also 146need the `composer` and `protoc` binaries. You can find out how to get these below. 147 148## Install other prerequisites for both Mac OS X and Linux 149 150* `protoc: protobuf compiler` 151* `protobuf.so: protobuf runtime library` 152* `grpc_php_plugin: Generates PHP gRPC service interface out of Protobuf IDL` 153 154### Install Protobuf compiler 155 156If you don't have it already, you need to install the protobuf compiler 157`protoc`, version 3.5.0+ (the newer the better) for the current gRPC version. 158If you installed already, make the protobuf version is compatible to the 159grpc version you installed. If you build grpc.so from the souce, you can check 160the version of grpc inside package.xml file. 161 162The compatibility between the grpc and protobuf version is listed as table below: 163 164grpc | protobuf 165--- | --- 166v1.0.0 | 3.0.0(GA) 167v1.0.1 | 3.0.2 168v1.1.0 | 3.1.0 169v1.2.0 | 3.2.0 170v1.2.0 | 3.2.0 171v1.3.4 | 3.3.0 172v1.3.5 | 3.2.0 173v1.4.0 | 3.3.0 174v1.6.0 | 3.4.0 175v1.8.0 | 3.5.0 176v1.12.0 | 3.5.2 177 178If `protoc` hasn't been installed, you can download the `protoc` binaries from 179[the protocol buffers Github repository](https://github.com/google/protobuf/releases). 180Then unzip this file and update the environment variable `PATH` to include the path to 181the protoc binary file. 182 183If you really must compile `protoc` from source, you can run the following 184commands, but this is risky because there is no easy way to uninstall / 185upgrade to a newer release. 186 187```sh 188$ cd grpc/third_party/protobuf 189$ ./autogen.sh && ./configure && make 190$ sudo make install 191``` 192 193### Protobuf Runtime library 194 195There are two protobuf runtime libraries to choose from. They are identical 196in terms of APIs offered. The C implementation provides better performance, 197while the native implementation is easier to install. Make sure the installed 198protobuf version works with grpc version. 199 200#### 1. C implementation (for better performance) 201 202``` sh 203$ sudo pecl install protobuf 204``` 205or specific version 206 207``` sh 208$ sudo pecl install protobuf-3.5.1.1 209``` 210 211Add this to your `php.ini` file: 212 213```sh 214extension=protobuf.so 215``` 216 217#### 2. PHP implementation (for easier installation) 218 219Add this to your `composer.json` file: 220 221``` 222 "require": { 223 "google/protobuf": "^v3.5.0" 224 } 225``` 226 227### PHP Protoc Plugin 228 229You need the gRPC PHP protoc plugin to generate the client stub classes. 230It can generate server and client code from .proto service definitions. 231 232It should already been compiled when you run `make` from the root directory 233of this repo. The plugin can be found in the `bins/opt` directory. We are 234planning to provide a better way to download and install the plugin 235in the future. 236 237You can also just build the gRPC PHP protoc plugin by running: 238 239```sh 240$ git clone -b $(curl -L https://grpc.io/release) https://github.com/grpc/grpc 241$ cd grpc 242$ git submodule update --init 243$ make grpc_php_plugin 244``` 245 246Plugin may use the new feature of the new protobuf version, thus please also 247make sure that the protobuf version installed is compatible with the grpc version 248you build this plugin. 249 250## Unit Tests 251 252You will need the source code to run tests 253 254```sh 255$ git clone -b $(curl -L https://grpc.io/release) https://github.com/grpc/grpc 256$ cd grpc 257$ git submodule update --init 258``` 259 260Run unit tests 261 262```sh 263$ cd grpc/src/php 264$ ./bin/run_tests.sh 265``` 266 267## Generated Code Tests 268 269This section specifies the prerequisites for running the generated code tests, 270as well as how to run the tests themselves. 271 272### Composer 273 274Install the runtime dependencies via `composer install`. 275 276```sh 277$ cd grpc/src/php 278$ composer install 279``` 280 281 282### Client Stub 283 284Generate client stub classes from `.proto` files 285 286```sh 287$ cd grpc/src/php 288$ ./bin/generate_proto_php.sh 289``` 290 291### Run test server 292 293Run a local server serving the math services. Please see [Node][] for how to 294run an example server. 295 296```sh 297$ cd grpc 298$ npm install 299$ node src/node/test/math/math_server.js 300``` 301 302### Run test client 303 304Run the generated code tests 305 306```sh 307$ cd grpc/src/php 308$ ./bin/run_gen_code_test.sh 309``` 310 311## Use the gRPC PHP extension with Apache 312 313Install `apache2`, in addition to `php5` above 314 315```sh 316$ sudo apt-get install apache2 317``` 318 319Add this line to your `php.ini` file, e.g. `/etc/php5/apache2/php.ini` 320or `/etc/php/7.0/apache2/php.ini` 321 322```sh 323extension=grpc.so 324``` 325 326Restart apache 327 328```sh 329$ sudo service apache2 restart 330``` 331 332Make sure the Node math server is still running, as above. 333 334```sh 335$ cd grpc 336$ npm install 337$ node src/node/test/math/math_server.js 338``` 339 340Make sure you have run `composer install` to generate the `vendor/autoload.php` file 341 342```sh 343$ cd grpc/src/php 344$ composer install 345``` 346 347Make sure you have generated the client stubs 348 349```sh 350$ ./bin/generate_proto_php.sh 351``` 352 353Copy the `math_client.php` file into your Apache document root, e.g. 354 355```sh 356$ cp tests/generated_code/math_client.php /var/www/html 357``` 358 359You may have to fix the first line to point the includes to your installation: 360 361```php 362include 'vendor/autoload.php'; 363``` 364 365Connect to `localhost/math_client.php` in your browser, or run this from command line: 366 367```sh 368$ curl localhost/math_client.php 369``` 370 371## Use the gRPC PHP extension with Nginx/PHP-FPM 372 373Install `nginx` and `php5-fpm`, in addition to `php5` above 374 375```sh 376$ sudo apt-get install nginx php5-fpm 377 378OR 379 380$ sudo apt-get install nginx php7.0-fpm 381``` 382 383Add this line to your `php.ini` file, e.g. `/etc/php5/fpm/php.ini` 384 385```sh 386extension=grpc.so 387``` 388 389Uncomment the following lines in your `/etc/nginx/sites-available/default` file: 390 391``` 392location ~ \.php$ { 393 include snippets/fastcgi-php.conf; 394 fastcgi_pass unix:/var/run/php5-fpm.sock; 395} 396``` 397 398Restart nginx and php-fpm 399 400```sh 401$ sudo service nginx restart 402$ sudo service php5-fpm restart 403``` 404 405Make sure the Node math server is still running, as above. 406 407```sh 408$ cd grpc 409$ npm install 410$ node src/node/test/math/math_server.js 411``` 412 413Make sure you have run `composer install` to generate the `vendor/autoload.php` file 414 415```sh 416$ cd grpc/src/php 417$ composer install 418``` 419 420Make sure you have generated the client stubs 421 422```sh 423$ ./bin/generate_proto_php.sh 424``` 425 426Copy the `math_client.php` file into your Nginx document root, e.g. 427 428```sh 429$ cp tests/generated_code/math_client.php /var/www/html 430``` 431 432You may have to fix the first line to point the includes to your installation: 433 434```php 435include 'vendor/autoload.php'; 436``` 437 438Connect to `localhost/math_client.php` in your browser, or run this from command line: 439 440```sh 441$ curl localhost/math_client.php 442``` 443 444[Node]:https://github.com/grpc/grpc/tree/master/src/node/examples 445