ChoiceListInterface.php 4.5 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140
  1. <?php
  2. /*
  3. * This file is part of the Symfony package.
  4. *
  5. * (c) Fabien Potencier <fabien@symfony.com>
  6. *
  7. * For the full copyright and license information, please view the LICENSE
  8. * file that was distributed with this source code.
  9. */
  10. namespace Symfony\Component\Form\ChoiceList;
  11. /**
  12. * A list of choices that can be selected in a choice field.
  13. *
  14. * A choice list assigns unique string values to each of a list of choices.
  15. * These string values are displayed in the "value" attributes in HTML and
  16. * submitted back to the server.
  17. *
  18. * The acceptable data types for the choices depend on the implementation.
  19. * Values must always be strings and (within the list) free of duplicates.
  20. *
  21. * @author Bernhard Schussek <bschussek@gmail.com>
  22. */
  23. interface ChoiceListInterface
  24. {
  25. /**
  26. * Returns all selectable choices.
  27. *
  28. * @return array The selectable choices indexed by the corresponding values
  29. */
  30. public function getChoices();
  31. /**
  32. * Returns the values for the choices.
  33. *
  34. * The values are strings that do not contain duplicates:
  35. *
  36. * $form->add('field', 'choice', [
  37. * 'choices' => [
  38. * 'Decided' => ['Yes' => true, 'No' => false],
  39. * 'Undecided' => ['Maybe' => null],
  40. * ],
  41. * ]);
  42. *
  43. * In this example, the result of this method is:
  44. *
  45. * [
  46. * 'Yes' => '0',
  47. * 'No' => '1',
  48. * 'Maybe' => '2',
  49. * ]
  50. *
  51. * Null and false MUST NOT conflict when being casted to string.
  52. * For this some default incremented values SHOULD be computed.
  53. *
  54. * @return string[] The choice values
  55. */
  56. public function getValues();
  57. /**
  58. * Returns the values in the structure originally passed to the list.
  59. *
  60. * Contrary to {@link getValues()}, the result is indexed by the original
  61. * keys of the choices. If the original array contained nested arrays, these
  62. * nested arrays are represented here as well:
  63. *
  64. * $form->add('field', 'choice', [
  65. * 'choices' => [
  66. * 'Decided' => ['Yes' => true, 'No' => false],
  67. * 'Undecided' => ['Maybe' => null],
  68. * ],
  69. * ]);
  70. *
  71. * In this example, the result of this method is:
  72. *
  73. * [
  74. * 'Decided' => ['Yes' => '0', 'No' => '1'],
  75. * 'Undecided' => ['Maybe' => '2'],
  76. * ]
  77. *
  78. * Nested arrays do not make sense in a view format unless
  79. * they are used as a convenient way of grouping.
  80. * If the implementation does not intend to support grouped choices,
  81. * this method SHOULD be equivalent to {@link getValues()}.
  82. * The $groupBy callback parameter SHOULD be used instead.
  83. *
  84. * @return string[] The choice values
  85. */
  86. public function getStructuredValues();
  87. /**
  88. * Returns the original keys of the choices.
  89. *
  90. * The original keys are the keys of the choice array that was passed in the
  91. * "choice" option of the choice type. Note that this array may contain
  92. * duplicates if the "choice" option contained choice groups:
  93. *
  94. * $form->add('field', 'choice', [
  95. * 'choices' => [
  96. * 'Decided' => [true, false],
  97. * 'Undecided' => [null],
  98. * ],
  99. * ]);
  100. *
  101. * In this example, the original key 0 appears twice, once for `true` and
  102. * once for `null`.
  103. *
  104. * @return int[]|string[] The original choice keys indexed by the
  105. * corresponding choice values
  106. */
  107. public function getOriginalKeys();
  108. /**
  109. * Returns the choices corresponding to the given values.
  110. *
  111. * The choices are returned with the same keys and in the same order as the
  112. * corresponding values in the given array.
  113. *
  114. * @param string[] $values An array of choice values. Non-existing values in
  115. * this array are ignored
  116. *
  117. * @return array An array of choices
  118. */
  119. public function getChoicesForValues(array $values);
  120. /**
  121. * Returns the values corresponding to the given choices.
  122. *
  123. * The values are returned with the same keys and in the same order as the
  124. * corresponding choices in the given array.
  125. *
  126. * @param array $choices An array of choices. Non-existing choices in this
  127. * array are ignored
  128. *
  129. * @return string[] An array of choice values
  130. */
  131. public function getValuesForChoices(array $choices);
  132. }