Laraslice Laravel Package

Getting Started

1. Migrate manifests before anything else. v1.8.0 removes JSON manifest reads entirely — any slice with a slice.json will throw. Run the upgrade path in this order:

   grep -rl "slice.json" .            # find the stragglers
   php artisan slice:migrate-json-to-yaml --dry-run
   php artisan slice:migrate-json-to-yaml
   

   Only add --delete once you've committed and confirmed the YAML output is correct.
2. Republish the UI layer. The Default UI program ships as published components, so an upgrade without php artisan slice:repair --publish-ui leaves you on the old, hand-tuned views and none of the rendering fixes appear.
3. Validate the shipped blueprints first. Run php artisan slice:validate against the 10 example blueprints — they all pass on v1.8.0, which makes them a trustworthy reference for what a correct manifest looks like before you touch your own.
4. Open /laraslice/studio and answer the home prompt. Studio Home asks "What are you starting from?" and routes you to a BRD/AI brief, a legacy port, or a from-zero design. Pick the path that matches your task rather than navigating menus.
5. First real use case: port an existing MySQL schema through the Porter. You get sidebar curation and enum(...) → manifest options extracted for free, which is the fastest way to see the Default UI improvements on something that isn't a toy.

Implementation Patterns

• Treat the manifest as the source of truth, not a scaffold. Detail pages, form selects, table columns, and labels are all built from the manifest in 1.8. Everything you'd previously fix in Blade — an FK showing an ID, a raw active/inactive string, a date as a timestamp — is now a manifest declaration. Fix it there and it propagates to listings, detail pages, and form selects at once.
• Declare options, don't post-process. Any field with declared options renders as a real <select> in forms and as its label (not the raw value) in displays. Storage suffixes are stripped from display labels automatically, so status_id-style naming doesn't leak into the UI.
• Rely on *_name columns for FK labels. Foreign keys resolve to real labels everywhere — including *_name label columns. If a relation renders as a bare ID, the relation isn't declared in the manifest; that's the fix, not a view override.
• Curate wide tables via essential columns. Mark essential columns in the manifest; everything else lands behind the persisted Columns menu. Don't trim columns by editing the generated table — users' column choices are persisted and would be lost.
• Use the destinations as destinations. Port, Design, Create, and Manage are peers at stable URLs (Schema is a sub-view of Design). Deep-link into the one you need; legacy studio URLs redirect in. All POST endpoints are unchanged, so existing automation and form posts against the studio keep working.
• Review YAML diffs, not screens. Studio saves are preview-first with a YAML diff modal and version history; slice:diff gives you the same diff in the CLI. Wire slice:diff into code review so manifest changes are reviewed like code, not discovered at runtime.

Gotchas and Tips

• The JSON removal is a hard failure, not a warning. JSON-only slices throw with a migration hint at read time. Migrate before deploying, and re-run slice:validate after migration — a mechanically-converted manifest can be syntactically valid but semantically wrong.
• --delete is destructive. It removes the source JSON. Run --dry-run, diff the output, commit, then delete; otherwise your rollback path is git history only.
• slice:repair --publish-ui overwrites published components. If you've hand-edited generated Blade, diff before repairing or you'll lose those edits — and if you keep them, you also keep the old rendering bugs (long text stretching tables, raw values, ID-instead-of-label, raw date dumps).
• "Zero hand-tuning" only holds for unmodified output. The Default UI claims are verified against a production ERP port, but they assume generated views. Stale published components are the most likely reason a fix "didn't apply."
• Enum extraction happens at port time. MySQL enum(...) vocabularies become manifest options during the port — it is not a runtime reflection. Existing slices ported earlier won't gain options; re-port or add them to the manifest by hand.
• Long text clamps to two lines by design. That's the fix for table stretching. If a field genuinely needs full text inline, that's an explicit view override, not a bug report.
• Booleans render Yes/No and dates render human-readably. Don't store or migrate display formatting — it's presentation derived from the manifest. If a date looks wrong, check the manifest field type first.
• Columns-menu state is persisted per user. When testing table defaults, use a fresh user or clear state, otherwise "the default columns are wrong" is really your own saved preference.
• Extension points: the manifest schema (Design), the Porter's curation/extraction behaviour (Port), and the published UI components are the three places to customize. Prefer the first two — component edits are the ones slice:repair will fight you on.
• Bookmarks still work. Legacy studio URLs redirect into the ONE Studio shell, so internal docs and links don't need an emergency sweep — but update them as you touch them.