ChoiceListInterface.php 3.7 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116
  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. * @return string[] The choice values
  37. */
  38. public function getValues();
  39. /**
  40. * Returns the values in the structure originally passed to the list.
  41. *
  42. * Contrary to {@link getValues()}, the result is indexed by the original
  43. * keys of the choices. If the original array contained nested arrays, these
  44. * nested arrays are represented here as well:
  45. *
  46. * $form->add('field', 'choice', array(
  47. * 'choices' => array(
  48. * 'Decided' => array('Yes' => true, 'No' => false),
  49. * 'Undecided' => array('Maybe' => null),
  50. * ),
  51. * ));
  52. *
  53. * In this example, the result of this method is:
  54. *
  55. * array(
  56. * 'Decided' => array('Yes' => '0', 'No' => '1'),
  57. * 'Undecided' => array('Maybe' => '2'),
  58. * )
  59. *
  60. * @return string[] The choice values
  61. */
  62. public function getStructuredValues();
  63. /**
  64. * Returns the original keys of the choices.
  65. *
  66. * The original keys are the keys of the choice array that was passed in the
  67. * "choice" option of the choice type. Note that this array may contain
  68. * duplicates if the "choice" option contained choice groups:
  69. *
  70. * $form->add('field', 'choice', array(
  71. * 'choices' => array(
  72. * 'Decided' => array(true, false),
  73. * 'Undecided' => array(null),
  74. * ),
  75. * ));
  76. *
  77. * In this example, the original key 0 appears twice, once for `true` and
  78. * once for `null`.
  79. *
  80. * @return int[]|string[] The original choice keys indexed by the
  81. * corresponding choice values
  82. */
  83. public function getOriginalKeys();
  84. /**
  85. * Returns the choices corresponding to the given values.
  86. *
  87. * The choices are returned with the same keys and in the same order as the
  88. * corresponding values in the given array.
  89. *
  90. * @param string[] $values An array of choice values. Non-existing values in
  91. * this array are ignored
  92. *
  93. * @return array An array of choices
  94. */
  95. public function getChoicesForValues(array $values);
  96. /**
  97. * Returns the values corresponding to the given choices.
  98. *
  99. * The values are returned with the same keys and in the same order as the
  100. * corresponding choices in the given array.
  101. *
  102. * @param array $choices An array of choices. Non-existing choices in this
  103. * array are ignored
  104. *
  105. * @return string[] An array of choice values
  106. */
  107. public function getValuesForChoices(array $choices);
  108. }