shalvah/clara
Clara is a tiny PHP library for beautiful console output, with helpers for titles, badges, progress bars, spinners, and styled text. It works in Laravel and plain PHP, making CLI apps and artisan commands easier to read and pleasant to use.
Install
composer require shalvah/clara
Clara ships a single global helper, clara(), that returns the shared Shalvah\Clara\Clara instance. Use it like a nicer echo:
require __DIR__ . '/vendor/autoload.php';
clara('Starting import...');
clara()->success('Imported 1,204 rows');
clara()->error('Failed to write cache');
Check your PHP version first. 3.3.0 is the release that adds PHP 8.4 compatibility. If you are running PHP 8.4, require ^3.3 explicitly — 3.2.x predates that fix and can surface deprecation notices under 8.4's stricter checks.
Where to look first
README.md — it is short and it is the whole API surface; read it end to end before anything else.src/helpers.php — the clara() function definition and how the singleton is resolved.src/Clara.php — the class you will actually interact with. The public methods are the package.tests/ — this is where the fake/assertion API lives, and it is the second reason to use the package (the first being pretty output).Because the surface area is tiny, you can read the entire source in ten minutes. Budget that time up front; it will save you guessing at method names.
First use case
Take an existing CLI script (deploy script, import command, a bin/ tool) that currently uses echo and print_r. Replace output calls with clara() and its severity helpers, then add a test that asserts on the output. That is the whole value proposition: styled output you can also assert on. Do this on one script before rolling it out across the codebase.
Severity helpers as the primary vocabulary
Rather than sprinkling raw colors everywhere, use the named levels so output is consistent and so assertions are stable:
clara()->info('Checking database connection');
clara()->success('Connected');
clara()->warn('Retrying in 5s');
clara()->error('Connection refused');
This mirrors the familiar console-output vocabulary from frameworks like Laravel, which makes it easy to onboard developers.
Chained styling for emphasis
For one-off highlighting (headers, paths, IDs), chain the color/style methods:
clara()->bold()->blue('=== Deployment ===');
clara()->cyan($filePath);
Treat chaining as the exception, not the default — reserve it for section headers and machine-identifiable values (paths, IDs, hashes). Consistent semantics beat rainbow output.
Wrap it in your own reporter (strongly recommended)
Because Clara is a global singleton with a static-ish feel, do not call clara() from every corner of your domain code. Introduce a thin Reporter/ConsoleOutput wrapper and inject that:
final class Reporter
{
public function step(string $msg): void { clara()->info($msg); }
public function done(string $msg): void { clara()->success($msg); }
public function fail(string $msg): void { clara()->error($msg); }
}
Two payoffs: you can swap Clara out later without touching call sites, and tests of your business logic do not need to know Clara exists. Reserve direct clara() calls for bin/ entry points and top-level command classes.
Testing with the fake
The reason to pick Clara over hand-rolled echo "\033[32m..." is that it can be faked. The pattern is:
Clara::fake();
// run the code under test...
Clara::assertWrote('Imported 1,204 rows');
Look at tests/ for the exact assertion names your version ships with (there is usually a "wrote" assertion and variant(s) for style/color). The key habit: call Clara::fake() in setUp() (or the top of the test) before the first output call, and assert against the semantic string, not against ANSI escape codes. Testing raw escape sequences is brittle and breaks the moment you tweak styling.
Integration tips
bin/ scripts: call clara() directly; there is no framework to integrate with.$this->info() inside Artisan/Symfony commands (it already handles decoration and verbosity). Use Clara for standalone scripts, CI helpers, or code shared outside the framework. Don't fight the framework's console layer.Global helper autoloading
clara() is a namespaced function loaded via Composer's files autoload. If it "doesn't exist," the usual culprits are: stale autoloader (composer dump-autoload), a manually assembled autoloader that skipped files, or calling it from a namespace where you forgot the use function Shalvah\Clara\clara; import. The function is namespace-scoped, not truly global.
The singleton and test leakage
Clara is effectively a process-wide singleton. If one test calls Clara::fake() and another does not reset it, you get order-dependent failures. The package usually offers a way to restore/clear state; if not, isolate fake-enabled tests and verify assertions against the fake you enabled, not against the real writer. Watch for tearDown() omissions.
Fake must be enabled before output
If the code under test writes before you call Clara::fake(), that early output goes to the real stream and your assertion fails mysteriously. Enable the fake at the very top of the test.
PHP 8.4 compatibility
3.3.0 is a compatibility-only release: it updates the code for PHP 8.4. There are no API changes, no new methods, no deprecations to migrate — if you are on 3.2.x and PHP ≤ 8.3 you can upgrade without touching a line of your code. The practical action item is narrow but real: on PHP 8.4, pin ^3.3 and re-run your suite with deprecation warnings surfaced (E_ALL in phpunit.xml or error_reporting(-1)) to confirm the fix actually covers your call paths. Because this is a single-maintainer package, treat a PHP-version bump in your app as a trigger to check whether Clara has shipped a matching compat release before assuming the upgrade went cleanly.
ANSI codes and non-TTY environments
Colors are ANSI escape sequences. In CI logs, piped output, or log aggregators, they show up as garbage ([32m...) unless stripped. The package typically auto-detects TTY (or exposes a way to disable color), but verify this against your target versions. Conventions worth respecting: honor NO_COLOR and a --no-ansi/--plain flag on your own commands. Never let ANSI codes leak into files you write.
Windows / legacy terminals
Modern Windows Terminal handles ANSI fine; older cmd.exe historically did not. If you ship to Windows users, test in the terminal(s) they actually use rather than assuming.
Output buffering and PHPUnit
If your test suite or a test listener buffers output (ob_start), or if PHPUnit's own output handling is in play, faking sidesteps most of this — but mixed use of echo and clara() in the same code path will produce confusing interleaved output. Pick one output channel per script.
It is not a logger
Clara is for human-facing CLI messages. Do not use it as a substitute for PSR-3 logging or structured logs — it has no levels, timestamps, or sinks beyond the stream. If you need both, wire a logger for machine-readable events and Clara for the human-facing summary.
Extension points
The class is small and the API is mostly direct methods. Realistic extension strategies are: (a) wrap it in your own reporter (preferred), (b) subclass Clara and have your wrapper use your subclass if the constructor/visibility allows it, or (c) fork — the package is MIT and the surface is small enough that a fork is a legitimate option if you need behavior the maintainer will not take. Check the exact method set in src/Clara.php before promising anything to your team; verify method and assertion names against the installed version rather than blog posts and memory.
Version pinning
It is a low-star, single-maintainer package, and releases are infrequent and compatibility-driven rather than feature-driven (3.3.0 is a PHP 8.4 compat patch; 3.2.0 preceded it). Pin to a minor version in composer.json and review the changelog before bumping. The API is small enough to read, so a composer update review is cheap — and because the maintainer's release cadence tracks PHP versions rather than features, a PHP upgrade is the most likely reason you will ever need to bump Clara at all.
How can I help you explore Laravel packages today?