README

TYPO3 extension typo3_routing

This extension lets you register frontend endpoints via PHP attributes on controller methods — the attribute-based counterpart to the backend-only Configuration/Backend/AjaxRoutes.php. It is response-format agnostic: return JSON, HTML, XML, or a download.

Warning

This package is in early development stage and may change significantly in the future. I am working steadily to release a stable version as soon as possible.

Note

The goal is a familiar, Symfony-Routing-like developer experience: declare a frontend endpoint with a single #[Route] attribute instead of wiring a custom middleware and duplicating the path across PHP and JavaScript.

✨ Features

• Attribute routing — declare an endpoint with #[Route] directly on a controller method
• Typed arguments — methods receive type-cast path/query/body values, no manual request reading
• Zero-config discovery — routes are collected at container compile time, no extra cache
• URL generation — a Fluid ViewHelper so the path lives once, not duplicated as a PHP constant and a JS string
• Opt-in caching — cache responses with #[Cache], with tag-based invalidation
• Opt-in rate limiting — throttle requests per client IP with #[RateLimit]
• Opt-in authentication & CSRF — protect routes with #[Authenticate] (bearer token / FE / BE user) and #[RequireRequestToken]
• Debug command — list every registered route as a table or JSON, including an --unprotected audit

🔥 Installation

Requirements

• TYPO3 >= 13.4
• PHP 8.2+

Composer

composer require konradmichalik/typo3-routing

TER

Download the zip file from TYPO3 extension repository (TER).

🚀 Quick start

Implement RouteControllerInterface, register the controller as a service, and annotate a public method with #[Route]:

use KonradMichalik\Typo3Routing\Attribute\Route;
use KonradMichalik\Typo3Routing\Routing\RouteControllerInterface;
use Psr\Http\Message\ResponseInterface;
use TYPO3\CMS\Core\Http\JsonResponse;

final readonly class CourseSearchController implements RouteControllerInterface
{
    #[Route(path: '/api/course-search/count', name: 'course_search_count')]
    public function count(): ResponseInterface
    {
        return new JsonResponse(['count' => 42]);
    }
}

That's it — GET /api/course-search/count now returns your JSON.

Everything else is opt-in on top of that. A route can take typed arguments, validate input, cache its response, and throttle clients — all declared with attributes, the controller stays plain:

use Symfony\Component\Routing\Requirement\Requirement;

#[Route(path: '/api/courses/{id}', name: 'course_show', requirements: ['id' => Requirement::DIGITS])]
#[Cache(lifetime: 3600, tags: ['tx_courses_domain_model_course'])]
#[RateLimit(limit: 60, interval: '1 minute')]
public function show(int $id, int $page = 1): ResponseInterface
{
    // $id  ← path placeholder, cast to int (404 if not digits)
    // $page ← ?page=… query param, defaults to 1
    return new JsonResponse(/* … */);
}

Protecting a route is just as declarative — require a logged-in frontend user (or a bearer token / BE user, OR-combined):

#[Route(path: '/api/account', name: 'account')]
#[Authenticate(FrontendUserAuthenticator::class)]
public function account(): ResponseInterface
{
    // Reached only when a frontend user is logged in — 401 otherwise.
    return new JsonResponse(/* … */);
}

See Usage for the full #[Route] reference and typed arguments.

📚 Documentation

🧑‍💻 Contributing

Please have a look at CONTRIBUTING.md.

⭐ License

This project is licensed under GNU General Public License 2.0 (or later).