PHPackages                             shishima/laravel-thumbnail - 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. [PDF & Document Generation](/categories/documents)
4. /
5. shishima/laravel-thumbnail

ActiveLaravel-package[PDF & Document Generation](/categories/documents)

shishima/laravel-thumbnail
==========================

This package is used to create thumbnail images for document files. It supports the following file types: doc, docx, xls, xlsx, pdf, gif, jpg, jpeg, png.

v2.1.0(1y ago)1731MITPHPPHP >=8.0

Since Jun 29Pushed 1y ago1 watchersCompare

[ Source](https://github.com/shishima123/laravel-thumbnail)[ Packagist](https://packagist.org/packages/shishima/laravel-thumbnail)[ Docs](https://github.com/shishima123/laravel-thumbnail)[ RSS](/packages/shishima-laravel-thumbnail/feed)WikiDiscussions master Synced 1mo ago

READMEChangelog (4)Dependencies (5)Versions (4)Used By (0)

Laravel Document Thumbnail
==========================

[](#laravel-document-thumbnail)

This package is used to create thumbnail images for document or image files. It supports the following file formats: doc, docx, xls, xlsx, pdf, gif, jpg, jpeg, png.

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

[](#requirements)

This package only works on a Linux environment. In order to use it, the following libraries must be pre-installed on the Linux environment:

#### libmagickwand

[](#libmagickwand)

```
sudo apt-get install libmagickwand-dev --no-install-recommends

```

#### ghostscript

[](#ghostscript)

```
sudo apt-get install ghostscript

```

#### libreoffice

[](#libreoffice)

```
sudo apt-get install libreoffice

```

#### unoconv

[](#unoconv)

```
sudo apt-get install unoconv

```

Those installation commands are for reference only, and the specific commands to use depend on the corresponding distribution. Please use the appropriate commands for your distribution to ensure accurate installation.

#### Imagick

[](#imagick)

This package uses the Imagick extension of PHP to create thumbnail files, so it is necessary to install this extension.

```
sudo apt install php-imagick

//then

sudo apt list php-magick -a

```

After installation, remember to restart the server to activate the extension.

Copy the `policy.xml` file to the path `/etc/ImageMagick-6/policy.xml`. This file is used to grant Imagick read and write permissions for PDF files.

Copy the `Module1.xba` file to the path `/usr/lib/libreoffice/presets/basic/Standard/Module1.xba`. This file is used to fix the line break issue when creating thumbnails for Excel files.

### Docker

[](#docker)

If you are using Docker, you can add the following lines to your Dockerfile to install the necessary libraries for Linux:

```
# Install dependencies
RUN apt-get update && apt-get install -y \
    libmagickwand-dev --no-install-recommends \
    ghostscript \
    libreoffice \
    unoconv

# Install php extensions
RUN pecl install imagick
RUN docker-php-ext-enable imagick

```

Copy the `policy.xml` and `Module1.xba` files into the same directory as the `docker-compose.yml` file.

Then, add them to the `volumes` section of the app.

```
laravel_app:
    // ***
    volumes:
      // ***
      - ./policy.xml:/etc/ImageMagick-6/policy.xml
      - ./Module1.xba:/usr/lib/libreoffice/presets/basic/Standard/Module1.xba

```

For more information, please refer to the Docker directory.

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

[](#installation)

Install by using composer:

```
composer require shishima/laravel-thumbnail

```

### Publish config

[](#publish-config)

```
php artisan vendor:publish --provider="Shishima\Thumbnail\ThumbnailServiceProvider" --tag="thumbnail-config"

```

After publishing the configuration file, you can edit the app/config/thumbnail file to customize the settings.

#### Publish default thumbnail icon

[](#publish-default-thumbnail-icon)

```
php artisan vendor:publish --provider="Shishima\Thumbnail\ThumbnailServiceProvider" --tag="thumbnail-assets"

```

A default file is published to the path `public/vendor/laravel_thumbnail/Thumbnail-default.svg`. This path is used to specify the default file. You can change it to a different path if necessary.

The `default` config is used in case the file is not in the list of supported thumbnail file types. In this case, a default icon can be used as a replacement. You can disable this feature by setting `enable = false`.

### Notes

[](#notes)

#### Disks

[](#disks)

The configuration section `disks` includes two configurations:

- The **disks.temp\_thumbnail** configuration is utilized to temporarily clone the original file to the temp directory during the thumbnail creation process.
    This allows for modifications to be made to the file before generating the thumbnail. Once the thumbnail is generated, the temporary file is deleted.
- The **disk.thumbnail** configuration is used to store the generated thumbnail files.

By default, these files are stored in the storage directory. If you opt to use the default configuration, you will need to create a symbolic link to the public directory.

```
php artisan storage:link

```

You can customize these settings as necessary.

### Ignore extensions

[](#ignore-extensions)

By default, the package supports the following file extensions: doc, docx, xls, xlsx, pdf, gif, jpg, jpeg, png. However, if you want to exclude a specific extension from being processed, you can add it to the `ignore_extensions` list.

```
'ignore_extensions' => ['png', 'jpg']
```

Usage
-----

[](#usage)

### Create thumbnail file

[](#create-thumbnail-file)

To use the package, you can use the `Thumbnail` facade:

```
use Shishima\Thumbnail\Facade\Thumbnail;

Thumbnail::setFile($file)->create();
```

In this example, the file can be a path to a file on the system:

```
use Shishima\Thumbnail\Facade\Thumbnail;

$file = public_path('files/example.docx');
Thumbnail::setFile($file)->create();
```

Or it could be a file retrieved from the `request` when using the `POST` method in a form submit with ``.

```
use Shishima\Thumbnail\Facade\Thumbnail;

Thumbnail::setFile($request->file('file'))->create();
```

The `setFile` method is used to pass in the file that will have its thumbnail generated, or it can be done by passing the file as a parameter to the `create` method.

```
Thumbnail::create($file);
```

The data returned by the `create` function will have the following format:

```
[
    'name' => 'thumbnail_name',
    'origin_name' => 'thumbnail_origin_name'
    'path' => 'path to file'
]
```

### Changing options

[](#changing-options)

The default options can be configured in the `app/config/thumbnail` file, but they can still be changed during the thumbnail generation process by using the following methods:

#### setHeight

[](#setheight)

Changes the default height:

```
Thumbnail::setHeight(100)->create($file);
```

#### setWidth

[](#setwidth)

Changes the default width:

```
Thumbnail::setWidth(100)->create($file);
```

#### setSize

[](#setsize)

Changes both the default width and height:

```
Thumbnail::setSize(width: 200, height: 200)->create($file);
```

#### setFormat

[](#setformat)

Changes the default format of the thumbnail:

```
Thumbnail::setFormat('png')->create($file);
```

#### setLayer

[](#setlayer)

If the generated thumbnail image is not displayed correctly, you can try changing the layer parameter:

```
Thumbnail::setLayer(20)->create($file);
```

#### setOptions

[](#setoptions)

To change multiple options at once, you can use the `setOptions` method and pass in an array of options:

**IMPORTANT!** The package only supports changing: width, height, layer, and format options.

```
$options = [
        'width' => 200,
        'height' => 200,
        'format' => 'png',
        'layer' => 20
    ];
Thumbnail::setOptions($options)->create($file);
```

#### doNotRemoveTempFileAfterConvert

[](#donotremovetempfileafterconvert)

By default, the temporary file will be automatically deleted upon completion. Using this function, the temporary file will not be deleted after the conversion is completed.

```
Thumbnail::doNotRemoveTempFileAfterConvert()->create($file);
```

#### shouldRemoveTempFileAfterConvert

[](#shouldremovetempfileafterconvert)

Contrary to `shouldRemoveTempFileAfterConvert`, the temporary file will be deleted.

```
Thumbnail::shouldRemoveTempFileAfterConvert()->create($file);
```

**IMPORTANT!** By default, the temporary file will be automatically deleted upon completion.

Model events
------------

[](#model-events)

This feature relies on the model events feature of Laravel. When a request with a file upload is saved to the database, the thumbnail will be automatically created.

### Publish migration

[](#publish-migration)

This package comes with a migration file that is used to create the thumbnails table which is used to store records of the recently created thumbnail.

To publish:

```
php artisan vendor:publish --provider="Shishima\Thumbnail\ThumbnailServiceProvider" --tag="thumbnail-migrations"

```

Migrate table after publish:

```
php artisan migrate

```

#### Customize migration file

[](#customize-migration-file)

To customize the columns in the thumbnails table, you can change the generated migration file.

After modifying the migration file, use the `php artisan migrate` command to create a new table.

To add new columns, you can refer to [Custom Data Save](#custom-data-save) to add the data.

### Change table name

[](#change-table-name)

To change the table name, you can change `table_name` in the `app/config/thumbnail` file.

### Change model

[](#change-model)

By default, the package will use the `\Shishima\Thumbnail\Models\Thumbnail::class` model to save data to the database.

You can change this by changing `thumbnail_model` in the `app/config/thumbnail` file.

### Usage

[](#usage-1)

To use the automatic thumbnail creation feature, add the `HasThumbnail` trait to the Model class:

For example:

```
use Shishima\Thumbnail\HasThumbnail;

class Document extends Models
{
    use HasThumbnail;
    //
}
```

### Thumbnail Event Trigger Configuration

[](#thumbnail-event-trigger-configuration)

After adding HasThumbnail, you will need to specify the $thumbnailEventTriggerColumn. This column will store the path of the file for which you want to generate a thumbnail.

```
protected static string $thumbnailEventTriggerColumn = 'file_path';
```

### Disk Configuration

[](#disk-configuration)

By default, the package will check files using Laravel's Storage class.

If you save files using Laravel's Storage and your disk is different from the `filesystems.default` configured in `config/filesystems`, you need to configure the disk information by:

```
protected static function getDiskOfFileUploaded(): string
{
    return 'local_public';
}
```

**IMPORTANT!** The current version of the package only supports disks stored locally. Cloud storage will be supported in the future.

### Custom Events

[](#custom-events)

The package offers support for two events: `saved` and `updated`. If you wish to customize these events, you can achieve that by setting the `$thumbnailEvents` attribute in the model file.

```
protected static $thumbnailEvents = ['saved'];
```

**IMPORTANT!** The package only supports 2 events: `saved` and `updated`. Therefore, other events cannot be added and are not supported."

### Disable

[](#disable)

To disable the thumbnail creation feature, use the `$doNotCreateThumbnail` property:

```
protected static $doNotCreateThumbnail = true;
```

### Options

[](#options)

To customize the options in the Model, use the `$thumbnailOptions` property:

```
protected static array $thumbnailOptions = [
    'height' => 200,
    'width' => 200,
    'format' => 'png',
    'layer' => 12
];
```

### Custom Data Save

[](#custom-data-save)

To customize the data before saving, you can use `$thumbnailSaveData`:

```
protected static function thumbnailSaveData($thumbnail, $file, $model): array
{
    return [
        'name' => 'custom_name',
    ];
}
```

The parameters passed are:

- **$thumbnail** Data returned by the Thumbnail Facade
- **$file** File uploaded from the form submission
- **$model** Current Model performing the data save

As mentioned earlier, you have the ability to customize the file migration by adding a new mime column, for instance.

By default, the package does not provide support for saving data in custom columns like this.

To address this, you can utilize the `thumbnailSaveData` method, which allows you to customize the data before it undergoes processing by the Thumbnail Model.

For example:

```
protected static function thumbnailSaveData($thumbnail, $file, $model): array
{
    $mime = $file->getMimeType();
    return [
        'name' => 'custom_name',
        'mime' => $mime
    ];
}
```

### Custom Handle Save Data

[](#custom-handle-save-data)

If you prefer not to utilize the default migration and model included in the package for saving thumbnail records when model events are triggered, you have the option to customize this functionality using the `thumbnailCustomSave` method.

To illustrate, let's consider a scenario where the current model has a thumbnail column for storing the file path. In this case, you can implement the following code:

```
protected static function thumbnailCustomSave($thumbnail, $file, $model)
    {
        $model->thumbnail = $thumbnail['path'];
        $model->saveQuietly();

        // Or
        // CustomModelThumbnail::insert($data);
    }
```

**IMPORTANT!** Use methods that do not trigger model events, such as `saveQuietly` or `insert`, to avoid infinite loop errors.

### Overwrite On Update

[](#overwrite-on-update)

By default, whenever a model event is triggered, new records are added to the `thumbnails` table.

However, if you wish to update the existing records when modifying data for the current model, you can make use of the `$thumbnailUpdateWillOverwrite` feature.

```
protected static bool $thumbnailUpdateWillOverwrite = true;
```

Testing
-------

[](#testing)

Run the tests with:

```
composer test

```

Contributing
------------

[](#contributing)

Please see [CONTRIBUTING](CONTRIBUTING.md) for details.

### Security

[](#security)

If you discover any security related issues, please email  instead of using the issue tracker.

Credits
-------

[](#credits)

- [Phuoc Nguyen](https://github.com/shishima)
- [All Contributors](../../contributors)

License
-------

[](#license)

The MIT License (MIT). Please see [License File](LICENSE.md) for more information.

###  Health Score

31

—

LowBetter than 68% of packages

Maintenance44

Moderate activity, may be stable

Popularity13

Limited adoption so far

Community8

Small or concentrated contributor base

Maturity51

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 100% 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 ~304 days

Total

3

Last Release

439d ago

Major Versions

v1.0.1 → v2.0.02023-07-03

### Community

Maintainers

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

---

Top Contributors

[![shishima123](https://avatars.githubusercontent.com/u/43268912?v=4)](https://github.com/shishima123 "shishima123 (10 commits)")

---

Tags

laravelthumbnailpreviewdocument

###  Code Quality

TestsPHPUnit

### Embed Badge

![Health badge](/badges/shishima-laravel-thumbnail/health.svg)

```
[![Health](https://phpackages.com/badges/shishima-laravel-thumbnail/health.svg)](https://phpackages.com/packages/shishima-laravel-thumbnail)
```

###  Alternatives

[maatwebsite/excel

Supercharged Excel exports and imports in Laravel

12.7k144.3M712](/packages/maatwebsite-excel)[barryvdh/laravel-snappy

Snappy PDF/Image for Laravel

2.8k24.8M48](/packages/barryvdh-laravel-snappy)[barryvdh/laravel-dompdf

A DOMPDF Wrapper for Laravel

7.3k87.6M278](/packages/barryvdh-laravel-dompdf)[elibyy/tcpdf-laravel

tcpdf support for Laravel 6, 7, 8, 9, 10, 11

3542.7M5](/packages/elibyy-tcpdf-laravel)[bfinlay/laravel-excel-seeder

Seed the database with Laravel using Excel, XLSX, XLS, CSV, ODS, Gnumeric, XML, HTML, SLK files

3944.4k](/packages/bfinlay-laravel-excel-seeder)

PHPackages © 2026

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