🔊 Simple, pretty, testable console output for CLI apps.
Simple, pretty, testable console output for PHP CLI apps. (Used in Scribe.)
- Colours and emoji to distinguish between log types
- Two different output modes, depending on how much colour you want
- Automatically hide/show debug output
- Can capture console output for easy testing—no need for mocks
- Customizable colour palette
composer require shalvah/clara
$output = clara('myappname'); $output->info("Installing package"); $output->debug("Attempt 3 of 5"); $output->warn("The file does not exist."); $output->error("Something went wrong!"); $output->success("Done. Go and be awesome.");
By default, Clara uses "icons" mode—the output is coloured differently by output type and an emoji is added (as in the first screenshot above). If you prefer, you can switch to "labels" mode:
$output = clara('myappname', \Shalvah\Clara\Clara::MODE_LABELS); // The default $output = clara('myappname', \Shalvah\Clara\Clara::MODE_ICONS);
In labels mode, (the second screenshot above), the emojis are still present, but the output types are written out, and the main output message is not coloured.
If you'd like to output a line of text without the extra formatting provided by the functions above, you can use the
->line() method instead.
You can also customise the colours Clara uses for each type, by passing in an array as the third argument, containing your preferred colours:
$output = clara('myappname', \Shalvah\Clara\Clara::MODE_ICONS, [ 'info' => 'blue', ]);
See the Symfony docs for details about supported colours.
It's common practice to include a verbose flag (
--verbose) in your CLI app that lets you show additional (debug) output to the user. With Clara, you can easily enable or disable debug logging:
$isVerbose = $this->getFlag('verbose'); // If $isVerbose is true, // Clara won't print or capture any debug logs $app1 = clara('app1')->showDebugOutput($isVerbose); $app1->debug("App 1 - Output 1"); // You can also toggle debug output manually $app1->hideDebugOutput(); $app1->debug("App 1 - Output 2"); $app1->showDebugOutput(); $app1->debug("App 1 - Output 3");
Note that by default, Clara will show all output.
Sometimes when running your app's tests, you don't want to clutter your console with the output messages. You can turn off Clara's output by using the
unmute static methods. To mute or unmute a specific app, pass in the app name.
$output1 = clara('myapp1'); $output2 = clara('myapp2'); // Mute only output from "myapp1" Clara::mute('myapp1'); // Won't be printed. $output1->info("Installing package"); // Will be printed $output2->info("Installing package"); Clara::mute(); // Mute all apps Clara::unmute("myapp1"); // Unmute myapp1 Clara::unmute(); // Unmute all apps
Imagine your app includes another app that uses Clara. By default, the output from all apps will be shown. You can turn off output for all apps but yours by calling
// SHow only output from mymainapp $output1 = clara('mymainapp')->only(); // This is equivalent to doing: Clara::mute(); Clara::unmute('yourappname');
Sometimes you need to assert that your app printed what you expect. An easy way is to use output capturing.
Clara::startCapturingOutput('myapp1'); // Clara will start capturing output from myapp1 $output1 = clara('myapp1'); $output1->warn("Going to fail"); $output1->error("Failed"); $capturedOutput = Clara::getCapturedOutput('myapp1'); // $capturedOutput = [ // "⚠ <fg=yellow>Going to fail</>", // "✖ <fg=red>Failed</>", // ] Clara::stopCapturingOutput('myapp1'); Clara::clearCapturedOutput('myapp1'); // Will empty saved output
You can reset the entire state of Clara to default by calling
Clara::reset(). This will clear captured output, stop capturing for all apps and unmute all apps.
By default, Clara outputs to the console, but you can actually output to somewhere else. This is helpful if you're writing a Laravel Artisan command and want to use Clara for output while still capturing the output via Artisan's
->output() method. All you need to do is call
useOutput with an instance of
Symfony\Component\Console\Output\OutputInterface (for Artisan classes, it's
$this->clara = clara('myapp' ->showDebugOutput($this->option('verbose')) ->useOutput($this->output) ->only();