Code Coverage
 
Lines
Functions and Methods
Classes and Traits
Total
0.00% covered (danger)
0.00%
0 / 12
0.00% covered (danger)
0.00%
0 / 7
 CRAP
0.00% covered (danger)
0.00%
0 / 1
Field
0.00% covered (danger)
0.00%
0 / 12
0.00% covered (danger)
0.00%
0 / 7
 56
0.00% covered (danger)
0.00%
0 / 1
 __construct
0.00% covered (danger)
0.00%
0 / 6
0.00% covered (danger)
0.00%
0 / 1
 2
 getId
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
 isFieldset
0.00% covered (danger)
0.00%
0 / 1
0.00% covered (danger)
0.00%
0 / 1
 2
 getFields
0.00% covered (danger)
0.00%
0 / 1
0.00% covered (danger)
0.00%
0 / 1
 2
 getAttributes
0.00% covered (danger)
0.00%
0 / 1
0.00% covered (danger)
0.00%
0 / 1
 2
 getHtml
0.00% covered (danger)
0.00%
0 / 1
0.00% covered (danger)
0.00%
0 / 1
 2
1<?php
2/**
3 * Field.php
4 *
5 * This file is part of the Codex design system, the official design system for Wikimedia projects.
6 * It contains the definition and implementation of the `Field` class, responsible for managing
7 * the behavior and properties of the corresponding component.
8 *
9 * @category Component
10 * @package  Codex\Component
11 * @since    0.1.0
12 * @author   Doğu Abaris <abaris@null.net>
13 * @license  https://www.gnu.org/copyleft/gpl.html GPL-2.0-or-later
14 * @link     https://doc.wikimedia.org/codex/main/ Codex Documentation
15 */
16
17namespace Wikimedia\Codex\Component;
18
19use Wikimedia\Codex\Renderer\FieldRenderer;
20
21/**
22 * Field
23 *
24 * This class is part of the Codex PHP library and is responsible for
25 * representing an immutable object. It is primarily intended for use
26 * with a builder class to construct its instances.
27 *
28 * @category Component
29 * @package  Codex\Component
30 * @since    0.1.0
31 * @author   Doğu Abaris <abaris@null.net>
32 * @license  https://www.gnu.org/copyleft/gpl.html GPL-2.0-or-later
33 * @link     https://doc.wikimedia.org/codex/main/ Codex Documentation
34 */
35class Field {
36
37    /**
38     * The ID for the fieldset.
39     */
40    protected string $id;
41
42    /**
43     * The label for the fieldset.
44     */
45    protected Label $label;
46
47    /**
48     * Indicates if the fields should be wrapped in a fieldset with a legend.
49     */
50    protected bool $isFieldset;
51
52    /**
53     * An array of fields (as HTML strings) included within the fieldset or div.
54     */
55    protected array $fields;
56
57    /**
58     * Additional HTML attributes for the fieldset or div element.
59     */
60    protected array $attributes;
61
62    /**
63     * The renderer instance used to render the field.
64     */
65    protected FieldRenderer $renderer;
66
67    /**
68     * Constructor for the Field component.
69     *
70     * Initializes a Field instance with the specified properties.
71     *
72     * @param string $id The ID for the fieldset or div.
73     * @param Label $label The label for the fieldset.
74     * @param bool $isFieldset Indicates if fields are wrapped in a fieldset.
75     * @param array $fields An array of fields (HTML strings).
76     * @param array $attributes Additional HTML attributes for the fieldset or div.
77     * @param FieldRenderer $renderer The renderer to use for rendering the field.
78     */
79    public function __construct(
80        string $id,
81        Label $label,
82        bool $isFieldset,
83        array $fields,
84        array $attributes,
85        FieldRenderer $renderer
86    ) {
87        $this->id = $id;
88        $this->label = $label;
89        $this->isFieldset = $isFieldset;
90        $this->fields = $fields;
91        $this->attributes = $attributes;
92        $this->renderer = $renderer;
93    }
94
95    /**
96     * Get the fieldset or div's HTML ID attribute.
97     *
98     * This method returns the ID that is assigned to the fieldset or div element. The ID is useful for targeting
99     * the field with JavaScript, CSS, or for accessibility purposes.
100     *
101     * @since 0.1.0
102     * @return string The ID of the fieldset or div element.
103     */
104    public function getId(): string {
105        return $this->id;
106    }
107
108    /**
109     * Get the label of the field.
110     *
111     * This method returns the label object associated with the field. The label provides a descriptive
112     * name that helps users understand the purpose of the field.
113     *
114     * @since 0.1.0
115     * @return Label The label of the field.
116     */
117    public function getLabel(): Label {
118        return $this->label;
119    }
120
121    /**
122     * Check if the fields are wrapped in a fieldset with a legend.
123     *
124     * This method returns a boolean indicating whether the fields are wrapped in a `<fieldset>`
125     * element with a `<legend>`. If false, the fields are wrapped in a `<div>` with a `<label>`.
126     *
127     * @since 0.1.0
128     * @return bool True if the fields are wrapped in a fieldset, false otherwise.
129     */
130    public function isFieldset(): bool {
131        return $this->isFieldset;
132    }
133
134    /**
135     * Get the fields included within the fieldset or div.
136     *
137     * This method returns an array of fields (as HTML strings) that are included
138     * within the fieldset or div.
139     *
140     * @since 0.1.0
141     * @return array The fields included in the fieldset or div.
142     */
143    public function getFields(): array {
144        return $this->fields;
145    }
146
147    /**
148     * Get the additional HTML attributes for the fieldset or div element.
149     *
150     * This method returns an associative array of additional HTML attributes
151     * that are applied to the fieldset or div element.
152     *
153     * @since 0.1.0
154     * @return array The additional attributes as an array.
155     */
156    public function getAttributes(): array {
157        return $this->attributes;
158    }
159
160    /**
161     * Get the component's HTML representation.
162     *
163     * This method generates the HTML markup for the component, incorporating relevant properties
164     * and any additional attributes. The component is structured using appropriate HTML elements
165     * as defined by the implementation.
166     *
167     * @since 0.1.0
168     * @return string The generated HTML string for the component.
169     */
170    public function getHtml(): string {
171        return $this->renderer->render( $this );
172    }
173}