Merge github.com:grpc/grpc into flow-like-lava-to-a-barnyard

Conflicts:
	src/core/surface/call.c
	src/core/transport/chttp2_transport.c
	src/core/transport/transport.h

1 files changed, 123 insertions, 35 deletions

diff --git a/src/php/README.md b/src/php/README.md
index 40c79e0dd4..1804606e09 100644
--- a/src/php/README.md
+++ b/src/php/README.md
@@ -5,53 +5,141 @@ This directory contains source code for PHP implementation of gRPC layered on sh
 
 #Status
 
-Pre-Alpha : This gRPC PHP implementation is work-in-progress and is not expected to work yet.
+Alpha : Ready for early adopters
 
+## ENVIRONMENT
 
-## LAYOUT
+Prerequisite: PHP 5.5 or later, `phpunit`, `pecl`
 
-Directory structure is as generated by the PHP utility
-[ext_skel](http://php.net/manual/en/internals2.buildsys.skeleton.php)
+Linux:
 
-## ENVIRONMENT
+```sh
+$ sudo apt-get install php5 php5-dev phpunit php-pear
+```
+
+OS X:
+
+```sh
+$ curl https://phar.phpunit.de/phpunit.phar -o phpunit.phar
+$ chmod +x phpunit.phar
+$ sudo mv phpunit.phar /usr/local/bin/phpunit
+
+$ curl -O http://pear.php.net/go-pear.phar
+$ sudo php -d detect_unicode=0 go-pear.phar
+```
+
+## Build from Homebrew
+
+On Mac OS X, install [homebrew][]. On Linux, install [linuxbrew][]. Run the following command to
+install gRPC.
+
+```sh
+$ curl -fsSL https://goo.gl/getgrpc | bash -s php
+```
+
+This will download and run the [gRPC install script][] and compile the gRPC PHP extension.
+
+## Build from Source
+
+Clone this repository
+
+```
+$ git clone https://github.com/grpc/grpc.git
+```
+
+Build and install the Protocol Buffers compiler (protoc)
+
+```
+$ cd grpc
+$ git pull --recurse-submodules && git submodule update --init --recursive
+$ cd third_party/protobuf
+$ ./autogen.sh
+$ ./configure
+$ make
+$ make check
+$ sudo make install
+```
 
-Install `php5` and `php5-dev`.
+Build and install the gRPC C core libraries
 
-To run the tests, additionally install `php5-readline` and `phpunit`.
+```sh
+$ cd grpc
+$ make
+$ sudo make install
+```
+
+Install the gRPC PHP extension
 
-Alternatively, build and install PHP 5.5 or later from source with standard
-configuration options.
+```sh
+$ sudo pecl install grpc
+```
 
-To also download and install protoc and the PHP code generator.
+OR
 
-```bash
-apt-get install -y procps
-curl -sSL https://get.rvm.io | sudo bash -s stable --ruby
-git clone git@github.com:google/protobuf.git
-cd protobuf
-./configure
-make
-make install
-git clone git@github.com:murgatroid99/Protobuf-PHP.git
-cd Protobuf-PHP
-rake pear:package version=1.0
-pear install Protobuf-1.0.tgz
+```sh
+$ cd grpc/src/php/ext/grpc
+$ phpize
+$ ./configure
+$ make
+$ sudo make install
 ```
 
-## BUILDING
+In your php.ini file, add the line `extension=grpc.so` to load the extension
+at PHP startup.
+
+Install Composer
+
+```sh
+$ cd grpc/src/php
+$ curl -sS https://getcomposer.org/installer | php
+$ php composer.phar install
+```
 
- 1. In ./ext/grpc, run the command `phpize` (distributed with PHP)
- 2. Run `./ext/grpc/configure`
- 3. In ./ext/grpc, run `make` and `sudo make install`
- 4. In your php.ini file, add the line `extension=grpc.so` to load the
-    extension at PHP startup.
+## Unit Tests
 
-## PHPUnit
+Run unit tests
 
-This repo now has PHPUnit tests, which can by run by executing
-`./bin/run_tests.sh` after building.
+```sh
+$ cd grpc/src/php
+$ ./bin/run_tests.sh
+```
+
+## Generated Code Tests
+
+Install `protoc-gen-php`
+
+```sh
+$ cd grpc/src/php/vendor/datto/protobuf-php
+$ gem install rake ronn
+$ rake pear:package version=1.0
+$ sudo pear install Protobuf-1.0.tgz
+```
+
+Generate client stub code
+
+```sh
+$ cd grpc/src/php
+$ ./bin/generate_proto_php.sh
+```
+
+Run a local server serving the math services
+
+ - Please see [Node][] on how to run an example server
+
+```sh
+$ cd grpc/src/node
+$ npm install
+$ nodejs examples/math_server.js
+```
+
+Run the generated code tests
+
+```sh
+$ cd grpc/src/php
+$ ./bin/run_gen_code_test.sh
+```
 
-There is also a generated code test (`./bin/run_gen_code_test.sh`), which tests
-the stub `./tests/generated_code/math.php` against a running localhost server
-serving the math service. That stub is generated from
-`./tests/generated_code/math.proto`.
+[homebrew]:http://brew.sh
+[linuxbrew]:https://github.com/Homebrew/linuxbrew#installation
+[gRPC install script]:https://raw.githubusercontent.com/grpc/homebrew-grpc/master/scripts/install
+[Node]:https://github.com/grpc/grpc/tree/master/src/node/examples