PHPackages                             outerweb/image-library - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. outerweb/image-library

ActiveLibrary

outerweb/image-library
======================

Store and link files to your models

v3.0.2(2mo ago)1113.0k↓44.8%1[4 PRs](https://github.com/outer-web/image-library/pulls)1MITPHPPHP ^8.4CI passing

Since Feb 16Pushed 2mo ago1 watchersCompare

[ Source](https://github.com/outer-web/image-library)[ Packagist](https://packagist.org/packages/outerweb/image-library)[ Docs](https://github.com/outer-web/image-library)[ GitHub Sponsors](https://github.com/outer-web)[ RSS](/packages/outerweb-image-library/feed)WikiDiscussions main Synced 1mo ago

READMEChangelogDependencies (42)Versions (21)Used By (1)

Image Library
=============

[](#image-library)

[![Latest Version on Packagist](https://camo.githubusercontent.com/6b9722631e19471879a7612961927942a3a6075d97d996d0f0476b7b5458b737/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f6f757465727765622f696d6167652d6c6962726172792e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/outerweb/image-library)[![GitHub Tests Action Status](https://camo.githubusercontent.com/4574ab9a817cac348b5a3cff5f0cf00c9d2a920153ff5e21363a2703cf7b2c2e/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f616374696f6e732f776f726b666c6f772f7374617475732f6f757465727765622f696d6167652d6c6962726172792f72756e2d74657374732e796d6c3f6272616e63683d6d61696e266c6162656c3d7465737473267374796c653d666c61742d737175617265)](https://github.com/outer-web/image-library/actions?query=workflow%3Arun-tests+branch%3Amain)[![GitHub Code Style Action Status](https://camo.githubusercontent.com/5071e0dbbd076ee284734ca339e99c86e846530f5fc457e541b8819c4049325a/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f616374696f6e732f776f726b666c6f772f7374617475732f6f757465727765622f696d6167652d6c6962726172792f6669782d7068702d636f64652d7374796c652d6973737565732e796d6c3f6272616e63683d6d61696e266c6162656c3d636f64652532307374796c65267374796c653d666c61742d737175617265)](https://github.com/outer-web/image-library/actions?query=workflow%3A%22Fix+PHP+code+style+issues%22+branch%3Amain)[![Total Downloads](https://camo.githubusercontent.com/071ffd13ae807e79e7dc29ae5a41e08b15631a5f00886a3bc0c48c5e1e7f3eec/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f6f757465727765622f696d6167652d6c6962726172792e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/outerweb/image-library)

A powerful Laravel package for managing images with responsive breakpoints, automatic optimization, and contextual configurations. Store and link images to your models with advanced features like automatic WebP generation, responsive image versions, and flexible image contexts.

> ⚠️ **Caution:** V3 is a complete rewrite of the package and logic. Please take a look at the [upgrade guide](./docs/upgrade-to-v3.md) before upgrading from v2.x to v3.x.

Table of Contents
-----------------

[](#table-of-contents)

- [Requirements](#requirements)
- [Installation](#installation)
- [Core concepts](#core-concepts)
    - [SourceImages](#sourceimages)
    - [Images](#images)
    - [ImageContexts](#imagecontexts)
    - [Breakpoints](#breakpoints)
- [Configuration](#configuration)
    - [The config file](#the-config-file)
    - [Javascript](#javascript)
    - [Defining ImageContexts](#defining-imagecontexts)
    - [Custom Breakpoints](#custom-breakpoints)
- [Usage](#usage)
    - [Uploading an image](#uploading-an-image)
    - [Attaching an image to your model](#attaching-an-image-to-your-model)
    - [Using your model image(s)](#using-your-model-images)
    - [Rendering images](#rendering-images)
- [Upgrading](#upgrading)
- [Changelog](#changelog)
- [License](#license)

Requirements
------------

[](#requirements)

This package uses [spatie/image](https://github.com/spatie/image) for image manipulations, so it requires the GD or Imagick PHP extension.

Installation
------------

[](#installation)

You can install the package via composer:

```
composer require outerweb/image-library
```

Run the install command to publish the migrations, config file, and service provider:

```
php artisan image-library:install
```

This will:

- Publish the configuration file to `config/image-library.php`
- Copy and register the `ImageLibraryServiceProvider` in your application
- Publish the database migrations
- Optionally run the migrations

Core concepts
-------------

[](#core-concepts)

### SourceImages

[](#sourceimages)

SourceImages are the original images uploaded to the system. They are not directly linked to any model. They are meant for internal use in this package.

### Images

[](#images)

Images are the link between a SourceImage and your Model(s). The Image has a `BelongsTo` relationship to the SourceImage and a `MorphTo` relationship to your Model.

You can see these as an instance of the uploaded images in a specific use case. You can define the use case using the `context` attribute on the Image model.

### ImageContexts

[](#imagecontexts)

ImageContexts allow you to define a configuration for images used in a specific way. Examples include "profile\_picture", "thumbnail", "gallery\_entry", "hero", etc.

They are fully customizable and should be defined in the ImageServiceProvider or in a custom service provider.

Images get generated based on the defined ImageContext when the Image model gets created or updated. This is based on the image\_context\_hash that is stored per Image. It is a hashed version of the whole configuration so that changes in the context will trigger regeneration of the images.

#### WebP versions

[](#webp-versions)

This package also generates WebP versions of images for better performance in modern browsers. You can configure whether to generate WebP versions globally in the config file or per ImageContext.

#### Responsive versions

[](#responsive-versions)

The package supports generating multiple responsive versions of images based on defined breakpoints. You can configure the sizes and aspect ratios for each breakpoint in the ImageContext, ensuring optimal display across different devices.

Each breakpoint can have a minimum and maximum width defined in the context. This allows the package to generate only necessary image sizes based on your design requirements.

### Breakpoints

[](#breakpoints)

Breakpoints define responsive screen sizes for image optimization. The package uses a Breakpoint enum that follows Tailwind CSS conventions, allowing you to specify different image configurations for various screen sizes.

Available breakpoints:

- **`Breakpoint::Small`** (`'sm'`): 640px and up - Mobile devices in landscape, small tablets
- **`Breakpoint::Medium`** (`'md'`): 768px and up - Tablets in portrait mode
- **`Breakpoint::Large`** (`'lg'`): 1024px and up - Tablets in landscape, small desktops
- **`Breakpoint::ExtraLarge`** (`'xl'`): 1280px and up - Desktop screens
- **`Breakpoint::DoubleExtraLarge`** (`'2xl'`): 1536px and up - Large desktop screens

You can use these breakpoints to define different aspect ratios, sizes, crop positions, and effects for different screen sizes, ensuring optimal image display across all devices.

> **Note:** If the default breakpoints don't match your design system, you can create custom breakpoints. See [Custom Breakpoints](#custom-breakpoints) in the Configuration section.

If you don't need responsive images, you can disable breakpoints globally in the config file or per ImageContext.

Configuration
-------------

[](#configuration)

### The config file

[](#the-config-file)

The config file allows you to customize various aspects of the image library. Some key configuration options include:

- **`defaults.disk`**: The default filesystem disk for storing images if not specified during upload
- **`use_breakpoints`**: Enable or disable responsive breakpoints globally
- **`generate.webp`**: Automatically generate WebP versions of images if not specified in the image context
- **`generate.responsive_versions`**: Generate multiple sizes for responsive images if not specified in the image context
- **`defaults.crop_position`**: Default crop position for image transformations if not specified in the image context
- **`models`**: Customize the Eloquent models used by the package to easily extend functionality
- **`enums`**: Customize the enums used by the package to easily extend functionality
- **`spatie_image.driver`**: Choose between 'gd' or 'imagick' for image manipulations

### Javascript

[](#javascript)

The package includes a JavaScript component that automatically sets the `sizes` attribute on `picture` elements rendered by the package. This ensures that the browser selects the most appropriate image size based on the actual display size of the image.

To include the script, add the following Blade component to the `` section of your layout:

```

```

### Defining ImageContexts

[](#defining-imagecontexts)

ImageContexts are defined in your application's `ImageLibraryServiceProvider` that gets published during installation. This provider extends the base service provider and allows you to define contexts in the `imageContexts()` method:

```