Add further documentation and fix bug for missing width and height of icon set (#2)

* configure package

* Initial setup to find icons and cache results

* Ignore cache directory

* Change workflows

* Update workflow to install npm dependencies

* Test workflow

* Icons being found, cached, and tests passing

* Pint format code

* Clean up and get tests fixed

* Blade directive to publish out config

* Fix styling

* Collection routes

* Refactor to increase test coverage

* Clean up and fix domain

* Install command and cache refactor

* Refactor to cache icon info separate from the icon data to lower repeated caches

* Format code

* Clean up

* Tests passing

* Unset data right away

* Test expanding testing matrix

* Only do version 11 and 12

* Update dependencies

* Revert to only testing Laravel 11

* Remove declaring carbon version

* Okay okay, bring back carbon version

* Update dependencies

* Clean up and correct types

* Documentation and ability to turn off API

* Add contributing docs

* Update README.md

* Clean up email

* Clean up and consistency

* Greater documentation in read me file and fix when height and width aren't available

* Clean up incorrect docs

* Fix styling

* Update run-tests.yml

---------

Co-authored-by: abetwothree <[email protected]>

Author: abetwothree

.github/workflows/run-tests.yml

@@ -8,6 +8,8 @@ on:
       - 'phpunit.xml.dist'
       - 'composer.json'
       - 'composer.lock'
+      - 'package.json'
+      - 'package-lock.json'
 
 jobs:
   test:

README.md

@@ -5,12 +5,19 @@
 [![GitHub Code Style Action Status](https://img.shields.io/github/actions/workflow/status/abetwothree/laravel-iconify-api/fix-php-code-style-issues.yml?branch=main&label=code%20style&style=flat-square)](https://github.com/abetwothree/laravel-iconify-api/actions?query=workflow%3A"Fix+PHP+code+style+issues"+branch%3Amain)
 [![Total Downloads](https://img.shields.io/packagist/dt/abetwothree/laravel-iconify-api.svg?style=flat-square)](https://packagist.org/packages/abetwothree/laravel-iconify-api)
 
-This is a Laravel package for the [Iconify](https://iconify.design/index.html) icons [on demand API](https://iconify.design/docs/icon-components/). It allows you to easily use on demand icons and use your Laravel applicatioin as the Iconify API.
+Make your Laravel Application an API for on demand icons using the [Iconify](https://iconify.design/index.html) icon web components.
+
+This Laravel package creates a few API routes for the [Iconify](https://iconify.design/index.html) icons [on demand API](https://iconify.design/docs/icon-components/). It allows you to easily use on demand icons and use your Laravel applicatioin as the Iconify API.
 
 It works similarly to the [Node Iconify API](https://github.com/iconify/api) and is a spiritual successor to their [PHP implementation](https://github.com/iconify/api.php).
 
 On demand icons work great whether you use Livewire, Inertia, or just plain Blade views to render your Laravel application and want to render icons dynamically using a single component.
 
+## Requirements
+
+- PHP 8.4
+- Laravel 11.x
+
 ## How To Use
 
 Install the package via composer:
@@ -27,6 +34,19 @@ In your core application blade layout file add the following directive in the he
 
 This will configure the [Iconify API](https://iconify.design/docs/api/providers.html#api-config) on demand icons to load the icons from your Laravel application instead of the Iconify API.
 
+By default Icon API routes will work out of the following route path in your Laravel application:
+
+```
+/iconify/api
+```
+
+The following routes are currently available:
+
+- `/iconify/api/{prefix}.json?icons={icon-prefix}` - Returns icon SVG data for an icon set. Icon prefix can be comma separated for multiple icons.
+- `/iconify/api/{prefix}/icons.jsonicons={icon-prefix}` - Same as above.
+- `/iconify/api/collections` - Returns a list of icon collections available in your application.
+- `/iconify/api/collection?prefix={prefix}` - Returns the information for a specific icon collection.
+
 ### How To Display Icons
 
 To displays icons follow the instructions on the [Iconify](https://iconify.design/docs/icon-components/) on demand docs and use any of their component libraries in your Laravel Application.
@@ -47,6 +67,22 @@ This will publish a `iconify-api.php` file in your `config` directory. You can t
 
 For advanced setting details, please see the [config file](config/iconify-api.php).
 
+## Icon Caching
+
+This package uses Laravel's caching system to cache the icon data to make repeated requests for the same icon faster. It caches icon data when it is requested so that it only caches the icons that are actually used in your application.
+
+You can set which cache store to use for this package in your `config/iconify-api.php` file. Otherwise, it will use your default cache store setting.
+
+## Missing Features
+
+The MVP of this package was to provide an API for on demand icons in your Laravel Application. A few API endpoints that currently exist on the Node JS package are missing in this package and will be added in future releases:
+
+- [ ] Return icon data in in JSONP callback format.
+- [ ] List icons in a collection.
+- [ ] List icons categorized in a collection.
+- [ ] Search endpoint for icons.
+- [ ] Keywords endpoint for icons.
+
 ## Changelog
 
 Please see [CHANGELOG](CHANGELOG.md) for more information on what has changed recently.
@@ -59,6 +95,14 @@ Please see [CONTRIBUTING](CONTRIBUTING.md) for details.
 
 Please review [our security policy](../../security/policy) on how to report security vulnerabilities.
 
+## Code Quality
+
+This package uses the following code quality tools:
+
+- PHPStan 2.x at level 10 for static analysis.
+- Laravel Pint for consistent code style.
+- PHP Pest for testing.
+
 ## Credits
 
 - [Abraham Arango](https://github.com/abetwothree)

config/iconify-api.php

@@ -22,7 +22,7 @@
     |
     */
 
-    'route_path' => 'iconify-api',
+    'route_path' => 'iconify',
 
     /*
     |--------------------------------------------------------------------------
@@ -63,7 +63,7 @@
     |--------------------------------------------------------------------------
     | Iconify Icon Providers
     |--------------------------------------------------------------------------
-    | By default, this will package will use your application's url as the provider
+    | By default, this package will use your Laravel application as the provider
     | for all iconify icons you install with NPM. If you would like to use a
     | different provider for a specific icon set, you can specify it here.
     |

phpstan-baseline.neon

@@ -1,6 +1,3 @@
-includes:
-    - phpstan-baseline.neon
-
 parameters:
     level: 10
     paths:

phpstan.neon.dist

@@ -9,7 +9,9 @@ class IconifyDirective
     public function render(): string
     {
         $url = LaravelIconifyApi::domain().'/'.LaravelIconifyApi::path();
-        $customProviders = $this->gatherCustomProviders();
+
+        /** @var array<string, array{resources: array<int, string>, rotate?: int}> $customProviders */
+        $customProviders = config()->get('iconify-api.custom_providers', []);
 
         if (empty($customProviders)) {
             $customProviders = '';
@@ -34,22 +36,4 @@ public function render(): string
             </script>
         HTML;
     }
-
-    /**
-     * @return array<string, array{resources: array<int, string>, rotate?: int}>
-     */
-    protected function gatherCustomProviders(): array
-    {
-        /**
-         * @var array<string, array{resources: array<int, string>, rotate?: int}> $customProviders
-         */
-        $customProviders = config()->get('iconify-api.custom_providers', []);
-        $providerList = [];
-
-        foreach ($customProviders as $provider => $data) {
-            $providerList[$provider] = $data;
-        }
-
-        return $providerList;
-    }
 }

resources/views/.gitkeep

@@ -8,8 +8,8 @@
  *      lastModified: int,
  *      icons: array<string, array{body: string}>,
  *      aliases: array<string, array<string,string>>,
- *      width?: int,
- *      height?: int,
+ *      width?: int|null,
+ *      height?: int|null,
  * }
  * @phpstan-type TIconData = array{
  *      icons: array<string, array{body: string}>,

src/IconifyDirective.php

@@ -28,10 +28,16 @@ public function find(string $set): array
         $data = [
             'prefix' => $content['prefix'],
             'lastModified' => $content['lastModified'],
-            'width' => $content['width'] ?? 0,
-            'height' => $content['height'] ?? 0,
         ];
 
+        if (isset($content['width']) && ! empty($content['width'])) {
+            $data['width'] = $content['width'];
+        }
+
+        if (isset($content['height']) && ! empty($content['height'])) {
+            $data['height'] = $content['height'];
+        }
+
         unset($content);
 
         return $data;

src/Icons/Contracts/IconFinder.php

@@ -9,11 +9,17 @@
     $info = $iconFinder->find($set);
 
     expect($info)->toBeArray()
-        ->toHaveKeys(['prefix', 'lastModified', 'width', 'height'])
+        ->toHaveKeys(['prefix', 'lastModified'])
         ->prefix->toBe($set)
-        ->lastModified->toBeInt()
-        ->width->toBeInt()
-        ->height->toBeInt();
+        ->lastModified->toBeInt();
+
+    if (isset($info['width'])) {
+        expect($info['width'])->toBeInt();
+    }
+
+    if (isset($info['height'])) {
+        expect($info['height'])->toBeInt();
+    }
 })->with([
     ['mdi'],
     ['heroicons'],