diff --git a/Model/FileManagerInterface.php b/Model/FileManagerInterface.php
index f2d48cb6cce2b68ad8a2ef063dedfc6fef94cda7..1352528cfd666b2705011c972e6d6c02eed34549 100644
--- a/Model/FileManagerInterface.php
+++ b/Model/FileManagerInterface.php
@@ -1,53 +1,82 @@
<?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();
}
diff --git a/Model/UploadedFileInterface.php b/Model/UploadedFileInterface.php
index 6bc261890dd6f334e308053168b7b6812aee4dd8..a3eb621b9f461e3be706a167a490319eb826260d 100644
--- a/Model/UploadedFileInterface.php
+++ b/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();
}