Statamic Weather Addon Laravel Package

Getting Started

Install the package and publish its configuration so you can see the condition-to-icon map it ships with:

composer require <vendor>/<package>
php artisan vendor:publish --tag=<package>-config

Look first at the published config file — it is the heart of the package. You will find an icons (or similarly named) array keyed by weather condition, with per-icon-set sub-arrays. As of v2.0.2 there is a phosphor (Phosphoricons) mapping alongside the previously supported sets, so any condition entry now resolves to a Phosphor icon name as well as the older ones.

Confirm the service provider is auto-discovered (php artisan about or check bootstrap/cache/packages.php), then verify the mapping resolves:

// tinker
app(<Vendor>\<Package>\WeatherIcons::class)->for('partly-cloudy-day', 'phosphor');

The first real use case is rendering a forecast in Blade: take the condition string your weather API returns, pass it through the package, and output the icon class or SVG. Start with a single hard-coded condition before wiring in live API data — that isolates mapping problems from provider problems.

Implementation Patterns

Resolve icons in one place, not in views. Wrap the package call in a small helper, Blade component, or view model so the icon-set choice is a single decision rather than scattered string literals:

class WeatherIcon
{
    public function __construct(protected string $set = 'phosphor') {}

    public function render(string $condition, ?bool $isNight = null): string
    {
        return app(WeatherIcons::class)->for($condition, $this->set, $isNight);
    }
}

Pick the set at the boundary. Bind your preferred icon set once in a service provider (or read it from config('weather-icons.default')) rather than passing 'phosphor' at every call site. When you later switch sets, the change is one line and one config value.

Normalise provider conditions before lookup. Different APIs say Partly cloudy, partly-cloudy, cloudy-partly, or return numeric codes. Build a thin adapter that maps your provider’s vocabulary onto the package’s canonical keys, and keep that adapter under test. The package’s map is the target, not the source of truth for upstream naming.

Use it in API resources and Inertia props too. Icon names are cheap strings; resolve them server-side and ship the resolved name (plus the set identifier) to the frontend so your JS never needs a duplicate map:

return [
    'condition' => $forecast->condition,
    'icon'      => $icons->for($forecast->condition, 'phosphor'),
];

Cache the resolved map, not the lookups. If you are rendering dozens of icons per request, the array lookup is already trivial — don’t reach for Cache::remember per condition. If anything, memoise the parsed config once per request in a singleton.

Compose with a Blade component for markup consistency, especially if you render Phosphor as a webfont (class-based) versus inline SVG:

<x-weather-icon :condition="$forecast->condition" set="phosphor" />

Test the mapping, not the package. Assert that your domain conditions produce non-null icons and that unmapped conditions fall back rather than throwing. A data-provider test over your condition enum catches upstream vocabulary drift early.

Gotchas and Tips

Re-publish or merge, never overwrite blindly. If you published the config before v2.0.2, the Phosphor block will not appear in your app’s copy. Diff the vendor config against yours and merge the new keys — or, better, keep your customisations in a separate config file merged at boot so package upgrades stay painless.

config:cache is the usual culprit. A published config that works in local but returns null icon names in production is almost always a stale config cache. Run php artisan config:clear && php artisan config:cache after any config change.

Phosphor weight variants change the class, not the icon. Phosphoricons ships multiple weights (regular, bold, fill, duotone, light, thin). The icon name from the mapping stays the same; the weight is a CSS/class concern. If your icons render as empty boxes or fall back to a generic glyph, check that the weight suffix you append matches the Phosphor CSS you actually loaded. Duotone in particular needs its own stylesheet.

Webfont vs SVG are not interchangeable. Class-based Phosphor (ph ph-cloud-sun) requires the Phosphor CSS/font assets in your build. If your CSP blocks font files, or you are rendering into email/PDF, prefer the package’s SVG output path (if available) or vendor the SVGs yourself.

Day/night pairs are a common gap. Many condition maps have distinct -day/-night keys. If your provider gives you a condition but no timestamp, you will silently get the daytime icon on a midnight forecast. Derive isNight from the location’s local time and pass it explicitly.

Unknown conditions should degrade gracefully. Decide now what happens for null, '', or an unmapped string — a neutral cloud icon is far better than an exception in a weather widget. Wrap the lookup in your adapter and log the miss (rate-limited) so you learn which conditions the package lacks.

Case and whitespace sensitivity. The map keys are exact strings. Str::slug()-ing or Str::lower()-ing provider values inconsistently is the top source of “the icon is missing” reports. Normalise once, in one function, and use it everywhere.

Extension point: merge your own map at boot. Rather than editing the published file, add missing conditions in a service provider:

$this->mergeConfigFrom(config_path('weather-icons-custom.php'), 'weather-icons');

This survives package upgrades and keeps your additions reviewable in one place.

Debugging a bad mapping — dump the resolved array key and the full map side by side:

dump(config('weather-icons.icons.phosphor.'.Str::slug($condition)));

If the key exists but the value is null, the icon set is missing for that condition (a genuine package gap worth a PR); if the key is absent, your normalisation is off.