tzsk/collage

Generate Image Collage with Laravel

7.0.0 2023-05-06 08:51 UTC

Requires

• php: ^8.0
• illuminate/support: ^8.0|^9.0|^10.0
• intervention/image: ^2.5
• laravel/pint: ^1.10

Requires (Dev)

• laravel/legacy-factories: ^1.0
• orchestra/testbench: ^6.0|^7.0|^8.0
• phpunit/phpunit: ^9.3
• vimeo/psalm: ^5.0

MIT

• tzsk

• tzsk
• collage
• php collage
• image collage php
• create image collage laravel
• laravel image collage

README

Create Image Collage with ease now with PHP. This package uses intervention/image package to leverage image manipulation.

Using this package is very easy and creating Beautiful Collages are not tough anymore.

NOTE: Currently this package only supports 4 images. You can write your own generator to add 5 if you like.

📦 Installation

This is a composer package. So just run the below composer command inside your project directory to get it installed.

composer require tzsk/collage

⚙️ Configure

If you are using this package outside laravel then you don't need to do this step.

config/app.php

This package supports Package Auto-Discovery. And the latest version only supports Laravel >= 7.x

If you want to use any other driver besides 'gd' then you have to publish the configuration file:

php artisan collage:publish

You will then have a file in your config directory: config/collage.php

If you are using 'imagick' then you can change it.

🔥 Usage

First you need to have a set of images to make collage of. This package can except many kinds of Targets.

$images = [
    // List of images
    'images/some-image.jpg',
];

There are other kinds of image targets supported:

$images = [
    // 1. File Contents
    file_get_contents('some/image/path/or/url'),

    // 2. Direct URLs
    'https://some/image/url',

    // 3. Absolute & Relative Path
    '/some/image/somewhere/on/disk',

    // 4. Intervention\Image\Image Object
    ImageManagerStatic::make('...'),
    // It's Intervention\Image\ImageManagerStatic

    // 5. Or if you are Using Laravel
    Image::make('...'),
    // It's Intervention\Image\Facades\Image
];

Depending upon the number of images in the array this package will automatically use the right Generator.

🌐 Examples Outside Laravel

Firstly, use the Class Namespace at the top.

use Tzsk\Collage\MakeCollage;

$collage = new MakeCollage($driver); // Default: 'gd'

The Driver is either 'gd' or 'imagick'. Depending upon which library you are using with PHP. You can customize that. The default is 'gd'.

Create collage with 1 Image

Supported, yes.

$image = $collage->make(400, 400)->from($images);

// Add Padding:
$image = $collage->make(400, 400)->padding(10)->from($images);

// Add Background Color:
$image = $collage->make(400, 400)->padding(10)->background('#000')->from($images);

Create collage with 2 images

$image = $collage->make(400, 400)->from($images); // Default Alignment: vertical

// Change Alignment:
$image = $collage->make(400, 400)->from($images, function($alignment) {
    $alignment->vertical(); // Default, no need to have the Closure at all.
    // OR...
    $alignment->horizontal();
});

You can also add padding() and background() here.

Create collage with 3 images

$image = $collage->make(400, 400)->from($images); // Default Alignment: twoTopOneBottom

// Change Alignment:
$image = $collage->make(400, 400)->from($images, function($alignment) {
    $alignment->twoTopOneBottom(); // Default, no need to have the Closure at all.
    // OR...
    $alignment->oneTopTwoBottom();
    // OR...
    $alignment->oneLeftTwoRight();
    // OR...
    $alignment->twoLeftOneRight();
    // OR...
    $alignment->vertical();
    // OR...
    $alignment->horizontal();
});

You can also add padding() and background() here.

Create collage with 4 images

$image = $collage->make(400, 400)->from($images); // Default Alignment: grid

// Change Alignment:
$image = $collage->make(400, 400)->from($images, function($alignment) {
    $alignment->grid(); // Default, no need to have the Closure at all.
    // OR...
    $alignment->vertical();
    // OR...
    $alignment->horizontal();
});

You can also add padding() and background() here.

😍 Examples in Laravel

In laravel you already have the Alias for the Collage Maker

use Tzsk\Collage\Facade\Collage;

$image = Collage::make(400, 400)->from($images);

The rest of the Features are same as when using in normal php.

Create collage with 1 Image

$image = Collage::make(400, 400)->from($images);

// Add Padding:
$image = Collage::make(400, 400)->padding(10)->from($images);

// Add Background Color:
$image = Collage::make(400, 400)->padding(10)->background('#000')->from($images);

Create collage with 2 images

$image = Collage::make(400, 400)->from($images); // Default Alignment: vertical

// Change Alignment:
$image = Collage::make(400, 400)->from($images, function($alignment) {
    $alignment->vertical(); // Default, no need to have the Closure at all.
    // OR...
    $alignment->horizontal();
});

You can also add padding() and background() here.

Create collage with 3 images

$image = Collage::make(400, 400)->from($images); // Default Alignment: twoTopOneBottom

// Change Alignment:
$image = Collage::make(400, 400)->from($images, function($alignment) {
    $alignment->twoTopOneBottom(); // Default, no need to have the Closure at all.
    // OR...
    $alignment->oneTopTwoBottom();
    // OR...
    $alignment->oneLeftTwoRight();
    // OR...
    $alignment->twoLeftOneRight();
    // OR...
    $alignment->vertical();
    // OR...
    $alignment->horizontal();
});

You can also add padding() and background() here.

Create collage with 4 images

$image = Collage::make(400, 400)->from($images); // Default Alignment: grid

// Change Alignment:
$image = Collage::make(400, 400)->from($images, function($alignment) {
    $alignment->grid(); // Default, no need to have the Closure at all.
    // OR...
    $alignment->vertical();
    // OR...
    $alignment->horizontal();
});

You can also add padding() and background() here.

🏆 Return Value

The reaturned $image is the instance of Intervention\Image\Image object.

You can do multiple things with it.

• You can save the final collage.
• You can just use it as a plain response.
• You can crop/resize/colorize and more.

Read more about what you can do in the Official Documentation.

🔌 Create Custom Generators

Creating a generator is very easy. Create a class that extends the abstract class: Tzsk\Collage\Contracts\CollageGenerator.

Example:

use Tzsk\Collage\Contracts\CollageGenerator;

class FiveImage extends CollageGenerator
{
    /**
     * @param Closure $closure
     * @return \Intervention\Image\Image
     */
    public function create($closure = null)
    {
        // Your code to generate the Intervention\Image\Image object
    }
}

NOTE: Take a look at src/Contracts/CollageGenerator.php for details about all the things you have access to in the generator class. Also, if you need a reference consider looking into: src/Generators/FourImage.php.

Extend outside laravel

$image = $collage->with([5 => Your\Class\Namespace\FiveImage::class]);
// Here the key is the number of file your generator accepts.
// After this you can continue chaining methods like ->padding()->from() as usual.

You can also override existing generators. Let's say you want to have the FourImage generator to behave differently. You can make your own MyFourImage class and add it.

$image = $collage->with([4 => Your\Class\Namespace\MyFourImage::class]);
// It will replace the existing Generator with your own.
// After this you can continue chaining methods like ->padding()->from() as usual.

Extend in laravel

$image = Collage::with([5 => Your\Class\Namespace\FiveImage::class]);
// Here the key is the number of file your generator accepts.
// After this you can continue chaining methods like ->padding()->from() as usual.

You can also override existing generators. Let's say you want to have the FourImage generator to behave differently. You can make your own MyFourImage class and add it.

$image = Collage::with([4 => Your\Class\Namespace\MyFourImage::class]);
// It will replace the existing Generator with your own.
// After this you can continue chaining methods like ->padding()->from() as usual.

You can also do this from the config/collage.php config file.

There is a generators array which is currently empty. You can add your own generators there like below to Replace or add new generators.

'generators' => [
    // It will replace the current FourImage generator.
    4 => Your\Class\Namespace\MyFourImage::class,

    // It will add a new generator.
    5 => Your\Class\Namespace\FiveImage::class,
]

🔬 Testing

composer test

📅 Changelog

Please see CHANGELOG for more information on what has changed recently.

❤️ Contributing

Please see CONTRIBUTING for details.

🔒 Security

If you discover any security related issues, please email [e-mail] instead of using the issue tracker.

👑 Credits

• Kazi Ahmed
• All Contributors

👮‍♂️ License

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