README

Laravel EasyCloudStorage是一个灵活且直观的包，旨在简化Laravel应用程序中的云存储管理。它提供了一个干净的接口，用于与各种存储提供商进行交互，包括本地磁盘、Amazon S3和Google Cloud Storage。

安装

要安装此包，请通过Composer运行以下命令

composer require danilowa/laravel-easy-cloud-storage

安装后，服务提供程序将自动注册。要自定义配置，请发布包的配置文件

php artisan vendor:publish --provider="Danilowa\LaravelEasyCloudStorage\EasyCloudStorageServiceProvider"

配置

配置文件位于 config/easycloudstorage.php。主要设置包括

return [
    'default' => 'local', // Default disk for storage operations.
    'log_errors' => false, // Enable error logging.
    'throw_errors' => false, // Enable exception throwing for errors.
    'disks' => [
        'local' => [
            'driver' => 'local',
            'root' => storage_path('app'), // Root path for local storage.
        ],
        's3' => [
            'driver' => 's3',
            'key' => env('AWS_ACCESS_KEY_ID'),
            'secret' => env('AWS_SECRET_ACCESS_KEY'),
            'region' => env('AWS_DEFAULT_REGION'),
            'bucket' => env('AWS_BUCKET'),
            'url' => env('AWS_URL'),
        ],
        'google' => [
            'driver' => 'gcs',
            'project_id' => env('GOOGLE_CLOUD_PROJECT_ID'),
            'key_file' => env('GOOGLE_CLOUD_KEY_FILE'),
            'bucket' => env('GOOGLE_CLOUD_STORAGE_BUCKET'),
            'url' => env('GOOGLE_CLOUD_URL'),
        ],
        // Additional providers can be added as needed.
    ],
];

使用

配置后，您可以使用EasyCloudStorage包执行各种操作。

初始示例

本节演示了如何使用EasyCloudStorage包执行文件上传。示例说明了将文件上传到指定目录的过程，包括可选的日志记录和错误处理配置。

use Danilowa\LaravelEasyCloudStorage\Facades\EasyStorage;

// Assume $uploadedFile is an instance of UploadedFile, obtained from an HTTP request.
$filePath = EasyStorage::upload($uploadedFile, 'uploads/myfile.txt')
    ->withLog(true)  // Set error logging behavior. Defaults to true if not specified.
    ->withError(false) // Set error handling behavior. Defaults to true if not specified.
    ->setDisk('s3'); // Specify the disk manually instead of using the default.

// Check if the upload was successful
if($filePath === false) {
    return echo "Error uploading the file.";
}

echo "File uploaded successfully: $filePath";

代码说明

使用语句
- use 语句导入 EasyStorage 外观，这使得您可以轻松访问存储功能。
上传文件
- 在 EasyStorage 外观上调用 upload 方法，传入以下参数
  - $uploadedFile：一个 UploadedFile 实例，通常从HTTP请求中的文件上传中获得。
  - 'uploads/myfile.txt'：文件将在磁盘上存储的目标路径。
错误日志配置
- withLog 方法允许您控制上传过程中的错误日志记录
  - 启用（true）：上传操作将激活错误日志记录。
  - 禁用（false）：关闭错误日志记录。
  - 默认行为：如果没有参数调用，它假定 true，默认启用错误日志记录。
  - 配置回退：如果没有使用，则包使用配置文件中指定的错误日志记录设置。
错误处理配置
- withError 方法配置是否在上传过程中出现错误时抛出异常
  - 抛出异常（true）：系统将为任何遇到的错误抛出异常。
  - 不抛出异常（false）：防止抛出异常。
  - 默认行为：如果没有参数调用，它默认为 true。
  - 配置回退：遵循配置文件中指定的错误处理配置。
设置磁盘
- setDisk 方法允许您手动指定要使用的存储磁盘，以覆盖默认磁盘配置。
成功检查
- 尝试上传后，结果存储在 $filePath 中。此变量将包含表示上传文件路径的字符串或如果上传失败则包含 false。
- if 语句检查 $filePath 的值以确定上传是否成功
  - 上传成功：如果 $filePath 是 string 类型，则会打印出上传文件的路径。
  - 上传失败：如果 $filePath 是 false，则表示上传失败，并显示错误信息。

文件操作

上传文件

将文件上传到存储磁盘的指定路径。

$filePath = EasyStorage::upload($uploadedFile, 'uploads/myfile.txt', 'banana.txt');

// Upload to a specific disk (S3)
$filePathS3 = EasyStorage::upload($uploadedFile, 'uploads/myfile.txt')->setDisk('s3');

参数
- UploadedFile $file：要上传的文件。
- string $path：上传的目的路径。
- string|null $newName：可选。文件的新的名称；如果没有提供，则使用原始名称。
返回： string|false - 成功时返回文件路径；否则返回 false。

下载文件

从存储磁盘的指定路径下下载文件。

return EasyStorage::download('uploads/myfile.txt', 'name.txt')->withLog();

参数
- string $path：要下载的文件的路径。
- string|null $newName：可选。下载文件的新的名称；如果没有提供，则使用原始名称。
返回： BinaryFileResponse
抛出： 如果文件不存在，抛出 NotFoundHttpException。

获取文件URL

检索存储文件的 URL。

$fileUrl = EasyStorage::url('uploads/myfile.txt');

参数
- string $path：文件的路径。
返回： string - 文件的 URL。

删除文件

在指定的路径下删除文件。

$deleted = EasyStorage::delete('uploads/myfile.txt');

参数
- string $path：要删除的文件的路径。
返回： bool - 成功时返回 true，否则返回 false。

检查文件是否存在

检查指定路径下是否存在文件。

$exists = EasyStorage::exists('uploads/myfile.txt');

参数
- string $path：文件的路径。
返回： bool - 如果存在返回 true，否则返回 false。

复制文件

从源路径复制文件到目标路径。

$copied = EasyStorage::copy('uploads/myfile.txt', 'uploads/myfile_copy.txt');

参数
- string $from：源文件的路径。
- string $to：目标路径。
返回： bool - 成功时返回 true，否则返回 false。

移动文件

移动或重命名文件。

$success = EasyStorage::move('uploads/myfile.txt', 'uploads/newfile.txt');

参数
- string $from：文件的旧路径。
- `string

$to`：新路径。

返回： bool - 成功时返回 true，否则返回 false。

获取文件大小

以字节为单位检索文件大小。

$size = EasyStorage::size('uploads/myfile.txt');

参数
- string $path：文件的路径。
返回： int|null - 返回文件大小（字节）或 null（如果文件不存在）。

获取最后修改时间

获取文件的最后修改时间戳。

$lastModified = EasyStorage::lastModified('uploads/myfile.txt');

参数
- string $path：文件的路径。
返回： int|null - 返回时间戳或 null（如果文件不存在）。

获取元数据

检索文件的元数据。

$metadata = EasyStorage::metadata('uploads/myfile.txt');

参数
- string $path：文件的路径。
返回： array|null - 返回元数据或 null（如果文件不存在）。

设置元数据

设置文件的元数据。

$success = EasyStorage::setMetadata('uploads/myfile.txt', [
    'Content-Type' => 'application/pdf',
]);

参数
- string $path：文件的路径。
- array $metadata：要设置的元数据。
返回： bool - 成功时返回 true，否则返回 false。

列出文件

列出指定目录中的文件。

$files = EasyStorage::list('uploads');

参数
- string $directory：目录路径。
返回： array - 文件名数组。

预拼接和追加数据

向文件中追加或预置数据。

$successPrepend = EasyStorage::prepend('uploads/myfile.txt', 'Header data');
$successAppend = EasyStorage::append('uploads/myfile.txt', 'Footer data');

参数
- string $path：文件的路径。
- string $data：要预置或追加的数据。
返回： bool - 成功时返回 true，否则返回 false。

创建和删除目录

创建或删除目录。

EasyStorage::createDirectory('uploads/new_directory');
EasyStorage::deleteDirectory('uploads/old_directory');

参数
- string $directory：目录路径。
返回： bool - 成功时返回 true，否则返回 false。

错误处理

您可以通过配置或方法链启用错误日志记录和异常抛出。使用 withLog() 和 withError() 方法为每个操作自定义错误处理。

特定驱动程序的方法可用性

请注意，并非所有存储驱动程序都支持 EasyCloudStorage 包中提供的所有方法。提供的功能完全取决于每个特定驱动程序的功能，例如 Google Cloud Storage、Amazon S3 等。

例如，虽然上传和删除文件是大多数驱动程序中常见的操作，但某些方法（如管理元数据或创建目录）可能不是所有驱动程序都支持的。

放心，EasyCloudStorage 包内置了处理这些差异的逻辑。如果一个方法对于特定的驱动程序不可用，将返回一个有用的错误信息，确保您能够及时了解到限制。这种设计让您能够在不担心意外失败的情况下实现逻辑，从而促进顺畅的开发体验。

设计模式：外观和契约

外观

在Laravel中，外观模式提供了一个简单直观的接口来访问应用服务容器中的类。通过使用EasyStorage外观，您可以直接调用方法，而无需每次都解析底层服务。这种方法不仅简化了您的代码，还提高了可读性，使您能够专注于构建功能，而不是管理复杂的依赖关系。结果是更干净、更高效的API，从而提升了您的开发体验。

合约

Laravel中的合约定义了服务的预期行为，为它们应该如何操作提供了明确的指导。通过使用合约，您确保了应用程序可以轻松地在不同服务实现之间切换，而不会影响到与之交互的代码。这种灵活性对开发者来说非常有益，因为它允许更容易地更新或更改底层逻辑，而无需进行大量的代码修改。

对于用户来说，这意味着更可靠、更易于维护的应用程序。您可以在确保核心功能保持完整的同时，自信地集成新功能或优化现有功能。通过遵循这一实践，您也促进了易于理解和扩展的整洁架构，从而提高了代码库的长期可持续性。

许可证

本软件包采用MIT许可证。有关详细信息，请参阅许可证文件。

danilowa / laravel-easy-cloud-storage

维护者

详细信息