Download the PHP package tobento/service-file-storage without Composer

File Storage Service

File storage interface for PHP applications using Flysystem as default implementation.

Table of Contents

• Getting started
  • Requirements
  • Highlights
• Documentation
  • Create Storage
    • Public Storage
    • Private Storage
  • File
    • Write File
    • File Exists
    • Retrieve File
    • Retrieve Files
    • Delete File
    • Move File
    • Copy File
    • Available File Attributes
  • Folder
    • Create Folder
    • Folder Exists
    • Retrieve Folders
    • Delete Folder
  • Storages
    • Create Storages
    • Add Storages
    • Get Storage
    • Default Storages
  • Available Storages
    • Flysystem Storage
    • Null Storage
    • Read Only Storage Adapter
  • Interfaces
    • Storage Factory Interface
    • Storage Interface
    • Storages Interfaces
    • File Interface
    • Files Interface
    • Folder Interface
    • Folders Interface
  • Repositories
    • File Repository
    • Folder Repository
    • File and Folder Repository
    • Using Repositories with App CRUD
• Credits

  ---

Getting started

Add the latest version of the file storage service project running this command.

Requirements

• PHP 8.4 or greater

Highlights

• Framework-agnostic, will work with any project
• Decoupled design

Documentation

Create Storage

Check out the Available Storages section to create storages.

Public Storage

Public storages are intended for assets that can be accessed directly by end-users.

• URL available (when configured, e.g. via public_url)
• No signing required
• For public assets, such as:
  • website images
  • CSS / JS files
  • thumbnails
  • media intended for direct embedding

Public storage is ideal when files should be openly accessible without authentication.

Create Public Storage

Check out the Available Storages section to create storages using the appropriate storage adapter.
A public storage is created by setting its type to public.
If the storage adapter supports direct URL generation (for example in the Flysystem Storage),
you may configure a public_url to enable public file URLs.

Note

The storage type does not automatically make files public.
It is a semantic flag that your application and configuration must handle correctly
(for example by defining a public_url or implementing access control).

Private Storage

Private storages are intended for files that must not be directly exposed.

• No direct URL
• Access only through your application
• Can generate signed URLs (if your app implements this)
• Used for, for example:
  • user uploads
  • original images (before processing)
  • protected downloads
  • documents behind authentication
  • editor-only or unpublished assets

Private storage is ideal when you need full control over who can access a file.

Create Private Storage

Check out the Available Storages section to create storages using the appropriate storage adapter.
A private storage is created by setting its type to private.

Note

The storage type does not automatically make files private.
It is a semantic flag that your application and configuration must handle correctly.

File

Write File

supported content

• any object implementing

File Exists

Returns if file exists, otherwise .

Retrieve File

Use the with method to retrieve specific file attributes. Check out the Available File Attributes for more detail.

Check out the File Interface to learn more about it.

Retrieve Files

Use the with method to retrieve specific file attributes. Check out the Available File Attributes for more detail.

Check out the Files Interface to learn more about it.

Delete File

Move File

Copy File

Available File Attributes

Check out the File Interface to learn more about it.

Folder

Create Folder

Folder Exists

Returns if folder exists, otherwise .

Retrieve Folders

Check out the Folders Interface to learn more about it.

Delete Folder

Deleting a folder will delete the specified folder and all of its files.

Storages

Create Storages

Add Storages

add

register

You may use the register method to only create the storage if requested.

Get Storage

If the storage does not exist or could not get created it throws a StorageException.

You may use the method to check if a storage exists.

Default Storages

You may add default storages for your application design.

Available Storages

Flysystem Storage

Check out the League Flysystem to learn more about it.

Null Storage

Read Only Storage Adapter

Any storage implementing the can be made read-only by decorating them using the :

Interfaces

Storage Factory Interface

You may use the storage factory interface for creating storages.

Storage Interface

All methods from:

• File
• Folder

name

Returns the storage name.

type

Returns the storage type (public or private).

isPublic

Returns true if the storage is public.

isPrivate

Returns true if the storage is private.

Storages Interface

All methods from:

• Add Storages
• Get Storage
• Default Storages

File Interface

Methods

Files Interface

filter

Returns a new instance with the filtered files.

sort

Returns a new instance with the files sorted.

all

Returns all files.

Folder Interface

Methods

Folders Interface

filter

Returns a new instance with the filtered folders.

sort

Returns a new instance with the folders sorted.

first

Returns the first folder or null if none.

get

Returns the folder by path or null if not exists.

all

Returns all folders.

Repositories

The file storage service provides optional repository abstractions for querying files and folders using a consistent, storage-agnostic API.
Repositories allow you to filter, sort, and retrieve filesystem items in a structured way, similar to database repositories.

Using repositories is optional.
To enable them, install the following packages:

• tobento/service-repository
  Provides the base repository interfaces and exceptions.

• tobento/service-repository-storage
  Provides repository implementations backed by storage services.

• tobento/service-storage
  Required for storage-based repositories (files, folders, etc.).

Repositories can also be used together with
tobento/app-crud
to build CRUD interfaces or file manager UIs, as the repository API is fully compatible out of the box.
This integration is optional and not required to use repositories.

Repositories also integrate seamlessly with
tobento/app-search,
allowing you to make files and folders searchable using the RepositorySearchable adapter.
This integration is optional and not required to use repositories.

File Repository

The File Repository offers a structured, storage-agnostic way to query files from a storage location.
It supports filtering, sorting, limits, recursive traversal, and root folder scoping.

The repository is provided by
tobento/service-repository-storage,
which contains the full repository documentation, and relies on
tobento/service-repository
for the base repository interfaces.

By default, all file attributes are loaded, and recursive mode is disabled (false).
See the list of available attributes under
Available File Attributes.

Creation Behavior

1. FileSource-driven creation (no content provided)

If the content attribute is not provided, the repository assumes that:

• a FileSource Field - App CRUD or another external component has already written the file to storage
• the repository should only resolve and return the file entity

In this mode:

• No write operation is performed
• The repository attempts to load the file using findById()
• If the file does not exist, a RepositoryCreateException is thrown

This is ideal for upload pipelines where the file is already stored before the repository is invoked.

2. Repository-driven creation (with content)

If the content attribute is provided, the repository writes the file to storage:

Steps performed:

1. The repository writes the file using StorageInterface::write()
2. It then resolves the file entity via findById()
3. If the file cannot be resolved, a RepositoryCreateException is thrown

Folder Repository

The Folder Repository provides a structured, storage-agnostic way to query folders from a storage location.
It supports filtering, sorting, limits, recursive traversal, and root folder scoping.

The repository is provided by
tobento/service-repository-storage,
which contains the full repository documentation, and relies on
tobento/service-repository
for the base repository interfaces.

By default, all folder data is loaded, and recursive mode is disabled (false).

Creation Behavior

The repository creates folders using the underlying storage's createFolder() method. After creation, the repository resolves the folder entity using findById() to ensure it exists and is fully hydrated.

Steps performed:

1. The repository validates that a valid path is provided
2. It creates the folder using StorageInterface::createFolder()
3. It resolves the folder entity via findById()
4. If the folder cannot be resolved, a RepositoryCreateException is thrown

File and Folder Repository

The File and Folder Repository provides a unified way to query both files and folders from a storage location.
It supports filtering, sorting, limits, recursive traversal, and root folder scoping, returning a mixed collection of filesystem items.

The repository is provided by
tobento/service-repository-storage,
which contains the full repository documentation, and relies on
tobento/service-repository
for the base repository interfaces.

By default, recursive mode is disabled (false), and all file and folder data is loaded.

Creation Behavior

1. Explicit type (file or folder)

If the type attribute is provided, it takes precedence:

This directly delegates to either:

• FileRepository::create()
• FolderRepository::create()

2. Content provided: file

If the content attribute exists, the repository treats the entity as a file:

This mirrors the behavior of the FileRepository.

3. Path contains a file extension: file

If no explicit type is given and no content is provided, the repository inspects the path:

If the path contains a file extension (e.g. .jpg, .png, .txt), the repository assumes it is a file.

This makes the API intuitive and filesystem-friendly.

4. Default behavior: folder

If none of the above conditions apply, the repository treats the entity as a folder:

This mirrors the behavior of the FolderRepository.

Using Repositories with App CRUD

The File, Folder, and FileFolder repositories can be used directly with tobento/app-crud to build full CRUD interfaces for file storage. However, because file paths behave differently from typical numeric IDs, there are two important considerations.

1. Routing for Recursive Paths

File and folder identifiers are paths, not integers. When recursive mode is enabled, IDs may contain slashes:

This requires a custom route parameter pattern.

Default CRUD routing is not sufficient

will stop at the first slash and break for nested paths.

Correct routing configuration

Why this is needed

• {id*} allows the ID to contain slashes
• Without it, CRUD cannot resolve nested file paths
• This applies to show, edit, update, and delete routes
• This applies to all routes that accept an entity ID - typically show, and delete. (Edit and update are not supported for file storage repositories.)

2. Entity ID Name and Entity Mapping

CRUD needs to know which attribute represents the entity's primary key. For file storage, this is not always the filename.

Credits

• Tobias Strub
• All Contributors
• League Flysystem