README

提供VichUploaderBundle 和 JMSSerializerBundle 之间的集成。允许在序列化期间生成指向用 @Vich 和 @JMS 注解映射的实体字段的完整或相对URI。

要求

• PHP 7.1 及以上
• Symfony 3.4, 4.3 及以上

安装

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

使用方法

将以下类添加到您的实体类的 use 部分。

use Fresh\VichUploaderSerializationBundle\Annotation as Fresh;

该Bundle提供了两个注解，允许在实体中序列化 @Vich\UploadableField 字段。首先，您需要将 @Fresh\VichSerializableClass 添加到具有上传字段的实体类中。然后，您需要将 @Fresh\VichSerializableField 注解添加到您想要序列化的上传字段中。

注解 @Fresh\VichSerializableClass 没有任何选项。
注解 @Fresh\VichSerializableField 有一个必需选项 value（或 field），其值应链接到带有 @Vich\UploadableField 注解的字段。它可以设置为如下 @Fresh\VichSerializableField("photoFile") 或 @Fresh\VichSerializableField(field="photoFile")。还有一个可选的选项 includeHost，它不是必需的，默认设置为 true。但如果需要，您可以排除主机以从生成的URI中，只需使用注解的以下变体 @Fresh\VichSerializableField("photoFile", includeHost=false)。

并且，别忘了要序列化Vich上传字段，它们也应使用 @JMS 注解进行标记以进行序列化。

默认生成的URI

{
  "photo": "http://example.com/uploads/users/photos/5659828fa80a7.jpg",
  "cover": "http://example.com/uploads/users/covers/456428fa8g4a8.jpg",
}

将 includeHost 设置为 false 的生成的URI

{
  "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;    
}

不要犯错！

以下是一个使用提供的注解的 错误使用 的额外示例，以吸引您的注意。仅使用 @Fresh\VichSerializableField 与带有 @ORM\Column 映射的字段，因为此字段映射到数据库并保留存储文件的名称。不要使用 @Fresh\VichSerializableField 与也带有 @Vich\UploadableField 映射的字段，这是一个错误用例，将会抛出异常！

因此，以下示例是提供的注解的 错误使用！不要这样做！

<?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 文件。