Xphp Symfony Bundle Laravel Package

Getting Started

This is a Symfony bundle (xphp-lang/xphp-symfony-bundle), not a Laravel package — there is no ServiceProvider, no facade, and no config publish tag you can rely on. Treat it as the reference integration for the underlying xphp compiler and expect to write a thin Laravel adapter yourself.

Start here:

1. composer require xphp-lang/xphp-symfony-bundle:^0.2.0 (pin the minor — see Gotchas).
2. Read the bundle's DependencyInjection/ extension class and its service definitions first; that is the only authoritative documentation of which compiler services exist and how they are configured.
3. Ignore the bundle's kernel/Bundle class in Laravel. Register the underlying xphp compiler service yourself in a ServiceProvider::register() and bind it as a singleton.
4. First use case: transpile a single small file through the compiler in a Tinker session or an artisan command, before wiring it into any build step.

v0.2.0 is a syntax-level breaking change — the compiler now targets xphp v0.2.0's turbofish generic instantiation syntax (Foo::<T> style, Rust-like) instead of the previous instantiation form. Any source files, docblocks, or stubs in your repo that instantiate generics will need updating, and you must upgrade the xphp core to ^0.2.0 in lockstep.

Implementation Patterns

Wrap the compiler in a Laravel service. The bundle's value is its service wiring, not its HTTP/kernel integration. Extract the compiler construction into a singleton bound in your provider so commands, jobs, and tests all share one configured instance.

Artisan command as the entry point. A php artisan xphp:build {path} command is the most idiomatic Laravel surface: resolve the compiler from the container, glob your source directory, compile, and write output to a configurable target path. Keep the command dumb and put the file-walking logic in a dedicated class so it is unit-testable.

Match the turbofish syntax in your own code. Since v0.2.0 the compiler expects ::<>-style generic instantiation. Centralise your type-annotated instantiations in as few files as possible (a Types/ or Support/Generics directory) so the next syntax bump is a one-directory diff rather than a repo-wide grep.

CI gate, not runtime. Run the transpiler in a pipeline step or a pre-commit hook, not per-request. Compilation output should be committed or built as an artifact; there is no reason to pay compilation cost inside a web request.

Version-pin the pair. Constrain both xphp-lang/xphp and this bundle to the same 0.2.x range in composer.json. conflict entries for xphp <0.2.0 are cheap insurance given the pre-1.0 churn.

Gotchas and Tips

• Symfony package discovery does nothing for you. Laravel's package auto-discovery looks for Illuminate\Support\ServiceProvider; this bundle ships Symfony\Component\HttpKernel\Bundle\Bundle. You will get zero automatic registration — wire it manually or not at all.
• The bundle may pull Symfony components (http-kernel, dependency-injection, config). These install fine alongside Laravel but add weight and can create container/config interface collisions if you also run Symfony packages. Inspect composer why after install.
• Turbofish is a breaking change, not a feature. There is no deprecation path in this release — v0.1.0 syntax will not parse under v0.2.0. If you have v0.1.0-generated artifacts checked in, regenerate them; do not mix output from both compiler versions in one tree.
• 0.x semver means minor bumps break. Both packages are pre-1.0 and have now shipped a syntax-breaking change in a minor release. Pin with ~0.2.0 (not ^0.2) and upgrade deliberately.
• Debugging transpiler errors is easiest by compiling the single failing file through the compiler instance directly in Tinker rather than through your build command — you get the raw exception instead of one wrapped in your own command's output handling.
• Extension point: if you need config, mirror the bundle's extension class keys into a config/xphp.php and map them explicitly. Don't try to load the Symfony extension config format through Laravel's config repository.
• This release adds no new runtime capability — no new services, no new config keys, only the syntax target bump. If you are not yet on v0.1.0, there is no separate migration to plan; start directly on v0.2.0 semantics.