Developed with love by KnpLabs Hire us for your project!
57

VichUploaderSerializationBundle

by fre5h

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.

Scrutinizer Quality Score
Build Status
CodeCov
License
Latest Stable Version
Total Downloads
StyleCI
Gitter

SensioLabsInsight
knpbundles.com

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.

The MIT License (MIT)

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, 4 months ago
  • Update LICENSE
    By web-flow, 4 months ago
  • Upgrade Symfony to 5.0 (#34)
    By web-flow, 4 months ago
  • Add first workflow
    By fre5h, 4 months ago
  • Update composer.json
    By web-flow, 4 months ago
  • Merge pull request #32 from fre5h/update-travis
    By web-flow, 5 months ago
  • Add php7.4 to travis CI
    By web-flow, 5 months ago
  • Merge pull request #30 from fre5h/update-symfony
    By web-flow, 6 months ago
  • Update .travis.yml
    By web-flow, 6 months ago
  • Update dependencies (#28)
    By web-flow, 6 months ago
  • Update JmsSerializerSubscriber.php
    By web-flow, 6 months ago
  • Update README.md
    By web-flow, 7 months ago
  • Merge pull request #27 from aless673/master
    By web-flow, 7 months ago
  • [FIX] CI pr style
    By , 8 months ago
  • [UPDATE] Prevent error when using custom type
    By aless673, 8 months ago
  • Create FUNDING.yml
    By web-flow, 11 months ago
  • Update .travis.yml
    By web-flow, 11 months 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, 1 year ago
  • Allow JMS Serializer bundle 3.0
    By Bukashk0zzz, 1 year ago
  • Update LICENSE
    By web-flow, 1 year ago
  • Update .travis.yml
    By web-flow, 1 year ago
  • Update README.md
    By web-flow, 1 year ago
  • Merge pull request #22 from fre5h/feature-update-vendors
    By web-flow, 1 year ago
  • Refactoring
    By Artem Henvald, 1 year ago
  • Update vendors
    By Artem Henvald, 1 year ago
  • Merge pull request #21 from lsv/symfony41
    By web-flow, 1 year ago
  • added php codesniffer to composer requirements
    By lsv, 1 year ago
  • cs fix
    By lsv, 1 year ago