├── src
    ├── UnknownIconException.php
    ├── functions.php
    ├── Facades
    │   └── Icon.php
    ├── IconDownloader.php
    ├── IconRenderer.php
    ├── Icon.php
    ├── IconServiceProvider.php
    ├── IconCache.php
    └── Commands
    │   └── IconsPreloadCommand.php
├── LICENSE
├── README.md
├── composer.json
└── config
    └── unicon.php


/src/UnknownIconException.php:
--------------------------------------------------------------------------------
 1 | <?php
 2 | 
 3 | declare(strict_types=1);
 4 | 
 5 | namespace Unicon;
 6 | 
 7 | use Exception;
 8 | 
 9 | class UnknownIconException extends Exception
10 | {
11 |     public function __construct(string $name)
12 |     {
13 |         parent::__construct("Unknown icon: {$name}");
14 |     }
15 | }
16 | 


--------------------------------------------------------------------------------
/src/functions.php:
--------------------------------------------------------------------------------
 1 | <?php
 2 | 
 3 | declare(strict_types=1);
 4 | 
 5 | use Unicon\Facades\Icon;
 6 | 
 7 | if (! function_exists('icon')) {
 8 |     /**
 9 |      * Renders an icon.
10 |      * 
11 |      * @param  string  $name  The name of the icon to render.
12 |      * @return string The rendered icon.
13 |      */
14 |     function icon(string $name): string
15 |     {
16 |         return Icon::render($name);
17 |     }
18 | }
19 | 


--------------------------------------------------------------------------------
/src/Facades/Icon.php:
--------------------------------------------------------------------------------
 1 | <?php
 2 | 
 3 | declare(strict_types=1);
 4 | 
 5 | namespace Unicon\Facades;
 6 | 
 7 | use Unicon\IconRenderer;
 8 | use Illuminate\Support\Facades\Facade;
 9 | 
10 | /**
11 |  * @see Unicon\IconRenderer
12 |  * 
13 |  * @method static string render(string $name) Renders the icon.
14 |  */
15 | class Icon extends Facade
16 | {
17 |     protected static function getFacadeAccessor()
18 |     {
19 |         return IconRenderer::class;
20 |     }
21 | }
22 | 


--------------------------------------------------------------------------------
/LICENSE:
--------------------------------------------------------------------------------
1 | Copyright 2024 Nicolas Hedger
2 | 
3 | Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
4 | 
5 | The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
6 | 
7 | THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.


--------------------------------------------------------------------------------
/README.md:
--------------------------------------------------------------------------------
 1 | [![](docs/og.svg)](https://unicon.rocks)
 2 | 
 3 | ![GitHub License](https://img.shields.io/github/license/unicon-rocks/unicon-laravel)
 4 | ![GitHub Tag](https://img.shields.io/github/v/tag/unicon-rocks/unicon-laravel?label=version)
 5 | ![PHP Versions](https://img.shields.io/badge/php-%3E%3D8.1-blue)
 6 | ![Laravel Versions](https://img.shields.io/badge/laravel-%3E%3D10-red)
 7 | 
 8 | Unicon is a package for [Laravel] that enables seamless, on-demand integration of over 200,000 icons from the [Iconify] API, with caching for optimized performance.
 9 | 
10 | [Laravel]: https://laravel.com
11 | [Iconify]: https://iconify.design/
12 | 
13 | # Installation
14 | 
15 | You can install the package via [Composer] by running the following command.
16 | 
17 | ```bash
18 | composer require unicon-rocks/unicon-laravel
19 | ```
20 | 
21 | [Composer]: https://getcomposer.org
22 | 
23 | ## Documentation
24 | 
25 | The full documentation can be found at [unicon.rocks](https://unicon.rocks).
26 | 
27 | ## License
28 | 
29 | Unicon is open-source software licensed under the [MIT license](LICENSE).
30 | 


--------------------------------------------------------------------------------
/src/IconDownloader.php:
--------------------------------------------------------------------------------
 1 | <?php
 2 | 
 3 | declare(strict_types=1);
 4 | 
 5 | namespace Unicon;
 6 | 
 7 | use Illuminate\Support\Facades\Http;
 8 | 
 9 | /**
10 |  * Iconify icon downloader.
11 |  */
12 | class IconDownloader
13 | {
14 |     /**
15 |      * Downloads an icon from the Iconify API.
16 |      *
17 |      * This method will attempt to resolve the icon by calling the Iconify API.
18 |      *
19 |      * @param  string  $prefix  The prefix of the icon to download.
20 |      * @param  string  $name  The name of the icon to download.
21 |      *
22 |      * @returns string  The icon as an SVG string.
23 |      * @returns null    If the icon could not be resolved.
24 |      */
25 |     public function download(string $prefix, string $name): ?string
26 |     {
27 |         try {
28 |             return Http::baseUrl(config('unicon.iconify.url'))
29 |                 ->withOptions(config('unicon.iconify.request_options', []))
30 |                 ->get("$prefix/$name.svg")
31 |                 ->throwUnlessStatus(200)
32 |                 ->body();
33 |         } catch (\Exception) {
34 |             return null;
35 |         }
36 |     }
37 | }
38 | 


--------------------------------------------------------------------------------
/composer.json:
--------------------------------------------------------------------------------
 1 | {
 2 | 	"name": "unicon-rocks/unicon-laravel",
 3 | 	"description": "Universal icon component for Laravel",
 4 | 	"type": "library",
 5 | 	"license": "MIT",
 6 | 	"autoload": {
 7 | 		"psr-4": {
 8 | 			"Unicon\\": "src/"
 9 | 		},
10 | 		"files": ["src/functions.php"]
11 | 	},
12 | 	"authors": [
13 | 		{
14 | 			"name": "Nicolas Hedger",
15 | 			"email": "nicolas@hedger.ch"
16 | 		}
17 | 	],
18 | 	"minimum-stability": "stable",
19 | 	"require": {
20 | 		"php": ">=8.1",
21 | 		"illuminate/console": "^12|^11|^10",
22 | 		"illuminate/support": "^12|^11|^10",
23 | 		"guzzlehttp/guzzle": "^7"
24 | 	},
25 | 	"require-dev": {
26 | 		"orchestra/testbench": "^8 || ^9 || ^10",
27 | 		"laravel/pint": "^1.18",
28 | 		"phpunit/phpunit": "^11 || ^10"
29 | 	},
30 | 	"autoload-dev": {
31 | 		"psr-4": {
32 | 			"Unicon\\Test\\": "test/"
33 | 		}
34 | 	},
35 | 	"scripts": {
36 | 		"test": "@php vendor/bin/phpunit --colors=always",
37 | 		"lint": ["@php vendor/bin/phpstan analyse --verbose --ansi"],
38 | 		"format": "@php vendor/bin/pint --repair"
39 | 	},
40 | 	"extra": {
41 | 		"laravel": {
42 | 			"providers": ["Unicon\\IconServiceProvider"],
43 | 			"aliases": {
44 | 				"Icon": "Unicon\\Facades\\Icon"
45 | 			}
46 | 		}
47 | 	}
48 | }
49 | 


--------------------------------------------------------------------------------
/src/IconRenderer.php:
--------------------------------------------------------------------------------
 1 | <?php
 2 | 
 3 | declare(strict_types=1);
 4 | 
 5 | namespace Unicon;
 6 | 
 7 | class IconRenderer
 8 | {
 9 |     public function __construct(
10 |         protected IconCache $cache,
11 |         protected IconDownloader $downloader,
12 |     ) {}
13 | 
14 |     public function render(string $name): ?string
15 |     {
16 |         $parts = explode(':', $name, 2);
17 | 
18 |         $prefix = count($parts) === 2 ? $parts[0] : config('unicon.defaults.prefix');
19 |         $name = count($parts) === 2 ? $parts[1] : $name;
20 | 
21 |         if (!$prefix) {
22 |             throw new \InvalidArgumentException(
23 |                 'The prefix must be specified either in the name of the icon or in the configuration.',
24 |             );
25 |         }
26 | 
27 |         $icon = match ($isInCache = $this->cache->has($prefix, $name)) {
28 |             true => $this->cache->pull($prefix, $name),
29 |             false => $this->downloader->download($prefix, $name),
30 |         };
31 | 
32 |         // If the icon was not found in the cache, store it in the cache.
33 |         if (! $isInCache && ! is_null($icon)) {
34 |             $this->cache->put($prefix, $name, $icon);
35 |         }
36 | 
37 |         return $icon;
38 |     }
39 | }
40 | 


--------------------------------------------------------------------------------
/src/Icon.php:
--------------------------------------------------------------------------------
 1 | <?php
 2 | 
 3 | declare(strict_types=1);
 4 | 
 5 | namespace Unicon;
 6 | 
 7 | use Closure;
 8 | use Illuminate\Support\Facades\App;
 9 | use Illuminate\Support\Str;
10 | use Illuminate\View\Component;
11 | use PHPUnit\Framework\TestSize\Unknown;
12 | 
13 | class Icon extends Component
14 | {
15 |     public function __construct(
16 |         public IconRenderer $renderer,
17 |         public string $name,
18 |     ) {}
19 | 
20 |     /**
21 |      * Renders the Icon component.
22 |      */
23 |     public function render(): Closure
24 |     {
25 |         return function () {
26 | 
27 |             $svg = $this->name ? $this->renderer->render($this->name) : '';
28 | 
29 |             if (!$svg) {
30 |                 if (!App::environment(['production'])) {
31 |                     throw new UnknownIconException($this->name);
32 |                 }
33 |                 return '';
34 |             }
35 | 
36 |             return $this->injectAttributes($svg);
37 |         };
38 |     }
39 | 
40 |     /**
41 |      * Injects the attributes into the SVG element.
42 |      */
43 |     protected function injectAttributes(string $svg): string
44 |     {
45 |         return Str::replace(
46 |             search: '<svg ',
47 |             replace: '<svg {{ $attributes->merge([\'class\' => config(\'unicon.defaults.class\') ?: null ]) }} ',
48 |             subject: $svg,
49 |         );
50 |     }
51 | }
52 | 


--------------------------------------------------------------------------------
/src/IconServiceProvider.php:
--------------------------------------------------------------------------------
 1 | <?php
 2 | 
 3 | declare(strict_types=1);
 4 | 
 5 | namespace Unicon;
 6 | 
 7 | use Illuminate\Foundation\Application;
 8 | use Illuminate\Support\Facades\Blade;
 9 | use Illuminate\Support\ServiceProvider;
10 | 
11 | class IconServiceProvider extends ServiceProvider
12 | {
13 |     public function register(): void
14 |     {
15 |         // Merge the default configuration
16 |         $this->mergeConfigFrom(__DIR__ . '/../config/unicon.php', 'unicon');
17 | 
18 |         // Bind the IconRenderer to the container
19 |         $this->app->bind(IconRenderer::class, function (Application $app) {
20 |             return new IconRenderer(
21 |                 cache: $app->make(IconCache::class),
22 |                 downloader: $app->make(IconDownloader::class),
23 |             );
24 |         });
25 | 
26 |         // Register the Blade component
27 |         Blade::component(
28 |             class: Icon::class,
29 |             alias: config('unicon.name', 'icon'),
30 |         );
31 |     }
32 | 
33 |     public function boot(): void
34 |     {
35 |         if ($this->app->runningInConsole()) {
36 |             $this->publishes([
37 |                 __DIR__ . '/../config/unicon.php' => config_path('unicon.php'),
38 |             ], 'unicon-config');
39 | 
40 |             $this->commands([
41 |                 Commands\IconsPreloadCommand::class,
42 |             ]);
43 |         }
44 |     }
45 | }
46 | 


--------------------------------------------------------------------------------
/config/unicon.php:
--------------------------------------------------------------------------------
 1 | <?php
 2 | 
 3 | declare(strict_types=1);
 4 | 
 5 | return [
 6 | 
 7 |     /*
 8 |     |--------------------------------------------------------------------------
 9 |     | Default rendering options
10 |     |--------------------------------------------------------------------------
11 |     |
12 |     | This section contains the default rendering options for the icons.
13 |     |
14 |     */
15 | 
16 |     'defaults' => [
17 | 
18 |         /*
19 |         |--------------------------------------------------------------------------
20 |         | Default class names
21 |         |--------------------------------------------------------------------------
22 |         |
23 |         | The default class names to apply to all rendered icons.
24 |         |
25 |         */
26 | 
27 |         'class' => '',
28 | 
29 |     ],
30 | 
31 |     /*
32 |     |--------------------------------------------------------------------------
33 |     | Cache configuration
34 |     |--------------------------------------------------------------------------
35 |     |
36 |     | This section contains the configuration options for the icon cache.
37 |     |
38 |     */
39 | 
40 |     'cache' => [
41 |         'disk' => [
42 |             'driver' => 'local',
43 |             'path' => 'icons',
44 |         ],
45 |     ],
46 | 
47 |     /*
48 |     |--------------------------------------------------------------------------
49 |     | Component name
50 |     |--------------------------------------------------------------------------
51 |     |
52 |     | This value is the name that will be used to register the Blade component
53 |     | and directive.
54 |     |
55 |     */
56 | 
57 |     'name' => 'icon',
58 | 
59 |     /*
60 |     |--------------------------------------------------------------------------
61 |     | Iconify options
62 |     |--------------------------------------------------------------------------
63 |     |
64 |     | This section contains the configuration options for the Iconify API.
65 |     |
66 |     */
67 | 
68 |     'iconify' => [
69 |         'url' => 'https://api.iconify.design',
70 |         'request_options' => [
71 |             'timeout' => 5,
72 |         ],
73 |     ],
74 | 
75 | ];
76 | 


--------------------------------------------------------------------------------
/src/IconCache.php:
--------------------------------------------------------------------------------
 1 | <?php
 2 | 
 3 | declare(strict_types=1);
 4 | 
 5 | namespace Unicon;
 6 | 
 7 | use Illuminate\Contracts\Filesystem\Filesystem;
 8 | use Illuminate\Support\Facades\Storage;
 9 | 
10 | class IconCache
11 | {
12 |     /**
13 |      * Puts an icon in the cache.
14 |      *
15 |      * @param  string  $prefix  The prefix of the icon to put.
16 |      * @param  string  $name  The name of the icon to put.
17 |      * @param  string  $svg  The SVG string of the icon to put.
18 |      * @return bool True if the icon was successfully put in the cache,
19 |      *              false otherwise.
20 |      */
21 |     public function put(string $prefix, string $name, string $svg): bool
22 |     {
23 |         return $this->getDisk()->put($this->getPath($prefix, $name), $svg);
24 |     }
25 | 
26 |     /**
27 |      * Checks if an icon is in the cache.
28 |      *
29 |      * @param  string  $prefix  The prefix of the icon to check.
30 |      * @param  string  $name  The name of the icon to check.
31 |      * @return bool True if the icon is in the cache, false otherwise.
32 |      */
33 |     public function has(string $prefix, string $name): bool
34 |     {
35 |         return $this->getDisk()->exists($this->getPath($prefix, $name));
36 |     }
37 | 
38 |     /**
39 |      * Pulls an icon from the cache.
40 |      *
41 |      * @param  string  $prefix  The prefix of the icon to pull.
42 |      * @param  string  $name  The name of the icon to pull.
43 |      * @return string|null The SVG string of the icon, or null if the icon
44 |      *                     was not found in the cache.
45 |      */
46 |     public function pull(string $prefix, string $name): ?string
47 |     {
48 |         if (!$this->has($prefix, $name)) {
49 |             return null;
50 |         }
51 | 
52 |         return $this->getDisk()->get($this->getPath($prefix, $name));
53 |     }
54 | 
55 |     public function clear(): void
56 |     {
57 |         $this->getDisk()->deleteDirectory('icons');
58 |     }
59 | 
60 |     protected function getDisk(): Filesystem
61 |     {
62 |         return Storage::disk(config('unicon.cache.disk.driver', 'local'));
63 |     }
64 | 
65 |     protected function getPath(string $prefix, string $name): string
66 |     {
67 |         $path = config('unicon.cache.disk.path', '');
68 | 
69 |         return "$path/$prefix/$name.svg";
70 |     }
71 | }
72 | 


--------------------------------------------------------------------------------
/src/Commands/IconsPreloadCommand.php:
--------------------------------------------------------------------------------
  1 | <?php
  2 | 
  3 | declare(strict_types=1);
  4 | 
  5 | namespace Unicon\Commands;
  6 | 
  7 | use Unicon\IconRenderer;
  8 | use Illuminate\Console\Command;
  9 | use Illuminate\Support\Collection;
 10 | use Illuminate\Support\Str;
 11 | 
 12 | class IconsPreloadCommand extends Command
 13 | {
 14 |     /**
 15 |      * The name and signature of the console command
 16 |      */
 17 |     protected $signature = 'icons:preload';
 18 | 
 19 |     /**
 20 |      * The console command description
 21 |      */
 22 |     protected $description = 'Preloads all Unicon icons';
 23 | 
 24 |     public function __construct(
 25 |         protected IconRenderer $renderer,
 26 |     ) {
 27 |         parent::__construct();
 28 |     }
 29 | 
 30 |     /**
 31 |      * Execute the console command
 32 |      */
 33 |     public function handle(): int
 34 |     {
 35 |         $this->info('Looking for icons to preload in your Blade files...');
 36 | 
 37 |         $this->findAllBladeFiles()
 38 |             ->flatMap(fn(string $file) => $this->findIconsInFile($file))
 39 |             ->unique()
 40 |             ->sort()
 41 |             ->each(fn(string $icon) => $this->preloadIcon($icon));
 42 | 
 43 |         return self::SUCCESS;
 44 |     }
 45 | 
 46 |     /**
 47 |      * Find all Blade files in the application
 48 |      * 
 49 |      * This method will look for all Blade files in the application and return
 50 |      * them as an array of paths.
 51 |      * 
 52 |      * @return Collection<string>
 53 |      */
 54 |     protected function findAllBladeFiles(): Collection
 55 |     {
 56 |         return $this->glob('*.blade.php');
 57 |     }
 58 | 
 59 |     /**
 60 |      * Recursive glob
 61 |      * 
 62 |      * This method will recursively glob files using the given pattern.
 63 |      */
 64 |     protected function glob(string $pattern, ?string $root = null): Collection
 65 |     {
 66 |         $root ??= base_path();
 67 | 
 68 |         $files = collect(glob($root . '/' . $pattern));
 69 | 
 70 |         collect(glob($root . '/*', GLOB_ONLYDIR))->each(function ($dir) use (&$files, $pattern) {
 71 |             if (!in_array(basename($dir), ['node_modules', 'vendor'])) {
 72 |                 $files = $files->merge($this->glob($pattern, $dir));
 73 |             }
 74 |         });
 75 | 
 76 |         return $files;
 77 |     }
 78 | 
 79 |     /**
 80 |      * Find all icons in a Blade file
 81 |      * 
 82 |      * This method will attempt to find all Unicon icons in a Blade file
 83 |      * by performing a regex search on the file contents. This implementation
 84 |      * only works for icons that have been statitcally defined. Variables in
 85 |      * the name attribute will not be evaluated.
 86 |      */
 87 |     protected function findIconsInFile(string $path): Collection
 88 |     {
 89 |         $contents = file_get_contents($path);
 90 | 
 91 |         $componentName = Str::snake(config('unicon.name', 'icon'));
 92 | 
 93 |         $hasMatches = preg_match_all(
 94 |             pattern: '/<x-' . $componentName . '\s+name\s*=\s*(["\'])(?<name>[\s\S]*?)\1/m',
 95 |             subject: $contents,
 96 |             matches: $matches,
 97 |             flags: PREG_SET_ORDER,
 98 |         );
 99 | 
100 |         if (!$hasMatches) {
101 |             return [];
102 |         }
103 | 
104 |         return collect($matches)->map(fn($match) => $match['name']);
105 |     }
106 | 
107 |     /**
108 |      * Preloads an icon
109 |      */
110 |     protected function preloadIcon(string $icon): void
111 |     {
112 |         $this->info("Preloading {$icon}...");
113 |         $this->renderer->render($icon);
114 |     }
115 | }
116 | 


--------------------------------------------------------------------------------