README

PHPThis Workbench is an explicit, development-only expression workspace for a PHPThis application. It helps a human inspect ordinary objects, try one call, and observe one returned value or failure without adding a temporary HTTP route.

Workbench is not an application container, queue facade, test runner, debugger, production console, or sandbox. Every entered expression is unchecked arbitrary PHP. Its authority combines the launching operating-system identity, inherited environment, independently loaded child PHP CLI configuration, ambient filesystem, network, process, and service access, native PHP functions and Composer-autoloaded code, and every explicitly composed dependency. The narrow workspace limits the intended application surface; it is not containment.

Install

Package availability is external state. Before changing dependencies in a PHPThis consumer, read installed vendor/phpthis/framework/docs/workbench.md, obtain accountable-human approval, record the bootstrap, concrete workspace type, complete authority, excluded credentials, resource limits, side-effect and job-path policy, and retained-test evidence in .ai/workbench.md, verify phpthis/workbench through the application's approved Composer source, and require clean consumer-install evidence.

Workbench is intended to be installed only as a development dependency:

composer require --dev "phpthis/workbench:^0.1@alpha"

The initial release series is alpha software. Workbench currently supports PHP 8.4.x with ext-readline; the package does not claim PHP 8.5 compatibility until that runtime is covered by its required interactive test suite.

Create one application-owned bootstrap, for example tools/workbench.php. It is ordinary application PHP and must pass the application's normal composer check. It returns exactly one concrete final named application-owned object:

<?php

declare(strict_types=1);

use App\Development\DevelopmentWorkspace;
use App\Routes;

return new DevelopmentWorkspace(
    routes: Routes::create(),
);

The concrete DevelopmentWorkspace class may expose narrowly named readonly values or operations. It is not a registry: do not give it a string-keyed service map, get() method, discovery, a service container, credentials, raw administrative connections, or generic queue dispatch.

The bootstrap argument is a 1-to-4,096-byte project-relative .php path using forward slashes. Empty, dot, parent, control-byte, absolute, root vendor, root .git, missing, unreadable, escaping, and directly symlinked paths are rejected. Start Workbench at a readable Composer project root with vendor/autoload.php already installed. The PHP CLI must also make proc_open available so Workbench can create the fresh expression process.

Fix the bootstrap path in the consuming application's Composer scripts:

{
  "scripts": {
    "workbench": [
      "Composer\\Config::disableProcessTimeout",
      "phpthis-workbench tools/workbench.php"
    ]
  }
}

Then start it from the application root:

composer workbench

Disabling Composer's process timeout keeps an intentional interactive session open beyond Composer's normal limit. It does not add a Workbench or per-expression timeout: an expression can still hang indefinitely until the operator or operating system terminates it.

Use

Workbench exposes only $workspace. Enter one PHP expression at a time:

phpthis> $workspace->routes[0]->parameterCount()
int(0)

phpthis> $workspace->previewWelcomeJob->execute($workspace->welcomeFixture)
object(App\Jobs\WelcomePreview)#...

A trailing semicolon is accepted. Each expression is compiled with declare(strict_types=1), receives a newly required bootstrap in a fresh child process, is inspected with native var_dump, and then exits. Variables and mutable objects do not persist into the next expression. Up and down recall up to 100 nonblank expressions from the current session; consecutive duplicates, :help, and :exit are omitted. :help shows the session rules and :exit closes Workbench.

Press Tab at the end of a nonempty line to complete :help, :exit, $workspace, or a matching expression already retained in the current session history. Session commands accept the trailing separator space that Readline may append to a unique completion. Completion uses only literal prefix matching. It does not inspect the workspace, discover application code, load the bootstrap, evaluate PHP, or persist candidates. Workbench provides no always-visible suggestion or application method and property completion.

An expression contains 1 through 16,384 bytes after the prompt, with no ASCII control byte or DEL. Workbench accepts one line and does not parse a statement language, provide multiline editing, or persist history.

This fresh-process model is deliberate. An ordinary compile failure, exception, or PHP Error ends that child without reusing its in-memory state in a later expression. It is not universal failure isolation: OS-level termination, resource exhaustion, signals, hangs, and durable side effects remain possible. A one-shot application operation does not reuse a connection, budget, trace, lease, worker, or other invocation state from an earlier experiment.

Jobs and side effects

An application may expose a concrete deferred-work handler with synthetic development input for inspection, or call an already-adopted business operation that atomically publishes one real job through the application's normal transaction path. Do not create a Workbench-only publisher or a second publication path. Workbench supplies no dispatch(), queue, job base class, class-name execution, discovery, run-by-ID, replay, retry, or worker helper.

Claiming one queued delivery remains the responsibility of the application's recorded, finite, tested, one-delivery operational command. The framework example spells this command jobs:run-one; that spelling is not a universal application command. Production one-off work also belongs in the application's operational console, where argument, authority, output, redaction, failure, idempotency, and audit behavior can be reviewed and tested.

Safety boundary

The narrow $workspace surface limits what the bootstrap deliberately presents; it is not a capability sandbox. Every arbitrary expression still retains inherited environment values, independently loaded child PHP CLI configuration, native PHP functions, Composer-autoloaded code, and any ambient filesystem, network, process, or service access permitted to the child process.
Run Workbench only under a dedicated development process identity and environment containing no production, migration, administrative, or unrelated secrets.
The bootstrap loads no configuration, database, session, queue, or external service unless its visible application code explicitly does so.
Workbench performs no environment-name safety check because a label is not an authority boundary.
The child uses the same PHP binary, working directory, OS identity, and inherited environment, but it starts its own CLI configuration. Parent-process ini_set values and php -d overrides are not an inherited safety boundary; Workbench clears only auto_prepend_file and auto_append_file explicitly.
Workbench keeps up to 100 expressions in process memory for up/down recall and prefix completion during the current session. It never reads or writes a history or completion file and clears the in-memory expressions when the session ends. It still prints values and exception messages without redaction; do not enter credentials, tokens, private data, or production payloads.
There is no HTTP, remote-shell, noninteractive batch, deployment, or production mode.
A Workbench result is exploratory evidence only. Retained behavior belongs in ordinary checked source plus automated tests and must pass composer check.

Production artifacts should install Composer dependencies with --no-dev and verify that phpthis/workbench and vendor/bin/phpthis-workbench are absent.

phpthis / workbench

Maintainers

Package info

Statistics

Security

README

Install

Use

Jobs and side effects

Safety boundary