img/image-bundle

A bundle providing fields for image upload with jquery upload and image cropping with jcrop for symfony2

Wednesday, December 20, 2017
by scotonnec
Repository
2 Watchers
3 Stars
12 Installations

PHP
0 Dependents
0 Suggesters
81 Forks
0 Open issues
25 Versions
0 % Grown

The README.md

Use 1.3 branch for Symfony 3 compatibility, thanks goes to @anthonyherve

Use 0.X releases for compatibility with bootstrap 2.x.

Compatibility with bootstrap 2.X is no more maintained

ComurImageBundle

Image upload / crop bundle for Symfony2, _(*1)

This bundle helps you easily create an image upload / crop field in your forms. You don't need to use any type of generator or there is no other requirements. It uses bootstrap to make it look well but you can use any other css to customize it., _(*2)

It uses beautiful Jquery File Upload to upload files (original UploadHandler has been modified to add namespace and a new config parameter to generate random filenames) and JCrop to let you crop uploaded images., _(*3)

New Since Version 0.2.3 !! you can also save original file in a separate field See saveOriginal parameter below., _(*4)

New Since Version 0.2.0 !! you can also create sortable & croppable gallery widgets without any specific configuration. It only needs an array typed property in your entity (and a text column in your database). See below for examples, screenshots and how to use it., _(*5)

Screen shots

Here are some screen shots since i didn't have time to put a demo yet:, _(*6)

alt tag , _(*7)

alt tag , _(*8)

Upload image screen

alt tag , _(*9)

Select image from library screen

alt tag , _(*10)

Crop image screen

alt tag , _(*11)

Change gallery image order screen

alt tag , _(*12)

Installation

Add this bundle to your project in composer.json:, _(*13)

{
    "require": {
        "comur/image-bundle": "1.0.*@dev",
    }
}

// app/AppKernel.php
public function registerBundles()
{
    return array(
        // ...
        new FOS\JsRoutingBundle\FOSJsRoutingBundle(),
        new JMS\TranslationBundle\JMSTranslationBundle(),
        new Comur\ImageBundle\ComurImageBundle(),
        // ...
    );
}

Add this route to your routing.yml:, _(*15)

# app/config/routing.yml
fos_js_routing:
    resource: "@FOSJsRoutingBundle/Resources/config/routing/routing.xml"

comur_image:
    resource: "@ComurImageBundle/Resources/config/routing.yml"
    prefix:   /

Add Modal template after body tag of your layout:, _(*16)

<body>
{% include "ComurImageBundle:Form:croppable_image_modal.html.twig"%}
…
</body>

Note: This template includes many script and styles including jquery and bootstrap. You can use following parameters to avoid jquery and/or bootstrap being included:, _(*17)

{% include "ComurImageBundle:Form:croppable_image_modal.html.twig" with {'include_jquery': false, 'include_bootstrap': false} %}

Do not forget to put FOSJSRoutingBundle script in your :

    <script src="{{ asset('bundles/fosjsrouting/js/router.js') }}"></script>
    <script src="{{ path('fos_js_routing_js', {"callback": "fos.Router.setData"}) }}"></script>

That's it !, _(*18)

Configuration

br/ All parameters are optional:, _(*19)

comur_image:
    config:
        cropped_image_dir: 'cropped'
        thumbs_dir: 'thumbnails'
        media_lib_thumb_size: 150
        web_dirname: 'web'
        translation_domain: 'ComurImageBundle'
        gallery_thumb_size: 150
        gallery_dir: 'gallery'

cropped_image_dir

It's used to determine relative directory name to put cropped images (see above)., _(*20)

Default value: 'cropped', _(*21)

thumbs_dir

It's used to determine relative directory name to put thumbnails (see above)., _(*22)

Default value: 'thumbnails', _(*23)

media_lib_thumb_size

It's used to determine thumbnails size in pixels (squares) used in media library., _(*24)

Default value: 150, _(*25)

upload_dir

Dirname of your public directory. It's used to check thumb existence in thumb twig helper., _(*26)

Default value: 'web', _(*27)

translation_domain

Domain name for translations. For instance two languages are provided (en & fr). To override the domain name, change this parameter to whatever you want., _(*28)

Default value: 'ComurImageBundle', _(*29)

gallery_thumb_size

That's the image size in pixels that you want to show in gallery widget. Gallery widget will automaticaly create square thums having this size and show them in the gallery widget., _(*30)

Default value: 150, _(*31)

gallery_dir

That's the gallery directory name. The widget will store all gallery images in a specific directory inside the root directory that you will give when you will add the widget to your forms., _(*32)

For eg. if you put 'uploads/images' as webDir when you add the widget, gallery images will be stored in 'uploads/images/[gallery_dir]'. This is added to make gallery use easier so you don't have to add new functions to your entities to get gallery dirs., _(*33)

Usage

There are two widgets provided with this bundle. They both have exacly same config parameters., _(*34)

Use widget in your forms (works with SonataAdmin too) to create a simple image field :, _(*35)

public function buildForm(FormBuilderInterface $builder, array $options)
{
    // get your entity related with your form type
    $myEntity = $builder->getForm()->getData();
    ...
    ->add('image', 'comur_image', array(
        'uploadConfig' => array(
            'uploadRoute' => 'comur_api_upload',        //optional
            'uploadUrl' => $myEntity->getUploadRootDir(),       // required - see explanation below (you can also put just a dir path)
            'webDir' => $myEntity->getUploadDir(),              // required - see explanation below (you can also put just a dir path)
            'fileExt' => '*.jpg;*.gif;*.png;*.jpeg',    //optional
            'libraryDir' => null,                       //optional
            'libraryRoute' => 'comur_api_image_library', //optional
            'showLibrary' => true,                      //optional
            'saveOriginal' => 'originalImage',          //optional
            'generateFilename' => true          //optional
        ),
        'cropConfig' => array(
            'minWidth' => 588,
            'minHeight' => 300,
            'aspectRatio' => true,              //optional
            'cropRoute' => 'comur_api_crop',    //optional
            'forceResize' => false,             //optional
            'thumbs' => array(                  //optional
                array(
                    'maxWidth' => 180,
                    'maxHeight' => 400,
                    'useAsFieldImage' => true  //optional
                )
            )
        )
    ))

You need to create a field (named image in this example but you can choose whatever you want):, _(*36)

// YourBundle\Entity\YourEntity.php

…

/**
 * @ORM\Column(type="string", length=255, nullable=true)
 */
protected $image;

…

And create your functions in your entity to have directory paths, for ex :, _(*37)

public function getUploadRootDir()
{
    // absolute path to your directory where images must be saved
    return __DIR__.'/../../../../../web/'.$this->getUploadDir();
}

public function getUploadDir()
{
    return 'uploads/myentity';
}

public function getAbsolutePath()
{
    return null === $this->image ? null : $this->getUploadRootDir().'/'.$this->image;
}

public function getWebPath()
{
    return null === $this->image ? null : '/'.$this->getUploadDir().'/'.$this->image;
}

That's all ! This will add an image preview with an edit button in your form and will let you upload / select from library and crop images without reloading the page., _(*38)

To save original image path, you have to create another field and name it same as saveOriginal parameter:, _(*39)

// YourBundle\Entity\YourEntity.php

…

/**
 * @ORM\Column(type="string", length=255, nullable=true)
 */
protected $originalImage;

…

I will put a demo soon…, _(*40)

Use widget in your forms (works with SonataAdmin too) to create a sortable list of images (so a gallery :)) stored in an array typed field :, _(*41)

->add('gallery', 'comur_gallery', array(
    //same parameters as comur_image
))

And create your array typed field for storing images in it. Doctrine (or other ORM) will serialize this field to store it as string in the DB., _(*42)

// YourBundle\Entity\YourEntity.php

…

/**
 * @ORM\Column(type="array", nullable=true)
 */
protected $gallery;

…

And create your functions in your entity to have directory paths, for ex :, _(*43)

public function getUploadRootDir()
{
    // absolute path to your directory where images must be saved
    return __DIR__.'/../../../../../web/'.$this->getUploadDir();
}

public function getUploadDir()
{
    return 'uploads/myentity';
}

public function getAbsolutePath()
{
    return null === $this->image ? null : $this->getUploadRootDir().'/'.$this->image;
}

public function getWebPath()
{
    return null === $this->image ? null : '/'.$this->getUploadDir().'/'.$this->image;
}

That's all ! This will create a widget like on the following image when you will use it in your forms. You can also reorder them since php serialized arrays are ordered:, _(*44)

Gallery images will be stored in uploadUrl / gallery_dir (default is gallery). Cropped images will be stored in uploadUrl / gallery_dir / cropped_dir (same as image widget) and thumbs in uploadUrl / gallery_dir / cropped_dir / thumb_dir with specified width. So if you pu, _(*45)

uploadConfig

uploadRoute (optional)

Route called to send uploaded file. It's recommended to not change this parameter except if you know exactly what you do., _(*46)

Default value: comur_api_upload, _(*47)

uploadUrl (required)

Absolute url to directory where put uploaded image. I recommend you to create a function in your entity and call it like it's showen in the example:, _(*48)

public function getUploadRootDir()
{
    // absolute path to your directory where images must be saved
    return __DIR__.'/../../../../../web/'.$this->getUploadDir();
}

public function getUploadDir()
{
    return 'uploads/myentity';
}

public function getAbsolutePath()
{
    return null === $this->image ? null : $this->getUploadRootDir().'/'.$this->image;
}

public function getWebPath()
{
    return null === $this->image ? null : '/'.$this->getUploadDir().'/'.$this->image;
}

webDir (required)

Url used to show your image in templates, must be relative url. If you created related functions as explained in uploadUrl section, then you can user getWebPath() function for webDir parameter., _(*49)

fileExt (optional)

Permitted image extensions., _(*50)

Default value: '.jpg;.gif;.png;.jpeg', _(*51)

libraryDir (optional)

Directory to look into for images to show in image library., _(*52)

Default value: uploadUrl, _(*53)

libraryRoute (optional)

Route called to get images to show in library. I recommend you to not change this parameter if you don't know exactly what it does., _(*54)

Default value: comur_api_image_library, _(*55)

showLibrary (optional)

Set this to false if you don't want the user see existing images in libraryDir., _(*56)

Default value: true, _(*57)

saveOriginal (optional)

Use this parameter if you want to save original file's path (for eg. to show big image in a lightbox). You have to put property name of your entity and the bundle will use it to save original file path in it., _(*58)

Attention: This parameter is disabled for gallery for instance. It will be implemented soon., _(*59)

Default value: false, _(*60)

generateFilename (optional)

This parameter is used to generate an uniq file name. Setted to false, it will keep the original filename., _(*61)

Default value: true, _(*62)

cropConfig

minWidth (optional)

Minimum with of desired image., _(*63)

Default value: 1, _(*64)

minHeight (optional)

Minimum height of desired image., _(*65)

Default value: 1, _(*66)

aspectRatio (optional)

True to aspect ratio of crop screen., _(*67)

Default value: true, _(*68)

cropRoute (optional)

Route to crop action. I recommend you to not change this parameter if you don't know exactly what it does., _(*69)

Default value: comur_api_crop, _(*70)

forceResize (optional)

If true, system will resize image to fit minWidth and minHeight., _(*71)

thumbs (optional)

Array of thums to create automaticly. System will resize images to fit maxWidth and maxHeight. It will put them in "uploadDir/cropped_images_dir/thumbs_dir/widthxheight-originalfilename.extension" so you can use included Thumb Twig extension to get them, ex:, _(*72)

{# your_themplate.html.twig #}
<img src="{{ entity.imagePath|thumb(45, 56) }}"

New in 0.2.2: You can use 'useAsFieldImage' option to use this thumb as image field's preview (in your form you will see this thumb instead of original cropped image). Usefull when you have big cropped images., _(*73)

TODO LIST

Create tests
Add more comments in the code
Think about removed image deletion (for now images are not deleted, you have to care about it by yourself…)
Update existing images list dynamicly after an image upload

The Versions

20/12 2017

1.3.x-dev

1.3.9999999.9999999-dev https://github.com/comur/ComurImageBundle

A bundle providing fields for image upload with jquery upload and image cropping with jcrop for symfony2

symfony-bundle image-bundle

A bundle providing fields for image upload with jquery upload and image cropping with jcrop for symfony2

img/image-bundle

The README.md

Use 1.3 branch for Symfony 3 compatibility, thanks goes to @anthonyherve

Use 0.X releases for compatibility with bootstrap 2.x.

Compatibility with bootstrap 2.X is no more maintained

ComurImageBundle

Screen shots

Simple Image widget

Gallery widget

Upload image screen

Select image from library screen

Crop image screen

Change gallery image order screen

Installation

Configuration

cropped_image_dir

thumbs_dir

media_lib_thumb_size

upload_dir

translation_domain

gallery_thumb_size

gallery_dir

Usage

Image widget

Gallery widget

uploadConfig

uploadRoute (optional)

uploadUrl (required)

webDir (required)

fileExt (optional)

libraryDir (optional)

libraryRoute (optional)

showLibrary (optional)

saveOriginal (optional)

generateFilename (optional)

cropConfig

minWidth (optional)

minHeight (optional)

aspectRatio (optional)

cropRoute (optional)

forceResize (optional)

thumbs (optional)

TODO LIST

The Versions

1.3.x-dev

The Requires

by Can OMUR

dev-master

The Requires

by Steve Cotonnec

1.0.x-dev

The Requires

by Can OMUR

1.1.0

The Requires

by Can OMUR

0.2.5

The Requires

by Can OMUR

1.0.2

The Requires

by Can OMUR

1.0.1

The Requires

by Can OMUR

0.2.4

The Requires

by Can OMUR

0.2.3

The Requires

by Can OMUR

0.2.2

The Requires

by Can OMUR

0.2.1

The Requires

by Can OMUR

0.2.0