README

php-svg-optimizer is a lightweight PHP library designed to optimize, minify, and sanitize SVG files. It applies various transformations and cleanup operations while ensuring compliance with SVG 2.0 specifications. The resulting SVGs remain visually identical to the original but are smaller, cleaner, and safer.

Versions & Dependencies

Version	PHP	Documentation
^8.3	^8.3	current

Requirements

ext-dom: Required PHP extension for XML handling.
ext-libxml: Required PHP extension for XML error handling.
ext-mbstring: Required PHP extension for multibyte string handling.

Installation

To install the library, run:

composer require mathiasreker/php-svg-optimizer

Using the Library

You can use this library in two main ways:

Command-Line Interface (CLI): Run the optimizer directly from your terminal to process SVG files quickly. This is ideal for batch processing or integrating into build scripts.
Standalone Package: Use it as a PHP package in your project to optimize SVGs programmatically. This allows you to integrate SVG optimization directly into your application workflow or custom scripts.

CLI tool

vendor/bin/svg-optimizer [options] process <path1> <path2> ...

Options:
-h , --help               Display help for the command.
-c , --config             Path to a JSON file with custom optimization rules. If not provided, all default optimizations will be applied.
-d , --dry-run            Only calculate potential savings without modifying the files.
-r , --allow-risky        Explicitly enables risky rules, allowing them to be applied.
-a , --with-all-rules     Enable all non-risky rules. Use --allow-risky to include risky rules as well.
-q , --quiet              Suppress all output except errors.
-v , --version            Display the version of the library.

Commands:
Process                   Provide a list of directories or files to process.

Examples:

vendor/bin/svg-optimizer --dry-run --with--all-rules process /path/to/svgs
vendor/bin/svg-optimizer --config=config.json process /path/to/file.svg
vendor/bin/svg-optimizer --config='{"removeUnsafeElements": true}' --allow-risky process /path/to/file.svg
vendor/bin/svg-optimizer --quiet --with--all-rules process /path/to/file.svg
vendor/bin/svg-optimizer --with-all-rules process /path/to/file.svg

Config file example:

{
    "convertColorsToHex": true,
    "convertCssClassesToAttributes": true,
    "convertEmptyTagsToSelfClosing": true,
    "convertInlineStylesToAttributes": true,
    "fixAttributeNames": true,
    "flattenGroups": true,
    "minifySvgCoordinates": true,
    "minifyTransformations": true,
    "removeAriaAndRole": true,
    "removeComments": true,
    "removeDataAttributes": true,
    "removeDefaultAttributes": true,
    "removeDeprecatedAttributes": true,
    "removeDoctype": true,
    "removeDuplicateElements": true,
    "removeEmptyAttributes": true,
    "removeEmptyGroups": true,
    "removeEmptyTextElements": true,
    "removeEnableBackgroundAttribute": true,
    "removeInkscapeFootprints": true,
    "removeInvisibleCharacters": true,
    "removeMetadata": true,
    "removeTitleAndDesc": true,
    "removeUnnecessaryWhitespace": true,
    "removeUnsafeElements": false,
    "removeUnusedMasks": true,
    "removeUnusedNamespaces": true,
    "removeWidthHeightAttributes": false,
    "sortAttributes": true
}

Example Workflow for GitHub Actions

name: Optimize SVGs

on: [push, pull_request]

jobs:
  run-optimizer:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v6
      - uses: shivammathur/setup-php@v2
        with:
          php-version: '8.5'
      - run: composer install --no-dev --optimize-autoloader --no-interaction --no-progress
      - run: php vendor/bin/svg-optimizer -a -q process /path/to/svgs

Package

It is recommended to catch exceptions when using this library. Doing so ensures that your application can handle unexpected input gracefully and avoid unintended crashes.

Example specifying rules

<?php

declare(strict_types=1);

require_once __DIR__ . '/vendor/autoload.php';

use MathiasReker\PhpSvgOptimizer\Service\Facade\SvgOptimizerFacade;

try {
    $svgOptimizer = SvgOptimizerFacade::fromFile('path/to/source.svg')
        ->withRules(
            convertColorsToHex: true,
            convertCssClassesToAttributes: true,
            convertEmptyTagsToSelfClosing: true,
            convertInlineStylesToAttributes: true,
            fixAttributeNames: true,
            flattenGroups: true,
            minifySvgCoordinates: true,
            minifyTransformations: true,
            removeAriaAndRole: true,
            removeComments: true,
            removeDataAttributes: true,
            removeDefaultAttributes: true,
            removeDeprecatedAttributes: true,
            removeDoctype: true,
            removeDuplicateElements: true,
            removeEmptyAttributes: true,
            removeEmptyGroups: true,
            removeEmptyTextElements: true,
            removeEnableBackgroundAttribute: true,
            removeInkscapeFootprints: true,
            removeInvisibleCharacters: true,
            removeMetadata: true,
            removeTitleAndDesc: true,
            removeUnnecessaryWhitespace: true,
            removeUnsafeElements: false,
            removeUnusedMasks: true,
            removeUnusedNamespaces: true,
            removeWidthHeightAttributes: false,
            sortAttributes: true,
        )
        ->optimize()
        ->saveToFile('path/to/output.svg');
} catch (\Exception $exception) {
    echo $exception->getMessage();
}

Example parsing from a file and saving to a file using default rules

<?php

declare(strict_types=1);

require_once __DIR__ . '/vendor/autoload.php';

use MathiasReker\PhpSvgOptimizer\Service\Facade\SvgOptimizerFacade;

try {
    $svgOptimizer = SvgOptimizerFacade::fromFile('path/to/source.svg')
        ->withAllRules()
        ->optimize()
        ->saveToFile('path/to/output.svg');

    $metaData = $svgOptimizer->getMetaData();

    echo sprintf('Optimized size: %d bytes%s', $metaData->getOptimizedSize(), \PHP_EOL);
    echo sprintf('Original size: %d bytes%s', $metaData->getOriginalSize(), \PHP_EOL);
    echo sprintf('Size reduction: %d bytes%s', $metaData->getSavedBytes(), \PHP_EOL);
    echo sprintf('Reduction percentage: %s %%%s', $metaData->getSavedPercentage(), \PHP_EOL);
    echo sprintf('Processing time: %s seconds%s', $metaData->getOptimizationTime(), \PHP_EOL);
} catch (\Exception $exception) {
    echo $exception->getMessage();
}

Example parsing from a file and returning the content using default rules

<?php

declare(strict_types=1);

require_once __DIR__ . '/vendor/autoload.php';

use MathiasReker\PhpSvgOptimizer\Service\Facade\SvgOptimizerFacade;

try {
    $svgOptimizer = SvgOptimizerFacade::fromFile('path/to/source.svg')
        ->withAllRules()
        ->optimize();

    echo sprintf('Get content: ', $svgOptimizer->getContent(), \PHP_EOL);

    $metaData = $svgOptimizer->getMetaData();

    echo sprintf('Optimized size: %d bytes%s', $metaData->getOptimizedSize(), \PHP_EOL);
    echo sprintf('Original size: %d bytes%s', $metaData->getOriginalSize(), \PHP_EOL);
    echo sprintf('Size reduction: %d bytes%s', $metaData->getSavedBytes(), \PHP_EOL);
    echo sprintf('Reduction percentage: %s %%%s', $metaData->getSavedPercentage(), \PHP_EOL);
    echo sprintf('Processing time: %s seconds%s', $metaData->getOptimizationTime(), \PHP_EOL);
} catch (\Exception $exception) {
    echo $exception->getMessage();
}

Example parsing from a string and returning the content using default rules

<?php

declare(strict_types=1);

require_once __DIR__ . '/vendor/autoload.php';

use MathiasReker\PhpSvgOptimizer\Service\Facade\SvgOptimizerFacade;

try {
    $svgOptimizer = SvgOptimizerFacade::fromString('<svg>...</svg>')
        ->withAllRules()
        ->optimize();

    echo sprintf('Content: ', $svgOptimizer->getContent(), \PHP_EOL);

    $metaData = $svgOptimizer->getMetaData();

    echo sprintf('Optimized size: %d bytes%s', $metaData->getOptimizedSize(), \PHP_EOL);
    echo sprintf('Original size: %d bytes%s', $metaData->getOriginalSize(), \PHP_EOL);
    echo sprintf('Size reduction: %d bytes%s', $metaData->getSavedBytes(), \PHP_EOL);
    echo sprintf('Reduction percentage: %s %%%s', $metaData->getSavedPercentage(), \PHP_EOL);
    echo sprintf('Processing time: %s seconds%s', $metaData->getOptimizationTime(), \PHP_EOL);
} catch (\Exception $exception) {
    echo $exception->getMessage();
}

Example applying risky rules

<?php

declare(strict_types=1);

require_once __DIR__ . '/vendor/autoload.php';

use MathiasReker\PhpSvgOptimizer\Service\Facade\SvgOptimizerFacade;

try {
    $svgOptimizer = SvgOptimizerFacade::fromFile('path/to/source.svg')
        ->withRules(
            removeWidthHeightAttributes: true,
            removeUnsafeElements: true,
        )
        ->allowRisky()
        ->optimize()
        ->saveToFile('path/to/output.svg');

    echo sprintf('Content: ', $svgOptimizer->getContent(), \PHP_EOL);

    $metaData = $svgOptimizer->getMetaData();

    echo sprintf('Optimized size: %d bytes%s', $metaData->getOptimizedSize(), \PHP_EOL);
    echo sprintf('Original size: %d bytes%s', $metaData->getOriginalSize(), \PHP_EOL);
    echo sprintf('Size reduction: %d bytes%s', $metaData->getSavedBytes(), \PHP_EOL);
    echo sprintf('Reduction percentage: %s %%%s', $metaData->getSavedPercentage(), \PHP_EOL);
    echo sprintf('Processing time: %s seconds%s', $metaData->getOptimizationTime(), \PHP_EOL);
} catch (\Exception $exception) {
    echo $exception->getMessage();
}

Documentation

SvgOptimizerFacade

Static factory method to create SvgOptimizerFacade from a file path.

$svgOptimizer = SvgOptimizerFacade::fromFile('path/to/source.svg');

Static factory method to create SvgOptimizerFacade from a string.

$svgOptimizer = SvgOptimizerFacade::fromString('<svg>...</svg>');

`withRules`

Configure which SVG optimization rules to apply. The method accepts boolean parameters that determine whether specific rules should be enabled or disabled.

$svgOptimizer->withRules();

Parameters

Below is a detailed description of each available optimization rule. Each rule focuses on either reducing file size, improving consistency, modernizing SVG output, or increasing security. Some rules are marked risky, meaning they may alter behavior or semantics in certain use cases and should be enabled with care.

`convertColorsToHex`

Normalizes all color definitions to hexadecimal notation. Color values expressed as functional formats (such as rgb() or rgba()) are converted to their hexadecimal equivalents, using shorthand notation where possible. This improves consistency across the SVG, reduces textual variation, and can slightly decrease file size while maintaining visual fidelity.

$svgOptimizer->convertColorsToHex();

`convertCssClassesToAttributes`

Replaces CSS class-based styling with equivalent inline SVG attributes on each affected element.

$svgOptimizer->convertCssClassesToAttributes();

`convertEmptyTagsToSelfClosing`

Converts elements without child nodes into self-closing tags. This simplifies the markup structure and reduces unnecessary characters, resulting in cleaner and more compact SVG output without affecting rendering.

$svgOptimizer->convertEmptyTagsToSelfClosing();

`convertInlineStylesToAttributes`

Extracts individual style declarations from inline style attributes and converts them into their corresponding SVG presentation attributes. This improves compatibility with SVG renderers and tooling that do not fully support CSS styling, and makes attribute-level optimizations more effective downstream.

$svgOptimizer->convertInlineStylesToAttributes();

`fixAttributeNames` (risky)

Normalizes SVG attribute names to their canonical, specification-compliant casing and hyphenation. Attribute names are matched against a known set of valid SVG attributes and corrected where case differences or missing hyphens occur. This improves standards compliance, avoids duplicate or conflicting attributes, and ensures consistent output across different SVG sources and editors.

$svgOptimizer->fixAttributeNames();

`flattenGroups`

Removes unnecessary nested <g> (group) elements by moving their child elements directly into the parent group. This reduces DOM depth, simplifies the SVG structure, and can marginally reduce file size while preserving visual output.

$svgOptimizer->flattenGroups();

`minifySvgCoordinates`

Reduces numeric precision in coordinate values and other numeric attributes where excessive precision is unnecessary. Trailing zeros and redundant decimal places are removed without introducing visible rendering differences, leading to smaller file sizes and cleaner markup.

$svgOptimizer->minifySvgCoordinates();

`minifyTransformations`

Optimizes transform attributes by simplifying expressions, removing redundant transformations, and normalizing transform syntax. This reduces attribute length and improves parsing efficiency while maintaining equivalent geometric transformations.

$svgOptimizer->minifyTransformations();

`removeAriaAndRole`

Removes ARIA (aria-*) and role attributes that are often unnecessary in static or decorative SVGs. This reduces file size and avoids redundant accessibility metadata when SVGs are not intended to be interactive or exposed to assistive technologies.

$svgOptimizer->removeAriaAndRole();

`removeComments`

Deletes all non-essential XML comments from the SVG document, excluding legally required comments if applicable. This eliminates developer notes and editor artifacts that do not affect rendering, reducing file size.

$svgOptimizer->removeComments();

`removeDataAttributes` (risky)

Removes all data-* attributes from elements. These attributes are often used for application-specific metadata or scripting hooks; removing them can significantly reduce file size but may break integrations or runtime behavior that relies on them.

$svgOptimizer->removeDataAttributes();

`removeDefaultAttributes`

Eliminates attributes whose values match SVG specification defaults and therefore do not affect rendering. By omitting redundant information, this rule reduces clutter and minimizes output size while preserving visual correctness.

$svgOptimizer->removeDefaultAttributes();

`removeDeprecatedAttributes`

Removes attributes that are deprecated or obsolete according to modern SVG specifications. This helps modernize SVG output, improves forward compatibility, and reduces reliance on legacy behavior.

$svgOptimizer->removeDeprecatedAttributes();

`removeDoctype`

Removes the <!DOCTYPE> declaration from the SVG document. This is typically unnecessary for inline SVGs or SVGs embedded in HTML and slightly reduces file size.

$svgOptimizer->removeDoctype();

`removeDuplicateElements`

Detects and removes identical duplicate elements that do not contribute additional visual output. This reduces redundancy in the SVG structure and helps minimize file size without altering appearance.

$svgOptimizer->removeDuplicateElements();

`removeEmptyAttributes`

Removes attributes that have empty values. Such attributes add noise to the markup without affecting rendering and can safely be removed to produce cleaner output.

$svgOptimizer->removeEmptyAttributes();

`removeEmptyGroups`

Deletes <g> elements that do not contain any child elements. This simplifies the DOM tree and removes unnecessary structural nodes.

$svgOptimizer->removeEmptyGroups();

`removeEmptyTextElements`

Removes <text> elements that contain no textual content. These elements have no visual impact and can safely be eliminated to reduce file size.

$svgOptimizer->removeEmptyTextElements();

`removeEnableBackgroundAttribute` (risky)

Removes the enable-background attribute from the root <svg> element. While often unnecessary, this attribute can affect certain filters or compositing behaviors. Removing it may improve performance and reduce size but could alter rendering in advanced use cases.

$svgOptimizer->removeEnableBackgroundAttribute();

`removeInkscapeFootprints`

Strips Inkscape-specific metadata, attributes, and elements that are added during export but are not required for rendering. This cleans up SVGs generated by Inkscape and significantly reduces noise and file size.

$svgOptimizer->removeInkscapeFootprints();

`removeInvisibleCharacters`

Removes invisible or non-printable Unicode characters, such as zero-width spaces, that may inadvertently appear in SVG files. This prevents subtle rendering or parsing issues and ensures clean textual content.

$svgOptimizer->removeInvisibleCharacters();

`removeMetadata`

Deletes <metadata> elements, which often contain authoring information, editor data, or descriptive metadata not required for rendering. This reduces file size and removes non-essential content.

$svgOptimizer->removeMetadata();

`removeTitleAndDesc`

Removes <title> and <desc> elements. While these elements provide accessibility and descriptive information, they are optional in many contexts. Removing them reduces file size but should only be done when accessibility metadata is not required.

$svgOptimizer->removeTitleAndDesc();

`removeUnnecessaryWhitespace`

Collapses or removes redundant whitespace such as extra spaces, tabs, and line breaks. This produces more compact SVG output while preserving semantic structure and rendering.

$svgOptimizer->removeUnnecessaryWhitespace();

`removeUnusedNamespaces`

Removes XML namespace declarations that are never referenced within the document. This cleans up the root element, reduces verbosity, and improves readability.

$svgOptimizer->removeUnusedNamespaces();

`removeWidthHeightAttributes` (risky)

Removes the width and height attributes from the root <svg> element, relying solely on the viewBox for scaling. This enables responsive resizing but may break layouts that depend on fixed dimensions.

$svgOptimizer->removeWidthHeightAttributes();

`removeUnsafeElements` (risky)

Sanitizes SVG content by removing elements and attributes that can pose security risks. This includes scripting capabilities, external resource references, and interactive event handlers. The rule is intended for use with untrusted SVG input and helps prevent script execution, data exfiltration, and other attack vectors when embedding SVGs in web applications.

$svgOptimizer->removeUnsafeElements();

`removeUnusedMasks`

Removes <mask> elements that are defined but never referenced by any element in the document. This reduces file size and eliminates unused definitions without affecting rendering.

$svgOptimizer->removeUnusedMasks();

`sortAttributes`

Sorts element attributes alphabetically. This improves consistency, makes diffs easier to read in version control systems, and results in more deterministic SVG output across optimization runs.

$svgOptimizer->sortAttributes();

`withRules`

Below you see the default configuration. You can configure each rule individually by passing the desired values to it:

$svgOptimizer->withRules(
    convertColorsToHex: true,
    convertCssClassesToAttributes: true,
    convertEmptyTagsToSelfClosing: true,
    convertInlineStylesToAttributes: true,
    fixAttributeNames: true,
    flattenGroups: true,
    minifySvgCoordinates: true,
    minifyTransformations: true,
    removeAriaAndRole: true,
    removeComments: true,
    removeDefaultAttributes: true,
    removeDeprecatedAttributes: true,
    removeDoctype: true,
    removeDuplicateElements: true,
    removeEmptyAttributes: true,
    removeEmptyGroups: true,
    removeEmptyTextElements: true,
    removeEnableBackgroundAttribute: true,
    removeInkscapeFootprints: true,
    removeInvisibleCharacters: true,
    removeMetadata: true,
    removeTitleAndDesc: true,
    removeUnnecessaryWhitespace: true,
    removeUnsafeElements: false,
    removeUnusedMasks: true,
    removeUnusedNamespaces: true,
    removeWidthHeightAttributes: false,
    sortAttributes: true,
);

`withAllRules`

Enable all rules. Risky rules remain disabled unless allowRisky() is explicitly set.

$svgOptimizer->withAllRules();

`allowRisky`

By default, risky rules are not applied even if you add them unless explicitly allowed.

$svgOptimizer->allowRisky();

`optimize`

Finalizes the optimization process and generates the optimized SVG file.

$svgOptimizer->optimize();

`saveToFile`

Saves the optimized SVG file to the specified path.

$svgOptimizer->saveToFile('path/to/output.svg');

`getContent`

Returns the optimized SVG content.

$svgOptimizer->getContent();

`getOptimizedSize`

Returns the size of the optimized SVG file.

$svgOptimizer->getMetaData()->getOptimizedSize();

`getOriginalSize`

Returns the size of the original SVG file.

$svgOptimizer->getMetaData()->getOriginalSize();

`getSavedBytes`

Returns the number of bytes saved by the optimization process.

$svgOptimizer->getMetaData()->getSavedBytes();

`getSavedPercentage`

Returns the percentage of bytes saved by the optimization process.

$svgOptimizer->getMetaData()->getSavedPercentage();

`getOptimizedTime`

Returns the time taken to optimize the SVG file, in seconds.

$svgOptimizer->getMetaData()->getOptimizedTime();

Roadmap

For a complete list of proposed features and known issues, see the open issues.

Contributing

We welcome all contributions! If you have ideas for improvements, feel free to fork the repository and submit a pull request. You can also open an issue. If you find this project helpful, don’t forget to give it a star!

Library Structure and Contribution Guide

The library implements the Strategy Pattern, where strategies are encapsulated as "rules" located in the /src/Service/Rule directory.

Adding a New Rule

1. Create the Rule

Create a new final readonly class in the /src/Service/Rule directory and implement the SvgOptimizerRuleInterface. This interface will define the logic for your rule.

2. Write Tests

Write comprehensive unit tests for your rule in the /tests/Unit/Service/Rule directory. Ensure the tests cover various scenarios to verify the correct behavior and edge cases for your rule.

3. Integrate the Rule

Add your rule to the rule enum in /src/Type/Rule.php.
Register the rule in the SVG optimizer builder located at /src/Service/Facade/SvgOptimizerFacade.php.

4. Update Documentation

Document the functionality and purpose of your rule in the README.md to ensure users understand its behavior and usage.

Docker

To use the project with Docker, you can start the container using:

docker-compose up -d

Then, access the container:

docker exec -it php-svg-optimizer bash

Tools

Run static analysis:

composer analyze:all

Run tests:

composer test

Fix code style:

composer lint:all

Build:

composer build:all

License

This project is licensed under the MIT License. See the LICENSE file for more information.

Disclaimer

Use of this tool is entirely at your own risk. The authors and maintainers make no warranties regarding the correctness, reliability, or suitability of the tool for any particular purpose. Users are solely responsible for verifying the results and ensuring that files are properly backed up before use. It is strongly recommended to test the tool on non-critical files and confirm compatibility with your workflow prior to deploying it in any production environment.

mathiasreker / php-svg-optimizer

Maintainers

Details

README

Versions & Dependencies

Requirements

Installation

Using the Library

CLI tool

Examples:

Config file example:

Example Workflow for GitHub Actions

Package

Example specifying rules

Example parsing from a file and saving to a file using default rules

Example parsing from a file and returning the content using default rules

Example parsing from a string and returning the content using default rules

Example applying risky rules

Documentation

SvgOptimizerFacade

withRules

Parameters

convertColorsToHex

convertCssClassesToAttributes

convertEmptyTagsToSelfClosing

convertInlineStylesToAttributes

fixAttributeNames (risky)

flattenGroups

minifySvgCoordinates

minifyTransformations

removeAriaAndRole

removeComments

removeDataAttributes (risky)

removeDefaultAttributes

removeDeprecatedAttributes

removeDoctype

removeDuplicateElements

removeEmptyAttributes

removeEmptyGroups

removeEmptyTextElements

removeEnableBackgroundAttribute (risky)

removeInkscapeFootprints

removeInvisibleCharacters

removeMetadata

removeTitleAndDesc

removeUnnecessaryWhitespace

removeUnusedNamespaces

removeWidthHeightAttributes (risky)

removeUnsafeElements (risky)

removeUnusedMasks

sortAttributes

withRules

withAllRules

allowRisky

optimize

saveToFile

getContent

getOptimizedSize

getOriginalSize

getSavedBytes

getSavedPercentage

getOptimizedTime

Roadmap

Contributing

Library Structure and Contribution Guide

Adding a New Rule

1. Create the Rule

2. Write Tests

3. Integrate the Rule

4. Update Documentation

Docker

Tools

License

Disclaimer

`withRules`

`convertColorsToHex`

`convertCssClassesToAttributes`

`convertEmptyTagsToSelfClosing`

`convertInlineStylesToAttributes`

`fixAttributeNames` (risky)

`flattenGroups`

`minifySvgCoordinates`

`minifyTransformations`

`removeAriaAndRole`

`removeComments`

`removeDataAttributes` (risky)

`removeDefaultAttributes`

`removeDeprecatedAttributes`

`removeDoctype`

`removeDuplicateElements`

`removeEmptyAttributes`

`removeEmptyGroups`

`removeEmptyTextElements`

`removeEnableBackgroundAttribute` (risky)

`removeInkscapeFootprints`

`removeInvisibleCharacters`

`removeMetadata`

`removeTitleAndDesc`

`removeUnnecessaryWhitespace`

`removeUnusedNamespaces`

`removeWidthHeightAttributes` (risky)

`removeUnsafeElements` (risky)

`removeUnusedMasks`

`sortAttributes`

`withRules`

`withAllRules`

`allowRisky`

`optimize`

`saveToFile`

`getContent`

`getOptimizedSize`

`getOriginalSize`

`getSavedBytes`

`getSavedPercentage`

`getOptimizedTime`