Laravel 5.3 中文文档

简体中文

English

简体中文

English

主题

文件系统 / 云存储 ​

介绍 ​

Laravel 提供了一个强大的文件系统抽象，这要归功于 Frank de Jonge 的优秀 PHP 包 Flysystem。Laravel 的 Flysystem 集成提供了简单易用的驱动程序，用于处理本地文件系统、Amazon S3 和 Rackspace 云存储。更好的是，切换这些存储选项非常简单，因为每个系统的 API 都保持不变。

配置 ​

文件系统配置文件位于 config/filesystems.php。在此文件中，您可以配置所有的“磁盘”。每个磁盘代表一个特定的存储驱动程序和存储位置。配置文件中包含了每个支持的驱动程序的示例配置。因此，只需修改配置以反映您的存储偏好和凭据。

当然，您可以配置任意数量的磁盘，甚至可以有多个使用相同驱动程序的磁盘。

公共磁盘 ​

public 磁盘用于将要公开访问的文件。默认情况下，public 磁盘使用 local 驱动程序，并将这些文件存储在 storage/app/public 中。为了使它们可以从网络访问，您应该创建一个从 public/storage 到 storage/app/public 的符号链接。当使用零停机时间部署系统（如 Envoyer）时，这种约定将使您的公开访问文件保存在一个目录中，便于跨部署共享。

要创建符号链接，您可以使用 storage:link Artisan 命令：

php
php artisan storage:link

当然，一旦文件存储完毕并创建了符号链接，您可以使用 asset 辅助函数创建文件的 URL：

php
echo asset('storage/file.txt');

本地驱动 ​

使用 local 驱动程序时，所有文件操作都是相对于配置文件中定义的 root 目录的。默认情况下，此值设置为 storage/app 目录。因此，以下方法将文件存储在 storage/app/file.txt 中：

php
Storage::disk('local')->put('file.txt', 'Contents');

驱动程序先决条件 ​

Composer 包 ​

在使用 S3 或 Rackspace 驱动程序之前，您需要通过 Composer 安装相应的包：

  • Amazon S3: league/flysystem-aws-s3-v3 ~1.0
  • Rackspace: league/flysystem-rackspace ~1.0

S3 驱动程序配置 ​

S3 驱动程序的配置信息位于您的 config/filesystems.php 配置文件中。此文件包含 S3 驱动程序的示例配置数组。您可以自由修改此数组以包含您自己的 S3 配置和凭据。

FTP 驱动程序配置 ​

Laravel 的 Flysystem 集成与 FTP 配合得很好；然而，框架的默认 filesystems.php 配置文件中不包含示例配置。如果您需要配置 FTP 文件系统，可以使用以下示例配置：

php
'ftp' => [
    'driver'   => 'ftp',
    'host'     => 'ftp.example.com',
    'username' => 'your-username',
    'password' => 'your-password',

    // 可选的 FTP 设置...
    // 'port'     => 21,
    // 'root'     => '',
    // 'passive'  => true,
    // 'ssl'      => true,
    // 'timeout'  => 30,
],

Rackspace 驱动程序配置 ​

Laravel 的 Flysystem 集成与 Rackspace 配合得很好；然而，框架的默认 filesystems.php 配置文件中不包含示例配置。如果您需要配置 Rackspace 文件系统，可以使用以下示例配置：

php
'rackspace' => [
    'driver'    => 'rackspace',
    'username'  => 'your-username',
    'key'       => 'your-key',
    'container' => 'your-container',
    'endpoint'  => 'https://identity.api.rackspacecloud.com/v2.0/',
    'region'    => 'IAD',
    'url_type'  => 'publicURL',
],

获取磁盘实例 ​

Storage facade 可用于与任何已配置的磁盘交互。例如，您可以在 facade 上使用 put 方法将头像存储在默认磁盘上。如果在调用 disk 方法之前调用 Storage facade 上的方法，则方法调用将自动传递给默认磁盘：

php
use Illuminate\Support\Facades\Storage;

Storage::put('avatars/1', $fileContents);

如果您的应用程序与多个磁盘交互，您可以在 Storage facade 上使用 disk 方法来处理特定磁盘上的文件：

php
Storage::disk('s3')->put('avatars/1', $fileContents);

检索文件 ​

get 方法可用于检索文件的内容。该方法将返回文件的原始字符串内容。请记住，所有文件路径都应相对于为磁盘配置的“根”位置指定：

php
$contents = Storage::get('file.jpg');

exists 方法可用于确定磁盘上是否存在文件：

php
$exists = Storage::disk('s3')->exists('file.jpg');

文件 URL ​

使用 local 或 s3 驱动程序时，您可以使用 url 方法获取给定文件的 URL。如果您使用的是 local 驱动程序，这通常只会在给定路径前加上 /storage 并返回文件的相对 URL。如果您使用的是 s3 驱动程序，将返回完全限定的远程 URL：

php
use Illuminate\Support\Facades\Storage;

$url = Storage::url('file1.jpg');
exclamation

请记住，如果您使用的是 local 驱动程序，所有应公开访问的文件应放置在 storage/app/public 目录中。此外，您应该在 public/storage 创建一个符号链接，指向 storage/app/public 目录。

文件元数据 ​

除了读取和写入文件，Laravel 还可以提供有关文件本身的信息。例如，size 方法可用于获取文件的大小（以字节为单位）：

php
use Illuminate\Support\Facades\Storage;

$size = Storage::size('file1.jpg');

lastModified 方法返回文件上次修改的 UNIX 时间戳：

php
$time = Storage::lastModified('file1.jpg');

存储文件 ​

put 方法可用于在磁盘上存储原始文件内容。您还可以将 PHP resource 传递给 put 方法，这将使用 Flysystem 的底层流支持。处理大文件时，强烈建议使用流：

php
use Illuminate\Support\Facades\Storage;

Storage::put('file.jpg', $contents);

Storage::put('file.jpg', $resource);

自动流 ​

如果您希望 Laravel 自动管理将给定文件流式传输到您的存储位置，可以使用 putFile 或 putFileAs 方法。此方法接受 Illuminate\Http\File 或 Illuminate\Http\UploadedFile 实例，并将自动将文件流式传输到您想要的位置：

php
use Illuminate\Http\File;

// 自动生成文件名的 UUID...
Storage::putFile('photos', new File('/path/to/photo'));

// 手动指定文件名...
Storage::putFileAs('photos', new File('/path/to/photo'), 'photo.jpg');

关于 putFile 方法，有几点需要注意。请注意，我们只指定了目录名称，而不是文件名。默认情况下，putFile 方法将生成一个 UUID 作为文件名。putFile 方法将返回文件的路径，以便您可以将路径（包括生成的文件名）存储在数据库中。

putFile 和 putFileAs 方法还接受一个参数来指定存储文件的“可见性”。如果您将文件存储在云磁盘（如 S3）上，并希望文件可以公开访问，这一点特别有用：

php
Storage::putFile('photos', new File('/path/to/photo'), 'public');

在文件中添加和附加 ​

prepend 和 append 方法允许您在文件的开头或结尾写入：

php
Storage::prepend('file.log', 'Prepended Text');

Storage::append('file.log', 'Appended Text');

复制和移动文件 ​

copy 方法可用于将现有文件复制到磁盘上的新位置，而 move 方法可用于重命名或将现有文件移动到新位置：

php
Storage::copy('old/file1.jpg', 'new/file1.jpg');

Storage::move('old/file1.jpg', 'new/file1.jpg');

文件上传 ​

在 Web 应用程序中，存储文件的最常见用例之一是存储用户上传的文件，如个人资料图片、照片和文档。Laravel 使得使用上传文件实例上的 store 方法存储上传文件变得非常容易。只需调用 store 方法并指定要存储上传文件的路径：

php
<?php

namespace App\Http\Controllers;

use Illuminate\Http\Request;
use App\Http\Controllers\Controller;

class UserAvatarController extends Controller
{
    /**
     * 更新用户的头像。
     *
     * @param  Request  $request
     * @return Response
     */
    public function update(Request $request)
    {
        $path = $request->file('avatar')->store('avatars');

        return $path;
    }
}

关于此示例，有几点需要注意。请注意，我们只指定了目录名称，而不是文件名。默认情况下，store 方法将生成一个 UUID 作为文件名。store 方法将返回文件的路径，以便您可以将路径（包括生成的文件名）存储在数据库中。

您还可以在 Storage facade 上调用 putFile 方法来执行与上述示例相同的文件操作：

php
$path = Storage::putFile('avatars', $request->file('avatar'));

指定文件名 ​

如果您不希望为存储的文件自动分配文件名，可以使用 storeAs 方法，该方法接收路径、文件名和（可选）磁盘作为其参数：

php
$path = $request->file('avatar')->storeAs(
    'avatars', $request->user()->id
);

当然，您也可以使用 Storage facade 上的 putFileAs 方法，它将执行与上述示例相同的文件操作：

php
$path = Storage::putFileAs(
    'avatars', $request->file('avatar'), $request->user()->id
);

指定磁盘 ​

默认情况下，此方法将使用您的默认磁盘。如果您想指定另一个磁盘，请将磁盘名称作为第二个参数传递给 store 方法：

php
$path = $request->file('avatar')->store(
    'avatars/'.$request->user()->id, 's3'
);

文件可见性 ​

在 Laravel 的 Flysystem 集成中，“可见性”是跨多个平台的文件权限的抽象。文件可以被声明为 public 或 private。当文件被声明为 public 时，您表示该文件通常应可供他人访问。例如，使用 S3 驱动程序时，您可以检索 public 文件的 URL。

您可以在通过 put 方法设置文件时设置可见性：

php
use Illuminate\Support\Facades\Storage;

Storage::put('file.jpg', $contents, 'public');

如果文件已经存储，可以通过 getVisibility 和 setVisibility 方法检索和设置其可见性：

php
$visibility = Storage::getVisibility('file.jpg');

Storage::setVisibility('file.jpg', 'public')

删除文件 ​

delete 方法接受单个文件名或要从磁盘中删除的文件数组：

php
use Illuminate\Support\Facades\Storage;

Storage::delete('file.jpg');

Storage::delete(['file1.jpg', 'file2.jpg']);

目录 ​

获取目录中的所有文件 ​

files 方法返回给定目录中所有文件的数组。如果您希望检索给定目录中所有文件的列表，包括所有子目录，可以使用 allFiles 方法：

php
use Illuminate\Support\Facades\Storage;

$files = Storage::files($directory);

$files = Storage::allFiles($directory);

获取目录中的所有目录 ​

directories 方法返回给定目录中所有目录的数组。此外，您可以使用 allDirectories 方法获取给定目录及其所有子目录中的所有目录的列表：

php
$directories = Storage::directories($directory);

// 递归...
$directories = Storage::allDirectories($directory);

创建目录 ​

makeDirectory 方法将创建给定目录，包括任何需要的子目录：

php
Storage::makeDirectory($directory);

删除目录 ​

最后，deleteDirectory 方法可用于删除目录及其所有文件：

php
Storage::deleteDirectory($directory);

自定义文件系统 ​

Laravel 的 Flysystem 集成为多个“驱动程序”提供了开箱即用的驱动程序；然而，Flysystem 并不限于这些，并且有许多其他存储系统的适配器。如果您想在 Laravel 应用程序中使用这些额外的适配器之一，可以创建自定义驱动程序。

为了设置自定义文件系统，您需要创建一个服务提供者，例如 DropboxServiceProvider。在提供者的 boot 方法中，您可以使用 Storage facade 的 extend 方法来定义自定义驱动程序：

php
<?php

namespace App\Providers;

use Storage;
use League\Flysystem\Filesystem;
use Dropbox\Client as DropboxClient;
use Illuminate\Support\ServiceProvider;
use League\Flysystem\Dropbox\DropboxAdapter;

class DropboxServiceProvider extends ServiceProvider
{
    /**
     * 执行服务的注册后引导。
     *
     * @return void
     */
    public function boot()
    {
        Storage::extend('dropbox', function ($app, $config) {
            $client = new DropboxClient(
                $config['accessToken'], $config['clientIdentifier']
            );

            return new Filesystem(new DropboxAdapter($client));
        });
    }

    /**
     * 在容器中注册绑定。
     *
     * @return void
     */
    public function register()
    {
        //
    }
}

extend 方法的第一个参数是驱动程序的名称，第二个参数是接收 $app 和 $config 变量的闭包。解析器闭包必须返回 League\Flysystem\Filesystem 的实例。$config 变量包含在 config/filesystems.php 中为指定磁盘定义的值。

一旦创建了注册扩展的服务提供者，您就可以在 config/filesystems.php 配置文件中使用 dropbox 驱动程序。

版权所有 © 2024-2025 laravel.wiki