README

Perfectly sized. Never pixelated.

Opixlig is a Laravel-friendly image component inspired by modern frameworks like Next.js — designed to make responsive, optimized images effortless. It automatically generates and serves the right image size and format for every device, keeping your pages fast, sharp, and beautifully adaptive. Write clean Blade, and let Opixlig handle the rest.

Features

🖼️ Responsive images: Automatically generates and serves appropriately sized images for any device
🚀 Performance optimized: Converts images to modern formats like WebP for faster loading
📱 Adaptive srcsets: Creates optimized srcsets for both responsive and fixed-width images
🔍 Placeholder support: Includes "blur" and "empty" placeholder options while images load
⚙️ Highly configurable: Customize quality, widths, and more to fit your needs
🛠️ Simple API: Clean Blade component syntax that feels natural in your Laravel views

Installation

You can install the package via composer:

composer require itiden/opixlig

Publishing the config

php artisan vendor:publish --tag="itiden-opixlig-config"

Configuration

After publishing the config file, you can customize the following settings in config/opixlig.php:

return [
    // Where generated images are stored in your storage directory
    'storage_folder' => 'app/.images',

    // Public URL path to access the images
    'public_folder' => 'images',

    // Image manipulation driver ('imagick' or 'gd')
    'driver' => 'imagick',

    // Default widths for responsive images
    'default_widths' => [384, 640, 828, 1200, 2048, 3840],

    // Default placeholder type ('empty' or 'blur')
    'default_placeholder' => 'empty',

    // Default image quality (1-100)
    'default_quality' => 75,
];

Usage

Basic Example

Use the Blade component in your views:

<x-opixlig::image
    src="public/images/hero.jpg"
    width="800"
    height="600"
    alt="Hero image"
/>

Responsive Images with Custom Sizes

<x-opixlig::image
    src="public/images/hero.jpg"
    sizes="(max-width: 768px) 100vw, 50vw"
    width="1200"
    height="800"
    alt="Responsive hero image"
/>

Using Blur Placeholder

<x-opixlig::image
    src="public/images/hero.jpg"
    width="800"
    height="600"
    placeholder="blur"
    alt="Hero image with blur placeholder"
/>

Custom Quality

<x-opixlig::image
    src="public/images/hero.jpg"
    width="800"
    height="600"
    quality="90"
    alt="High quality hero image"
/>

Using the Helper Function

You can also use the img() helper function directly:

$imageUrl = img('public/images/hero.jpg', 800, 600, ['fm' => 'webp', 'q' => 80])->url(['w' => 800]);

Advanced Usage

Available Props

Prop	Type	Default	Description
src	string	''	Path to the source image (including disk name e.g., 'public/images/file.jpg')
sizes	string	''	Media query sizes attribute for responsive images
width	number	''	Width of the image
height	number	''	Height of the image
loading	string	'lazy'	Image loading strategy ('lazy', 'eager', 'auto')
decoding	string	'async'	Image decoding strategy ('async', 'sync', 'auto')
quality	number	config('opixlig.default_quality')	Image quality (1-100)
placeholder	string	config('opixlig.default_placeholder')	Placeholder type ('empty' or 'blur')

Image Manipulations

Opixlig uses League's Glide under the hood, so you can pass any Glide manipulation parameters:

$imageUrl = img('public/images/hero.jpg', 800, 600)
    ->url([
        'w' => 800,               // Width
        'q' => 90,                // Quality
        'fm' => 'webp',           // Format
        'fit' => 'crop',          // Fit
        'crop' => 'center',       // Crop position
        // Other Glide parameters...
    ]);

How It Works

The component generates optimized images on demand
Images are processed using the configured driver (Imagick or GD)
Processed images are stored in the configured cache directory
Subsequent requests for the same image with the same parameters are served directly from cache without hitting laravel
The package automatically generates appropriate srcsets for responsive designs

Contributing

Please see CONTRIBUTING.md for details.

License

The MIT License (MIT). Please see License File for more information.

itiden / opixlig

Maintainers

Details