Getting Started

Know what you're installing first. madeyourday/contao-rocksolid-icon-picker is a Contao bundle (composer type contao-module), not a Laravel package. It registers a DCA field so editors get a visual icon grid instead of typing CSS classes. In a pure Laravel app, composer require will drop files into vendor/ and do nothing else: no service provider, no routes, no vendor:publish. So "getting started" splits into two tracks:

You are on Contao 4.13+/5.0 — install it and use it directly:
```
composer require madeyourday/contao-rocksolid-icon-picker
```
Then clear the Contao cache (var/cache) and look in the bundle's src/ + dca/ folders for the field class and its eval keys. The vendor docs (rocksolidthemes.com, EN/DE links in the README) are the only prose documentation — the changelog is your real API reference. The changelog confirms the keys you'll actually touch: fontPath, the optional blank/"none" entry, and the icon font family.
You are on Laravel — treat the package as a reference implementation and an icon-font asset source. First files to open: the bundled WOFF/WOFF2 fonts and their @font-face CSS, the picker template (how icons are rendered and titled), and the field class (how icon names are discovered from the CSS). That's the 90% you can reuse; the DCA plumbing is the 10% you replace.

First use case to build: a "feature card" or "button" content block where an editor picks an icon and the front end renders <i class="icon icon-{{ $icon }}">. In Contao that's a DCA field + palette entry. In Laravel that's a string column, a validation rule against an icon manifest, and a Blade partial:

{{-- resources/views/components/icon.blade.php --}}
<i class="icon icon-{{ $name }}" aria-hidden="true" title="{{ $title ?? '' }}"></i>

Pick this package over hand-rolling when you want the visual grid UX and a ready icon font rather than SVG-per-icon, and when your editors are non-technical.

Implementation Patterns

Pattern A — Native Contao DCA field (the intended path). Add the field to tl_content (or your own table) via dca/*.php, set fontPath to your icon font's CSS, and reference the field in a palette. Behaviours baked in and worth copying into any reimplementation:

The blank/"none" entry is only injected when the field is not mandatory (v2.0.2, #7) — so a required picker can never be submitted empty.
Icons carry title attributes (v2.0.2) — keep that for accessibility.
Dark-theme colours are inherited (v2.1.1) — the icons follow the backend theme.

Pattern B — Laravel: port the manifest, not the DCA. Build a single source of truth for icons and generate everything from it:

// config/icons.php  (or storage/app/icons.json generated by a command)
return [
    'rocket'   => ['title' => 'Launch',  'class' => 'icon-rocket'],
    'user'     => ['title' => 'Account', 'class' => 'icon-user'],
];

Then:

Validate in a Form Request: 'icon' => ['nullable', Rule::in(array_keys(config('icons')))], — never trust the raw class string.
Render via the Blade component above, resolving the title from the manifest rather than the DB.
Generate the picker as an Alpine/Livewire radio grid (icon + label + title) so you keep the package's "browsable grid, no typing" UX.

Pattern C — Filament / Nova admin panel. Wrap the same manifest in a Select with ->options() plus a custom option view that emits <i class="icon ...">, or a Radio with grid columns. This is the closest Laravel analogue to the DCA field and takes an afternoon.

Pattern D — Filament-style "swap the set" abstraction. Store a slug (user), not a CSS class (fa-user). It survives font swaps (Font Awesome → bundled WOFF set → SVG sprite) without a data migration, and it lets you keep the package's font for now and move to Blade Icons/Heroicons later.

Asset pipeline. Copy the WOFF2/WOFF fonts into resources/fonts/ and let Vite rewrite the URLs — do not copy the vendor @font-face block verbatim, because it points at Contao-symlinked web/ paths:

@font-face {
  font-family: 'rs-icons';
  src: url('../fonts/rs-icons.woff2') format('woff2'),
       url('../fonts/rs-icons.woff') format('woff');
  font-display: swap;
}
.icon { font-family: 'rs-icons'; font-style: normal; line-height: 1; }

Load the icon CSS only in your admin layout (and wherever the front end genuinely uses the icons) — it's a full icon font, so don't ship it to every public page if you only use three glyphs.

Hybrid Contao + Laravel. If you run a bridge/embedded backend, let Contao own the picker and expose the stored value read-only to Laravel (repository or small API endpoint). Don't try to render a Contao DCA widget from Blade — you'll inherit the widget's JS, its save-mode handling, and its backend asset loading for zero benefit.

Gotchas and Tips

It will not boot in Laravel. No service provider, no auto-discovery, composer type is a Contao module. Any guide implying vendor:publish or a config file is wrong for this package.
fontPath is the number-one failure point. v2.0.2 fixed paths starting with web/; v2.0.5-era fixes covered Windows path separators and empty fontPath. If icons silently don't render, check fontPath first, then the font family name — v1.0.3 existed because IE choked on over-long family names.
Symlinked assets are fragile. v1.0.8 fixed symlink recursion; v1.0.1 fixed Apache 2.4 access protection. If composer install leaves you with 403s or a symlink loop, that's a known class of problem, not your server being weird. In Laravel you avoid it entirely by copying fonts into resources/ and building with Vite.
Blank option is conditional. In a mandatory field there is no empty choice — if you replicate the picker, mirror that and still validate server-side. Also remember the v2.0.2 "merge icon names" change (#8): if your CSS has aliases, the value stored may differ from the class you expect. Prefer an explicit manifest over CSS class-name scraping.
title attributes and dark theme are features, not decoration. Use fill: currentColor / inherit colour when you port the CSS, or your icons will be invisible in dark admin themes (the 2.1.1 work exists for exactly this).
WOFF2 is backend-only (v2.1.2). The package loads WOFF2 in Contao's back end; it does not style your front end. Your site needs its own @font-face, and if you're on Laravel you're writing that regardless.
Version bounds are tight. Requires Contao 4.13/5.0 and Symfony 6 (v2.1.0). A Contao 4.9/Symfony 5 project can't take the current release — pin to an older tag or skip.
"Save mode hack" support (v1.0.2). This is Contao-specific submit handling. Not a concern in Laravel, but a useful warning: any port must handle the case where the field was not re-rendered before save (Livewire/Alpine: make sure the bound value is on the model before validation).
Tiny vendor, small blast radius. 7 stars, 0 dependents, docs hosted on the vendor's site. Pin an exact version in composer.json, and if you depend on undocumented eval keys, read the field class in vendor/ rather than guessing — the changelog references DCA-config access bugs (#12) that only surface once you start customising fields.
Debugging checklist: Contao → clear var/cache, verify the palette actually references the field, inspect the rendered <i> classes; Laravel → config:clear/view:clear after editing the manifest, and check that the font file is emitted by Vite (public/build/manifest.json).
Extension point for a custom icon set: keep the package's naming convention (CSS classes + fontPath) and point fontPath at your own stylesheet. In Laravel the equivalent extension point is the manifest array — which is why storing slugs rather than classes matters.

Contao Rocksolid Icon Picker Laravel Package

Getting Started

Implementation Patterns

Gotchas and Tips