README

PHP middleware for handling Javascript Unpoly Framework requests.

Built by The Webstronauts, go-to agency for challenging ideas and ambitious organisations.

Unpoly Protocol Support

This package implements the Unpoly 3.x protocol, providing full server-side support for:

• ✅ Request inspection - Detect Unpoly requests, read target selectors, layer modes, and context
• ✅ Layer management - Accept/dismiss overlays, open new layers, manage layer context
• ✅ Response manipulation - Set document title, emit events, override targets
• ✅ Cache control - Evict or expire cached responses
• ✅ Cache revalidation - Support If-Modified-Since, If-None-Match, ETag, Last-Modified, and 304 responses
• ✅ Vary header management - Proper cache partitioning with Vary headers
• ✅ Validation support - Detect validation requests and handle field-level validation
• ✅ Context management - Read and update layer context data
• ✅ Location/Method control - Explicitly set browser location and method after fragment updates

The package is compatible with Unpoly 3.x. See the official protocol documentation for details.

Installation

You can install the package via Composer.

composer require webstronauts/unpoly

Usage

You can manually decorate the response with the Unpoly object.

use Symfony\Component\HttpFoundation\Request;
use Symfony\Component\HttpFoundation\Response;
use Webstronauts\Unpoly\Unpoly;

// ...

$unpoly = new Unpoly();
$unpoly->decorateResponse($request, $response);

Symfony

To use the package with Symfony, create an event subscriber that decorates responses:

<?php

namespace App\EventSubscriber;

use Symfony\Component\EventDispatcher\EventSubscriberInterface;
use Symfony\Component\HttpKernel\Event\ResponseEvent;
use Symfony\Component\HttpKernel\KernelEvents;
use Webstronauts\Unpoly\Unpoly;

class UnpolySubscriber implements EventSubscriberInterface
{
    public static function getSubscribedEvents(): array
    {
        return [
            KernelEvents::RESPONSE => 'onKernelResponse',
        ];
    }

    public function onKernelResponse(ResponseEvent $event): void
    {
        if (!$event->isMainRequest()) {
            return;
        }

        (new Unpoly())->decorateResponse($event->getRequest(), $event->getResponse());
    }
}

Register the subscriber in config/services.yaml:

services:
    App\EventSubscriber\UnpolySubscriber:
        tags:
            - { name: kernel.event_subscriber }

Laravel

To use the package with Laravel, you'll have to wrap it around a middleware instance.

<?php

namespace App\Http\Middleware;

use Closure;
use Webstronauts\Unpoly\Unpoly as UnpolyMiddleware;

class Unpoly
{
    /**
     * Handle an incoming request.
     *
     * @param  \Illuminate\Http\Request  $request
     * @param  \Closure  $next
     * @return mixed
     */
    public function handle($request, Closure $next)
    {
        $response = $next($request);

        (new UnpolyMiddleware)->decorateResponse($request, $response);

        return $response;
    }
}

Now use this middleware as described by the Laravel documentation.

<?php

// Within App\Http\Kernel class...

protected $routeMiddleware = [
    // ...
    'unpoly' => \App\Http\Middleware\Unpoly::class,
];

Validation Errors

Whenever a form is submitted through Unpoly, the response is returned as JSON by default. This is because Laravel returns JSON formatted response for any request with the header X-Requested-With set to XMLHttpRequest. To make sure the application returns an HTML response for any validation errors, overwrite the convertValidationExceptionToResponse method in your App\Exceptions\Handler class.

<?php

// Within App\Exceptions\Handler class...

protected function convertValidationExceptionToResponse(ValidationException $e, $request)
{
    if ($e->response) {
        return $e->response;
    }

    return $request->expectsJson() && ! $request->hasHeader('X-Up-Target')
        ? $this->invalidJson($request, $e)
        : $this->invalid($request, $e);
}

Other HTTP Errors

If your Laravel session expires and a user attempts to navigate or perform an operating on the page using Unpoly, an abrupt JSON error response will be displayed to the user:

{'error': 'Unauthenticated.'}

To prevent this, create your own Request and extend Laravel's built-in Illuminate\Http\Request, and override the expectsJson method:

namespace App\Http;

use Illuminate\Http\Request as BaseRequest;

class Request extends BaseRequest
{
    public function expectsJson()
    {
        if ($this->hasHeader('X-Up-Target')) {
            return false;
        }

        return parent::expectsJson();
    }
}

Then, navigate to your public/index.php file, and update the usage:

// From...
$response = $kernel->handle(
    $request = Illuminate\Http\Request::capture()
);

// To...
$response = $kernel->handle(
    $request = App\Http\Request::capture()
);

Now when a user session expires, the <body> of your page will be replaced with your login page, allowing users to sign back in without refreshing the page.

Testing

composer test

Changelog

Please see CHANGELOG for more information on what has changed recently.

Credits

As it's just a simple port of Ruby to PHP code. All credits should go to the Unpoly team and their unpoly gem.

• Robin van der Vleuten
• All Contributors

License

The MIT License (MIT). Please see License File for more information.