Download the PHP package fusionphp/fusion without Composer

Unite your modern frontend with your Laravel backend.

--- Fusion is the best way to combine your Laravel backend with your JavaScript frontend. We currently only support Vue.js, but React + Svelte are on the roadmap. > [!CAUTION] > 🚨🚨🚨 > > Fusion is in a _very_ early development preview. Please do not use it in production yet! There are still lots of > bugs (probably.) > > 🚨🚨🚨 ## Concepts It is important to note up front what Fusion **does not** do: - Fusion does not transpile your PHP to WASM. - Fusion does not turn your JavaScript into PHP/Blade. - Fusion does not use the "PHP for templating." - Fusion does not *automatically* sync frontend/backend state. What Fusion **does** do: - Fusion uses Vite to extract the PHP blocks from your JavaScript files and writes the PHP to disk. - Fusion uses Vite to inject some information into your JavaScript file as it is being transpiled. - Fusion runs your PHP on the backend and your JavaScript on the frontend. - Fusion turns your PHP block into a sort of controller. - Fusion uses the standard Laravel request/response lifecycle, router, auth, middleware, etc. - Fusion allows *you* to sync frontend/backend state. Conceptually, you can think of the `` block in your file as your controller, with a little bit of auto-wiring applied to inject state and call methods. That's about it! (To learn more, you may read the [how Fusion works](#how-fusion-works) section.) Using Fusion, you can write a single file like this: This exposes the `$name` variable to your Vue template as `name`. It will be passed down to the frontend upon first load. You do not need to define any props on the Vue side, we take care of that for you. There are two styles of PHP you can write. You can write "[procedural](#procedural-php)" or "[class-based](#class-based-php)" PHP. Procedural is much closer to a functional paradigm, and may feel more comfortable to folks coming from other languages like JavaScript. Writing the previous example using a class-based approach is very similar: You define a class and all public properties become state. Neither approach is right, neither is wrong. Neither approach is stupid, neither is smart. It's merely a matter of preference! More details on each approach can be found throughout. ## Installation **Fusion expects to be installed in a Laravel application that uses Inertia.** In the future we might not have that stipulation, but for now it needs to be an Inertia application. If you want to play with a Fusion app without creating your own, you can clone the [FusionCasts](https://github.com/fusion-php/fusioncasts) repo. To install Fusion into your application, you must first require it from Packagist: (Yes, it's `fusionphp` without a dash. The GitHub org is `fusion-php` but the packagist namespace is `fusionphp`.) Then you can run the installation command. The installation command will do the following: - Publish the `config/fusion.php` file - Make sure the correct storage directory exists - Add the Vue package to your `package.json` - Add a `fusion:install` script and modify the `postinstall` script to call it - Add the Vue plugin to your `resources/js/app.js` - Add the Vite plugin to your `vite.config.js` - Add a `post-update-cmd` to your `composer.json` - Migrate Fusion's internal SQLite database Fusion creates `[original].backup` files for each file it modifies, in case it messes your file up in any way. You're free to delete those once you're comfortable with the modifications. ## Getting Started You may now run Vite by running `npm run dev`. Fusion will run as a part of the Vite toolchain. (A Vite plugin was added by the `fusion:install` Artisan command.) Thanks to the Vite plugin, every `` block gets extracted from the `.vue` single file components (SFCs.) More in-depth information on the entire process can be seen at the bottom of the page. ## Routing You have two options when it comes to routing. You may choose to do file-based routing, or route your components individually. You are free to mix and mingle the styles. ### File-based routing File-based routing is convenient when you want your URL structure to mirror your file structure. To get started with file-based routing, you can call `Fusion::pages()` in your `web.php` file. The `pages` method accepts two arguments: a URI `$root` and a `$directory`. By default, the URI root is `/` and the directory is whatever is defined in your config under `paths.pages`, which is `resources/js/Pages` by default. By calling `Fusion::pages()` with no arguments, you're saying "route everything in my `fusion.paths.pages` directory, using `/` as the starting point." This includes pages that have no `` block. By passing arguments, you have more control over the routes. Maybe you only want to auto-route marketing pages, but you want them routed to the root domain. This will route an example component `Marketing/Hello.vue` to the URI `/hello`. You're free to use `pages` as many times as you want: #### Route binding Laravel has powerful [route model binding](https://laravel.com/docs/11.x/routing#route-model-binding), which allows you to automatically inject models into your controllers instead of having to look them up manually. Fusion exposes that same route model binding. To indicate that a route has a segment that is a parameter, you may use square brackets `[]` in the filename. For example, a file name `Podcasts/[Podcast].vue` would receive a `$podcast` parameter. When a user visits `podcasts/1`, you would receive a string `"1"` as your parameter. How you receive this parameter depends on the style of PHP you're writing. To receive it in procedural PHP, you may use the `fromRoute` method on the `prop` function. In this example, having not passed any arguments, we will assume that the route's parameter is named `podcast` because your variable was named `$podcast`. Should you need to customize it, you can pass a value: Using class-based PHP, you may receive the route parameter in your `mount` method. When you're using the class-based method of route binding, you actually do not have to include a `mount` function. If you have a public or protected property that is named the same as a route parameter, we will go ahead and auto set it if there is no `mount` function available. #### Route model binding So far, all we've done is _route_ binding, not _route model_ binding. Sometimes route binding is all you want. Most times, you want route model binding. To route model bind, you'll need to tell Fusion what class to look for. Using procedural PHP: And class based: If the model is not found, a 404 error will be thrown. Again, you can just use a public property instead of using the mount function and we will respect the type hint on that property. To customize the routing even further, you may pass more arguments to the procedural `fromRoute` method. These follow Laravel's standards of including [soft-deleted models](https://laravel.com/docs/11.x/routing#implicit-soft-deleted-models) and [customizing the route key](https://laravel.com/docs/11.x/routing#customizing-the-default-key-name). Customization using the class-based `mount` method is not available yet, but we'll add attributes to control the route key and soft-deletes very soon. Sorry about that! #### Wild-card routes If you have a route that might have many wildcard segments, you may indicate that with a preceding `...` in the parameter name, like this: `Podcasts/[...wild].vue`. In your PHP, we will pass `$wild` as an array, split by slashes (`/`). This can be useful for SEO purposes, amongst other things. Given a file of `Podcasts/[...wild].vue` and the URI `podcasts/the-best/show-in-the-world/a8f74b`, a prop of `$wild` will be equal to the array `['the-best', 'show-in-the-world', 'a8f74b']`. #### Fine-grained control over the routed files Should you need it, you may exercise greater control over file-based routing by passing a closure as the second argument. The Closure must return an instance of `\Symfony\Component\Finder`. ### Manual routing If you prefer to route your pages one-by-one, you may use the singular `page` method: You are free to combine `page()` along with `pages()`. We would suggest putting your `page` calls first, so that any routes with parameters or wildcards don't take precedence. ## Writing PHP Your PHP code must be contained inside of a single `` block, anywhere inside of your Vue SFC. It seems to make sense to place it as the first block in your file, since it's the first thing that will be executed when a request comes in. That's merely preference though, you're free to do as you please. Your PHP code will be run within the context of a Laravel request. You have full access to the [container](https://laravel.com/docs/11.x/container), [facades](https://laravel.com/docs/11.x/facades), [helpers](https://laravel.com/docs/11.x/helpers), and everything else Laravel has to offer. Regardless of the style of PHP you write, it must be valid PHP. If it isn't, Vite will show you an overlay with your errors. ### Best practices There aren't a lot of best practices for writing PHP in Vue templates or JavaScript files, because that's never really been done before! My recommendation is that you treat your PHP block as a "thin controller." I would recommend that you defer much of the business logic out to actions, service objects, or other classes in your application, and use the PHP block in your Vue template as a sort of routing layer into the rest of your application. Then, the PHP block in your Vue template only serves as an entry point from HTTP into the rest of your application. ### Procedural PHP Procedural PHP is very a straightforward, top-to-bottom style of writing your PHP. Fusion provides you a few important functions, which we will cover in detail elsewhere. For now, know that they are: - `prop` - `expose` - `mount` And that you may import them from the Fusion namespace: You do not *have* to import them, as they are available in your Vue files by default. They are worth importing though, if only for the sake of autocomplete. ### Class-based PHP Class-based PHP will feel much more familiar to traditional PHP developers. To use class based PHP, you must define an anonymous class: You may extend `Fusion\FusionPage` if you wish. You may `return` the class, if that feels more logical to you: ### Code highlighting in PHP blocks If you're using PhpStorm, you may configure a "Language Injection" to alert the editor that the language inside the `` block is PHP. In your preferences, look for Editor > Language Injections. In the top left you'll see a plus sign (+). From that menu, choose "XML Tag Injection". Then enter the following details. This should make your editing experience much nicer. We'll work with the JetBrains team to make this step unnecessary. As of now, we have no instructions on VSCode. Please stay tuned, we'll figure it out as quickly as we can. ## State One of Fusion's primary responsibilities is to send your state to the frontend. State is sent at runtime, not compiled into your JavaScript bundle. The only thing that gets written into your bundle are the names of your properties and exposed actions. ### State with Procedural PHP When using procedural PHP, you can expose a variable to the frontend by using the `Fusion\prop` function. > [!TIP] > This is very non-traditional PHP, and only possible because we're transpiling your PHP code before it gets written to > disk. All transpiled PHP is written into your storage directory and you're free to inspect it! By assigning a variable of `$name` to the function `prop`, you've alerted Fusion that `$name` is something that should be shared with the frontend. #### Defaults You are free to pass in a default value as either a scalar or a Closure. The _default_ is "Aaron", but if a different value is sent from the frontend, the `$name` variable will be assigned to that value. If the frontend sends `name: "Steve"`, then in your PHP `$name = "Steve"` instead of `"Aaron"`. We'll cover syncing state further down. #### Tracking Something that may feel familiar to a user of a JavaScript framework is that we'll keep track of that variable throughout your code. This will feel strange to most PHP developers: We're only able to do this because we are transpiling your code. At the end of the code that you write, we call a Fusion method named `syncProps` passing in `get_defined_vars()`. This gives us the names and values of all of the variables that are in scope. If you've declared a variable as a prop, we will take the last value and use that as the state for the frontend. #### Readonly state To declare a piece of state "readonly", meaning that you never want to receive it back from the frontend, you can append `->readonly()` to the `prop` function. When `name` gets sent to the frontend, it can still be modified *on the frontend,* if you allow that. But the frontend will never send it to the backend, the backend will *always* recalculate it. You can think of this type of state as computed props. #### Syncing values to the querystring It may be convenient to sync state to the querystring to create stable URLs. You may do so by appending `->syncQueryString`. By default `$search` is null, but if there is a `?search=` in the URL, that value will be used. If you want the querystring name to be different than the variable name, you may use the `as: ` argument. The querystring will now use `?s=` to track this prop. ### State with Class-based PHP Using class-based PHP, any properties that are `public` will be sent to the frontend. (WIth one caveat, mentioned below.) Declaring a class like this: will send `name` to your frontend to be consumed. If you need to hide a `public` property, you may annotate it with `#[Fusion\Attributes\ServerOnly]`. You should rarely need this. If you find yourself needing this often, please open an issue and explain why! We might be able to make it less cumbersome. #### Readonly state You may annotate a public property with `#[Fusion\Attributes\IsReadOnly]` to mark a property as readonly, i.e., it will never be set from a frontend request. Alternatively, you may set the value via the `mount` method to accomplish the same outcome. Consider the previous class: The default for `$name` is `Aaron`, but if a value comes in from the frontend where `name: "Steve"` then the `$name` variable will be set to `Steve`. However, if you annotate it with the attribute, it will stay "Aaron". Beyond annotating with the `#[IsReadOnly]` attribute, you can just brute-force the value in `mount`: Now, regardless of what was sent from the frontend, we set the value to `"Aaron"`. You could accomplish a "default" by using the null coalescing operator: This allows you to potentially sync the `name` state from the frontend, but otherwise assign a default. #### Syncing QueryString If you'd like to sync a property to the querystring, you may use the `#[SyncQueryString]` attribute. You're free to pass an `as:` argument to control the name of the querystring: The variable passed to your frontend will be named `search`, but in the querystring it will appear as `s`. ## Actions On the backend, along with state, you can declare "actions." Actions are a way for the JavaScript frontend to reach over the network and call functions on your backend. In the class-based approach, any method that you define as a `public` method will be exposed to the frontend. We'll talk further down about calling these methods from your JavaScript, but now on the frontend you have a `hello` function that will route to this method on the backend. If, for whatever reason, you don't want a public method to be reachable from the frontend, you can add a `ServerOnly` attribute to it in class-based PHP. In procedural PHP, you may pass the function as a named argument to the `expose` method and that will make it visible to the frontend. ## Working with JavaScript You don't _have_ to do anything to receive your state on the frontend, but there is a lot you _can_ do. Because we have a plugin in the Vite toolchain, we're able to add some Vue code to inject the state and actions for you automatically, provided you don't do it yourself. The automatic process is this simple: That's it! You do not have to define props, a `script` tag of any sort, or anything else. > [!NOTE] > We are still working on making your editor aware of these injected pieces of data. More on that soon. If you'd like to define your own script tags, you have as many options as Vue supports. ### A `