Preface

Introduction

A Platform 9 extension to manage media.

Have a read through the Installation Guide.

Features

• Create, update, delete files.
• Email files.
• Set media visibility to private/public.
• Share file urls.
• Download files.
• Blade call to retrieve the path to a media file.
• Blade call to perform file uploads.
• Add tags.
• Create config styles.

Examples

The $media variable used below is a reference to the MediaRepository.

$media = app('platform.media');

Retrieve a media entry

$media = $media->find(1);

Dynamically upload a new file

// $file must be an instance of `Symfony\Component\HttpFoundation\File\UploadedFile`

$media->upload($file, [
    'name' => 'Foobar',
]);

Setup

Installation

The best and easiest way to install the Media extension is with Composer.

Preparation

Open your composer.json file and add the following to the require array:

"platform/media": "^8.0"

Add the following lines after the require array on your composer.json file:

"repositories": [
    {
        "type": "composer",
        "url": "https://packages.cartalyst.com"
    }
]

Note: Make sure that after the required changes your composer.json file is valid by running composer validate.

Install the dependencies

Run Composer to install or update the new requirement.

php composer install

or

php composer update

Now you are able to install the extension through Platform's admin.

Usage

In this section we'll show how you can manage your media.

Repository

IoC Binding

The media repository is bound to platform.media and can be resolved out of the IoC Container using that offset.

$media = app('platform.media');

Methods

The repository contains several methods that are used throughout the extension, most common methods are listed below.

For an exhaustive list of available methods, checkout the MediaRepositoryInterface

• find($id);

Returns an media object based on the given id.

• findByPath($path);

Returns a collection of all media.

• upload($file, array $input)

Uploads the given file and populates the data passed as input.

• create(array $data);

Creates and stores a new media object.

• update($id, array $data);

Updates an existing media object.

• delete($id);

Deletes a media object.

Manager

The media manager makes integrating media with your extension a breeze. It allows you to attach media to your entities. The following example is going to explain how to use the manager for an Employee.

Model setup

The model must use Platform\Media\Support\MediaTrait and implement Cartalyst\Support\Contracts\NamespacedEntityInterface

Example

<?php
namespace Platform\Employees\Models;

use Platform\Media\Support\MediaTrait;
use Illuminate\Database\Eloquent\Model;
use Cartalyst\Support\Traits\NamespacedEntityTrait;
use Cartalyst\Support\Contracts\NamespacedEntityInterface;

class Employee extends Model implements NamespacedEntityInterface
{
    use NamespacedEntityTrait, MediaTrait;

    protected static $entityNamespace = 'platform/employees';

    ...
}

Note The $entityNamespace of your model is used by the media when uploading images.

View setup

On the view, a simple blade call is needed that requires an instance of the model in question to be passed in as first argument, an optional second argument indicates whether the widget should allow attaching a single or multiple media objects, multiple is the default.

Third argument is optional and can be a view that would override the default widget view that ships with the extension.

Example

Allow only a single image to be attached to the model

@mediaUpload($employee, false)

Allow multiple images to be attached to the model

@mediaUpload($employee)

Use a custom view for the media widget

@mediaUpload($employee, true, 'yourvendor/yourextension::widgets.upload')

Use the media manager in a Platform Extension / Model Form

@extends('layouts/default')

{{-- Page content --}}
@section('page')

<section class="panel panel-default panel-tabs">

    {{-- Form --}}
    <form id="employees-form" action="{{ request()->fullUrl() }}" role="form" method="post">

    {{-- Form fields --}}
        ...

        <div class="row">

            @mediaUpload($employee)

        </div>

    </form>

</section>
@stop

Upload media

1. Click on Upload
2. Drop your files on the uploadable area
3. Start Upload

Note

The files are going to be attached to your entity.

Select media

You can attach media to your entity by using the Media Manager Selector.

1. Click Select
2. Select your files
3. Select to attach the selected media to your entityNamespace

Note

You can select/unselect files by clicking on the Selected Collapse or by clicking again on the selected media. Furthermore you can search your media library or narrow your library down by applying mime-type filters.

Sort media

The media manager is built with sorting in mind. Just drag the media by clicking and dragging the arrows icon.

Detach media

Detach a media by clicking on the trash Icon. The File is not going to be entirely deleted, only the relation to the entity. If you want to delete a media permanently you can use the Media Extension.

Image Manipulation

If you have the need to present images in different sizes or even to add simple watermarks, presets and macros will surely help you.

As an example, you can have product images in different sizes while maintaining the source image clean.

These presets will be triggered when a file is uploaded and each preset will run depending on the "filters" you apply to each preset like only run on certain mime types or even namespaces.

Macros

A macro is what will perform the image manipulation behind the scenes.

Create a macro

We'll create a very basic macro:

<?php

namespace App\Macros;

use Platform\Media\Macros\Fit;
use Cartalyst\Filesystem\File;
use Platform\Media\Models\Media;
use Illuminate\Container\Container;

class Crop extends Fit
{
    public function up(Media $media, File $file)
    {
        if (! $file->isImage()) {
            return;
        }

        $preset = $this->getPreset();

        $path = $this->getPath($file, $media);

        $this->intervention->make($file->getContents())
            ->crop($preset->width, $preset->height)->save($path)
        ;
    }
}

Note: In this example we're extending the default Fit macro, so the example is more cleaner and simple!

Note: Every macro needs to extend the Platform\Media\Macros\AbstractMacro or to implement the Platform\Media\Macros\MacroInterface interface if more customization is required.

Now that we have the macro created, we need to register it and to register we have two ways, through the config file or at runtime, either one is fine.

Config

Open the config/platform-media.php config file and add the preset to the macros array, here's an example:

'macros' => [

    'crop' => 'App\Macros\Crop',

],

Runtime

Somewhere on your application you can register the macro by running the following:

$manager = app('platform.media.manager');

$manager->setMacro('crop', 'App\Macros\Crop');

Presets

A preset is mostly used to define the width and height using one or multiple macros.

Create a preset

Presets are however very easy and extremely simple to create/define and can be done either through the config or at runtime.

Config

Open the config/platform-media.php config file and add the preset to the presets array, here's an example:

'presets' => [

    'mini' => [
        'width'  => 80,
        'macros' => [ 'fit' ],
        'mimes'  => [ 'image/jpeg' ],
    ],

],

Note: Please refer to the list of allowed keys below.

Runtime

Somewhere on your application you can register the preset by running the following:

$manager = app('platform.media.manager');

$manager->setPreset('mini', [
    'width'  => 80,
    'macros' => [ 'fit' ],
    'mimes'  => [ 'image/jpeg' ],
]);

Note: Please refer to the list of allowed keys below.

Allowed Keys on Presets by Default

Here's a list of allowed keys that can be used on each preset, but you're free to pass any key for your custom macros.

Parameter	Type	Default	Required	Description
width	integer	null	yes	The width of the image.
height	integer	null	no	The height of the image.
path	integer	null	no	The path where to store this image.
mimes	array	null	no	The valid mime types.
macros	array	null	no	The macros that will run with this preset.
constraints	array	null	no	The constraints to be applied on this preset.
namespaces	array	null	no	The namespaces that are only allowed for this preset to run.

Widgets

@mediaPath($id, $name, $attributes)

Examples

Retrieve original file path

@mediaPath(1)

Retrieve the thumb preset path

@mediaPath(1, 'thumb')

Retrieve a non existing preset (created on demand)

By passing the attributes below for a non existing preset, an image will be created based on them and its path returned.

@mediaPath(1, 'new_preset', ['width' => 100, 'height' => 100, 'macros' => [ 'fit' ]])

@mediaUpload($namespace, $multiUpload, $view)

Documented under the Manager section above.

Artisan Commands

php artisan images:generate

Generates images using the given criteria and presets.

Optional parameters

• --mime=:val only apply for the given mime.
• --media=:val only apply for the given media.
• --preset=:val only apply for the given preset.
• --namespace=:val only apply for the given namespace.

Examples

Generate media items for the 720p preset

php artisan images:generate --preset=720p

Generate media items for all items with a mime type of image/jpeg.

php artisan images:generate --mime=image/jpeg

php artisan images:clear

Clears images using the given criteria and presets.

• --mime=:val only apply for the given mime.
• --media=:val only apply for the given media.
• --preset=:val only apply for the given preset.
• --namespace=:val only apply for the given namespace.

Examples

Clear all thumb preset media items

php artisan images:clear --preset=thumb

Clear all media items for the foo/bar namespace

php artisan images:clear --namespace=foo/bar