Fetching contributors…
Cannot retrieve contributors at this time
325 lines (216 sloc) 14.9 KB
# lyMediaManagerPlugin
The plugin offers a simple web interface to upload and manage images, documents and other media files directly from the backend of your symfony application. File upload and file browsing features can be easily integrated into the TinyMCE editor.
lyMediaManagerPlugin is inspired to sfAssetsLibraryPlugin for Propel, but some of its features have not been ported yet while others have been reimplemented in a different way.
This plugin is being developed to be included in Lyra CMS (also under development), but it's a standard plugin that can be used in any symfony project with no dependencies except sfThumbnailPlugin, needed to generate thumbnails.
This is currently a beta release, play with it, please report me any error and feel free to suggest improvements
###Automatic installation
lyMediaManagerPlugin can be quickly installed with the symfony command `plugin:install` (you must have PEAR installed on your system).
php symfony plugin:install --stability=beta lyMediaManagerPlugin
sfThumbnailPlugin is also needed to generate thumbnails of images.
php symfony plugin:install sfThumbnailPlugin
###Manual installation
Alternatively you can uncompress the .tgz package inside the `plugins` directory of your symfony project. If you have Subversion installed you can also install the plugin by checking out the source code from the repository: `cd` to the `plugins` directory of your symfony project and execute
svn checkout lyMediaManagerPlugin
If you choose the manual installation another two steps are needed. Plugins must be enabled in your project configuration class. Example:
public function setup()
Plugin assets must be published with the following symfony command
php symfony plugin:publish-assets
### Configuring i18n
If you want to enable i18N behavior, add this in your app.yml:
use_i18n: true
en: English
fr: Français
### Building models and tables
Then we need to generate plugin model classes and corresponding database tables.
php symfony doctrine:build --all
Keep in mind that this will erase all your data and rebuild everything from scratch. Before executing the statement above you may want to backup your database and restore it thereafter.
### Enabling plugin modules
lyMediaManagerPlugin contains two modules: lyMediaAsset, lyMediaFolder. Both must be enabled in `settings.yml` file (usually in your backend application). Example.
enabled_modules: [default, lyMediaAsset, lyMediaFolder]
### Initializing folder tree
lyMediaManagerPlugin provides a custom task to create the media library root directory inside the `web` directory of your project and the corresponding root node in the database. By default this directory will be called `media`: see configuration below if you prefer a different name.
php symfony media:create-root
This command should be executed by an user of the same group of the http server, if this is not possible chmod/chown the media library root directory so that is writable by the http server.
### Go to default page
Assuming that you are testing the plugin on localhost and you have enabled modules in your backend application, visit
to go to the module default page.
## Configuration
Some configuration parameters can be set inside the `app.yml` file of your application. Example.
# root directory name (used by task media:create-root)
media_root: media
# thumbnails settings
width: 32
height: 32
# forces thumbnail size to fixed width/height values
shave: true
width: 84
height: 84
shave: true
width: 194
height: 152
# name of folder where thumbnails will be created
thumbnail_folder: thumbs
# thumbnails will be created only for these mime-types
create_thumbnails_for: [image/jpeg,image/png,image/gif]
# only files with these extensions can be uploaded
allowed_extensions: [jpg,png,gif,txt]
# only files of these mime-types can be uploaded
mime_types: [image/jpeg,image/png,image/gif,text/plain]
# libray used for thumbnail creation: true ImageMagick, false (default) GD
use_ImageMagick: false
Note: `mini`, `small` and `medium` size thumbnails are used by the plugin itself and should not be removed. More thumbnails of desired sizes can be created for use in your application.
## Customizing views
Media library contents can be displayed and managed in different views: `list view` and `icons view`.
The `list view` is a sortable list created with the standard Doctrine admin generator templates and can be customized as any other module created with the task `doctrine:generate-admin`. Here are some quick instructions.
First create a folder `lyMediaAsset` and a subfolder `config` inside the `modules` folder of the application where you have enabled the plugin module. Then add a `generator.yml` file inside `config`
%app_name% (likely `backend`)
You can now safely customize the `list view` layout in your own `generator.yml` file without losing your changes when you upgrade the plugin. A complete list of all parameters and settings you can use in configuration files is available in symfony [official documentation]( "The symfony Reference Book"). Here are a couple of simple examples.
Always remember to issue a `symfony clear-cache` command to see the effect of any change made to a configuration file in the production environment.
created_at: {date_format: 'd MMM, yyyy'}
display: [_td_image,title,description,created_at]
title: Assets List
With this configuration the list layout displays the following columns: asset thumbnail, title, description, creation date. We have also set a custom page title and a date format for `creation date` column.
The `display` option contains an array of columns: a column can show not only field values (`title`, `description`, `created_at` in our example), but also partials (`_td_image` defined in `%project_dir%/plugins/lyMediaManagerPlugin/modules/lyMediaAsset/templates`), components (not used in our example) and any value returned by a **getter method** declared in model class. Let see an example.
With the default layout the first column of the list displays a thumbnail or icon. We may want to replace it with the asset path to save space: to do so it's sufficient to change our `generator.yml` in this way.
display: [path,title,description,created_at]
If you look at the definition of the class `lyMediaAsset` in plugin `schema.yml` you won't find a column named `path` : the list column will show the value returned by `lyMediaAsset::getPath()` method.
## Tasks
### Synchronize
A dedicated task is available to synchronize the media library database with the contents of a directory.
php symfony media:synchronize ./web/uploads/medias --application=backend
All folders and files in './web/uploads/medias' (a relative path, but you can specify an absolute path as well) that are not present in the media library will be added and a corresponding record created in the database. Thumbnails will be automatically generated for files of mime-types indicated in plugin configuration (see parameter `create_thumbnails_for`).
php symfony media:synchronize ./web/uploads/medias --removeOrphanAssets --application=backend
Same as above, but in addition every file that is present in the media library without a corresponding file in './web/uploads/medias' will be removed from the media library.
php symfony media:synchronize ./web/uploads/medias --removeOrphanFolders --application=backend
This time every folder in the media library without a corresponding folder in the directory will be removed. If something it's not clear, play with the task in a development environment to see the effect of these switches.
### Generate thumbnails
The `generate-thumbs` task will regenerate thumbnails for all assets in a given folder or the whole media library, provided thumbnails are supported by asset mime-type (see parameter `create_thumbnails_for` in plugin configuration).
This can be useful once we have added a new thumbnail type or changed the width or height of an existing type in plugin configuration.
php symfony media:generate-thumbs
Thumbnails are generated for **all** assets of the media library.
php symfony media:generate-thumbs media/photos
Thumbnails are generated for assets inside the `media/photos` folder **and** all subfolders.
php symfony media:generate-thumbs media/photos --no-recurse
Thumbnails are generated **only** for assets inside the `media/photos` folder.
Note that all folder paths passed to the task must be **relative**.
## Working with TinyMCE editor
lyMediaManagerPlugin can work together with the TinyMCE editor to make file browsing and file uploading features accessible directly from the editor toolbar. A few configuration steps are needed.
### Installing TinyMCE
Download the package from the [TinyMCE site]( it will be something like ``, where `x` is the minor version number. Uncompress it in a temporary folder on your hard disk: the resulting folder tree should be like the following
--tiny_mce <--Only this folder (with all subfolders and files inside) is needed.
Copy the `tiny_mce` folder (with all its subfolders and files) in '%project_dir%/web/js'. Verify that the following javascript files are present exactly in these paths:
### Configuring your form
To use TinyMCE with the file browser provided by lyMediaManagerPlugin you need to configure your forms following one of these **alternative** methods.
1) Dedicated widget
In the configure() method of your form replace `sfWidgetFormTextarea` with `sfWidgetFormLyMediaTinyMCE`. For example, assuming that the field you want to make editable with TinyMCE editor is named `content`
class MyForm extends BaseMyForm
public function configure()
$this->widgetSchema['content'] = new sfWidgetFormLyMediaTinyMCE(array(
'width' => 450,
'height' => 300
Refer to the source of `sfWidgetFormLyMediaTinyMCE` for other options supported by the widget. If you have installed TinyMCE exactly as explained above, you won't need to change options default values.
2) Manual inclusion of Javascript files
If you prefer to not use the widget you can include all the needed Javascript files in your form template through standard helpers.
<?php use_stylesheets_for_form($form) ?>
<?php use_javascripts_for_form($form) ?>
<?php use_javascript('tiny_mce/tiny_mce', 'last'); ?>
<?php use_javascript('/lyMediaManagerPlugin/js/lymedia_tiny', 'last'); ?>
<?php use_javascript('/lyMediaManagerPlugin/js/lymedia_tiny_cfg', 'last'); ?>
Then in the configure() method of your form set a class attribute for all textareas you want to make editable with TinyMCE.
class MyForm extends BaseMyForm
public function configure()
$this->widgetSchema['content']->setAttribute('class', 'rich');
Also refer to comments inside `lymedia_tiny_cfg.js` file because you may need to edit something depending by the name and location of your front controller.
Using `sfWidgetFormLyMediaTinyMCE` is easier, while manual inclusion of Javascript files is preferable if you want to keep TinyMCE configuration in a separate javascript file e do not want to mix markup and Javascript code in document body. Whichever method you choose, if you have configured everything properly you will see `lyMediaManagerPlugin` file browser when you select the `insert/edit image` button in TinyMCE toolbar and click the `browse` icon in the pop-up window.
## Working with FCKEditor
### Installation
Refer to official [FCKeditor documentation]( for instructions on how to install the editor. I will assume that installation folder is `%project_dir%/web/js/fckeditor`
### Form setup
Insert the following lines at the top of the form template where you want to use the editor
<?php use_javascript('/js/fckeditor/fckeditor', 'last'); ?>
<?php use_javascript('/lyMediaManagerPlugin/js/lymedia_fck_init', 'last'); ?>
If the form is part of a module generated by the admin generator, you can insert the lines above in `_form_header.php` template.
The script `lymedia_fck_init` will create an instance of FCKeditor for each textarea with a class attribute of `rich`. Assuming that the field you want to make editable with FCKeditor editor is named `content`, insert the following code in the configure() method of your form.
class MyForm extends BaseMyForm
public function configure()
$this->widgetSchema['content']->setAttribute('class', 'rich');
If the form is part of a module generated by the admin generator you can set this attribute in `generator.yml`
content: {attributes {class: rich}}
If everything is properly configured the dialog window opened by the insert image button on editor toolbar should now contain a `Browse Server` button: click it to have acess to lyMediaManagerPlugin `icons view` and select the image to insert in content.
## Credits
* This plugin is inspired to (and in part derived from) [sfAssetsLibraryPlugin](
* Optional i18n support has been contributed by Vincent Jousse ([vjousse](
* Icons come from [Tango Icon Library](
## Todo
* Complete this README :)
* i18n
* Improve user interface
* Support other plugins for thumbnail generation (sfImageTransformPlugin)
* Add more tests