Download the PHP package amims71/lara-shell without Composer

lara-shell

An interactive artisan command shell for Laravel. Run php artisan shell and you get a REPL where bare words execute as artisan commands, ;-prefixed lines evaluate as PHP (Tinker-style), and you get fuzzy command matching, managed background jobs, aliases, macros, and a production safety guard on top.

It fuses two workflows into one prompt: the ergonomics of an artisan command runner and the power of a Tinker/PsySH PHP REPL.

Requirements

• PHP 8.2+
• Laravel 10, 11, or 12 (illuminate/console, illuminate/contracts, illuminate/support ^10|^11|^12)
• psy/psysh ^0.12.20, symfony/process ^6.4|^7

Installation

The service provider (Amims71\LaraShell\LaraShellServiceProvider) is auto-discovered — no manual registration needed.

To customize behavior, optionally publish the config file:

This copies config/lara-shell.php into your app's config/ directory.

Quick start

Launch the shell:

The command is also registered under the aliases terminal and repl, so php artisan terminal and php artisan repl open the same shell.

Then just type commands at the artisan> prompt:

New here? Type help (or h) for a built-in guide to everything the shell can do, and help <command> for a specific command's usage. A short hint is printed on launch.

Features

help and h — the built-in guide

Type help (or its aliases h, about, guide) for an overview of everything the shell does. Pass a command name to see its usage, arguments, and options — rendered from the live command catalog, no subprocess:

The shell prints a one-line hint on launch pointing you at help and palette.

Bare-word artisan commands

Type any artisan command name (with its usual arguments and options) with no artisan prefix. It runs against your application:

Fuzzy matching, palette, and ?

You don't have to type the full command name. lara-shell resolves input in tiers:

1. Exact name or alias.
2. Unambiguous prefix abbreviation — mig → migrate (when only one command starts with it).
3. Colon-segment abbreviation — m:f → migrate:fresh, r:l → route:list.
4. fzf-style subsequence match, when there is a single clear winner.

When you want to browse or search the catalog, use the palette command (aliased ?):

With no query, palette lists commands name-sorted; with a query it ranks by fuzzy score against command names and descriptions.

PHP eval / Tinker fusion — the ; escape

Anything that isn't a known command runs as PHP, exactly like Tinker (lara-shell is built on PsySH). You can also force a line to be treated as PHP by prefixing it with ; (the php_escape character). This is useful when your PHP expression would otherwise collide with a command name:

An empty line and any line starting with ; are always classified as PHP.

Background jobs — &, jobs, kill, logs

Append & to any artisan command to run it detached in the background:

Commands listed under long_running in the config (serve, queue:work, horizon, pail, octane:start, …) are backgrounded automatically, so you don't need the trailing &:

Manage running jobs with the meta-commands:

Jobs are tracked in a shared file registry, so jobs, logs, and kill see jobs started from any lara-shell session in the same project.

Aliases and @macros

Aliases rewrite the first word of a line. Manage them from inside the shell:

A real command always wins over an alias of the same name, and alias expansion is loop-guarded.

Macros are named sequences of steps, invoked with the @ sigil (macro_sigil). Each step is a line (an artisan command, an alias, or another @macro). Macros are defined in the per-project .lara-shell.php file (see Configuration):

Macro recursion is loop-guarded and depth-capped.

Both aliases and macros are stored in a per-project .lara-shell.php file at your application root.

Production safety guard

When your app is in a guarded environment (by default production), destructive commands are gated. The guard has three levels:

• allow — runs normally.
• confirm — you must re-type the exact command name to proceed; anything else aborts.
• block — refused outright.

The default config marks a list of destructive commands as confirm (migrate, migrate:fresh, db:wipe, db:seed, cache:clear, queue:flush, …). Passing --force/-f also escalates a command to confirm in a guarded environment. Outside guarded environments, everything is allowed.

reload

Refresh the command catalog (and, on drivers that support it, reload code):

The current cross-platform driver already runs each command in a fresh subprocess, so your code is always current; reload refreshes the in-shell command catalog so newly registered commands become resolvable.

Configuration

config/lara-shell.php

Publish it with php artisan vendor:publish --tag=lara-shell-config. Keys:

Default config:

Per-project .lara-shell.php

Aliases and macros live in a .lara-shell.php file at your application root. alias add/alias rm write to it automatically; you can also edit it by hand. It returns an array with aliases and macros keys:

How commands run

On macOS/Linux (with pcntl + posix), lara-shell boots your app once and runs each foreground command by pcntl_fork()-ing the warm process — so commands execute instantly (no re-boot), inherit your real terminal (colors, make:* prompts), and a crash or exit() only kills that fork, never your session. Long-running commands are detached background jobs logged to storage/lara-shell/logs/<job-id>.log and tracked in a shared registry so multiple terminals see the same jobs. reload re-execs the shell for fresh code.

On Windows / hosts without pcntl, it transparently falls back to running each command as a fresh subprocess.

Pick a driver with the driver config key: auto (default — warm-fork on Unix, subprocess elsewhere), forking, or local.

Testing

License

MIT.