[6.x] FR: Enable routing element url to controller actions instead of just a template

[wsydney76]

While we're looking forward to greater integration with Blade, routing to a template instead of a controller action seems to be rather unusual for Laravel developers.

Besides better separating application logic from presentation, there are several other use cases where routing through a controller is preferable (for both Twig and Blade):

• Testing: If the database queries live inside Blade, testing becomes awkward because rendering the template is the only way to execute that logic. The controller action is testable, e.g. via ->assertViewHas('entry', fn(Entry $e) => $e->title === 'The Test Entry in English')
• Selecting the final template: You can call different tempates in different situations, e.g. dedicated templates for each entry type.
• Content representations: Serve different formats (e.g. JSON, PDF) depending on query params/http headers.
• Authorization: Use different templates depending on user status, e.g. public content, content for members.
• Customization: Show different sets of data depending on user preference.
• Form handling/validation: enable forms (e.g. a feedback form) to be backed by an entry and handle validation/data processing from the controller without extra actions.
• Performance: Handle caching of reused data

Some quick and dirty experiments for now:

As a start and without looking deeply into Craft's code, we experimented with the SetRoute event, setting a section's template site setting to something like route:App\Http\Controllers\ArticleController:show and hacking the route like:

if (str_starts_with($template, 'route:')) {
    $parts = explode(':', $template);
    $event->handled = true;
    $event->route = ['/tmproute', []];

    $actionTrigger = app(GeneralConfig::class)->actionTrigger;
    Route::get("/{$actionTrigger}/tmproute", [$parts[1], $parts[2]]);
}

which seems to work at first glance, but messes up Laravel functionality like paginators page url generation.

Or setting up custom routes matching the sections URI settings, which seem to 'win' over Craft's routing (is that guarenteed??)

Route::any('{site}/demo/{slug}', [DemoController::class, 'showByManualRoute'])->middleware([
    ResolveSite::class,
    CustomGetMatchedElement::class,
]);

(where CustomGetMatchedElement is a copy of the HandleMatchedElementRoute middleware, just letting the request continue.)

This also seems feasible, but it requires setting up many routes, especially in multi-site installations, and requires a better understanding of how Craft's middleware works.

Or pointing the route to a 'proxy' template:

{{ new App\Http\Controllers\DemoControllerDemoController()->show() }}

No idea whether this would always work.

So it would be great to have official support for routing to controller actions, whether through the CP UI, event handling, documentation, or any other supported mechanism.

[riasvdv]

Or setting up custom routes matching the sections URI settings, which seem to 'win' over Craft's routing (is that guarenteed??)

Yes, your own application routes will always win from Craft's, the Craft site route is registered as a fallback route.

I do agree it would be cumbersome, so I've added a way to define this when using the SetRoute event: f6903a2

You can look at the tests in that commit on usage.

The matched element can be added as a parameter to your controller's method, either through ElementInterface $element or by its refname, in the case of an entry this would be Entry $entry

[AugustMiller]

Craft will transparently “proxy” the return from Element::getRoute() (after an element is matched via its natural URI), and generate a response as though that route was called.

This is roughly equivalent to the 5.x behavior, but should be compatible. The one major limitation in the Laravel implementation that I can see is that it will only accept “action” routes, which we're slowly moving away from. All this means is that it's technically only possible for plugins to register, via their routes/actions.php file (we don’t support this routes file for the application).

Here’s a working example that replaces the controller for an entry:

# In your plugin’s `bootPlugin()` method…

Event::listen(function (\CraftCms\Cms\Element\Events\SetRoute $event) {
    if (! $event->element instanceof Entry) {
        // …or other conditions!
        return;
    }

    $event->handled = true;

    // Legacy “action route” format:
    $event->route = [
        'my-plugin/some-element-route',
        [
            'variables' => [
                'entry' => $event->element,
            ],
        ],
    ];
});

# routes/actions.php

# Bind the action path to your controller:
Route::get('some-element-route', MyController::class);

(The second step is not necessary if you are using the adapter and your controller is automatically given an action route!)

I'm curious what Rias will recommend, as far as making this future-friendly. It would be great to be able to set a class name (i.e. App\Http\Controllers\ArticleController::class) onto the SetRoute event and cut out the intermediate action route registration!

(Oh, he already replied!!!)

[wsydney76]

Phantastic, that was quick, thanks. Just played around with the dev branch which works great, this is what our experiment looks like now:

<?php

namespace wsydney76\craft6blade\Listeners;

use CraftCms\Cms\Element\Events\SetRoute;
use CraftCms\Cms\Entry\Elements\Entry;
use CraftCms\Cms\Route\ControllerRoute;
use http\Exception\InvalidArgumentException;

class HandleSetRoute
{
    public function handle(SetRoute $event): void
    {
        $element = $event->element;

        // Provisionally only top-level entries
        if (!($element instanceof Entry) || !$element->section) {
            return;
        }

        $template = $element->section->getSiteSettings()[$element->siteId]->template ?? null;

        if (!$template) {
            return;
        }

        if (str_starts_with($template, 'route:')) {

            $action = explode(':', $template);
            array_shift($action);

            if (count($action) !== 2) {
                throw new InvalidArgumentException('Template must have exactly 2 route parts after prefix, separated by colon.');
            }

            $event->route = new ControllerRoute($action, [
                'format' => request()->query('format', 'html'), // project-specific convention
            ]);

            $event->handled = true;
        }
    }
}

Just some questions (no priority)

• Is there a generic, element type agnostic way to get the configured template, instead of the entry specific $element->section->getSiteSettings()[$element->siteId]->template something like $element->theTemplateItWillBeRenderedWithForTheCurrentSite ?

• The extra params option is great, show(Entry $entry, string $format) will however resolve to $format = the entry title (probably via _toString()), while show(Entry $entry, ElementInterface $element, string $format) works. So the extra params are not bound by name, but by position? Which is ok, you just have to know.

• Could it make sense to support more methods than just the hardcoded GET ? Could feel a bit closer to a Laravel resource controller, for some use cases like updating an entry from the frontend or adding content like comments, reviews etc.

PS.
On a side note:

The blade directives do not register, I (well, AI) had to change in ViewServiceProvider::registerBladeDirectives:

// replace
$this->app->afterResolving('blade.compiler', function (BladeCompiler $blade): void {}

// with 

$this->callAfterResolving('blade.compiler', function(BladeCompiler $blade): void {}

[riasvdv]

Is there a generic, element type agnostic way to get the configured template

No not currently

The extra params option is great,...

This is indeed confusing, I've adjusted the implementation so only ElementInterface $element is passed to the controller.

Could it make sense to support more methods than just the hardcoded GET

No, the way we register the fallback route which makes Craft handle the route is GET only. You are free to register any routes you want if you want to update entries from the frontend and use all the services / element queries Craft provides.