Have you seen our new video tutorials? Check it out!

Files Module

Powerful driver-based asset management made easy.

Introduction

The Users module is a powerful, easy-to-use, and driver-based asset management system.

Features

The Files module comes with everything you need to manage your assets with any storage provider.

  • Folders
  • Storage Disks
  • File Management
  • Simple Structure
  • File Synchronization
  • Extension-based Storage
  • Folder MIME Restrictions
  • File Reading/Downloading/Streaming
  • Integration with Image service.
  • Integration with Laravel Filesystem.
  • Integration with Flysystem package.
  • Multiple file/drag 'n drop uploading.
  • Integration with File/Files field types.

Installation

You can install the Users module with the addon:install command:

php artisan addon:install anomaly.module.users
Notice: The Users module comes installed with PyroCMS out of the box.

Configuration

You can override Files module configuration by publishing the addon and modifying the resulting configuration file:

php artisan addon:publish anomaly.module.files

The addon will be published to /resources/{application}/addons/anomaly/files-module.

MIME Types

The anomaly.module.files::mimes.types value tells the files module what type of file is associated with a given file extension.

If your project deals with strange file types feel free to add them here under the appropriate type.

Contribute: If you think an extension should be included in configuration please submit a pull request!

Usage

This section will show you how to use the addon via API and in the view layer.

Files

Files are stream entries representing a physical file somewhere. Files must be unique per folder just as the physical file would have to be.

File Fields

Below is a list of fields in the files stream. Fields are accessed as attributes:

$file->name;

Same goes for decorated instances in Twig:

{{ file.name }}
Fields
Key Type Description

name

text

The name of the file.

disk

relationship

The disk the file is on.

folder

relationship

The folder the file is in.

extension

text

The file extension only.

size

integer

The size of the file in bytes.

mime_type

text

The MIME type of the file.

entry

polymorphic

The related entry with custom attributes.

keywords

tags

An array of organizational keywords.

height

integer

The height of the image file in pixels.

width

integer

The width of the image file in pixels.

Custom File Fields

Custom file fields associated with folders through the control panel can be accessed via the related entry. The entry is part of the type pattern.

$file->entry->custom_field;

When working with custom fields it is a good idea to verify the existence of the related entry since it only exists after editing the file through a form:

if ($entry = $file->getEntry()) {
    $entry->custom_field;
}

The file presenter allows direct access in Twig:

{{ file.custom_field }}

File Interface

This section will go over the \Anomaly\FilesModule\File\Contract\FileInterface class.

FileInterface::type()

The type method returns the file type based on the addon's configured MIMEs or null if not defined.

Returns: string or null
Example
if ($file->type() == 'audio') {
    echo "I love this song!";
}
Twig
{% if file.type() == 'audio' %}
    I love this song!
{% endif %]
FileInterface::path()

The path method returns the internal file path like folder/filename.ext.

Returns: string
Example
$file->path();
Twig
{{ file.path() }}
FileInterface::location()

The location method returns the internal file path and disk like disk://folder/filename.ext.

Returns: string
Example
$file->location();
Twig
{{ file.location() }}
Making an Image instance

// You can return an image instance with the file path {{ img("disk://folder/filename.ext").fit(100, 100)|raw }}

// Remember you can just use the file too {{ img(file).fit(100, 100)|raw }}

// And lastly the make / image method {{ file.image.fit(100, 100)|raw }} {{ file.make.fit(100, 100)|raw }}

FileInterface::image()

The image method returns an image of the \Anomaly\Streams\Platform\Image\Image class with the file as the source.

For more information on using the image class check out the Streams Platform documentation.

Returns: \Anomaly\Streams\Platform\Image\Image
Example
$file->image()->fit(100, 100)->output(); // the image tag
Twig
{{ file.image().fit(100, 100)|raw }} // the image tag
FileInterface::make()

The make method is an alias for the image method above. This method reduces confusion when your object or file relation field is called image.

Returns: \Anomaly\Streams\Platform\Image\Image
Example
$file->make()->fit(100, 100)->output(); // the image tag
Twig
{{ file.make().fit(100, 100)|raw }} // the image tag
FileInterface::resource()

The resource method returns the file resource object.

Returns: \League\Flysystem\File
Example
$resource = $file->resource();
Twig
{% set resource = file.resource() %}

File Presenter

This section will go over the \Anomaly\FilesModule\File\FilePresenter class.

FilePresenter::dimensions()

The dimensions method returns the width x height string.

Returns: string
Example
$decorated->dimensions();
Twig
{{ decorated.dimensions() }}
FilePresenter::size()

The size method returns the file size in human readable format.

Returns: string
Arguments
Key Required Type Default Description

$unit

false

string

Varies on size of file.

The unit of measurement to return. Valid options are B, KB, MB, and GB.

$decimals

false

integer

2

The decimal precision to show.

Example
$decorated->size(); // 2.5 MB
Twig
{{ decorated.size() }} // 2.5 MB
FilePresenter::preview()

The preview method returns an image thumbnail with preserved proportions.

If the file is not an image a file-type preview icon will be returned.

Returns: string
Arguments
Key Required Type Default Description

$width

false

integer

64

The maximum width constraint.

$height

false

integer

64

The maximum height constraint.

Example
$decorated->preview(100, 100);
Twig
{{ decorated.preview(100, 100)|raw }}
FilePresenter::thumbnail()

The thumbnail method returns an image thumbnail with cropped proportions.

If the file is not an image a file-type preview icon will be returned.

Returns: string
Arguments
Key Required Type Default Description

$width

false

integer

64

The thumbnail width.

$height

false

integer

64

The thumbnail height.

Example
$decorated->thumbnail(100, 100);
Twig
{{ decorated.thumbnail(100, 100)|raw }}
FilePresenter::viewPath()

The viewPath method returns the public path to view the file.

Returns: string
Example
$url->to($decorated->viewPath());
Twig
{{ url_to(decorated.viewPath()) }}
FileInterface::streamPath()

The streamPath method returns the public path to stream the file.

Returns: string
Example
$url->to($decorated->streamPath());
Twig
{{ url_to(decorated.streamPath()) }}
FilePresenter::downloadPath()

The downloadPath method returns the public path to download the file.

Returns: string
Example
$url->to($decorated->downloadPath());
Twig
{{ url_to(decorated.downloadPath()) }}
FilePresenter::__get()

The __get magic method first checks for a custom entry field before native behavior.

Returns: mixed
Arguments
Key Required Type Default Description

$name

true

string

none

The name of the attribute to access.

Example
$decorated->my_custom_field;
Twig
{{ decorated.my_custom_field }}

Folders

Folders are the basic containers that hold files. Folders have a flat structure (can not be nested).

Folder Fields

Below is a list of fields in the folders stream. Fields are accessed as attributes:

$folder->name;

Same goes for decorated instances in Twig:

{{ folder.name }}

Disks

Disks are the top-most structural component for the Files module. Files reside in a folder. Folders reside on a disk. The disk determines "where" the files are stored like locally on the server or on Amazon S3.

Disk Interface

This section will go over the features of the \Anomaly\FilesModule\Disk\Contract\DiskInterface class.

DiskInterface::filesystem()

The filesystem returns the disk adapter's filesystem.

Returns: \Anomaly\FilesModule\Disk\Adapter\AdapterFilesystem
Example
$disk->filesystem();
DiskInterface::getFolders()

The getFolders method returns a collection of related folders.

Returns: \Anomaly\FilesModule\Folder\FolderCollection
Example
foreach ($disk->getFolders() as $folder) {
    echo $folder->getName();
}
DiskInterface::folders()

The folders returns the folder relationship.

Returns: \Illuminate\Database\Eloquent\Relations\HasMany
Example
$disk->folders()->where('name', 'LIKE', '%Gallery Images')->get();

Integration

The Files module integrates tightly with Laravel's filesystem and the Flysystem package from The PHP League.

Laravel Filesystem

This section will go over how the Files module integrates with Laravel's filesystem.

Storage Disks

Disks in the Files module are automatically configured as Laravel storage disks.

You may use the disk method on the Storage facade to work with files on a particular disk using the disk's slug:

Storage::disk('local')->put('avatars/me.jpg', $fileContents);
Note: You don't HAVE to use disks from the Files module. If the disk does not exist in the Files module Laravel's filesystem will work just as it would natively.

Retrieving Files

Accessing files on a disk from the Files module works just the same as native behavior. Note, however, that you must include a folder reference since all files in the Files module belong to a folder:

$contents = Storage::disk('local')->get('example_folder/file.jpg');

$exists = Storage::disk('local')->exists('example_folder/file.jpg');

Storing Files

When you store files on a disk from the Files module the file entry will be automatically synced into the database:

Storage::disk('local')->put('example_folder/file.jpg', $contents);

Storage::disk('local')->put('example_folder/file.jpg', $resource);

Directories

Folders in the Files module act just like directories. Being that a file in the Files module requires a folder you must always define the folder path if using the Laravel filesystem with files from the Files module.

foreach ($file in Storage::disk('local')->files('example_folder')) {
    echo $file->name;
}
Creating Directories

When you create a directory in Laravel on a disk from the Files module the resulting folder will be added automatically to the Files module:

Storage::makeDirectory('My Folder'); // Makes a folder like my_folder named "My Folder"
Heads Up: Folders are always referred to by their slugs in the Files module. Even though they have a name field.
Deleting Directories

When you delete a directory in Laravel on a disk from the Files module the resulting folder and files will be deleted automatically in the Files module:

Storage::deleteDirectory('my_folder');

Flysystem Package

This section will go over how the Files module integrates with The PHP League's filesystem.

Mount Manager

Disks created in the Files module are automatically configured as mounted file systems. You can access the mounted file system using the disk's slug:

$contents = $manager->read('local://example_folder/file.jpg');

Retrieving Files

Retrieving files through the mount manager works just the same. Simply use your disk slug and folder:

$contents = $manager->read('local://example_folder/file.jpg');

Check if a file exists:

$exists = $manager->has('local://example_folder/file.jpg');

Storing Files

Writing files to a disk from the Files module works just the same using the mount manager:

$manager->write('local://example_folder/file.text', 'contents');

Updating files:

$manager->update('local://example_folder/file.text', 'new contents');

Directories

Working with directories on a disk from the Files module works just the same using the mount manager too:

foreach ($file in $manager->listFiles('local://example_folder')) {
    echo $file->name;
}
Creating Directories

When you create a directory with Flysystem on a disk from the Files module the resulting folder will be added automatically to the Files module:

$manager->createDir('My Folder'); // Makes a folder like my_folder named "My Folder"
Heads Up: Folders are always referred to by their slugs in the Files module. Even though they have a name field.
Deleting Directories

When you delete a directory using the Flysystem from a disk from the Files module the resulting folder and files will be deleted automatically in the Files module:

$manager-> deleteDir('my_folder');