nutshell-framework / icon-picker

1.0.1 2026-07-08 04:03 UTC

Requires

• php: ^8.1
• contao/core-bundle: ^5.7
• contao/manager-plugin: ^2.0
• symfony/http-kernel: ^6.0 || ^7.0

LGPL-3.0-or-later

• Dennis Erdmann

• svg
• contao
• icon picker
• contao bundle
• inline svg

Published on Packagist.org on 2026-09-14 13:05 UTC

README

Generischer Inline-SVG-Icon-Picker fürs Contao-Backend. Lädt Icons aus konfigurierbaren Verzeichnissen (mit Layer-Override), bietet ein Modal-Widget für die DCA und eine Twig-Funktion inline_icon() zum sicheren Rendern im Frontend.

Funktionen

• DCA-Widget iconPicker — Auswahl per <dialog>-Modal mit Inline-Vorschau, Live-SVG-Darstellung und „Auswahl aufheben". Gespeichert wird der Slug (Dateiname ohne .svg).
• Layer-Override — mehrere Icon-Verzeichnisse möglich; bei Namensgleichheit gewinnt das zuletzt konfigurierte (Defaults zuerst, Custom-Overrides am Ende).
• Gruppierung — Unterordner (z. B. social/twitter) werden im Modal als aufklappbare Gruppen dargestellt.
• Twig-Funktion inline_icon() — zwei Render-Modi: vollständiges Inline-SVG oder <use>-Referenz auf ein gebautes Sprite.
• SVG-Sanitizer — entfernt script, Event-Handler und externe Referenzen, bevor SVG ausgegeben wird (Backend-Vorschau, Inline-Render und Sprite).
• Sprite-Builder — baut bei cache:warmup automatisch eine Sprite-Datei unter public/.
• Dark-/Light-Mode — das Widget nutzt Contaos Backend-CSS-Variablen und passt sich dem gewählten Farbschema an.

Voraussetzungen

• PHP >= 8.1
• Contao >= 5.7

Installation

composer require nutshell-framework/icon-picker

Alternativ über den Contao Manager: nach nutshell-framework/icon-picker suchen und installieren.

Konfiguration

Standardmäßig scannt der Picker files/icons im Projekt — dort einfach SVGs ablegen, und sie tauchen sofort im Backend auf. Keine weitere Konfiguration nötig.

Eigene Verzeichnisse (z. B. Theme-Defaults plus Projekt-Overrides) werden über den IconSetResolver-Service gesetzt. Spätere Pfade überschreiben frühere bei gleichem Dateinamen:

# config/services.yaml (Projekt oder Theme-Bundle)
services:
    Nutshell\IconPicker\Icon\IconSetResolver:
        public: true
        arguments:
            $iconDirs:
                - '%kernel.project_dir%/../layout/seeker-theme/img/icons'  # Defaults
                - '%kernel.project_dir%/../layout/custom/img/icons'        # Overrides

Der Render-Modus und die Sprite-Pfade lassen sich über Parameter steuern:

Parameter	Default	Bedeutung
nutshell_icon_picker.render_mode	inline	inline = SVG direkt; sprite = <use>-Referenz
nutshell_icon_picker.sprite_target_path	%kernel.project_dir%/public/assets/icons/sprite.svg	Schreibpfad der Sprite-Datei
nutshell_icon_picker.sprite_public_path	/assets/icons/sprite.svg	Web-URL der Sprite-Datei

Verwendung

Im DCA

Das Widget per inputType in einer DCA registrieren:

$GLOBALS['TL_DCA']['tl_content']['fields']['my_icon'] = [
    'inputType' => 'iconPicker',
    'eval'      => ['tl_class' => 'w50'],
    'sql'       => "varchar(255) NOT NULL default ''",
];

Gespeichert wird der Slug (Dateiname ohne .svg, inkl. Unterordner-Pfad, z. B. social/twitter).

Im Twig-Template

{# Inline-SVG mit optionaler CSS-Klasse #}
{{ inline_icon('star') }}
{{ inline_icon('social/twitter', 'icon icon--lg') }}

{# Aus einem DCA-Feld #}
{{ inline_icon(content.my_icon) }}

Existiert der Slug in keinem konfigurierten Verzeichnis, gibt die Funktion leeres Markup zurück (kein kaputter Output).

Jede Ausgabe trägt die Basisklasse inline-icon (zusätzlich zu einer optional übergebenen Klasse) — als Styling-Hook fürs Theme und als Ziel fürs Backend-Sizing (siehe unten).

Icon-Größe im Backend

Vom Picker gerenderte Icons (.inline-icon) werden in Backend-Vorschauen und -Listen auf 60px gedeckelt, damit SVGs ohne intrinsische Größe nicht auf die volle Spaltenbreite laufen. Die dafür nötige public/backend.css wird beim Setup veröffentlicht:

vendor/bin/contao-console contao:setup   # oder: assets:install --symlink

Sprite-Modus

Für weniger HTML und besseren Browser-Cache render_mode auf sprite setzen. Die Sprite-Datei wird automatisch beim cache:warmup gebaut:

vendor/bin/contao-console cache:warmup

inline_icon() gibt dann <svg><use href="/assets/icons/sprite.svg#slug"/></svg> aus. Nach Änderungen an den Icons den Cache neu aufwärmen.

Sicherheit

Jedes SVG durchläuft vor der Ausgabe den SvgSanitizer. Entfernt werden u. a.:

• <script>, <iframe>, <foreignObject>, <use>, <image>
• alle on*-Event-Handler
• href/xlink:href, sofern nicht rein dokumentintern (#…)

Slugs sind gegen Path-Traversal abgesichert (kein .., kein führender Slash).

Lizenz

LGPL-3.0-or-later