ichava/core

The engine for the Ichava Laravel icon ecosystem: icon registry, queue-backed seeder, DOM-based SVG sanitiser, icon cache, and the base <x-ichava::icon> Blade component, with zero HTTP surface.

Targets PHP ^8.4.1 || ^8.5 on Laravel ^13, against SQLite, PostgreSQL, MySQL or MariaDB.

Install

Nothing in the Ichava family is on Packagist yet, so the application's composer.json first names the VCS repositories for core, the four laranail/* packages core depends on, and each pack you install. Installation holds that block, and it is the one place that lists them. Then:

composer require ichava/core:^0.1

The service provider registers itself through package discovery. Installation covers every step.

Quick start guide and usage

Getting started

Core ships no icons, so install a pack beside it, run the migrations and seed the icon index:

composer require ichava/icon-sets-tabler:^0.1
php artisan migrate
php artisan ichava::ichava-core.database seed --package=ichava/icon-sets-tabler

Publishing the config is optional: php artisan vendor:publish --tag=ichava::ichava-core-config writes config/ichava/ichava-core.php, read as config('ichava.ichava-core.*').

Usage

Render an icon with the Blade component, which works with any installed pack:

<x-ichava-core::icon name="ichava/icon-sets-tabler::outline/home" class="w-6 h-6" />

<x-ichava::icon> is the same component under the configurable short prefix (components.short_prefix), on by default. Or use the fluent helper, which renders when cast to a string:

{{ ichava('ichava/icon-sets-tabler::filled/home')->color('#4338ca')->class('w-5 h-5') }}

Register a set of your own, from a pack provider's optional pack() hook or straight from code:

use Simtabi\Laranail\Ichava\Services\IconRegistry;
use Simtabi\Laranail\Ichava\Support\Pack\PackBuilder;

app(IconRegistry::class)->register(
    PackBuilder::make('acme/social', storage_path('icons/social/files'))
        ->prefix('social')
        ->variant('outline', ['fill' => 'none', 'stroke' => 'currentColor'])
        ->build(),
);

A pack that keeps everything in its config.json needs none of this: its provider names its constants and component classes, and Pack registration covers both paths and bulk registration.

See Getting started for the full walkthrough, and the documentation index for everything else.

Documentation

The full documentation lives in this repository, under docs/, and is indexed below.

Guides

• Installation — VCS repositories, config, migrations, first pack
• Getting started — your first icon, in Blade and in PHP
• Configuration — every config key and what it changes
• Environment variables — the ICHAVA_* surface
• Database support — the four drivers, and what only PostgreSQL does
• Icons and illustrations — SVG kind, theme twins, and querying by kind
• Host user — the host's signed-in user, Gates, owner-keyed preferences and host events
• Architecture — what core provides, topology, boot order, extension seams
• Troubleshooting — the failures that look like something else
• Release — how a version is cut, and what a release carries

Reference

• Icon path format — the one normaliser both spellings go through
• Blade components — <x-ichava-core::icon>, the short tag, and the attributes
• Pack registration — the simple and advanced pack paths, PackBuilder, and bulk registration
• Global helper — the fluent ichava() API
• Artisan commands — every command core registers
• Query and model API — scopes, filters, events, status and the extension interfaces

Recipes

• Seed the database
• Add a custom icon set
• Use an icon pack
• Seed pack icons
• Check pack updates
• Serve icons from a CDN

Contributing & security

See CONTRIBUTING.md. Report vulnerabilities privately through the security policy, never in a public issue.

License

MIT. © Simtabi LLC. See LICENSE.