Yorn Laravel Package

Getting Started

First, correct your mental model: despite the package description mentioning Symfony Console, nunomaduro/yorn is an experimental PHP extension/loader that adds JavaScript-style import/export syntax to PHP. You are not installing a Composer library you can use — you are adding a nonstandard language surface that must be compiled and enabled in the runtime before any file containing import/export will parse.

Minimal path:

git clone https://github.com/nunomaduro/yorn.git
cd yorn
phpize && ./configure && make && sudo make install
# then in php.ini (or a -d flag / Dockerfile layer):
# extension=yorn.so
php -m | grep -i yorn   # verify it loaded

Then confirm the syntax works at all before writing anything real:

// math.php
export function add(int $a, int $b): int {
    return $a + $b;
}

// index.php
import { add } from './math.php';
echo add(2, 3);

Where to look first: the tests/ directory and the extension source. With ~144 stars and zero dependents, the tests are the only reliable specification of what syntax is actually supported — the README is aspirational, the tests are behaviour. Read them before designing anything.

First use case: a throwaway spike or a self-contained CLI script in a sandboxed container. Not an existing Laravel app, not a package you intend to publish. The deliverable of your first session is a written answer to "does this parse, run, and cache predictably in our image?" — not working code.

Implementation Patterns

• One module per file, named exports only. export function / export const, never default exports. Named exports keep the dependency graph greppable and make the eventual migration to static methods mechanical.
• Thin entry file. One file performs all imports and delegates to exported functions; the modules themselves stay pure and testable. This is also your migration seam later.
• Pin everything at the image level. The extension is built against a specific PHP ABI. Pin the PHP version in your Dockerfile, pin the Yorn commit, and rebuild the extension as part of the image — never rely on a developer's local make install. A PHP minor upgrade silently invalidates the .so.
• Keep Composer on the outside. Yorn does not replace PSR-4. Inside exported functions, use normal use statements for vendor packages and let Composer's autoloader handle them. The boundary is: Yorn-parsed files declare no namespace; everything else is untouched Laravel/Composer.
• Quarantine the syntax. Put Yorn modules in a dedicated directory (e.g. spikes/modules/) that is excluded from Pint, PHPStan, Psalm, and the Composer autoload map. If it isn't in autoload, composer dump-autoload and artisan will never trip over it.
• Smoke test through the loader. Exported functions are ordinary PHP functions at runtime, so PHPUnit can often call them once the module is loaded — but verify with one test before building a suite, because the loading mechanics are undocumented.
• Compare, don't commit. Run the same spike twice: once in Yorn, once as plain PSR-4 classes. The value of the exercise is the delta in ergonomics, not the artifact.
• Prototype-then-lift. Treat Yorn modules as disposable sketches. If a module survives, lifting export function add() into final class Math { public static function add() } should be a fifteen-minute change.

Gotchas and Tips

• The description lies. Documentation describes a Symfony Console wrapper; the repository is a language-level module extension. Trust the source, not the metadata — this mismatch alone is a signal about how much scrutiny the docs have had.
• No IDE or static-analysis support. PhpStorm, PHPStan, and Psalm will not parse import/export. Expect red squiggles and zero autocompletion. Use per-directory exclusions/baselines rather than disabling analysis globally — degrading your whole codebase to accommodate an experiment is the wrong trade.
• Transform overhead. Files must be transformed before PHP executes them. Check whether compiled output is cached; if it isn't, never put a Yorn module on a hot path. Prefer ahead-of-time generation so production never depends on runtime transpilation.
• Debugging is indirect. Stack traces and __FILE__/__DIR__ may point at generated or cached files rather than your originals. var_dump inside the module and compare against the transformed output — that comparison will explain most "impossible" bugs.
• Relative imports are literal. ./math.php resolves relative to the importing file, not the CWD. Mixing relative and absolute paths produces the least helpful error messages in the toolchain.
• Never mix paradigms in one file. A file with both a namespace declaration and import/export will break. Hard rule: Yorn files are namespace-free.
• Laravel is the wrong host. Blade, Artisan, queue workers, Octane, and preloading all assume a standard interpreter. If you must try it, keep it outside app/ and out of every autoloaded path so a colleague can composer install && artisan serve without building an extension.
• Plan the exit on day one. Zero dependents means you are the only person exercising your code path, and you inherit the maintenance. Assign an owner, document the rollback (delete the directory, convert to classes), and re-evaluate at each PHP minor release. If the spike doesn't produce a concrete finding for your architecture RFC, retire it immediately — the real risk here is scope creep, not the extension itself.