Interactive Shell

PHP can execute code interactively or run a short snippet without creating a script file. These tools are useful when you need to inspect one runtime value, verify a standard-library return type, reproduce an edge case, or explore the smallest version of a helper before adding it to a project.

The shell is an investigation tool, not a home for application behaviour. Anything that must be repeated, reviewed, deployed, or trusted belongs in a file with tests.

Start The Native Shell With php -a

Run:

php -a

A working interactive shell prints a prompt similar to this:

Interactive shell

php > echo PHP_VERSION . PHP_EOL;
8.5.6
php > var_dump(extension_loaded('mbstring'));
bool(true)

Do not type <?php at this prompt. The shell is already interpreting PHP code, and each complete statement still needs its semicolon.

The native shell depends on readline support. PHP's manual states that php -a provides the interactive shell when PHP was built with readline support; on Windows, the readline extension can provide it. Since PHP 8.1, php -a fails when readline is unavailable instead of falling back to the older, confusing interactive mode.

Check the local build rather than assuming the shell exists:

php -m
php --ri readline
php -a

php --ri readline reports extension information when readline is loaded. If it reports that the extension is absent, use php -r, a temporary script, or a project REPL instead.

Work With A Stateful Session

Variables, functions, classes, and included files remain available until the process ends:

php > $prices = [12.50, 8.25, 3.00];
php > echo array_sum($prices) . PHP_EOL;
23.75
php > function addTax(float $amount): float { return $amount * 1.2; }
php > var_dump(addTax(10.0));
float(12)

This persistent state is convenient, but it can also mislead you. A result may depend on a variable changed ten commands earlier. Restart the shell when you need a clean experiment. A function or class cannot simply be redefined under the same name in one process, so restarting is often easier than trying to repair a long session.

The prompt changes while PHP is waiting for a closing brace, parenthesis, quote, or comment. Complete the construct before expecting execution. Readline-enabled builds also provide command history and tab completion for names such as functions, constants, classes, variables, static methods, and class constants.

Use explicit inspection functions because the native shell is not designed to present every expression as a polished result:

• var_dump() shows type and value;
• var_export() prints a PHP representation;
• print_r() is convenient for a quick array view but gives less type detail;
• json_encode() is useful when the intended boundary is JSON.

Run One-Off Code With php -r

php -r executes the supplied code and exits:

php -r "echo PHP_VERSION . PHP_EOL;"
php -r "var_dump(extension_loaded('intl'));"
php -r "echo ini_get('memory_limit') . PHP_EOL;"

Do not include <?php or ?> in a -r snippet. The CLI option expects code without script tags and those tags cause a parse error.

php -r is especially useful in setup instructions and diagnostic commands because it is non-interactive. It can be run by a person, CI job, or support script and produces a fresh process each time. That fresh process prevents hidden state from an earlier experiment.

The surrounding shell parses quoting before PHP sees the code. Double quotes, single quotes, dollar signs, backslashes, and command substitution behave differently across POSIX shells, PowerShell, and Command Prompt. Keep published one-liners short. Once escaping becomes harder to understand than the PHP itself, put the code in a .php file.

Inspect The Exact CLI Runtime

An interactive result describes the CLI process that produced it. It does not automatically describe PHP-FPM, Apache's PHP module, a container, a queue worker, or another PHP binary on the machine.

Useful checks include:

php -r "echo PHP_BINARY . PHP_EOL;"
php -r "echo PHP_SAPI . PHP_EOL;"
php -r "var_dump(php_ini_loaded_file());"
php -r "var_dump(php_ini_scanned_files());"
php -r "var_dump(getcwd());"

php_ini_loaded_file() returns the loaded main configuration path or false. php_ini_scanned_files() reports additional parsed INI files or false. The distinction matters because extension configuration is often split into a scan directory instead of written directly in the main file.

Compare a normal process with controlled alternatives:

php -n -r "var_dump(php_ini_loaded_file());"
php -d memory_limit=256M -r "echo ini_get('memory_limit') . PHP_EOL;"

-n starts PHP without a php.ini. -d changes one configuration directive for that invocation. These commands are diagnostic controls: if behaviour changes under -n, configuration or an extension may be involved. They are not instructions to disable production configuration.

Load Project Code Deliberately

The native shell does not automatically know about Composer packages or your application classes. From a project root, you can load Composer's generated autoloader:

php > require getcwd() . '/vendor/autoload.php';
php > var_dump(class_exists(Composer\InstalledVersions::class));
bool(true)

Requiring vendor/autoload.php makes package and project classes discoverable according to the project's Composer configuration. It does not necessarily boot the framework, create a database connection, or load application environment files. Those steps depend on the project.

Be precise about the working directory. getcwd() reflects where the shell was launched, while __DIR__ entered directly in a shell expression does not represent an application source file. If a require path fails, inspect getcwd() and use an explicit path rather than guessing.

Use The Shell To Answer One Question

A useful experiment starts with a narrow question and an observable result. For example:

php -r "var_dump(filter_var('ada@example.com', FILTER_VALIDATE_EMAIL));"
php -r "var_dump(json_decode('{\"active\":true}', true, flags: JSON_THROW_ON_ERROR));"
php -r "echo (new DateTimeImmutable('2026-06-10'))->modify('+30 days')->format('Y-m-d') . PHP_EOL;"

The first command checks a return value and type. The second checks the array shape produced by JSON decoding. The third checks a date transformation from a fixed input, making the result reproducible.

Avoid experiments based on now, tomorrow, the machine timezone, random values, or mutable external data unless those variables are the subject of the investigation. Fixed inputs make it easier to explain and repeat the finding.

Move A Prototype Into A File

Suppose you explore a tag-normalisation rule in the shell:

php > $tag = trim('  Release_Candidate  ');
php > $tag = strtolower($tag);
php > $tag = preg_replace('/[ _-]+/', '-', $tag);
php > var_dump($tag);
string(17) "release-candidate"

The experiment proves one path. It does not define what happens for an empty value, unsupported punctuation, repeated separators, or multiple examples. Durable code needs an explicit contract:

<?php

declare(strict_types=1);

function normaliseTag(string $tag): string
{
    $tag = trim($tag);

    if ($tag === '' || preg_match('/^[A-Za-z0-9 _-]+$/D', $tag) !== 1) {
        throw new InvalidArgumentException('Tag contains unsupported characters.');
    }

    $tag = strtolower($tag);
    $normalised = preg_replace('/[ _-]+/', '-', $tag);

    if ($normalised === null) {
        throw new RuntimeException('Tag normalisation failed.');
    }

    $normalised = trim($normalised, '-');

    if ($normalised === '') {
        throw new InvalidArgumentException('Tag must contain a letter or digit.');
    }

    return $normalised;
}

The function deliberately documents an ASCII input contract. It does not pretend that strtolower() implements Unicode-aware language rules. A project that accepts international text needs a separately designed Unicode policy and appropriate extension support.

Protect Secrets And Production Data

Readline-enabled PHP normally stores shell history in ~/.php_history. Since PHP 8.4, PHP_HISTFILE can select another history path. Your operating-system shell may also save the original php -r command.

Do not type passwords, API tokens, private customer data, or production connection strings into either command history. Clearing a terminal screen does not remove history files, process arguments, audit logs, screen recordings, or copied output.

Treat application REPLs as production access when they boot production configuration. A read-looking expression can trigger lazy loading, accessors, events, or external calls. Database writes, queue dispatches, emails, payments, and destructive filesystem operations belong in reviewed, repeatable commands with safeguards and logs.

Know The Project-Specific Alternatives

Laravel Tinker is a REPL powered by PsySH and can boot a Laravel application. PsySH can also be used outside Laravel. These tools provide richer inspection than PHP's native shell, but loading the application also increases the possible side effects.

Symfony Console is primarily a framework for named commands, not an automatic project REPL. A Symfony project may add PsySH or another shell, but bin/console by itself should not be described as an interactive PHP evaluator.

For static facts, a shell may be unnecessary. The PHP CLI provides reflection-oriented options:

php --rf array_map
php --rc DateTimeImmutable
php --ri json

These inspect a function, class, or extension without creating session state.

Stop Exploring At The Right Time

Move the work into a committed script, test, migration, or console command when:

• another person needs to repeat it;
• the result changes data or external systems;
• input validation and failure handling matter;
• more than a few lines are required;
• the finding documents a bug or compatibility decision;
• code review or an audit trail is required.

A strong workflow is: state one question, run the smallest controlled experiment, record the result, then encode lasting behaviour in a test or named piece of code.

What You Should Be Able To Do

After this lesson, you should be able to determine whether php -a is available, use php -r without script tags, inspect the exact CLI configuration, load Composer's autoloader deliberately, avoid history leaks, and turn a successful experiment into validated project code.

The official references are PHP's interactive shell manual and CLI options manual.