PHPackages                             tobento/app-media - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [File & Storage](/categories/file-storage)
4. /
5. tobento/app-media

ActiveLibrary[File & Storage](/categories/file-storage)

tobento/app-media
=================

App media support.

2.0.3(2mo ago)0522MITPHPPHP >=8.4

Since Dec 5Pushed 2mo ago1 watchersCompare

[ Source](https://github.com/tobento-ch/app-media)[ Packagist](https://packagist.org/packages/tobento/app-media)[ Docs](https://www.tobento.ch)[ RSS](/packages/tobento-app-media/feed)WikiDiscussions 2.x Synced 1mo ago

READMEChangelog (7)Dependencies (29)Versions (9)Used By (2)

App Media
=========

[](#app-media)

The App Media package provides a set of features and services for working with media files, including:

- [responsive images](#picture-feature) using the HTML `` element
- [file display](#file-display-feature) and [file download](#file-download-feature)
- [image editing](#image-editor-feature) for cropping, resizing, and transforming images
- [upload validation](#upload-validators) for validating uploaded files

and more ...

Table of Contents
-----------------

[](#table-of-contents)

- [Getting Started](#getting-started)
    - [Requirements](#requirements)
- [Documentation](#documentation)
    - [App](#app)
    - [Media Boot](#media-boot)
        - [Media Config](#media-config)
    - [Features](#features)
        - [File Feature](#file-feature)
        - [File Display Feature](#file-display-feature)
        - [File Display Signed Feature](#file-display-signed-feature)
        - [File Download Feature](#file-download-feature)
        - [File Download Signed Feature](#file-download-signed-feature)
        - [Icons Feature](#icons-feature)
        - [Image Editor Feature](#image-editor-feature)
            - [Edit Image](#edit-image)
        - [Picture Feature](#picture-feature)
            - [Display Picture](#display-picture)
            - [Picture Definitions](#picture-definitions)
            - [Clearing Generated Picture](#clearing-generated-picture)
        - [Picture Editor Feature](#picture-editor-feature)
            - [Edit Picture](#edit-picture)
    - [Services](#services)
        - [File Storage Writer](#file-storage-writer)
        - [Copy Mode (CopyFileWrapper)](#copy-mode-copyfilewrapper)
        - [Upload Validators](#upload-validators)
        - [Uploaded File Factory](#uploaded-file-factory)
        - [Image Processor](#image-processor)
        - [Picture Generator](#picture-generator)
    - [Learn More](#learn-more)
        - [Display And Download Files Using Apps](#display-and-download-files-using-apps)
- [Credits](#credits)

---

Getting Started
===============

[](#getting-started)

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

```
composer require tobento/app-media

```

Requirements
------------

[](#requirements)

- PHP 8.4 or greater

Documentation
=============

[](#documentation)

App
---

[](#app)

Check out the [**App Skeleton**](https://github.com/tobento-ch/app-skeleton) if you are using the skeleton.

You may also check out the [**App**](https://github.com/tobento-ch/app) to learn more about the app in general.

Media Boot
----------

[](#media-boot)

The media boot does the following:

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

```
use Tobento\App\AppFactory;
use Tobento\App\Media\FeaturesInterface;

// Create the app
$app = new AppFactory()->createApp();

// Add directories:
$app->dirs()
    ->dir(realpath(__DIR__.'/../'), 'root')
    ->dir(realpath(__DIR__.'/../app/'), 'app')
    ->dir($app->dir('app').'config', 'config', group: 'config')
    ->dir($app->dir('root').'public', 'public')
    ->dir($app->dir('root').'vendor', 'vendor');

// Adding boots
$app->boot(\Tobento\App\Media\Boot\Media::class);

// Implemented interfaces:
$features = $app->get(FeaturesInterface::class);

// Run the app
$app->run();
```

### Media Config

[](#media-config)

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

Features
--------

[](#features)

### File Feature

[](#file-feature)

This feature provides convenient access to files and file URLs from any supported [file storage](https://github.com/tobento-ch/app-file-storage).
Its primary purpose is to retrieve file URLs or file objects for internal use within your application.

This feature works with both public and private storages.
Private storages are not intended to generate public URLs.
When using a private storage, the `File` feature is primarily meant for retrieving file objects for further processing within your application, not for producing URLs.

**Requirements**

This feature does not have any requirements.

**Install**

In the [media config file](#media-config) you can configure this feature:

```
'features' => [
    new Feature\File(
        // define the supported storages which have public urls:
        supportedStorages: ['images'],

        // you may throw exeptions if storage or file does not exist for debugging e.g.:
        throw: true, // false default
    ),
],
```

**Retrieve Files**

To retrieve files, use the `storage` method from the `File::class` returning a **read-only** [file storage](https://github.com/tobento-ch/service-file-storage#storage-interface). The file storage does not throw any exceptions when a file does not exists instead it returns an "empty" file.

```
use Tobento\App\Media\Feature\File;
use Tobento\Service\FileStorage\FileInterface;
use Tobento\Service\FileStorage\StorageInterface;

$fileUrl = $app->get(File::class)
    ->storage(storage: 'images')
    ->file(path: 'path/to/file.jpg')
    ->url();

$storage = $app->get(File::class)->storage(storage: 'images');
// StorageInterface

$file = $storage->file(path: 'path/to/file.jpg');
// FileInterface
```

By default, the file storage will retrieve only file urls. If you wish to retrieve other [file attributes](https://github.com/tobento-ch/service-file-storage#available-file-attributes) use the file storage `with` method:

```
use Tobento\App\Media\Feature\File;

$file = $app->get(File::class)
    ->storage(storage: 'images')
    ->with('url', 'width', 'height')
    ->file(path: 'path/to/file.jpg');
```

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

```
use Tobento\App\Media\Feature\File;

$file = $app->get(File::class)->url(storage: 'images', path: 'path/to/file.jpg');
```

**Retrieve Files Within Views**

Make sure you have booted the [View Boot](https://github.com/tobento-ch/app-view#view-boot).

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

```
$fileUrl = $view->fileStorage(storage: 'images')->file(path: 'path/to/file.jpg')->url();
```

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

```
$fileUrl = $view->fileUrl(storage: 'images', path: 'path/to/file.jpg');
```

**Using File Display Feature For Urls**

If a storage does not support public urls you may use the [File Display Feature](#file-display-feature) and in the [File Storage Config](https://github.com/tobento-ch/app-file-storage#file-storage-config) set the `public_url` parameter as the route uri configured in the [File Display Feature](#file-display-feature):

```
'storages' => [

    'files' => [
        'factory' => \Tobento\App\FileStorage\FilesystemStorageFactory::class,
        'config' => [
            // The location storing the files:
            'location' => directory('app').'storage/files/',

            // Point to the file display feature route uri:
            'public_url' => 'https://example.com/media/file/',
        ],
    ],
],
```

### File Display Feature

[](#file-display-feature)

This feature may be used to display a file from a supported [file storage](https://github.com/tobento-ch/app-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](#media-config) you can configure this feature:

```
'features' => [
    new Feature\FileDisplay(
        // define the supported storages (public-only storages are allowed):
        supportedStorages: ['images'],

        // you may change the route uri:
        routeUri: 'media/file/{storage}/{path*}', // default

        // you may define a route domain:
        routeDomain: 'media.example.com', // null is default
    ),
],
```

> **Important**
>
> This feature only works with storages of type [**public**](https://github.com/tobento-ch/service-file-storage#public-storage).
> Private storages will always result in a **404 Not Found** response.

**Display File**

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

```
https://example.com/media/file/images/path/to/file.jpg

```

To generate a file url, use the router `url` method:

```
use Tobento\Service\Routing\RouterInterface;

$router = $app->get(RouterInterface::class);

$router->url('media.file.display', ['storage' => 'images', 'path' => 'path/to/file.jpg']);
```

You may check out the [Display And Download Files Using Apps](#display-and-download-files-using-apps) if you want to serve files from a customized app.

### File Display Signed Feature

[](#file-display-signed-feature)

This feature may be used to securely display a file from a supported [file storage](https://github.com/tobento-ch/app-file-storage) using **signed URLs**.
A signed URL ensures that the file can only be accessed when the URL contains a valid cryptographic signature, and optionally an expiration timestamp.

This is ideal for displaying private or protected files such as PDFs, images, or documents that should not be publicly accessible.

**Requirements**

This feature does not have any requirements.

**Install**

In the [media config file](#media-config) you can configure this feature:

```
'features' => [
    new Feature\FileDisplaySigned(
        // define the supported storages (private-only storages are allowed):
        supportedStorages: ['uploads-private'],

        // you may change the route uri:
        routeUri: 'media/s/file/{storage}/{path*}', // default

        // you may define a route domain:
        routeDomain: 'media.example.com', // null is default
    ),
],
```

> **Important**
>
> This feature only works with storages of type [**private**](https://github.com/tobento-ch/service-file-storage#private-storage).
> Public storages will always result in a **404 Not Found** response.

**Display File**

Once installed, files can only be accessed using a **signed URL**. Unsigned URLs will always result in a **403 Forbidden** response.

A typical signed URL looks like:

```
https://example.com/media/s/file/uploads-private/path/to/file.pdf/{expires}/{signature}

```

To generate a signed file URL, use the router `url` method and call `sign`:

```
use Tobento\Service\Routing\RouterInterface;

$router = $app->get(RouterInterface::class);

$url = $router->url('media.file.display.signed', [
    'storage' => 'private',
    'path' => 'path/to/file.pdf',
])->sign();
```

For additional information on signing options and behavior, visit the [Signed URL Generation](https://github.com/tobento-ch/service-routing#signed-url-generation) section.

You may check out the [Display And Download Files Using Apps](#display-and-download-files-using-apps) if you want to serve files from a customized app.

### File Download Feature

[](#file-download-feature)

This feature may be used to force downloading a file from a supported [file storage](https://github.com/tobento-ch/app-file-storage) in the user's browser.

**Requirements**

This feature does not have any requirements.

**Install**

In the [media config file](#media-config) you can configure this feature:

```
'features' => [
    new Feature\FileDownload(
        // define the supported storages (public-only storages are allowed):
        supportedStorages: ['images'],

        // you may change the route uri:
        routeUri: 'media/download/{storage}/{path*}', // default

        // you may define a route domain:
        routeDomain: 'media.example.com', // null is default
    ),
],
```

> **Important**
>
> This feature only works with storages of type [**public**](https://github.com/tobento-ch/service-file-storage#public-storage).
> Private storages will always result in a **404 Not Found** response.

**Download File**

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

```
https://example.com/media/download/images/path/to/file.jpg

```

To generate a file url, use the router `url` method:

```
use Tobento\Service\Routing\RouterInterface;

$router = $app->get(RouterInterface::class);

$router->url('media.file.download', ['storage' => 'images', 'path' => 'path/to/file.jpg']);
```

You may check out the [Display And Download Files Using Apps](#display-and-download-files-using-apps) if you want to serve files from a customized app.

### File Download Signed Feature

[](#file-download-signed-feature)

This feature may be used to securely download a file from a supported [file storage](https://github.com/tobento-ch/app-file-storage) using **signed URLs**.
A signed URL ensures that the file can only be accessed when the URL contains a valid cryptographic signature, and optionally an expiration timestamp.

This is ideal for downloading private or protected files such as PDFs, images, or documents that should not be publicly accessible.

**Requirements**

This feature does not have any requirements.

**Install**

In the [media config file](#media-config) you can configure this feature:

```
'features' => [
    new Feature\FileDownloadSigned(
        // define the supported storages (private-only storages are allowed):
        supportedStorages: ['uploads-private'],

        // you may change the route uri:
        routeUri: 'media/s/download/{storage}/{path*}', // default

        // you may define a route domain:
        routeDomain: 'media.example.com', // null is default
    ),
],
```

> **Important**
>
> This feature only works with storages of type [**private**](https://github.com/tobento-ch/service-file-storage#private-storage).
> Public storages will always result in a **404 Not Found** response.

**Download File**

Once installed, files can only be accessed using a **signed URL**. Unsigned URLs will always result in a **403 Forbidden** response.

A typical signed URL looks like:

```
https://example.com/media/s/download/uploads-private/path/to/file.pdf/{expires}/{signature}

```

To generate a signed file URL, use the router `url` method and call `sign`:

```
use Tobento\Service\Routing\RouterInterface;

$router = $app->get(RouterInterface::class);

$url = $router->url('media.file.download.signed', [
    'storage' => 'private',
    'path' => 'path/to/file.pdf',
])->sign();
```

For additional information on signing options and behavior, visit the [Signed URL Generation](https://github.com/tobento-ch/service-routing#signed-url-generation) section.

You may check out the [Display And Download Files Using Apps](#display-and-download-files-using-apps) if you want to serve files from a customized app.

### Icons Feature

[](#icons-feature)

This feature may be used to render SVG icons using the [Icon Service](https://github.com/tobento-ch/service-icon).

**Requirements**

This feature does not have any requirements.

**Install**

In the [media config file](#media-config) you can configure this feature:

```
'features' => [
    new Feature\Icons(
        // Define the directory where to store cached icons:
        cacheDir: directory('app').'storage/icons/',

        // You may enable to throw an exception if an icon is not found.
        // This is useful during development, but in production, you may want to log a message instead (see below).
        throwIconNotFoundException: true, // default is false
    ),
],
```

**Render Icons Within Views**

To render icons within your views use the view `icon` method returning an icon implementing the [Icon Interface](https://github.com/tobento-ch/service-icon#icon-interface):

```