Platform Laravel Package

Getting Started

0.4.0 is a milestone release, not a patch. It adds three features that change how you'll integrate the package (multi-tenancy, Tiptap editor type, menu-driven user dropdown) plus a stack of dependency majors (Symfony 8, jQuery 4, Webpack Encore 7, Babel 8, Tiptap 3, PHPUnit 13). Budget an upgrade session rather than a composer update.

First steps:

1. Confirm the runtime. SolidWorx/platform is a Symfony bundle, not a Laravel package. If you're coming from Laravel, map your instincts: config/packages/*.yaml instead of config/*.php, service autowiring instead of the container's facades, Doctrine entities instead of Eloquent, Twig instead of Blade. The bundle gives you a user/auth foundation, an admin UI, and a form layer — roughly the role Breeze/Filament play in Laravel.
2. Register the bundle in config/bundles.php and import its routing, then run the Doctrine migrations for the user tables.
3. Look first at the UI bundle and the user entity contract. Everything you extend hangs off these two: your User class implements the bundle's user interface, and your templates override the UI bundle's Twig namespace.
4. First use case: stand up login + registration + a Tabler-layout admin page. That exercises the auth stack, the new layouts, and the newly-default form loading overlay in one pass.
5. If you're greenfield, decide on tenancy now. Retrofitting TenantInterface-style isolation onto an existing schema is much more expensive than adopting it at the start.

Implementation Patterns

Extend the user entity, don't fight it. Subclass the bundle's base user, add your domain fields, and keep the bundle's interfaces intact — the registration and access-control listeners type-hint against them.

Registration hardening is now free — and configurable. Disposable-domain blocking ships on by default at registration. In practice you'll want to subtract from the blocklist for internal/staging domains (e.g. @example.test, your own QA domains) rather than disabling the check wholesale. Wrap it in a config flag per environment so dev and test suites aren't fighting the blocklist.

Rich text with TextEditorType. Use it as a drop-in form type wherever you'd otherwise reach for a TextareaType, then be deliberate about persistence: Tiptap emits HTML or JSON depending on config. Pick HTML if you need to render server-side with minimal ceremony, JSON if you want structure for downstream processing. Either way, sanitize on output — an editor widget is not a sanitizer.

Multi-tenancy: resolve once, early, and thread it through. The workable pattern is a listener or middleware that resolves the tenant (subdomain, header, or authenticated user's tenant) before controllers run, storing it in a request-scoped context service. Repositories then filter by the context service rather than re-deriving the tenant in each query. Treat any code path that touches the DB outside a request — console commands, queue workers, scheduled jobs — as needing an explicit tenant binding, because there's no request to resolve from.

Customize the user dropdown via KnpMenu, not template surgery. The dropdown is now driven by a user_menu menu, so add or reorder items by decorating that menu in a MenuBuilder event subscriber. This is the intended extension point and keeps you off the template-override treadmill.

Override Tabler layouts by template inheritance. Register your Twig path ahead of the bundle's, extend the base layout, and override individual blocks. Don't copy the whole layout file — you'll be re-diffing it every release.

Integration tip: keep your app's own controllers thin and let bundle-provided base controllers handle the plumbing (forms, flash messages, redirects). Overriding a base controller method is safer than cloning the action.

Gotchas and Tips

• Symfony 8+ is the new floor. If your app is on 6.x or 7.x, resolve that constraint first — it may block the upgrade entirely, or force a framework major of its own. Read the composer.json constraints rather than assuming.
• The asset pipeline moved under you. jQuery 3→4, Webpack Encore 6→7, ESLint Webpack Plugin 5→6, and Babel 7→8 all landed. jQuery 4 drops APIs (notably older .bind()/.delegate() shims), Encore 7 changes config contracts, and Babel 8 changes preset behavior. Any custom JS in your UI bundle overrides is the most likely thing to break, silently, in the browser. Rebuild and click through every form.
• Tiptap 2→3. If you'd already wired a Tiptap editor by hand before TextEditorType existed, migrate to the shipped type rather than maintaining your own — but re-test extensions, since the v3 extension API changed.
• The form loading overlay is now on by default. This is a visual/behavioral change across every form. Forms that submit via Turbolinks-style partials, or that rely on custom submit handlers, can look hung. Know where the global toggle lives so you can flip it off per form or app-wide.
• The user dropdown switching to user_menu is a quiet breaking change for anyone who overrode the dropdown template. If your custom links vanished after upgrading, this is why.
• Multi-tenancy is the highest-risk feature to adopt lazily. Audit for missing tenant scopes: raw query builder calls, find() by primary key, cache keys, queued job payloads, and file storage paths. A missing scope is a data-leak bug, not a display bug. Write a test that asserts tenant A cannot read tenant B's records through every repository.
• Debugging tip: when access control denies unexpectedly, check tenant resolution and role evaluation separately — a null tenant context often surfaces as a generic 403 that looks like a role problem.
• Dev-dependency churn is noise, but the PHPStan baseline being emptied is a signal. The maintainers now hold a zero-error static analysis line, so a PHPStan bump on your side is more likely to surface real findings in code that calls the bundle. Take the upgrade.
• The monolog dev bump to ^3.12 and phpunit to ^13.3 can conflict with your app's own dev constraints; sort dev deps in a separate commit from the feature upgrade so you can revert cleanly.