[TASK] Streamline phpdoc annotations in EXT:fluid
[Packages/TYPO3.CMS.git] / typo3 / sysext / fluid / Classes / ViewHelpers / Format / CaseViewHelper.php
1 <?php
2 namespace TYPO3\CMS\Fluid\ViewHelpers\Format;
3
4 /*
5 * This file is part of the TYPO3 CMS project.
6 *
7 * It is free software; you can redistribute it and/or modify it under
8 * the terms of the GNU General Public License, either version 2
9 * of the License, or any later version.
10 *
11 * For the full copyright and license information, please read the
12 * LICENSE.txt file that was distributed with this source code.
13 *
14 * The TYPO3 project - inspiring people to share!
15 */
16
17 use TYPO3\CMS\Fluid\Core\ViewHelper\Exception\InvalidVariableException;
18 use TYPO3Fluid\Fluid\Core\Rendering\RenderingContextInterface;
19 use TYPO3Fluid\Fluid\Core\ViewHelper\AbstractViewHelper;
20 use TYPO3Fluid\Fluid\Core\ViewHelper\Traits\CompileWithRenderStatic;
21
22 /**
23 * Modifies the case of an input string to upper- or lowercase or capitalization.
24 * The default transformation will be uppercase as in ``mb_convert_case`` [1].
25 *
26 * Possible modes are:
27 *
28 * ``lower``
29 * Transforms the input string to its lowercase representation
30 *
31 * ``upper``
32 * Transforms the input string to its uppercase representation
33 *
34 * ``capital``
35 * Transforms the input string to its first letter upper-cased, i.e. capitalization
36 *
37 * ``uncapital``
38 * Transforms the input string to its first letter lower-cased, i.e. uncapitalization
39 *
40 * ``capitalWords``
41 * Not supported yet: Transforms the input string to each containing word being capitalized
42 *
43 * Note that the behavior will be the same as in the appropriate PHP function ``mb_convert_case`` [1];
44 * especially regarding locale and multibyte behavior.
45 *
46 * @see http://php.net/manual/function.mb-convert-case.php [1]
47 *
48 * = Examples =
49 *
50 * <code title="Example">
51 * <f:format.case>Some Text with miXed case</f:format.case>
52 * </code>
53 * <output>
54 * SOME TEXT WITH MIXED CASE
55 * </output>
56 *
57 * <code title="Example with given mode">
58 * <f:format.case mode="capital">someString</f:format.case>
59 * </code>
60 * <output>
61 * SomeString
62 * </output>
63 */
64 class CaseViewHelper extends AbstractViewHelper
65 {
66 use CompileWithRenderStatic;
67
68 /**
69 * Directs the input string being converted to "lowercase"
70 */
71 const CASE_LOWER = 'lower';
72
73 /**
74 * Directs the input string being converted to "UPPERCASE"
75 */
76 const CASE_UPPER = 'upper';
77
78 /**
79 * Directs the input string being converted to "Capital case"
80 */
81 const CASE_CAPITAL = 'capital';
82
83 /**
84 * Directs the input string being converted to "unCapital case"
85 */
86 const CASE_UNCAPITAL = 'uncapital';
87
88 /**
89 * Directs the input string being converted to "Capital Case For Each Word"
90 */
91 const CASE_CAPITAL_WORDS = 'capitalWords';
92
93 /**
94 * Output is escaped already. We must not escape children, to avoid double encoding.
95 *
96 * @var bool
97 */
98 protected $escapeChildren = false;
99
100 /**
101 * Initialize ViewHelper arguments
102 */
103 public function initializeArguments()
104 {
105 $this->registerArgument('value', 'string', 'The input value. If not given, the evaluated child nodes will be used.', false, null);
106 $this->registerArgument('mode', 'string', 'The case to apply, must be one of this\' CASE_* constants. Defaults to uppercase application.', false, self::CASE_UPPER);
107 }
108
109 /**
110 * Changes the case of the input string
111 *
112 * @param array $arguments
113 * @param \Closure $renderChildrenClosure
114 * @param RenderingContextInterface $renderingContext
115 * @return string
116 * @throws InvalidVariableException
117 */
118 public static function renderStatic(array $arguments, \Closure $renderChildrenClosure, RenderingContextInterface $renderingContext)
119 {
120 $value = $arguments['value'];
121 $mode = $arguments['mode'];
122
123 if ($value === null) {
124 $value = $renderChildrenClosure();
125 }
126
127 switch ($mode) {
128 case self::CASE_LOWER:
129 $output = mb_strtolower($value, 'utf-8');
130 break;
131 case self::CASE_UPPER:
132 $output = mb_strtoupper($value, 'utf-8');
133 break;
134 case self::CASE_CAPITAL:
135 $firstChar = mb_substr($value, 0, 1, 'utf-8');
136 $firstChar = mb_strtoupper($firstChar, 'utf-8');
137 $remainder = mb_substr($value, 1, null, 'utf-8');
138 $output = $firstChar . $remainder;
139 break;
140 case self::CASE_UNCAPITAL:
141 $firstChar = mb_substr($value, 0, 1, 'utf-8');
142 $firstChar = mb_strtolower($firstChar, 'utf-8');
143 $remainder = mb_substr($value, 1, null, 'utf-8');
144 $output = $firstChar . $remainder;
145 break;
146 case self::CASE_CAPITAL_WORDS:
147 $output = mb_convert_case($value, MB_CASE_TITLE, 'utf-8');
148 break;
149 default:
150 throw new InvalidVariableException('The case mode "' . $mode . '" supplied to Fluid\'s format.case ViewHelper is not supported.', 1358349150);
151 }
152
153 return $output;
154 }
155 }