# 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.