Select Laravel Package

Getting Started

The package is a small piece of the Laravel Enso ecosystem, so treat it as "Enso + Bulma + Vue 2" rather than a standalone select widget.

Minimal setup:

1. composer require laravel-enso/select (the service provider is auto-discovered).
2. If your app already uses laravel-enso/core and the Enso asset pipeline, publish/rebuild front-end assets (php artisan vendor:publish --tag=enso-assets then yarn && yarn dev / npm run prod) so the Vue component is registered alongside the other Enso components.
3. On the backend, expose an options endpoint. The usual pattern is to put the package's Options trait on the controller (or model) and implement an options() method that returns the query used to build the list:

use LaravelEnso\Select\app\Traits\Options;

class UserController extends Controller
{
    use Options;

    protected $optionList = ['value' => 'id', 'label' => 'name'];

    public function options()
    {
        return User::query()->where('active', true);
    }
}

4. On the front end, use the registered component in a form:

<select v-model="form.user_id" :source="route('administration.users.options')" />

Where to look first: src/app/Traits/Options.php (or the equivalent trait) and src/app/Classes/ for the option-list builder — that is where the contract between your Eloquent query and the JSON the component consumes is defined. Then the Vue component under resources/js/ (or src/resources/js/) to see the accepted props.

First use case worth wiring: a single-user picker on an edit form — load the current value via v-model, fetch the rest from the options endpoint, confirm the selected user renders correctly on reload.

Implementation Patterns

Server-side option builder. The trait is meant to be composed into a controller; the options() method returns an Eloquent builder, and the package serializes it to {value, label} pairs using the $optionList mapping. Override $optionList per controller to change which columns become the value and label, or define a custom OptionList class when you need computed labels (e.g. first_name . ' ' . last_name).

Standard endpoint shape. Keep the route under your existing administration.* or api.* group so it inherits auth middleware. The component expects a JSON array of objects; returning paginated envelopes will silently render an empty dropdown.

Cascading selects. The common day-to-day pattern is country → county or role → permissions. Bind a @change / @input on the parent, reset the child model to null, and point the child's :source at a route that accepts the parent id, passing it with :params (or interpolating the URL). Always clear the child value before re-fetching, or you'll keep a stale selection whose id no longer exists in the new list.

Edit forms. Preload the current value by passing the raw id(s) into v-model. The component will fetch the label for the pre-set value on mount. For multi-select, the model must be an array — pass [] not null in the initial form state.

Multi-select. Set the multiple prop and bind a v-model array. The payload sent to the server is an array of ids; persist it via a pivot table or a JSON column, whichever your domain uses. Remember to transform the ids back into an array on edit ($model->roles->pluck('id')).

Reusable field definitions in Enso forms. If you're using enso-form, declare the select in the fields config with type: 'select' and a route pointing to the options endpoint; this is the idiomatic way and avoids hand-rolling the component in each view.

Search and pagination. For large lists, prefer a source endpoint that supports a query parameter and debounce the client-side search rather than shipping thousands of options at once. Trim the builder (select('id', 'name')) — the package maps columns, so hydrating full models is wasted work.

Gotchas and Tips

• Vue 2 and Bulma only. The component assumes Enso's Vue 2 + Bulma stack. Dropping it into a Vue 3 / Tailwind app means rewriting the component; you'd be better off with vue-multiselect.
• Empty dropdown, no error. Almost always a payload-shape mismatch. Check the endpoint returns a flat array of {value, label} (or whatever your $optionList maps to) and that value keys exist — a null id breaks track-by.
• Auth and CSRF on the options route. Because it's a JSON fetch from the component, the endpoint must sit behind your normal web middleware. 401/419 failures surface as an empty select; check the network tab first.
• Type coercion in multi-select. Eloquent ids come back as ints, form values may be strings. Use track-by or cast consistently, or the pre-selected item won't highlight on edit.
• Asset rebuild required. Changes to the Vue component or published config won't appear until you recompile. If the component "isn't registered", verify yarn dev ran and that Enso's asset plugin is including the package.
• Don't ->get() in options() unless you must — return the builder and let the package apply its own limits/serialization, otherwise you lose the mapping logic.
• Extension point: subclass or replace the OptionList builder when you need formatted labels, appended keys, or custom JSON structure. That's the intended seam rather than overriding the Vue component.
• Debugging tip: hit the options endpoint directly with curl/Postman while authenticated. If the JSON is right, the problem is the component props; if it's wrong, it's the trait/$optionList mapping. That split saves most of the debugging time.
• Small ecosystem, limited docs. With ~26 stars, expect to read src/ rather than rely on a README. Pin the version in composer.json — this package tracks Enso releases and breaking changes land without much ceremony.