π¦ 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.
- 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
composer req fresh/vich-uploader-serialization-bundle='~3.3'
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",
}
<?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;
}
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;
}
See CONTRIBUTING file.