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,51 +70,41 @@ 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!
      * ]
      * ```
      */
     public function renderIcon(array $userOptions): string
     {
-        $options = $this->mergeUserOptionsWithDefaults($userOptions);
+        $options = $this->getMergedOptions($userOptions);
+        $svg = $this->getSanitisedIconSvg($options['icon']);
 
-        $this->throwIfUnrecognisedOptionExists($options);
+        $colourClasses = $this->getColourClasses($options['colour'], $options['hover']);
+        $extraClasses = $this->getExtraClasses($options['classes']);
 
-        $iconFilepath = $this->findSvgFilepath($options['icon']);
-        $rawSvgMarkup = $this->getSvgMarkup($iconFilepath);
-        $cleanSvgMarkup = $this->cleanSvgMarkup($rawSvgMarkup);
+        $svg = $this->addClassesToSvg($svg, trim($colourClasses.' '.$extraClasses));
+        $svg = $this->addTitleToSvgIfNotNull($svg, $options['title']);
+        $svg = $this->setSvgHeightAndWidth($svg, $options['size']);
 
-        $mainPallete = $this->getPallete($options['colour']);
+        return $svg;
+    }
 
-        $colourClasses = "{$mainPallete['stroke']} {$mainPallete['fill']}";
+    private function getExtraClasses(array $extraClasses): string
+    {
+        return implode(' ', $extraClasses);
+    }
 
-        if (null !== $options['hover']) {
-            $hoverPallete = $this->getPallete($options['hover']);
-            $colourClasses .= " cursor-pointer hover:{$hoverPallete['stroke']} hover:{$hoverPallete['fill']} group-hover:{$hoverPallete['stroke']} group-hover:{$hoverPallete['fill']}";
-        }
-
-        $xml = new \SimpleXMLElement($cleanSvgMarkup);
-        $xml = $this->addAttributeToXmlElement($xml, 'class', $colourClasses);
-        $markup = $this->removeXMLDeclaration($xml->saveXML());
-
-        if ($this->isNonEmptyString($options['title']))
-            $markup = $this->addTitleToMarkup($markup, $options['title']);
-
-        if ($options['size'] < 0)
-            throw new \InvalidArgumentException('Size must not be negative');
-
-        if (!is_int($options['size']))
-            throw new \TypeError('Size value must be an integer');
-
-        $markup = $this->setSize($markup, $options['size']);
-        $markup = $this->removeBlackStrokeAttributes($markup);
-        $markup = $this->removeBlackFillAttributes($markup);
-
-        return $markup;
+    private function getMergedOptions(array $userOptions): array
+    {
+        $this->throwIfUnrecognisedOptionExists($userOptions);
+        return $this->mergeUserOptionsWithDefaults($userOptions);
     }
 
     private function mergeUserOptionsWithDefaults(array $userOptions): array
@@ -129,6 +120,15 @@ final class IconExtension extends AbstractExtension
         }
     }
 
+    private function getSanitisedIconSvg(string $iconName): string
+    {
+        $iconFilepath = $this->findSvgFilepath($iconName);
+        $rawSvgMarkup = $this->getSvgMarkup($iconFilepath);
+        $cleanSvgMarkup = $this->removeExistingTitleElement($rawSvgMarkup);
+        $cleanSvgMarkup = $this->removeBlackStrokeAttributes($cleanSvgMarkup);
+        return $this->removeBlackFillAttributes($cleanSvgMarkup);
+    }
+
     private function findSvgFilepath(string $iconName): string
     {
         foreach ($this->directories as $directory) {
@@ -146,9 +146,32 @@ final class IconExtension extends AbstractExtension
         return file_get_contents($filepath);
     }
 
-    private function cleanSvgMarkup(string $markup): string
+    private function removeExistingTitleElement(string $svg): string
     {
-        return preg_replace('/<title>.*<\/title>/', '', $markup);
+        return preg_replace('/<title>.*<\/title>/', '', $svg);
+    }
+
+    private function removeBlackStrokeAttributes(string $content): string
+    {
+        return preg_replace('/stroke(=|:)"?\s*(#0{6}|#000|rgb\(\s*0,\s*0,\s*0\s*\)|black)\s*"?/', '', $content);
+    }
+
+    private function removeBlackFillAttributes(string $content): string
+    {
+        return preg_replace('/fill(=|:)"?\s*(#0{6}|#000|rgb\(\s*0,\s*0,\s*0\s*\)|black)\s*"?/', '', $content);
+    }
+
+    private function getColourClasses(string $primaryColour, ?string $hoverColour): string
+    {
+        $mainPallete = $this->getPallete($primaryColour);
+        $colourClasses = "{$mainPallete['stroke']} {$mainPallete['fill']}";
+
+        if (null !== $hoverColour) {
+            $hoverPallete = $this->getPallete($hoverColour);
+            $colourClasses .= " cursor-pointer {$hoverPallete['stroke-hover']} {$hoverPallete['fill-hover']} {$hoverPallete['stroke-group-hover']} {$hoverPallete['fill-group-hover']}";
+        }
+
+        return $colourClasses;
     }
 
     private function getPallete(string $palleteName): array
@@ -159,36 +182,19 @@ final class IconExtension extends AbstractExtension
         throw new PalleteNotFound("The pallete '$palleteName' was not found!");
     }
 
-    private function isNonEmptyString(mixed $title): bool
+    private function addClassesToSvg(string $svg, string $classes): string
     {
-        if (!is_string($title) && null !== $title)
-            throw new \TypeError('Title must be a string!');
-
-        if ('' === $title)
-            throw new \InvalidArgumentException('Title string must not be empty!');
-
-        return true;
+        $xml = new \SimpleXMLElement($svg);
+        $xml = $this->addAttributeToXmlElement($xml, 'class', $classes);
+        return $this->removeXMLDeclaration($xml->saveXML());
     }
 
-    private function addTitleToMarkup(string $markup, ?string $title): string
+    private function addTitleToSvgIfNotNull(string $svg, ?string $title): string
     {
-        if (null === $title)
-            return $markup;
+        if (null === $title) return $svg;
+        $this->throwIfTitleIsEmpty($title);
 
-        return preg_replace('/(<svg(.|\n)*?>\n?)/', "$1<title>$title</title>", $markup);
-    }
-
-    private function setSize(string $content, int $size): string
-    {
-        $svgAsXmlElement = new \SimpleXMLElement($content);
-        $svgAsXmlElement = $this->addAttributeToXmlElement($svgAsXmlElement, 'width', $size);
-        $svgAsXmlElement = $this->addAttributeToXmlElement($svgAsXmlElement, 'height', $size);
-        return $this->removeXMLDeclaration($svgAsXmlElement->saveXML());
-    }
-
-    private function removeXMLDeclaration(string $content): string
-    {
-        return trim(preg_replace('/<\?xml.*\?>/', '', $content));
+        return preg_replace('/(<svg(.|\n)*?>\n?)/', "$1<title>$title</title>", $svg);
     }
 
     private function addAttributeToXmlElement(\SimpleXMLElement $xml, string $attrName, mixed $attrValue): \SimpleXMLElement
@@ -202,14 +208,30 @@ final class IconExtension extends AbstractExtension
         return $xml;
     }
 
-    private function removeBlackStrokeAttributes(string $content): string
+    private function removeXMLDeclaration(string $content): string
     {
-        return preg_replace('/stroke(=|:)"?\s*(#0{6}|#000|rgb\(\s*0,\s*0,\s*0\s*\)|black)\s*"?/', '', $content);
+        return trim(preg_replace('/<\?xml.*\?>/', '', $content));
     }
 
-    private function removeBlackFillAttributes(string $content): string
+    private function throwIfTitleIsEmpty(string $title): void
     {
-        return preg_replace('/fill(=|:)"?\s*(#0{6}|#000|rgb\(\s*0,\s*0,\s*0\s*\)|black)\s*"?/', '', $content);
+        if ('' === $title)
+            throw new \InvalidArgumentException('Title string must not be empty!');
+    }
+
+    private function setSvgHeightAndWidth(string $content, int $size): string
+    {
+        $this->throwIfSizeIsNegative($size);
+        $svgAsXmlElement = new \SimpleXMLElement($content);
+        $svgAsXmlElement = $this->addAttributeToXmlElement($svgAsXmlElement, 'width', $size);
+        $svgAsXmlElement = $this->addAttributeToXmlElement($svgAsXmlElement, 'height', $size);
+        return $this->removeXMLDeclaration($svgAsXmlElement->saveXML());
+    }
+
+    private function throwIfSizeIsNegative(int $size): void
+    {
+        if ($size < 0)
+            throw new \InvalidArgumentException('Size must not be negative');
     }
 }
 

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]);
-
     }
 }