README

该软件包提供了一套管理用户资产的工具，例如文件上传或其他第三方内容在Laravel中。

安装

您可以通过composer安装此包

composer require mehr-it/levi-assets

Laravel的包自动检测将自动加载服务提供者和包的Assets外观。

使用

当处理资产时，该包提供了许多有用的工具。您可以直接使用它们，或者在资产管理器间接使用它们。

图像处理依赖于mehr-it/levi-images。请阅读该包的文档以获取图像处理详情和配置。

资产管理器

资产管理器是管理用户资产的中心枢纽。资产被分组到集合中。这允许为多个资产组配置不同的行为。

配置

以下示例配置定义了一个产品图像集合

// config/leviAssets.php

return [
    'collections' => [
        'productImages' => [
            'storage'        => 'local',
            'storage_path'   => 'products/images',
            'public_storage' => 's3',
            'public_path'    => 'static/pi',
            'virus_scan'     => true,
            'build' => [
                'small_jpg' => [
                    'imgMaxSize:100,75',
                    'imgFormat:jpg',
                    'imgOptimize',
                ],
                'small_webp' => [
                    'imgMaxSize:100,75',
                    'imgFormat:webp',
                ],
                'large_jpg' => [
                    'imgMaxSize:800,600',
                    'imgFormat:jpg',
                    'imgOptimize',
                ],
                'large_webp' => [
                    'imgMaxSize:800,600',
                    'imgFormat:webp',
                ],
            ],
            'link_filters' => [
                'webp:small_webp,large_webp'
            ]
        ],
    ],
    'builders' => [
        'imgMaxSize'  => ImageMaxSizeBuilder::class,
        'imgFormat'   => ImageFormatBuilder::class,
        'imgOptimize' => OptimizeImageBuilder::class,
    ]
]

为每个资产集合配置了两个磁盘。存储磁盘用于存储原始资产，而公开存储磁盘用于将公开构建的资产写入，以便它们可供公开访问。

build选项包含公开资产构建的配置。数组键用作构建名称，而值包含应用于原始资产以生成公开构建的所有构建器的数组。例如，字符串'imgMaxSize:100,75'将'imgMaxSize'构建器添加到构建管道中，并使用100和70作为参数。

virus_scan允许禁用添加的资产的病毒扫描，默认情况下是启用的。

link_filters选项定义了生成资产链接时的常见链接处理过滤器。有关使用和内置链接过滤器的更多信息，请参阅mehr-it/levi-assets-linker。

使用builders数组定义构建类及其名称。默认情况下，添加了一个名为'_'的纯复制构建，它可以在构建配置中禁用，方法是将['_' => false]传递。

虚拟资产构建

有时您需要对多个资产构建执行相同的操作。想象一个图像需要调整大小，然后以不同的格式输出。而不是多次调整图像大小，您可以定义一个“虚拟”构建来计算调整大小的图像。然后，可以使用此虚拟构建作为其他构建的输入。以下是一个示例配置

// config/leviAssets.php

return [
    'collections' => [
        'productImages' => [
            /*
             * ...
             */
            'build' => [
                ':small' => [
                     'imgMaxSize:100,75',
                ],
                'small_jpg:small' => [
                    'imgFormat:jpg',
                ],
                'small_webp:small' => [
                    'imgFormat:webp',
                ],
            ],
        ],
    ],
]

:small构建通过以冒号开头定义虚拟构建。它执行调整大小任务，但永远不会输出到任何地方。

small_jpg和small_webp构建将虚拟构建作为输入并应用格式转换。这是通过将":small"追加到构建名称来完成的。

这样，调整大小只进行一次。

资产构建器

资产构建器允许对给定资产应用任何类型的修改以生成公共文件版本。常见用例包括图像处理和优化或添加元数据。

资产构建器可以修改文件内容、文件路径以及写入公开资产文件时传递给存储磁盘的选项。

资产构建器必须实现AssetBuilder接口。AbstractAssetBuilder类是实现自定义资产构建器的良好起点。在使用之前必须按名称注册资产构建器。配置文件可用于此目的，如上所述。

内置资源构建器

此软件包包含一组广泛使用的资源构建器

Cache-Control（缓存）

允许定义一个 Cache-Control 元数据值。例如，'cache:max-age=3600,public'

Content-Disposition（处理）

允许定义一个 Content-Disposition 元数据值。例如，'disposition:attachment'

Content-Encoding（编码）

允许定义一个 Content-Encoding 元数据值。例如，'encoding:gzip'

Content-Language（语言）

允许定义一个 Content-Language 元数据值。例如，'language:de-DE,en-CA'

Content-Type（MIME）

设置 Content-Type 元数据值。内容类型可以显式作为参数传递：mime:text/plain,charset=utf-8。如果没有参数，则使用 finfo 评估文件内容，如果检测到内容类型，则使用该类型。如果内容类型检测失败或结果为 "application/octet-stream"，则不设置 Content-Type 元数据值。

Expires（过期时间）

允许定义一个 Expires 元数据值。例如，'expires:' . (time() + 60 * 60)。时间戳和日期对象作为参数将被自动转换为 HTTP 日期字符串。

S3-Options（S3）

将元数据值转换为与 S3 兼容的配置数组，以便在上传对象时传递给 S3。当使用 S3 存储时，此构建器强烈推荐使用。否则，任何元数据都将丢失。

ImageAutoCrop

自动从边缘裁剪图像背景像素。例如：imgAutoCrop:ffffff,0.01 使用 1% 的容差从边缘删除所有白色。默认选项为 ffffff 和 0.04。

ImageCanvas

在图像背景中用给定的颜色和边距绘制画布。例如：imgCanvas:ffffff,10 创建白色背景并在图像的每个边缘添加 10 像素。默认选项为 ffffff 和 0（无边距）。

ImageFormat

设置图像的输出格式。例如：imgFormat:jpg,quality=90 将输出格式设置为 Jpeg，质量为 90。格式选项是可选的，并且因格式而异。常见的输出格式是 png（默认）、jpg、gif 和 webp。

ImageGrayscale

将图像转换为灰度颜色空间。此构建器没有参数：imgGrayscale。

ImageGrayscaleMaxBlack

将图像转换为灰度颜色空间，并拉伸图像直方图，使最暗的颜色变为黑色。此构建器没有参数：imgGrayscaleMaxBlack

ImageMaxSize

如果图像超过指定大小，则将其调整到最大尺寸。例如，imgMaxSize:200,300,cubic 强制最大尺寸为 200x300 像素，并使用 "cubic" 过滤器进行插值。过滤器选项是可选的，但宽度和高度是必需的。可以在 Imagine\Image\ImageInterface 中找到一些有效的过滤器值，但可能因驱动程序而异。

ImageMinSize

如果图像的任何一边小于最小尺寸，则将其调整到最小尺寸。例如，imgMinSize:100,50,cubic 强制最小宽度为 100 像素和最小高度为 50 像素。它使用 "cubic" 过滤器进行插值。过滤器选项是可选的，但宽度和高度是必需的。可以在 Imagine\Image\ImageInterface 中找到一些有效的过滤器值，但可能因驱动程序而异。

ImageMinEdge

如果图像的至少一边小于最小尺寸，则将其调整到最小尺寸。例如，imgMinEdge:100,50,cubic 强制最小宽度为 100 像素或最小高度为 50 像素。它使用 "cubic" 过滤器进行插值。过滤器选项是可选的，但宽度和高度是必需的。可以在 Imagine\Image\ImageInterface 中找到一些有效的过滤器值，但可能因驱动程序而异。

ImageOptimize

将图像传递到相应的格式对应的图像优化器。此构建器没有选项：imgOptimize。相应的优化器库必须安装。有关详细信息，请参阅 mehr-it/levi-images。

ImagePalette

如果需要，将图像转换为给定的调色板。例如：imgPalette:rgb 转换为 RGB 调色板。如果图像驱动程序支持，其他选项还有 grayscale 和 cmyk。

解析和链接资源

在生成页面时，必须生成相应资产的URI。这项任务分为两个步骤：解析和链接。这个概念的一个优点是，可以使用轻量级的外部页面生成器（不加载整个PHP框架）来快速生成页面。它只需要持久化的解析路径数组来生成基于请求的资产链接。更多信息请参见 mehr-it/levi-assets-linker。

首先解析给定资产的公共构建路径。结果是包含每个构建的公共路径的数组（构建名称作为键）。例如，对于上面配置的产品图像示例，解析路径数组可能如下所示

[
    'small_jpg'  => 'static/pi/small_jpg/GiftCardRed.jpg',
    'small_webp' => 'static/pi/small_webp/GiftCardRed.webp',
    'large_jpg'  => 'static/pi/large_jpg/GiftCardRed.jpg',
    'large_webp' => 'static/pi/large_webp/GiftCardRed.webp',
]

链接器获取这个路径数组，选择最合适的路径，并为其生成链接。如果没有链接过滤器，这总是第一个路径。因此，构建定义的顺序也定义了优先级。

然而，链接过滤器可以修改路径数组（例如，删除路径或重新排序数组）。由于路径过滤器是在站点生成时应用的，它们可以例如响应请求头。一个例子是webp过滤器，当浏览器指示支持WebP时，它将WebP构建的优先级设置得更高。

链接过滤器还可以修改生成的URL，例如替换主机或确保使用'https'作为协议。

可以在配置文件中为每个集合指定链接过滤器，或将其作为链接方法的参数传递。

Assets::link('productImages', 'GiftCardRed.jpg', [], 'proto:https|host:example.com');

对于图像，通常生成多个不同大小的缩略图。第三个参数允许定义构建过滤器，在将路径数组传递给链接器之前预先选择相应的构建。

 Assets::link('productImages', 'GiftCardRed.jpg', 'small_jpg,small_web_p', 'proto:https');

而不是列出所有构建，可以使用'pfx'和sfx过滤器通过前缀或后缀来过滤构建名称。

Assets::link('productImages', 'GiftCardRed.jpg', 'pfx:small_', 'proto:https');

可调用和多个过滤器也可以作为路径过滤器接受。它们的语法与链接过滤器非常相似。

Blade指令

如果在使用blade模板中的资产，@assetLink指令指向Assets::link()方法。

@assetLink('productImages', 'GiftCardRed.jpg', [], 'proto:https');

病毒扫描

病毒扫描需要安装ClamAV（带守护进程）。您可以通过以下方式安装它

apt-get install clamav clamav-daemon

扫描文件非常简单

$scanner = app(VirusScanner::class);
try {
    $scanner->scanFile($file);
}
catch(VirusDetectedException $ex) {
    // malicious content was detected
}    
catch(VirusScanException $ex) {
    // an error occured on file scanning
}

配置病毒扫描

如果您的ClamAV使用不同于unix:///var/run/clamav/clamd.ctl的其他套接字，您必须将ASSETS_VIRUS_SCAN_SOCKET设置为正确值。

如果您想全局禁用病毒扫描，例如在开发环境中，可以将ASSETS_VIRUS_SCAN_BYPASS设置为true。

mehr-it / levi-assets

维护者

详细信息