README

Pinimize 是一个强大的 Laravel 扩展包，简化了文件压缩和解压缩。它提供了一套干净、直观的 API，用于处理 Laravel 应用中的各种压缩和解压缩任务，完全支持 Laravel 的存储系统。

归档和解档操作将在不久的将来推出。

特性

• 文件压缩和解压缩
• 字符串压缩和解压缩
• 流压缩和解压缩
• 文件归档和解档
• 支持多种压缩算法和归档格式
• 基于 Facade 的 API，易于集成
• 完全与 Laravel 的存储系统集成
• 可扩展架构，支持自定义驱动器
• 积极维护，定期更新
• 使用简洁、现代的 PHP 代码编写

目录

• 特性
• 安装
• 配置
  • 默认驱动器
  • 压缩驱动器
  • 压缩级别
  • 存储磁盘
• 环境变量
• 基本用法
  • 字符串宏
  • 存储宏
  • 压缩字符串
  • 压缩资源
  • 压缩文件
  • 使用存储磁盘
• 支持的数据类型
• 高级用法
  • 下载压缩文件
  • 压缩率
  • 支持的算法
• 驱动器
  • Gzip 驱动器
  • Zlib 驱动器
• 自定义驱动器
• 测试
• 更新日志
• 致谢
• 许可证

安装

您可以通过 composer 安装此包

composer require pinimize/laravel-compression-and-archive

配置

发布配置文件

php artisan vendor:publish --provider="Pinimize\PinimizeServiceProvider" --tag="config"

config/pinimize.php 文件允许您配置 Pinimize 包的压缩和解压缩设置。当您发布包配置时，将创建此文件。

默认驱动器

您可以使用 COMPRESSION_DRIVER 环境变量或直接修改配置文件中的 compression.default 值来设置默认压缩驱动器。默认设置为 'gzip'。

'default' => env('COMPRESSION_DRIVER', 'gzip'),

压缩驱动器

该包支持两个压缩驱动器：'gzip' 和 'zlib'。每个驱动器都有自己的配置选项

Gzip 驱动器

'gzip' => [
    'level' => env('GZIP_LEVEL', -1),
    'encoding' => FORCE_GZIP,
    'disk' => env('COMPRESSION_DISK', null),
],

Zlib 驱动器

'zlib' => [
    'level' => env('ZLIB_LEVEL', -1),
    'encoding' => ZLIB_ENCODING_DEFLATE,
    'disk' => env('COMPRESSION_DISK', null),
],

未来版本中将添加更多驱动器。它们被分开以避免您安装可能不需要的 PHP 扩展，并保持代码库的整洁。

压缩级别

对于这两个驱动器，您可以设置压缩级别

• -1：默认压缩（大多数情况下推荐）
• 0：不压缩
• 1：最快的压缩
• 9：最佳压缩

存储磁盘

disk 选项允许您指定用于文件操作的磁盘。这与 Laravel 的存储系统集成

• 如果设置为 null（默认），将使用本地文件系统。
• 您可以将它设置为 config/filesystems.php 文件中配置的任何磁盘。

要设置磁盘，请使用 COMPRESSION_DISK 环境变量或直接在配置文件中修改 disk 值。

环境变量

为了便于配置，您可以使用以下环境变量

• COMPRESSION_DRIVER：设置默认压缩驱动器（'gzip' 或 'zlib'）
• GZIP_LEVEL：设置 gzip 驱动器的压缩级别
• ZLIB_LEVEL：设置 zlib 驱动器的压缩级别
• COMPRESSION_DISK：设置文件操作的存储磁盘

请记得根据需要更新 .env 文件中的这些变量。

基本用法

字符串宏

Pinimize 包扩展了 Laravel 的 Str Facade，添加了两个方便的宏用于字符串压缩和解压缩

Str::compress($data)

// and

Str::decompress($compressedData)

这些宏允许您轻松使用默认压缩驱动器压缩和解压缩数据。

use Illuminate\Support\Str;

// Using the default driver
$originalString = "This is a long string that will be compressed.";
$compressedString = Str::compress($originalString);

// Specifying a driver
$compressedStringGzip = Str::compress($originalString, 'gzip');
$compressedStringZlib = Str::compress($originalString, 'zlib');

解压缩压缩数据

use Illuminate\Support\Str;

$decompressedString = Str::decompress($compressedString);

// Specifying a driver
$decompressedStringGzip = Str::decompress($compressedStringGzip, 'gzip');
$decompressedStringZlib = Str::decompress($compressedStringZlib, 'zlib');

这些宏提供了一种简单便捷的方式，在Laravel应用程序中压缩和解压缩字符串，利用Pinimize包的强大功能。

存储宏

Pinimize包扩展了Laravel的Storage外观，增加了两个方便的文件压缩和解压缩方法

压缩

use Illuminate\Support\Facades\Storage;

Storage::compress(
    string $source,
    ?string $destination = null,
    bool $deleteSource = false,
    ?string $driver = null
): bool|string;

参数

• $source：源文件的路径（相对于存储磁盘）。
• $destination：（可选）压缩文件应保存的路径。如果为null，则使用源文件路径并附加扩展名。
• $deleteSource：（可选）在成功压缩后是否删除源文件。默认为false。
• $driver：（可选）要使用的压缩驱动（例如，'gzip'，'zlib'）。如果为null，则使用默认驱动。

返回值

• 如果提供了$destination：成功时返回true，失败时返回false。
• 如果$destination为null：成功时返回压缩文件的路径，失败时返回false。

解压缩

use Illuminate\Support\Facades\Storage;

Storage::decompress(
    string $source,
    ?string $destination = null,
    bool $deleteSource = false,
    ?string $driver = null
): string|bool;

参数

• $source：压缩文件的路径（相对于存储磁盘）。
• $destination：（可选）解压缩文件应保存的路径。如果为null，则使用$source移除压缩扩展名。
• $deleteSource：（可选）在成功解压缩后是否删除源文件。默认为false。
• $driver：（可选）要使用的解压缩驱动（例如，'gzip'，'zlib'）。如果为null，则使用默认驱动。

返回值

• 如果提供了$destination：成功时返回true，失败时返回false。
• 如果$destination为null：成功时返回解压缩文件的路径，失败时返回false。

示例

use Illuminate\Support\Facades\Storage;

// Compress a file with default settings
$compressResult = Storage::compress('large_file.txt');
if ($compressResult !== false) {
    echo "File compressed successfully to: $compressResult\n";
}

// Compress a file with custom destination and driver
$compressResult = Storage::compress('document.pdf', 'compressed_doc.pdf.gz', false, 'zlib');
if ($compressResult === true) {
    echo "File compressed successfully\n";
}

// Decompress a file with default settings
$decompressResult = Storage::decompress('large_file.txt.gz');
if ($decompressResult !== false) {
    echo "File decompressed successfully to: $decompressResult\n";
}

// Decompress a file, delete the source, and use a specific driver
$decompressResult = Storage::decompress('archive.tar.gz', 'extracted_archive.tar', true, 'gzip');
if ($decompressResult === true) {
    echo "File decompressed and compressed version deleted\n";
}

这些方法为在Laravel应用程序的存储系统中压缩和解压缩文件提供了一个简单便捷的方式，利用Pinimize包的强大功能。

压缩字符串

要将数据压缩为字符串，可以使用string方法。查看此方法的支持的数据类型。此方法适用于在内存中压缩少量数据。

use Illuminate\Http\File;
use Illuminate\Http\UploadedFile;
use Illuminate\Support\Facades\Compression;

// With string input
$compressed = Compression::string('Hello, World!');

// With file input
$compressed = Compression::string(new File($path));

// With uploaded input
$compressed = Compression::string(new UploadedFile($path));
// etc.

解压缩外观的工作方式类似，只是它解压缩数据

use Illuminate\Support\Facades\Decompression;

$data = gzencode('Hello, World!');
$compressed = Decompression::string($data); // Hello, World!

压缩资源

您可以使用resource方法将数据压缩并作为资源返回。此方法适用于处理不需要加载到内存中的数据。

查看此方法的支持的数据类型。

use Illuminate\Support\Facades\Compression;

// string input
$compressedResource = Compression::resource("I'm too big, make me smaller please!");

// resource input
$resource = fopen('path/to/input.txt', 'r');
$compressedResource = Compression::resource($resource);

解压缩外观的工作方式类似，只是它解压缩资源

use Illuminate\Support\Facades\Decompression;

// resource input
$resource = fopen('path/to/compressed_data.txt.gz', 'r');

$decompressedResource = Decompression::resource($resource);

压缩文件

put方法是一种灵活地将压缩内容写入文件的方法。它支持多种输入类型，并提供了在何处存储压缩文件的选择。

use Illuminate\Http\File;

// Storing on a local disk
Compression::put('local_output.gz', 'Content');

// Compressing a file and storing on a local disk
Compression::put('ftp_output.gz', new File($path));

// Storing on Google Cloud Storage
Compression::put('gcs_output.gz', 'Content');

解压缩外观的工作方式类似，只是它解压缩资源

use Illuminate\Support\Facades\Decompression;

// resource input
$resource = fopen('path/to/compressed.txt.gz', 'r');

$decompressedResource = Decompression::put('local_output.txt', $resource);
$decompressedResource = Decompression::put('local_output.txt', 'path/to/compressed.txt.gz');

使用存储磁盘

默认情况下，put方法将使用配置文件中提供的文件系统，默认为本地文件系统。但是，您可以使用Laravel的Storage外观通过指定disk选项将压缩文件写入任何配置的磁盘

use Illuminate\Support\Facades\Compression;

// Storing on an S3 bucket, the path is relative to the bucket's root
Compression::put('compressed/output.gz', 'Content to compress', [
    'disk' => 's3'
]);

这将压缩内容并将其存储在S3磁盘上（假设您已在filesystems.php配置中配置了S3磁盘）。

您可以使用config/filesystems.php中配置的任何磁盘。

// Storing on a local disk
Compression::put('local_output.gz', 'Content', ['disk' => 'local']);

// Storing on an FTP server
Compression::put('ftp_output.gz', 'Content', ['disk' => 'ftp']);

// Storing on Google Cloud Storage
Compression::put('gcs_output.gz', 'Content', ['disk' => 'gcs']);

当使用disk选项时，压缩服务将利用Laravel的Storage外观处理文件操作，让您能够利用Laravel文件系统抽象的所有优势。

请注意，当使用存储磁盘时，您提供给put的第一个参数的路径相对于磁盘配置的根目录。

支持的数据类型

string、resource和put方法可以处理多种类型的输入

1. 字符串:

   Compression::put('output.gz', 'String content to compress');

如果提供的字符串是文件的路径，则该软件包将首先尝试在指定的文件系统中定位该文件。如果找不到文件，则软件包将把该字符串视为要压缩的原始内容。

这种行为允许在同一接口中灵活地处理文件路径和直接内容压缩。如果您想确保指定路径的文件应该被加载，请考虑使用Illuminate\Http\File对象或作为资源传递。

1. PSR-7 StreamInterface:

   use GuzzleHttp\Psr7\Stream;
   
   $stream = new Stream(fopen('path/to/file.txt', 'r'));
   Compression::put('output.gz', $stream);

2. Laravel的文件对象:

   use Illuminate\Http\File;
   
   $file = new File('path/to/file.txt');
   Compression::put('output.gz', $file);

3. Laravel的上传文件对象:

   // In a controller method handling file upload
   public function handleUpload(Request $request)
   {
       $uploadedFile = $request->file('document');
       Compression::put('compressed_upload.gz', $uploadedFile);
   }

4. PHP资源:

   $resource = fopen('path/to/file.txt', 'r');
   Compression::put('output.gz', $resource);

高级用法

下载压缩文件

创建压缩文件的下载响应

return Compression::download('path/to/file.txt', 'downloaded_file.gz');

这也适用于解压缩文件

return Decompression::download('path/to/file.txt.gz', 'file.txt');

压缩率

获取原始数据和压缩数据之间的压缩比率

$ratio = Compression::getRatio('original_content', 'compressed_content');

支持的算法

获取当前驱动程序支持的压缩算法列表

$algorithms = Compression::getSupportedAlgorithms();

驱动器

Gzip 驱动器

Gzip驱动程序使用gzencode函数进行压缩。它支持FORCE_GZIP编码，并生成具有.gz扩展名的文件。

Zlib 驱动器

Zlib驱动程序使用zlib_encode函数进行压缩。它支持ZLIB_ENCODING_RAW、ZLIB_ENCODING_GZIP和ZLIB_ENCODING_DEFLATE编码。使用此驱动程序压缩的文件具有.zz扩展名。

自定义驱动器

您可以通过扩展CompressionContract接口并实现所需方法来创建自定义压缩驱动程序。然后，在服务提供程序中注册您的自定义驱动程序。

use Illuminate\Support\Facades\Compression;

public function boot()
{
    Compression::extend('custom', function ($app) {
        return new CustomCompressionDriver($app['config']['compression.custom']);
    });
}

注册自定义驱动程序后，您可以在应用程序中像使用其他压缩驱动程序一样使用它。创建自定义解压缩驱动程序的过程相同。

链接

• 文章 - 使用Pinimize简化Laravel中的文件压缩

测试

使用以下命令运行测试

composer test

更新日志

请参阅变更日志以获取有关最近更改的更多信息。

致谢

• Einar Hansen
• 所有贡献者

许可证

MIT许可证（MIT）。有关更多信息，请参阅许可证文件。