Download the PHP package tobento/app-media without Composer

App Media

The app media provides features and services such as:

• responsive images using the HTML picture element
• file download
• image editor to crop, resize and other actions to modify images
• upload validator to validate uploaded files

and more ...

Table of Contents

• Getting Started
  • Requirements
• Documentation
  • App
  • Media Boot
    • Media Config
  • Features
    • File Feature
    • File Display Feature
    • File Download Feature
    • Icons Feature
    • Image Editor Feature
      • Edit Image
    • Picture Feature
      • Display Picture
      • Picture Definitions
      • Clearing Generated Picture
    • Picture Editor Feature
      • Edit Picture
  • Services
    • File Writer
    • Upload Validator
    • Uploaded File Factory
    • Image Processor
  • Learn More
    • Display And Download Files Using Apps
• Credits

  ---

Getting Started

Add the latest version of the app media project running this command.

Requirements

• PHP 8.0 or greater

Documentation

App

Check out the App Skeleton if you are using the skeleton.

You may also check out the App to learn more about the app in general.

Media Boot

The media boot does the following:

• installs and loads the media config
• implements media interfaces
• boots features from media config

Media Config

The configuration for the media is located in the file at the default App Skeleton config location.

Features

File Feature

This feature may be used to retrieve files from a supported file storage. The main aim of this feature is to retrieve file urls.

Requirements

This feature does not have any requirements.

Install

In the media config file you can configure this feature:

Retrieve Files

To retrieve files, use the method from the returning a read-only file storage. The file storage does not throw any exceptions when a file does not exists instead it returns an "empty" file.

By default, the file storage will retrieve only file urls. If you wish to retrieve other file attributes use the file storage method:

If you only want to retrieve a file url, you may prefer to use the method instead:

Retrieve Files Within Views

Make sure you have booted the View Boot.

Use the view method to retrieve file(s) within your views:

If you only want to retrieve a file url, you may prefer to use the method instead:

Using File Display Feature For Urls

If a storage does not support public urls you may use the File Display Feature:

File Display Feature

This feature may be used to display a file from a supported file storage, such as an image or PDF, directly in the user's browser.

Requirements

This feature does not have any requirements.

Install

In the media config file you can configure this feature:

Display File

Once installed, files will be publicly accessible by the defined route uri:

To generate a file url, use the router method:

You may check out the Display And Download Files Using Apps if you want to serve files from a customized app.

File Download Feature

This feature may be used to force downloading a file from a supported file storage in the user's browser.

Requirements

This feature does not have any requirements.

Install

In the media config file you can configure this feature:

Download File

Once installed, files will be publicly accessible by the defined route uri:

To generate a file url, use the router method:

You may check out the Display And Download Files Using Apps if you want to serve files from a customized app.

Icons Feature

This feature may be used to render SVG icons using the Icon Service.

Requirements

This feature does not have any requirements.

Install

In the media config file you can configure this feature:

Render Icons Within Views

To render icons within your views use the view method returning an icon implementing the Icon Interface:

Access Icons

In addition, to render icons you may just access them within any service:

Storing SVG icons

Store your SVG icon files in the directory:

Clear cached icons

To clear cached icons you may delete the defined folder manually or run the following command:

During development, if you store more SVG icons, you will need to clear the cache to see the changes!

Log Not Found Icons

Make sure you have booted the App Logging Boot.

In the file you may define the logger to be used, otherwise the default logger will be used:

Image Editor Feature

This feature may be used to edit images.

Requirements

This features requires:

Install

In the media config file you can configure this feature:

Edit Image

Use the route name to generate the url where you can edit the specified image.

Events

The will dispatch after the image is edited.

Picture Feature

This feature may be used to generate HTML markup for responsive images using the HTML picture element.

Workflow

If images are not created yet when you display a picture, a picture job will be sent to the defined queue, generating the images in the background and returning a "fallback" picture from the defined resource. Once, the images are generated, the picture will be displayed with the images generated.

Requirements

This feature does not have any requirements.

Install

In the media config file you can configure this feature:

Make sure you have configured the defined storages in the App File Storage Config.

Make sure you have configured the defined queue in the App Queue Config.

Logging

Make sure you have booted the App Logging Boot.

In the file you may define the logger to be used, otherwise the default logger will be used:

Display Picture

Within your view file, use the method to display a picture based on the given , and parameter:

Example Using A Named Definition

You may use named definitions to generate images from. Check out the Picture Definitions section to learn how to add named definitions.

Depending on your definition this will output:

Using named definitions have the following advantages:

• you can crop images based on the named definition
• you can have different definitions per view theme

Example Using A Definition

Check out the Picture Definition section to learn more about definitions in general.

Example Using An Imager Resource

Check out the Picture Creating - Create Picture From Resource section to learn more about.

Picture Definitions

Store your picture definition JSON files in the directory:

You may check out the Json Files Definitions for more information.

Clearing Generated Picture

Using Console Command

To clear all generated pictures run the following command:

Or clear generated pictures of specific definitions only:

Picture Editor Feature

This feature requires the Picture Feature to be installed.

Requirements

This features requires:

Install

In the media config file you can configure this feature:

Edit Picture

Use the route name to generate the url where you can edit the specified picture.

Events

The will dispatch after the picture is edited.

Services

File Writer

The file writer class writes the given file to the defined File Storage.

You may check out the Image Processor section to learn more about it.

writeFromStream

Use the method to write the given stream to the file storage:

writeUploadedFile

Use the method to write the given uploaded file to the file storage:

It is highly recommended to use the Upload Validator before writing the uploaded file to the file storage.

writeResponse

Upload Validator

The upload validator validates the given uploaded file.

validateUploadedFile

Use the method to validate the given uploaded file:

Security

The validator validates that

• the file extension and mime type detected by its content is allowed
• the client filename extension, client media type of the file is consistent with its content
• the filename consists only of alphanumeric characters, hyphen, spaces, and periods if is set to (default)
• the filename length does not exceed the defined parameter
• the file size does not exceed the defined parameter. Default is unlimited

Once the uploaded file is validated and valid, you can be sure that

• the is allowed, consistent with its file content and extension
• the file extension is allowed and consistent with its file content

The only thing you have to take care of is the filename except the extension:

If you use the File Writer to store files, make sure the parameter is configured safely.

File Storage Location

Always store uploaded files outside the webroot or on a different host. If using the File Writer to store files, make sure your defined is outside the webroot such as the default configured storage.

Resources

You may read the File Upload Cheatsheet - owasp.org.

Uploaded File Factory

The upload file factory may be used to create uploaded files from different resources.

createFromRemoteUrl

Use the method to create an uploaded file from a remote url:

createFromStorageFile

Use the method to create an uploaded file from a Storage File:

Image Processor

The image processor class processes the given image with the defined actions using the Imager Service.

processFromResource

Use the method to process the given resource:

Check out the Resource and Encoded documentation to learn more.

processFromStream

Use the method to process the given stream:

Check out the Encoded documentation to learn more.

Learn More

Display And Download Files Using Apps

You may use the Apps to create multiple apps, one for your main app and one for displaying and downloading files only:

Once you have created and configured your apps you may

In Media File Display App

In Main App

Credits

• Tobias Strub
• All Contributors