Laravel Favicon Generator Laravel Package

Getting Started

Heads-up on this release. v2.0.0 shipped with no release notes beyond a changelog link, so treat the upgrade as a verify-then-adopt rather than a drop-in. A major bump on a package this small almost always means a config schema change, a renamed facade/namespace, or a new minimum PHP/Laravel constraint. Before you composer require it, open the changelog commits and diff config/favicon.php (or equivalent) against your published copy — that file is where 90% of breaking changes will land.

Install and publish:

composer require infernalmedia/laravel-favicon-generator
php artisan vendor:publish --tag=favicon-config   # confirm tag name in the README

Where to look first, in order:

1. config/favicon.php — source image path, output sizes, storage disk, and any cache/TTL settings. If v2 renamed keys, this is your migration surface.
2. The package service provider — confirms what's auto-registered (routes, Blade directives, facades) and what you must wire manually.
3. The README's "usage" block — the shortest path from a source image to generated <link> tags.

First use case: point the config at your master source image (ideally a 512×512+ PNG with transparency), run the generate command, then drop the package's Blade component/directive into your layout's <head>. That single loop — source image in, correct <link rel="icon"> set out — is what you'll use 95% of the time. Get that working end-to-end before touching per-environment or per-tenant variations.

Implementation Patterns

Static assets, generated at deploy time. The healthiest pattern for most apps: treat favicons like compiled assets. Run generation in your deploy pipeline or a post-autoload-dump hook, commit or upload the output to your public disk, and let the Blade directive just emit tags. This keeps request-time latency at zero and makes the output diffable in review.

// In a deploy script or Composer hook — not on every request.
Artisan::call('favicon:generate');

Dynamic / multi-tenant generation. If the package supports generating from an arbitrary source (URL, upload, tenant logo), wrap it in a queued job rather than doing it inline in a controller. Image resizing is CPU-bound; a 10-size favicon set on a request thread is a great way to blow a timeout on modest hardware.

GenerateFavicons::dispatch($tenant);          // queued
// Blade: emit tags only once the job has completed, else fall back to defaults.

Guard with a tenant->favicons_generated_at column so you're not regenerating on every logo tweak that never actually changes the file hash.

Cache-busting is the real work. Browsers cache favicons aggressively — far more than other assets. Whatever the package emits, append a version/hash query string or write to a versioned path (/favicons/{hash}/favicon-32.png). This is the single most common "the package is broken" report, and it's almost never the package.

Layout integration. Keep the directive in your base layout only, not in partials, and make it the sole owner of <link rel="icon"> tags. Duplicate or conflicting icon tags across layouts cause browsers to pick nondeterministically, which makes debugging miserable.

Testing. Assert on the emitted HTML (tags present, correct rel values, absolute URLs) rather than on generated binary files. Snapshot the <head> output in a feature test; that catches config drift after an upgrade far faster than eyeballing a browser tab.

Gotchas and Tips

The empty changelog is the main gotcha. For v2.0.0, read the actual commit history before upgrading. Check specifically for: renamed config keys, a changed default storage disk, dropped support for older Laravel/PHP, and whether the facade or Blade directive name changed. Pin the old major in composer.json until you've confirmed each of these against your published config.

Config publishing shadowing. If you published config/favicon.php under v1, Composer's package update will not overwrite your published copy. New v2 defaults silently won't apply, and you'll get confusing behaviour where docs and reality diverge. Re-publish to a scratch file, diff, and merge deliberately.

Image driver dependency. Most generators of this type lean on GD or Imagick via Intervention Image. Verify which extension the CI container and production boxes actually have — a passing local run on a machine with Imagick tells you nothing about a slim Alpine image with neither. Add a startup check or a health assertion.

Storage disk and URL divergence. Generated files on local but URLs built for public, or a Storage::url() path that doesn't match your CDN prefix, produces 404s that look like generation failures. Confirm FILESYSTEM_DISK and the package's configured disk agree, and that php artisan storage:link has run wherever it's needed.

Permissions in the web root. Writing into public/ at runtime fails under many hardened deploy setups (read-only release dirs, e.g. some Envoyer/Deployer configurations). Prefer writing to a writable disk and serving via a route or symlink.

Debugging approach. When icons don't update: (1) curl the icon URL directly and check the HTTP status and Content-Type; (2) hard-reload or open in a private window to eliminate cache; (3) confirm the <link> tags in view-source, not the devtools element inspector, which can show normalised DOM. Work outward from the raw HTTP response — that isolates package vs. cache vs. markup in three steps.

Extension points to reach for before forking. The config file's size/path arrays and the package's generation event or command are usually enough to customise output without forking. If you find yourself overriding a class, check first whether v2 added a contract or a publishable view — major versions of small packages frequently add extension points precisely because everyone was forking.

Watch the source image. Square, ≥512×512, transparent background, no baked-in padding. A surprising share of "generated icons look wrong" issues trace back to a non-square or pre-padded source, and every downstream size inherits the problem.