fresh / vich-uploader-serialization-bundle
Provides integration between VichUploaderBundle and JMSSerializerBundle.
Fund package maintenance!
fre5h
Installs: 185 446
Dependents: 0
Suggesters: 0
Security: 0
Stars: 46
Watchers: 3
Forks: 11
Open Issues: 5
Type:symfony-bundle
Requires
- php: >=7.3.0
- doctrine/cache: ^1.11
- doctrine/common: ^2.11|^3.0
- doctrine/persistence: ^1.3|^2.0
- jms/serializer-bundle: ^3.7|v4.0
- monolog/monolog: ^2.0
- symfony/config: ^5.0|^6.0
- symfony/dependency-injection: ^5.0|^6.0
- symfony/property-access: ^5.0|^6.0
- symfony/routing: ^5.0|^6.0
- vich/uploader-bundle: ^1.16
Requires (Dev)
- escapestudios/symfony2-coding-standard: ^3.12
- phpstan/phpstan: ^1.8
- phpstan/phpstan-doctrine: ^1.3
- phpstan/phpstan-phpunit: ^1.1
- phpunit/phpunit: ^9.5
- symfony/yaml: ^5.0|^6.0
This package is auto-updated.
Last update: 2024-11-07 15:34:25 UTC
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.