Code Coverage
 
Lines
Functions and Methods
Classes and Traits
Total
0.00% covered (danger)
0.00%
0 / 30
0.00% covered (danger)
0.00%
0 / 19
 CRAP
0.00% covered (danger)
0.00%
0 / 1
Radio
0.00% covered (danger)
0.00%
0 / 30
0.00% covered (danger)
0.00%
0 / 19
 462
0.00% covered (danger)
0.00%
0 / 1
 __construct
0.00% covered (danger)
0.00%
0 / 1
0.00% covered (danger)
0.00%
0 / 1
 2
 getInputId
0.00% covered (danger)
0.00%
0 / 1
0.00% covered (danger)
0.00%
0 / 1
 2
 getName
0.00% covered (danger)
0.00%
0 / 1
0.00% covered (danger)
0.00%
0 / 1
 2
 getLabel
0.00% covered (danger)
0.00%
0 / 1
0.00% covered (danger)
0.00%
0 / 1
 2
 getValue
0.00% covered (danger)
0.00%
0 / 1
0.00% covered (danger)
0.00%
0 / 1
 2
 isChecked
0.00% covered (danger)
0.00%
0 / 1
0.00% covered (danger)
0.00%
0 / 1
 2
 isDisabled
0.00% covered (danger)
0.00%
0 / 1
0.00% covered (danger)
0.00%
0 / 1
 2
 isInline
0.00% covered (danger)
0.00%
0 / 1
0.00% covered (danger)
0.00%
0 / 1
 2
 getInputAttributes
0.00% covered (danger)
0.00%
0 / 1
0.00% covered (danger)
0.00%
0 / 1
 2
 getWrapperAttributes
0.00% covered (danger)
0.00%
0 / 1
0.00% covered (danger)
0.00%
0 / 1
 2
 setInputId
0.00% covered (danger)
0.00%
0 / 2
0.00% covered (danger)
0.00%
0 / 1
 2
 setName
0.00% covered (danger)
0.00%
0 / 2
0.00% covered (danger)
0.00%
0 / 1
 2
 setLabel
0.00% covered (danger)
0.00%
0 / 2
0.00% covered (danger)
0.00%
0 / 1
 2
 setValue
0.00% covered (danger)
0.00%
0 / 2
0.00% covered (danger)
0.00%
0 / 1
 2
 setChecked
0.00% covered (danger)
0.00%
0 / 2
0.00% covered (danger)
0.00%
0 / 1
 2
 setDisabled
0.00% covered (danger)
0.00%
0 / 2
0.00% covered (danger)
0.00%
0 / 1
 2
 setInline
0.00% covered (danger)
0.00%
0 / 2
0.00% covered (danger)
0.00%
0 / 1
 2
 setInputAttributes
0.00% covered (danger)
0.00%
0 / 3
0.00% covered (danger)
0.00%
0 / 1
 6
 setWrapperAttributes
0.00% covered (danger)
0.00%
0 / 3
0.00% covered (danger)
0.00%
0 / 1
 6
1<?php
2declare( strict_types = 1 );
3
4/**
5 * Radio.php
6 *
7 * This file is part of the Codex design system, the official design system for Wikimedia projects.
8 * It contains the definition and implementation of the `Radio` class, responsible for managing
9 * the behavior and properties of the corresponding component.
10 *
11 * @category Component
12 * @package  Codex\Component
13 * @since    0.1.0
14 * @author   Doğu Abaris <abaris@null.net>
15 * @license  https://www.gnu.org/copyleft/gpl.html GPL-2.0-or-later
16 * @link     https://doc.wikimedia.org/codex/main/ Codex Documentation
17 */
18
19namespace Wikimedia\Codex\Component;
20
21use Wikimedia\Codex\Contract\Component;
22use Wikimedia\Codex\Renderer\RadioRenderer;
23
24/**
25 * Radio
26 *
27 * @category Component
28 * @package  Codex\Component
29 * @since    0.1.0
30 * @author   Doğu Abaris <abaris@null.net>
31 * @license  https://www.gnu.org/copyleft/gpl.html GPL-2.0-or-later
32 * @link     https://doc.wikimedia.org/codex/main/ Codex Documentation
33 */
34class Radio extends Component {
35    public function __construct(
36        RadioRenderer $renderer,
37        private string $inputId,
38        private string $name,
39        private ?Label $label,
40        private string $value,
41        private bool $checked,
42        private bool $disabled,
43        private bool $inline,
44        private array $inputAttributes,
45        private array $wrapperAttributes
46    ) {
47        parent::__construct( $renderer );
48    }
49
50    /**
51     * Get the ID for the radio input.
52     *
53     * This method returns the unique identifier for the radio input element. The ID is used to associate the input
54     * with its corresponding label and for any JavaScript or CSS targeting.
55     *
56     * @since 0.7.1
57     * @return string The ID for the radio input.
58     */
59    public function getInputId(): string {
60        return $this->inputId;
61    }
62
63    /**
64     * Get the name attribute for the radio input.
65     *
66     * This method returns the name attribute used to identify form data after the form is submitted.
67     * It is crucial when handling groups of radio buttons where only one option can be selected at a time.
68     *
69     * @since 0.1.0
70     * @return string The name attribute for the radio input.
71     */
72    public function getName(): string {
73        return $this->name;
74    }
75
76    /**
77     * Get the label object for the radio input.
78     *
79     * This method returns the label object that provides a descriptive label for the radio button.
80     * The label is crucial for accessibility and usability.
81     *
82     * @since 0.1.0
83     * @return ?Label The label object for the radio button.
84     */
85    public function getLabel(): ?Label {
86        return $this->label;
87    }
88
89    /**
90     * Get the value associated with the radio input.
91     *
92     * This method returns the value submitted when the radio button is selected and the form is submitted.
93     * This is particularly important when dealing with groups of radio buttons where each needs a distinct value.
94     *
95     * @since 0.1.0
96     * @return string The value of the radio input.
97     */
98    public function getValue(): string {
99        return $this->value;
100    }
101
102    /**
103     * Check if the radio is selected by default.
104     *
105     * This method returns a boolean value indicating whether the radio button is selected by default.
106     * If true, the radio button is rendered in a checked state.
107     *
108     * @since 0.1.0
109     * @return bool True if the radio button is checked, false otherwise.
110     */
111    public function isChecked(): bool {
112        return $this->checked;
113    }
114
115    /**
116     * Check if the radio is disabled.
117     *
118     * This method returns a boolean value indicating whether the radio button is disabled,
119     * preventing user interaction. A disabled radio button cannot be selected or deselected by the user.
120     *
121     * @since 0.1.0
122     * @return bool True if the radio button is disabled, false otherwise.
123     */
124    public function isDisabled(): bool {
125        return $this->disabled;
126    }
127
128    /**
129     * Check if the radio button should be displayed inline.
130     *
131     * This method returns a boolean value indicating whether the radio button and its label are displayed
132     * inline with other elements. Inline radio buttons are typically used when multiple radio buttons need
133     * to appear on the same line.
134     *
135     * @since 0.1.0
136     * @return bool True if the radio button is displayed inline, false otherwise.
137     */
138    public function isInline(): bool {
139        return $this->inline;
140    }
141
142    /**
143     * Get the additional HTML attributes for the radio input.
144     *
145     * This method returns an associative array of custom HTML attributes for the radio input element,
146     * such as `id`, `data-*`, `aria-*`, or any other valid attributes.
147     *
148     * @since 0.1.0
149     * @return array The additional attributes as an array.
150     */
151    public function getInputAttributes(): array {
152        return $this->inputAttributes;
153    }
154
155    /**
156     * Get additional HTML attributes for the outer wrapper element.
157     *
158     * This method returns an associative array of custom HTML attributes that are applied to the outer wrapper element,
159     * enhancing its behavior or styling.
160     *
161     * @since 0.1.0
162     * @return array The associative array of HTML attributes for the wrapper element.
163     */
164    public function getWrapperAttributes(): array {
165        return $this->wrapperAttributes;
166    }
167
168    /**
169     * Set the ID for the radio input.
170     *
171     * The ID is a unique identifier for the radio input element. It is used to associate the input
172     * with its corresponding label and for any JavaScript or CSS targeting.
173     *
174     * @since 0.7.1
175     * @param string $inputId The ID for the radio input.
176     * @return $this Returns the Radio instance for method chaining.
177     */
178    public function setInputId( string $inputId ): self {
179        $this->inputId = $inputId;
180
181        return $this;
182    }
183
184    /**
185     * Set the name for the radio input.
186     *
187     * The name attribute is used to identify form data after the form is submitted. It is crucial when
188     * handling groups of radio buttons where only one option can be selected at a time.
189     *
190     * @since 0.1.0
191     * @param string $name The name attribute for the radio input.
192     * @return $this Returns the Radio instance for method chaining.
193     */
194    public function setName( string $name ): self {
195        $this->name = $name;
196
197        return $this;
198    }
199
200    /**
201     * Set the label for the radio input.
202     *
203     * This method accepts a Label object which provides a descriptive label for the radio.
204     *
205     * @since 0.1.0
206     * @param Label $label The Label object for the radio.
207     * @return $this Returns the Radio instance for method chaining.
208     */
209    public function setLabel( Label $label ): self {
210        $this->label = $label;
211
212        return $this;
213    }
214
215    /**
216     * Set the value for the radio input.
217     *
218     * The value is the data submitted when the radio button is selected and the form is submitted.
219     * This is particularly important when dealing with groups of radio buttons where each needs a distinct value.
220     *
221     * @since 0.1.0
222     * @param string $value The value for the radio input.
223     * @return $this Returns the Radio instance for method chaining.
224     */
225    public function setValue( string $value ): self {
226        $this->value = $value;
227
228        return $this;
229    }
230
231    /**
232     * Set whether the radio should be checked.
233     *
234     * This method determines whether the radio button is selected by default. If set to `true`,
235     * the radio button will be rendered in a checked state, otherwise, it will be unchecked.
236     *
237     * @since 0.1.0
238     * @param bool $checked Whether the radio button should be checked.
239     * @return $this Returns the Radio instance for method chaining.
240     */
241    public function setChecked( bool $checked ): self {
242        $this->checked = $checked;
243
244        return $this;
245    }
246
247    /**
248     * Set whether the radio should be disabled.
249     *
250     * This method determines whether the radio button is disabled, preventing user interaction.
251     * A disabled radio button cannot be selected or deselected by the user and is typically styled to appear inactive.
252     *
253     * @since 0.1.0
254     * @param bool $disabled Whether the radio button should be disabled.
255     * @return $this Returns the Radio instance for method chaining.
256     */
257    public function setDisabled( bool $disabled ): self {
258        $this->disabled = $disabled;
259
260        return $this;
261    }
262
263    /**
264     * Set whether the radio button should be displayed inline.
265     *
266     * This method determines whether the radio button and its label should be displayed inline with other elements.
267     * Inline radio buttons are typically used when multiple radio buttons need to appear on the same line.
268     *
269     * @since 0.1.0
270     * @param bool $inline Indicates whether the radio button should be displayed inline.
271     * @return $this Returns the Radio instance for method chaining.
272     */
273    public function setInline( bool $inline ): self {
274        $this->inline = $inline;
275
276        return $this;
277    }
278
279    /**
280     * Set additional HTML attributes for the radio input.
281     *
282     * This method allows custom HTML attributes to be added to the radio input element, such as `id`, `data-*`,
283     * `aria-*`, or any other valid attributes. These attributes can be used to integrate the radio button with
284     * JavaScript, enhance accessibility, or provide additional metadata.
285     *
286     * The values of these attributes are automatically escaped to prevent XSS vulnerabilities.
287     *
288     * Example usage:
289     *
290     *     $radio->setInputAttributes([
291     *         'id' => 'radio-button-1',
292     *         'data-toggle' => 'radio-toggle',
293     *         'aria-label' => 'Radio Button 1'
294     *     ]);
295     *
296     * @since 0.1.0
297     * @param array $inputAttributes An associative array of HTML attributes for the input element.
298     * @return $this Returns the Radio instance for method chaining.
299     */
300    public function setInputAttributes( array $inputAttributes ): self {
301        foreach ( $inputAttributes as $key => $value ) {
302            $this->inputAttributes[$key] = $value;
303        }
304
305        return $this;
306    }
307
308    /**
309     * Set additional HTML attributes for the outer wrapper element.
310     *
311     * This method allows custom HTML attributes to be added to the outer wrapper element,
312     * enhancing its behavior or styling.
313     *
314     * Example usage:
315     *
316     *     $textInput->setWrapperAttributes(['id' => 'custom-wrapper']);
317     *
318     * @since 0.1.0
319     * @param array $wrapperAttributes An associative array of HTML attributes for the wrapper element.
320     * @return $this Returns the Radio instance for method chaining.
321     */
322    public function setWrapperAttributes( array $wrapperAttributes ): self {
323        foreach ( $wrapperAttributes as $key => $value ) {
324            $this->wrapperAttributes[$key] = $value;
325        }
326
327        return $this;
328    }
329}