Tuto : Symfony3 et DropzoneJS

DropzoneJS est une bibliothèque open-source permettant le drag'n'drop de fichiers dans une zone tout en affichant une miniature à l'envoi ainsi qu'une barre de progression. Voyons ensemble comment le câbléer à une architecture Symfony3.

^ Ce tuto a été réalisé avec une version 3.0.* de Symfony. Peut être que dans le futur, la récupération des lignes de code ci-dessous ne marchera plus ;) !

DropzoneJS

DropzoneJS est une biblithèque javascript, rapide à mettre en place, qui combine toutes les fonctionnalités d'un uploader. Très pratique et relativement clé en main, elle fait gagner beaucoup de temps ! Nous avons très rapidement un rendu idéal.

Parmi toute la panoplie des uploaders ou des file managers que nous pouvons trouver en ligne, DropzoneJS est une des bibliothèques que je trouve la plus pratique à utiliser... Voici à quoi s'attendre rapidement :

A savoir que toute la doc de DropzoneJS se trouve à cette adresse.

Téléchargements des sources de DropzoneJS

Nous allons faire ça à l'ancienne. Débutez par télécharger les sources :

• Sources javascript à cette adresse
• Sources CSS à cette adresse

Je vous invite à les placer dans votre dossier contenant vos ressources publiques, puis à charger vos scripts avec votre méthode préférée. Cependant, en gros, ça devrait jamais vraiment s'éloigner de...

 <script src="./path/to/dropzone.js"></script>

@ À noter que DropzoneJS peut aussi être installée via Bower, "dropzone": "4.3.*"

Câblage de DropzoneJS avec Symfony3

Tout d'abord, vous devez définir dans votre template (par exemple uploader.html.twig) votre zone qui accueillera vos glisser/déposer ou votre invitation à l'upload. Il s'agit dans le cas de DropzoneJS, par défaut, d'une div de classe dropzone.

<div class="dropzone my-dropzone" id="form_snippet_image" action="{{path('ajax_snippet_image_send')}}">
</div>

Ensuite, dans votre Javascript, définissez cette zone comment étant celle de votre dropzone.

//je récupère l'action où sera traité l'upload en PHP
var _actionToDropZone = $("#form_snippet_image").attr('action');

//je définis ma zone de drop grâce à l'ID de ma div citée plus haut.
Dropzone.autoDiscover = false;
var myDropzone = new Dropzone("#form_snippet_image", { url: _actionToDropZone });

A ce stade, votre div devrait s'être transformée en zone d'accueil de drop de fichier ! Vos fichiers glissés ne sont pas encore uploadés sur votre serveur mais nous pouvons déjà voir que DropzoneJS fait son travail. Par exemple, dans votre Javascript, insérez le code suivant :

myDropzone.on("addedfile", function(file) {
            alert('nouveau fichier reçu');
        });

La petite fonction précédente devrait vous faire afficher un message à chaque fois qu'un fichier est ajouté à votre zone de drop. J'ai ici utilisé l'événement addedfile, mais toute une liste bien pratique est disponible à cette adresse

Uploader les fichiers

Pour que vos images ou documents soient correctement déplacés où vous le souhaitez lorsqu'ils sont déposés dans notre Dropzone, je me suis inspiré de la documentation officielle de Symfony3 sur la gestion des uploads.

Rappelez-vous, dans notre code ci-dessus, j'ai indiqué :

action="{{path('ajax_snippet_image_send')}}"

C'est dans l'action associée à la route ajax_snippet_image_send que nous traiterons nos fichiers/images. A chaque ajout d'un document dans la zone de drop, DropzoneJS enverra ce fichier sur la route définie juste au dessus.

Création de l'entité des documents

Si vous n'avez pas d'entité liée à vos médias/documents, vous êtes invités à le faire. C'est très pratique pour manager tout ça par la suite (ré-utilisation de fichiers anciennements uploadé, par exemple !).

Nous créons donc une entité Document.php ( toujours fortement inspiré de la doc officielle )

namespace AppBundle\Entity;

use Doctrine\ORM\Mapping as ORM;
use Symfony\Component\Validator\Constraints as Assert;
use Symfony\Component\HttpFoundation\File\UploadedFile;

/**
 * @ORM\Entity
 * @ORM\Table(name="document")
 * @ORM\HasLifecycleCallbacks
 * @ORM\Entity(repositoryClass="AppBundle\Repository\DocumentRepository")
 */
class Document
{
    /**
     * @ORM\Id
     * @ORM\Column(type="integer")
     * @ORM\GeneratedValue(strategy="AUTO")
     */
    public $id;

    /**
     * @ORM\Column(type="string", length=255)
     * @Assert\NotBlank
     */
    public $name;

    /**
     * @Assert\File(maxSize="6000000")
     */
    private $file;

    /**
     * @ORM\Column(type="string", length=255, nullable=true)
     */
    public $path;

    /**
     * Sets file.
     *
     * @param UploadedFile $file
     */
    public function setFile(UploadedFile $file = null)
    {
         $this->file = $file;
        // check if we have an old image path
        if (isset($this->path)) {
            // store the old name to delete after the update
            $this->temp = $this->path;
            $this->path = null;
        } else {
            $this->path = 'initial';
        }
    }

    /**
     * Get file.
     *
     * @return UploadedFile
     */
    public function getFile()
    {
        return $this->file;
    }

    public function getAbsolutePath()
    {
        return null === $this->path
            ? null
            : $this->getUploadRootDir().'/'.$this->path;
    }

    public function getWebPath()
    {
        return null === $this->path
            ? null
            : $this->getUploadDir().'/'.$this->path;
    }

    protected function getUploadRootDir()
    {
        // the absolute directory path where uploaded
        // documents should be saved
        return __DIR__.'/../../../../web/'.$this->getUploadDir();
    }

    protected function getUploadDir()
    {
        // get rid of the __DIR__ so it doesn't screw up
        // when displaying uploaded doc/image in the view.
        return 'uploads/documents';
    }

    /**
     * @ORM\PrePersist()
     * @ORM\PreUpdate()
     */
    public function preUpload()
    {
        // la propriété « file » peut être vide si le champ n'est pas requis
        if (null === $this->file) {
            return;
        }

        if ($this->path != $this->file->getClientOriginalName()) {
            $this->path = $this->file->getClientOriginalName();
        }
    }

    /**
     * @ORM\PostPersist()
     * @ORM\PostUpdate()
     */
    public function upload()
    {
        // la propriété « file » peut être vide si le champ n'est pas requis
        if (null === $this->file) {
            return;
        }

        $file_name = $this->file->getClientOriginalName();

        // la méthode « move » prend comme arguments le répertoire cible et
        // le nom de fichier cible où le fichier doit être déplacé
        if (!file_exists($this->getUploadRootDir())) {
            mkdir($this->getUploadRootDir(), 0775, true);
        }
        $this->file->move(
            $this->getUploadRootDir(), $file_name
        );
        $this->file = null;
    }

    /**
     * Get id
     *
     * @return integer
     */
    public function getId()
    {
        return $this->id;
    }

    /**
     * Set name
     *
     * @param string $name
     *
     * @return Document
     */
    public function setName($name)
    {
        $this->name = $name;

        return $this;
    }

    /**
     * Get name
     *
     * @return string
     */
    public function getName()
    {
        return $this->name;
    }

    /**
     * Set path
     *
     * @param string $path
     *
     * @return Document
     */
    public function setPath($path)
    {
        $this->path = $path;

        return $this;
    }

    /**
     * Get path
     *
     * @return string
     */
    public function getPath()
    {
        return $this->path;
    }
}

Votre entité est créée, un petit php bin/console doctrine:schema:update --force pour synchroniser votre base de données, et on est bon pour la suite !

@ Le dossier dans lequel seront transférées mes images est défini dans la méthode getUploadDir de l'entité Document.php. C'est à dire : 'uploads/documents'. Vous n'êtes pas obligés de créer ce dossier au préalable, un test d'existence est présent dans la méthode upload() de l'entité Document.php.

Création d'un controller de gestion du document envoyé par DropzoneJS

Voici l'action qui, appelée par DropzoneJS, traitera l'envoi de document.

    /**
     *
     * @Method({"GET", "POST"})
     * @Route("/ajax/snippet/image/send", name="ajax_snippet_image_send")
     */
    public function ajaxSnippetImageSendAction(Request $request)
    {
        $em = $this->container->get("doctrine.orm.default_entity_manager");

        $document = new Document();
        $media = $request->files->get('file');

        $document->setFile($media);
        $document->setPath($media->getPathName());
        $document->setName($media->getClientOriginalName());
        $document->upload();
        $em->persist($document);
        $em->flush();

        //infos sur le document envoyé
        //var_dump($request->files->get('file'));die;
        return new JsonResponse(array('success' => true));
    }

et voilà !

Et voilà, votre uploader est terminé ! Il est sommaire, mais il fonctionne ! Vous êtes invités à sécuriser ou à améliorer toute cette interface grâce à toute la panoplie d'événements et de méthodes que possède DropzoneJS !

N'hésitez pas à me faire vos retours d'utilisations, d'expériences (ou même à me remonter des erreurs s'il y en a ;) !)

Enfin, vous êtes invités à nous interpeller sur notre Twitter @agence_wanadev ou en commentaire ci-dessous !