PHPackages                             ziffmedia/laravel-eloquent-imagery - 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. [Image & Media](/categories/media)
4. /
5. ziffmedia/laravel-eloquent-imagery

ActiveLibrary[Image & Media](/categories/media)

ziffmedia/laravel-eloquent-imagery
==================================

Image handling per column/attribute for Laravel Eloquent

v2.0.2(1y ago)9178.9k↓19.5%5[1 PRs](https://github.com/ziffmedia/laravel-eloquent-imagery/pulls)MITPHPPHP ^8.1

Since Aug 22Pushed 5mo ago18 watchersCompare

[ Source](https://github.com/ziffmedia/laravel-eloquent-imagery)[ Packagist](https://packagist.org/packages/ziffmedia/laravel-eloquent-imagery)[ RSS](/packages/ziffmedia-laravel-eloquent-imagery/feed)WikiDiscussions master Synced 1mo ago

READMEChangelog (3)Dependencies (3)Versions (82)Used By (0)

Laravel Eloquent Imagery
========================

[](#laravel-eloquent-imagery)

Description
-----------

[](#description)

`ziffmedia/laravel-eloquent-imagery` takes a unique approach to handling images. Instead of treating images as model relations, they are treated as attributes of a model. To this end, image information is stored in a tables column (a model's attribute) at a given name. Additionally, this library handles image modifications (resizing, triming, backgrounds) when serving the image instead of at upload time. Images are stored in any of the configured kinds of file storage that Laravel supports.

Features:

- images are tracked in same table's column
- setup is handled by adding a trait and a method per image type
- modifications can be made by manipuliating the image's url
- placeholder generation is supported
- fallback to a placeholdler (mainily for dev purposes) is supported when the image is not on the disk

### Other Good Libraries

[](#other-good-libraries)

If this solution to the image problem does not appeal to you, [Spatie's MediaLibrary](https://github.com/spatie/laravel-medialibrary)is an excellent library that both treats images as Models as a Relation, and also has a concept of "conversions" that can be applied at upload time.

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

[](#installation)

First, install the package:

```
$ composer require ziffmedia/laravel-eloquent-imagery

```

In Laravel 5.5+. this library will self-register. Next, you should publish the vendor (config) files:

```
$ artisan vendor:publish --provider="ZiffMedia\LaravelEloquentImagery\EloquentImageryProvider"

```

It is now ready to use.

Usage
-----

[](#usage)

### Attaching An Image To A Model

[](#attaching-an-image-to-a-model)

In the simplest use case for a single image attached to a model, first create a `json` column in a migration to handle this image:

```
// in a table migration
$table->json('image')->nullable();
```

Next, in the model, add in the HasEloquentImagery trait and configure a class property called `$eloquentImagery` like so:

```
use ZiffMedia\LaravelEloquentImagery\Eloquent\HasEloquentImagery;

class Post extends Model
{
    use HasEloquentImagery;

    protected $eloquentImagery = [
        'path' => 'posts/{id}.{extension}',
    ];
}
```

### Attaching an Image Collection To A Model

[](#attaching-an-image-collection-to-a-model)

An Image Collection is a ordered list of Image objects. The collection itself when hydrated has images that are indexable starting at 0. Each collection has a concept of an *auto increment* number which is stored in the collection (and the collection's serialization) so that Image objects can take advantage of this in the path template.

In the simplest use case, using a `json` column like in the direct image scenario above, add in the `HasEloquentImagery` trait as before, and use the `eloquentImageryCollection` method at construction to setup the collection:

```
use ZiffMedia\LaravelEloquentImagery\Eloquent\HasEloquentImagery;

class Post extends Model
{
    use HasEloquentImagery;

    protected $eloquentImagery = [
        'images' => [
            'path' => 'post/{id}/image-{index}.{extension}',
            'collection' => true
        ],
    ];
}
```

### Displaying An Image In A View

[](#displaying-an-image-in-a-view)

The following blade syntax assumes $post is a Model of type Post with an `image` attribute. This will generate a url similar to `/imagery/post/11/image.png`:

```
@if($bam->image->exists)

@endif
```

Using modifiers when generating the url, a url generated such as `/imagery/post/11/image.@size200x200@trim.png`

```
@if($bam->image->exists)

@endif
```

Image Modifiers
---------------

[](#image-modifiers)

TODO

Detailed Configuration
----------------------

[](#detailed-configuration)

The following table describes the available configuration options:

##### `eloquent-imagery.filesystem`

[](#eloquent-imageryfilesystem)

Default: `env('IMAGERY_FILESYSTEM', 'public')`

This is the filesystem images will be stored on at the image's path.

##### `eloquent-imagery.render.enable`

[](#eloquent-imageryrenderenable)

Default: `true`

Whether or not to enable the render *route* and modification functionality.

##### `eloquent-imagery.render.path`

[](#eloquent-imageryrenderpath)

Default: `/imagery`

The path prefix the route will live at and serve images from.

##### `eloquent-imagery.render.placeholder.enable`

[](#eloquent-imageryrenderplaceholderenable)

Default: `env('IMAGERY_RENDER_PLACEHOLDER_ENABLE', false)`

Highly useful for dev purposes, consider enabling in local.

##### `eloquent-imagery.render.placeholder.filename`

[](#eloquent-imageryrenderplaceholderfilename)

default value `_placeholder_`

This identifies when a placeholder image is being requested.

##### `eloquent-imagery.render.placeholder.use_for_missing_files`

[](#eloquent-imageryrenderplaceholderuse_for_missing_files)

default value `env('IMAGERY_RENDER_PLACEHOLDER_USE_FOR_MISSING_FILES', false)`

If an image is requested that is not on the filesystem, enabling this will serve a placeholder instead (useful for dev).

##### `eloquent-imagery.render.caching.enable`

[](#eloquent-imageryrendercachingenable)

default value `env('IMAGERY_RENDER_CACHING_ENABLE', true)`

Whether or not the controller should use full request caching

##### `eloquent-imagery.render.caching.driver`

[](#eloquent-imageryrendercachingdriver)

default value `env('IMAGERY_RENDER_CACHING_DRIVER', 'disk')`

Cache to the disk.

##### `eloquent-imagery.render.caching.ttl`

[](#eloquent-imageryrendercachingttl)

default value `60`

How long the ttl for the cache is.

##### `eloquent-imagery.render.browser_cache_max_age`

[](#eloquent-imageryrenderbrowser_cache_max_age)

default value `31536000`

How long the browser should cache the image generated by this route for.

##### `eloquent-imagery.force_unmodified_image_rendering`

[](#eloquent-imageryforce_unmodified_image_rendering)

default value `env('IMAGERY_FORCE_UNMODIFIED_IMAGE_RENDERING', false)`

This will allow for the dynamic (controller) route or static route (link to storage, for example) to be selectively used based on if modifiers are present in the image request

Demo
----

[](#demo)

Once cloned, `cd demo` directory. Inside there do the following:

```
composer install
artisan migrate
artisan db:seed
artisan serve
```

If you wish to demo the Nova specific capabilities, you must first install the downloadable version of nova to `demo/nova`. Once it is there, continue with the above script from the top, then visit the examples at `/nova` in your browser.

TODO
----

[](#todo)

- support moving images as a result of updated path parts (attribute update, etc)

Updating
--------

[](#updating)

### Updating to 0.5.0

[](#updating-to-050)

- make sure to rename the `config/eloquent_imagery.php` to `config/eloquent-imagery.php`, probably a good idea to re-copy the original (or publish again).
- see the new method of configuring a model to use an image: use a property called `$eloqentImagery`

###  Health Score

55

—

FairBetter than 98% of packages

Maintenance60

Regular maintenance activity

Popularity40

Moderate usage in the ecosystem

Community22

Small or concentrated contributor base

Maturity82

Battle-tested with a long release history

 Bus Factor1

Top contributor holds 85.4% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~39 days

Recently: every ~95 days

Total

53

Last Release

431d ago

Major Versions

v0.11.1 → v1.0.0-beta.12021-04-08

v0.11.2 → v1.0.0-beta.22021-04-30

v0.11.5 → v1.0.0-beta.52021-09-22

v0.11.7 → v1.0.0-rc.12022-07-27

v1.0.1 → v2.0.0-beta.12023-01-25

PHP version history (3 changes)v0.7.0PHP ^7.1

v0.10.12PHP ^7.2|^8.0

v1.0.0-rc.1PHP ^8.1

### Community

Maintainers

![](https://www.gravatar.com/avatar/9c4a15cb4e97bc39a3aea8304fb04d56c0d753f2a6b79c83db0a894647ba8de7?d=identicon)[ralphschindler](/maintainers/ralphschindler)

![](https://www.gravatar.com/avatar/fff234ab9d8ee835e721f4594a9c6521ec0f244bfbd7e700a0d8902e5f22ed1e?d=identicon)[jimbojsb](/maintainers/jimbojsb)

---

Top Contributors

[![ralphschindler](https://avatars.githubusercontent.com/u/76674?v=4)](https://github.com/ralphschindler "ralphschindler (70 commits)")[![ivanmarchenko83](https://avatars.githubusercontent.com/u/38218499?v=4)](https://github.com/ivanmarchenko83 "ivanmarchenko83 (4 commits)")[![setonb](https://avatars.githubusercontent.com/u/1192514?v=4)](https://github.com/setonb "setonb (3 commits)")[![jcarouth](https://avatars.githubusercontent.com/u/34648?v=4)](https://github.com/jcarouth "jcarouth (2 commits)")[![emarshall87](https://avatars.githubusercontent.com/u/3854798?v=4)](https://github.com/emarshall87 "emarshall87 (1 commits)")[![coopers98](https://avatars.githubusercontent.com/u/116313?v=4)](https://github.com/coopers98 "coopers98 (1 commits)")[![dependabot[bot]](https://avatars.githubusercontent.com/in/29110?v=4)](https://github.com/dependabot[bot] "dependabot[bot] (1 commits)")

###  Code Quality

TestsPHPUnit

Code StyleLaravel Pint

### Embed Badge

![Health badge](/badges/ziffmedia-laravel-eloquent-imagery/health.svg)

```
[![Health](https://phpackages.com/badges/ziffmedia-laravel-eloquent-imagery/health.svg)](https://phpackages.com/packages/ziffmedia-laravel-eloquent-imagery)
```

###  Alternatives

[milon/barcode

Barcode generator like Qr Code, PDF417, C39, C39+, C39E, C39E+, C93, S25, S25+, I25, I25+, C128, C128A, C128B, C128C, 2-Digits UPC-Based Extention, 5-Digits UPC-Based Extention, EAN 8, EAN 13, UPC-A, UPC-E, MSI (Variation of Plessey code)

1.5k13.3M39](/packages/milon-barcode)[bkwld/croppa

Image thumbnail creation through specially formatted URLs for Laravel

510496.0k23](/packages/bkwld-croppa)[goat1000/svggraph

Generates SVG graphs

132849.6k3](/packages/goat1000-svggraph)[cohensive/embed

Media Embed (for Laravel or as a standalone).

120370.4k](/packages/cohensive-embed)[netresearch/rte-ckeditor-image

Image support in CKEditor for the TYPO3 ecosystem - by Netresearch

63991.3k4](/packages/netresearch-rte-ckeditor-image)[humanmade/tachyon-plugin

Rewrites WordPress image URLs to use Tachyon

87338.5k2](/packages/humanmade-tachyon-plugin)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)