# Instructions for create a gRPC client for google cloud services

## Overview

This instruction includes a step by step guide for creating a gRPC 
client to test the google cloud service from an empty linux 
VM, using GCE ubuntu 16.04 TLS instance.

The main steps are followed as steps below: 

- Environment prerequisite
- Install protobuf plugin and gRPC-PHP/protobuf extension
- Generate client API from .proto files
- Create the client and send/receive RPC.

## Environment Prerequisite

**Linux**
```sh
$ [sudo] apt-get install build-essential autoconf libtool pkg-config zip unzip zlib1g-dev
```
**PHP**
* `php` 5.5 or above, 7.0 or above
* `pecl`
* `composer`
```sh
$ [sudo] apt-get install php php-dev
$ curl -sS https://getcomposer.org/installer | php
$ [sudo] mv composer.phar /usr/local/bin/composer
```

## Install protobuf plugin and gRPC-PHP/protobuf extension
`grpc_php_plugin` is used to generate client API from `*.proto `files. Currently,
The only way to install `grpc_php_plugin` is to build from the gRPC source.

**Install protobuf, gRPC, which will install the plugin**
```sh
$ git clone -b $(curl -L https://grpc.io/release) https://github.com/grpc/grpc
$ cd grpc
$ git submodule update --init
# install protobuf
$ cd third_party/protobuf
$ ./autogen.sh && ./configure && make -j8
$ [sudo] make install
$ [sudo] ldconfig
# install gRPC
$ cd ../..
$ make -j8
$ [sudo] make install
```
It will generate `grpc_php_plugin` under `/usr/local/bin`.


**Install gRPC-PHP extension**
```sh
$ [sudo] pecl install protobuf
$ [sudo] pecl install grpc
```
It will generate `protobuf.so` and `grpc.so` under PHP's extension directory.
Note gRPC-PHP extension installed by pecl doesn't work on RHEL6 system.

## Generate client API from .proto files 
The common way to generate the client API is to use `grpc_php_plugin` directly.
Since the plugin won't find the dependency by itself. It works if all your
service proto files and dependent proto files are inside one directory. The 
command looks like:
```sh
$ mkdir $HOME/project
$ protoc --proto_path=./ --php_out=$HOME/project \  
--grpc_out=$HOME/project \
--plugin=protoc-gen-grpc=./bins/opt/grpc_php_plugin \
path/to/your/proto_dependency_directory1/*.proto \
path/to/your/proto_dependency_directory2/*.proto \
path/to/your/proto_directory/*.proto

```

Take `Firestore` service under [googleapis github repo](https://github.com/googleapis/googleapis)
for example. The proto files required for generating client API are
```
google/api/annotations.proto
google/api/http.proto
google/api/httpbody.proto
google/longrunning/operations.proto
google/rpc/code.proto
google/rpc/error_details.proto
google/rpc/status.proto
google/type/latlng.proto
google/firestore/v1beta1/firestore.proto
google/firestore/v1beta1/common.proto
google/firestore/v1beta1/query.proto
google/firestore/v1beta1/write.proto
google/firestore/v1beta1/document.proto
```
Thus the command looks like:
```sh
$ protoc --proto_path=googleapis --plugin=protoc-gen-grpc=`which grpc_php_plugin` \
--php_out=./ --grpc_out=./ google/api/annotations.proto google/api/http.proto \
google/api/httpbody.proto google/longrunning/operations.proto google/rpc/code.proto \
google/rpc/error_details.proto google/rpc/status.proto google/type/latlng.proto \
google/firestore/v1beta1/firestore.proto google/firestore/v1beta1/common.proto \
google/firestore/v1beta1/query.proto google/firestore/v1beta1/write.proto \
google/firestore/v1beta1/document.proto
```

Since most of cloud services already publish proto files under 
[googleapis github repo](https://github.com/googleapis/googleapis),
you can use it's Makefile to generate the client API.
The `Makefile` will help you generate the client API as
well as find the dependencies. The command will simply be:
```sh
$ cd $HOME
$ mkdir project
$ git clone https://github.com/googleapis/googleapis.git
$ cd googleapis
$ make LANGUAGE=php OUTPUT=$HOME/project
# (It's okay if you see error like Please add 'syntax = "proto3";' 
# to the top of your .proto file.)
```
The client API library is generated under `$HOME/project`.
Take [`Firestore`](https://github.com/googleapis/googleapis/blob/master/google/firestore/v1beta1/firestore.proto)
as example, the Client API is under 
`project/Google/Cloud/Firestore/V1beta1/FirestoreClient.php` depends on your 
package name inside .proto file. An easy way to find your client is 
```sh
$ find ./ -name [service_name]Client.php
```

## Create the client and send/receive RPC.
Now it's time to use the client API to send and receive RPCs.
```sh
$ cd $HOME/project
```
**Install gRPC-PHP composer library**
```sh
$ vim composer.json
######## you need to change the path and service namespace.
{
    "require": {
        "google/cloud": "^0.52.1"
    },
    "autoload": {
        "psr-4": {
            "FireStore\\": "src/",
            "Google\\Cloud\\Firestore\\V1beta1\\": "Google/Cloud/Firestore/V1beta1/"
        }
    }
}
########
$ composer install
```
**Set credentials file**
``` sh
$ vim $HOME/key.json
## Paste you credential file downloaded from your cloud project
## which you can find in APIs&Services => credentials => create credentials
## => Service account key => your credentials
$ export GOOGLE_APPLICATION_CREDENTIALS=$HOME/key.json
```

**Implement Service Client**
Take a unary-unary RPC `listDocument` from `FirestoreClient` as example.
Create a file name `ListDocumentClient.php`.
- import library
```
require_once __DIR__ . '/vendor/autoload.php';
use Google\Cloud\Firestore\V1beta1\FirestoreClient;
use Google\Cloud\Firestore\V1beta1\ListDocumentsRequest;
use Google\Auth\ApplicationDefaultCredentials;
```
- Google Auth
```
$host = "firestore.googleapis.com";
$credentials = \Grpc\ChannelCredentials::createSsl();
// WARNING: the environment variable "GOOGLE_APPLICATION_CREDENTIALS" needs to be set
$auth = ApplicationDefaultCredentials::getCredentials();
$opts = [
    'credentials' => $credentials,
    'update_metadata' => $auth->getUpdateMetadataFunc(),
]
```
- Create Client
```
$firestoreClient = new FirestoreClient($host, $opts);
```
- Make and receive RPC call
```
$argument = new ListDocumentsRequest();
$project_id = xxxxxxx;
$argument->setParent("projects/$project_id/databases/(default)/documents");
list($Response, $error) = $firestoreClient->ListDocuments($argument)->wait();
```
- print RPC response
```
$documents = $Response->getDocuments();
$index = 0;
foreach($documents as $document) {
        $index++;
        $name = $document->getName();
        echo "=> Document $index: $name\n";
        $fields = $document->getFields();
        foreach ($fields as $name => $value) {
                echo "$name => ".$value->getStringValue()."\n";
        }
}
```

- run the script
```sh
$ php -d extension=grpc.so -d extension=protobuf.so ListDocumentClient.php
```

For different kinds of RPC(unary-unary, unary-stream, stream-unary, stream-stream),
please check [grpc.io PHP part](https://grpc.io/docs/tutorials/basic/php.html#calling-service-methods)
for reference.