Sonata Permission Bundle Laravel Package

Getting Started

1. Install with composer require and publish the package assets — most Laravel form/field packages ship config, migrations, and Blade views in one command (php artisan vendor:publish --provider="..."). Publish and commit the config before writing any field definitions so later minor upgrades don't silently change defaults under you.
2. Look first at the field definition class and its option/attribute list. The 1.0.2 release adds multiple_choice as an option on a field, not a new field type — so the place to read is wherever existing options (labels, required flags, help text) are set, plus the renderer that maps option values to markup.
3. First use case: a single question that the author wants to expose as either a radio group (pick one) or a checkbox group (pick many). Define the field, set multiple_choice to the appropriate mode, drop it into a Blade form, and confirm the submitted payload shape before wiring up persistence.

Start with one field end-to-end (definition → render → validate → store → re-render on edit) before templating other forms; the option only pays off once the round-trip is proven.

Implementation Patterns

Treat multiple_choice as a contract between renderer and validator, not just a display toggle. The three places that must agree:

• Field definition — the option value (radio vs checkbox).
• Validation rule — required|string|in:... for a single selection, required|array|min:1 plus array.* for multiple.
• Storage cast — a scalar column for radio, a JSON/text column (with an array cast) for checkboxes.

Derive the last two from the option rather than duplicating literals:

$isMulti = $field->option('multiple_choice') === 'checkbox';

$rules = $isMulti
    ? ['answers.'.$key => ['required', 'array', 'min:1'], 'answers.'.$key.'.*' => ['string', Rule::in($options)]]
    : ['answers.'.$key => ['required', 'string', Rule::in($options)]];

Centralise the mode. If the option can be edited after responses exist, resolve it in one accessor/helper and read it everywhere. Scattered string comparisons on 'checkbox' are where inconsistent behaviour creeps in.

Editing existing records. Hydrate from storage into the renderer: cast JSON back to an array for multi, wrap the scalar in an array for the view's checked/selected comparison, so a single Blade partial can serve both modes.

Integration tips. For Livewire/Alpine, bind to an array in both modes (single-select simply keeps one element) to avoid the scalar↔array branch in the component. For API/Inertia surfaces, normalise the output to an array in resources and let the client decide how to present it.

Gotchas and Tips

• Unchecked radios submit nothing; unchecked checkboxes submit nothing either, but multi needs "at least one" handling. required behaves differently for arrays vs scalars — an empty array fails required, but so does a missing key, and the error message is unhelpful. Add a min:1 and a custom message.
• Default behaviour after the upgrade. 1.0.2 adds the option; confirm what an unset multiple_choice resolves to. If it defaults to radio, fields that previously accepted multiple values will start rejecting them. Diff the published config before deploying.
• Re-publish or clear caches after the bump if you've overridden the package views (php artisan view:clear); stale compiled views are the usual cause of "the option has no effect".
• Stored value drift. Adding multi-select to an existing field means old scalar rows and new array rows coexist. Normalise on read ((array) $value) rather than writing a migration that guesses.
• Comparison strictness in Blade. in_array($option, $value, true) with string cast values; loose comparison makes "0" and empty-string options match unexpectedly.
• Checkbox ids. Appending the option index to the id prevents duplicate-for label clicks selecting the wrong input in repeated/nested field groups.
• Debugging. Dump the field's resolved option array and the validated payload together — nine times out of ten the mismatch is between what the renderer emitted and the rule's expected shape, not the renderer itself.
• Extension point. If the package exposes a field/option resolver or view namespace, override there rather than editing vendor files; minor releases are frequent and small, so unpatched overrides are cheap insurance.