Working with media

Pragma CMS treats media not just as stored files, but as a high-performance asset pipeline. Instead of merely "saving" uploads, it actively optimizes them for modern web standards (2026 Core Web Vitals) to guarantee maximum loading speed and perfect SEO scores.

The "Master" Normalization

When a user uploads an image, Pragma CMS doesn't just save it. To protect your server storage and ensure performance, the CMS applies Master Normalization:

Size Guardrail: If an image exceeds 2560px (width or height), it is automatically resized before saving. This prevents "4K raw uploads" from consuming server storage and slowing down the site.
EXIF Auto-Orientation: Smartphone photos are automatically rotated based on their native EXIF data, ensuring they never appear sideways.
Memory-Safe Processing: The image processor (Imagick) is strictly capped at 256MB of RAM per operation to prevent server crashes during massive multi-file uploads.
Atomic Writing: Files are saved using atomic operations (.tmp renaming) to ensure no corrupted files are ever written to the disk.

The original normalized file is permanently kept in media/source, while web-ready variants are dynamically generated in the public media/images directory.

lightbulb

Best Practice

To guarantee optimal quality and processing speed, upload images with a maximum width between 1920px and 2560px. Larger files slow down processing and may produce compression artifacts.

Automated Variant System

For every bitmap image (JPEG, PNG, WebP), the CMS generates a complete set of variants. This allows the browser to download the exact file size required for the user's screen.

Suffix	Purpose	Default Behavior
thumbnail	Admin galleries & avatars	150x150px (Strict Hard Crop)
medium	Inline content / Cards	Max 300px width (Proportional Best Fit)
large	Standard content blocks	Max 1024px width (Proportional Best Fit)
xlarge	Hero banners / Full width	Max 1920px width (Proportional Best Fit)
social	Open Graph / Twitter Cards	1200x630px (Strict Center Crop)

Next-Gen Formats: WebP & AVIF

Pragma CMS is strictly future-proof. Every image goes through a highly optimized rendering engine:

AVIF & WebP Generation: Offers the best compression-to-quality ratio available. The CMS automatically generates these alongside the standard JPEG/PNG versions.
Intelligent PNG Handling: PNGs are treated differently than JPEGs. The CMS limits their compression (95%) and applies a very light sharpening filter to ensure screenshots, text, and UI elements remain perfectly crisp and artifact-free.
Adaptive Sharpening: When reducing an image's size by more than 20%, the CMS applies an intelligent "Unsharp Mask" (via Imagick or GD matrix) to compensate for the blurriness usually caused by downscaling.
Dynamic Chroma Subsampling: Large JPEG images are automatically compressed using 4:2:0 chroma subsampling to drastically reduce file weight, while smaller images retain 4:4:4 mapping to prevent pixelated color bleeding.

Transformation (Coming Soon)

Future updates will include a focal-point selector for art-directed cropping.

Rendering Optimized Images

To display an image on the front-end, never use a raw <img> tag. Always use the native renderImage() function. This engine generates a complex, fully responsive HTML structure seamlessly.

PHP

// Simple usage
renderImage($mediaId, 'large');

// Advanced usage for LCP (Largest Contentful Paint) optimization
renderImage($mediaId, 'xlarge', [
    'class' => 'hero-img',
    'fetchpriority' => 'high', // Tells the browser to download this first
    'loading' => 'eager'       // Disables lazy-loading for critical images
]);

What `renderImage()` handles automatically:

Format Negotiation: It outputs a <picture> element with <source> tags for AVIF and WebP, allowing modern browsers to pick the lightest format.
Resolution Switching: It generates a full srcset (e.g., 1024w, 1920w) and sizes attributes, ensuring Retina/4K screens display crisp images while mobile phones download smaller files.
Strict Anti-CLS: It calculates and injects the exact width and height attributes based on the variant's metadata. This ensures the page layout doesn't "jump" (Cumulative Layout Shift) while the image loads.
Lazy Loading: By default, all images are enforced with loading="lazy" and decoding="async" to prevent blocking the browser's main thread.

Non-Image Media

SVGs: Served via a "fast path". The CMS bypasses the <picture> generation and directly reads the viewBox or XML width/height attributes to ensure correct proportions without rasterizing the vector file.
PDFs: If the Imagick extension is active on your server, Pragma CMS automatically reads the PDF and generates a PNG preview of the first page to serve as a thumbnail in the gallery.
Videos & Docs: Safely stored, bypassed from image processing, and assigned a standard file-type icon for the UI.

Image Maintenance & Regeneration

Pragma CMS is designed to evolve. If you modify your image dimensions (e.g., changing medium width from 300px to 400px) or adjust compression quality in the Site Settings, your existing images won't be automatically updated to save server resources.

To sync your existing library with new settings, use the Regeneration Tool in Admin > Maintenance.

How it works:

Batch Processing: The regeneration process runs in small batches via AJAX. This prevents server timeouts and high CPU usage, even with libraries containing thousands of images.
Clean Slate: For each image, the CMS deletes all old variants (JPG, WebP, AVIF) and recreates them from the "Master" source stored in media/source.
Database Sync: The CMS updates the file_dimensions and variants JSON in the database to reflect the new file paths and sizes.

When to regenerate?

After changing image dimensions in Settings > Media.
After enabling/disabling AVIF or WebP support.
After changing the global JPEG Quality setting.

Storage Cleanup: Orphaned Files

Over time, server directories might accumulate files that are no longer linked to the database (e.g., due to interrupted deletions or manual FTP errors). These are called Orphaned Files.

Pragma CMS includes a smart scanner in the Maintenance panel that:

Scans and compares the physical files in your media/ directories with the database records.
Identifies "ghost" files that are taking up disk space for nothing.
Allows you to safely delete them in bulk to reclaim storage.