PHPackages                             mt-olympus/hermes - 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. [HTTP & Networking](/categories/http)
4. /
5. mt-olympus/hermes

ActiveLibrary[HTTP & Networking](/categories/http)

mt-olympus/hermes
=================

REST API Client using Hal

1.5.2(6y ago)124.7kMITPHPPHP ^7.2

Since Dec 7Pushed 6y ago1 watchersCompare

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

READMEChangelog (3)Dependencies (7)Versions (35)Used By (0)

Hermes
======

[](#hermes)

Hermes is a php library to consume Restful APIs using Hal, like [Apigility](http://apigility.org).

It is the main IPC method for other [Olympus](https://github.com/mt-olympus/Olympus) services.

Can be used with pure PHP or any PHP framework, like ZendFramework 2 and Zend-Expressive.

Requirements
------------

[](#requirements)

- PHP >= 7.2
- Laminas Http >= 2.4
- Laminas ServiceManager >= 2.5
- nocarrier/hal >= 0.9

You can add the module [hermes-loslog](https://github.com/mt-olympus/hermes-loslog) to log the requests.

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

[](#installation)

### Using composer (recommended)

[](#using-composer-recommended)

```
php composer.phar require mt-olympus/hermes
```

### Configuration

[](#configuration)

You need to configure at least the Api URI.

If using a framework that implements `container-interopt`, you can use the following configuration:

Copy the hermes.global.php.dist from this module to your application's config folder and make the necessary changes.

For more information about the http-client options, please check the official documentation at [Laminas\\Http\\Client options](http://framework.zend.com/manual/current/en/modules/zend.http.client.html#configuration).

```
'hermes' => [
    'uri' => 'https://localhost:8000',
    'depth' => 0,
    'http_client' => [
        'options' => [
            'timeout'       => 60,
            'sslverifypeer' => false,
            'keepalive'     => true,
            'adapter'       => 'Laminas\Http\Client\Adapter\Socket',
        ],
    ],
    'headers' => [
        'Accept'       => 'application/hal+json',
        'Content-Type' => 'application/json',
    ],
]
```

Usage
-----

[](#usage)

### Creating the client

[](#creating-the-client)

You can use the `Hermes\Api\ClientFactory` usign the above configuration or manually:

```
$httpClient = new Laminas\Http\Client('http://127.0.0.1', []);
$client = new Hermes\Apt\Client($httpClient, 10);
```

### Injecting a Cerberus Circuit Breaker

[](#injecting-a-cerberus-circuit-breaker)

You can use the client with a circuit breaker to control failures and success and avoid uncessary attempts.

More information about cerberus on it's [own repository](https://github.com/mt-olympus/cerberus).

```
$httpClient = new Laminas\Http\Client('http://127.0.0.1', []);
$storage = Laminas\Cache\StorageFactory\StorageFactory::factory([
            'adapter' => [
                'name' => 'memory',
                'options' => [
                    'namespace' => 'my-service',
                ],
            ],
            'plugins' => [
                'exception_handler' => [
                    'throw_exceptions' => false,
                ],
            ],
        ]);
$cerberus = new Cerberus($storage, 2, 2);

// Create a new client
$client = new Hermes\Apt\Client($httpClient, 10, $cerberus, 'my-service');

// Or add it to a previously created client
$client->setCircuitBreaker($cerberus);
$client->setServiceName('my-service');
```

### Single resource

[](#single-resource)

```
/* @var \Hermes\Api\Client $client */
$client = $this->getServiceLocator()->get('hermes');
/* @var \Hermes\Resource\Resource $ret */
$ret = $client->get('/album/1');

// $data is an array with all data and resources (_embedded) from the response
$data = $ret->getData();

// $data is an array only with data from the response
$data = $ret->getData(false);
```

### Collection

[](#collection)

```
/* @var \Hermes\Api\Client $client */
$client = $this->getServiceLocator()->get('hermes');

// Setting depth of _embedded resources to 10
$client->setDepth(10);

/* @var \Hermes\Resource\Resource $ret */
$ret = $client->get('/album',['year' => 2015]);

// $data is an array with all data and resources (_embedded) from the response
$data = $ret->getData();

// $data is an array with the first album resource from the response
$data = $ret->getFirstResource('album');

// $data is an array with the all album resources from the response
$data = $ret->getResources('album');

// $data is an array with the all resources from the response
$data = $ret->getResources();
```

### Paginator

[](#paginator)

This module provides a paginator helper.

```
/* @var \Hermes\Api\Client $client */
$client = $this->getServiceLocator()->get('hermes');
/* @var \Hermes\Resource\Resource $ret */
$ret = $client->get('/album',['year' => 2015]);

// Returns how many items a page can have
$ret->getPaginator()->getPageSize();

// Returns how many pages the response has
$ret->getPaginator()->getPageCount();

// Returns how many items the response has (across all pages)
$ret->getPaginator()->getTotalItems();

// Returns the current page
$ret->getPaginator()->getPage();
```

You can easily loop through the pages:

```
/* @var \Hermes\Api\Client $client */
$client = $this->getServiceLocator()->get('hermes');
$page = 1;
do {
    /* @var \Hermes\Resource\Resource $ret */
    $ret = $client->get('/album',[
        'year' => 2015,
        'page' => $page;
    ]);
    $data = $ret->getData();
    $page++;
} while ($ret->getPaginator()->hasMorePages());
```

You can use the Paginator with a Zend Framework 2 application:

```
$page = $this->getRequest()->getQuery('page', 1);
$sort = $this->getRequest()->getQuery('sort', 'name');
$order = $this->getRequest()->getQuery('order', 'asc');

$paginator = new \Laminas\Paginator\Paginator(new \Hermes\Paginator\ApiPaginator($client, $url, 'album', [
    'page'=>$page,
    'sort'=>$sort,
    'order' => $order,
]));
$paginator->setDefaultItemCountPerPage(25);
$paginator->setCurrentPageNumber($page);
$paginator->setPageRange($this->paginatorRange);
```

### Events

[](#events)

The client triggers an event before (request.pre) and after (request.post) a request and you can attach to them. More info about events on [zend-eventmanager](https://github.com/laminas/laminas-eventmanager).

### Request Id

[](#request-id)

The client automatically adds a X-Request-Id to each request, but only if there is no previous X-Request-Id added.

You can force a new id with:

```
$client = $this->getServiceLocator()->get('hermes');
$client->addRequestId(); // Auto generared
$client->addRequestId('123abc');
```

###  Health Score

34

—

LowBetter than 77% of packages

Maintenance20

Infrequent updates — may be unmaintained

Popularity22

Limited adoption so far

Community7

Small or concentrated contributor base

Maturity70

Established project with proven stability

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~48 days

Recently: every ~95 days

Total

33

Last Release

2250d ago

Major Versions

0.9.16 → 1.0.02016-07-22

PHP version history (4 changes)0.9.0PHP ^5.5|^7.0

1.0.0PHP ^5.6 || ^7.0

1.3.0PHP ^7.0

1.4.0PHP ^7.2

### Community

Maintainers

![](https://www.gravatar.com/avatar/5b54dffc1ebcb317a0cf825a781ab6c5f30980e9abd0d0a3f9c68830cb05c014?d=identicon)[Lansoweb](/maintainers/Lansoweb)

---

Top Contributors

[![Lansoweb](https://avatars.githubusercontent.com/u/2109813?v=4)](https://github.com/Lansoweb "Lansoweb (34 commits)")

---

Tags

apiclientresthalzf2

### Embed Badge

![Health badge](/badges/mt-olympus-hermes/health.svg)

```
[![Health](https://phpackages.com/badges/mt-olympus-hermes/health.svg)](https://phpackages.com/packages/mt-olympus-hermes)
```

###  Alternatives

[arhitector/yandex

PHP SDK для работы с некоторыми сервисами яндекса (Яндекс.Диск, Yandex.Disk)

13082.9k5](/packages/arhitector-yandex)[jsor/hal-client

A lightweight client for consuming and manipulating Hypertext Application Language (HAL) resources.

2425.9k1](/packages/jsor-hal-client)[api-platform/laravel

API Platform support for Laravel

59126.4k6](/packages/api-platform-laravel)[jarischaefer/hal-api

Enhances your HATEOAS experience by automating common tasks.

291.4k](/packages/jarischaefer-hal-api)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)