Documentation de l'API.

Form/Type/FileUploadType.php

@@ -3,6 +3,10 @@
 /*
  * Copyright (C) 2015 IRSTEA
  * All rights reserved.
+ *
+ * @package irstea/file-upload-bundle
+ * @copyright 2015 Irstea
+ * @author Guillaume Perréal <guillaume.perreal@irstea.fr>
  */
 
 namespace Irstea\FileUploadBundle\Form\Type;
@@ -23,21 +27,39 @@ use Symfony\Component\Routing\Router;
 use Symfony\Component\Validator\Constraints\Count;
 use Symfony\Component\Validator\Constraints\NotNull;
 
+/** Type de champ 'file_upload'.
+ *
+ * Options :
+ * * multiple (boolean) : fichier unique ou multiple ? false par défaut.
+ * * accept_file_types (string) : expression régulière de contrôle des types MIME acceptés. Aucune par défaut.
+ * * max_file_size (integer) : taille maximale d'un fichier. 0 (illimité) par défaut.
+ * * min_file_size (integer) : taille minimale d'un fichier. 0 par défaut.
+ * * max_number_of_files (integer) : nombre maximum de fichiers si multiple vaut true. 0 (illimité par défaut).
+ * * bitrate_interval (integer) : période de mise à jour du débit d'upload, en ms. 512ms par défaut.
+ * * progress_interval (integer): période de mis à jour de la progression, en ms. 100ms par défaut.
+ * * recalculate_progress (boolean) : recalculer la progression en cas d'erreur ? true par défaut.
+ * * sequential_uploads (boolean) : force un upload séquentiel des fichiers ? false par défaut.
+ * * max_chunk_size (integer) : taille maximule des parties envoyées, en octets. 0 (envoyer le fichier en une seule requête) par défaut.
+ *
+ */
 class FileUploadType extends AbstractType
 {
     use \Irstea\ThemeBundle\Form\AbstractJQueryWidgetTrait;
 
-    /**
+    /** Routeur.
+     *
      * @var Router
      */
     private $router;
 
-    /**
+    /** Gestionnaire de fichiers.
+     *
      * @var FileManagerInterface
      */
     private $fileManager;
 
-    /**
+    /** Taille par défaut pour l'envoi par morceaux.
+     *
      * @var int
      */
     private $defaultMaxChunkSize;
@@ -46,6 +68,7 @@ class FileUploadType extends AbstractType
      *
      * @param Router $router
      * @param FileManagerInterface $fileManager
+     * @param int $defaultMaxChunkSize
      */
     public function __construct(Router $router, FileManagerInterface $fileManager, $defaultMaxChunkSize)
     {
@@ -54,6 +77,9 @@ class FileUploadType extends AbstractType
         $this->defaultMaxChunkSize = $defaultMaxChunkSize;
     }
 
+    /**
+     * {@inheritdoc}
+     */
     public function buildForm(FormBuilderInterface $builder, array $options)
     {
         $builder->setCompound(false);
@@ -66,6 +92,9 @@ class FileUploadType extends AbstractType
         $builder->addViewTransformer(new UploadedFileTransformer($this->fileManager, $options['multiple']));
     }
 
+    /**
+     * {@inheritdoc}
+     */
     public function buildView(FormView $view, FormInterface $form, array $options)
     {
         $this->buildWidgetView($view, $form, $options);
@@ -77,6 +106,9 @@ class FileUploadType extends AbstractType
         }
     }
 
+    /**
+     * {@inheritdoc}
+     */
     public function setDefaultOptions(OptionsResolverInterface $resolver)
     {
         $this->setWidgetDefaultOptions($resolver);
@@ -89,6 +121,10 @@ class FileUploadType extends AbstractType
         }]);
     }
 
+    /** Ajoute des contraintes de validation correspondants aux paramètres du champ.
+     *
+     * @todo Implémenter min_file_size, max_file_size && accept_file_types.
+     */
     protected function addConstraints(OptionsResolver $options, $constraints)
     {
         if($options['multiple']) {
@@ -117,6 +153,9 @@ class FileUploadType extends AbstractType
         return $constraints;
     }
 
+    /**
+     * {@inheritdoc}des morceaux
+     */
     protected function getWidgetDefaults()
     {
         return [
@@ -132,11 +171,17 @@ class FileUploadType extends AbstractType
         ];
     }
 
+    /**
+     * {@inheritdoc}
+     */
     public function getName()
     {
         return "file_upload";
     }
 
+    /**
+     * {@inheritdoc}
+     */
     protected function getWidgetType()
     {
         return "irsteaFileUpload";

Twig/FileUploadExtension.php

@@ -3,6 +3,10 @@
 /*
  * Copyright (C) 2015 IRSTEA
  * All rights reserved.
+ *
+ * @package irstea/file-upload-bundle
+ * @copyright 2015 Irstea
+ * @author Guillaume Perréal <guillaume.perreal@irstea.fr>
  */
 
 namespace Irstea\FileUploadBundle\Twig;
@@ -38,6 +42,9 @@ class FileUploadExtension extends Twig_Extension
         $this->translator = $translator;
     }
 
+    /**
+     * {@inheritdoc}
+     */
     public function getFunctions()
     {
         return [
@@ -57,6 +64,9 @@ class FileUploadExtension extends Twig_Extension
         ];
     }
 
+    /**
+     * {@inheritdoc}
+     */
     public function getFilters()
     {
         return [
@@ -68,11 +78,23 @@ class FileUploadExtension extends Twig_Extension
         ];
     }
 
+    /**
+     * {@inheritdoc}
+     */
     public function getName()
     {
         return "irstea_file_upload";
     }
 
+    /** Genère un tag HTML pour représenter le fichier.
+     *
+     * Inclut un lien sécurisé qui permet de télécharger le fichier, mais uniquement à l'utilisateur qui a affiché la page.
+     *
+     * @param Twig_Environment      $env
+     * @param UploadedFileInterface $file
+     *
+     * @return string
+     */
     public function formatUploadedFile(Twig_Environment $env, $file = null)
     {
         if(null === $file) {
@@ -86,12 +108,31 @@ class FileUploadExtension extends Twig_Extension
         return $env->render('IrsteaFileUploadBundle:Extension:uploaded_file.html.twig', ['file' => $file]);
     }
 
+    /** Génère un tag "icône" Font-Awesome pour le type MIME indiqué.
+     *
+     * @param string $mimeType Type MIME.
+     *
+     * @return string Un tag  <i></i> avec les classes Font-Awesome.
+     *
+     * @uses MimeTypeIcon::getMimeTypeIcon
+     */
     public function formatFileIcon($mimeType)
     {
         $icon = MimeTypeIcon::getMimeTypeIcon($mimeType);
         return sprintf('<i class="icon fa fa-file%s-o"></i>', ($icon && $icon !== 'file') ? ('-'.$icon) : '');
     }
 
+    /** Formate une taille de fichier.
+     *
+     * @param array $context Contexte Twig.
+     * @param integer $size Taille du fichier.
+     * @param integer $precision Nombre de chiffres après la virgule.
+     * @param string $locale Langue
+     *
+     * @return string
+     *
+     * @uses \NumberFormatter
+     */
     public function formatFileSize($context, $size, $precision = null, $locale = null)
     {
         if(!is_numeric($size)) {