Core Laravel Package

Getting Started

First, the framing correction: contao-thememanager/core is not a Laravel package and has no Laravel integration surface. It is a Contao CMS bundle (Symfony-based) that provides a CSS framework, an SCSS compiler, and backend theme configuration. You cannot composer require it into a Laravel app and get anything useful. The only reason to read this assessment as a Laravel developer is if you are inheriting or quoting on a Contao site, or if you want to borrow its design-token/compiler architecture for your own build pipeline.

Minimal install (inside a Contao 4.13 or ^5.3 project):

composer require contao-thememanager/core
# then run pending schema updates — mandatory, the bundle ships Doctrine migrations
bin/console contao:migrate
bin/console cache:clear

Via Contao Manager, the equivalent is searching "Contao ThemeManager Core" and running the pending schema updates afterwards. Requirements per README: Contao 4.13 or ^5.3, PHP ^8.1 (see the version caveat in Gotchas — 2.4.0's release notes mention ^PHP 8.3).

Where to look first:

1. https://docs.contao-thememanager.com — the only documentation, German, and explicitly WIP. Treat it as a hint, not a spec.
2. The backend ThemeManager / theme configuration module — this is where SCSS variables are edited (backed by oveleon/contao-config-driver-bundle).
3. The three packages that actually do the work: contao-config-driver-bundle (variable storage), contao-theme-compiler-bundle (scssphp-based compilation and CSS versioning), contao-component-style-manager (per-element style options).
4. The bundle's own templates — several core Contao templates (form-wrapper.html5, block_searchable, block_unsearchable) are overridden here, so they are your first debugging stop for anything form- or navigation-related.

First use case worth validating: take a working Contao install with a page layout, change a handful of SCSS variables (primary color, container width, a breakpoint), trigger a compile, and confirm (a) the generated CSS filename/version changed, (b) the frontend picked it up without a manual cache clear, and (c) a second compile with no changes is a no-op. That single loop exercises the config driver, the compiler, CSS versioning, and filesystem write permissions — the four things that break in every deployment.

Implementation Patterns

Treat backend configuration as state that needs to travel with the code. SCSS variables and StyleManager options live in the database, not in your repo. The practical pattern is: configure in a dev environment, then export the configuration rows (or reproduce them via a migration/fixture) so staging and production aren't hand-tuned snowflakes. Without this you will get "works locally, wrong colors in prod" on every deploy.

Never edit the framework CSS. Use the custom SCSS hook. The bundle advertises "custom scss-file integration" for whole-site customization. Put your additions there so they compile after the framework, and re-declare custom properties rather than overriding selectors:

// custom layer — compiles after the framework
:root {
    --ctm-color-primary: #0b5fff;
    --ctm-container-max-width: 1320px;
}

Consume those same custom properties in your own templates (color: var(--ctm-color-primary)) instead of hardcoding, so a variable change in the backend ripples through your custom components too.

Prefer the bundled content elements over raw HTML elements. The package ships wrapper, text, image, icon, and list components plus a flexbox grid. Using them means you inherit grid placement, spacing tokens, and bottom-spacing handling (*_full templates) for free. Hand-rolled <div> markup escapes all of it and is the most common way CTM sites end up with inconsistent rhythm.

Use StyleManager for author-facing variation, not for one-offs. Configure the allowed style options per element type in the backend, then editors pick from a dropdown and the framework emits the corresponding classes. This is the right layer for "button variants", "backgrounds", "spacing presets". Anything you would otherwise describe in a support ticket goes here; anything only one page needs goes in custom SCSS.

Override templates the Contao way. Copy the vendor template into templates/ and modify the copy. Do not patch inside vendor/. Because this bundle ships its own versions of core templates, an override in your project templates/ directory is also your escape hatch if a shipped override conflicts with a Contao patch release.

Compile in the build step, not on production requests. The scssphp compiler writes CSS files to the filesystem with versioned names. Run compilation during deploy/CI (find the command with bin/console list | grep -i theme; it comes from contao-theme-compiler-bundle) so production never needs write access mid-request and so cache busting is deterministic across app servers.

Bring JS-dependent features in as separate extensions. Slider (Tiny Slider) and Recommendation are separate packages (ctm-tiny-slider, ctm-recommendation), not part of core. Budget for them explicitly rather than assuming "the theme manager does sliders".

Gotchas and Tips

v1 → v2 is not a supported upgrade. The README says so plainly. If you inherit a v1 site, quote a rebuild of the theme layer, not a migration.

Version-pin aggressively; the release history is bumpy. Concretely: 2.4.0 regressed background-image generation, fixed in 2.4.1 — never pin 2.4.0. 2.4.4 fixed Doctrine DBAL 4 type errors in migrations, so if you're on DBAL 4, floor at 2.4.4. With 6 stars, 0 dependents, and a single sponsor-funded maintainer, read every release note and pin exact versions.

Shipped template overrides mean Contao core updates are a compatibility event. Releases 2.1.2 and 2.1.3 exist specifically to re-sync form-wrapper.html5 with Contao 5.3.10/5.3.11 (double form submission, script evaluation in AJAX forms). Pattern to adopt: after every contao/core-bundle bump, manually test form submission, AJAX forms, searchable/unsearchable navigation, and news/event detail pages. Pin core to a patch range you've tested.

Breakpoints are global and semantic. The 1264px l breakpoint was deliberately changed so "medium" renders correctly inside a 1200px container. If you change container width or breakpoints in the backend, every hand-written media query in your custom SCSS is now suspect. Audit them together, not separately.

"Styles didn't change" has a short triage list: (1) did the compile actually run — check for an exception in the Contao log, scssphp errors carry file and line; (2) did the CSS version/hash change — if not, the compiler saw no input change, so your config write didn't land; (3) bin/console cache:clear; (4) browser cache on the versioned filename. Work that list in order; it resolves almost everything.

Generated assets are deployment state, not just code. If production filesystems are read-only, compile in the build and ship the generated CSS as an artifact — and check that .gitignore/rsync excludes aren't silently dropping it. Also keep the web server's write permissions consistent between the compile step and runtime.

Generator classes are @internal as of 2.4.0. Do not build integrations against them. Legitimate extension points are: custom SCSS, project templates, StyleManager configuration, and the backend config driver. Everything else is fair game to change under you.

PHP constraint ambiguity. README says ^8.1; 2.4.0's notes mention ^PHP 8.3. Resolve this with composer why-not contao-thememanager/core and by reading the actual composer.json constraint before planning a runtime upgrade — don't trust either document alone.

AGPL-3.0 is a real consideration, unlike most Composer packages. Client sites are fine. Distributing a modified fork, or offering it as a hosted service, triggers source-availability obligations. Get this signed off before you fork the CSS framework for reuse.

Expect to read source. German-only, WIP documentation plus a small project means the templates and SCSS in vendor/contao-thememanager/core are the authoritative reference. Budget discovery time accordingly, and keep a local copy of the compiled output so you can diff what the framework actually emits.