README

Laravel 文件系统管理器 是一个用于上传/查看文件并将其作为资源检索到前端文件管理器界面的项目 如果有任何建议，请提出。

作者: MCris112
供应商: mcris112
包: laravel-file-system-manager
版本: 1.x
PHP 版本: 8.1+
Laravel 版本: 10.x

安装

使用以下命令安装包 Composer:

composer require mcris112/laravel-file-system-manager

配置

发布配置文件

php artisan vendor:publish --tag="filesystemmanager.config"

添加/删除你将使用的磁盘驱动器大小

return [
    "storage" => [
        /********************************
         *
         * Define here what storage disk drivers should be supported
         * and the storage size has each driver
         *
         */
        'size' => [
            "local" => env('FM_STORAGE_LOCAL_SIZE', "1GB"),
            "public" => env('FM_STORAGE_PUBLIC_SIZE', "1GB"),
            //"s3" => env('FM_STORAGE_S3_SIZE', 0),
        ],
    ],

    /********************************
     *
     *  This is required to get authenticated user at StorageController
     *  to check if the user can view the file
     *
     */
    'auth' => [
        'user' => fn() => auth()->user() // ?? auth('api)->user()
    ],

在 Users 模型中，需要添加 CanViewFmFilePrivate，这是检查用户是否可以在路由 '.../storage/{disk}/{path}' 上查看当前选中文件的必要条件

use MCris112\FileSystemManager\Traits\CanViewFmFilePrivate;

class User extends Authenticatable
{
    use CanViewFmFilePrivate;

    //...
}

入门

保存文件

use MCris112\FileSystemManager\Facades\FileSystemManager;

FileSystemManager::file()->save(
    $request->file('content'),
    true, //is Public?
    1,¨// created by id (Comes from user id)
    'test/', // folder where it will be saved
    null, // name - If name is not set, It will take filename of file
    function (FmFileContent $data, FmFile $model){ // Do something after save, this can be null
        // Do something
    }
);

// This return a FmFile model
$model = FileSystemManager::file()->save(...);

使用不同的磁盘管理器

只需使用静态函数 disk 来更改

$model = FileSystemManager::disk('s3')->file()->save(...);

函数

URL

use \MCris112\FileSystemManager\Facades\FileSystemManager;
use \MCris112\FileSystemManager\Models\FmFile;

// Get URL by model
$url = FileSystemManager::url( FmFile::first() );

// Get by path
$url = FileSystemManager::url( "documents/your-filename.jpg" );

管理大小

获取配置和保存内容中设置的全球信息

use \MCris112\FileSystemManager\Facades\FileSystemManager;

// Retrieve the size used in kilobytes
$size = FileSystemManager::used();

// All size allowed
$size = FileSystemManager::size();

// How much space is left
$size = FileSystemManager::left();

通过特定类型的内容获取信息

use \MCris112\FileSystemManager\Facades\FileSystemManager;

// Get how much storage file is using
$size = FileSystemManager::file()->used();

// Get how much storage Avatar is using
$size = FileSystemManager::avatar()->used();

内容

获取这些信息以在文件管理器界面中显示。获取没有目录作为父级的文件模型分页列表

$list = FileSystemManager::content();

$load = 15;
// Can search by specific records - Returns CollectionsFmFileCollection
$list = FileSystemManager::list(
    $load // -> How many files will get in paginated list
);

从 Base 64

将 Base 64 编码转换为 UploadFile

/** @var Illuminate\Http\UploadedFile $list */
$list = FileSystemManager::fromBase64("base64...");

集合

当你获取文件模型集合时，它有一个可用的函数

use \MCris112\FileSystemManager\Models\FmFile;
use \MCris112\FileSystemManager\Collections\FmFileCollection;


/** @var FmFileCollection $models */
$models = FmFile::get();

// You can use
$models->toResource(); // This will return a FmFileListResource::collection()

特质

资源

将资源关系转换为前端响应。使用特质 ResourceFmImageVariationTransformation 来使用函数 $this->fmImageVariation()

use MCris112\FileSystemManager\Traits\Resource\ResourceFmImageVariationTransformation;

class ProductResource extends JsonResource
{
    use ResourceFmImageVariationTransformation;

    public function toArray(Request $request): array
    {
        return [
            'id' => $this->id,
            "name" => $this->name,

            // This function converts the normal relation into a complex array
            'image' => $this->fmImageVariation(),

            "timestamps" => [
                "createdAt" => $this->created_at,
                "updatedAt" => $this->updated_at,
            ]
        ];
    }

}

之前

{
    "id": 1,
    "name": "Aspernatur voluptas non illum. Ut sit suscipit explicabo.",
    "image": [
        {
            "id": 32,
            "filename": "..."
            //....
            "pivot": {
                //...
                "field": "full"
            }
        },
        {
            "id": 33,
            "filename": "..."
            //....
            "pivot": {
                //...
                "field": "thumbnail"
            }
        }
    ],
    "timestamps": {
        "createdAt": "2024-04-13T17:33:41.000000Z",
        "updatedAt": "2024-04-13T17:33:41.000000Z"
    }
}

之后

{
    "id": 1,
    "name": "Aspernatur voluptas non illum. Ut sit suscipit explicabo.",
    "image": {
        "full": {
            //.... FmFileListResource
        },
        "thumbnail": {
            //.... FmFileListResource
        }
    },
    "timestamps": {
        "createdAt": "2024-04-13T17:33:41.000000Z",
        "updatedAt": "2024-04-13T17:33:41.000000Z"
    }
}

自定义资源转换

如果你想在函数 $this->fmImageVariation() 中自定义资源，只需更改类中的内容

use MCris112\FileSystemManager\Traits\Resource\ResourceFmImageVariationTransformation;

class ProductResource extends JsonResource
{
    use ResourceFmImageVariationTransformation;

    //Replace with your custom resource
    protected string $fmImageResource = FmFileListResource::class;
}

有图片

如果你想使模型具有图片，你可以通过特质和表定义该关系

模型

use MCris112\FileSystemManager\Traits\HasFmImage;

class SomeModel extends Model
{
    use HasFmImage;
}

迁移

use MCris112\FileSystemManager\Facades\FileSystemManagerTable;

public function up(): void
{
    Schema::create('some_model', function (Blueprint $table) {
        //This will define the relationship on table
        FileSystemManagerTable::hasImage($table);
    });
}

有图片变体

如果有不同的图片变体

use MCris112\FileSystemManager\Traits\HasFmImageVariations;
use MCris112\FileSystemManager\Enums\FmFileSize;

class Product extends Model
{
    use HasFmImageVariations;
}

// Can load all image variations
Product::with('fmimages')->get();
$prodcut->load('fmimages');

//Just load specific image variation
Product::withThumbnail()->get()
Product::withSquareImage()->get()

/**
 * Load all or specific image size
 * @param array|string|FmFileSize|null $sizes can be '*'|null for load all image sizes or an array for load specific image sizes
 */
Product::withFmImageSize(FmFileSize::VIDEO)->get()

FmPagination

use \Illuminate\Http\Resources\Json\ResourceCollection;
use MCris112\FileSystemManager\Traits\FmPagination;

class YourResource extends ResourceCollection
{
    use FmPagination;

    public function toArray(\Illuminate\Http\Request $request){
        return [
            "data" => $this->collection,
            // now you can use this function to retrieve easily the pagination data
            "pagination" => $this->paginate();
        ];
    }
}


// FmPagination does
return [
    'total' => $this->total(),
    'perPage' => $this->perPage(),
    'currentPage' => $this->currentPage(),
    'totalPages' => $this->lastPage()
];

类别

文件夹

创建文件夹

use \MCris112\FileSystemManager\Facades\FileSystemManager;


$folderManager = FileSystemManager::folder()->create("Name of folder");

文件夹内容

use \MCris112\FileSystemManager\Facades\FileSystemManager;

/**
 * Get the parents of files and folder to show it into the file manager interface
 * @param int $id
 * @param int|null $perPage
 * @return \MCris112\FileSystemManager\FileManagerContent
 */
$content = FileSystemManager::folder()->content( $folderId )

搜索文件夹

use \MCris112\FileSystemManager\Facades\FileSystemManager;

/**
* @param string $name
* @param int|null $perPage
* @return \Illuminate\Contracts\Pagination\LengthAwarePaginator
*/
$content = FileSystemManager::folder()->search( "content" )

查找文件夹

use \MCris112\FileSystemManager\Facades\FileSystemManager;

/**
 * @param int $id
 * @return \MCris112\FileSystemManager\Models\FmFolder
 */
$content = FileSystemManager::folder()->find( $id )

文件夹父级

如果你想创建子文件夹，你可以定义父文件夹

use \MCris112\FileSystemManager\Facades\FileSystemManager;


$folderManager = FileSystemManager::folder( $FmFodlerOrIntOrNullableValue );

//Now will create a sub folder from parent folder
$folderManager->create("Sub Folder Name");

//For any case you couldnt set a parent folder, you can set it
$folderManager->parent($FmFodlerOrIntOrNullableValue)->create();

放入文件夹

要保存一些内容在文件夹中，只需这样做

use \MCris112\FileSystemManager\Facades\FileSystemManager;


$folderManager = FileSystemManager::folder( $FmFodlerOrIntOrNullableValue );

//Now will create a sub folder from parent folder
$folderManager->create("Sub Folder Name");

//For any case you couldnt set a parent folder, you can set it
$folderManager->parent($FmFodlerOrIntOrNullableValue)->create();

删除文件夹或内容

use \MCris112\FileSystemManager\Facades\FileSystemManager;

// For delete an specific file or content
$folderManager = FileSystemManager::folder($folder)->delete($fmFileOrFmFolderOrArray);

// For delete the folder
$folderManager = FileSystemManager::folder($folder)->delete();

// For delete the folder and the content inside
$folderManager = FileSystemManager::folder($folder)->delete(null , true);

文件

搜索文件

use \MCris112\FileSystemManager\Facades\FileSystemManager;

/**
* @param string $name
* @param int|null $perPage
* @return \Illuminate\Contracts\Pagination\LengthAwarePaginator
*/
$content = FileSystemManager::folder()->search( "content" )

查找文件

use \MCris112\FileSystemManager\Facades\FileSystemManager;

/**
 * Find a file by id or full path (folder + filename)
 * @param int|string $idOrPath
 * @return FmFile
 * @throws FmFileNotFoundException
 */
$content = FileSystemManager::folder()->find( $id )

为什么使用 FileSystemManager::folder()->find( $id ) 而不是 FmFile::find($id) 或 FmFile::whereId($id)->get()，你可以使用它，但在这种情况下将返回一个完整的缓存模型。

删除文件

use \MCris112\FileSystemManager\Facades\FileSystemManager;

$folderManager = FileSystemManager::file($file)->delete();

//or

/** @var \MCris112\FileSystemManager\Models\FmFile $file */
$file->delete(); // Automatically It will delete the file in your disk

为什么使用 FileSystemManager::file($file)->delete() 而不是 $file->delete()，在这种情况下，如果在销毁文件时发生错误，你的数据库中的记录将不会回滚，并且将生成一个错误的存储大小总和

头像

使用前

配置

如果你要使用头像，别忘了配置 filesystemmanager.php

return [
    //...
    "user" => [
        "avatar" => true, // Set this true to start using avatars
        "width" => 512, // Avatar width
        "height" => 512, // Avatar height
        "quality" => 80, // file quality of JPG
        "generatorUrl" => "https://ui-avatars.com/api/?size=512&name="
    ]
]

将 UserHasAvatar 特质添加到模型中，以避免在生成基于名称的头像时出现空值错误，但如果你始终会设置一个文件，你可以避免此步骤

use MCris112\FileSystemManager\Traits\UserHasAvatar;

class User extends Authenticatable
{
    use UserHasAvatar;

    //...
}

已使用

头像使用多少存储空间

use \MCris112\FileSystemManager\Facades\FileSystemManager;

$avatarManager = FileSystemManager::avatar()->used()

头像 URL

从用户处获取头像URL

use \MCris112\FileSystemManager\Facades\FileSystemManager;

$user = \App\Models\User::first();

$avatarManager = FileSystemManager::avatar()->user($user)->url();

//or
$avatarManager = FileSystemManager::avatar($user)->url();

//or
$user->avatar()->url();

创建头像

您可以定义文件，但也可以将其设置为null，此时将根据姓名创建头像

use \MCris112\FileSystemManager\Facades\FileSystemManager;


/**
 * @param UploadedFile|null $file
 * @return User
 */
public function create(?UploadedFile $file = null): User
{
    //...
}

$user = \App\Models\User::first();

FileSystemManager::avatar()->user($user)->create($file);

//or
FileSystemManager::avatar($user)->create($file);

//or
$user->avatar()->create($file);

mcris112 / file-manager-system

维护者

详细信息