shishima /

此包用于为文档文件创建缩略图。支持以下文件类型：doc, docx, xls, xlsx, pdf, gif, jpg, jpeg, png。

维护者

详细信息

github.com/shishima123/laravel-thumbnail

主页

源代码

问题

安装: 14

依赖项: 0

建议者: 0

安全: 0

星标: 2

关注者: 2

分支: 1

开放问题: 0

类型:laravel-package

v2.0.0 2023-07-03 17:44 UTC

Requires

Requires (Dev)

MIT 50e9c3c74a69676cf0dd4e46590c40b3fb81af10

  • Phuoc Nguyen <shishima21.woop@gmail.com>

thumbnaildocumentlaravelpreview

This package is auto-updated.

Last update: 2024-09-04 08:19:27 UTC

README

此包用于为文档或图像文件创建缩略图。支持的文件格式包括：doc, docx, xls, xlsx, pdf, gif, jpg, jpeg, png。

需求

此包仅在Linux环境下工作。为了使用它，您必须在Linux环境中预先安装以下库

libmagickwand

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

ghostscript

sudo apt-get install ghostscript

libreoffice

sudo apt-get install libreoffice

unoconv

sudo apt-get install unoconv

以下安装命令仅供参考，具体命令取决于相应的发行版。请使用您发行版的适当命令以确保正确安装。

Imagick

此包使用PHP的Imagick扩展来创建缩略图文件，因此必须安装此扩展。

sudo apt install php-imagick

//then

sudo apt list php-magick -a

安装后，请记得重新启动服务器以激活扩展。

将policy.xml文件复制到路径/etc/ImageMagick-6/policy.xml。此文件用于授予Imagick对PDF文件的读写权限。

将Module1.xba文件复制到路径/usr/lib/libreoffice/presets/basic/Standard/Module1.xba。此文件用于修复创建Excel文件缩略图时的换行问题。

Docker

如果您使用Docker，您可以将以下行添加到Dockerfile中，以安装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

将policy.xml和Module1.xba文件复制到与docker-compose.yml文件相同的目录。

然后，将它们添加到应用的volumes部分。

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

有关更多信息，请参阅Docker目录。

安装

使用Composer安装

composer require shishima/laravel-thumbnail

发布配置

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

发布配置文件后，您可以通过编辑app/config/thumbnail文件来自定义设置。

发布默认缩略图图标

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

将默认文件发布到路径public/vendor/laravel_thumbnail/Thumbnail-default.svg。此路径用于指定默认文件。如果需要，您可以将其更改为不同的路径。

当文件不在支持的缩略图文件类型列表中时，使用default配置。在这种情况下，可以使用默认图标作为替代。您可以通过设置enable = false来禁用此功能。

注意

磁盘

配置部分disks包括两个配置

  • disks.temp_thumbnail配置用于在创建缩略图过程中临时将原始文件克隆到临时目录。
    这允许在生成缩略图之前对文件进行修改。一旦生成缩略图，临时文件就会被删除。

  • disk.thumbnail配置用于存储生成的缩略图文件。

默认情况下，这些文件存储在存储目录中。如果您选择使用默认配置，则需要创建一个指向public目录的符号链接。

php artisan storage:link

您可以根据需要自定义这些设置。

忽略扩展名

默认情况下，此包支持以下文件扩展名：doc, docx, xls, xlsx, pdf, gif, jpg, jpeg, png。但是，如果您想排除特定的扩展名进行处理，可以将它添加到ignore_extensions列表中。

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

用法

创建缩略图文件

要使用此包，您可以使用Thumbnail外观

use Shishima\Thumbnail\Facade\Thumbnail;

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

在这个例子中，文件可以是系统上文件的路径

use Shishima\Thumbnail\Facade\Thumbnail;

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

或者可能是使用表单提交时，通过标签从request中检索到的文件。

use Shishima\Thumbnail\Facade\Thumbnail;

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

使用setFile方法来传入将生成缩略图的文件，或者可以将文件作为参数传递给create方法。

Thumbnail::create($file);

create函数返回的数据将具有以下格式

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

修改选项

默认选项可以在app/config/thumbnail文件中配置，但在缩略图生成过程中仍可以通过以下方法进行更改

setHeight

更改默认高度

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

setWidth

更改默认宽度

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

setSize

更改默认宽度和高度

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

setFormat

更改缩略图的默认格式

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

setLayer

如果生成的缩略图图像显示不正确，可以尝试更改层参数

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

setOptions

要同时更改多个选项，可以使用setOptions方法并传入选项数组

重要！该软件包仅支持更改：宽度、高度、层和格式选项。

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

doNotRemoveTempFileAfterConvert

默认情况下，临时文件将在完成时自动删除。使用此功能，转换完成后将不会删除临时文件。

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

shouldRemoveTempFileAfterConvert

与shouldRemoveTempFileAfterConvert相反，临时文件将被删除。

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

重要！默认情况下，临时文件将在完成时自动删除。

模型事件

此功能依赖于Laravel的模型事件功能。当一个带有文件上传的请求被保存到数据库时，将自动创建缩略图。

发布迁移

此软件包包含一个迁移文件，用于创建用于存储最近创建的缩略图记录的缩略图表。

要发布

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

发布后迁移表

php artisan migrate

自定义迁移文件

要自定义缩略图表中的列，可以更改生成的迁移文件。

修改迁移文件后，使用php artisan migrate命令创建新表。

要添加新列，可以参考自定义数据保存以添加数据。

更改表名

要更改表名，可以更改app/config/thumbnail文件中的table_name。

更改模型

默认情况下，该软件包将使用\Shishima\Thumbnail\Models\Thumbnail::class模型将数据保存到数据库。

您可以通过更改app/config/thumbnail文件中的thumbnail_model来实现这一点。

用法

要使用自动缩略图创建功能，请将HasThumbnail特征添加到模型类中

例如

use Shishima\Thumbnail\HasThumbnail;

class Document extends Models
{
    use HasThumbnail;
    //
}

缩略图事件触发配置

添加HasThumbnail后，您需要指定$thumbnailEventTriggerColumn。此列将存储要生成缩略图的文件的路径。

protected static string $thumbnailEventTriggerColumn = 'file_path';

磁盘配置

默认情况下，该软件包将使用Laravel的Storage类来检查文件。

如果您使用Laravel的Storage保存文件且您的磁盘与在config/filesystems中配置的filesystems.default不同，您需要通过以下方式配置磁盘信息

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

重要！该软件包的当前版本仅支持本地存储的磁盘。云存储将在未来得到支持。

自定义事件

该软件包提供了对两个事件的支持：saved和updated。如果您想自定义这些事件，可以通过设置模型文件中的$thumbnailEvents属性来实现。

protected static $thumbnailEvents = ['saved'];

重要！该包只支持2个事件：saved 和 updated。因此，无法添加其他事件，也不支持其他事件。

禁用

要禁用缩略图创建功能，请使用 $doNotCreateThumbnail 属性

protected static $doNotCreateThumbnail = true;

选项

要自定义模型中的选项，请使用 $thumbnailOptions 属性

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

自定义数据保存

在保存之前自定义数据，您可以使用 $thumbnailSaveData

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

传递的参数是

  • $thumbnail 缩略图外观返回的数据
  • $file 从表单提交中上传的文件
  • $model 当前执行数据保存的操作模型

如前所述，您可以通过添加新的MIME列等方式自定义文件迁移。

默认情况下，该包不支持在自定义列（如上述情况）中保存数据。

为此，您可以使用 thumbnailSaveData 方法，该方法允许您在缩略图模型处理之前自定义数据。

例如

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

自定义处理保存数据

如果您希望在不使用包中包含的默认迁移和模型的情况下保存缩略图记录，当模型事件触发时，您可以使用 thumbnailCustomSave 方法来自定义此功能。

为了说明，让我们考虑一个场景，其中当前模型有一个用于存储文件路径的缩略图列。在这种情况下，您可以实现以下代码

protected static function thumbnailCustomSave($thumbnail, $file, $model)
    {
        $model->thumbnail = $thumbnail['path'];
        $model->saveQuietly();
        
        // Or
        // CustomModelThumbnail::insert($data);
    }

重要！使用不会触发模型事件的方法，例如 saveQuietly 或 insert，以避免无限循环错误。

更新时覆盖

默认情况下，每当模型事件触发时，都会向 thumbnails 表中添加新记录。

但是，如果您希望在修改当前模型的数据时更新现有记录，您可以使用 $thumbnailUpdateWillOverwrite 功能。

protected static bool $thumbnailUpdateWillOverwrite = true;

测试

使用以下命令运行测试

composer test