ElFinder integration in Symfony2
elFinder is an open-source file manager for web, written in JavaScript using jQuery UI. Creation is inspired by simplicity and convenience of Finder program used in Mac OS X operating system.
Recommended bundles to use with:
- Installation
- Basic configuration
- Configuring symfony service as a volumeDriver
- ElFinder form type
- Using ElFinder with CKEditorBundle
- Using ElFinder with TinyMCE
- Custom configuration provider
To install this bundle, you'll need both the lib ElFinderPHP and this bundle.
This instruction explain how to setup bundle on Symfony 2.1 and newer
You have a choice to install bundle of version 1.x (1.x branch, documentation) or 2.x branch Add FMElfinderBundle in your composer.json:
{
"require": {
"helios-ag/fm-elfinder-bundle": "2.x"
}
}Now tell composer to download the bundle by running the command:
$ php composer.phar update helios-ag/fm-elfinder-bundleEnable the bundle in the kernel:
<?php
// app/AppKernel.php
public function registerBundles()
{
$bundles = array(
// ...
new FM\ElfinderBundle\FMElfinderBundle(),
);
}# app/config/routing.yml
elfinder:
resource: "@FMElfinderBundle/Resources/config/routing.yml"Secure ElFinder with access_control:
# app/config/security.yml
security:
//....
access_control:
- { path: ^/efconnect, role: ROLE_USER }
- { path: ^/elfinder, role: ROLE_USER }
role ROLE_USER is provided as example.
Under assetic section of your config.yml, add FMElfinderBundle to bundles section, also you can enable uglify js/css compressor (also you need to enable option "compression: true" under bundle configuration).
Also set "use_controller: false".
assetic:
debug: %kernel.debug%
use_controller: false
bundles: [FMElfinderBundle]
java: /usr/bin/java
filters:
cssrewrite: ~
uglifyjs2:
# the path to the uglifyjs executable
bin: /usr/bin/uglifyjs
uglifycss:
bin: /usr/bin/uglifycssInstall and dump assets using symfony built-in commands:
app/console assets:install web
app/console assetic:dump --env=prodfm_elfinder:
instances:
default:
locale: %locale% # defaults to current request locale
editor: ckeditor # other choices are tinymce or simple, and form
fullscreen: true # defaults true, applies to simple and ckeditor editors
include_assets: true # disable if you want to handle loading of the javascript and css assets yourself
compression: false # enable if you configured the uglifycss and uglifyjs2 assetic filters and want compression
connector:
debug: false # defaults to false
roots: # at least one root must be defined
uploads:
showhidden: false # defaults to false
driver: LocalFileSystem
path: uploads
upload_allow: ['image/png', 'image/jpg', 'image/jpeg']
upload_deny: ['all']
upload_max_size: 2M
- default - instance of elfinder, can be used to define multiple configurations of ElFinder, allows simultaneous configuration for different types of WYSIWYG editors in your project
- path - define root directory for the files inside web/ directory, default is "uploads". Make sure to set proper write/read permissions to this directory.
- url - url to be prefixed to image path, for displaying. Can be either absolute or relative. If relative, it will be prefixed with the applications base-url. If left blank, url will be the base-url, appened with the value of the 'path' parameter
- driver - can be LocalFileSystem, FTP or MySQL2, currently supported only LocalFileSystem, default is LocalFileSystem
- locale - locale determines, which language, ElFinder will use, to translate user interface, default is current request locale
- editor - determines what template to render, to be compatible with WYSIWYG web editor, currently supported options are: "ckeditor", "tinymce" and "simple". How to configure CKEDitor and TinyMCE to work with this bundle, will be explained further in this document. "simple" can be used as standalone filebrowser for managing and uploading files.
- showhidden - hides directories starting with . (dot)
- connector - root node for defining options for elfinder root directiories and debug option
- roots - define
volumeDriver can be declared as Symfony service The service should however be an instance of the FM\ElFinderPHP\Driver\ElFinderVolumeDriver class. This check is to ensure the service is a valid ElFinder VolumeDriver.
To configure a root with a service-driver you can simply use the service id as the drive key:
fm_elfinder:
connector:
roots:
uploads:
driver: elfinder.driver.filesystem
path: uploads
This means that if you add the service definition:
<service id="elfinder.driver.filesystem" class="FM\ElFinderPHP\Driver\ElFinderVolumeLocalFileSystem" />Since version 2.1 of the bundle, bundle come with custom form type, that is simple , that provide elfinder callback (opens Elfinder window), configuration for this form type is simple First, define instance with editor setted to "form":
fm_elfinder:
instances:
form:
locale: %locale% # defaults to current request locale
editor: form # other choices are tinymce or simple, and form
showhidden: false # defaults to false
fullscreen: true # defaults true, applies to simple and ckeditor editors
include_assets: true # disable if you want to handle loading of the javascript and css assets yourself
compression: false # enable if you configured the uglifycss and uglifyjs2 assetic filters and want compression
connector:
debug: false # defaults to false
roots: # at least one root must be defined
uploads:
driver: LocalFileSystem
path: uploads
upload_allow: ['image/png', 'image/jpg', 'image/jpeg']
upload_deny: ['all']
upload_max_size: 2M
On second step, add to your form builder (or form class), elfinder type, and pass instance and enable parameters:
$form = $this->createFormBuilder()
->add('elfinder','elfinder', array('instance'=>'form', 'enable'=>true))
->getForm();Render form with twig as usual:
<form action="" method="post" {{ form_enctype(form) }}>
{{ form_widget(form) }}
<input type="submit" />
</form>Using ElFinder with CKEditorBundle
Mostly filebrowsers used with WYSIWYG editors to upload images and other files. The example above will show how to configure CKEditorBundle by Trsteel to work with ElFinder through FMElFinderBundle Also take a view to @egeloen IvoryCKEditorBundle, which includes configuration guide for both bundles
Install both bundles according README files
trsteel_ckeditor:
...
filebrowser_image_browse_url:
route: elfinder
route_parameters:
instance: ckeditoror if you prefer Ivory CKEditor Bundle
ivory_ck_editor:
default_config: default
configs:
default:
filebrowserBrowseRoute: elfinder
filebrowserBrowseRouteParameters:
instance: ckeditor
Note that instance name should be the same as configured in elfinder bundle
<?php
$form = $this->createFormBuilder()
->add('content', 'ckeditor', array(
'filebrowser_image_browse_url' => array(
'route' => 'elfinder',
'route_parameters' => array('instance' => 'ckeditor'),
),
))
->getForm()
;ElFinder will be available under Insert Image dialog
You can integrate TinyMCE byself or use Bundles that already add TinyMCE functionality to your Symfony project. Below instruction how to integrate FMElfinderBundle with TinyMCEBundle
Using ElfinderBundle with TinyMCEBundle
Instruction for bundle version 0.2.1 (TinyMCE 3.x), instruction for TinyMCE 4.x, you can find at the end of this document. Download both bundles, configure, dump and install assets as written in installation steps
Update the editor property in your app/config.yml Set TinyMce popup path:
fm_elfinder:
editor: tinymce
tinymce_popup_path: "asset[bundles/stfalcontinymce/vendor/tiny_mce/tiny_mce_popup.js]"Under tinymce configuration node, theme configuration, add: file_browser_callback : 'elFinderBrowser'
stfalcon_tinymce:
theme:
simple:
file_browser_callback : 'elFinderBrowser'after ( {{ tinymce_init() }} ) function call place ElfinderBundle's function: {{ elfinder_tinymce_init('instance_name', {'width':'900', 'height': '450', 'title':'ElFinder 2.0'}) }} as shown below
{{ tinymce_init() }}
{{ elfinder_tinymce_init('instance_name') }}instance_name is instance of elfinder's configuration
Update the editor property in your app/config.yml
fm_elfinder:
editor: tinymce4Under tinymce configuration node, theme configuration, add: file_browser_callback : elFinderBrowser
stfalcon_tinymce:
theme:
simple:
file_browser_callback : elFinderBrowserbefore ( {{ tinymce_init() }} ) function call (order is important) place ElfinderBundle's function: {{ elfinder_tinymce_init4('instance_name', {'width':'900', 'height': '450', 'title':'ElFinder 2.0'} ) }} as shown below
{{ elfinder_tinymce_init4('instance_name') }}
{{ tinymce_init() }}instance_name is instance of elfinder's configuration
That's all, Elfinder is configured to work with TinyMCE editor.
#Custom configuration provider
ElFinder bundle allows to override his configuration provider service:
fm_elfinder:
configuration_provider: elfinder.configuratorwhere 'elfinder.configurator' is default ElFinder's bundle service to read configuration from DIC
To override service, simply define your own service:
services:
my_elfinder_configurator:
class: Acme\DemoBundle\MyElfinderConfigurator
arguments: ["%my_arguments%"]Configuration class must implement interface ElFinderConfigurationProviderInterface
method getConfiguration($instance) should return array of parameters compatible with ElFinder bundle configuration
Manual integration guide can be found here
##Todo
More tests, gridfs support, complex user intergration(?)
##Changelog
- New Elfinder form type, provides basic field with Elfinder callback
- Multiple instances of elfinder configuration (allows multiple editors in one project, with different elfinder configurations)
- Made compressing assets optional. When compressing is active, it now uses uglify.js instead of YUI compressor.