Merge pull request #5632 from stanley-cheung/php-update-readme
Doc Fixit: PHP update readme
diff --git a/examples/php/README.md b/examples/php/README.md
index 8fb0608..ea9ccb6 100644
--- a/examples/php/README.md
+++ b/examples/php/README.md
@@ -4,16 +4,15 @@
PREREQUISITES
-------------
-This requires PHP 5.5 or greater.
+This requires `php` >=5.5, `phpize`, `pecl`, `phpunit`
INSTALL
-------
- - On Mac OS X, install [homebrew][]. Run the following command to install gRPC.
+ - Install the gRPC PHP extension
```sh
- $ curl -fsSL https://goo.gl/getgrpc | bash -s php
+ $ [sudo] pecl install grpc-beta
```
- This will download and run the [gRPC install script][] and compile the gRPC PHP extension.
- Clone this repository
@@ -37,6 +36,7 @@
Please follow the instruction in [Node][] to run the server
```
$ cd examples/node
+ $ npm install
$ nodejs greeter_server.js
```
@@ -58,7 +58,5 @@
You can find a more detailed tutorial in [gRPC Basics: PHP][]
-[homebrew]:http://brew.sh
-[gRPC install script]:https://raw.githubusercontent.com/grpc/homebrew-grpc/master/scripts/install
[Node]:https://github.com/grpc/grpc/tree/master/examples/node
[gRPC Basics: PHP]:http://www.grpc.io/docs/tutorials/basic/php.html
diff --git a/src/php/README.md b/src/php/README.md
index b368482..cf8f2c1 100644
--- a/src/php/README.md
+++ b/src/php/README.md
@@ -9,14 +9,21 @@
## Environment
-Prerequisite: PHP 5.5 or later, `phpunit`, `pecl`
+Prerequisite: `php` >=5.5, `phpize`, `pecl`, `phpunit`
-**Linux:**
+**Linux (Debian):**
```sh
$ sudo apt-get install php5 php5-dev php-pear
```
+**Linux (CentOS):**
+
+```sh
+$ yum install php55w
+$ yum --enablerepo=remi,remi-php55 install php-devel php-pear
+```
+
**Mac OS X:**
```sh
@@ -24,11 +31,11 @@
$ sudo php -d detect_unicode=0 go-pear.phar
```
-**PHPUnit: (Both Linux and Mac OS X)**
+**PHPUnit:**
```sh
-$ curl https://phar.phpunit.de/phpunit.phar -o phpunit.phar
-$ chmod +x phpunit.phar
-$ sudo mv phpunit.phar /usr/local/bin/phpunit
+$ wget https://phar.phpunit.de/phpunit-old.phar
+$ chmod +x phpunit-old.phar
+$ sudo mv phpunit-old.phar /usr/bin/phpunit
```
## Quick Install
@@ -39,15 +46,22 @@
sudo pecl install grpc-beta
```
+This will compile and install the gRPC PHP extension into the standard PHP extension directory. You should be able to run the [unit tests](#unit-tests), with the PHP extension installed.
+
+To run tests with generated stub code from `.proto` files, you will also need the `composer`, `protoc` and `protoc-gen-php` binaries. You can find out how to get these [below](#generated-code-tests).
+
## Build from Source
+
+### gRPC C core library
+
Clone this repository
```sh
$ git clone https://github.com/grpc/grpc.git
```
-Build and install the gRPC C core libraries
+Build and install the gRPC C core library
```sh
$ cd grpc
@@ -56,20 +70,15 @@
$ sudo make install
```
-Note: you may encounter a warning about the Protobuf compiler `protoc` 3.0.0+ not being installed. The following might help, and will be useful later on when we need to compile the `protoc-gen-php` tool.
+### gRPC PHP extension
-```sh
-$ cd grpc/third_party/protobuf
-$ sudo make install # 'make' should have been run by core grpc
-```
-
-Install the gRPC PHP extension
+Install the gRPC PHP extension from PECL
```sh
$ sudo pecl install grpc-beta
```
-OR
+Or, compile from source
```sh
$ cd grpc/src/php/ext/grpc
@@ -79,23 +88,24 @@
$ sudo make install
```
+### Update php.ini
+
Add this line to your `php.ini` file, e.g. `/etc/php5/cli/php.ini`
```sh
extension=grpc.so
```
-Install Composer
+## Unit Tests
+
+You will need the source code to run tests
```sh
-$ cd grpc/src/php
-$ curl -sS https://getcomposer.org/installer | php
-$ sudo mv composer.phar /usr/local/bin/composer
-$ composer install
+$ git clone https://github.com/grpc/grpc.git
+$ cd grpc
+$ git pull --recurse-submodules && git submodule update --init --recursive
```
-## Unit Tests
-
Run unit tests
```sh
@@ -105,32 +115,71 @@
## Generated Code Tests
-Install `protoc-gen-php`
+This section specifies the prerequisites for running the generated code tests, as well as how to run the tests themselves.
+
+### Composer
+
+If you don't have it already, install `composer` to pull in some runtime dependencies based on the `composer.json` file.
```sh
-$ cd grpc/src/php/vendor/datto/protobuf-php
+$ curl -sS https://getcomposer.org/installer | php
+$ sudo mv composer.phar /usr/local/bin/composer
+
+$ cd grpc/src/php
+$ composer install
+```
+
+### Protobuf compiler
+
+Again if you don't have it already, you need to install the protobuf compiler `protoc`, version 3.0.0+.
+
+If you compiled the gRPC C core library from source above, the `protoc` binary should have been installed as well. If it hasn't been installed, you can run the following commands to install it.
+
+```sh
+$ cd grpc/third_party/protobuf
+$ sudo make install # 'make' should have been run by core grpc
+```
+
+Alternatively, you can download `protoc` binaries from [the protocol buffers Github repository](https://github.com/google/protobuf/releases).
+
+
+### PHP protobuf compiler
+
+You need to install `protoc-gen-php` to generate stub class `.php` files from service definition `.proto` files.
+
+```sh
+$ cd grpc/src/php/vendor/datto/protobuf-php # if you had run `composer install` in the previous step
+
+OR
+
+$ git clone https://github.com/stanley-cheung/Protobuf-PHP # clone from github repo
+
$ gem install rake ronn
$ rake pear:package version=1.0
$ sudo pear install Protobuf-1.0.tgz
```
-Generate client stub code
+### Client Stub
+
+Generate client stub classes from `.proto` files
```sh
$ cd grpc/src/php
$ ./bin/generate_proto_php.sh
```
-Run a local server serving the math services
+### Run test server
- - Please see [Node][] on how to run an example server
+Run a local server serving the math services. Please see [Node][] for how to run an example server.
```sh
-$ cd grpc/src/node
+$ cd grpc
$ npm install
-$ nodejs examples/math_server.js
+$ nodejs src/node/test/math/math_server.js
```
+### Run test client
+
Run the generated code tests
```sh
@@ -161,13 +210,15 @@
Make sure the Node math server is still running, as above.
```sh
-$ cd grpc/src/node
-$ nodejs examples/math_server.js
+$ cd grpc
+$ npm install
+$ nodejs src/node/test/math/math_server.js
```
Make sure you have run `composer install` to generate the `vendor/autoload.php` file
```sh
+$ cd grpc/src/php
$ composer install
```
@@ -229,13 +280,15 @@
Make sure the Node math server is still running, as above.
```sh
-$ cd grpc/src/node
-$ nodejs examples/math_server.js
+$ cd grpc
+$ npm install
+$ nodejs src/node/test/math/math_server.js
```
Make sure you have run `composer install` to generate the `vendor/autoload.php` file
```sh
+$ cd grpc/src/php
$ composer install
```