Skip to main content

Installation

This is a detailed installation guide for each component and dependency of TwirPHP.

tip

Give Nix a try and install dependencies in seconds. Check out the quickstart-demo repository for the necessary packages.

Prerequisites​

Protobuf compiler​

protoc is the compiler for protobuf definitions that generates code for different languages and frameworks.

The easiest way to install it is downloading the precompiled binary from the GitHub Releases page.

Alternatively, you can install it with your package manager, but be aware that packages in package repos might be outdated:

nix-env -iA nixpkgs.protobuf

TwirPHP protoc plugin​

Similarly to protoc, the easiest way to install the plugin is downloading the precompiled binary from the GitHub Releases page.

Alternatively, you can use the following oneliner to download and install the plugin to a custom path:

curl -Ls https://git.io/twirphp | bash [-b path/to/bin]

If you ommit the -b option, the plugin will be downloaded to $PWD/bin.

Finally, you can try installing the plugin with your package manager:

nix-env -iA nixpkgs.protoc-gen-twirp_php
caution

If the plugin is not installed in PATH, protoc has to be invoked differently:

protoc --plugin=protoc-gen-twirp_php=path/to/protoc-gen-twirp_php ...

Runtime library​

You can install the runtime library using Composer:

composer require twirp/twirp

Quickstart PHP dependencies​

Choosing the right set of dependencies is not always trivial.

If you don't care which HTTP libraries and which protobuf implementation you use, you can just install the following quickstart package:

composer require twirp/quickstart

It will install:

  • the pure PHP protobuf library
  • Guzzle HTTP client
  • Guzzle PSR-7
danger

This is not recommended for production!

Please carefully choose which dependencies you install before going to production.

Protobuf PHP library​

As explained in the Overview, protobuf comes with two different runtime implementations.

Choose one that fits your needs:

sudo pecl install protobuf-{VERSION}

HTTP libraries​

As explained in the Overview, the TwirPHP runtime library relies on various HTTP standard interfaces.

If you do HTTP stuff in your project, chances are that some of them are already installed.

You can find packages that implement the relevant interfaces on Packagist:

An example set of dependencies for server usage:

composer require guzzlehttp/psr7

An example set of dependencies for client usage:

composer require guzzlehttp/guzzle guzzlehttp/psr7