Code Coverage
 
Lines
Functions and Methods
Classes and Traits
Total
0.00% covered (danger)
0.00%
0 / 13
0.00% covered (danger)
0.00%
0 / 4
 CRAP
0.00% covered (danger)
0.00%
0 / 1
OptionBuilder
0.00% covered (danger)
0.00%
0 / 13
0.00% covered (danger)
0.00%
0 / 4
 30
0.00% covered (danger)
0.00%
0 / 1
 setValue
0.00% covered (danger)
0.00%
0 / 4
0.00% covered (danger)
0.00%
0 / 1
 6
 setText
0.00% covered (danger)
0.00%
0 / 2
0.00% covered (danger)
0.00%
0 / 1
 2
 setSelected
0.00% covered (danger)
0.00%
0 / 2
0.00% covered (danger)
0.00%
0 / 1
 2
 build
0.00% covered (danger)
0.00%
0 / 5
0.00% covered (danger)
0.00%
0 / 1
 2
1<?php
2/**
3 * OptionBuilder.php
4 *
5 * This file is part of the Codex design system, the official design system
6 * for Wikimedia projects. It provides the `Option` class, a builder for constructing
7 * individual option items within the `Select` component using the Codex design system.
8 *
9 * The `Option` class allows for easy and flexible creation of option elements with
10 * properties such as value, display text, and selected state.
11 *
12 * @category Builder
13 * @package  Codex\Builder
14 * @since    0.1.0
15 * @author   Doğu Abaris <abaris@null.net>
16 * @license  https://www.gnu.org/copyleft/gpl.html GPL-2.0-or-later
17 * @link     https://doc.wikimedia.org/codex/main/ Codex Documentation
18 */
19
20namespace Wikimedia\Codex\Builder;
21
22use InvalidArgumentException;
23use Wikimedia\Codex\Component\Option;
24
25/**
26 * OptionBuilder
27 *
28 * This class implements the builder pattern to construct instances of Option.
29 * It provides a fluent interface for setting various properties and building the
30 * final immutable object with predefined configurations and immutability.
31 *
32 * @category Builder
33 * @package  Codex\Builder
34 * @since    0.1.0
35 * @author   Doğu Abaris <abaris@null.net>
36 * @license  https://www.gnu.org/copyleft/gpl.html GPL-2.0-or-later
37 * @link     https://doc.wikimedia.org/codex/main/ Codex Documentation
38 */
39class OptionBuilder {
40
41    /**
42     * The value of the option, used for form submission and programmatic selection.
43     */
44    protected string $value = '';
45
46    /**
47     * The display text for the option, shown in the select dropdown.
48     */
49    protected string $text = '';
50
51    /**
52     * Indicates whether the option is selected by default.
53     */
54    protected bool $selected = false;
55
56    /**
57     * Set the value for the option.
58     *
59     * The value is used for form submission when this option is selected. The value is HTML-escaped for safety.
60     *
61     * @since 0.1.0
62     * @param string $value The unique value of the option.
63     * @return $this Returns the Option instance for method chaining.
64     */
65    public function setValue( string $value ): self {
66        if ( trim( $value ) === '' ) {
67            throw new InvalidArgumentException( 'Option value cannot be empty.' );
68        }
69        $this->value = $value;
70
71        return $this;
72    }
73
74    /**
75     * Set the display text for the option.
76     *
77     * The text is shown in the select dropdown. If not set, the value can also serve as the default display text.
78     *
79     * @since 0.1.0
80     * @param string $text The display text for the option.
81     * @return $this Returns the Option instance for method chaining.
82     */
83    public function setText( string $text ): self {
84        $this->text = $text;
85
86        return $this;
87    }
88
89    /**
90     * Set whether the option should be selected by default.
91     *
92     * This method specifies whether the option is pre-selected when the select dropdown is first displayed.
93     *
94     * @since 0.1.0
95     * @param bool $selected Whether the option is selected by default.
96     * @return $this Returns the Option instance for method chaining.
97     */
98    public function setSelected( bool $selected ): self {
99        $this->selected = $selected;
100
101        return $this;
102    }
103
104    /**
105     * Build and return the Option component object.
106     * This method constructs the immutable Option object with all the properties set via the builder.
107     *
108     * @since 0.1.0
109     * @return Option The constructed Option.
110     */
111    public function build(): Option {
112        return new Option(
113            $this->value,
114            $this->text,
115            $this->selected,
116        );
117    }
118}