Download the PHP package odesk/phystrix without Composer

About Phystrix

In distributed systems with PHP frontend, application talks to a number of remote services. Be it a set of services of your own, a 3rd party RESTful API or a legacy component that requires networking interaction: in complex, high-load systems occasional failure cannot be avoided.

Phystrix protects the points of access to remote resources by keeping track of various metrics and preventing repetitive failures.

In case of a service failing way too often, to not make the situation worse, Phystrix will temporarily stop issuing requests to it. When the service comes back to life, Phystrix allows the client application to access it again.

Understanding Phystrix

Not only Phystrix was heavily inspired by the amazing Hystrix library for Java by Netflix, it also attempts to follow the best practices set by the library. You will notice that configuration parameters are the same as well as much of how it works internally.

Even though there is not much available at the moment in terms of documentation for Phystrix, you can also use Hystrix wiki as an additional source of information, to understand how something works etc.

Installation

Recommended way to install Phystrix is by using Composer:

To store and share metrics between requests, Phystrix uses APC, so make sure you have the PHP extension enabled.

Php 7.2

In php 7 the API for apcu changed. You will need to install apcu-bc in addition to apcu to use Phystrix. The backwards compatibility layer extension must be loaded AFTER apcu.

Usage

To protect a point of access to remote service, we use the command pattern. Here is how a minimal implementation could look like:

To have the command preconfigured with Phystrix-specific dependencies, you need to obtain it from a special factory that you share with your objects. For instance, in your controller you would do:

Notice, the extra parameters you pass to the factory’s getCommand method are forwarded to the command’s constructor.

The factory is instantiated as follows:

The way you store the configuration files is up to you. Phystrix relies on Zend\Config to manage configurations. In this case, phystrix-config.php is a PHP array:

Command-specific configurations are merged with the default one on instantiation. “MyCommand” in this case is the command key. By default it is the same as command’s class, but you can set it yourself by overriding the getCommandKey protected method:

Phystrix only works with the command keys. If you have two different commands with the same command key - Phystrix will collect metrics, disable and enable requests, as for a single entity. This may be used for grouping commands.

Sometimes, you may need to change a parameter when a command is used in a particular context:

Note, the config you set is merged with the previously set value.

Features

Fallback

For a command, you can specify fallback logic, that will be executed in case of a failure, or when the remote service is blocked:

If you want to use logic requiring networking for your fallback, make sure to “wrap” it into a Phystrix command of its own.

Request cache

Request cache, when enabled, caches command execution result within a single HTTP request, so you don’t have to worry about loading data over network more than needed.

Results are cached per command key per cache key. To define cache key generation logic, implement getCacheKey protected method:

Timeout

Hystrix for Java allows you to set specific time a command is allowed to run. What it does is it limits the time for the thread a command is running in. In PHP we cannot do that, however, as we only have the context of one, current, thread.

Suggested approach is to manually configure the timeout in the library used to access the remote service.

Let’s say you have this Phystrix configuration for MyCommand:

where “timeout” is a custom parameter which Phystrix does not make any use of. You can specify any arbitrary parameters in Phystrix configuration and they will be available for you in the commands:

where the client might be a 3rd library you downloaded, or an instance of http client from a framework such as Zend Framework or Symfony or something you wrote yourself.

Of course, having to add this into each command would be suboptimal. Normally, you will have a set of abstract commands, specific to your use cases. E.g. you might have GenericCurlCommand or GenericGoogleApiCommand and MyCommand would extend one of those.

Custom dependencies

Since you get the commands from a special factory, you need a way to inject custom dependencies into your commands, such as an instance of HTTP client.

One way would be to extend the Odesk\Phystrix\CommandFactory, create your own factory and have it inject what you need.

Alternatively, configure the locator instance that Odesk\Phystrix\CommandFactory accepts in the constructor.

The service locator can be anything, implementing the very basic Zend\Di\LocatorInterface. You can inject an IoC container that will lazily instantiate instance as they are needed, or you can use a simpler, preconfigured, instance of Zend\Di\ServiceLocator:

You can access the service locator from within your commands as follows:

Request Log

A useful feature for performance monitoring. When enabled, allows you to retrieve the list of commands executed during the current HTTP request:

What you get is an array of actual command instances. For each command you can get the execution time in milliseconds:

and the list of events, such as "SUCCESS", "FAILURE", "TIMEOUT", "SHORT_CIRCUITED", "FALLBACK_SUCCESS", "FALLBACK_FAILURE", "EXCEPTION_THROWN", "RESPONSE_FROM_CACHE":

Hystrix Turbine and Dashboard Support

TBD

Licence

Copyright 2013-2017 Upwork Global Inc. All Rights Reserved.

Phystrix is licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.