PHPackages                             restruct/silverstripe-svg-images - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Image & Media](/categories/media)
4. /
5. restruct/silverstripe-svg-images

ActiveSilverstripe-vendormodule[Image & Media](/categories/media)

restruct/silverstripe-svg-images
================================

SVG Image support for Silverstripe with real manipulation and sanitization

2.1.0(5mo ago)154.7k↑117.9%20[2 issues](https://github.com/restruct/silverstripe-svg-images/issues)MITPHP

Since Apr 15Pushed 5mo ago5 watchersCompare

[ Source](https://github.com/restruct/silverstripe-svg-images)[ Packagist](https://packagist.org/packages/restruct/silverstripe-svg-images)[ Docs](https://github.com/restruct/silverstripe-svg-images)[ RSS](/packages/restruct-silverstripe-svg-images/feed)WikiDiscussions main Synced 2d ago

READMEChangelogDependencies (3)Versions (13)Used By (0)

SVG Image support for SilverStripe 6 (assets/uploads)
=====================================================

[](#svg-image-support-for-silverstripe-6-assetsuploads)

This module provides comprehensive SVG support in SilverStripe's asset management system, including:

- **CMS thumbnail/preview support** for SVG files in AssetAdmin
- **Real SVG manipulation** (resize, crop) that modifies viewBox/dimensions while preserving vectors
- **SVG sanitization** on upload to remove potentially dangerous content
- **Dimension parsing** from SVG viewBox/width/height attributes
- **Automatic class handling** for SVGs uploaded through Image relations

How it works
------------

[](#how-it-works)

The module configures SilverStripe to use the `SVGImage` class for `.svg` files via `class_for_file_extension`. This happens automatically for files uploaded through AssetAdmin.

### SVG uploads through Image relations

[](#svg-uploads-through-image-relations)

When uploading SVGs through relation fields (`has_one`, `has_many`, or `many_many` to `Image`), SilverStripe's ORM enforces the relation's class type, ignoring the `class_for_file_extension` config. This module includes `SVGImageExtension` which automatically corrects the `ClassName` to `SVGImage` after the file is written.

This happens transparently - no configuration needed.

### SVG Manipulation

[](#svg-manipulation)

Unlike raster images, SVG manipulation preserves the vector format by modifying viewBox and width/height attributes. The module uses [contao/imagine-svg](https://github.com/contao/imagine-svg) for manipulation.

Supported operations:

- `Fit($width, $height)` - Resize to fit within bounds, maintaining aspect ratio
- `FitMax($width, $height)` - Same as Fit, but only if image is larger
- `Fill($width, $height)` - Crop and resize to fill exact dimensions
- `FillMax($width, $height)` - Same as Fill, but only if image is larger
- `Pad($width, $height)` - Fit within bounds and add transparent padding to reach exact dimensions
- `ScaleWidth($width)` - Scale to specific width, maintaining aspect ratio
- `ScaleHeight($height)` - Scale to specific height, maintaining aspect ratio
- `CropRegion($x, $y, $width, $height)` - Crop to specific region

Manipulated SVGs are stored as variants (just like raster image variants), so they're cached and only generated once.

To disable manipulation and return original SVGs unchanged (legacy behavior):

```
Restruct\Silverstripe\SVG\SVGImage:
  enable_svg_manipulation: false
```

### SVG Sanitization

[](#svg-sanitization)

SVG files are automatically sanitized on upload using [enshrined/svg-sanitize](https://github.com/enshrined/svg-sanitize). This removes potentially dangerous content like:

- JavaScript/event handlers
- External references (can be disabled)
- PHP tags
- Other XSS vectors

Configuration options:

```
Restruct\Silverstripe\SVG\SVGImage:
  # Disable sanitization (not recommended)
  sanitize_on_upload: false

  # Keep remote references (disabled by default for security)
  sanitize_remove_remote_references: false
```

Migrating existing SVG files
----------------------------

[](#migrating-existing-svg-files)

If you have existing SVG files in your database that were uploaded before installing this module, enable auto-migration:

```
Restruct\Silverstripe\SVG\SVGImage:
  auto_migrate_svg_class: true
```

Then run `dev/build`. The migration will update the `ClassName` in `File`, `File_Live`, and `File_Versions` tables (including files with NULL or empty ClassName).

> **Note:** The migration runs via `requireDefaultRecords()`. If you use `dev/build --no-populate`, the migration will be skipped. Run a normal `dev/build` without `--no-populate` to trigger it.

Usage in templates
------------------

[](#usage-in-templates)

```

```

### Inline SVG

[](#inline-svg)

```

{$Image.SVG_RAW_Inline}

  {$Image.SVG_RAW_Inline}

```

### Inline SVG with color manipulation

[](#inline-svg-with-color-manipulation)

If you need to manipulate SVG colors or add CSS classes for inline SVGs, consider [stevie-mayhew/silverstripe-svg](https://github.com/stevie-mayhew/silverstripe-svg). You can use it alongside this module by passing the asset path:

```
{$SVG($Image.Filename).fill('#FF9933').extraClass('my-icon')}
```

SVG Security
------------

[](#svg-security)

SVGs can expose attack vectors comparable to HTML/JS. This module mitigates risks through automatic sanitization, but you should still:

- Only accept SVG uploads from trusted users
- Use `` tags rather than inline SVG when possible (provides more browser security)
- Keep the sanitization enabled (default)

For more information on SVG security risks, see [OWASP SVG Security Cheat Sheet](https://cheatsheetseries.owasp.org/cheatsheets/SVG_Security_Cheat_Sheet.html).

Configuration reference
-----------------------

[](#configuration-reference)

```
Restruct\Silverstripe\SVG\SVGImage:
  # Enable real SVG manipulation (resize/crop)
  enable_svg_manipulation: true

  # Sanitize SVGs on upload
  sanitize_on_upload: true

  # Remove remote references during sanitization
  sanitize_remove_remote_references: true

  # Auto-migrate existing SVG files on dev/build
  auto_migrate_svg_class: false
```

Development Tools
-----------------

[](#development-tools)

### SVG vs PNG Comparison Tool

[](#svg-vs-png-comparison-tool)

A visual comparison tool is available at `/dev/svg-compare` to verify that SVG manipulations behave consistently with PNG manipulations. The tool:

- Compares all manipulation methods (Fit, Fill, Pad, Scale, etc.) side-by-side
- Tests both published and draft/protected assets
- Includes bundled test images or accepts custom image IDs

### Clear SVG Variants Task

[](#clear-svg-variants-task)

To clear all generated SVG variant files (useful after upgrading or when manipulation settings change):

```
# Dry run - shows what would be deleted
vendor/bin/sake tasks:ClearSVGVariantsTask

# Actually delete variants
vendor/bin/sake tasks:ClearSVGVariantsTask --confirm

# Verbose output
vendor/bin/sake tasks:ClearSVGVariantsTask --confirm --verbose
```

Variants will be regenerated on next request using the current manipulation settings.

Technical Documentation
-----------------------

[](#technical-documentation)

For implementation details, architecture decisions, and explanations of why things are implemented in specific ways, see [TECHNICAL.md](TECHNICAL.md).

###  Health Score

52

—

FairBetter than 96% of packages

Maintenance69

Regular maintenance activity

Popularity34

Limited adoption so far

Community24

Small or concentrated contributor base

Maturity70

Established project with proven stability

 Bus Factor2

2 contributors hold 50%+ of commits

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~357 days

Recently: every ~1 days

Total

11

Last Release

158d ago

Major Versions

v1.3.1 → 2.02026-01-21

1.3.3 → 2.1.02026-01-24

### Community

Maintainers

![](https://www.gravatar.com/avatar/4d3680d6353e5f171543435b89965ba2588186ad7ec0ec97cbf572704fec2a4f?d=identicon)[micschk](/maintainers/micschk)

---

Top Contributors

[![micschk](https://avatars.githubusercontent.com/u/1005986?v=4)](https://github.com/micschk "micschk (23 commits)")[![patjnr](https://avatars.githubusercontent.com/u/435055?v=4)](https://github.com/patjnr "patjnr (8 commits)")[![tristan-mastrodicasa](https://avatars.githubusercontent.com/u/9061589?v=4)](https://github.com/tristan-mastrodicasa "tristan-mastrodicasa (4 commits)")[![RVXD](https://avatars.githubusercontent.com/u/1586761?v=4)](https://github.com/RVXD "RVXD (3 commits)")[![hubertusanton](https://avatars.githubusercontent.com/u/582188?v=4)](https://github.com/hubertusanton "hubertusanton (3 commits)")[![kdanilewicz](https://avatars.githubusercontent.com/u/1428945?v=4)](https://github.com/kdanilewicz "kdanilewicz (1 commits)")[![LABCAT](https://avatars.githubusercontent.com/u/9105153?v=4)](https://github.com/LABCAT "LABCAT (1 commits)")[![gazzayeatman](https://avatars.githubusercontent.com/u/13740601?v=4)](https://github.com/gazzayeatman "gazzayeatman (1 commits)")[![nathanbrauer](https://avatars.githubusercontent.com/u/323945?v=4)](https://github.com/nathanbrauer "nathanbrauer (1 commits)")[![balazsbohonyi](https://avatars.githubusercontent.com/u/507725?v=4)](https://github.com/balazsbohonyi "balazsbohonyi (1 commits)")[![straathof](https://avatars.githubusercontent.com/u/9931668?v=4)](https://github.com/straathof "straathof (1 commits)")[![sunnysideup](https://avatars.githubusercontent.com/u/167154?v=4)](https://github.com/sunnysideup "sunnysideup (1 commits)")[![adrexia](https://avatars.githubusercontent.com/u/984753?v=4)](https://github.com/adrexia "adrexia (1 commits)")[![jules0x](https://avatars.githubusercontent.com/u/8979741?v=4)](https://github.com/jules0x "jules0x (1 commits)")

---

Tags

silverstripesvg

### Embed Badge

![Health badge](/badges/restruct-silverstripe-svg-images/health.svg)

```
[![Health](https://phpackages.com/badges/restruct-silverstripe-svg-images/health.svg)](https://phpackages.com/packages/restruct-silverstripe-svg-images)
```

###  Alternatives

[craftcms/cms

Craft CMS

3.6k3.6M3.1k](/packages/craftcms-cms)[picqer/php-barcode-generator

An easy to use, non-bloated, barcode generator in PHP. Creates SVG, PNG, JPG and HTML images from the most used 1D barcode standards.

1.8k28.4M119](/packages/picqer-php-barcode-generator)[silverstripe/framework

The SilverStripe framework

7313.7M2.8k](/packages/silverstripe-framework)[contao/core-bundle

Contao Open Source CMS

1231.6M2.8k](/packages/contao-core-bundle)[helsingborg-stad/municipio

A bootstrap theme for creating municipality sites.

4028.5k10](/packages/helsingborg-stad-municipio)[unopim/unopim

UnoPim Laravel PIM

10.5k2.4k](/packages/unopim-unopim)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)