Files

Introduction

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 }}