#[AsImageSize]

Register a custom WordPress image size.

Signature

#[Attribute(Attribute::TARGET_CLASS)]
final readonly class AsImageSize
{
    public function __construct(
        public int $width,
        public int $height = 0,
        public bool $crop = false,
        public ?string $name = null,
    ) {}
}

Parameters

Parameter	Type	Default	Description
width	int	—	Image width in pixels (required)
height	int	0	Image height in pixels (0 for proportional scaling)
crop	bool	false	Whether to crop the image to exact dimensions
name	?string	null	Custom size name (derived from class name if omitted)

Name Derivation

When name is not specified, it's automatically derived from the class name:

1. Common suffixes (Image, Size, ImageSize) are removed
2. PascalCase is converted to snake_case

Class Name	Derived Name
HeroImage	hero
ThumbnailLarge	thumbnail_large
SocialShareImage	social_share
CardSize	card

Usage

Basic Image Size

<?php

namespace App\ImageSizes;

use Studiometa\Foehn\Attributes\AsImageSize;

#[AsImageSize(width: 1200, height: 630)]
final class SocialShareImage {}

This registers an image size named social_share with dimensions 1200×630 pixels.

With Cropping

#[AsImageSize(width: 800, height: 600, crop: true)]
final class ThumbnailLarge {}

When crop is true, images are cropped to exact dimensions rather than scaled proportionally.

Custom Name

#[AsImageSize(name: 'hero', width: 1920, height: 1080, crop: true)]
final class HeroBannerImage {}

Use a custom name when you want explicit control over the image size identifier.

Width Only (Proportional Height)

#[AsImageSize(width: 400)]
final class SmallThumbnail {}

When height is 0 (the default), the image height scales proportionally to maintain aspect ratio.

Theme Support

When any image size is discovered, Føhn automatically enables the post-thumbnails theme support:

add_theme_support('post-thumbnails');

This ensures featured images work correctly in the WordPress admin.

Using Custom Sizes

In Templates

{# Get specific image size #}
<img src="{{ post.thumbnail.src('social_share') }}" alt="{{ post.thumbnail.alt }}">

{# With Timber's resize #}
<img src="{{ post.thumbnail.src|resize(1200, 630) }}" alt="{{ post.thumbnail.alt }}">

In PHP

// Get image URL for custom size
$url = wp_get_attachment_image_url($attachment_id, 'social_share');

// Get full image tag
$img = wp_get_attachment_image($attachment_id, 'hero');

Organization

We recommend organizing image sizes in a dedicated directory:

app/
└── ImageSizes/
    ├── HeroImage.php
    ├── ThumbnailLarge.php
    └── SocialShareImage.php

Related

• WordPress Image Sizes
• #[AsPostType] — Post types with thumbnail support