Radiobuttonimage Laravel Package

Getting Started

Treat this as a small, early-stage package: before writing application code, spend ten minutes confirming what it actually ships.

composer require ibrahimbougaoua/radiobuttonimage
composer show ibrahimbougaoua/radiobuttonimage

Then inspect the installed package directly:

cat vendor/ibrahimbougaoua/radiobuttonimage/composer.json
find vendor/ibrahimbougaoua/radiobuttonimage -maxdepth 2 -type f | sort

Look for, in this order:

1. README.md — the authoritative usage example, if one exists.
2. composer.json — Laravel/PHP version constraints, autoload namespace, and whether it declares a service provider or a Filament plugin.
3. src/ — the service provider, any Blade component class, config class, or Filament field class.
4. resources/views/ — the actual markup you will be rendering and possibly overriding.
5. config/ — publishable configuration, if any.

Register/publish only what the package actually provides:

php artisan vendor:publish --tag=radiobuttonimage-config
php artisan vendor:publish --tag=radiobuttonimage-views
# or, if tags are undocumented:
php artisan vendor:publish --provider="IbrahimBougaoua\RadioButtonImage\RadioButtonImageServiceProvider"

First use case: a settings or product form where the user picks one image from a small set — storefront theme, product thumbnail variant, avatar preset, or shipping option icon — and you persist the selected key (not the image URL) in the database. Wire it into a single form first, confirm the submitted value, then standardise it as a reusable field across the app.

Implementation Patterns

Keep the persisted value as a stable key. Store theme_blue, variant_a, or an option ID in the database, and resolve the image URL at render time. This survives CDN changes, storage disk moves, and renames.

// config/radiobuttonimage.php (or your own app config)
return [
    'options' => [
        'classic' => ['label' => 'Classic', 'image' => 'images/themes/classic.png'],
        'modern'  => ['label' => 'Modern',  'image' => 'images/themes/modern.png'],
    ],
];

Build a thin wrapper component rather than calling the package field directly everywhere. This isolates you from the package's API and makes future replacement cheap.

{{-- resources/views/components/image-radio.blade.php --}}
@props(['name', 'options', 'selected' => null])

<fieldset class="image-radio">
    <legend class="sr-only">{{ $label ?? $name }}</legend>

    @foreach ($options as $value => $option)
        <label class="image-radio__option">
            <input
                type="radio"
                name="{{ $name }}"
                value="{{ $value }}"
                @checked(old($name, $selected) === $value)
            >
            <img src="{{ asset($option['image']) }}" alt="{{ $option['label'] }}">
            <span>{{ $option['label'] }}</span>
        </label>
    @endforeach
</fieldset>

@error($name)
    <p class="text-red-600">{{ $message }}</p>
@enderror

If the package provides its own Blade component or Filament field, use it inside this wrapper instead of duplicating the markup.

Validate against the same option list used to render the field:

$validated = $request->validate([
    'theme' => ['required', Rule::in(array_keys(config('radiobuttonimage.options')))],
]);

$user->update(['theme' => $validated['theme']]);

Repopulate with old() on every render. A failed validation round-trip is the most common place image radio fields break, because the checked state is easy to forget.

Livewire/Filament integration. If the package exposes a Livewire-compatible field, bind with wire:model and validate in the component's rules(). If it is a plain Blade component, wrap it in a Livewire view and pass $this->selected through. Confirm which layer the package targets before designing around it — a Filament field cannot be used in a plain Blade form, and vice versa.

Resolve URLs through storage, not asset(), if images are user-uploaded or hosted on S3:

Storage::disk('public')->url($option['image']);

Centralise the option list in config or a dedicated class so the form, validation rule, and any API resource all read from one source.

Gotchas and Tips

• Verify the package type first. The name and description do not make it clear whether this is a plain Blade component, a Filament field, or a form macro. Check src/ before assuming an API; guessing here wastes the most time.

• Zero dependents and a vague description mean low bus factor. Pin the version in composer.json, read the full source (it is small), and do not build critical UI on undocumented behaviour. The wrapper component pattern above is your insurance.

• Check Laravel/PHP constraints in the package's composer.json before upgrading your app. Early-stage packages often lag on Laravel major versions.

• Publish and own the views. If you need markup changes, publish the package views and edit them locally, or skip the package's view entirely and use only its option/config helpers. Do not edit files in vendor/.

• Clear caches after publishing:

  php artisan config:clear && php artisan view:clear
  

  A published config is invisible until the config cache is cleared.

• Accessibility is usually the weak point. Ensure the group is a <fieldset> with a <legend>, inputs share the same name, every image has meaningful alt text, and the selected state is visible without relying on colour alone.

• Validation error key mismatch. Errors surface under the input name. If the package nests names like options[theme], your @error directive and validation key must match exactly.

• Do not trust raw labels into HTML. If option labels are user-controlled, escape them; {!! !!} around package-rendered labels is an XSS vector.

• Image weight matters. Radio image grids load every option at once. Serve thumbnails, set explicit width/height, and lazy-load non-critical images.

• CSS conflicts. The package's styles may fight Tailwind or your design system. Prefer publishing the views and replacing classes over !important overrides.

• Debugging checklist: inspect the rendered HTML for the checked attribute, confirm the field name matches the validation rule, check that the service provider is auto-discovered (php artisan about or bootstrap/cache/packages.php), and verify asset URLs resolve in the browser network tab.

• Extension points to prefer: published config for options, published views for markup, and a wrapper component for everything else. Avoid subclassing package classes unless they are clearly designed for extension.