Media Library

FrankenCMS uses Spatie Media Library for powerful media management with automatic image processing, responsive images, and focal point cropping.

Uploading Media

Media can be uploaded in several ways:

  • Featured Image: Upload directly on the post/page editor
  • Content Images: Insert images via the rich editor
  • Template Fields: Use @frankenImage directive
Screenshot

Featured Image tab showing the upload, the Generate with AI action, the focal point, and image details.

Image Processing

FrankenCMS generates these conversions for post and page images:

Conversion Size Use Case
thumb 80×80 Admin previews
featured From Media settings Featured image on the single post view
listing From Media settings Blog index and archive cards
og 1200×630 Open Graph sharing image
twitter / twitter-summary 1200×675 / 600×600 Large and summary Twitter cards

The featured and listing aspect ratios, dimensions, and "Crop To Exact Dimensions" options live under CMS Settings → Media. When cropping is on, crops are centered on the image's focal point.

Changing the crop settings doesn't rebuild existing image files. Run php artisan media-library:regenerate afterwards.

Displaying Images

Featured Images

blade
@if($post->hasMedia('featured'))
    @php($media = $post->getFirstMedia('featured'))

    <img
        src="{{ $media->getUrl('featured') }}"
        alt="{{ $media->getCustomProperty('alt') }}"
        style="{{ \FrankenCms\Support\FocalPoint::toCss($media->getCustomProperty('focal_point')) }}"
        class="object-cover"
        loading="lazy"
    >
@endif

Responsive Images

blade
@if($post->hasMedia('featured'))
    {{ $post->getFirstMedia('featured')
        ->img('featured', ['class' => 'featured-image'])
        ->lazy() }}
@endif

Focal Point Cropping

A focal point keeps the important part of an image visible at every crop size:

  1. Upload a featured image, then click Update focal point below it
  2. Click the most important area of the image. The previews show how each crop will look
  3. Click Update and close, then save the post
Focal point picker modal with the source image on the left and crop previews on the right

The focal point picker previews each crop before you save.

Saving a new focal point regenerates the thumb, featured, and listing conversions automatically. The value is stored on the media item as a percentage string such as '50% 30%'. Use the FocalPoint helper to read it rather than parsing it yourself:

php
use FrankenCms\Support\FocalPoint;

$value = $media->getCustomProperty('focal_point');

FocalPoint::toCss($value);     // 'object-position: 50% 30%;'
FocalPoint::normalize($value); // ['x' => 50, 'y' => 30]

The example theme's OG image templates honor the focal point too. With AI integration enabled, a Generate with AI action next to the upload can create the featured image for you.

Alt Text and Metadata

Always add alt text for accessibility and SEO:

php
// Get alt text
$alt = $media->getCustomProperty('alt');

// Get caption
$caption = $media->getCustomProperty('caption');

// Get all custom properties
$properties = $media->custom_properties;

Using Media in Template Fields

blade
@frankenImage('banner.image', [
    'label' => 'Hero Background',
    'collection' => 'hero-images',
])

@
<div style="background-image: url('{{ frankenField('banner.image') }}')">
    ...
</div>

Storage Configuration

Configure the storage disk in your .env file:

bash
# Use local public disk (default)
MEDIA_DISK=public

# Use S3 for production
MEDIA_DISK=s3

Next Steps