vendor/symfony/form/Symfony/Component/Form/Extension/Core/ChoiceList/ChoiceListInterface.php

   1 <?php
   2
   3 /*
   4  * This file is part of the Symfony package.
   5  *
   6  * (c) Fabien Potencier <fabien@symfony.com>
   7  *
   8  * For the full copyright and license information, please view the LICENSE
   9  * file that was distributed with this source code.
  10  */
  11
  12 namespace Symfony\Component\Form\Extension\Core\ChoiceList;
  13
  14 /**
  15  * Contains choices that can be selected in a form field.
  16  *
  17  * Each choice has three different properties:
  18  *
  19  *    - Choice: The choice that should be returned to the application by the
  20  *              choice field. Can be any scalar value or an object, but no
  21  *              array.
  22  *    - Label:  A text representing the choice that is displayed to the user.
  23  *    - Value:  A uniquely identifying value that can contain arbitrary
  24  *              characters, but no arrays or objects. This value is displayed
  25  *              in the HTML "value" attribute.
  26  *
  27  * @author Bernhard Schussek <bschussek@gmail.com>
  28  */
  29 interface ChoiceListInterface
  30 {
  31     /**
  32      * Returns the list of choices
  33      *
  34      * @return array The choices with their indices as keys
  35      */
  36     public function getChoices();
  37
  38     /**
  39      * Returns the values for the choices
  40      *
  41      * @return array The values with the corresponding choice indices as keys
  42      */
  43     public function getValues();
  44
  45     /**
  46      * Returns the choice views of the preferred choices as nested array with
  47      * the choice groups as top-level keys.
  48      *
  49      * Example:
  50      *
  51      * <source>
  52      * array(
  53      *     'Group 1' => array(
  54      *         10 => ChoiceView object,
  55      *         20 => ChoiceView object,
  56      *     ),
  57      *     'Group 2' => array(
  58      *         30 => ChoiceView object,
  59      *     ),
  60      * )
  61      * </source>
  62      *
  63      * @return array A nested array containing the views with the corresponding
  64      *               choice indices as keys on the lowest levels and the choice
  65      *               group names in the keys of the higher levels
  66      */
  67     public function getPreferredViews();
  68
  69     /**
  70      * Returns the choice views of the choices that are not preferred as nested
  71      * array with the choice groups as top-level keys.
  72      *
  73      * Example:
  74      *
  75      * <source>
  76      * array(
  77      *     'Group 1' => array(
  78      *         10 => ChoiceView object,
  79      *         20 => ChoiceView object,
  80      *     ),
  81      *     'Group 2' => array(
  82      *         30 => ChoiceView object,
  83      *     ),
  84      * )
  85      * </source>
  86      *
  87      * @return array A nested array containing the views with the corresponding
  88      *               choice indices as keys on the lowest levels and the choice
  89      *               group names in the keys of the higher levels
  90      *
  91      * @see getPreferredValues
  92      */
  93     public function getRemainingViews();
  94
  95     /**
  96      * Returns the choices corresponding to the given values.
  97      *
  98      * The choices can have any data type.
  99      *
 100      * @param array $values An array of choice values. Not existing values in
 101      *                      this array are ignored
 102      *
 103      * @return array An array of choices with ascending, 0-based numeric keys
 104      */
 105     public function getChoicesForValues(array $values);
 106
 107     /**
 108      * Returns the values corresponding to the given choices.
 109      *
 110      * The values must be strings.
 111      *
 112      * @param array $choices An array of choices. Not existing choices in this
 113      *                       array are ignored
 114      *
 115      * @return array An array of choice values with ascending, 0-based numeric
 116      *               keys
 117      */
 118     public function getValuesForChoices(array $choices);
 119
 120     /**
 121      * Returns the indices corresponding to the given choices.
 122      *
 123      * The indices must be positive integers or strings accepted by
 124      * {@link FormConfigBuilder::validateName()}.
 125      *
 126      * The index "placeholder" is internally reserved.
 127      *
 128      * @param array $choices An array of choices. Not existing choices in this
 129      *                       array are ignored
 130      *
 131      * @return array An array of indices with ascending, 0-based numeric keys
 132      */
 133     public function getIndicesForChoices(array $choices);
 134
 135     /**
 136      * Returns the indices corresponding to the given values.
 137      *
 138      * The indices must be positive integers or strings accepted by
 139      * {@link FormConfigBuilder::validateName()}.
 140      *
 141      * The index "placeholder" is internally reserved.
 142      *
 143      * @param array $values An array of choice values. Not existing values in
 144      *                      this array are ignored
 145      *
 146      * @return array An array of indices with ascending, 0-based numeric keys
 147      */
 148     public function getIndicesForValues(array $values);
 149 }