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
Checkbox
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 * Checkbox.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 `Checkbox` 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\CheckboxRenderer;
23
24/**
25 * Checkbox
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 Checkbox extends Component {
35    public function __construct(
36        CheckboxRenderer $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 of the checkbox input.
52     *
53     * This method returns the unique identifier used for the checkbox input element.
54     * The ID is essential for associating the checkbox with its label and for targeting with JavaScript or CSS.
55     *
56     * @since 0.1.0
57     * @return string The ID of the checkbox input.
58     */
59    public function getInputId(): string {
60        return $this->inputId;
61    }
62
63    /**
64     * Get the name attribute of the checkbox input.
65     *
66     * This method returns the name attribute, which is used to identify the checkbox when the form is submitted.
67     * The name is especially important when handling multiple checkboxes as part of a group.
68     *
69     * @since 0.1.0
70     * @return string The name attribute of the checkbox input.
71     */
72    public function getName(): string {
73        return $this->name;
74    }
75
76    /**
77     * Get the label of the checkbox input.
78     *
79     * This method returns the label text associated with the checkbox. The label provides a descriptive
80     * name that helps users understand the purpose of the checkbox.
81     *
82     * @since 0.1.0
83     * @return ?Label The label of the checkbox input.
84     */
85    public function getLabel(): ?Label {
86        return $this->label;
87    }
88
89    /**
90     * Get the value of the checkbox input.
91     *
92     * This method returns the value submitted when the checkbox is checked and the form is submitted.
93     * The value is important for differentiating between various checkboxes in a group.
94     *
95     * @since 0.1.0
96     * @return string The value of the checkbox input.
97     */
98    public function getValue(): string {
99        return $this->value;
100    }
101
102    /**
103     * Check if the checkbox is selected.
104     *
105     * This method returns a boolean indicating whether the checkbox is checked by default.
106     *
107     * @since 0.1.0
108     * @return bool True if the checkbox is checked, false otherwise.
109     */
110    public function isChecked(): bool {
111        return $this->checked;
112    }
113
114    /**
115     * Check if the checkbox is disabled.
116     *
117     * This method returns a boolean indicating whether the checkbox is disabled, which prevents user interaction.
118     *
119     * @since 0.1.0
120     * @return bool True if the checkbox is disabled, false otherwise.
121     */
122    public function isDisabled(): bool {
123        return $this->disabled;
124    }
125
126    /**
127     * Check if the checkbox is displayed inline.
128     *
129     * This method returns a boolean indicating whether the checkbox
130     * and its label are displayed inline with other elements.
131     *
132     * @since 0.1.0
133     * @return bool True if the checkbox is displayed inline, false otherwise.
134     */
135    public function isInline(): bool {
136        return $this->inline;
137    }
138
139    /**
140     * Get the additional HTML attributes for the checkbox input.
141     *
142     * This method returns an associative array of custom HTML attributes that are applied
143     * to the checkbox element. These attributes can be used to customize the checkboxes behavior
144     * and appearance or to enhance its integration with JavaScript.
145     *
146     * @since 0.1.0
147     * @return array The additional attributes as an array.
148     */
149    public function getInputAttributes(): array {
150        return $this->inputAttributes;
151    }
152
153    /**
154     * Get additional HTML attributes for the outer wrapper element.
155     *
156     * This method returns an associative array of custom HTML attributes that are applied to the outer wrapper element,
157     * enhancing its behavior or styling.
158     *
159     * @since 0.1.0
160     * @return array The associative array of HTML attributes for the wrapper element.
161     */
162    public function getWrapperAttributes(): array {
163        return $this->wrapperAttributes;
164    }
165
166    /**
167     * Set the ID for the checkbox input.
168     *
169     * The ID is a unique identifier for the checkbox input element. It is used to associate the input
170     * with its corresponding label and for any JavaScript or CSS targeting.
171     *
172     * @since 0.1.0
173     * @param string $inputId The ID for the checkbox input.
174     * @return $this Returns the Checkbox instance for method chaining.
175     */
176    public function setInputId( string $inputId ): self {
177        $this->inputId = $inputId;
178
179        return $this;
180    }
181
182    /**
183     * Set the name for the checkbox input.
184     *
185     * The name attribute is used to identify form data after the form is submitted. It is crucial when
186     * handling multiple checkboxes as part of a group or when submitting form data via POST or GET requests.
187     *
188     * @since 0.1.0
189     * @param string $name The name attribute for the checkbox input.
190     * @return $this Returns the Checkbox instance for method chaining.
191     */
192    public function setName( string $name ): self {
193        $this->name = $name;
194
195        return $this;
196    }
197
198    /**
199     * Set the label for the checkbox input.
200     *
201     * This method accepts a Label object which provides a descriptive label for the checkbox.
202     *
203     * @since 0.1.0
204     * @param Label $label The Label object for the checkbox.
205     * @return $this Returns the Checkbox instance for method chaining.
206     */
207    public function setLabel( Label $label ): self {
208        $this->label = $label;
209
210        return $this;
211    }
212
213    /**
214     * Set the value for the checkbox input.
215     *
216     * The value is the submitted data when the checkbox is checked and the form is submitted.
217     * This is particularly important when dealing with groups of checkboxes where each needs a distinct value.
218     *
219     * @since 0.1.0
220     * @param string $value The value for the checkbox input.
221     * @return $this Returns the Checkbox instance for method chaining.
222     */
223    public function setValue( string $value ): self {
224        $this->value = $value;
225
226        return $this;
227    }
228
229    /**
230     * Set whether the checkbox should be checked.
231     *
232     * This method determines whether the checkbox is selected by default. If set to `true`,
233     * the checkbox will be rendered in a checked state, otherwise, it will be unchecked.
234     *
235     * @since 0.1.0
236     * @param bool $checked Whether the checkbox should be checked.
237     * @return $this Returns the Checkbox instance for method chaining.
238     */
239    public function setChecked( bool $checked ): self {
240        $this->checked = $checked;
241
242        return $this;
243    }
244
245    /**
246     * Set whether the checkbox should be disabled.
247     *
248     * This method determines whether the checkbox is disabled, preventing user interaction.
249     * A disabled checkbox cannot be checked or unchecked by the user and is typically styled to appear inactive.
250     *
251     * @since 0.1.0
252     * @param bool $disabled Whether the checkbox should be disabled.
253     * @return $this Returns the Checkbox instance for method chaining.
254     */
255    public function setDisabled( bool $disabled ): self {
256        $this->disabled = $disabled;
257
258        return $this;
259    }
260
261    /**
262     * Set whether the checkbox should display inline.
263     *
264     * This method determines whether the checkbox and its label should be displayed inline with other elements.
265     * Inline checkboxes are typically used when multiple checkboxes need to appear on the same line.
266     *
267     * @since 0.1.0
268     * @param bool $inline Indicates whether the checkbox should be displayed inline.
269     * @return $this Returns the Checkbox instance for method chaining.
270     */
271    public function setInline( bool $inline ): self {
272        $this->inline = $inline;
273
274        return $this;
275    }
276
277    /**
278     * Set additional HTML attributes for the root checkbox input.
279     *
280     * This method allows custom HTML attributes to be added to the checkbox element, such as `id`, `data-*`, `aria-*`,
281     * or any other valid attributes. These attributes can be used to integrate the checkbox with JavaScript, enhance
282     * accessibility, or provide additional metadata.
283     *
284     * The values of these attributes are automatically escaped to prevent XSS vulnerabilities.
285     *
286     * @since 0.1.0
287     * @param array $inputAttributes An associative array of HTML attributes for the input element.
288     * @return $this Returns the Checkbox instance for method chaining.
289     */
290    public function setInputAttributes( array $inputAttributes ): self {
291        foreach ( $inputAttributes as $key => $value ) {
292            $this->inputAttributes[$key] = $value;
293        }
294
295        return $this;
296    }
297
298    /**
299     * Set additional HTML attributes for the outer wrapper element.
300     *
301     * This method allows custom HTML attributes to be added to the outer wrapper element,
302     * enhancing its behavior or styling.
303     *
304     * Example usage:
305     *
306     *     $textInput->setWrapperAttributes(['id' => 'custom-wrapper']);
307     *
308     * @since 0.1.0
309     * @param array $wrapperAttributes An associative array of HTML attributes for the wrapper element.
310     * @return $this Returns the Checkbox instance for method chaining.
311     */
312    public function setWrapperAttributes( array $wrapperAttributes ): self {
313        foreach ( $wrapperAttributes as $key => $value ) {
314            $this->wrapperAttributes[$key] = $value;
315        }
316
317        return $this;
318    }
319}