PHPackages                             wwwision/command-jobs - 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. wwwision/command-jobs

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

wwwision/command-jobs
=====================

Coordinate execution of one-time commands

1.4.0(2mo ago)16.4k↓31.4%MITPHPPHP >=8.3CI passing

Since Sep 25Pushed 6mo agoCompare

[ Source](https://github.com/bwaidelich/command-jobs)[ Packagist](https://packagist.org/packages/wwwision/command-jobs)[ GitHub Sponsors](https://github.com/sponsors/bwaidelich)[ Fund](https://www.paypal.me/bwaidelich)[ RSS](/packages/wwwision-command-jobs/feed)WikiDiscussions main Synced 1mo ago

READMEChangelog (4)Dependencies (20)Versions (9)Used By (0)

Command Jobs
============

[](#command-jobs)

Coordinate execution of one-time commands

This library can be used to enqueue arbitrary commands that need to be executed on all stages, this includes:

- database migrations
- data fixtures / transformations
- one-time bug fixes
- ...

Usage
-----

[](#usage)

Install via [composer](https://getcomposer.org):

```
composer require wwwision/command-jobs
```

and run pending command jobs via

```
vendor/bin/command-jobs run
```

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

[](#configuration)

Upon first run, the CLI will create a `config.yaml` file in the root folder with the following contents:

```
commandResults:
  storage: filesystem
  options:
    path: /some/path/to/commandResults.yaml
```

Note

All configuration options allow to refer to environment variables in the form `%env(SOME_VARIABLE)%`

### Store command results in a database

[](#store-command-results-in-a-database)

To store command results in a MySQL/MariaDB database, the following configuration can be used:

```
commandResults:
  storage: database
  options:
    dsn: '%env(DATABASE_URL)%'
    tableName: command_jobs_results
```

Note

If the `database` storage is configured, the `doctrine/dbal` package has to be installed

### Options

[](#options)

#### `root`

[](#root)

By default, the `run` command will create a `command-jobs` folder in the current directory, that contains YAML files for [Command Definitions](#command-definition), [Command Jobs](#command-job), [Command Results](#command-results) and a `.gitignore` file that excludes Command Results from being added to VCS. The `--root` option allows to specify a different root directory for those three files:

```
vendor/bin/command-jobs run --root=/some/other/folder
```

#### `stop-on-error`

[](#stop-on-error)

Commands that fail or return an exit code other than `0` lead to an error (and the `run` command to exit with an error code as well). By default, remaining pending [Command Jobs](#command-job) will still be executed. It might make sense to stop processing of those jobs entirely in this case:

```
vendor/bin/command-jobs run --stop-on-error
```

#### default options

[](#default-options)

The `run` command supports default options that control verbosity and styling of the output:

```
Usage:
  vendor/bin/command-jobs run [options]

Options:
  -r, --root=ROOT       Root directory
      --stop-on-error   Intercept execution upon errors
  -h, --help            Display help for the given command. When no command is given display help for the list command
      --silent          Do not output any message
  -q, --quiet           Only errors are displayed. All other output is suppressed
  -V, --version         Display this application version
      --ansi|--no-ansi  Force (or disable --no-ansi) ANSI output
  -n, --no-interaction  Do not ask any interactive question
  -v|vv|vvv, --verbose  Increase the verbosity of messages: 1 for normal output, 2 for more verbose output and 3 for debug

```

Concepts
--------

[](#concepts)

### Command Definition

[](#command-definition)

In order for commands to be enqueued/executed, they have to be explicitly defined. This prevents invalid or potentially dangerous commands to be executed automatically. Furthermore, it allows commands to have a description and to be reused. A Command Definition consists of:

- `id` – a unique string, that identifies it. It might make sense to use dots for namespaces to group definitions (e.g. `"db.migrate.products-initial"`)
- `description` – a string, that explains the intention of a command (e.g. `"Creates required product tables – this command is idempotent"`)
- `cmd` – the actual command to execute. This is represented as an array that consists of an element for the command itself and one for each argument (e.g.`["some-command", "arg1", "\"arg2 with spaces\""]`)

The `add-definition` CLI command can be used to add Command Definitions:

```
Usage:
  vendor/bin/command-jobs add-definition [options] [--] [ [ [...]]]

Arguments:
  id                    ID of the command definition
  description           Description of the command definition
  cmd                   The command to execute (command and arguments, separated by spaces)

Options:
  -r, --root=ROOT       Root directory
      --timeout=TIMEOUT  Timeout (in seconds) for the command to run
  -h, --help            Display help for the given command. When no command is given display help for the list command
      --silent          Do not output any message
  -q, --quiet           Only errors are displayed. All other output is suppressed
  -V, --version         Display this application version
      --ansi|--no-ansi  Force (or disable --no-ansi) ANSI output
  -n, --no-interaction  Do not ask any interactive question
  -v|vv|vvv, --verbose  Increase the verbosity of messages: 1 for normal output, 2 for more verbose output and 3 for debug

```

### Command Job

[](#command-job)

To enqueue commands, a corresponding Command Job has to be added. Each Command Job is executed once (unless if fails) when `vendor/bin/command-jobs run` is invoked. A Command Job consists of:

- `id` – a unique string, that identifies it. This is the timestamp at the time of creation in the format `YmdHis` (e.g. `20250925151814`)
- `commandDefinitionId` – the id of an existing [Command Definition](#command-definition)

The `add-job` CLI command can be used to add Command Jobs:

```
Usage:
  vendor/bin/command-jobs add-job [options] [--] []

Arguments:
  definition            ID of the command definition

Options:
  -r, --root=ROOT       Root directory
  -h, --help            Display help for the given command. When no command is given display help for the list command
      --silent          Do not output any message
  -q, --quiet           Only errors are displayed. All other output is suppressed
  -V, --version         Display this application version
      --ansi|--no-ansi  Force (or disable --no-ansi) ANSI output
  -n, --no-interaction  Do not ask any interactive question
  -v|vv|vvv, --verbose  Increase the verbosity of messages: 1 for normal output, 2 for more verbose output and 3 for debug

```

### Command Result

[](#command-result)

The result of any execution of a [Command Jobs](#command-job) is stored as a Command Result. By default, the results are stored in a `commandResults.yaml` file.

Important

The `commandResults.yaml` file is specific to a single installation, it must not be added to the VCS It is therefore excluded via `.gitignore` file by default

A Command Result consists of:

- `commandJobId` – the id of the [Command Jobs](#command-job) that was executed
- `commandDefinitionId` – the id of the corresponding [Command Definition](#command-definition)
- `executionTime` – date and time of the execution
- `executionDurationInMilliseconds` – execution runtime in milliseconds
- `success` – a boolean flag that is `true` if the exit code of the command was `0` and otherwise `false`
- `output` - the string output of the command – or the exception message if it failed

Contribution
------------

[](#contribution)

Contributions in the form of [issues](https://github.com/bwaidelich/command-jobs/issues) or [pull requests](https://github.com/bwaidelich/command-jobs/pulls) are highly appreciated

License
-------

[](#license)

See [LICENSE](./LICENSE)

###  Health Score

45

—

FairBetter than 93% of packages

Maintenance76

Regular maintenance activity

Popularity26

Limited adoption so far

Community6

Small or concentrated contributor base

Maturity56

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 100% 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 ~34 days

Recently: every ~43 days

Total

6

Last Release

64d ago

PHP version history (2 changes)1.0.0PHP >=8.4

1.4.0PHP >=8.3

### Community

Maintainers

![](https://avatars.githubusercontent.com/u/307571?v=4)[Bastian Waidelich](/maintainers/bwaidelich)[@bwaidelich](https://github.com/bwaidelich)

---

Top Contributors

[![bwaidelich](https://avatars.githubusercontent.com/u/307571?v=4)](https://github.com/bwaidelich "bwaidelich (19 commits)")

###  Code Quality

TestsPHPUnit

Static AnalysisPHPStan

Code StylePHP\_CodeSniffer

Type Coverage Yes

### Embed Badge

![Health badge](/badges/wwwision-command-jobs/health.svg)

```
[![Health](https://phpackages.com/badges/wwwision-command-jobs/health.svg)](https://phpackages.com/packages/wwwision-command-jobs)
```

###  Alternatives

[sylius/sylius

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

8.4k5.6M651](/packages/sylius-sylius)[sulu/sulu

Core framework that implements the functionality of the Sulu content management system

1.3k1.3M152](/packages/sulu-sulu)[crunzphp/crunz

Schedule your tasks right from the code.

2292.0M6](/packages/crunzphp-crunz)[crazywhalecc/static-php-cli

Build single static PHP binary, with PHP project together, with popular extensions included.

1.8k13.9k](/packages/crazywhalecc-static-php-cli)[humbug/box

Fast, zero config application bundler with PHARs.

1.3k801.5k69](/packages/humbug-box)[illuminate/console

The Illuminate Console package.

12944.1M5.1k](/packages/illuminate-console)

PHPackages © 2026

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