Phar Composer Laravel Package

Getting Started

Install it as a dev dependency so it never ships in your app:

composer require --dev clue/phar-composer

Then build from your project root:

vendor/bin/phar-composer build .

That reads your composer.json, resolves/installs production dependencies, and writes a single executable .phar (typically named after your package) into the working directory. The other two commands worth knowing on day one:

• phar-composer install <package> — builds and drops the phar into /usr/local/bin (handy for distributing internal CLI tools).
• phar-composer build vendor/package:^1.0 or build https://github.com/org/repo.git:dev-main — build straight from Packagist or a git URL, no local checkout needed.

Where to look first: the README Usage section, and your own composer.json's bin and autoload keys — those are effectively the config for this tool. First realistic use case for a Laravel developer is not a full Laravel app; it's a standalone CLI tool (an artisan-style command built on illuminate/console + illuminate/container, or plain symfony/console) that you want to hand to teammates or CI without a composer install.

Implementation Patterns

Ship CLI tools, not web apps. Keep the phar'd tool in its own Composer package/repo with a bin entry, e.g.:

{
    "require": { "illuminate/console": "^10.0", "illuminate/container": "^10.0" },
    "autoload": { "psr-4": { "App\\Cli\\": "src/" } },
    "bin": ["bin/tool"]
}

You get the parts of Laravel you actually need (console kernel, container, config repo) without bootstrap/app.php, HTTP kernel, or storage paths. Laravel Zero projects work too, though they have their own build command — pick one and stick with it.

Wire it into Composer scripts so composer build matches the rest of your workflow:

"scripts": { "build": "phar-composer build ." }

CI release job. Build on tag, attach the artifact:

- run: composer install --no-dev --prefer-dist
- run: curl -JOL https://clue.engineering/phar-composer-latest.phar
- run: php phar-composer.phar build .
- uses: softprops/action-gh-release@v1
  with: { files: "*.phar" }

Build from a URL in deploy scripts when consumers shouldn't need git or Composer:

phar-composer build https://github.com/your-org/tool.git:^2.0

Reproducibility: pin the ref (vendor/package:1.4.2), and build on the lowest PHP minor you support — Composer's generated platform_check.php gets bundled and will refuse to run on unsupported runtimes.

Local distribution: phar-composer install your-org/tool puts it in $PATH; useful for internal ops tools where a global Composer install is overkill.

Gotchas and Tips

• Full Laravel apps are a poor fit. base_path(), storage_path(), view compilation, .env loading, and anything writing to disk behave badly from inside phar://. Migrations, config caches, and log files especially. If you need a phar, extract stubs to a temp dir at runtime instead of reading/writing inside the archive.

• phar.readonly. The default php.ini setting is 1, and phar creation will fail with “creating archive ... disabled by the php.ini setting phar.readonly”. If a build errors, run php -d phar.readonly=0 phar-composer.phar build ..

• Your bin and autoload are the config. Packages without an autoload definition or without a resolved vendor/ directory are silently skipped — a script-only package can produce a phar with nothing meaningful inside. Always verify with php tool.phar --version (and chmod +x tool.phar for the shebang) right after building.

• Dev dependencies aren't bundled. The build installs non-dev dependencies only, so anything referenced at runtime from require-dev (PHPUnit extensions, faker stubs, mock libs) will vanish in the phar.

• Native extensions can't be embedded. ext-* requirements must exist on the target machine; the phar only bundles PHP source. Database drivers are the usual culprit.

• vendor/ is excluded from the source scan automatically (that's a performance fix, not a bug). Don't try to ship a pre-built vendor dir alongside your sources.

• Debugging a broken phar: unpack and inspect it —

  php -r '$p = new Phar("tool.phar"); $p->extractTo("unpacked");'
  

  Then diff unpacked/vendor/autoload.php and the stub against your expectations. Running with php -d display_errors=1 tool.phar surfaces swallowed fatals the stub may hide.

• Windows: install is disabled; use build and place the phar on $PATH manually. Recent releases fixed path detection and slow network-drive renames, so prefer the latest 1.4.x phar over any vendored copy.

• Maturity: last release Feb 2022, but it supports Composer 2 and PHP 8.1+. Test against new PHP minors before trusting it in a release pipeline — you may see deprecation noise from the bundled Symfony/Console layer.

• No extension points. There's no config file or plugin API; customization happens entirely through composer.json and your stub script. For anything more elaborate (file exclusions, custom stubs, compression), reach for humbug/box instead.

• Self-updating: no update command — re-download the release or run phar-composer install clue/phar-composer again.