PHPackages                             chromatic/usher - 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. [CLI & Console](/categories/cli)
4. /
5. chromatic/usher

ActiveLibrary[CLI & Console](/categories/cli)

chromatic/usher
===============

A collection of Robo commands for use on Chromatic projects.

v5.1.4(2mo ago)13534.3k↑264.2%6[3 issues](https://github.com/ChromaticHQ/usher/issues)[2 PRs](https://github.com/ChromaticHQ/usher/pulls)1MITPHPPHP >=8.1CI passing

Since Feb 22Pushed 2mo ago4 watchersCompare

[ Source](https://github.com/ChromaticHQ/usher)[ Packagist](https://packagist.org/packages/chromatic/usher)[ RSS](/packages/chromatic-usher/feed)WikiDiscussions 5.x Synced 1mo ago

READMEChangelog (10)Dependencies (32)Versions (80)Used By (1)

Usher
=====

[](#usher)

Usher is intended for use on Chromatic repositories to supplement the use of the [Robo](https://robo.li/) PHP task runner. It contains a number of commands to assist in development, builds, and deployments, and can be extended in downstream repos.

- ush·er *(verb)*: to show or guide (someone) somewhere.
- ush·er *(noun)*: American singer, songwriter, businessman, and dancer.

[![Usher in a tuxedo](https://user-images.githubusercontent.com/20355/146567165-6a9a6dc5-66cd-4f7c-8e39-69de09365bfd.jpg)](https://user-images.githubusercontent.com/20355/146567165-6a9a6dc5-66cd-4f7c-8e39-69de09365bfd.jpg)

Compatibility
-------------

[](#compatibility)

Usher VersionPHPDrupalNotes5.x8.1+9.5 - 11.0+**Active development**4.x8.1+9.5 - 10.1+**Minimally maintained**3.x8.1+9.5 - 10.1+**Minimally maintained**2.x7.4 - 8.17, 9.4 - 10.0**Unsupported**1.x7.47, 8**Unsupported**Installation
------------

[](#installation)

`composer require chromatic/usher`

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

[](#configuration)

- Create a `robo.yml` file in the root of your codebase. `robo.drupal.example.yml`is provided as a starting point for Drupal projects.
- Create a `.sites.config.yml` file in the root of your codebase. See `.sites.config.example.yml` for reference on what can/should be configured.
- Add the following to your repo's `composer.json` "scripts" section so that you can call robo easily with `composer robo`: ```
    "scripts": {
      "robo": "robo --ansi"
    }
    ```
- If you are overriding any commands, add the following to your repo's `composer.json` file. Be sure to specify your own namespace prefix in place of `YOURPREFIX`. ```
    "autoload": {
    "psr-4": {
        "YOURPREFIXRobo\\": "robo/src"
      }
    }
    ```

    Then place the commands in `robo/src/Robo/Plugin/Commands` with the `YOURPREFIXRobo\Robo\Plugin\Commands` namespace.
- If you are using any of the commands that use the [`GitHubStatusTrait`](src/Robo/Plugin/Traits/GitHubStatusTrait.php) to set status checks on your pull requests, a personal access token must be created in GitHub.
    1. Create a [personal access token](https://github.com/settings/tokens/new) in GitHub.
    2. Create an environment variable named `GITHUB_ACCESS_TOKEN` with the token value in the environment where the checks will run.

Commands
--------

[](#commands)

### `robo dev:refresh`

[](#robo-devrefresh)

The `dev:refresh` command, often available in downstream repos as `composer robo dev:refresh -- SITENAME`, refreshes your local development environment (DDEV) which includes:

1. `composer install`
2. Theme build (`robo theme:build`).
3. Disabling front-end caches.
4. Downloading the most recent database dump.
5. Importing the database dump.
6. `drush deploy`
7. Generating a Drupal login link.

### `robo deploy:drupal`

[](#robo-deploydrupal)

The `deploy:drupal` command, often available in downstream repos as `composer robo deploy:drupal SITENAME DOCROOT`, deploys Drupal in a standardized way which includes:

1. `drush deploy`
2. `drush config:import`

### `robo drupal:status-report`

[](#robo-drupalstatus-report)

The `drupal:status-report` command, often available in downstream repos as `composer robo drupal:status-report`, checks Drupal's status report and reports warnings and errors. Specific warnings or errors can be ignored by adding the warning/error ID to the `drupal_status_report_ignore_checks` key in the downstream repository's `robo.yml` config file. For example:

```
drupal_status_report_ignore_checks:
  - update_core
```

To identify the ID's in question, run `drush status-report --format=yaml`. The output will include the ID's.

### `robo config:update-php-version`

[](#robo-configupdate-php-version)

Use the `config:update-php-version` command to update the PHP version configured for a project in files listed in the `php_version_config_paths` key of `robo.yml`:

```
php_current_version: '8.1'
php_version_config_paths:
  - composer.json
  - .tugboat/config.yml
  - .platform.app.yaml
```

#### Slack Notification Options

[](#slack-notification-options)

If you would like to have Usher send a notification to Slack, you need to [create a Slack app in your workspace](https://api.slack.com/apps), and then add an "incoming webhook" for the channel where you would like the notification sent. When you create the webhook, Slack will provide you with a unique URL for that channel. You must then set the `SLACK_WEBHOOK_URL` environment variable to the Slack webhook URL in whatever environment Usher is running in.

Sample webhook URL: `https://hooks.slack.com/services/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`

- `notify-slack` - Default to `false`. If `true`, Slack notification will be sent on build failure in Tugboat.
- `notify-slack-force` - Default to `false`. If `true`, it will force an attempt to notify Slack about the build regardless of what happened.

Extending
---------

[](#extending)

You can use this package for the basics and then build upon it. New commands that are relevant only to a single repo should be added to a top-level `/robo`directory in the project repo. Commands should live at `/robo/src/Robo/Plugin/Commands/`. Add a new autoload namespace to `composer.json` so these commands will be detected:

```
"autoload": {
    "psr-4": {
        "YOURPREFIXRobo\\": "robo/src"
    }
}
```

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

[](#contributing)

If you have a new command that would be useful to multiple repositories that use this package, create a new command here under `/src/Robo/Plugin/Commands` via a pull request.

###  Health Score

61

—

FairBetter than 99% of packages

Maintenance83

Actively maintained with recent releases

Popularity45

Moderate usage in the ecosystem

Community23

Small or concentrated contributor base

Maturity77

Established project with proven stability

 Bus Factor2

2 contributors hold 50%+ of commits

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 ~26 days

Recently: every ~88 days

Total

71

Last Release

63d ago

Major Versions

v2.24.3 → v3.1.02023-06-13

v2.24.4 → v3.3.02023-10-19

v3.3.0 → v4.0.02023-10-25

2.x-dev → v4.0.12024-01-09

v4.0.4 → v5.0.02024-10-01

PHP version history (2 changes)v2.1.0PHP >=7.4

v3.0.0PHP >=8.1

### Community

Maintainers

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

![](https://www.gravatar.com/avatar/170e70c6dea76559e7cfc15812b47aa621ceb92d4c9c35290bd671203db8e6e7?d=identicon)[adamzimmermann](/maintainers/adamzimmermann)

---

Top Contributors

[![markdorison](https://avatars.githubusercontent.com/u/20355?v=4)](https://github.com/markdorison "markdorison (105 commits)")[![dependabot[bot]](https://avatars.githubusercontent.com/in/29110?v=4)](https://github.com/dependabot[bot] "dependabot[bot] (51 commits)")[![renovate[bot]](https://avatars.githubusercontent.com/in/2740?v=4)](https://github.com/renovate[bot] "renovate[bot] (24 commits)")[![apotek](https://avatars.githubusercontent.com/u/279278?v=4)](https://github.com/apotek "apotek (16 commits)")[![adamzimmermann](https://avatars.githubusercontent.com/u/1349906?v=4)](https://github.com/adamzimmermann "adamzimmermann (11 commits)")[![Boegie](https://avatars.githubusercontent.com/u/18569707?v=4)](https://github.com/Boegie "Boegie (4 commits)")[![agarzola](https://avatars.githubusercontent.com/u/439649?v=4)](https://github.com/agarzola "agarzola (2 commits)")[![chrisfree](https://avatars.githubusercontent.com/u/604059?v=4)](https://github.com/chrisfree "chrisfree (1 commits)")[![mmatsoo](https://avatars.githubusercontent.com/u/6803156?v=4)](https://github.com/mmatsoo "mmatsoo (1 commits)")

###  Code Quality

TestsPHPUnit

Static AnalysisRector

Type Coverage Yes

### Embed Badge

![Health badge](/badges/chromatic-usher/health.svg)

```
[![Health](https://phpackages.com/badges/chromatic-usher/health.svg)](https://phpackages.com/packages/chromatic-usher)
```

###  Alternatives

[drush/drush

Drush is a command line shell and scripting interface for Drupal, a veritable Swiss Army knife designed to make life easier for those of us who spend some of our working hours hacking away at the command prompt.

2.4k57.4M685](/packages/drush-drush)[mglaman/phpstan-drupal

Drupal extension and rules for PHPStan

20829.0M124](/packages/mglaman-phpstan-drupal)[pantheon-systems/terminus

A command line interface for Pantheon

3391.5M13](/packages/pantheon-systems-terminus)[wp-cli/wp-cli-tests

WP-CLI testing framework

422.7M87](/packages/wp-cli-wp-cli-tests)[tempest/framework

The PHP framework that gets out of your way.

2.1k23.1k9](/packages/tempest-framework)[drupal/coder

Coder is a library to review Drupal code.

3043.6M461](/packages/drupal-coder)

PHPackages © 2026

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