Mise à jour des docblocks.

Model/FileManagerInterface.php

 <?php
-
-/*
+/**
  * Copyright (C) 2015 IRSTEA
  * All rights reserved.
+ *
+ * @package irstea/file-upload-bundle
+ * @author Guillaume Perréal <guillaume.perreal@irstea.fr>
  */
 
 namespace Irstea\FileUploadBundle\Model;
 
 /**
- * Description of FileManager
+ * Gestionnaire de fichier uploadé.
+ *
+ * Cette interface est le point d'entrée obligatoire pour toute manipulation de fichiers uploadés.
  */
 interface FileManagerInterface
-{
-    /**
+{les
+    /** Retrouve un fichier uploadé par son identifiant.
+     *
+     * @param string $id Identifiant du fichier.
      *
-     * @param string $id
-     * @return UploadedFileInterface
+     * @return UploadedFileInterfaceǹull Le fichier retrouvé ou null si aucun fichier ne correspond.
+     *
+     * @api
      */
     public function get($id);
 
-    /**
-     * @param string $name
-     * @param int $size
-     * @param string $mimeType
-     * @param int $lastModified
-     * @return UploadedFileInterface
+    /** Crée un nouveau fichier uploadé, vide.
+     *
+     * Le fichier est créé à l'état UploadedFileInterface::ETAT_EN_COURS.
+     *
+     * @param string $name Nom original du fichier.
+     * @param int $size Taille prévisionnelle, en octets.
+     * @param string $mimeType Mime TYPE provisoire.
+     * @param int $lastModified Timestamp de la date de dernière modification.
+     *
+     * @return UploadedFileInterface Le fichier créé.
+     *
+     * @api
      */
     public function create($name, $size, $mimeType, $lastModified = null, $createdBy = null, $createdFrom = null);
 
-    /**
-     * @param UploadedFileInterface $file
+    /** Supprime un fichier uploadé.
+     *
+     * *Attention :* le fichier est supprimé du disque !
+     *
+     * @param UploadedFileInterface $file Fichier à supprimer.
+     *
+     * @api
      */
     public function delete(UploadedFileInterface $file);
 
-    /**
-     * @param UploadedFileInterface $file
+    /** Indique que l'upload d'un fichier est terminé.
+     *
+     * Cela passe le fichier à l'état UploadedFileInterface::ORPHELIN et provoque la mise-à-jour de la taille, du
+     * type MIME et de la somme de contrôle.
+     *
+     * @param UploadedFileInterface $file Fichier terminé.
+     *
+     * @internal
      */
     public function completed(UploadedFileInterface $file);
 
-
-    /** Retourne un tableau de fichiers à nettoyer.
+    /** Retourne une liste de fichiers invalides à supprimer.
+     *
+     * Ce sont des fichiers partiels ou orphelin qui n'ont pas été modifiés depuis plus d'une heure.
      *
      * @return UploadedFileInterface[]
+     *
+     * @internal
      */
     public function findGarbage();
 
-    /** Retourne des fichiers à valider.
+    /** Retourne la liste des fichiers à valider.
      *
      * @return UploadedFileInterface[]
+     *
+     * @internal
      */
     public function findFilesToValidate();
 }

Model/UploadedFileInterface.php

@@ -3,29 +3,71 @@
 /*
  * Copyright (C) 2015 IRSTEA
  * All rights reserved.
+ *
+ * @package irstea/file-upload-bundle
+ * @author Guillaume Perréal <guillaume.perreal@irstea.fr>*
  */
 
 namespace Irstea\FileUploadBundle\Model;
 
 use DateTime;
 
-/**
+/** Un fichier uploadé.
  *
- * @author Guillaume Perréal <guillaume.perreal@irstea.fr>
  */
 interface UploadedFileInterface
 {
+    /** Fichier en cours d'upload.
+     *
+     * @var string
+     */
     const ETAT_EN_COURS = 'en-cours';
+
+    /** Fichier orphelin.
+     *
+     * Fichier qui n'a pas encore été associé à un objet métier.
+     *
+     * @var string
+     */
     const ETAT_ORPHELIN = 'orphelin';
+
+    /** Fichier normal.
+     *
+     * Fichier associé à un objet métier.
+     *
+     * @var string
+     */
     const ETAT_NORMAL   = 'normal';
+
+    /** Fichier corrompu.
+     *
+     * Fichier dont le contenu disque ne correspond pas à la somme de contrôle enregistreé en base de données.
+     *
+     * @var string
+     */
     const ETAT_CORROMPU = 'corrompu';
+
+    /** Fichier manquant.
+     *
+     * Fichier existant en base de données mais introuvable sur disque.
+     *
+     * @var string
+     */
     const ETAT_MANQUANT = 'manquant';
+
+    /** Fichier rejeté.
+     *
+     * Fichier uploadé mais rejeté par un listener (par exemple l'antivirus).
+     *
+     * @var string
+     */
     const ETAT_REJETE   = 'rejete';
 
-    /**
-     * Get id
+    /** Retourne l'identifiant du fichier.
      *
-     * @return integer
+     * @return string
+     *
+     * @api
      */
     public function getId();
 
@@ -34,46 +76,64 @@ interface UploadedFileInterface
      *
      * @param string $displayName
      * @return UploadedFileInterface
+     *
+     * @api
      */
     public function setDisplayName($displayName);
 
-    /**
-     * Get originalFilename
+    /** Retourne le nom original du fichier (c-à-d sur le poste de l'utilisateur ayant fait l'upload.)
      *
      * @return string
+     *
+     * @api
      */
     public function getDisplayName();
 
     /**
      * @param string $description
      * @return UploadedFileInterface
+     *
+     * @api
      */
     public function setDescription($description = null);
 
-    /**
+    /** Retourne la description du fichier.
+     *
      * @return string
+     *
+     * @api
      */
     public function getDescription();
 
-    /**
-     * Get path
+    /** Retourne le chemin du fichier dans le filesystem.
      *
      * @return string
+     *
+     * @api
      */
     public function getPath();
 
-    /**
-     * Set path
+    /** Remplace le chemin du fichier dans le filesystem.
+     *
+     * Cela devrait causer un déplacement/renommage du fichier.
      *
      * @param string $path
+     *
      * @return UploadedFileInterface
+     *
+     * @api
      */
     public function setPath($path);
 
-    /** Change le chemin d'un fichier sans changer le nom.
+    /** Change le chemin du fichier sans changer le nom.
      *
      * @param string $newDir Nouveau répertoire
+     *
      * @return UploadedFileInterface
+     *
+     * @uses UploadedFileInterface::setPath
+     *
+     * @api
      */
     public function moveTo($newDir);
 
@@ -82,13 +142,16 @@ interface UploadedFileInterface
      *
      * @param string $mimeType
      * @return UploadedFileInterface
+     *
+     * @api
      */
     public function setMimeType($mimeType);
 
-    /**
-     * Get mimeType
+    /** Retourne le type MIME enregistré.
      *
      * @return string
+     *
+     * @api
      */
     public function getMimeType();
 
@@ -97,13 +160,16 @@ interface UploadedFileInterface
      *
      * @param integer $size
      * @return UploadedFileInterface
+     *
+     * @api
      */
     public function setSize($size);
 
-    /**
-     * Get size
+    /** Retourne la taille enregistrée, en octets.
      *
      * @return integer
+     *
+     * @api
      */
     public function getSize();
 
@@ -112,135 +178,180 @@ interface UploadedFileInterface
      *
      * @param string $checksum
      * @return UploadedFileInterface
+     *
+     * @api
      */
     public function setChecksum($checksum);
 
-    /**
-     * Get checksum
+    /** Retourne la somme de contrôle enregistrée.
      *
      * @return string
+     *
+     * @api
      */
     public function getChecksum();
 
-    /**
-     * Set etat
+    /** Modifie l'état courant du fichier.
      *
      * @param string $etat
      * @return UploadedFileInterface
+     *
+     * @api
      */
     public function setEtat($etat);
 
-    /**
-     * Get etat
+    /** Retourne l'état courant du fichier.
      *
      * @return string
+     *
+     * @api
      */
     public function getEtat();
 
-    /**
-     * Get createdAt
+    /** Retourne la date de création du fichier.
      *
      * @return DateTime
+     *
+     * @api
      */
     public function getCreatedAt();
 
-  /**
-     * Get createdBy
+    /** Retourne le nom de l'utilisateur ayant uploadé le fichier.
      *
      * @return string
+     *
+     * @api
      */
     public function getCreatedBy();
 
-    /**
-     * Get createdFrom
+    /** Retourne l'adresse IP du client ayant uploadé le fichier.
      *
      * @return string
+     *
+     * @api
      */
     public function getCreatedFrom();
 
-    /**
-     * Set metadata
+    /** Remplace les métadonnées du fichier.
+     *
+     * @param array $metadata Les nouvelles métadonnées.
      *
-     * @param array $metadata
      * @return UploadedFileInterface
+     *
+     * @api
      */
     public function setMetadata(array $metadata);
 
-    /**
-     * Get metadata
+    /** Retourne les métadonnées du fichier.
      *
      * @return array
+     *
+     * @api
      */
     public function getMetadata();
 
-    /**
+    /** Retourne une représentation texte du fichier.
+     *
      * @return string
+     *
+     * @api
      */
     public function __toString();
 
-    /**
+    /** Vérifie la validité du fichier.
      *
+     * Cela consiste à vérifier que le fichier existe dans le filesystem, et que la taille et la somme de contrôle
+     * correspondent. En cas d'erreur, l'état du fichier est modifié en conséquence.
+     *
+     * @uses UploadedFileInterface::setEtat
+     *
+     * @api
      */
     public function validate();
 
-    /**
+    /** Détermine si le fichier est dans un état "valide".
      *
      * @return boolean
+     *
+     * @api
      */
     public function isValid();
 
-    /**
+    /** Détermine si le fichier est orphelin.
      *
      * @return boolean
+     *
+     * @api
      */
     public function isOrphelin();
 
     /** Retourne la date de dernière modification dans le filesystem.
      *
      * @return DateTime
+     *
+     * @api
      */
     public function getLastModified();
 
     /** Retourne le contenu du fichier.
      *
-     * @return string Une chaîne si $asResource vaut faux,
+     * @return string Une chaîne.
+     *
+     * @api
      */
     public function getContent();
 
-    /** Ecrit dans le fichier.
+    /** Remplace le contenu du fichier.
      *
      * @param string $content
+     *
+     * @api
      */
     public function setContent($content);
 
     /** Ecrit dans le fichier depuis un descripteur de fichier.
      *
-     * @param resource $source
-     * @param int $maxlen
-     * @param int $writeOffset
-     * @return int
+     * @param resource $source Flux d'entrée à lire.
+     * @param int $maxlen Nombre maximum d'octets à lire.
+     * @param int $writeOffset Offset depuis le début du fichier.
+     *
+     * @return int Nombre d'octets écrits.
+     *
+     * @api
      */
     public function copyFrom($source, $maxlen = -1, $writeOffset = 0);
 
     /** Envoie le contenu du fichier dans un descripteur de fichier.
      *
-     * @param resource $dest
-     * @param int $maxlen
-     * @param int $readOffset
-     * @return int
+     * @param resource $dest Flux de sortie.
+     * @param int $maxlen Nombre maximum d'octets à lire.
+     * @param int $readOffset Offset depuis le début du fichier.
+     *
+     * @return int Nombre d'octets lus.
+     *
+     * @api
      */
     public function copyTo($dest, $maxlen = PHP_INT_MAX, $readOffset = 0);
 
     /** Retourne un nom de fichier local pour ce fichier.
      *
-     * Ce peut-être un fichier temporaire qui sera supprimé à la fin de la requête !
+     * Ce peut-être un fichier temporaire qui sera supprimé à la fin de la requête.
      *
      * @return string
+     *
+     * @api
      */
     public function getLocalPath();
 
-    /**
+    /** Retourne une représentation "tableau" des attributs du fichier uploadé.
+     *
+     * Utilisé comme sérialisation du pauvre.
+     *
+     * @todo Utiliser un vrai serializer.
+     *
      * @return array
+     *
+     * @internal
      */
     public function toArray();
 }