Update readme

README.md

@@ -1,6 +1,7 @@
 # PCM Icon Bundle
 
-Use icons inside of Twig templates with ease!
+Use icons inside of Twig templates with ease! Project must be using Tailwind for the colours to work properly.
+
 
 ```php
 {{ icon({ icon: 'person' }) }}
@@ -52,9 +53,20 @@ PALLETE_NAME:
 
 `size (int)` Size of the icon in pixels
 
-`colour (string)` Name of the main colour pallete to use. Defaults to `"primary"`, assuming that a pallete with the project's primary colour will exist
+`colour (string)` Name of the main colour pallete to use. Defaults to `"primary"`, which is a pallete that uses the project's primary colour. If however you are not using `primary` to set a Tailwind primary colour in your project, you can instead set the default colour of the icon by changing what colour classes the primary pallete uses. EG:
+```yaml
+primary:
+    fill:                             'fill-purple-700'
+    stroke:                         'stroke-purple-700'
+    fill-hover:                 'hover:fill-purple-700'
+    stroke-hover:             'hover:stroke-purple-700'
+    fill-group-hover:     'group-hover:fill-purple-700'
+    stroke-group-hover: 'group-hover:stroke-purple-700'
+```
 
 `hover (string)` Name of the colour pallete to use when the icon is hovered over
 
+`classes (string[])` Additional classes to add to the icon. This can cause Tailwind class collisions, so use with caution if at all.
+
 ## Reminders
-Remember to add `./config/packages/*.yaml` as a value in your Tailwind config content array if it does not already exist.
+Remember to add `./config/packages/*.yaml` as a value in your Tailwind config content array if it does not already exist. This will ensure Tailwind classes inside of the config file get compiled.

src/Twig/Functions/IconExtension.php

@@ -12,11 +12,12 @@ final class IconExtension extends AbstractExtension
     public const DEFAULT_SIZE = 32;
 
     private const DEFAULT_OPTIONS = [
-        'icon' => null,
-        'title' => null,
-        'size' => self::DEFAULT_SIZE,
-        'colour' => 'primary',
-        'hover' => null
+        'icon'    => null,
+        'title'   => null,
+        'size'    => self::DEFAULT_SIZE,
+        'colour'  => 'primary',
+        'hover'   => null,
+        'classes' => [],
     ];
 
     public function __construct(private array $directories, private array $palletes)
@@ -33,10 +34,10 @@ final class IconExtension extends AbstractExtension
         if (empty($this->palletes))
             throw new \InvalidArgumentException('Palletes array must contain at least one pallet!');
 
-        $pelletesContainNonarray = array_reduce($this->palletes,
+        $palletesContainNonarray = array_reduce($this->palletes,
             fn($notArray, $path) => $notArray || !is_array($path));
 
-        if ($pelletesContainNonarray)
+        if ($palletesContainNonarray)
             throw new \TypeError('Palletes array must only contain arrays!');
 
         foreach ($this->palletes as $pallete) {
@@ -69,11 +70,14 @@ final class IconExtension extends AbstractExtension
      * @param array $options
      * ```
      * $options = [
-     *     'icon'   => (string)  Which icon to use
-     *     'title'  => (?string) Text to appear on mouse hover
-     *     'size'   => (int)     Height and width in px
-     *     'colour' => (string)  Main colour pallete
-     *     'hover'  => (?string) Hover colour pallete
+     *     'icon'     => (string)  REQUIRED Which icon to use
+     *     'title'    => (?string) Text to appear on mouse hover
+     *     'size'     => (int)     Height and width in px
+     *     'colour'   => (string)  Main colour pallete
+     *     'hover'    => (?string) Hover colour pallete
+     *     'classes'  => (array)   Additional classes to add to the icon.
+     *                             Use with caution as this can potentially
+     *                             cause Tailwind class conflicts!
      * ]
      * ```
      */
@@ -81,14 +85,22 @@ final class IconExtension extends AbstractExtension
     {
         $options = $this->getMergedOptions($userOptions);
         $svg = $this->getSanitisedIconSvg($options['icon']);
+
         $colourClasses = $this->getColourClasses($options['colour'], $options['hover']);
-        $svg = $this->addClassesToSvg($svg, $colourClasses);
+        $extraClasses = $this->getExtraClasses($options['classes']);
+
+        $svg = $this->addClassesToSvg($svg, trim($colourClasses.' '.$extraClasses));
         $svg = $this->addTitleToSvgIfNotNull($svg, $options['title']);
         $svg = $this->setSvgHeightAndWidth($svg, $options['size']);
 
         return $svg;
     }
 
+    private function getExtraClasses(array $extraClasses): string
+    {
+        return implode(' ', $extraClasses);
+    }
+
     private function getMergedOptions(array $userOptions): array
     {
         $this->throwIfUnrecognisedOptionExists($userOptions);

tests/Twig/Functions/IconExtensionTest.php

@@ -300,10 +300,29 @@ class IconExtensionTest extends TestCase
         $this->assertMatchesRegularExpression('/<svg.+class=".*group-hover:stroke-white.*".*>/', $contents);
     }
 
+    public function testExtraClassesThrowsIfNotAnArray(): void
+    {
+        $this->expectException(\TypeError::class);
+        $this->icon->renderIcon(['icon' => self::ICON, 'classes' => 'string_value']);
+    }
+
+    public function testExtraClassesGetAdded(): void
+    {
+        $contents = $this->icon->renderIcon(['icon' => self::ICON, 'classes' => ['abc', 'def']]);
+        $this->assertMatchesRegularExpression('/<svg.+class=".*abc.*".*>/', $contents);
+        $this->assertMatchesRegularExpression('/<svg.+class=".*def.*".*>/', $contents);
+    }
+
+    public function testAddingExtraClassesDoesntStripAwayColourClasses(): void
+    {
+        $contents = $this->icon->renderIcon(['icon' => self::ICON, 'classes' => ['abc']]);
+        $this->assertMatchesRegularExpression('/<svg.+class=".*abc.*".*>/', $contents);
+        $this->assertMatchesRegularExpression('/<svg.+class=".*fill-primary.*".*>/', $contents);
+    }
+
     public function testThrowsIfInvalidOptionPassed(): void
     {
         $this->expectException(\InvalidArgumentException::class);
         $this->icon->renderIcon(['icon' => self::ICON, 'fake-key-should-throw' => null]);
-
     }
 }