Preface
Introduction
A Platform 5 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": "4.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 runningcomposer 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
- Click on Upload
- Drop your files on the uploadable area
- 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.
- Click Select
- Select your files
- 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 thePlatform\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