Chiron Laravel Package

Getting Started

Start with the three sibling packages, not the core: laravelui5-modules (scaffolding), laravelui5-actions (controller/action layer), and laravelui5-settings (per-artifact context). Install them as you would any Laravel package and publish config before writing anything else — most of the behaviour that bites you in v1.3.0 is config- and CLI-flag-driven rather than code-driven.

First thing to read is the laravelui5-modules scaffolding skill, because since core 3.0 the identity options are mandatory. A --create invocation is refused unless you pass --package-prefix and --php-ns-prefix, plus --vendor when you are scaffolding an app. Read those flags first, then read the settings skill, then the actions skill.

Your first use case should be a throwaway module scaffold:

php artisan ui5:create --package-prefix=acme --php-ns-prefix=Acme --vendor=acme

Do this before you touch an existing app. It gives you a working package layout (composer name, PHP namespace, action directory, settings wiring) that you can diff against your real codebase, and it surfaces missing identity options in seconds rather than at review time.

Note the naming shift while you are orienting: a library is a package since core 3.0. ui5-charts-lib → ui5/Charts → acme/charts is the canonical example — a library is no longer a special case you configure differently, it is a package with the same identity requirements.

Implementation Patterns

Scaffold with explicit identity, every time. Treat the three identity options as required arguments in your own wrapper command or Makefile target rather than relying on muscle memory. --package-prefix drives the composer package name, --php-ns-prefix drives the PHP namespace, and --vendor drives app-level placement. Passing them explicitly also makes scaffolds reproducible in CI and reviewable in diffs.

Do not expect --js-ns-prefix to name anything. It only widens the search for an Easy UI5 source folder. Developers routinely assume it sets the JS namespace on generated output; it does not. Use it when your Easy UI5 folder lives somewhere non-standard and the scaffolder cannot find it, and leave it off otherwise.

Accept kebab-case action namespaces; do not migrate. A scaffolded action's namespace ends in kebab-case since core 3.0 — actions.clear-mailbox rather than actions.clear_mailbox. Existing snake_case namespaces remain valid, so the correct pattern is coexistence: new actions get kebab-case, legacy ones stay as they are, and you never run a mass rename. If you have a registry, route table, or resolver that keys on action namespace strings, make sure it compares literally and does not normalise _ to - (or vice versa), because both forms are now legitimate.

Read settings through the context, everywhere. Since core 3.0, Tile, Chart and Report providers receive their artifact's settings too. The old "reports are the exception" carve-out is gone — you can rely on the same settings-access pattern in every provider type, which means one shared trait or base class instead of per-provider special-casing in the report layer.

Treat settings as read-only at runtime. Writing to a setting throws. This is the single most important pattern change: settings are resolved from configuration, not mutated by application code. If you find yourself wanting to write a setting from a provider, that value belongs in your own storage (cache, DB column, request-scoped service), not in the settings object. Seed defaults in config, then read.

Slots: read anywhere, sourced only from the query string. A slot is read anywhere with $context->slot() — controllers, providers, actions — which makes it a convenient ambient value. But slot values come from the query string only. Do not attempt to populate slots from config, headers, session, or a service container binding; there is no supported path for that. Document the accepted slot keys next to your routes so front-end callers know what to send.

Locale, time zone and period are the slot examples to copy. Build your own slots in that shape: small, presentation-adjacent, per-request values.

Gotchas and Tips

• --create without identity options fails outright on core 3.0. The error is the scaffolder refusing, not a validation warning. If a colleague reports "the command doesn't work anymore", check for a missing --package-prefix / --php-ns-prefix (and --vendor for apps) before anything else.
• The base currency is no longer a slot. If you are upgrading from a 2.x-era setup and your code or docs reference a currency slot, that slot is gone as of core 3.0. Currency belongs in config/settings, not slots. Grep your templates and route documentation for it.
• Settings write attempts throw, not silently no-op. The failure mode is an exception at the write site, which is good for debugging but means a lazy $settings->foo = $bar that used to be harmless is now a runtime error. Search for setter-style calls on settings objects during upgrade.
• Report providers gained settings. Anything you wrote to work around reports not having settings — duplicated config lookups, injected config repositories, constructor shims — can be deleted. Leaving it in place creates two sources of truth.
• Mixed action namespaces are expected. If your tooling (route caching, static analysis, custom scanners) assumes a single casing convention for action namespaces, it will break. Fix the tooling, not the namespaces.
• Kebab-case in namespaces is unusual in PHP. Static analysers and IDE inspections may flag actions.clear-mailbox as a style violation. Configure an exclusion rather than fighting the framework convention; do not "fix" it back to snake_case in new code.
• Extension point to watch: --js-ns-prefix is your only lever for Easy UI5 source discovery. If scaffolding cannot locate your source folder and adding the prefix still fails, the problem is the folder layout expectations, not the prefix — verify the Easy UI5 structure before adding more flags.
• Debugging tip: when a scaffolded module misbehaves, print the resolved identity tuple (vendor / package prefix / PHP namespace) and compare it against composer.json and the PSR-4 autoload block. Mismatches there produce confusing "class not found" errors that look like action-namespace problems but are not.