Installation

You need PHP 8.5, a CakePHP 6 development application, and Composer. The standard package includes the browser runtime; Node and npm are not required. Interact is available on Packagist as dev-main only. There is no stable release yet, and the API is experimental.

To explore without integrating an existing application, run the demo.

Install in your application

Run these commands from your CakePHP application's root directory:

composer config minimum-stability dev
composer config prefer-stable true
composer require josbeir/cakephp-interact:dev-main --with-all-dependencies

Packagist is Composer's default repository; no custom repository or separate clone is needed. The stability settings permit CakePHP's development dependencies while preferring stable versions where possible. Interact targets CakePHP 6; these steps do not make an existing CakePHP 5 application compatible.

Browser runtime

Composer installs the prebuilt webroot/js/runtime.js and its third-party license notices with the PHP plugin. The runtime includes Alpine CSP and Alpine Morph. The helper queues this script automatically; no JavaScript build is needed.

Composer updates supply the matching runtime alongside the PHP source. Deploy the included webroot/ assets with the package and serve them as described below.

Load the plugin

Add the plugin inside your existing Application::bootstrap() method, after parent::bootstrap():

use Interact\InteractPlugin;

$this->addPlugin(InteractPlugin::class);

The use declaration belongs with the imports at the top of src/Application.php; the call belongs inside the method. Keep your existing plugin registrations.

Load the helper

Add this configuration to your existing AppView. The complete minimal class is:

<?php
declare(strict_types=1);

namespace App\View;

use Cake\View\View;
use Interact\View\Helper\InteractHelper;

/**
 * Makes the island mounting helper available to application templates.
 */
class AppView extends View
{
    /**
     * Register Interact alongside the application's other view helpers.
     */
    public function initialize(): void
    {
        parent::initialize();
        $this->addHelper('Interact', ['className' => InteractHelper::class]);
    }
}

The helper queues the standalone script once. Ensure your layout outputs the script block, usually inside <head>:

<?= $this->fetch('script') ?>

Serve plugin assets through your normal CakePHP asset setup. For a web server serving the application webroot directly, create the plugin asset symlink:

bin/cake plugin assets symlink Interact

Check that /interact/js/runtime.js returns JavaScript under your application's base URL. See troubleshooting if it returns a 404 or HTML.

Keep the update route protected

The plugin registers POST /_interact/update, named interact:update. Your middleware stack must run CakePHP's error handler, routing, body parser, and CSRF protection, together with your authentication integration. The update route needs the same access protections as the original page.

Keep CSRF enabled. The helper reads the request's CSRF token and the runtime sends it with same-origin update requests. For protected route scopes, read security and deployment before exposing an island.

Next: Build your first island.

Application-owned Alpine

Use Alpine 3.17.4 or later in the 3.x series. Interact uses Alpine’s native expression evaluation API to keep submission promises and failures observable.

Use this integration when your application already starts Alpine. This optional integration needs Node 24.11+ or Node 26+ and a JavaScript build. Build the npm module in the installed package, then install it from your application's root:

cd vendor/josbeir/cakephp-interact
npm ci
npm run build
cd ../../..

npm install ./vendor/josbeir/cakephp-interact @alpinejs/csp

Set autoScript to false in the helper configuration:

$this->addHelper('Interact', [
    'className' => InteractHelper::class,
    'autoScript' => false,
]);

Register the plugin before your application's existing Alpine.start():

import Alpine from '@alpinejs/csp';
import interact from '@josbeir/cakephp-interact';

Alpine.plugin(interact);
Alpine.start();

Load this entry using your application's bundler. Use one Alpine instance per page; omit the standalone Interact script for this integration. If you use standard alpinejs instead, its expression evaluator has different CSP needs. Repeat the module build and refresh your application's dependency after Composer updates the plugin.

Prepare the plugin checkout

For plugin development, you can use a local checkout instead of the Packagist package. Install Node 24.11+ or Node 26+, clone the plugin next to your application, then build its assets:

git clone https://github.com/josbeir/cakephp-interact.git
cd cakephp-interact
npm ci
npm run build

From your application's root directory, configure the sibling checkout as a path repository before running the Composer installation commands above:

composer config repositories.interact path ../cakephp-interact

Build assets in that checkout. For application-owned Alpine, use npm install ../cakephp-interact @alpinejs/csp instead of the vendor path.

Enhanced navigation setup

The existing Interact installer also installs its internal navigation integration. No additional JavaScript dependency or stylesheet is needed. Keep rendering the layout's script block even with autoScript: false: the helper supplies document compatibility metadata for the npm integration too.

Use x-interact:navigate to opt individual links in. The default plugin middleware marks complete HTML responses after application middleware. Missing metadata, unsupported pages, and incompatible document policies use native navigation.