Download the PHP package archtechx/airwire without Composer

Note: Development is currently paused. It will be resumed after we launch Lean Admin this year.

Airwire

A lightweight full-stack component layer that doesn't dictate your front-end framework

Demo

Introduction

Airwire is a thin layer between your Laravel code and your JavaScript.

It lets you write Livewire-style OOP components like this:

Then, it generates a TypeScript definition like this:

And Airwire will wire the two parts together. It's up to you what frontend framework you use (if any), Airwire will simply forward calls and sync state between the frontend and the backend.

The most basic use of Airwire would look like this:

Installation

Laravel 8 and PHP 8 are needed.

First install the package via composer:

Then go to your webpack.mix.js and register the watcher plugin. It will refresh the TypeScript definitions whenever you make a change to PHP code:

Next, generate the initial TS files:

This will create airwire.ts and airwired.d.ts. Open your app.ts and import the former:

If you have an app.js file instead of an app.ts file, change the file suffix and update your webpack.mix.js file:

If you're using TypeScript for the first time, you'll also need a tsconfig.json file in the the root of your project. You can use this one to get started:

And that's all! Airwire is fully installed.

PHP components

Creating components

To create a component run the php artisan airwire:component command.

The command in the example will create a file in app/Airwire/CreateUser.php.

Next, register it in your AppServiceProvider:

Wired properties and methods

Component properties and methods will be shared with the frontend if they use the #[Wired] attribute (in contrast to Livewire, where public visibility is used for this).

This means that your components can use properties (even public) just fine, and they won't be shared with the frontend until you explicitly add this attribute.

Lifecycle hooks

As showed in the example above, Airwire has useful lifecycle hooks:

Validation

Airwire components use strict validation by default. This means that no calls can be made if the provided data is invalid.

To disable strict validation, set this property to false:

Note that disabling strict validation means that you're fully responsible for validating all incoming input before making any potentially dangerous calls, such as database queries.

Custom types

Airwire supports custom DTOs. Simply tell it how to decode (incoming requests) and encode (outgoing responses) the data:

This doesn't require changes to the DTO class, and it works with any classes that extend the class.

Models

A type transformer for models is included by default. It uses the toArray() method to generate a JSON-friendly representation of the model (which means that things like $hidden are respected).

It supports converting received IDs to model instances:

Converting arrays/objects to unsaved instances:

Converting properties/return values to arrays:

If you wish to have even more control over how the data should be encoded, on a property-by-property basis, you can add a Decoded attribute. This can be useful for returning the id of a model, even if a property holds its instance:

Default values

You can specify default values for properties that can't have them specified directly in the class:

These values will be part of the generated JS files, which means that components will have correct initial state even if they're initialized purely on the frontend, before making a single request to the server.

Readonly values

Properties can also be readonly. This tells the frontend not to send them to the backend in request data.

A good use case for readonly properties is data that's only written by the server, e.g. query results:

Mounting components

Components can have a mount() method, which returns initial state. This state is not accessible when the component is instantiated on the frontend (unlike default values of properties), so the component requests the data from the server.

A good use case for mount() is <select> options:

Mount data is often readonly, so the method supports returning values that will be added to the frontend component's readonly data:

Metadata

You can also add metadata to Airwire responses:

This metadata will be accessible to response watchers which are documented in the next section.

Frontend

Airwire provides several helpers on the frontend.

Global watcher

All responses can be watched on the frontend. This is useful for displaying notifications and rendering exceptions.

Reactive helper

Airwire lets you specify a helper for creating singleton proxies of components. They are used for integrating with frontend frameworks.

For example, integrating with Vue is as easy as:

Integrating with Vue.js

As mentioned above, you can integrate Airwire with Vue using a single line of code.

If you'd also like a this.$airwire helper (to avoid having to use window.Airwire), you can use our Vue plugin. Here's how an example app.ts might look like:

Integrating with Alpine.js

Note: The Alpine integration hasn't been tested, but we expect it to work correctly. We'll be reimplementing the Vue demo in Alpine soon.

Alpine doesn't have a reactive() helper like Vue, so we created it.

There's one caveat: it's not global, but rather component-specific. It works with a list of components to update when the data mutates.

For that reason, you'd need to pass the reactive helper inside the component:

To simplify that, you may use our Airwire plugin which provides an $airwire helper:

To use the plugin, use this call before importing Alpine:

Testing

Airwire components are fully testable using fluent syntax:

You can look at the package's tests to see real-world examples.

Protocol spec

Airwire components aren't signed or fingerprinted in any way. They're completely stateless just like a REST API, which allows for instantiation from the frontend. This is in contrast to Livewire which doesn't allow any direct state changes — they all have to be "approved" and signed by the backend.

The best way to think about Airwire is simply an OOP wrapper around a REST API. Rather than writing low-level controllers and routes, you write expressive object-oriented components.

Request

Response

State

The state refers to the old state, before any changes are made. The difference isn't big, since Airwire doesn't blindly trust the state, but it is separated from changes in the request.

One use of this are the updating, updated, and changed lifecycle hooks.

Changes

If the change is not allowed, Airwire will silently fail and simply exclude the change from the request.

Calls

Calls are a key-value pair of methods and their arguments.

If the execution is not allowed, Airwire will silently fail and simply exclude the call from the request.

If the execution results in an exception, Airwire will also add methodName: { exception object } to the exceptions part of the metadata.

Exceptions have a complete type definition in TypeScript.

Validation

Validation is executed on the combination of the current state and the new changes.

Properties that failed validation will have an array of error strings in the errors object of the metadata.

Compared to other solutions

Due to simply being a REST API layer between JavaScript code and a PHP file, Airwire doesn't have to be used instead of other libraries. You can use it with anything else.

Still, let's compare it with other libraries to understand when each solution works the best.

Livewire

Livewire is specifically for returning HTML responses generated using Blade.

Most of our API is inspired by Livewire, with a few minor improvements (such as the use of PHP attributes) that were found as a result of using Livewire.

The best way to think about Livewire and Airwire is that Livewire supports Blade (purely server-rendered), whereas Airwire supports JavaScript (purely frontend-rendered).

Neither one has the ability to support the other approach, so the main deciding factor is what you're using for templating.

(This comparison is putting aside all of the ecosystem differences; it only looks at the tech.)

Inertia.js

Inertia is best thought of as an alternative router for Vue/React/etc. There is some similarity in how Airwire and Inertia are used for a couple of use cases, but for the most part they're very different, since Inertia depends on visits, whereas Airwire has no concept of visits or routing.

Inertia and Airwire pair well for specific UI components — say that you use Inertia for most things on your frontend, but then you want to build a really dynamic component that sends a lot of requests to the backend (e.g. due to real-time input validation). You could simply install Airwire and use it for that one component, while using Inertia for everything else.