PHPackages                             bigcommerce/grphp - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Framework](/categories/framework)
4. /
5. bigcommerce/grphp

ActiveLibrary[Framework](/categories/framework)

bigcommerce/grphp
=================

gRPC PHP Framework

v4.0.4(8mo ago)25603.9k—4%61MITPHPPHP ^8.1

Since May 22Pushed 3mo ago70 watchersCompare

[ Source](https://github.com/bigcommerce/grphp)[ Packagist](https://packagist.org/packages/bigcommerce/grphp)[ RSS](/packages/bigcommerce-grphp/feed)WikiDiscussions master Synced 1mo ago

READMEChangelog (10)Dependencies (6)Versions (55)Used By (1)

grphp - gRPC PHP Framework
==========================

[](#grphp---grpc-php-framework)

[![Build Status](https://camo.githubusercontent.com/5fd934490a21b4c59b2eb908dcef414c89c4a93eec2273254bff95d995f61962/68747470733a2f2f7472617669732d63692e636f6d2f626967636f6d6d657263652f67727068702e7376673f746f6b656e3d44334363344c4346394267705578346470507076266272616e63683d6d6173746572)](https://travis-ci.com/bigcommerce/grphp)

grphp is a PHP framework that wraps the [gRPC PHP library](https://github.com/grpc/grpc/tree/master/src/php) to provide a more streamlined integration into PHP applications.

It provides an abstracted client for gRPC services, along with other tools to help get gRPC services in PHP up fast and efficiently at scale. Some of its features include:

- Robust client error handling and metadata transport abilities
- Server authentication strategy support, with basic auth with multiple key support built in
- Error data serialization in output metadata to allow fine-grained error handling in the transport while still preserving gRPC BadStatus codes
- Client execution timings in responses
- H2Proxy via nghttpx support that allows gRPC-based communication without the gRPC C libraries

grphp currently has active support for gRPC 1.9.0, and requires PHP 7.4+ to run.

Installation
------------

[](#installation)

```
composer require bigcommerce/grphp
```

You'll need to make sure you fit [the requirements for the grpc/grpc PHP library](https://github.com/grpc/grpc/tree/master/src/php#environment), which does involve installing the gRPC PHP extension (unless you are using the H2Proxy strategy).

Client
------

[](#client)

```
$config = new Grphp\Client\Config([
    'hostname' => 'IP_OF_SERVER:PORT',
]);
$client = new Grphp\Client(Things\ThingsClient::class, $config);

$request = new Things\GetThingReq();
$request->setId(1234);

$resp = $client->call($request, 'GetThing');
$thing = $resp->getResponse(); // Things\Thing
echo $thing->id; // 1234
echo $resp->getStatusCode(); // 0 (these are gRPC status codes)
echo $resp->getStatusDetails(); // OK
```

Strategy
--------

[](#strategy)

grphp comes with the ability to utilize injectable strategies for how it communicates outward. Currently, there are two strategies that come packaged with grphp:

- *Grpc* - This strategy class will utilize the core gRPC PHP libraries to communicate outbound to services
- *H2Proxy* - This strategy is set to call out to an [nghttpx](https://nghttp2.org/) proxy to communicate via HTTP/1.1, which is then upgraded to an HTTP/2 connection, and transformed into a gRPC request.

### H2Proxy Strategy

[](#h2proxy-strategy)

The H2Proxy strategy pairs with a [nghttpx](https://nghttp2.org/) service and sends HTTP/1.1 requests that are upgraded to HTTP/2 and gRPC. It does this by sending the binary encoded protobuf across the wire with the `Upgrade: h2c` and `Connection: Upgrade` headers, which nghttpx uses to upgrade the connection into a proper gRPC request.

This is useful if you do not want to utilize the gRPC PHP C extension but still gain the benefit of the protobuf contracts. If you do not have the gRPC PHP C extension installed, grphp will automatically switch you to the H2Proxy strategy.

You can use and configure the proxy strategy like so, assuming we have a nghttpx service running at the address 0.0.0.0 on port 3000:

```
$proxyConfig = new Grphp\Client\Strategy\H2Proxy\Config('http://0.0.0.0:3000', 15);
$proxyStrategyFactory = new Grphp\Client\Strategy\H2Proxy\StrategyFactory($proxyConfig);
$config = new Grphp\Client\Config([
    'strategy' => $proxyStrategyFactory->build(),
]);
```

This sets the proxy client to also utilize a timeout of 15 seconds. This setup is configurable per-client, so you can adjust these settings - and the strategy - on a service-by-service basis.

### Envoy Strategy

[](#envoy-strategy)

The Envoy strategy uses [Envoy](https://www.envoyproxy.io/) as an HTTP/1.1 bridge for gRPC egress traffic. It automatically serializes messages and buffers requests to handle the response trailers. More can be read about the [Envoy bridge here](https://www.envoyproxy.io/docs/envoy/latest/configuration/http/http_filters/grpc_http1_bridge_filter).

```
// Connect to Envoy at 127.0.0.1:19000
$envoyConfig = new Grphp\Client\Strategy\Envoy\Config('127.0.0.1', 19000, 2);
$envoyStrategyFactory = new Grphp\Client\Strategy\Envoy\StrategyFactory($envoyConfig);
$config = new Grphp\Client\Config([
    'strategy' => $envoyStrategyFactory->build(),
]);
```

This sets the proxy client to also utilize a timeout of 2 seconds. This setup is configurable per-client, so you can adjust these settings - and the strategy - on a service-by-service basis.

Authentication
--------------

[](#authentication)

Authentication is done via adapters, which are specified in the config. You can either pass in:

- The string "basic" for basic HTTP auth
- A string class name for an existing class
- An instantiated object that extends `Grphp\Authentication\Base`

### Basic Authentication

[](#basic-authentication)

grphp supports basic auth for requests that is sent through the metadata of the request.

```
$config = new Grphp\Client\Config([
    'hostname' => 'IP_OF_SERVER:PORT',
    'authentication' => 'basic',
    'authentication_options' => [
        'username' => 'foo',
        'password' => 'bar', // optional
    ]
]);
```

### Custom Client Interceptors

[](#custom-client-interceptors)

grphp comes with a base Client Interceptor class that can be extended to provide your own custom interceptors. This is an example interceptor that adds a "X-Foo" header with a customizable value to all metadata:

```