VichUploaderSerializationBundle

Provides integration between VichUploaderBundle and JMSSerializerBundle. Allows to generate full or relative URIs to entity fields mapped with @Vich and @JMS annotations during the serialization.

Installation

php composer.phar require fresh/vich-uploader-serialization-bundle='~1.0'

Register the bundle

To start using the bundle, register it in app/AppKernel.php:

public function registerBundles()
{
    $bundles = [
        // Other bundles...
        new Fresh\VichUploaderSerializationBundle\FreshVichUploaderSerializationBundle(),
    ];
}

Using

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

use Fresh\VichUploaderSerializationBundle\Annotation as Fresh;

Bundle provides two annotations which allow the serialization of @Vich\UploadableField fields in your entities. At first you have to add @Fresh\VichSerializableClass to the entity class which has uploadable fields. Then you have to add @Fresh\VichSerializableField annotation to the uploadable field you want to serialize.

Annotation @Fresh\VichSerializableClass does not have any option.
Annotation @Fresh\VichSerializableField has one required option value (or field) which value should link to the field with @Vich\UploadableField annotation. It can be set like this @Fresh\VichSerializableField("photoFile") or @Fresh\VichSerializableField(field="photoFile"). Also there is another option includeHost, it is not required and by default is set to true. But if you need, you can exclude the host from the generated URI, just use the next variant of the annotation @Fresh\VichSerializableField("photoFile", includeHost=false).

And also don't forget that to serialize Vich uploadable 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",
}

Example of entity with serialized uploadable fields

<?php

namespace AppBundle\Entity;

use Doctrine\ORM\Mapping as ORM;
use Fresh\VichUploaderSerializationBundle\Annotation as Fresh;
use JMS\Serializer\Annotation as JMS;
use Vich\UploaderBundle\Mapping\Annotation as Vich;

/**
 * User Entity
 *
 * @ORM\Table(name="users")
 * @ORM\Entity()
 *
 * @Vich\Uploadable
 * @Fresh\VichSerializableClass
 */
class User
{
    /**
     * @var string $photoName Photo name
     *
     * @ORM\Column(type="string", length=255)
     *
     * @JMS\Expose
     * @JMS\SerializedName("photo")
     *
     * @Fresh\VichSerializableField("photoFile")
     */
    private $photoName;

    /**
     * @var File $photoFile Photo file
     *
     * @JMS\Exclude
     *
     * @Vich\UploadableField(mapping="user_photo_mapping", fileNameProperty="photoName")
     */
    private $photoFile;
    
    /**
     * @var string $coverName Cover name
     *
     * @ORM\Column(type="string", length=255)
     *
     * @JMS\Expose
     * @JMS\SerializedName("cover")
     *
     * @Fresh\VichSerializableField("coverFile", includeHost=false)
     */
    private $coverName;

    /**
     * @var File $coverFile Cover file
     *
     * @JMS\Exclude
     *
     * @Vich\UploadableField(mapping="user_cover_mapping", fileNameProperty="coverName")
     */
    private $coverFile;    
}

Don't make a mistake!

Additional example of a wrong use of provided annotations to attract your attention. Use @Fresh\VichSerializableField only with the field which is mapped with @ORM\Column, because this field is mapped to a database and keeps the name of stored file. Don't use the @Fresh\VichSerializableField with a field which also mapped with @Vich\UploadableField, this is a wrong use case and will throw an exception!

So the next example is the incorrect use of provided annotations! Don't do so!

<?php

namespace AppBundle\Entity;

use Doctrine\ORM\Mapping as ORM;
use Fresh\VichUploaderSerializationBundle\Annotation as Fresh;
use JMS\Serializer\Annotation as JMS;
use Vich\UploaderBundle\Mapping\Annotation as Vich;

/**
 * User Entity
 *
 * @ORM\Table(name="users")
 * @ORM\Entity()
 *
 * @Vich\Uploadable
 * @Fresh\VichSerializableClass
 */
class User
{
    /**
     * @var string $photoName Photo name
     *
     * @ORM\Column(type="string", length=255)
     */
    private $photoName;

    /**
     * @var File $photoFile Photo file
     *
     * !!! Next three annotations should be moved to the `photoName` property
     * @JMS\Expose
     * @JMS\SerializedName("photo")
     * @Fresh\VichSerializableField("photoFile")
     *
     * !!! This annotation should be left here
     * @Vich\UploadableField(mapping="user_photo_mapping", fileNameProperty="photoName")
     */
    private $photoFile;  
}

Contributing

See CONTRIBUTING file.

anboo / VichUploaderSerializationBundle