# Favicon Management Feature

**Date**: 2026-01-06
**Type**: ACF Field Addition + Theme Feature

## Summary

Added favicon management through Theme Options. Site administrators can upload a source image that gets automatically converted to all required favicon sizes using ImageMagick.

## ACF Field Group Changes

### Theme Options (group_theme_options)

Added new "Branding" tab (before Advanced tab):

**New Tab**: Branding (field_theme_tab_branding)

**New Fields**:
1. `theme_favicon_source` (field_theme_favicon_source) - Image field
   - Return format: ID
   - Mime types: png, webp
   - Minimum dimensions: 256x256 pixels
   - Instructions: Upload square image at least 512x512

2. `theme_favicon_status` (field_theme_favicon_status) - Message field
   - Shows instructions about saving to generate favicons

## Generated Files

When a favicon source is uploaded and saved, the following files are generated in `/wp-content/uploads/favicon/`:

| File | Size | Purpose |
|------|------|---------|
| favicon.ico | 16x16, 32x32, 48x48 | Legacy browsers |
| favicon-16x16.png | 16x16 | Standard favicon |
| favicon-32x32.png | 32x32 | Standard favicon |
| favicon-48x48.png | 48x48 | Standard favicon |
| apple-touch-icon.png | 180x180 | iOS home screen |
| android-chrome-192x192.png | 192x192 | Android/Chrome |
| android-chrome-512x512.png | 512x512 | Android/Chrome splash |
| mstile-150x150.png | 150x150 | Windows tiles |
| site.webmanifest | - | PWA manifest |
| browserconfig.xml | - | Windows tile config |

## Theme Files Added/Modified

### New File: `inc/favicon.php`
- ACF save hook for favicon processing
- ImageMagick conversion functions
- Web manifest generation
- HTML head output with cache busting
- Disables WordPress Site Icon (Customizer)

### Modified: `functions.php`
- Added `require_once` for `inc/favicon.php`

### Modified: `inc/acf-fields.php`
- Added Branding tab with favicon fields

## Server Requirements

- **ImageMagick**: Must be installed with `convert` command available
- Admin notice displays if ImageMagick is not found

## How to Use

1. Go to Theme Options in WordPress admin
2. Click the "Branding" tab
3. Upload a square PNG or WebP image (minimum 256x256, recommended 512x512)
4. Save the Theme Options
5. Favicons are automatically generated and output in the HTML head

## Cache Busting

Favicon URLs include a version query parameter based on file modification time to ensure browsers load updated favicons when changed.

## Dependencies

- ACF Pro
- ImageMagick on server
- Theme must include favicon.php