PHPackages                             titasgailius/terminal - 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. titasgailius/terminal

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

titasgailius/terminal
=====================

Terminal is an Elegent wrapper around Symfony's Process component.

1.2.1(1y ago)512340.9k—3.8%37[1 PRs](https://github.com/TitasGailius/terminal/pulls)11MITPHPCI passing

Since Mar 22Pushed 3mo ago11 watchersCompare

[ Source](https://github.com/TitasGailius/terminal)[ Packagist](https://packagist.org/packages/titasgailius/terminal)[ RSS](/packages/titasgailius-terminal/feed)WikiDiscussions master Synced 1mo ago

READMEChangelog (10)Dependencies (4)Versions (19)Used By (11)

Terminal
========

[](#terminal)

An Elegant wrapper around Symfony's Process component.

[![Preview](./screenshots/preview.png)](./screenshots/preview.png)

---

Content
=======

[](#content)

- [Installation](#installation)
- [Executing Commands](#executing-commands)
- [Response](#response)
    - [Overview](#response)
    - [Output to Array](#output-to-array)
    - [Output Stream (Recommended)](#output-stream)
    - [Output Lines](#output-lines)
    - [Output via Laravel Artisan Command](#output-via-laravel-artisan-command)
    - [Output via Symfony Console Command](#output-via-symfony-console-command)
    - [Throwing Exceptions](#throwing-exceptions)
- [Data](#data)
- [Working Directory](#working-directory)
- [Timeout](#timeout)
- [Retries](#retries)
- [Environment Variables](#environment-variables)
- [Command](#command)
- [Symfony Process](#symfony-process)
- [Testing](#testing)
    - [Overview](#testing)
    - [Faking Responses](#faking-responses)
    - [Faking Specific Commands](#faking-specific-commands)
    - [Response Lines](#response-lines)
    - [Failed Response](#failed-response)
    - [Inspecting Commands](#inspecting-commands)
    - [Mocking Symfony Process](#mocking-symfony-process)
    - [Caveats](#caveats)
- [PHP 8 Support](#php-8-support)

Installation
============

[](#installation)

`composer require titasgailius/terminal`

Executing Commands
==================

[](#executing-commands)

To execute a command, you may use the `run` method. First, let's examine how to execute a basic shell command.

```
$response = Terminal::run('rm -rf vendor');
```

Response
========

[](#response)

The `run` method returns an instance of `TitasGailius\Terminal\Response`, which provides a variety of methods that may be used to inspect the response:

```
$response->getExitCode() : int;
$response->ok() : bool;
$response->successful() : bool;

$response->lines() : array;
$response->output() : string;
(string) $response: string;
```

### Output to Array

[](#output-to-array)

You may get the entire command output on a single array by using `lines` method:

```
foreach ($response->lines() as $line) {
    //
}
```

### Output Stream (Recommended)

[](#output-stream-recommended)

If memory consumption is important, you may read the entire output line by line, using a `foreach` loop on the response instance:

```
foreach ($response as $line) {
    //
}
```

### Output Lines

[](#output-lines)

Every `$line` item is an instance of `TitasGailius\Terminal\OutputLine` object, which provides a variety of methods that may be used to inspect the output line.

You may inspect if the output line is an error:

```
$line->error(); // true|false
```

And you may use this object as a string to get the contents of the line:

```
(string) $line;
```

Alternatively, you may use the `content` method to get the contents of the line:

```
$line->content();
```

### Output via Laravel Artisan Command

[](#output-via-laravel-artisan-command)

If you run Terminal from the Laravel's Artisan command, you may send the output to the console by passing an instance of the Command to the `output` method:

```
public function handle()
{
    Terminal::output($this)->run('echo Hello, World');
}
```

### Output via Symfony Console Command

[](#output-via-symfony-console-command)

If you run Terminal from the Symfony's Console command, you may send the output to the console by passing an instance of the OutputInterface to the `output` method:

```
protected function execute(InputInterface $input, OutputInterface $output)
{
    Terminal::output($output)->run('echo Hello, World');
}
```

### Throwing Exceptions

[](#throwing-exceptions)

If you would like to throw an exception when the command is not successful, you may use the `throw` method:

```
$response = Terminal::run(...);

$response->throw();

return (string) $response;
```

An instance of `Symfony\Component\Process\Exception\ProcessFailedException` will be thrown on error.

Data
====

[](#data)

If you need to pass any data to your command line, it's better to bind it using the `with` method. Terminal can escape and prepare the values for you. Reference these values using the `{{ $key }}` syntax.

```
Terminal::with([
    'firstname' => 'John',
    'lastname' => 'Doe',
])->run('echo Hello, {{ $firstname}} {{ $lastname }}');
```

Alternatively, you may pass the key-value pair in separate parameters.

```
Terminal::with('greeting', 'World')
        ->run('echo Hello, {{ $greeting }}');
```

Working Directory
=================

[](#working-directory)

If you would like to change the current working directory from which the script is executed, you may use the `in` method that accepts a path:

```
Terminal::in(storage_path('framework'))->run('rm -rf views');
```

Timeout
=======

[](#timeout)

If you would like to add a timeout to your command, you may use the `timeout` method that accepts an integer in seconds or an instance of DateTime, DateInterval and Carbon:

```
Terminal::timeout(25)->run('rm -rf vendor');
```

Using `DateInterval`:

```
$duration = new DateInterval('PT25S');

Terminal::timeout($duration)->run('rm -rf vendor');
```

Using `DateTime`:

```
$date = (new DateTime)->add(new DateInterval('PT25S'));

Terminal::timeout($date)->run('rm -rf vendor');
```

Using `Carbon`:

```
$date = Carbon::now()->addSeconds(25);

Terminal::timeout($date)->run('rm -rf vendor');
```

Retries
=======

[](#retries)

If you would like to automatically retry a command when an error occurs, you may use the `retries` method. The `retries` method accepts two arguments: the number of times the command should be attempted and the number of milliseconds that should wait in between attempts:

```
Terminal::retries(3, 100)->run('rm -rf vendor');
```

Environment Variables
=====================

[](#environment-variables)

By default, the shell script is run with the same environment variables as the current PHP process. If you would like to run a script with a different set of environment variables, you may use the `withEnvironmentVariables` method. The `withEnvironmentVariables` method accepts an array with key-value pairs of the environment variables.

```
Terminal::withEnvironmentVariables([
    'APP_ENV' => 'testing',
])->run('rm -rf $DIRECTORY');
```

Command
=======

[](#command)

In some situations, you might want to use the `command` method to define the executable command before actually executing it.

```
$command = Terminal::command('rm -rf vendor');

if ($inBackground) {
    $command->inBackground();
}

$command->run();
```

Symfony Process
===============

[](#symfony-process)

You may get an underlying instance of `Symfony\Component\Process\Process` class by calling `process` method.

```
$process = Terminal::timeout(25)->process();
```

You may also get the process instance from the `TitasGailius\Terminal\Response` object.

```
$response = Terminal::run(...);

$process = $response->process();
```

Lastly, all missing method calls to the `TitasGailius\Terminal\Response` instance are passed to the underlying process instance automatically.

```
$response = Terminal::run(...);

$response->isRunning(); // "isRunning" method is passed to the \Symfony\Component\Process\Process class
```

Extending
=========

[](#extending)

The `extend` method allows you to define custom methods.

```
Terminal::extend('removeVendors', function ($terminal) {
  return $terminal->run('rm -rf vendors');
});

Terminal::removeVendors();
```

Testing
=======

[](#testing)

Terminal has some special features to help you easily and expressively write tests. Terminal's fake method allows you to instruct the Terminal to return stubbed / dummy response when commands are executed.

### Faking Responses

[](#faking-responses)

To instruct the Terminal to return empty responses for every executed command, you may call the `fake` method with no arguments:

```
Terminal::fake();

$response = Terminal::run(...);
```

### Faking Specific Commands

[](#faking-specific-commands)

Alternatively, you may pass an array to the fake method. The array's keys should represent the commands that you wish to fake and their associated responses.

```
Terminal::fake([
    'php artisan inspire' => 'Simplicity is the ultimate sophistication. - Leonardo da Vinci',

    'cowsay Hi, How are you' => [
        ' _________________             ',
        '< Hi, How are you >            ',
        ' -----------------             ',
        '        \   ^__^               ',
        '         \  (oo)\_______       ',
        '            (__)\       )\/\   ',
        '                ||----w |      ',
        '                ||     ||      ',
    ],
]);
```

### Response Lines

[](#response-lines)

Besides passing a string or an array of lines, you may explicitly specify the type of each line. Terminal has `line` and `error` methods that help you create more accurate responses.

```
Terminal::fake([
    'wp cli update' => [
        Terminal::line('Downloading WordPress files.'),
        Terminal::error('WordPress is down.'),
    ],
]);
```

### Failed Response

[](#failed-response)

It is very simple to stub a failed response. Move your response line(s) to the Terminal's `response` method and call `shouldFail` on top of that.

```
Terminal::fake([
    'php artisan migrate' => Terminal::response([
        'Migrating: 2012_12_12_000000_create_users_table',
        'Migrated: 2012_12_12_000000_create_users_table',
    ])->shouldFail(),
]);
```

### Inspecting Commands

[](#inspecting-commands)

When faking responses, you may occasionally wish to inspect the commands the Terminal receives in order to make sure your application is executing the correct commmands.

You may accomplish this by calling the `Terminal::assertExecuted` method after calling `Terminal::fake`.

```
Terminal::fake();

Terminal::run('php artisan migrate');

Terminal::assertExecuted('php artisan migrate');
```

Alternatively you can also check that a given command was not executed. You may accomplish this by calling the `Terminal::assertNotExecuted` method after calling `Terminal::fake`.

```
Terminal::fake();

Terminal::assertNotExecuted('php artisan migrate');
```

### Mocking Symfony Process

[](#mocking-symfony-process)

If you need to mock the underlying Symfony's Process, you may use the Terminal's `response` method.

Terminal's `response` method may be used in several ways:

1. Passing response line(s) and an optional process instance.
2. Passing only the process instance.

```
$process = Mockery::mock(Process::class, function ($mock) {
    $mock->shouldReceive('getPid')
        ->twice()
        ->andReturn(123, 321);
});

Terminal::fake([
    // Empty response with a mocked \Symfony\Component\Process\Process instance.
    'factor 12' => Terminal::response($process)

    // Response lines with a mocked \Symfony\Component\Process\Process instance.
    'php artisan migrate' => Terminal::response([
        'Migrating: 2012_12_12_000000_create_users_table',
        'Migrated: 2012_12_12_000000_create_users_table',
    ], $process),
]);

$this->assertEquals(123, Terminal::run('factor 12')->getPid());
$this->assertEquals(321, Terminal::run('php artisan migrate')->getPid());
```

### Caveats

[](#caveats)

Terminal is using some static methods to provide these beautiful testing features. Specifically, Terminal stores the fake responses on a static property, which means they do not get cleared between each test.

To prevent this you may use the `Terminal::reset` method. The best place to call it is from the PhpUnit's `teardown` method.

```
/**
 * This method is called after each test.
 */
protected function tearDown(): void
{
    parent::tearDown();

    Terminal::reset();
}
```

PHP 8 Support
-------------

[](#php-8-support)

To use Terminal with PHP 8.x, please upgrade Terminal to the `^1.0` version.

1. Update your `composer.json` to use the latest version of the terminal: `"titasgailius/terminal": "^1.0"`.
2. Note that the `Builder::retry` is now a `protected` method.
     *It's very unlikely that you were was using this method.*.

###  Health Score

58

—

FairBetter than 98% of packages

Maintenance66

Regular maintenance activity

Popularity55

Moderate usage in the ecosystem

Community34

Small or concentrated contributor base

Maturity65

Established project with proven stability

 Bus Factor1

Top contributor holds 75.9% 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 ~117 days

Recently: every ~408 days

Total

17

Last Release

367d ago

Major Versions

0.5.0 → 1.0.12021-01-24

### Community

Maintainers

![](https://avatars.githubusercontent.com/u/12625773?v=4)[Titas Gailius](/maintainers/TitasGailius)[@TitasGailius](https://github.com/TitasGailius)

---

Top Contributors

[![TitasGailius](https://avatars.githubusercontent.com/u/12625773?v=4)](https://github.com/TitasGailius "TitasGailius (41 commits)")[![nlivingstone](https://avatars.githubusercontent.com/u/1995501?v=4)](https://github.com/nlivingstone "nlivingstone (2 commits)")[![irazasyed](https://avatars.githubusercontent.com/u/1915268?v=4)](https://github.com/irazasyed "irazasyed (1 commits)")[![jkniest](https://avatars.githubusercontent.com/u/15618191?v=4)](https://github.com/jkniest "jkniest (1 commits)")[![michaelrog](https://avatars.githubusercontent.com/u/102379?v=4)](https://github.com/michaelrog "michaelrog (1 commits)")[![muffycompo](https://avatars.githubusercontent.com/u/780240?v=4)](https://github.com/muffycompo "muffycompo (1 commits)")[![bartdenhoed](https://avatars.githubusercontent.com/u/10920039?v=4)](https://github.com/bartdenhoed "bartdenhoed (1 commits)")[![ohnotnow](https://avatars.githubusercontent.com/u/6471843?v=4)](https://github.com/ohnotnow "ohnotnow (1 commits)")[![pkboom](https://avatars.githubusercontent.com/u/13960169?v=4)](https://github.com/pkboom "pkboom (1 commits)")[![ryancco](https://avatars.githubusercontent.com/u/20148569?v=4)](https://github.com/ryancco "ryancco (1 commits)")[![spekulatius](https://avatars.githubusercontent.com/u/8433587?v=4)](https://github.com/spekulatius "spekulatius (1 commits)")[![nexxai](https://avatars.githubusercontent.com/u/4316564?v=4)](https://github.com/nexxai "nexxai (1 commits)")[![defunctl](https://avatars.githubusercontent.com/u/1066195?v=4)](https://github.com/defunctl "defunctl (1 commits)")

---

Tags

terminalsymfonylaravelprocessexecbash

###  Code Quality

TestsPHPUnit

### Embed Badge

![Health badge](/badges/titasgailius-terminal/health.svg)

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

###  Alternatives

[nunomaduro/laravel-console-dusk

Laravel Console Dusk allows the usage of Laravel Dusk in Laravel/Laravel Zero artisan commands.

16255.4k7](/packages/nunomaduro-laravel-console-dusk)[rahul900day/laravel-console-spinner

Laravel Console Spinner is a spinner output for Laravel command line.

76125.4k1](/packages/rahul900day-laravel-console-spinner)[bvanhoekelen/terminal-style

Return your terminal message in style! Change the text style, text color and text background color form the terminal interface with ANSI color codes. The terminal style tool support Laravel and Composer.

19784.4k2](/packages/bvanhoekelen-terminal-style)[mwguerra/web-terminal

A web-based terminal component for Filament/Laravel with command whitelisting and multiple connection types

251.1k](/packages/mwguerra-web-terminal)[ptlis/shell-command

A basic wrapper around execution of shell commands.

2256.0k2](/packages/ptlis-shell-command)[zachleigh/artisanize

Use Laravel Artisan command syntax in any Symfony Console project.

122.6k1](/packages/zachleigh-artisanize)

PHPackages © 2026

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