Icons Laravel Package

Getting Started

The install is a single Composer line and no manual service-provider registration, because Laravel package discovery picks it up:

composer require orchidsoftware/icons

Immediately after install, do two things before writing any UI code:

1. Publish and read the config. php artisan vendor:publish --tag=orchid-icons-config (confirm the exact tag in the package README — it is the fastest way to learn the option names) and open the resulting file. Everything you need to know about the package lives there: the default set, the asset path, and the size/class defaults. That file is the API surface.
2. Publish the assets if the package ships SVGs rather than inlining them, and commit or deploy that directory deliberately. This is the single most common post-deploy failure — a working local dev environment and blank icons in production because the published path was never shipped.

Then run a real screen. The highest-value first use case is an Orchid menu item, because it exercises the whole chain in about five minutes: registration, name resolution, asset lookup, and CSS inheritance.

Menu::make('Dashboard')
    ->icon('speedometer')
    ->route('platform.dashboard');

If that icon renders and inherits your sidebar's text colour, the package is wired correctly and you can spend the rest of the day on coverage. If it renders an empty gap, you have an asset path or naming problem — debug that before touching anything else, because every subsequent failure mode looks identical.

Budget roughly one day for the spike: install, one menu, one table action, one button, one empty state. That is enough to answer "does this fit" without committing a sprint.

Implementation Patterns

Wrap it before you use it. This is the pattern that matters more than anything else in this assessment. Every call site should go through one local Blade component, not the vendor component directly:

{{-- resources/views/components/admin/icon.blade.php --}}
@props(['name', 'class' => 'icon icon-sm'])
<x-orchid-icon :path="$name" {{ $attributes->class($class) }} />

(Verify the vendor tag name — <x-orchid-icon> vs <x-icon> — from the README; the wrapper means you only get that wrong once.) With the wrapper in place, swapping the source set later, or vendoring the SVGs, is a one-file change instead of a codebase-wide find-and-replace. It also gives you a single place to add aria-hidden, a fallback renderer, and name normalisation.

Keep a named vocabulary, not free-form strings. Icons fail silently on unknown names, so the cheapest defence is to stop hand-typing icon strings at call sites. Define an enum or a constant list of approved names and reference those:

enum AdminIcon: string {
    case Dashboard = 'speedometer';
    case Orders    = 'basket';
    case Settings  = 'settings';
}

Then ->icon(AdminIcon::Orders->value) in the menu builder, and @props(['name' => AdminIcon::Dashboard]) in the wrapper. A typo becomes a PHP error instead of a blank gap that survives code review.

Menu builder, table actions, and buttons are the three integration points you will use daily:

// Screen / table row actions
TD::make('actions')
    ->render(fn ($row) => Button::make()
        ->icon(AdminIcon::Settings->value)
        ->method('edit', ['id' => $row->id]));

// Blade layout
<x-admin.icon :name="AdminIcon::Orders" class="icon-lg text-muted" />

The icon-picker field is the differentiator. If the package exposes an Orchid form field for icons (per the package description it registers sets and integrates with form builders), use it wherever a user or admin chooses an icon — CMS categories, navigation entries, status badges. Store the name in a string column and render it through the wrapper at display time; never store SVG markup in the database.

Control size and colour from CSS, never from the package. Pass a class in, let currentColor do the rest:

.icon     { width: 1rem;  height: 1rem; }
.icon-sm  { width: .875rem; height: .875rem; }
.icon-lg  { width: 1.25rem; height: 1.25rem; }

The moment you start passing fill="#333" or hard-coded width="24", dark mode and theme changes break, and you have re-created the inconsistent-SVGs problem the package exists to solve.

Add a dev-only assertion. In AppServiceProvider::boot(), fail loudly in local/testing when a name is not in your enum, and render a visible fallback (a square, a question mark) in production instead of a blank gap.

Gotchas and Tips

• Unknown icon names fail silently. This is the number-one operational risk named in the technical review, and it produces quiet visual regressions that pass code review because nothing throws and nothing logs. Mitigate with the enum pattern above plus a visible fallback, not just discipline.

• Pin against your orchid/platform version. Zero stars and zero dependents means no external production validation of compatibility. Check the package's constraint against your Laravel and Orchid majors in CI, and pin the exact version — an unpinned minor bump is an unnecessary variable in an admin panel deploy.

• Accessibility is on you, not the package. Decide per icon whether it is decorative or semantic. Decorative: aria-hidden="true" and a text label elsewhere. Semantic (icon-only buttons): role="img" plus aria-label. An icon-only table action with no label is unusable with a screen reader — bake the label into your wrapper's API so developers cannot forget it.

• Check CSP early. Inlined SVG sometimes carries style attributes or inline <style> blocks that violate a strict style-src. Verify against your actual production CSP header rather than the local default — this is a fifteen-minute check that costs a day if found after launch.

• Asset publishing and caching. Published assets need to be in your deploy artifact, and you may need a cache-busting strategy for upgraded icon sets. Also remember php artisan config:cache and view:cache in your deploy script — stale config is a frequent cause of "icons stopped working after deploy" that looks like a package bug.

• Licence clearance is a real gate. The icon sets (Font Awesome, Bootstrap Icons, Tabler) carry their own licences, and Font Awesome in particular has attribution requirements. Confirm commercial redistribution is permitted before shipping, and document the answer somewhere durable.

• Do not mix sets. The package supports several families, which is convenient for the picker but dangerous for consistency. Pick one set for your admin chrome and enforce it in the enum. Mixing reintroduces the visual inconsistency the adoption was meant to remove.

• Vendoring is a cheap escape hatch. Keep the published SVGs in a path you control so that if upstream goes stale you can fork the assets without touching call sites. Because the wrapper is your only coupling point, this is measured in hours.

• Keep it out of marketing surfaces. This is a restrained, single-weight line vocabulary for wayfinding. It will not stretch to brand expression, and the technical review is explicit that you should not try. If the roadmap includes a brand-forward surface, that is a separate decision.

• Debugging checklist for a blank icon: is the name in the set (check the published directory listing) → are the assets deployed → is the config cached with a stale path → is a CSP rule blocking it → is the element actually sized (zero-width container is the sneaky one). Work that list in order; it resolves nearly every report.