Laravel Iconify Api Laravel Package

Getting Started

• Install with composer require abetwothree/laravel-iconify-api; the service provider and Iconify facade are auto-discovered, so there's no manual registration step in a standard Laravel skeleton.
• Publish the config first and read it before writing any call site: php artisan vendor:publish --tag=iconify-config (check the README for the exact tag in v1.5.x). The config holds the API base URL/host, HTTP timeout, cache store + TTL, and the providers array.
• Skim, in this order: config/iconify.php, the facade class (to see the real method signatures), then the provider/client class that builds requests. Most surprises come from config defaults, not from the methods.
• First use case: search for an icon by keyword and render the resulting SVG in a Blade view. Do it once, inline, in a throwaway route — it confirms outbound connectivity to the Iconify host, that caching works, and that your config is actually being read.

Implementation Patterns

• Wrap the facade, don't sprinkle it. Create a small IconService (or a Icon value object) that resolves names, applies fallbacks, and returns a typed DTO. Iconify's payload shape is verbose; normalizing it once keeps controllers and Blade clean and gives you a single place to change when the upstream API shifts.
• Blade rendering via a component. A <x-icon name="mdi:home" /> component that calls your service and emits {!! $svg !!} is the highest-leverage integration. Add aria-hidden/role="img" and a $attributes merge so it composes with Tailwind classes.
• Cache aggressively, per icon. Wrap calls in Cache::remember("iconify:{$prefix}:{$name}", $ttl, ...). Icon data is effectively immutable for a given set version, so a long TTL (days) with a scheduled flush is usually right. Keys must include the provider name once you configure more than one.
• Prefetch / warm. A small Artisan command that scans templates (or a hardcoded list of used icons) and primes the cache makes cold renders deterministic and lets you run with a short HTTP timeout in production.
• Custom providers are the pattern to reach for when you're behind a firewall, self-hosting the Iconify API, or serving a proprietary icon set. Register each one in providers with its own base URL and prefix, then resolve icons with that prefix. Keep provider definitions in config, not in code, so per-environment hosts differ cleanly.
• Admin icon pickers. Expose a search endpoint through your own controller (with throttle middleware) rather than calling the facade from the browser-facing route directly — you get validation, prefix whitelisting, and rate limiting for free.
• Testing. Http::fake() the Iconify endpoints in your test suite; assert on the cached path too. Never let CI hit the live API.

Gotchas and Tips

• v1.5.1 adds declare(strict_types=1) package-wide. This is the one upgrade risk. If you extend any package class or implement an interface from it, your overrides must now match parameter and return types exactly — loose coercion that previously passed will throw TypeError. Run your suite against 1.5.1 before shipping; if you only consume the facade, the upgrade is a no-op.
• v1.5.1 fixes a bug in custom Iconify provider handling. If your providers entries were silently falling back to the default host (or resolving the wrong base URL), that's the fix. Re-test multi-provider setups after upgrading rather than assuming prior behaviour.
• Always set a timeout. These are outbound HTTP calls; a slow icon host inside a Blade @foreach will stall the whole response. Set a short connect/read timeout in config and make your service fail soft.
• Cache key collisions across providers. The classic bug is caching mdi:home from provider A and serving it for provider B. Prefix keys with the provider name.
• Config caching in production. php artisan config:cache snapshots your config — don't call env() from application code, and remember to re-run it after changing provider hosts.
• Raw SVG output is deliberate. {!! !!} is required, so treat the source as trusted. If a custom provider base URL is operator-configurable, sanitize the payload; don't let untrusted SVG through.
• Search is expensive. Limit the prefixes you search and cap result counts; unbounded searches across all Iconify sets are slow and hit rate limits.
• Upstream drift. Icon sets are updated independently of this package. Pin a TTL and refresh rather than caching forever, or you'll ship stale icon definitions for renamed glyphs.