• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
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