Cms Frontend Laravel Package

Getting Started

Read this first: typo3/cms-frontend is not a Laravel package, and it is not an API package. It is a read-only subtree split of the TYPO3 Core monorepo containing typo3/sysext/frontend — the request handler, page rendering pipeline, TypoScript content objects, frontend user sessions, and page cache. There is no service provider, no facade, no config/frontend.php. If you composer require typo3/cms-frontend inside a Laravel app you will get a broken install: the package needs typo3/cms-core, the bootstrap in index.php, typo3conf/, typo3temp/, and a database full of pages/tt_content tables before a single line of it does anything.

So the only two realistic starting points are:

1. TYPO3 owns the request (classic or hybrid): you run a full TYPO3 instance and Laravel either lives behind a path prefix, or is not in the request path at all.
2. TYPO3 owns the content, Laravel owns the request (headless): Laravel fetches rendered output or JSON from a TYPO3 instance over HTTP.

Minimal steps for either:

# Do NOT install the split package standalone. Install a full distribution.
composer create-project typo3/cms-base-distribution typo3-site "^13.4"
cd typo3-site
php vendor/bin/typo3 setup          # TYPO3 12.4+, interactive, creates site config
php vendor/bin/typo3 server:start   # or point Nginx/Apache at public/

Pin the major/minor exactly — typo3/cms-frontend, typo3/cms-core, and every other typo3/cms-* package must be the same version. The split repos carry no independent release history.

Where to look first, in typo3/sysext/frontend/:

• Classes/Http/RequestHandler.php — the PSR-15 entry point for every frontend request (v12/v13). This is the seam you extend.
• Classes/Controller/TypoScriptFrontendController.php — the legacy god-object; in v13 much of its state moved to Classes/Page/PageInformation. Read it to understand page cache, config., and frontend user handling.
• Classes/ContentObject/ContentObjectRenderer.php — how tt_content rows become HTML (TEXT, IMAGE, FLUIDTEMPLATE, USER, …).
• Configuration/RequestMiddlewares.php — where frontend middlewares are declared; copy this pattern for your own.
• Docs at docs.typo3.org (Frontend chapter), issues at forge.typo3.org (project_id=27), reviews at review.typo3.org. Query Forge with curl -H "Accept: application/json" and the default curl user agent — browser-like UAs hit a bot check.

First use case: fetch one rendered page from Laravel and cache it.

// config/services.php
'typo3' => ['url' => env('TYPO3_URL', 'https://cms.example.test')],

// app/Services/Typo3Client.php
public function page(string $path): string
{
    return Cache::remember("typo3:page:{$path}", now()->addMinutes(10), fn () =>
        Http::baseUrl(config('typo3.url'))
            ->timeout(5)
            ->retry(2, 200)
            ->get($path)
            ->throw()
            ->body()
    );
}

Then {!! $client->page('/about-us') !!} behind an HTML sanitizer, or better, extract fragments rather than whole documents. If that already feels wrong, headless is not the right shape for your project — go straight to option 1.

Implementation Patterns

Route delegation (fastest, least invasive). Terminate at Nginx and split by prefix: / → TYPO3, /app → Laravel (or the reverse). If you must do it in PHP, use a middleware that hands off, not one that redirects — a 302 loses POST bodies and breaks SEO:

public function handle(Request $request, Closure $next)
{
    if (! $request->is('app/*')) {
        $response = Http::baseUrl(config('typo3.url'))
            ->withHeaders(['X-Forwarded-Host' => $request->getHost()])
            ->send($request->method(), $request->getRequestUri(), ['body' => $request->getContent()]);

        return response($response->body(), $response->status())
            ->withHeaders($response->headers());
    }

    return $next($request);
}

Do this only for low-traffic sites. It doubles latency and destroys TYPO3's page cache benefits.

Headless via a custom PSR-15 middleware (the real headless pattern). cms-frontend ships no JSON API. TYPO3 GmbH's EXT:headless exists, but the day-to-day approach is a small middleware that resolves a page and serializes content elements:

// Configuration/RequestMiddlewares.php in your site package
return ['frontend' => [
    'vendor/headless-json' => [
        'target' => \Vendor\SitePackage\Middleware\JsonApi::class,
        'after'  => ['typo3/cms-frontend/site', 'typo3/cms-frontend/page-resolver'],
        'before' => ['typo3/cms-frontend/page-argument-validator'],
    ],
]];

Inside, use PageRepository to fetch the page and its tt_content rows, then run each row through ContentObjectRenderer if you want HTML, or hand-map CType/pi_flexform to your own DTO. Return application/json. Every field you expose is a contract — version it (/api/v1/pages/{slug}) on the Laravel side, not inside TYPO3.

Laravel-side consumption. Wrap the client in a typed service returning DTOs, not arrays:

final readonly class PageDto
{
    public function __construct(
        public string $slug,
        public string $title,
        public array $blocks,
        public string $updatedAt,
    ) {}
}

Use Http::pool() for multi-page fetches, Cache::remember with a key that includes the SiteLanguage (/de/about-us), and an Http::macro or PendingRequest default of ->acceptJson()->timeout(3). Expose to your frontend with API Resources — Spatie's laravel-data fits well here.

Push-based sync instead of pull. When content changes, TYPO3 fires PSR-14 events (AfterPageContentGenerationEvent, cache-clear events). Register a listener that POSTs the page id to a Laravel webhook endpoint, then dispatch a queued job that re-fetches and warms your cache. typo3/cms-webhooks gives you this out of the box in v12+. Make the receiver idempotent — TYPO3 will retry on non-2xx.

URL generation belongs to TYPO3, not Laravel. With routeEnhancers in the site config, slugs are computed by PageRouter. Never concatenate /{slug} in Blade. Have the JSON endpoint return a _links.self and _links.canonical per node, or add a typolink. content object that emits the URL, then render it. Getting this wrong produces links that 404 the moment an editor renames a page.

Auth bridge. fe_users sessions are PHP sessions scoped to the TYPO3 cookie domain — there is no shared session with Laravel. Don't try to share PHPSESSID. Either (a) keep authenticated areas entirely in Laravel and use TYPO3 only for public content, or (b) issue a short-lived signed JWT from Laravel and validate it in a TYPO3 middleware that hydrates $GLOBALS['TSFE']->fe_user. Pattern (a) is dramatically cheaper; pick it unless product forces otherwise.

Assets. fileadmin/ is TYPO3's upload area. Expose it read-only via CDN or a signed Nginx alias rather than symlinking into public/ — a symlink into storage/ will be stale after deploys and the paths TYPO3 emits in tt_content bodies are absolute anyway. Set config.absRefPrefix / the site's base variant so URLs from the API are usable by Laravel.

Gotchas and Tips

• Composer conflicts are near-certain if you co-locate. TYPO3 13 pulls Symfony 7 and psr/http-message; Laravel 11 does too, so composer require typo3/cms-frontend inside a Laravel app sometimes resolves and then fails at runtime on duplicated TYPO3\ autoload roots or a typo3conf/ that doesn't exist. Keep two vendor/ directories, two deploys, or two containers. Never use Composer's replace trick to merge them — you will spend weeks on Class not found in the bootstrap.
• License. GPL-2.0. Running TYPO3 as a separate network service and consuming its output is unambiguously fine. Linking cms-frontend classes directly into a proprietary Laravel app is a legal conversation, not a technical one — get it settled before you write the bridge.
• The page cache is the whole point, and it will lie to you. Frontend output is cached in typo3temp/var/cache/ keyed by page, language, and frontend-user group. Symptoms: your API returns stale content after an edit; a "personalized" block leaks between users. Fixes in order of preference: (1) don't personalize server-side at all if you're consuming over HTTP — do it client-side in Laravel; (2) use cache tags and have your publish listener flush them; (3) ?no_cache=1 for debugging only, never in production code. php vendor/bin/typo3 cache:flush when in doubt.
• no_cache in TypoScript is a footgun. A single config.no_cache = 1 or a [request] condition depending on fe_user disables caching for the entire site and can take a healthy instance to seconds-per-request. Grep your TypoScript for it during reviews.
• CORS needs explicit work. TYPO3's frontend middleware stack does not send Access-Control-Allow-Origin for arbitrary origins. If your React app calls TYPO3 directly, add a PSR-15 middleware for preflight OPTIONS and the response header — and remember that cookie-authenticated cross-origin calls need credentials: 'include' plus an exact (non-wildcard) origin.
• Version drift between v12 and v13 breaks examples you'll find online. TypoScriptFrontendController is heavily reduced in v13; PageRepository moved from TYPO3\CMS\Frontend\Page to TYPO3\CMS\Core\Domain\Repository. Always check which LTS a snippet targets before pasting. The split package's own composer.json in the monorepo is the source of truth for what's supported, not blog posts.
• Debugging levers, in order: TYPO3_CONTEXT=Development (verbose errors, no cache); the Admin Panel extension (typo3/cms-adminpanel) for query/cache/TypoScript inspection; ?ADMCMD_prev=1 to preview hidden pages; ?no_cache=1; then the log at typo3temp/var/log/. If you're the Laravel side, log the TYPO3 URL and response status on every outbound call — you will otherwise debug a blank page for an hour.
• Don't patch sysext/frontend. It's core; your change vanishes on the next composer update. Extend via a site package: PSR-15 middlewares, a USER/custom content object, a PSR-14 event listener, or a PageRenderer hook for injecting assets. If you genuinely need a core change, it goes through Gerrit (review.typo3.org) — and core's own workflow rule applies: reproduce with a test first, then fix.
• typo3temp/ and permissions. Deployments that don't preserve typo3temp/var/cache/ write permissions produce "page is not available" with no other symptom. Create the directories in your deploy script with the correct owner, and don't rm -rf them on every release unless you also warm the cache (php vendor/bin/typo3 cache:warmup).
• The extension points worth memorizing: Configuration/RequestMiddlewares.php (every request), ContentObjectRenderer custom content objects (editor-selectable blocks), $GLOBALS['TYPO3_CONF_VARS']['SYS']['routing']['enhancers'] (clean URLs), and PSR-14 events like AfterPageContentGenerationEvent (publish hooks). Anything else you need is probably already a service in Configuration/Services.yaml — debug:container will list it.