README

A comprehensive SilverStripe CMS module for generating and managing website favicons with support for multiple formats, sizes, and generation methods.

Features

Dual Generation Modes: Upload ZIP from favicon generators or upload a single image for automatic generation
Multiple Formats: Supports ICO, PNG, SVG, JSON manifest, and XML browserconfig files
Complete Size Coverage: Generates all standard favicon sizes (16x16, 32x32, 48x48, 180x180, 192x192, 256x256, 384x384, 270x270)
Image Processing: Uses ImageMagick or GD for high-quality image generation
Asset Management: Fully integrated with SilverStripe's asset management system
CMS Integration: Easy-to-use interface in Site Settings

Requirements

SilverStripe Framework ^6.0
SilverStripe Admin ^3.0
Display Logic ^3.0
PHP extensions: ImageMagick (recommended) or GD for image generation

Installation

composer require khalsa-jio/silverstripe-favicon-generator

After installation, run a dev/build to apply database changes:

vendor/bin/sake dev/build flush=1

Usage

Via CMS Admin

Log into your SilverStripe admin panel
Navigate to Settings > Site Settings
Click on the "Favicon" tab
Choose your generation method:

Method 1: ZIP Upload (Recommended)

Generate a favicon package using RealFaviconGenerator
Download the ZIP file
Upload the ZIP file through the CMS interface
Configure color values as needed

Method 2: Single Image Generation

Upload a high-resolution square image (minimum 512x512px)
Enable "Auto-generate when image changes"
The module will automatically generate all required sizes and formats

Template Integration

The module includes a pre-built template that handles all favicon links automatically. Simply add this single line to your page template:

<!-- In your Page.ss template's <head> section -->
<% include Favicons %>

That's it! The included template will automatically output all necessary favicon links and meta tags based on the files configured in Site Settings.

What's Included Automatically

The <% include Favicons %> template automatically adds:

Standard favicon (ICO format for legacy browsers)
PNG favicons for modern browsers (16x16, 32x32)
Apple Touch Icon for iOS devices
Safari Pinned Tab icon with configured color
Web App Manifest for PWA support
Theme color meta tag for mobile browsers
Microsoft application config for Windows tiles
Fallback MS Application meta tags

Advanced Template Usage

If you need more control, you can manually add individual favicon elements:

<!-- Individual favicon elements -->
<% with $SiteConfig %>
    <% if $Favicon %>
        <link rel="icon" type="image/x-icon" href="$Favicon.Link">
    <% end_if %>
    
    <% if $Favicon16x16 %>
        <link rel="icon" type="image/png" sizes="16x16" href="$Favicon16x16.Link">
    <% end_if %>
    
    <% if $AppleTouchIcon %>
        <link rel="apple-touch-icon" sizes="180x180" href="$AppleTouchIcon.Link">
    <% end_if %>
    
    <% if $SafariPinnedTab %>
        <link rel="mask-icon" href="$SafariPinnedTab.Link" color="$getMaskIconColour">
    <% end_if %>
    
    <% if $Manifest %>
        <link rel="manifest" href="$Manifest.Link">
    <% end_if %>
    
    <% if $FaviconManifestThemeColour %>
        <meta name="theme-color" content="$FaviconManifestThemeColour">
    <% end_if %>
<% end_with %>

Configuration

The module comes with sensible defaults but can be customized via YAML configuration:

# app/_config/favicon-config.yml
KhalsaJio\FaviconGenerator\Extension\SiteConfigExtension:
  defaults:
    FaviconManifestThemeColour: '#ffffff'
    FaviconMSAppTileColour: '#174a5b'
    FaviconMaskIconColour: '#a2b7bd'
    FaviconGenerationMode: 'zip'
    AutoGenerateFromSource: true

File Structure

Generated files are organized in the assets directory:

assets/
└── favicons/
    └── site{ID}/
        ├── archives/          # ZIP files (protected)
        ├── favicon.ico
        ├── favicon-16x16.png
        ├── favicon-32x32.png
        ├── apple-touch-icon.png
        ├── android-chrome-192x192.png
        ├── android-chrome-256x256.png
        ├── android-chrome-384x384.png
        ├── mstile-150x150.png
        ├── safari-pinned-tab.svg
        ├── site.webmanifest
        └── browserconfig.xml

Supported File Formats

Input Formats (Single Image Mode)

PNG
JPEG/JPG
SVG

Generated Output Formats

ICO: favicon.ico (48x48)
PNG: Various sizes (16x16, 32x32, 180x180, 192x192, 256x256, 384x384, 270x270)
SVG: Safari pinned tab icon
JSON: Web app manifest
XML: Microsoft browserconfig

Browser Support

Generated favicons support all modern browsers including:

Chrome/Chromium
Firefox
Safari
Edge
Internet Explorer 11+
Mobile browsers (iOS Safari, Android Chrome)

Troubleshooting

Image Generation Issues

Ensure ImageMagick or GD PHP extension is installed
Check PHP memory limits for large source images
Verify write permissions in assets directory

ZIP Upload Issues

Ensure ZIP contains all required files with exact filenames
Check file size limits in PHP configuration
Verify ZIP file structure matches expected format

Contributing

Contributions are welcome! Please ensure:

Code follows PSR-12 standards
All tests pass
Documentation is updated

License

This module is licensed under the BSD-3-Clause license. See LICENSE for details.

Support

For issues, feature requests, or questions:

Create an issue on the GitHub repository
Check existing issues for solutions
Review the SilverStripe documentation for general CMS help

khalsa-jio / silverstripe-favicon-generator

Maintainers

Details