README

A dynamic, memory-safe image collage generator for Laravel. This package evaluates image orientations on the fly to produce structural, clean masonry grids (such as top-banners or side-portrait pillars) layouts.

Features

• Adaptive 3-Image Engine: Intelligently swaps between a Landscape Banner framework or a Portrait Left Pillar layout depending on the primary image's aspect ratio.
• Dynamic Height Compression: Automatically calculates and shrinks row elements proportionally using a configuration threshold boundary (canvas_height) so multi-image elements snap perfectly onto single-page PDF engines (like DomPDF or Snappy) without creating blank whitespace gaps.
• Memory Optimization Pipeline: Gathers layout image dimensions safely (getimagesize) without loading pixel matrices directly into memory, cleaning up processing allocations instantly after write sequences finish to protect server thresholds.
• Fluent Chaining Interface: Allows developers to adjust constraints on the fly and immediately pluck out absolute filesystem paths or asset URLs.

Installation

You can install this package easily via Composer.

1. Run the Composer Require Command

Execute the following command in your terminal root to download and install the distribution:

composer require dot-env-it/collage

2. Publish Configuration Assets

Expose the custom layout variables to your root application configuration directory by running:

php artisan vendor:publish --tag=collage-config

Configuration

Once published, you can fine-tune default compilation parameters globally inside config/collage.php:

return [
    // Default canvas width constraint (Pixels)
    'canvas_width' => 1200,

    // Strict maximum vertical height ceiling to prevent page-overflow breaks
    'canvas_height'  => 1200,

    // Border gaps between bounding layout rows/columns
    'padding'      => 12,

    // Default Storage Disk driver target
    'disk'         => 'public',
];

Usage

Basic Usage

Pass an array of local absolute file paths to the Collage builder and export it to your destination path:

use DotEnvIt\Collage\Facades\Collage;

$imagePaths = [
    '/storage/app/public/photos/img1.jpg',
    '/storage/app/public/photos/img2.jpg',
    '/storage/app/public/photos/img3.jpg',
];

// Returns instance of Collage after writing to disk
$collage = Collage::make()
    ->from($imagePaths)
    ->save('collages/event-101.jpg');

Fluent Extraction Methods

You can easily extract the file targets inline directly out of your execution pipeline:

// Extract the absolute local file path (perfect for PDF engines)
$absolutePath = Collage::make()
    ->from($imagePaths)
    ->save('collages/event-101.jpg')
    ->getPath(); 
// Returns: "/home/user/app/storage/app/public/collages/event-101.jpg"

// Extract the publicly accessible public asset URL string
$publicUrl = Collage::make()
    ->from($imagePaths)
    ->save('collages/event-101.jpg')
    ->getUrl();
// Returns: "[https://your-domain.com/storage/collages/event-101.jpg](https://your-domain.com/storage/collages/event-101.jpg)"

Runtime Method Overrides

If a specific layout demands unique structural parameters that differ from your global config/collage.php file defaults, you can override settings fluently at runtime:

$customCollagePath = Collage::make()
    ->from($imagePaths)
    ->width(1600)       // Enforce a crisp wider base profile
    ->height(1200)  // Expand vertical space threshold limit
    ->disk('local')
    ->save('collages/high-res-event.jpg')
    ->getPath();

License

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