Pandoc Laravel Package

Getting Started

Install the package (typically as a dev dependency) and publish its config:

composer require --dev vendor/package
php artisan vendor:publish --tag=package-config

Read three things first, in this order:

1. config/<package>.php — most of the day-to-day knobs live here, including the default for standalone execution.
2. The package's service provider — this is where the fluent builder / command options are wired up.
3. The command signature (php artisan <command> --help) — the --standalone flag and its siblings are the fastest way to see what the builder methods map to.

A good first use case is simply running the command in an existing Laravel app and comparing the two modes:

php artisan package:command            # boots the framework, resolves the container
php artisan package:command --standalone  # runs without booting the app

What's new in 0.9.0: a noStandalone() method on the fluent configuration object. It opts your invocation out of standalone execution, regardless of the ambient default. This is the method to reach for when the work you're doing genuinely needs the container (Eloquent, config(), bindings, facades) and you don't want a stray --standalone in CI or a wrapper script to silently strip the framework out from under you.

Package::configure()
    ->noStandalone()
    ->run();

If you have no reason to touch standalone mode at all, 0.9.0 is additive and non-breaking — you can upgrade without changing code, though pinning to ^0.9 is sensible.

Implementation Patterns

Force framework context where it matters. Any code path that touches the database, config repository, or container bindings should be explicit about it. Chaining noStandalone() at the call site is clearer than relying on a config default that someone may flip later:

// app/Console/Commands/ExportReports.php
public function handle(): int
{
    return Package::configure()
        ->noStandalone()
        ->output($this->output)
        ->run();
}

Keep the default for scripts and CI. The whole point of standalone mode is speed — no app boot, no service providers, no DB connection. Let the default stand for lint-style, file-scanning, or code-generation work where the framework is irrelevant. Only opt out per invocation, not globally, unless your entire app depends on container access.

Wrap it in an Artisan command rather than shelling out. You get the output helper, exit codes, and testability for free. Delegate flags rather than hardcoding them, and only add noStandalone() where it is a genuine requirement — not as a blanket safety net.

Test both paths. noStandalone() is easy to cover with an Artisan assertion, and doing so documents intent:

it('runs in framework mode', function () {
    Package::configure()->noStandalone()->run();

    // or, at the command level:
    $this->artisan('package:command')->assertSuccessful();
});

Layer it with config. The builder method wins over the config default, which wins over the CLI flag — verify that precedence in the package's resolution code before you build anything clever on top of it.

Gotchas and Tips

• noStandalone() is not a CLI lock. It disables standalone mode for builder-driven invocations. If a user runs the underlying command directly with --standalone, they will still get standalone behaviour unless the command itself rejects the flag. Don't treat it as a security boundary.
• Standalone means no container. In that mode config(), env(), Eloquent, and facades are unavailable or unreliable. If you see Target class [...] does not exist or a null config value, the first thing to check is whether the code accidentally ran standalone.
• Option ordering and precedence. Fluent builder settings are resolved at run time, so calling noStandalone() after a terminal method like run() is a silent no-op. Chain it before the execution call.
• Config caching. If you set standalone behaviour inside a config file using a closure or a service-container lookup, php artisan config:cache will break it. Prefer scalar config values and put conditional logic in a service provider or at the call site.
• Debugging the resolution. When behaviour is unclear, dump the resolved mode just before execution (or use -v). Nine times out of ten the surprise is an inherited default from a published config file that predates your upgrade.
• Extension points. The fluent builder is the intended surface — prefer it over subclassing the command. If you need custom behaviour per environment, bind a small wrapper in a service provider and call noStandalone() there, keeping call sites clean.
• Upgrade hygiene. 0.9.0 adds a method only; no deprecations. Republish the config only if you want the new key documented alongside existing ones — otherwise leave your published copy alone to avoid noisy diffs.