# Featured Image Fallback Fix

**Last Updated:** 2026-01-09

## Problem

Featured images were not displaying because:

1. Local image files don't exist in `/assets/blog-images/` directory
2. Fallback mechanism only checked content HTML, but featured images were removed from content
3. No lookup mechanism to find WordPress URLs from the images list

## Solution

Enhanced the `get_image_with_fallback()` function to use multiple fallback strategies:

### Fallback Strategy Order

1. **Check if local file exists** - Use local path if file exists
2. **Extract from content HTML** - Try to find WordPress URL in content HTML
3. **Lookup from blog-images-list.json** - Match by filename and post URL
4. **Return null** - Don't show broken images if no fallback found

### New Function: `get_wordpress_image_url_from_list()`

Looks up WordPress URLs from `docs/data/blog-images-list.json`:

- Matches by filename (handles different extensions and size suffixes)
- Matches by post URL (for featured images)
- Prioritizes featured images for the specific post
- Falls back to filename match if no post match found

### Matching Logic

**Filename Matching:**

- Removes extensions (.webp, .jpg, .png)
- Removes size suffixes (-768x626)
- Normalizes to lowercase for comparison
- Handles partial matches

**Post URL Matching:**

- Normalizes URLs (removes trailing slashes)
- Checks for exact match or substring match
- Prioritizes featured images for matching posts

## Files Modified

### 1. `v2/config/blog-template-helpers.php`

**New Function:**

- `get_wordpress_image_url_from_list()` - Looks up WordPress URLs from images list

**Updated Function:**

- `get_image_with_fallback()` - Added `$post_url` parameter and lookup from images list

### 2. `v2/components/blog/PostHeader.php`

**Changes:**

- Pass `$post_url` to `get_image_with_fallback()` function
- Extract post URL from `$post` array if available

## Usage

```php
// In PostHeader.php
$image_data = get_image_with_fallback($featured_image, $content_html, $post_url);
```

The function will:

1. Check if local file exists at `/assets/blog-images/...`
2. If not, try to extract WordPress URL from content HTML
3. If not found, look up WordPress URL from `blog-images-list.json`
4. Return image data with WordPress URL as fallback

## Image List Lookup

The lookup uses `docs/data/blog-images-list.json` which contains:

- WordPress URLs for all images
- Image type (featured/content)
- Post URL association
- Image metadata

**Lookup Priority:**

1. Featured image for matching post URL
2. Filename match (any image with matching filename)

## Testing

### Test Cases

1. **Local File Exists**

   - Should use local path
   - No fallback needed

2. **Local File Missing, WordPress URL in Content**

   - Should extract from content HTML
   - Use WordPress URL as fallback

3. **Local File Missing, WordPress URL in Images List**

   - Should look up from images list
   - Match by filename or post URL
   - Use WordPress URL as fallback

4. **No Fallback Available**
   - Should return null
   - Image won't display (prevents broken images)

### Verification Steps

1. Check blog posts with featured images
2. Verify images display using WordPress URLs
3. Check browser network tab for image requests
4. Verify images load correctly
5. Check console for any image loading errors

## Impact

### Before

- ❌ Featured images not displaying
- ❌ Only checked content HTML for fallback
- ❌ No lookup mechanism for WordPress URLs

### After

- ✅ Featured images display using WordPress URLs as fallback
- ✅ Multiple fallback strategies
- ✅ Lookup from images list by filename and post URL
- ✅ Prevents broken images (returns null if no fallback)

## Related Documentation

- `docs/content/blog/IMAGE_FIX_SUMMARY.md` - Content image display fix
- `docs/content/blog/CONTENT_EXTRACTION_GUIDE.md` - Image extraction process
- `docs/data/blog-images-list.json` - Complete images list with WordPress URLs

## Next Steps

1. **Download Images** - Download all images to `/assets/blog-images/` directory
2. **Image Optimization** - Convert to WebP format and optimize sizes
3. **CDN Setup** - Consider using CDN for image delivery
4. **Performance** - Monitor image loading performance
5. **Fallback Removal** - Once images are downloaded, remove WordPress fallback