Cms Kernel Laravel Package

Getting Started

Pin the exact version — this remains a low-adoption, zero-dependency package, and v0.4.0 is the release you should be evaluating, not dev-master.

composer require lin3s/cms-kernel:0.4.*

Where to look first:

1. README.md and any docs/ folder — for a base "kernel" package the docs are the contract; the code is mostly abstractions meant to be extended, not used directly.
2. composer.json — check require for the exact Symfony/Doctrine versions and note the v0.4.0 "less strict shared kernel dependency" change: the constraint on the shared Lin3s kernel was loosened, so Composer may now resolve a sibling package version this release was never tested against. Lock it down.
3. The frontend surface — v0.4.0 is largely an asset release (IE11-compatible styles, optimized login background, Parsley removed in favour of lin3s-front-foundation, react-dates fix). Look for the package's CSS/JS/assets directory and its package.json before you assume this is a pure PHP library. It ships a login page and an admin UI you will inherit.
4. The service definitions (Resources/config/*.yml or services.xml) — this is where the kernel wires repositories, factories, event listeners, and (new in 0.4.0) Tactician command handlers. Reading this is faster than reading every class.
5. The base model classes (often under Model/, Domain/, or Entity/) — these are the classes you subclass.

Register the bundle(s) in your kernel/bundles.php, then compile once and inspect what you actually got:

bin/console debug:container --tag=tactician.handler
bin/console debug:container --tag=<vendor tag>

First use case: stand up a single page type. Create your own entity extending the package's base page/model, map it with Doctrine using the same mapping driver the package uses, implement the required abstract methods, and render it through your app's controller — then save it through the command bus if you've opted into that. If persist → fetch via the package repository → render works end-to-end, the rest of the surface area (pages, blocks, menus) is that same extension point repeated.

Implementation Patterns

Extend, don't instantiate. The kernel is a base layer. One entity per content type, each inheriting the kernel's base class and its lifecycle behavior. Keep subclasses thin — only the fields and validation your content type needs.

Write through commands, read through repositories. v0.4.0 adds Tactician command bus support. The idiomatic shape is: controller validates input → builds a command → dispatches on the bus → handler loads the entity via the package repository, mutates it, persists. Keep reads out of the bus; keep the kernel's repository as the read boundary. If your app is on Symfony Messenger, do not mix — either run Tactician alongside it or write a thin adapter in your own container so the kernel's handlers stay untouched.

Composition over inheritance for page content. Pages hold an ordered collection of blocks; blocks are reusable and reference-shared rather than field-duplicated. One block type renders identically wherever it is placed — that is the whole value proposition.

Repository as the read boundary. Inject the package repository (or your subclass) into controllers and services rather than querying with the EntityManager. This preserves locale/status/published filters the kernel applies and stops hand-written DQL bypassing them.

Let the Slug component own URLs. v0.4.0 improves slug behaviour. Generate slugs on create, persist them as data, and treat them as stable identifiers — do not regenerate on every save, or published URLs will churn. If you need per-locale slugs, follow whatever the package's slug/translation pairing does rather than adding a parallel scheme.

Template inheritance mirrors entity inheritance. One base Twig layout per content family, each concrete page type overriding blocks. Keep the kernel's block template naming conventions so new block types are drop-in.

Wire content types as services/tags. If the package exposes a registry or tagged-service mechanism for page/block types, register each type there instead of a switch in a controller.

Consume the shipped frontend, don't fork it. The admin/login styling and JS (foundation, date picker) ship with the package. Publish/copy the built assets into your pipeline. Do not point your build at their source package.json unless you enjoy resurrecting a 2017 Node toolchain — use the dist files.

Integrate at the edges. Admin forms in your form types, routing in your app, persistence and content modeling in the kernel. Decorate services in your container rather than editing vendor code.

Gotchas and Tips

• Maintenance risk is still the headline. v0.4.0 is a frontend/asset release plus one integration (Tactician); it does not modernize the underlying Symfony/PHP baseline. Treat the package as vendored code you may have to own. Pin exact versions for both the package and the shared kernel.
• The loosened kernel constraint is a real hazard. A permissive require means composer update can silently pull a shared-kernel version the CMS was never tested against. Commit composer.lock, and add a constraint in your root composer.json if the package's own constraint is too loose.
• Tactician is pre-Messenger. It has no first-class Symfony 4.3+/5+/6+ integration. Expect to register the bus yourself. A command dispatched with no registered handler fails at runtime, not compile time — verify with debug:container --tag=tactician.handler before debugging your business logic.
• Parsley is gone. If your forms relied on Parsley's client-side validation coming in with the bundle, that dependency was removed in favour of lin3s-front-foundation. Your validation may now be silently absent — re-test forms, especially anything with server-side gaps.
• Slug behaviour changed. Improved slugging can alter output for edge cases (unicode, punctuation, collisions). Before upgrading on a live site, diff the slugs the component generates for your existing titles against what's stored; add redirects or a backfill if they diverge.
• IE11-compatible CSS implies an old stack. Expect autoprefixed/legacy CSS, older JS bundling, and react-dates pinned to an old version. Budget for replacing the admin frontend with your own UI if you need a modern browser story — the PHP side can stay.
• PHP/Symfony version drift. Expect PHP 7.x idioms and older Symfony APIs (AppKernel, YAML service configs, getName() bundles). On PHP 8+ you'll hit dynamic-property and return-type deprecations before real bugs. react-dates and foundation pins mean the JS side drifts too.
• Doctrine mapping conflicts. If the package ships mapping metadata for base classes and you declare your own on subclasses, the inheritance strategy (single-table vs. joined vs. class-table) must match exactly. Mismatches surface as "column already defined" or silently missing columns.
• Container caching masks config errors. After changing bundle registration, service tags, or command handler registration, run bin/console cache:clear before debugging — stale compiled containers produce "service not found" errors unrelated to your code.
• Repository filters are easy to bypass. Custom DQL skipping the kernel's query builder leaks unpublished or wrong-locale content. Extend the repository's query methods instead of writing new ones.
• Debugging extension points: debug:container --tag=..., debug:event-dispatcher, and (for 0.4.0) debug:container --tag=tactician.handler. Most "the package isn't doing anything" reports are missing bundle registration or a missing tag.
• Event subscribers are the safe customization seam. Hook persist/remove/render events rather than overriding lifecycle methods — it survives upgrades and keeps entities portable.
• Templates fail silently into empty output. A blank block usually means an unregistered Twig path or a discriminator value that doesn't match the registered type string exactly (case-sensitive in most registries).
• Write characterization tests before extending — and before upgrading. With no community and no changelog guarantees, a small suite asserting actual persist/fetch/slug/render behaviour is your only upgrade safety net. Add slug fixtures and a command-dispatch smoke test with 0.4.0.
• Know when to stop. If the kernel fights your Symfony version, the abstractions are thin enough that reimplementing the page/block model directly in your app — and writing your own admin UI — is often cheaper than sustaining a 2017 dependency with a 2017 build pipeline.