Filament Grapesjs V3 Laravel Package

Getting Started

• Install with composer require <vendor>/<package> and confirm you are on ^1.1.1 — this is the first release with explicit Laravel 12 support, so pin at least this version if you are on Laravel 12.
• Publish any shipped config (php artisan vendor:publish --tag=<package>-config) before touching the builder. Most builder-driven packages read their defaults from config at resolve time, so an unpublished config file is the usual cause of "it works in tinker but not in the app."
• Read the README's builder section first. v1.1.1 rewrote it to document builder use from other plugins/configurations, which is the fastest path to understanding how the pieces compose.
• First use case: instantiate the builder once inside a service provider (or a small dedicated class) and resolve it from the container rather than new-ing it inline. Then add a single plugin/configuration through the builder and verify it renders/behaves before layering more on.
• Verify the wiring with a trivial feature test — build the object, assert the expected configuration/plugin set — before integrating it into real controllers or Blade views.

Implementation Patterns

• Builder-in-a-provider: construct and configure the builder in a register()/boot() method, bind it as a singleton, and inject it where needed. This keeps plugin/config registration in one place and makes the order of registration explicit.
• Composable plugin registration: with v1.1.1's support for other plugins and configurations, prefer registering each plugin/config as its own small method (registerFoo(), registerBar()) called from a single configure() entry point. This scales cleanly as you add third-party plugins.
• Config-driven setups: drive the builder from a config array (plugin list, per-plugin options) so environments can differ without code changes. Keep the config flat and validated — deep nesting makes partial overrides painful.
• Extension over modification: if you need behaviour the builder does not expose, extend the builder or register a custom plugin rather than editing vendor code. v1.1.1's cross-plugin support is aimed squarely at this.
• Multi-context usage: when the same package instance serves several contexts (multiple plugins, multiple configurations), build one configured instance per context and resolve by name/alias instead of mutating a shared singleton.
• Testing: assert on the builder's resolved output (plugin list, rendered config) rather than internal state. This survives minor internal refactors between patch releases.
• Upgrade path: treat v1.1.1 as additive — it advertises new capabilities and Laravel 12 support, not removals. Still, run your test suite against Laravel 12 in CI before bumping in production.

Gotchas and Tips

• Config caching: after changing the package config, run php artisan config:clear. Cached config is the number one source of "my new plugin/config isn't picked up."
• Singleton mutation: if the builder is bound as a singleton, mutating it in one request/context leaks into others (especially in Octane or long-running workers). Prefer factory-style resolution or reset state between uses.
• Registration order matters: plugins/configurations registered via the builder can depend on earlier ones. Keep a deterministic order in your provider and document it; don't rely on config array ordering if the array can be merged from multiple sources.
• Laravel 12: the release adds support but the surrounding ecosystem (other packages, test tooling) may lag. Check composer why-not laravel/framework 12.* when the upgrade fails rather than assuming this package is the blocker.
• Version pinning: if you consume the new builder capabilities, require ^1.1.1. Earlier versions will silently ignore or reject the cross-plugin configuration paths.
• Debugging: dump the builder's resolved configuration rather than inspecting intermediate state — most issues are a plugin never being registered, not a plugin misbehaving.
• Extension points: the builder itself is the intended extension surface. Before writing a workaround, check whether the README's new section covers your case (e.g. another plugin's config), since that scenario is exactly what v1.1.1 added.
• Docs drift: the README changed materially in this release. If you copied snippets from an older tutorial, re-check them against the current README before debugging phantom issues.