VichUploaderSerializationBundle
:package: 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.2 and later
- Symfony 5.0 later
Installation
composer req fresh/vich-uploader-serialization-bundle='~3.0'
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.
Copyright (c) 2015-2020 Artem Henvald
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.
-
Create CODEOWNERS
By web-flow, 1 year ago
-
Update LICENSE
By web-flow, 1 year ago
-
Upgrade Symfony to 5.0 (#34)
By web-flow, 1 year ago
-
Add first workflow
By fre5h, 1 year ago
-
Update composer.json
By web-flow, 1 year ago
-
Merge pull request #32 from fre5h/update-travis
By web-flow, 1 year ago
-
Add php7.4 to travis CI
By web-flow, 1 year ago
-
Merge pull request #30 from fre5h/update-symfony
By web-flow, 1 year ago
-
Update .travis.yml
By web-flow, 1 year ago
-
Update dependencies (#28)
By web-flow, 1 year ago
-
Update JmsSerializerSubscriber.php
By web-flow, 1 year ago
-
Update README.md
By web-flow, 1 year ago
-
Merge pull request #27 from aless673/master
By web-flow, 1 year ago
-
[FIX] CI pr style
By , 1 year ago
-
[UPDATE] Prevent error when using custom type
By aless673, 1 year ago
-
Create FUNDING.yml
By web-flow, 1 year ago
-
Update .travis.yml
By web-flow, 1 year ago
-
Merge pull request #26 from Codevate/bugfix/host-appended-to-uri-with-host
By web-flow, 1 year ago
-
Don't prepend the host URL if the URI already validates as a URL
By lushc, 1 year ago
-
Merge pull request #24 from Bukashk0zzz/patch-1
By web-flow, 2 years ago
-
Allow JMS Serializer bundle 3.0
By Bukashk0zzz, 2 years ago
-
Update LICENSE
By web-flow, 2 years ago
-
Update .travis.yml
By web-flow, 2 years ago
-
Update README.md
By web-flow, 2 years ago
-
Merge pull request #22 from fre5h/feature-update-vendors
By web-flow, 2 years ago
-
Refactoring
By Artem Henvald, 2 years ago
-
Update vendors
By Artem Henvald, 2 years ago
-
Merge pull request #21 from lsv/symfony41
By web-flow, 2 years ago
-
added php codesniffer to composer requirements
By lsv, 2 years ago
-
cs fix
By lsv, 2 years ago