[export] adding spreadsheet formatter

Export/AggregatorInterface.php

@@ -41,11 +41,49 @@ interface AggregatorInterface extends ModifierInterface
     public function getQueryKeys($data);
     
     /**
-     * transform the results to viewable and understable string.
+     * get a callable which will be able to transform the results into
+     * viewable and understable string.
+     * 
+     * The callable will have only one argument: the `value` to translate. 
+     * 
+     * The callable should also be able to return a key `_header`, which
+     * will contains the header of the column. 
+     * 
+     * The string returned **must** be already translated if necessary, 
+     * **with an exception** for the string returned for `_header`.
+     * 
+     * Example : 
+     * 
+     * ```
+     * protected $translator;
+     * 
+     * public function getLabels($key, array $values, $data)
+     * {
+     *      return function($value) {
+     *          case $value
+     *          {
+     *              case '_header' : 
+     *                  return 'my header not translated'; 
+     *              case true:
+     *                  return $this->translator->trans('true');
+     *              case false:
+     *                  return $this->translator->trans('false');
+     *              default:
+     *                  // this should not happens !
+     *                  throw new \LogicException();
+     *          }
+     * }
+     * ```
+     * 
+     * **Note:** Why each string must be translated with an exception for 
+     * the `_header` ? For performance reasons: most of the value will be number
+     * which do not need to be translated, or value already translated in
+     * database. But the header must be, in every case, translated.
      * 
      * @param string $key The column key, as added in the query
-     * @param mixed[] $values The values from the result. Each value is unique
-     * @param mixed $data The data from the form
+     * @param mixed[] $values The values from the result. if there are duplicates, those might be given twice. Example: array('FR', 'BE', 'CZ', 'FR', 'BE', 'FR')
+     * @param mixed $data The data from the export's form (as defined in `buildForm`
+     * @return \Closure where the first argument is the value, and the function should return the label to show in the formatted file. Example : `function($countryCode) use ($countries) { return $countries[$countryCode]->getName(); }`
      */
     public function getLabels($key, array $values, $data);