README

📦 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.

Requirements 🧐

PHP 7.3, 7.4, 8.0, 8.1, 8.2
Symfony 5.0, 5.1, 5.2, 5.3, 5.4, 6.0, 6.1, 6.2

Installation 🌱

composer req fresh/vich-uploader-serialization-bundle='~3.3'

Usage 🧑‍🎓

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;

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

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

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

Don't make a mistake!

Additional example of a wrong usage 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 the 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 usage 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;

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

    /**
     * @var 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.

fresh / vich-uploader-serialization-bundle

Maintainers

Details