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