README

使用Flysystem作为默认实现，为PHP应用程序提供文件存储接口。

入门

运行此命令添加文件存储服务项目的最新版本。

composer require tobento/service-file-storage

要求

PHP 8.0或更高版本

亮点

框架无关，与任何项目兼容
解耦设计

文档

创建存储

查看Flysystem存储以创建存储。

文件

写入文件

use Tobento\Service\FileStorage\FileWriteException;

try {
    $storage->write(
        path: 'folder/file.txt',
        content: 'message',
    );
} catch (FileWriteException $e) {
    //
}

支持的内容

字符串
资源
实现Stringable接口的任何对象
Psr\Http\Message\StreamInterface
Tobento\Service\Filesystem\File

文件是否存在

如果文件存在，则返回true，否则返回false。

$exists = $storage->exists(path: 'folder/image.jpg');

var_dump($exists);
// bool(true)

检索文件

使用with方法检索特定文件属性。有关更多详细信息，请查看可用的文件属性。

use Tobento\Service\FileStorage\FileInterface;
use Tobento\Service\FileStorage\FileNotFoundException;

try {
    $file = $storage
        ->with('stream', 'mimeType')
        ->file(path: 'folder/image.jpg');

    var_dump($file instanceof FileInterface);
    // bool(true)
} catch (FileNotFoundException $e) {
    //
}

查看文件接口以了解更多信息。

检索文件列表

使用with方法检索特定文件属性。有关更多详细信息，请查看可用的文件属性。

use Tobento\Service\FileStorage\FilesInterface;

$files = $storage->with('stream', 'mimeType')->files(
    path: 'folder',
    recursive: false // is default
);

var_dump($files instanceof FilesInterface);
// bool(true)

查看文件接口以了解更多信息。

删除文件

use Tobento\Service\FileStorage\FileException;

try {
    $storage->delete(path: 'folder/image.jpg');
} catch (FileException $e) {
    // could not delete file
}

移动文件

use Tobento\Service\FileStorage\FileException;

try {
    $storage->move(from: 'old/image.jpg', to: 'new/image.jpg');
} catch (FileException $e) {
    // could not move file
}

复制文件

use Tobento\Service\FileStorage\FileException;

try {
    $storage->copy(from: 'old/image.jpg', to: 'new/image.jpg');
} catch (FileException $e) {
    // could not copy file
}

可用的文件属性

$file = $storage
    ->with(
        'stream',
        'mimeType',
        'size', // not needed if stream is set as it can get size from stream.
        'width', 'height', // ignored if not image.
        'lastModified',
        'url',
        'visibility',
    )
    ->file(path: 'folder/image.jpg');

$stream = $file->stream();
$mimeType = $file->mimeType();
$size = $file->size();
$width = $file->width();
$height = $file->height();
$lastModified = $file->lastModified();
$url = $file->url();
$visibility = $file->visibility();

查看文件接口以了解更多信息。

文件夹

创建文件夹

use Tobento\Service\FileStorage\FolderException;

try {
    $storage->createFolder(path: 'folder/name');
} catch (FolderException $e) {
    // could not create folder
}

文件夹是否存在

如果文件夹存在，则返回true，否则返回false。

$exists = $storage->folderExists(path: 'folder/name');

var_dump($exists);
// bool(true)

检索文件夹列表

use Tobento\Service\FileStorage\FoldersInterface;

$folders = $storage->folders(
    path: '',
    recursive: false // is default
);

var_dump($folders instanceof FoldersInterface);
// bool(true)

查看文件夹接口以了解更多信息。

删除文件夹

删除文件夹将删除指定的文件夹及其所有文件。

use Tobento\Service\FileStorage\FolderException;

try {
    $storage->deleteFolder(path: 'folder/name');
} catch (FolderException $e) {
    // could not delete folder
}

可见性

设置可见性

use Tobento\Service\FileStorage\Visibility;

$storage->setVisibility(
    path: 'folder/image.jpg',
    visibility: Visibility::PRIVATE // or Visibility::PUBLIC
);

存储

创建存储

use Tobento\Service\FileStorage\Storages;
use Tobento\Service\FileStorage\StoragesInterface;

$storages = new Storages();

var_dump($storages instanceof StoragesInterface);
// bool(true)

添加存储

添加

use Tobento\Service\FileStorage\StorageInterface;

$storages->add($storage); // StorageInterface

您可以使用register方法仅在请求时创建存储。

use Tobento\Service\FileStorage\StorageInterface;

$storages->register(
    'name',
    function(string $name): StorageInterface {
        // create storage:
        return $storage;
    }
);

获取存储

如果存储不存在或无法创建，则抛出StorageException。

use Tobento\Service\FileStorage\StorageInterface;
use Tobento\Service\FileStorage\StorageException;

$storage = $storages->get('name');

var_dump($storage instanceof StorageInterface);
// bool(true)

$storages->get('unknown');
// throws StorageException

您可以使用has方法检查存储是否存在。

var_dump($storages->has('name'));
// bool(false)

默认存储

您可以为应用程序设计添加默认存储。

use Tobento\Service\FileStorage\Storages;
use Tobento\Service\FileStorage\StorageInterface;
use Tobento\Service\FileStorage\StorageException;

$storages = new Storages();

// add "locale" storage:
$storages->add($storage);

// add default:
$storages->addDefault(name: 'primary', storage: 'local');

// get default storage for the specified name.
$primaryStorage = $storages->default('primary');

var_dump($primaryStorage instanceof StorageInterface);
// bool(true)

var_dump($storages->hasDefault('primary'));
// bool(true)

var_dump($storages->getDefaults());
// array(1) { ["primary"]=> string(5) "local" }

$storages->default('unknown');
// throws StorageException

接口

存储工厂接口

您可以使用存储工厂接口创建存储。

use Tobento\Service\FileStorage\StorageFactoryInterface;
use Tobento\Service\FileStorage\StorageInterface;
use Tobento\Service\FileStorage\StorageException;

interface StorageFactoryInterface
{
    /**
     * Create a new Storage based on the configuration.
     *
     * @param string $name Any storage name.
     * @param array $config Configuration data.
     * @return StorageInterface
     * @throws StorageException
     */
    public function createStorage(string $name, array $config = []): StorageInterface;
}

存储接口

所有方法来自

文件
文件夹
可见性

名称

返回存储名称。

var_dump($storage->name());
// string(5) "local"

存储接口

所有方法来自

添加存储
获取存储
默认存储

文件接口

use Tobento\Service\FileStorage\FileInterface;

$file = $storage
    ->with(
        'stream', 'mimeType', 'size', 'width',
        'lastModified', 'url', 'visibility',
    )
    ->file(path: 'folder/image.jpg');
    
var_dump($file instanceof FileInterface);
// bool(true)

方法

var_dump($file->path());
// string(16) "folder/image.jpg"

var_dump($file->name());
// string(9) "image.jpg"

var_dump($file->filename());
// string(5) "image"

var_dump($file->extension());
// string(3) "jpg"

var_dump($file->folderPath());
// string(6) "folder"

var_dump($file->stream() instanceof \Psr\Http\Message\StreamInterface);
// bool(true) or NULL

var_dump($file->content());
// string(...) or NULL

var_dump($file->mimeType());
// string(10) "image/jpeg" or NULL

var_dump($file->size());
// int(20042) or NULL

var_dump($file->width());
// int(450) or NULL

var_dump($file->height());
// int(450) or NULL

var_dump($file->lastModified());
// int(1672822057) or NULL

var_dump($file->url());
// string(40) "https://www.example.com/folder/image.jpg" or NULL

var_dump($file->visibility());
// string(6) "public" or NULL

var_dump($file->metadata());
// array(0) { }

var_dump($file->isHtmlImage());
// bool(true)

文件接口

use Tobento\Service\FileStorage\FilesInterface;

$files = $storage->with('stream', 'mimeType')->files(
    path: 'folder',
    recursive: false // is default
);

var_dump($files instanceof FilesInterface);
// bool(true)

var_dump($files instanceof \IteratorAggregate);
// bool(true)

过滤器

返回具有过滤文件的新的实例。

use Tobento\Service\FileStorage\FileInterface;
use Tobento\Service\FileStorage\Visibility;

$files = $files->filter(
    fn(FileInterface $f): bool => $f->visibility() === Visibility::PUBLIC
);

排序

返回具有排序文件的新的实例。

use Tobento\Service\FileStorage\FileInterface;

$files = $files->sort(
    fn(FileInterface $a, FileInterface $b) => $a->path() <=> $b->path()
);

全部

返回所有文件。

use Tobento\Service\FileStorage\FileInterface;

foreach($files->all() as $file) {
    var_dump($file instanceof FileInterface);
    // bool(true)
}

// or just
foreach($files as $file) {}

文件夹接口

use Tobento\Service\FileStorage\FolderInterface;

foreach($storage->folders(path: 'foo') as $folder) {
    var_dump($folder instanceof FolderInterface);
    // bool(true)
}

方法

var_dump($folder->path());
// string(7) "foo/bar"

var_dump($folder->parentPath());
// string(3) "foo"

var_dump($folder->name());
// string(3) "bar"

var_dump($folder->lastModified());
// int(1671889402) or NULL

var_dump($folder->visibility());
// string(6) "public" or NULL

var_dump($folder->metadata());
// array(0) { }

文件夹接口

use Tobento\Service\FileStorage\FoldersInterface;

$folders = $storage->folders(path: '');

var_dump($folders instanceof FoldersInterface);
// bool(true)

过滤器

返回具有过滤文件夹的新实例。

use Tobento\Service\FileStorage\FolderInterface;
use Tobento\Service\FileStorage\Visibility;

$folders = $folders->filter(
    fn(FolderInterface $f): bool => $f->visibility() === Visibility::PUBLIC
);

排序

返回具有排序文件夹的新实例。

use Tobento\Service\FileStorage\FolderInterface;

$folders = $folders->sort(
    fn(FolderInterface $a, FolderInterface $b) => $a->path() <=> $b->path()
);

第一个

返回第一个文件夹或null（如果没有）。

use Tobento\Service\FileStorage\FolderInterface;

$folder = $folders->first();

// null|FolderInterface

获取

通过路径返回文件夹或null（如果不存在）。

use Tobento\Service\FileStorage\FolderInterface;

$folder = $folders->get(path: 'foo');

// null|FolderInterface

全部

返回所有文件夹。

use Tobento\Service\FileStorage\FolderInterface;

foreach($folders->all() as $folder) {
    var_dump($folder instanceof FolderInterface);
    // bool(true)
}

// or just
foreach($folders as $folder) {}

Flysystem

查看League Flysystem以了解更多信息。

Flysystem存储

use Tobento\Service\FileStorage\Flysystem;
use Tobento\Service\FileStorage\StorageInterface;
use Nyholm\Psr7\Factory\Psr17Factory;

$filesystem = new \League\Flysystem\Filesystem(
    adapter: new \League\Flysystem\Local\LocalFilesystemAdapter(
        location: __DIR__.'/root/directory/'
    )
);

$storage = new Flysystem\Storage(
    name: 'local',
    flysystem: $filesystem,
    fileFactory: new Flysystem\FileFactory(
        flysystem: $filesystem,
        streamFactory: new Psr17Factory()
    ),
);

var_dump($storage instanceof StorageInterface);
// bool(true)

tobento / service-file-storage

维护者

详细信息

README

目录

入门

要求

亮点

文档

创建存储

文件

写入文件

文件是否存在

检索文件

检索文件列表

删除文件

移动文件

复制文件

可用的文件属性

文件夹

创建文件夹

文件夹是否存在

检索文件夹列表

删除文件夹

可见性

设置可见性

存储

创建存储

添加存储

获取存储

默认存储

接口

存储工厂接口

存储接口

存储接口

文件接口

文件接口

文件夹接口

文件夹接口

Flysystem

Flysystem存储

致谢