Cms Laravel Package

Getting Started

TallCMS is a Filament plugin, not a standalone app (in this package). The minimum viable install is four steps and roughly ten minutes:

composer require tallcms/cms
php artisan tallcms:install        # publishes migrations, config, runs migrate
npm install && npm run build       # host app must produce a Vite manifest

Then register the plugin in your panel provider and make your User model role-aware:

use TallCms\Cms\Filament\TallCmsPlugin;

public function panel(Panel $panel): Panel
{
    return $panel
        ->plugin(TallCmsPlugin::make());
}

class User extends Authenticatable
{
    use HasFactory, HasRoles, Notifiable; // Spatie\Permission\Traits\HasRoles
}

Where to look first, in order:

1. docs/gs-installation.md in the monorepo (tallcms/tallcms), not this repo — this package is a read-only subtree split and ships no docs directory.
2. TallCmsPlugin itself. It is the real API surface: what registers, what can be switched off, and which resources land in your navigation.
3. config/tallcms.php — plugin_mode.user_model, component toggles, and (in 4.x) localization settings all live here.
4. docs/dev-blocks.md before you touch the editor. Blocks are where 90% of day-to-day customization happens.

First use case: log into /admin, create a Page, drop a few built-in blocks (there are 16), attach a featured image from the media library, publish. Then hit the frontend route and confirm your theme templates resolve. If that loop works, the rest of the package is variations on it.

Implementation Patterns

Register selectively, not wholesale. You almost never want all of TallCMS in an existing panel — a SaaS app with its own Order and Customer resources doesn't need Posts or Comments in the sidebar. Use the without*() fluent methods on the plugin to trim, and keep the CMS behind a separate panel if your audience is different:

TallCmsPlugin::make()
    ->withoutComments()
    ->withoutForms()
    ->withoutPosts();

Multi-panel is the intended integration path. The 2.0 rewrite moved every internal URL onto Page::getUrl() specifically so resources resolve correctly when mounted at /admin, /cms, or a tenant-scoped path. If you build custom actions or notifications that link to CMS records, use the model's getUrl() — hardcoded /admin/pages/... will break the moment someone changes the panel path.

Block authoring is the main extension point. Use the generator rather than hand-rolling:

php artisan make:tallcms-block hero-banner

That scaffolds a block class plus its Blade view. Follow the daisyUI semantic class convention the 1.1.0 release standardized on (bg-base-200, text-base-content, btn btn-primary) — it means your block automatically respects the active theme preset and dark mode instead of hardcoding colors that break on theme switch. Keep block data serializable and flat; the editor round-trips it as structured JSON and deeply nested arrays are painful to diff in the revision viewer.

Treat revisions and preview as infrastructure you get for free. The publish workflow is Draft → Pending Review → Scheduled → Published, with revision diffs and preview tokens for unpublished content. For editorial teams, wire your notification/approval emails off the content events rather than polling status columns. If you're pinning below 4.6.4, do not rely on revision pruning — see the gotcha below.

Localization is opt-in but pervasive. Pages, Posts, and Categories use HasTranslatableContent (Spatie Translatable). If you enable it, expect locale-prefixed routes (/en/about, /zh-CN/about) and use the package helpers instead of Laravel's:

tallcms_localized_url($page->slug);
tallcms_localized_route('page.show', $page);

…and include the <x-tallcms-hreflang /> component in your layout head. Register SetLocaleMiddleware and mind its position relative to auth/bindings — it needs to run before route model binding resolves a localized slug.

Permissions run through Filament Shield/Spatie. Don't invent your own gating. The site_owner role (added 4.0.14, 47 permissions) is the right default for anyone who owns content end-to-end; the older author role is narrow (write posts, submit for review) and is a poor fit for a "manages their own site" workflow. Seed roles via Shield's seeder and let policy checks flow through SitePolicy / resource policies.

Frontend integration: the package gives you models, routes, and rendered block output; your Blade templates control the chrome. Override theme/layout views in your app rather than editing vendor files, and render menus and forms through the package's components so you don't reimplement drag-and-drop ordering or spam handling.

Gotchas and Tips

You are reading a build artifact. tallcms/cms is a CI-generated subtree split of the tallcms/tallcms monorepo. Issues, PRs, and the entire docs/ tree live upstream. Don't patch vendor/tallcms/cms — the fix has to land in the monorepo or it will be overwritten on the next release.

Run php artisan tallcms:diagnose after every upgrade. The 4.8.0 i18n pass introduced this for a specific, nasty failure mode: previously-published config files shadow package defaults, so upgraded installs silently keep English-only labels and stale setting keys while the code expects translations. If admin labels look wrong or new settings don't appear in the UI, this command is your first move, not your last.

The Vite manifest is a hard dependency of the admin. Node 20+ is required and your app must build. A fresh clone with composer install but no npm run build yields a broken-looking admin panel that reads like a package bug. Same for CI pipelines that skip the asset step.

Version pinning matters more than usual here. Two concrete examples: 4.6.4 fixed revision pruning that was deleting the newest revisions and keeping the oldest (orderByDesc on the relation only got a secondary sort clause — the fix was reorder()); 4.3.2 fixed a high-severity bug where embed-code saves could write to the installation-wide global table even when the UI implied a specific site. Pin ^4.6.4 at minimum, and read the changelog before jumping majors.

The code-injection API changed shape in 4.3.2. The standalone /admin/code-injection page is gone; head/body-start/body-end embed zones now live as an "Embed Code" tab on the Site edit page, gated by SitePolicy (the Manage:CodeInjection permission is orphaned on upgraded installs — harmless, deletable). TallCmsPlugin::make()->withoutCodeInjection() still exists but is a no-op shim. If your deployment relied on that method to disable the page, it no longer does anything and you need to control access via the Site policy instead.

Per-site settings silently fall back to global. The SiteSettingsService::setForSite() / global-fallback pattern is used across embed code, languages (redirect_root_to_locale), and theme options. On a single-site install you'll never notice; the moment someone adds multisite, "I set it and it didn't take" is usually an ambient-session site resolution problem rather than a cache problem. Pass explicit site_id in any custom code that writes settings — the 4.3.2 and 4.9.1 releases were both fixes for exactly this class of bug.

Multisite is commercial. The per-site override plumbing is in the open-source package, but the multisite plugin that gives each site its own domain and theme is a paid add-on. Plan for that in budget if "run five client sites from one install" is the actual requirement — and note the README's standalone-edition link is where themes and the plugin marketplace live; those subsystems are gated by a mode-detection check in plugin mode and won't behave the way standalone docs describe.

Database and PHP constraints are narrower than "Laravel 11–13" suggests. MySQL 8 / MariaDB 10.3 / SQLite are the named backends — PostgreSQL isn't listed, which is a blocker for plenty of shops. Laravel 13 needs PHP 8.3+. And despite the README's "Laravel 11, 12, or 13," the 4.7.0 changelog records Laravel 11 being dropped from the CI matrix and supported range — treat 11 as untested on current releases even though the badge says otherwise.

Adopt with eyes open on maturity. 5 stars, 0 dependents, a single-maintainer-adjacent project with a commercial upsell. The engineering signals are genuinely good — regression tests cited per fix, security releases for Guzzle advisories, a real changelog with contributor credit — but you are an early adopter. Budget for reading source when docs lag, keep the package behind a panel you can disable, and avoid making its models the backbone of your domain data. Let it own pages, posts, and media; keep your business entities in your own tables with soft references.