Ui Designer Laravel Package

Getting Started

This is the first public release (v0.1.0), so treat it as alpha: the API surface is still settling and 0.x semver means minor bumps may include breaking changes. Pin the exact version in composer.json ("symfinity/ui-designer": "0.1.0") rather than using a caret constraint.

Minimal setup:

composer require symfinity/ui-designer:0.1.0
php artisan vendor:publish --provider="Symfinity\UiDesigner\UiDesignerServiceProvider"
php artisan migrate

Where to look first, in order:

1. CHANGELOG.md in the repo — it is the only release artifact published for v0.1.0, so it is the authoritative record of what actually shipped.
2. The published config/ui-designer.php — this is where routes, storage, middleware, and rendering drivers are toggled. Read it end-to-end before writing code; it is the fastest map of the package's capabilities.
3. src/UiDesignerServiceProvider.php — confirms what is registered (routes, Blade namespace, Livewire components, migrations, publish tags). If a feature seems missing, check here before assuming it does not exist.
4. Published migrations — tells you the persistence model (single JSON schema column vs. normalised rows), which drives most downstream decisions.

First use case: stand up the designer in a local environment, save one schema, and render it back out on a plain Blade page. Do this on a throwaway route before wiring it into a real feature — it validates the publish/migrate/render path without committing to a data model.

Implementation Patterns

Schema-as-data. The core pattern for this class of package is storing a JSON document describing the UI, then rendering it through a package component. Keep the schema in a json column and version it (a schema_version integer alongside) so you can migrate documents later without guessing their shape. Never let application code read the raw JSON directly — wrap it in a small value object or cast so the schema contract lives in one place.

Wrap the renderer, don't inline it. Put the package's render call behind your own Blade component or a view composer. When 0.x breaking changes land, you patch one file instead of every view.

<x-render-ui :schema="$page->ui_schema" />

Publish-then-edit. Copy config and any views/assets into your app and edit the copies. Never modify vendor/. Re-publish deliberately on upgrade and diff against the old copy — this is how you surface new config keys.

Gate the designer routes. The visual designer is an authoring surface, usually far more sensitive than the public render path. In the published config, set the route middleware to ['web', 'auth'] plus an authorization gate, and register the designer routes only outside production (or behind a permission) unless end users are genuinely meant to author their own layouts.

Testing. Build a small fixture set of schema documents (empty, minimal, deeply nested, one with unknown node types) and snapshot the rendered HTML. Schema renderers fail badly on malformed input, so also test the failure path — a schema referencing an unregistered component should degrade gracefully, not 500 the page.

Integration tip. If the designer writes to your own Eloquent models, do the persistence in your app via an event/listener rather than letting the package own the write. That keeps the package on the "authoring UI" side of the boundary.

Gotchas and Tips

• 0.x means breaking changes are legal in minor releases. There is no upgrade path documented yet for v0.1.0 because there is no prior version. Lock the version, read the changelog before every bump, and keep the wrapper component described above.
• Config and view caching. After publishing or editing config, run php artisan config:clear && php artisan view:clear. A stale cached config is the single most common cause of "the package ignores my settings" during local setup.
• Publish tags. vendor:publish without --tag may push assets, config, views, and migrations at once, and can silently overwrite files you have edited. Run php artisan vendor:publish --list-style discovery (or check the service provider) to find the exact tags, then publish tag by tag.
• Migrations. If the package ships migrations and you also need your own columns on its table, add a separate migration after the published one rather than editing it — editing breaks idempotency on fresh installs.
• Asset pipeline. Visual designers typically ship JS/CSS. If assets are published rather than bundled through Vite, check whether they need a vendor:publish --force after upgrade; stale published assets produce confusing runtime errors that look like PHP bugs.
• Authorization is opt-in. Do not assume the package protects its own routes. Verify the published route definitions and add middleware yourself.
• Debugging flow. When something renders blank: (1) confirm the service provider is auto-discovered (php artisan about), (2) config:clear, (3) confirm published views/assets exist and are not stale, (4) check the schema JSON parses and that every referenced node type is registered, (5) tail storage/logs/laravel.log for swallowed exceptions from the renderer.
• Extension points to probe early. Component/node registration (how you add a custom element type), the render driver abstraction if one exists, and any events fired on save. These are the three places a 0.x package is most likely to churn, so knowing them now shortens future upgrades.
• Documentation risk. With only a changelog link at v0.1.0, budget time for reading source. Do not build a large feature on an undocumented behaviour; confirm it in the code first.