Cms Laravel Package

Getting Started

The package lives on a private Forgejo/Gitea instance (git.ft.ro), so the very first step is access, not code. Since it's not on Packagist and has zero public dependents, treat it as an internal or early-stage package until proven otherwise.

1. Confirm access and requirements. You need SSH or token access to git.ft.ro/falcon/falcon-cms. Because it's "CMS on top of Nova," a valid Nova license and a compatible Laravel/Nova version matrix are hard prerequisites — read composer.json (Laravel, Nova, PHP constraints) before anything else. Add the VCS repository in composer.json:

   "repositories": [{ "type": "vcs", "url": "[email protected]:falcon/falcon-cms.git" }],
   "require": { "falcon/cms": "dev-main" }
   

   Pin a tag or commit hash — no Packagist means no semver safety net.

2. Look here first, in order: composer.json → README → config/falcon-cms.php (published) → the service provider's register/boot (what it binds, what it publishes) → migrations (the real domain model) → src/Nova (the resources are the CMS surface).

3. Install and publish:

   composer require falcon/cms
   php artisan vendor:publish --provider="Falcon\Cms\CmsServiceProvider"
   php artisan migrate
   

   Verify which publish tags exist (config, migrations, assets, views) rather than assuming.

4. First use case: create one content type / page in the Nova UI, save it, then wire a single front-end route that resolves and renders it. That one end-to-end loop tells you more about the package's shape than any doc — you'll immediately see whether rendering is route-driven, model-driven, or Blade-component-driven, and whether it expects a catch-all route.

Implementation Patterns

Treat Nova resources as the content schema. In a Nova-based CMS, day-to-day work is usually: define a resource (fields = content fields), register it so it appears in the sidebar, and let editors manage content through Nova. Your job shifts from "build CRUD" to "shape fields and relationships." If the package exposes a registry/contract for page types or block types, register custom types there rather than editing vendor code.

Rendering: pick one integration boundary and stick to it. The common patterns are (a) a catch-all route registered by the package, (b) you define Route::get('/{slug}', ...) and hand off to a resolver, or (c) Blade components the package ships. Whichever it is, wrap it in your own thin controller/ViewModel so view logic, caching, and SEO concerns live in your app, not in the package. That keeps upgrades survivable.

Menus/nav and media are usually separate Nova-managed resources with their own helpers. Pulling a menu into a layout typically means a facade/helper call — cache that result per request or per menu key rather than hitting it in every partial.

Localization and drafts/publishing are the two features most likely to be half-implemented. If the package supports them, model the workflow explicitly (status column, locale column) and gate where('published', true) in your resolver. Don't assume the package's default scope does it for you.

Multi-site or multi-tenant (if present) will usually key off a domain or a site ID in config. Set that per-request in middleware so the CMS resolves the right content tree.

Integration hygiene: keep Falcon registration in a dedicated CmsServiceProvider in your app, and put any custom resources, blocks, or template overrides in app/, referenced through config — not in vendor/.

Gotchas and Tips

• Nova version coupling is the #1 risk. Nova has breaking changes between majors; verify the exact supported Nova version in composer.json and test upgrades in isolation. With no public dependents, you are the QA.
• Private repo in CI/CD: your build pipeline needs SSH keys or a Composer auth token for git.ft.ro. Use COMPOSER_AUTH / auth.json in the deploy environment, and prefer a tagged release over dev-main so deploys are reproducible.
• No Packagist = no automated security advisories. Run composer audit and track the repo's commits yourself.
• Migrations and config drift: published config/migrations are now yours. If the package updates, diff its stub against your published copies before merging — silently changed defaults are a classic cause of "it worked yesterday."
• Catch-all route conflicts will bite you if your app also defines /{any} or localized routes. Inspect php artisan route:list after install and check route order/priority.
• Cache invalidation: if content is cached (Nova + CMS almost always implies caching), hook the package's saved/deleted events — or Nova's NovaResourceSaved — to bust cache keys. Test the "edit page, refresh front-end" loop early; a stale cache here is the most common support ticket.
• Debugging: start with php artisan route:list, then php artisan nova:resource, then dump the service provider's boot. If rendering silently fails, check whether the package expects a view namespace (falcon-cms::) you haven't published.
• Extension points: look for interfaces/contracts in src/ (resolvers, block types, page templates) — these are the intended seams. If everything is final with no contracts, plan for forks and keep your own code out of vendor/ so you can rebase.
• Given the score and empty signals, budget time for reading source rather than docs, and isolate the integration behind an adapter class so you can swap it out if the package turns out to be abandoned.