README.md

Attacher - Pictures attachment tool for Laravel

Upload for S3, Copy, Local, Anything, Manipulate and Attach Images in your Models

Current Build Status

Statistics

Tips

Installation

1 - Dependency

The first step is using composer to install the package and automatically update your composer.json file, you can do this by running:

composer require artesaos/attacher

or manually update your composer.json file

{
    "require": {
        "artesaos/attacher": "~0.6"
    }
}

2 - Provider

You need to update your application configuration in order to register the package so it can be loaded by Laravel, just update your config/app.php file adding the following code at the end of your 'providers' section:

// file START ommited
    'providers' => [
        // other providers ommited
        \Artesaos\Attacher\Providers\AttacherServiceProvider::class,
    ],
// file END ommited

3 - Facade

Optional. You do not need to register the Facade of Attacher, but if you want to have access to some shortcuts feel free to use it.

In order to use the Attacher facade, you need to register it on the config/app.php file, you can do that the following way:

<?php
# config/app.php

// file START ommited
    'aliases' => [
        // other Facades ommited
        'Attacher'   => \Artesaos\Attacher\Facades\Attacher::class,
    ],
// file END ommited

3.1 - Facade API

Attacher::process(Model $model);
Attacher::getPath();
Attacher::setPath($path);
Attacher::setBaseURL($url);
Attacher::getProcessor();
Attacher::getInterpolator();

4 - Configuration

Run in your console php artisan vendor:publish, now you have 3 new files, config/attacher.php, config/flysystem.php and database/migrations/2015_03_28_000000_create_attacher_images_table.php

Attacher need graham-campbell/flysystem Don't worry, Attacher registers the flysystem service automatically for you.

In the config/app.php file, you can configure the destination path and the styles guides to manipulate the images.

return [
    'model'    => 'Artesaos\Attacher\AttacherModel', # You can customize the model for your needs.
    'base_url' => '', # The url basis for the representation of images.
    'path'     => '/uploads/images/:id/:style/:filename', # Change the path where the images are stored.

    'style_guides'   => [
        'default' => [
            # If you set the original style all other styles used his return to base
            'original'=> function($image)
            {
                return $image->insert('public/watermark.png');
            },

            # Generate thumb (?x500)
            'thumb' => function ($image) {
                $image->resize(null, 500, function ($constraint) {
                    $constraint->aspectRatio();
                    $constraint->upsize();
                });

                return $image;
            },
        ],
        'my_custom_style' => [
            # Generate thumb (460x120)
            'cover' => function ($image) {
                $image->fit(460, 120);

                return $image;
            }
        ],
    ]
];

Usage

The usage is very simple. The image destination information are in flysystem configuration file config/flysystem.php there you define which provider to use for uploading.

1 - Basic

$upload = Input::file('image');

$image = new \Artesaos\Attacher\AttacherModel();
$image->setupFile($upload); # attach image
$image->save(); # now attacher process file (generate styles and save in your provider configured in flysystem)

echo $image->url('original');
echo $image->url('thumb'); // your style

1.1 - Using Styles Guide

Using a specific guide style to manipulate the images:

$upload = Input::file('image');

$image = new \Artesaos\Attacher\AttacherModel();
$image->setupFile($upload, 'custom_style'); # attach image using the "custom_style"
$image->save();

echo $image->url('cover'); // The "cover" setted in "my_custom_style" of the config/attacher.php file

It is possible to change the style setted in config/attacher.php, by passing an array keyed by the style guide and the style that you wish to change. The array values should be Closure instances which receive the \Intervention\Image\Image:

$upload = Input::file('image');

$image = new \Artesaos\Attacher\AttacherModel();
$image->setupFile($upload, [
    'my_custom_style' => [
        # Generate thumb (30x30)
        'cover' => function ($image) {
            $image->fit(30, 30);

            return $image;
        }
    ]
]); # attach image using the "my_custom_style" changed by Closure
$image->save();

echo $image->url('cover'); // Now, the "cover" generates a resized image of 30 by 30 pixels

Or use dot notation to change style:

$upload = Input::file('image');

$image = new \Artesaos\Attacher\AttacherModel();
$image->setupFile($upload, [
    'my_custom_style.cover' => function ($image) {
        $image->fit(30, 30);

        return $image;
    }
]); # attach image using the "my_custom_style" changed by Closure
$image->save();

echo $image->url('cover'); // Now, the "cover" generates a resized image of 30 by 30 pixels

2 - Traits

Attacher provides you two traits to facilitate the creation of galleries/collections of images linked to other objects using the technique morphMany and morphOne

2.1 - HasImages

Bond with many images

#app/Project.php
namespace App;

use Illuminate\Database\Eloquent\Model;
use Artesaos\Attacher\Traits\HasImage;

class Projects extends Model
{
    use HasImages;

    protected $table = 'projects';
}

////

$upload = Input::file('image');

$project = Projects::find(73);

$image = $project->addImage($upload); # Create a new image, save model and save image file with your styles

echo $image->url('thumbnail');

////

$project = Projects::find(73);

# Collection of images
$images = $project->images;

The method addImage() has the same attributes of the method setupFile() of the AttachModel:

$model->addImage(UploadedFile $image, $styleGuide = null, $type = null);

2.2 - HasImage [WIP]

Link to an image

#app/People.php
namespace App;

use Illuminate\Database\Eloquent\Model;
use Artesaos\Attacher\Traits\HasImage;

class People extends Model
{
    use HasImage;

    protected $table = 'people';
}

////

$upload = Input::file('image');

$people = People::find(73);

$image = $people->addImage($upload); # Create a new image, save model and save image file with your styles

echo $image->url('thumbnail');

////

$people = People::find(73);

echo $people->image->url('original');

The method addImage() has the same attributes of the method setupFile() of the AttachModel:

$model->addImage(UploadedFile $image, $styleGuide = null, $type = null);

3 - Setting a Image Model Type

Sometimes you may need to specify a type of image model. For example, when a product there are images for listing and images for gallery. To do so, just pass additional third argument to the method:

$people = People::find(73);

$upload = Input::file('image');
$people->addImage($upload, 'default', 'listing'); # attach image using the "listing" custom guide style

$upload2 = Input::file('image2');
$people->addImage($upload2, 'default', 'gallery'); # attach image using the "gallery" custom guide style

$listingImages = $people->images->ofType('listing'); // Get images of the listing
$galleryImages = $people->images->ofType('gallery'); // Get images of the gallery

Author

Vinicius Reis