Developed with love by KnpLabs Hire us for your project!
0

LiipImagineSerializationBundle

by Bukashk0zzz

Provides integration between LiipImagineBundle and JMSSerializerBundle

Symfony LiipImagineSerialization Bundle

Build Status
Code Coverage
Scrutinizer Code Quality
Dependency Status
License
Latest Stable Version
Total Downloads

SensioLabsInsight
knpbundles.com

About

Provides integration between LiipImagineBundle and
JMSSerializerBundle.
Allows to generate full or relative URIs to entity fields mapped with @Bukashk0zzz and @JMS annotations during the serialization.
Also bundle supports VichUploaderBundle field type.

Installation Symfony Flex

composer config extra.symfony.allow-contrib true
composer require bukashk0zzz/liip-imagine-serialization-bundle

Installation without Symfony Flex

composer require bukashk0zzz/liip-imagine-serialization-bundle

Add the bundle to app/AppKernel.php

$bundles = array(
    // ... other bundles
    new Bukashk0zzz\LiipImagineSerializationBundle\Bukashk0zzzLiipImagineSerializationBundle(),
);

Configuration

Add this to your config.yml:

bukashk0zzz_liip_imagine_serialization:
    # Set true for generating url for vichUploader fields
    vichUploaderSerialize: false
    # Set true for generating url with host for vichUploader fields
    includeHost: false
    # Set true for adding original field value to object
    includeOriginal: false
    # Set true for adding host url to original value for vichUploader fields
    includeHostForOriginal: false
    # You can pass there your UrlNormalizer class that implements UrlNormalizerInterface
    originUrlNormalizer: null
    # You can pass there your UrlNormalizer class that implements UrlNormalizerInterface
    filteredUrlNormalizer: null

Usage

Add the next class to the use section of your entity class.

use Bukashk0zzz\LiipImagineSerializationBundle\Annotation as Bukashk0zzz;

Bundle provides two annotations which allow the serialization of url or @Vich\UploadableField fields in your entities.
At first you have to add @Bukashk0zzz\LiipImagineSerializableClass to the entity class which has image fields.
Then you have to add @Bukashk0zzz\LiipImagineSerializableField annotation to the field you want to serialize.

Annotation @Bukashk0zzz\LiipImagineSerializableClass does not have any option.

Annotation @Bukashk0zzz\LiipImagineSerializableField has one required option filter which value should link to the LiipImagine filter.

It can be set like this @Bukashk0zzz\LiipImagineSerializableField("photoFile") or @Bukashk0zzz\LiipImagineSerializableField(filter="photoFile").
filter can be array of filters in this case serialized field will be also array.
For example if you add annotation @Bukashk0zzz\LiipImagineSerializableField(filter={"big", "small"}) for field image then you get:

{
  "image": {
             "big": "/uploads/users/big/5659828fa80a7.jpg",
             "small": "/uploads/users/small/5659828fa80a7.jpg"
           }
}

Also there is another two options:
- vichUploaderField - If you use VichUploaderBundle for your uploads you must specify link to the field with @Vich\UploadableField annotation
- virtualField - By default serializer will override field value with link to filtered image. If you add virtualField option serializer will add to serialized object new field with name that you provided in this option and url to filtered image, original field in this case will be unattached. This option are required if you're using an array of filters.

Don't forget that to serialize image fields they also should be marked with @JMS annotations to be serialized.

The generated URI by default:

{
  "photo": "http://example.com/uploads/users/photos/5659828fa80a7.jpg",
  "cover": "http://example.com/uploads/users/covers/456428fa8g4a8.jpg"
}

The generated URI with includeHost set to false:

{
  "photo": "/uploads/users/photos/5659828fa80a7.jpg",
  "cover": "/uploads/users/covers/456428fa8g4a8.jpg"
}

If you need to change url before passing it to LiipImagine, for example you need to swap origin name, you can use originUrlNormalizer option in bundle config.
yaml
bukashk0zzz_liip_imagine_serialization:
originUrlNormalizer: AppBundle\Normalizer\UrlNormalizer

If you need to change url after LiipImagine processing, for example you need to swap origin domain, you can use filteredUrlNormalizer option in bundle config.
yaml
bukashk0zzz_liip_imagine_serialization:
filteredUrlNormalizer: AppBundle\Normalizer\UrlNormalizer

UrlNormalizer class must implement UrlNormalizerInterface

<?php

namespace AppBundle\Normalizer;

use Bukashk0zzz\LiipImagineSerializationBundle\Normalizer\UrlNormalizerInterface;

/**
 * Url normalizer
 */
class UrlNormalizer implements UrlNormalizerInterface
{    
    /**
    * {@inheritdoc} 
    */
    public function normalize($url){
        return str_replace('photo.jpg', 'my_photo.jpg', $url);
    }
}

Events

There are two events:
- bukashk0zzz_liip_imagine.event_pre_origin_normalize // Dispatch before origin url normalization
- bukashk0zzz_liip_imagine.event_pre_filtered_normalize // Dispatch before filtered url normalization

Example subscriber:
yaml
services:
app.liip_imagine_serialization_subscriber:
class: AppBundle\Subscribers\LiipImagineSerializationEventSubscriber
tags:
- { name: bukashk0zzz_liip_imagine_subscriber }

<?php

namespace AppBundle\Subscribers;

use Bukashk0zzz\LiipImagineSerializationBundle\Event\UrlNormalizerEvent;
use Symfony\Component\EventDispatcher\EventSubscriberInterface;

/**
 * LiipImagineSerializationEventSubscriber
 */
class LiipImagineSerializationEventSubscriber implements EventSubscriberInterface
{
    /**
     * @return array
     */
    public static function getSubscribedEvents()
    {
        return [
            UrlNormalizerEvent::ORIGIN => [
                ['normalizeOrigin', 10],
            ],
            UrlNormalizerEvent::FILTERED => [
                ['normalizeFiltered', 10],
            ],
        ];
    }

    /**
     * @param UrlNormalizerEvent $event
     */
    public function normalizeOrigin(UrlNormalizerEvent $event)
    {
        $event->setUrl(str_replace('photo', 'newPhoto', $event->getUrl()));
    }

    /**
     * @param UrlNormalizerEvent $event
     */
    public function normalizeFiltered(UrlNormalizerEvent $event)
    {
        $event->setUrl(str_replace('example.com', 'img.example.com', $event->getUrl()));
    }
}

Example

<?php

namespace AppBundle\Entity;

use Doctrine\ORM\Mapping as ORM;
use JMS\Serializer\Annotation as JMS;
use Vich\UploaderBundle\Mapping\Annotation as Vich;
use Bukashk0zzz\LiipImagineSerializationBundle\Annotation as Bukashk0zzz;
use Symfony\Component\HttpFoundation\File\File;

/**
 * User Entity
 *
 * @ORM\Table(name="users")
 * @ORM\Entity()
 *
 * @Vich\Uploadable
 * @Bukashk0zzz\LiipImagineSerializableClass
 */
class User
{    
    /**
     * @var string $coverUrl Cover url
     *
     * @ORM\Column(type="string", length=255)
     *
     * @JMS\Expose
     * @JMS\SerializedName("cover")
     *
     * @Bukashk0zzz\LiipImagineSerializableField("thumb_filter")
     */
    public $coverUrl; 

    /**
     * @var string $photoName Photo name
     *
     * @ORM\Column(type="string", length=255)
     *
     * @JMS\Expose
     * @JMS\SerializedName("photo")
     *
     * @Bukashk0zzz\LiipImagineSerializableField("thumb_filter", vichUploaderField="photoFile")
     */
    public $photoName;

    /**
     * @var File $photoFile Photo file
     *
     * @JMS\Exclude
     *
     * @Vich\UploadableField(mapping="user_photo_mapping", fileNameProperty="photoName")
     */
    public $photoFile;
}

Copyright / License

See LICENSE

The MIT License (MIT)

Copyright (c) 2015 Denis Golubovskiy

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.