Json Laravel Package

Technical Evaluation

Architecture fit. iconify/json is not a PHP library — it is a versioned data corpus of ~150k icons across 100+ sets, shipped as consolidated per-set JSON files plus metadata. Its architectural role in a Laravel app is a data layer behind an icon resolver, not a runtime dependency. That fits cleanly with Laravel's service-provider + facade idiom: one IconifyRepository reading from a configured filesystem path, one Cache-backed resolver, one Blade component. The package's value is breadth and licensing-permissiveness of the icon inventory, not any code it contributes.

Integration feasibility. Three viable paths, in descending order of preference:

1. Consume a Composer wrapper (e.g. blade-icons + an Iconify driver) that already vendors the JSON — fastest, lowest ownership cost.
2. Vendor the JSON under resources/icons/ (or read from node_modules) and write a thin reader service ourselves — more control, more ownership.
3. Runtime fetch from the Iconify API — acceptable only for low-traffic or admin surfaces; introduces a third-party network dependency on the render path.

All three are feasible within a single sprint. Path 1 is the recommended default.

Technical risk.

• Licensing is the primary risk. Icon sets are heterogeneous in license (MIT, Apache-2.0, CC-BY-4.0, and some GPL/CC-BY-SA). A per-set license audit is mandatory before shipping; attribution may be required in-product.
• Zero dependents signals no PHP-side validation of this consumption pattern — precedent comes from the JS ecosystem, so we own the integration risk.
• Deploy artifact weight. The full corpus is large; bundling everything inflates build images and slows cold deploys. Set-level curation is an architectural decision, not an optimization.
• No PHP types, no semver on the data. Set prefixes can be renamed or deprecated upstream; our config must treat prefix:name as a soft reference.

Key questions for the team.

1. Which sets do we actually need (target: 2–4)? Who signs off on removing the rest?
2. Build-time bundle vs. runtime fetch — what is our tolerance for a network hop on icon render?
3. Who owns the license audit and the attribution surface?
4. Do we need server-rendered icons (Blade) only, or also a JSON/sprite endpoint for an Inertia/Vue/React front end?
5. What is the fallback behavior for an unresolved icon name?

Integration Approach

Stack fit. Laravel 10/11, PHP 8.1+. The package has no framework coupling, so it composes with whatever rendering layer we already use. For Blade, expose <x-icon name="mdi:home" />; for a JS front end, expose GET /icons/{set}/{name}.svg behind cache headers. Both share the same resolver and cache key space.

Migration path.

• Phase 1 — Curate. Select 2–4 sets, complete the license review, commit only those JSON files, pin the upstream version in composer.json or a lockfile.
• Phase 2 — Wrap. Build IconifyRepository (read + parse + cache) and the Blade component. No call sites change yet.
• Phase 3 — Swap. Migrate existing FontAwesome/Heroicons usages set by set, keeping the old packages installed as a rollback path.
• Phase 4 — Retire. Remove legacy icon fonts and their CSS bundles; measure the payload win.

Compatibility. Coexists with any existing SVG icon package, with one caveat: component name collisions on x-icon if another package already registers it — namespace ours explicitly. No database, queue, or Node build step is strictly required if we consume a Composer-vendored copy; a Node step is only needed if we pull from node_modules.

Sequencing. License audit → set selection → data ingestion → resolver + cache → Blade component / HTTP endpoint → call-site migration → legacy removal. The audit gates everything; do not let a "just try it" spike ship a GPL set into a proprietary product.

Operational Impact

Maintenance. Upstream moves quickly. Pin the version, review upgrades as a scheduled task (monthly is sufficient), and automate the diff as a bot-opened PR. Diffs are large but mechanically reviewable — additions only, unless a set is renamed.

Support. Iconify is a well-run community org but has no PHP maintainer; if we take path 2, we own the wrapper outright. Assign a named owner and write a one-page runbook covering cache busting and set updates.

Scaling. File reads are cheap, but only if we read one consolidated JSON per set and cache the parsed array — never walk per-icon files. For high-traffic surfaces, pre-generate a sprite or inline critical icons at build time and serve the HTTP endpoint through a CDN. OPcache handles the PHP side; Laravel's cache handles the parse cost.

Failure modes to design for.

• Unresolved icon name → render a neutral fallback glyph and log, never a broken layout.
• Cold-cache stampede after deploy → warm the cache in the deploy hook.
• Upstream set rename/removal → references break silently; add a CI check that every icon name used in templates resolves.
• Inline SVG from curated data is low XSS risk, but sanitize anyway if any path allows non-curated input.
• Deploy bloat → enforce the curated set list in CI.

Ramp-up. Low. A developer familiar with Blade components reaches productivity in half a day; the only new concepts are the prefix:name convention and the JSON shape (icons, aliases, width, height, chars). Budget the real time on the license audit and the call-site migration, not the code.