Add ImageableInterface, PdfInterface, FileableInterface and their tra…

…it to demonstrate how to properly configure VichUploader annotations/attributes

+ ParentFileTransformer to ease the init of parent relation

CHANGELOG.md

@@ -1,5 +1,16 @@
 CHANGELOG for 1.x
 ===================
+## v1.9.0 - (2024-07-11)
+### Added
+- `FileableInterface`, `ImageableInterface`, `PdfInterface` and their trait to demonstrate how to properly configure VichUploader annotations/attributes
+- `EmbeddedFile` to deal with multiple files on the same entity. To use in combination with a OneToOne relation and ORM\Embedded
+- `UuidInterface` and trait to for uuid management
+- `ParentFileTransformer` to used on form with entity implementing the `FileableInterface` to auto set the parent relation
+- `MimeTypesUtils` helper for constraints mimeTypes check
+
+### Fixed
+- `NameableTrait` handle setName with null type
+
 ## v1.8.0 - (2024-06-25)
 
 **Add Entity json History feature**

src/Entity/EmbeddedFile.php

@@ -0,0 +1,86 @@
+<?php
+
+namespace Smart\CoreBundle\Entity;
+
+use Doctrine\ORM\Mapping as ORM;
+use Smart\CoreBundle\Utils\MathUtils;
+
+/**
+ * @author Mathieu Ducrot <[email protected]>
+ *
+ * @ORM\Embeddable()
+ */
+#[ORM\Embeddable]
+class EmbeddedFile
+{
+    /**
+     * File name based on the originalName slug concatenated with a hash
+     * @ORM\Column(nullable=true)
+     */
+    #[ORM\Column(nullable: true)]
+    protected ?string $name = null;
+
+    /**
+     * Original name of the uploaded file
+     * @ORM\Column(nullable=true)
+     */
+    #[ORM\Column(nullable: true)]
+    protected ?string $originalName = null;
+
+    /**
+     * @ORM\Column(nullable=true)
+     */
+    #[ORM\Column(nullable: true)]
+    protected ?float $size = null;
+
+    /**
+     * @ORM\Column(nullable=true)
+     */
+    #[ORM\Column(nullable: true)]
+    private ?\DateTimeImmutable $updatedAt = null; // @phpstan-ignore-line
+
+    public function getName(): ?string
+    {
+        return $this->name;
+    }
+
+    public function setName(?string $name): void
+    {
+        $this->name = $name;
+    }
+
+    public function getOriginalName(): ?string
+    {
+        return $this->originalName;
+    }
+
+    public function setOriginalName(?string $originalName): void
+    {
+        $this->originalName = $originalName;
+    }
+
+    public function getSize(): ?float
+    {
+        return $this->size;
+    }
+
+    public function setSize(?float $size): void
+    {
+        $this->size = $size;
+    }
+
+    public function getFormattedSize(): ?string
+    {
+        $size = $this->getSize();
+        if ($size === null) {
+            return null;
+        }
+
+        return MathUtils::formatBytes($size);
+    }
+
+    public function setUpdatedAt(?\DateTimeImmutable $updatedAt): void
+    {
+        $this->updatedAt = $updatedAt;
+    }
+}

src/Entity/FileableInterface.php

@@ -0,0 +1,28 @@
+<?php
+
+namespace Smart\CoreBundle\Entity;
+
+use Symfony\Component\HttpFoundation\File\File;
+
+interface FileableInterface
+{
+    public function hasFile(): bool;
+
+    public function getFormattedFileSize(): ?string;
+
+    public function setFileFile(File|false|null $file = null): void;
+
+    public function getFileFile(): File|false|null;
+
+    public function getFileOriginalName(): ?string;
+
+    public function setFileOriginalName(?string $name): self;
+
+    public function getFileName(): ?string;
+
+    public function setFileName(?string $name): self;
+
+    public function getFileSize(): ?float;
+
+    public function setFileSize(?float $size): self;
+}

src/Entity/FileableTrait.php

@@ -0,0 +1,125 @@
+<?php
+
+namespace Smart\CoreBundle\Entity;
+
+use Doctrine\ORM\Mapping as ORM;
+use Smart\CoreBundle\Utils\MathUtils;
+use Symfony\Component\HttpFoundation\File\File;
+use Symfony\Component\HttpFoundation\File\UploadedFile;
+use Symfony\Component\Uid\Uuid;
+use Vich\UploaderBundle\Mapping\Annotation as Vich;
+
+trait FileableTrait
+{
+    /**
+     * NOTE: This is not a mapped field of entity metadata, just a simple property to use in form type.
+     * If the project use annotation then the entity using this trait must add the following :
+     *  @Vich\UploadableField(mapping="%mapping_name%", fileNameProperty="fileName", size="fileSize", originalName="fileOriginalName")
+     *  protected File|false|null $fileFile = null;
+     */
+    #[Vich\UploadableField(mapping: self::FILE_MAPPING, fileNameProperty: "fileName", size:"fileSize", originalName: "fileOriginalName")]
+    protected File|false|null $fileFile = null;
+
+    /**
+     * Original name of the uploaded file
+     * @ORM\Column(nullable=true)
+     */
+    #[ORM\Column(nullable: true)]
+    protected ?string $fileOriginalName = null;
+
+    /**
+     * File name based on the fileOriginalName slug concatenated with a hash
+     * @ORM\Column(nullable=true)
+     */
+    #[ORM\Column(nullable: true)]
+    protected ?string $fileName = null;
+
+    /**
+     * @ORM\Column(nullable=true)
+     */
+    #[ORM\Column(nullable: true)]
+    protected ?float $fileSize = null;
+
+    /**
+     * @ORM\Column(nullable=true)
+     */
+    #[ORM\Column(nullable: true)]
+    protected ?\DateTimeImmutable $fileUpdatedAt = null;
+
+    public function hasFile(): bool
+    {
+        return $this->fileName !== null;
+    }
+
+    public function getFormattedFileSize(): ?string
+    {
+        $size = $this->getFileSize();
+        if ($size === null) {
+            return null;
+        }
+
+        return MathUtils::formatBytes($size);
+    }
+
+    /**
+     * If manually uploading a file (i.e. not using Symfony Form) ensure an instance
+     * of 'UploadedFile' is injected into this setter to trigger the update. If this
+     * bundle's configuration parameter 'inject_on_load' is set to 'true' this setter
+     * must be able to accept an instance of 'File' as the bundle will inject one here
+     * during Doctrine hydration.
+     */
+    public function setFileFile(File|false|null $file = null): void
+    {
+        $this->fileFile = $file;
+
+        if ($file instanceof UploadedFile) {
+            // It is required that at least one field changes if you are using doctrine
+            // otherwise the event listeners won't be called and the file is lost
+            $this->fileUpdatedAt = new \DateTimeImmutable();
+            if ($this instanceof UuidInterface && $this->getUuid() === null) {
+                $this->setUuid(Uuid::v7());
+            }
+        }
+    }
+
+    public function getFileFile(): File|false|null
+    {
+        return $this->fileFile;
+    }
+
+    public function getFileOriginalName(): ?string
+    {
+        return $this->fileOriginalName;
+    }
+
+    public function setFileOriginalName(?string $name): self
+    {
+        $this->fileOriginalName = $name;
+
+        return $this;
+    }
+
+    public function getFileName(): ?string
+    {
+        return $this->fileName;
+    }
+
+    public function setFileName(?string $name): self
+    {
+        $this->fileName = $name;
+
+        return $this;
+    }
+
+    public function getFileSize(): ?float
+    {
+        return $this->fileSize;
+    }
+
+    public function setFileSize(?float $size): self
+    {
+        $this->fileSize = $size;
+
+        return $this;
+    }
+}

src/Entity/ImageableInterface.php

@@ -0,0 +1,36 @@
+<?php
+
+namespace Smart\CoreBundle\Entity;
+
+use Symfony\Component\HttpFoundation\File\File;
+
+/**
+ * @author Mathieu Ducrot <[email protected]>
+ */
+interface ImageableInterface
+{
+    public const IMAGE_MAPPING = 'image';
+    public const IMAGE_MAX_SIZE = '8M';
+    public const IMAGE_MAX_WIDTH = '1000';
+    public const IMAGE_MAX_HEIGHT = '1000';
+
+    public function hasImage(): bool;
+
+    public function getFormattedImageSize(): ?string;
+
+    public function setImageFile(File|false|null $file = null): void;
+
+    public function getImageFile(): File|false|null;
+
+    public function getImageOriginalName(): ?string;
+
+    public function setImageOriginalName(?string $name): self;
+
+    public function getImageName(): ?string;
+
+    public function setImageName(?string $name): self;
+
+    public function getImageSize(): ?float;
+
+    public function setImageSize(?float $size): self;
+}