PHPackages                             php-heroku-client/php-heroku-client - 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. [API Development](/categories/api)
4. /
5. php-heroku-client/php-heroku-client

ActiveLibrary[API Development](/categories/api)

php-heroku-client/php-heroku-client
===================================

A PHP client for the Heroku Platform API

v4.0.4(2mo ago)24413.4k↓83.5%93MITPHPPHP ^7.3||^8.0CI failing

Since Jun 18Pushed 2mo ago1 watchersCompare

[ Source](https://github.com/TransitScreen/php-heroku-client)[ Packagist](https://packagist.org/packages/php-heroku-client/php-heroku-client)[ Docs](https://github.com/TransitScreen/php-heroku-client)[ RSS](/packages/php-heroku-client-php-heroku-client/feed)WikiDiscussions main Synced 1w ago

READMEChangelog (10)Dependencies (21)Versions (19)Used By (3)

PHP Heroku Client
=================

[](#php-heroku-client)

[![Latest Version](https://camo.githubusercontent.com/baddde56866473f692e04ed0a13606f7ef568c6272a00a0f709da2ae6686518a/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f72656c656173652f5472616e73697453637265656e2f7068702d6865726f6b752d636c69656e742e737667)](https://github.com/TransitScreen/php-heroku-client/releases)[![Software License](https://camo.githubusercontent.com/074b89bca64d3edc93a1db6c7e3b1636b874540ba91d66367c0e5e354c56d0ea/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f6c6963656e73652d4d49542d627269676874677265656e2e737667)](LICENSE)[![Maintainability Rating](https://camo.githubusercontent.com/5710f1819a3540594918dca0ffab222d21fccdb8bb693a8787aafbb89811eba6/68747470733a2f2f736f6e6172636c6f75642e696f2f6170692f70726f6a6563745f6261646765732f6d6561737572653f70726f6a6563743d5472616e73697453637265656e5f7068702d6865726f6b752d636c69656e74266d65747269633d7371616c655f726174696e67)](https://sonarcloud.io/summary/overall?id=TransitScreen_php-heroku-client)[![Code Coverage](https://camo.githubusercontent.com/e6febbc80cf77d739d2badf941e50b727e1c49e48b25a623804ab57cd624d5b5/68747470733a2f2f696d672e736869656c64732e696f2f736f6e61722f636f7665726167652f5472616e73697453637265656e5f7068702d6865726f6b752d636c69656e742f6d61696e3f7365727665723d6874747073253341253246253246736f6e6172636c6f75642e696f)](https://sonarcloud.io/summary/overall?id=TransitScreen_php-heroku-client)[![Downloads](https://camo.githubusercontent.com/0f1c52c4b2a540d123a92a0e37e28514bea906474d98c6f198a78e6f79a48c7f/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f7068702d6865726f6b752d636c69656e742f7068702d6865726f6b752d636c69656e742e737667)](https://packagist.org/packages/php-heroku-client/php-heroku-client)

A PHP client for the Heroku Platform API, similar to [platform-api](https://github.com/heroku/platform-api) for Ruby and [node-heroku-client](https://github.com/heroku/node-heroku-client) for Node.js. With it you can create and alter Heroku apps, install or remove add-ons, scale resources up and down, and use any other capabilities documented by the [Platform API Reference](https://devcenter.heroku.com/articles/platform-api-reference).

Features
--------

[](#features)

- Reads `HEROKU_API_KEY` for zero-config use (deprecated)
- Returns JSON-decoded Heroku API responses
- Exposes response headers (necessary for some API functionality)
- Uses a built-in cURL-based HTTP client or one that you provide
- Accepts cURL options and custom request headers
- Throws informative exceptions for authentication, JSON, and HTTP errors
- Designed around the [PSR-7](http://www.php-fig.org/psr/psr-7/) (Request/Response) and [PSR-18](https://www.php-fig.org/psr/psr-18/) (HTTP client) standards

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

[](#requirements)

All versions are dependent on cURL, unless providing an HTTP client without cURL dependencies (such as [Socket Client](http://docs.php-http.org/en/latest/clients/socket-client.html)). In addition:

- v4.x
    - PHP 7.3+ or 8.x
    - Incompatible with Guzzle *less than* v7.x (due to guzzlehttp/psr7:^2.0 dependency)
- v3.x
    - PHP 7.3+ or 8.x
    - Incompatible with Guzzle v7.x (due to http-interop/http-factory-guzzle dependency)
- v2.x
    - PHP 7.1 or 7.2
    - Incompatible with Guzzle v7.x (due to http-interop/http-factory-guzzle dependency)
- v1.x
    - PHP 5.6 or 7.0
    - Incompatible with Guzzle v7.x (due to http-interop/http-factory-guzzle dependency)

So modern projects will either use v3 or v4 of this library, depending on what version of Guzzle they use. Note that Guzzle is not required by this library; it's just that it may have dependency conflicts if you do also use it in your project.

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

[](#installation)

```
$ composer require php-heroku-client/php-heroku-client

```

Quick start
-----------

[](#quick-start)

Instantiate the client:

```
require_once __DIR__ . '/vendor/autoload.php';

use HerokuClient\Client as HerokuClient;

$heroku = new HerokuClient([
    'apiKey' => 'my-api-key',
]);
```

Find out how many web dynos are currently running:

```
$currentDynos = $heroku->get('apps/my-heroku-app-name/formation/web')->quantity;
```

Scale up:

```
// patch(), post(), and put() accept an array or object as a body.
$heroku->patch(
    'apps/my-heroku-app-name/formation/web',
    ['quantity' => $currentDynos + 1]
);
```

Find out how many more calls we can make in the near future:

```
// Underlying PSR-7 Request and Response objects are available for header inspection and general debugging.
$remainingCalls = $heroku->getLastHttpResponse()->getHeaderLine('RateLimit-Remaining');
```

Configuration
-------------

[](#configuration)

The client can be configured at instantiation with these settings, all of which are optional and have sane defaults:

```
new HerokuClient([
    'apiKey' => 'my-api-key',                 // If not set, the client finds HEROKU_API_KEY (deprecated) or fails
    'baseUrl' => 'http://custom.base.url/',   // Defaults to https://api.heroku.com/
    'httpClient' => $myFavoriteHttpClient,    // Any PSR-18 compatible HTTP client
    'curlOptions' => [                        // Options can be set when using the default HTTP client
        CURLOPT_TIMEOUT => 10,
        CURLOPT_USERAGENT => 'My Agent',
        ...
    ],
]);
```

Making calls
------------

[](#making-calls)

Make calls using the client's `get()`, `delete()`, `head()`, `patch()`, `post()`, and `put()` methods. The first argument is always the required `string` path and the last is always an optional `array` of custom headers. `patch()`, `post()`, and `put()` take an `array` or `object` body as the second argument. These methods return the `\stdClass` object that results from JSON-decoding the Heroku API response.

- See the [Quick Start](#quick-start) for examples with and without a body.
- See the full [Platform API Reference](https://devcenter.heroku.com/articles/platform-api-reference) for a list of all endpoints and their responses.

Using headers
-------------

[](#using-headers)

The Heroku API uses headers as a separate channel for [range](https://devcenter.heroku.com/articles/platform-api-reference#ranges), [rate limit](https://devcenter.heroku.com/articles/platform-api-reference#rate-limits), and [caching](https://devcenter.heroku.com/articles/platform-api-reference#caching) information. You can read and send headers like this:

```
$page1 = $heroku->get('apps');

// 206 Partial Content means there are more records to get.
if ($heroku->getLastHttpResponse()->getStatusCode() == 206) {
    $nextRange = $heroku->getLastHttpResponse()->getHeaderLine('Next-Range');
    $page2 = $heroku->get('apps', ['Range' => $nextRange]);
}
```

Using other Request/Response features
-------------------------------------

[](#using-other-requestresponse-features)

Underlying HTTP requests and responses are exposed via the `getLastHttpRequest()` and `getLastHttpResponse()` methods. These return instances of [Guzzle's implementations](http://docs.guzzlephp.org/en/latest/psr7.html) of the [PSR-7 Request and Response interfaces](http://www.php-fig.org/psr/psr-7/). Note that the Response body is a stream, so it has [special handling considerations](http://docs.guzzlephp.org/en/latest/psr7.html#streams). Response bodies are rewound by this client so that you can access them again immediately with a call to `getBody()->getContents()` on the Response. The properties exposed via the `getLast...()` methods are nulled initially and whenever you call one of the entry point methods (`get`/`delete`/`head`/`patch`/`post`/`put`), then set again as soon as their corresponding objects are generated. So for certain failures (such as a hard network error in the HTTP client) `getLastHttpRequest()` would return the attempted Request object while `getLastHttpResponse()` would return `null`.

Reacting to problems
--------------------

[](#reacting-to-problems)

You may wish to recognize and react to specific error conditions. In this example we use the API's [data integrity mechanism](https://devcenter.heroku.com/articles/platform-api-reference#data-integrity) to require that the requested data hasn't changed since an earlier call. If it has, we will receive a `412 Precondition Failed` response. We handle that case specially, then catch more general situations:

```
use HerokuClient\Exception\BadHttpStatusException;

try {
    $heroku->get('some/path', ['If-Match' => $eTagFromEarlierCall]);
} catch (BadHttpStatusException $exception) {
    if ($heroku->getLastHttpResponse()->getStatusCode() == 412) {
        // React to the fact that our requested data has changed.
    } else {
        // React to all other bad HTTP status codes.
    }
} catch (\Exception $exception) {
    // React to all other problems.
}
```

Exceptions thrown
-----------------

[](#exceptions-thrown)

- `BadHttpStatusException`
- `JsonDecodingException`
- `JsonEncodingException`
- `MissingApiKeyException`

In addition to exceptions thrown directly from this API client, [standardized exceptions](https://www.php-fig.org/psr/psr-18/#clientexceptioninterface) may bubble up from the HTTP client.

Contributing
------------

[](#contributing)

Pull Requests are welcome. Please see our [Contribution Guidelines](CONTRIBUTING.md).

###  Health Score

62

—

FairBetter than 99% of packages

Maintenance86

Actively maintained with recent releases

Popularity46

Moderate usage in the ecosystem

Community22

Small or concentrated contributor base

Maturity77

Established project with proven stability

 Bus Factor1

Top contributor holds 92.2% 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 ~188 days

Recently: every ~153 days

Total

18

Last Release

74d ago

Major Versions

v1.x-dev → v2.0.02020-12-08

v2.x-dev → v3.0.02021-02-20

v3.1.0 → v4.0.02022-04-29

v3.1.1 → v4.0.32026-02-18

PHP version history (3 changes)v1.0.0PHP ^5.6 || ^7.0

v2.0.0PHP ^7.1

v3.0.0PHP ^7.3||^8.0

### Community

Maintainers

![](https://www.gravatar.com/avatar/b00da41c1c235cbbeaa064e5644599b9cd3dc83932cb6cd64535cf3a41d7aef4?d=identicon)[ethanpooley](/maintainers/ethanpooley)

---

Top Contributors

[![ethanpooley](https://avatars.githubusercontent.com/u/856884?v=4)](https://github.com/ethanpooley "ethanpooley (94 commits)")[![lukasjuhas](https://avatars.githubusercontent.com/u/5247674?v=4)](https://github.com/lukasjuhas "lukasjuhas (5 commits)")[![hotmeteor](https://avatars.githubusercontent.com/u/378585?v=4)](https://github.com/hotmeteor "hotmeteor (1 commits)")[![rodrigoprimo](https://avatars.githubusercontent.com/u/77215?v=4)](https://github.com/rodrigoprimo "rodrigoprimo (1 commits)")[![simoheinonen](https://avatars.githubusercontent.com/u/3840367?v=4)](https://github.com/simoheinonen "simoheinonen (1 commits)")

---

Tags

heroku

###  Code Quality

TestsPHPUnit

### Embed Badge

![Health badge](/badges/php-heroku-client-php-heroku-client/health.svg)

```
[![Health](https://phpackages.com/badges/php-heroku-client-php-heroku-client/health.svg)](https://phpackages.com/packages/php-heroku-client-php-heroku-client)
```

###  Alternatives

[aws/aws-sdk-php

AWS SDK for PHP - Use Amazon Web Services in your PHP project

6.3k532.1M2.5k](/packages/aws-aws-sdk-php)[algolia/algoliasearch-client-php

API powering the features of Algolia.

69534.4M144](/packages/algolia-algoliasearch-client-php)[sylius/sylius

E-Commerce platform for PHP, based on Symfony framework.

8.5k5.8M710](/packages/sylius-sylius)[theodo-group/llphant

LLPhant is a library to help you build Generative AI applications.

1.7k371.6k5](/packages/theodo-group-llphant)[gotenberg/gotenberg-php

A PHP client for interacting with Gotenberg, a developer-friendly API for converting numerous document formats into PDF files, and more!

3835.9M26](/packages/gotenberg-gotenberg-php)[telnyx/telnyx-php

Official Telnyx PHP SDK — APIs for Voice, SMS, MMS, WhatsApp, Fax, SIP Trunking, Wireless IoT, Call Control, and more. Build global communications on Telnyx's private carrier-grade network.

35729.6k2](/packages/telnyx-telnyx-php)

PHPackages © 2026

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