File: README.md

Recommend this page to a friend!

README.md

File:	`README.md`
Role:	Documentation
Content type:	`text/markdown`
Description:	Documentation
Class:	Laravel Model Images Store images in models and serve in multiple sizes
Author:	By Ahmed Saad
Last change:
Date:	3 years ago
Size:	`8,357 bytes`

Download

<img src="https://laravel.com/assets/img/components/logo-laravel.svg">
<h1 align="center">Model Images</h1>

this package make saving (uploading or from storage) images with any set of dimensions and attachs them to you model is very easy
just a few lines of code
<br>
for any customizations also have the full control of saving process

Dependencies

this library uses two providers one of intervention/image library and the other saad/image (My Package) for image manipulation the default provider is my package (saad/image) but you can switch between them as you wish and also you can create your own driver if you wish and use it.

Install

	composer require saad/laravel-model-images

Basic Usage

1- Model Setup

assume we have a model like User model has a string field called `image` this field will contains his profile image

all we need to do is in User Model File `User.php` we need to do:

1. implement `Saad\ModelImages\Contracts\ImageableContract` 2. use trait `Saad\ModelImages\Traits\HasImages` 3. define image fields for this model via defining a static method `imageableFields()` which will return array of image fields for the model


// User.php File
class User extends Autheticatable implements ImageableContract
{
    use HasImages;
    
    public static function imageableFields() {
        return ['image'];
    }
}

2- Store Images:

Now to set user profile image, assume in profile controller we have a method called uploadUserProfile responds to upload image request, and another method setUserProfile to set profile image from storage image file


// ProfilesController.php File
class ProfilesController
{		
    // Save Image From Upload Request    
    public function setUserProfile(Request $request, User $user) {
        // You can Validate
        $image = $request->file('image');
        if ($image) {
            $user->image = $image;
        }
        
        $user->save();
    }
    
    // Set Image from image file on storage
    public function setUserProfile() {
        $user = User::find(1);
        $user->image = storage_path('app/images/profile.png');
        $user->save();
    }
}

3- Public link

OK, for now we stored our user profile image, so how we can get our user profile image public link this is very easy just use $user->getImagePublicLink() it will get profile photo url by default all images will be stored inside public directory in the following directory images/uploads > this library uses the convention naming __getImageFieldPublicLink()__ > so if we have image field called profile_photo the method will be getProfilePhotoPublicLink()

Customization

1- Multiple image sizes:

to set custom sizes like thumbnails or different dimensions for your uploaded images all you need is to define __imageFieldImageSizes()__ method on your model

		
// User.php File
class User extends Autheticatable implements ImageableContract
{
    use HasImages;
    ...
    public function imageImageSizes() {
        return [
            [512, 512], // Full size version
            [256, 256], // Thumbnail version
            [46, 46],   // Thumbnail version
        ];
    }
}

> __Get Public links__ $user->getImagePublicLink() => for 512x512 $user->getImagePublicLink('256x256') => for 256x256 $user->getImagePublicLink('46x46') => for 46x46 Or yo can use general method getPublicLink($field) $user->getPublicLink('image') => for 512x512 $user->getPublicLink('image', '256x256') => for 256x256 $user->getPublicLink('image', '46x46') => for 46x46

2- Custom save directory:

to set custom save directory (within public folder) define method > imageGeneralSavePath() this method will set save path for all model image fields > > __imageFieldNameSavePath__ the naming convention used to set different paths for each field

		
// User.php File
class User extends Autheticatable implements ImageableContract
{
    use HasImages;
    ...
    // path for saving user profile images
    public function imageImageSavePath() :string
    {
        return 'images/users/profile';
    }
    
    // user model default saving directory for all model image fields if any
    public function imageGeneralSavePath() :string
    {
        return 'images/users';
    }
}

3- Custom save options:

you can control saving format, quality and png filters by defining those methods: > imageSaveExtension() defines image format default jpg > imageSaveQuality() defines image quality default 70 for jpg >> for jpg quality will be from 0 to 100 low to high quality >> for png quality will be from 0 to 9 high to low quality

> imagePNGFilter() defines png image filter default PNG_NO_FILTER

		
// User.php File
class User extends Autheticatable implements ImageableContract
{
    use HasImages;
    ...
    public function imageSaveExtension() :string
    {
        return 'png';
    }
    
    public function imageSaveQuality() :int
    {
        return 7;
    }
    
    public function imagePNGFilter() :int
    {
        return PNG_ALL_FILTERS;
    }
}

4- Custom save provider:

this package shipped with two image manipulation providers: > __Providers:__ > SaadImageProvider this is the default provider, it uses my image package saad/image for image manipulation process > InterventionImageProvider provider for famous package intervention/image for image manipulation process

> __Define Custom Provider:__ > you can define your custom provider class by implementing this interface Saad\ModelImages\Contracts\ImageProviderContract

> __Change Provider__ you can change driver be defining imageSaveProvider() method in your model, which should return the provider instance.

> __Note:__ > > There are difference between how intervention and my image library handle resizing images when width and height are defined and differs from original aspect > > __saad/image__ resize images to new dimensions by centering original image then resize and crop if necessary > > __intervention/image__ will stretch image to new size or will preserve aspect so it will respect one dimension and auto set the other according to original aspect > > if this note is not clear, you can try both providers and see.

		
// User.php File
class User extends Autheticatable implements ImageableContract
{
    use HasImages;
    ...
    public function imageSaveProvider() :ImageProviderContract
    {
        return new InterventionImageProvider;
    }

}

4- Default image:

Each model image field should have a default image, so consider the following cases: > 1-Record does not have image > when we try to get an image for a record which does not have an image attached yet > > 2- Record has image but file deleted or not exists > when we try to get an image for a record but this image file is deleted or not exists

for these reasons we should define default image for each field, and this package will automatically return this default image if one of the previous cases happens

__To set Default Image:__ defining a default image is the same process as attaching image to the model, the only difference is we tell the model that we are defining default image by calling the static method settingDefaultImage() on the model ex: User::settingDefaultImage() here we can see in action:


// ProfilesController.php File
class ProfilesController
{		
    // Set image field default image
    public function setDefaultProfileImage() {
        // telling User model we are defining default image
        User::settingDefaultImage();
        
        // assign default image
        $user = new User;
        $user->image = storage_path('app/images/default_profile.png');
    }
}