Code Coverage
 
Lines
Functions and Methods
Classes and Traits
Total
0.00% covered (danger)
0.00%
0 / 37
0.00% covered (danger)
0.00%
0 / 19
 CRAP
0.00% covered (danger)
0.00%
0 / 1
Table
0.00% covered (danger)
0.00%
0 / 37
0.00% covered (danger)
0.00%
0 / 19
 420
0.00% covered (danger)
0.00%
0 / 1
 __construct
0.00% covered (danger)
0.00%
0 / 19
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
 getCallbacks
0.00% covered (danger)
0.00%
0 / 1
0.00% covered (danger)
0.00%
0 / 1
 2
 oppositeSort
0.00% covered (danger)
0.00%
0 / 1
0.00% covered (danger)
0.00%
0 / 1
 6
 getUseRowHeaders
0.00% covered (danger)
0.00%
0 / 1
0.00% covered (danger)
0.00%
0 / 1
 2
 getShowVerticalBorders
0.00% covered (danger)
0.00%
0 / 1
0.00% covered (danger)
0.00%
0 / 1
 2
 getPager
0.00% covered (danger)
0.00%
0 / 1
0.00% covered (danger)
0.00%
0 / 1
 2
 getPaginationPosition
0.00% covered (danger)
0.00%
0 / 1
0.00% covered (danger)
0.00%
0 / 1
 2
 getTotalRows
0.00% covered (danger)
0.00%
0 / 1
0.00% covered (danger)
0.00%
0 / 1
 2
 getFooter
0.00% covered (danger)
0.00%
0 / 1
0.00% covered (danger)
0.00%
0 / 1
 2
 getHeaderContent
0.00% covered (danger)
0.00%
0 / 1
0.00% covered (danger)
0.00%
0 / 1
 2
 getCaption
0.00% covered (danger)
0.00%
0 / 1
0.00% covered (danger)
0.00%
0 / 1
 2
 getHideCaption
0.00% covered (danger)
0.00%
0 / 1
0.00% covered (danger)
0.00%
0 / 1
 2
 getColumns
0.00% covered (danger)
0.00%
0 / 1
0.00% covered (danger)
0.00%
0 / 1
 2
 getData
0.00% covered (danger)
0.00%
0 / 1
0.00% covered (danger)
0.00%
0 / 1
 2
 getCurrentSortColumn
0.00% covered (danger)
0.00%
0 / 1
0.00% covered (danger)
0.00%
0 / 1
 2
 getCurrentSortDirection
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 * Table.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 `Table` 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\Contract\IWebRequestCallbacks;
20use Wikimedia\Codex\Renderer\TableRenderer;
21
22/**
23 * Table
24 *
25 * This class is part of the Codex PHP library and is responsible for
26 * representing an immutable object. It is primarily intended for use
27 * with a builder class to construct its instances.
28 *
29 * @category Component
30 * @package  Codex\Component
31 * @since    0.1.0
32 * @author   Doğu Abaris <abaris@null.net>
33 * @license  https://www.gnu.org/copyleft/gpl.html GPL-2.0-or-later
34 * @link     https://doc.wikimedia.org/codex/main/ Codex Documentation
35 */
36class Table {
37
38    /**
39     * Sort direction for ascending order.
40     */
41    public const SORT_ASCENDING = 'asc';
42
43    /**
44     * Sort direction for descending order.
45     */
46    public const SORT_DESCENDING = 'desc';
47
48    /**
49     * The ID for the table.
50     */
51    protected string $id;
52
53    /**
54     * The caption for the table.
55     */
56    protected string $caption;
57
58    /**
59     * Whether the caption is hidden.
60     */
61    protected bool $hideCaption;
62
63    /**
64     * The content for the table header.
65     */
66    protected ?string $headerContent;
67
68    /**
69     * Array of columns for the table.
70     */
71    protected array $columns;
72
73    /**
74     * Array of data for the table rows.
75     */
76    protected array $data;
77
78    /**
79     * Whether row headers are used.
80     */
81    protected bool $useRowHeaders;
82
83    /**
84     * Array of sorting configurations.
85     */
86    protected array $sort;
87
88    /**
89     * The current sorted column.
90     */
91    protected ?string $currentSortColumn;
92
93    /**
94     * The current sort direction.
95     */
96    protected string $currentSortDirection;
97
98    /**
99     * Whether to show vertical borders.
100     */
101    protected bool $showVerticalBorders;
102
103    /**
104     * Additional HTML attributes for the table.
105     */
106    protected array $attributes;
107
108    /**
109     * Whether pagination is enabled.
110     */
111    protected bool $paginate;
112
113    /**
114     * The total number of rows in the table.
115     */
116    protected int $totalRows;
117
118    /**
119     * The pagination position ('top', 'bottom', or 'both').
120     */
121    protected string $paginationPosition;
122
123    /**
124     * The pager for handling pagination.
125     */
126    protected ?Pager $pager;
127
128    /**
129     * The footer content of the table.
130     */
131    protected ?string $footer;
132
133    /**
134     * Callbacks object for handling custom actions.
135     */
136    protected IWebRequestCallbacks $callbacks;
137
138    /**
139     * The renderer instance used to render the table.
140     */
141    protected TableRenderer $renderer;
142
143    /**
144     * Constructor for the Table class.
145     *
146     * Initializes the Table with the necessary properties.
147     *
148     * @param string $id The ID for the table.
149     * @param string $caption The caption for the table.
150     * @param bool $hideCaption Whether the caption is hidden.
151     * @param array $columns Array of columns.
152     * @param array $data Array of row data.
153     * @param bool $useRowHeaders Whether to use row headers.
154     * @param ?string $headerContent The header content.
155     * @param array $sort Array of sorting configurations.
156     * @param ?string $currentSortColumn The current sorted column.
157     * @param string $currentSortDirection The current sort direction.
158     * @param bool $showVerticalBorders Whether to show vertical borders.
159     * @param array $attributes Additional HTML attributes.
160     * @param bool $paginate Whether pagination is enabled.
161     * @param int $totalRows The total number of rows.
162     * @param string $paginationPosition The pagination position.
163     * @param ?Pager $pager The pager for handling pagination.
164     * @param ?string $footer The footer content.
165     * @param IWebRequestCallbacks $callbacks The callbacks for handling custom actions.
166     * @param TableRenderer $renderer The renderer instance.
167     */
168    public function __construct(
169        string $id,
170        string $caption,
171        bool $hideCaption,
172        array $columns,
173        array $data,
174        bool $useRowHeaders,
175        ?string $headerContent,
176        array $sort,
177        ?string $currentSortColumn,
178        string $currentSortDirection,
179        bool $showVerticalBorders,
180        array $attributes,
181        bool $paginate,
182        int $totalRows,
183        string $paginationPosition,
184        ?Pager $pager,
185        ?string $footer,
186        IWebRequestCallbacks $callbacks,
187        TableRenderer $renderer
188    ) {
189        $this->id = $id;
190        $this->caption = $caption;
191        $this->hideCaption = $hideCaption;
192        $this->columns = $columns;
193        $this->data = $data;
194        $this->useRowHeaders = $useRowHeaders;
195        $this->headerContent = $headerContent;
196        $this->sort = $sort;
197        $this->currentSortColumn = $currentSortColumn;
198        $this->currentSortDirection = $currentSortDirection;
199        $this->showVerticalBorders = $showVerticalBorders;
200        $this->attributes = $attributes;
201        $this->paginate = $paginate;
202        $this->totalRows = $totalRows;
203        $this->paginationPosition = $paginationPosition;
204        $this->pager = $pager;
205        $this->footer = $footer;
206        $this->callbacks = $callbacks;
207        $this->renderer = $renderer;
208    }
209
210    /**
211     * Get the HTML ID for the table.
212     *
213     * This method returns the HTML `id` attribute value for the table element.
214     *
215     * @since 0.1.0
216     * @return string The ID for the table.
217     */
218    public function getId(): string {
219        return $this->id;
220    }
221
222    /**
223     * Get the IWebRequestCallbacks instance.
224     *
225     * This method returns the IWebRequestCallbacks instance if it is set. If no instance is set, it returns null.
226     *
227     * @since 0.1.0
228     * @return IWebRequestCallbacks Returns the IWebRequestCallbacks.
229     */
230    public function getCallbacks(): IWebRequestCallbacks {
231        return $this->callbacks;
232    }
233
234    /**
235     * Get the opposite sort direction.
236     *
237     * This method returns the opposite of the current sort direction.
238     *
239     * @since 0.1.0
240     * @param string $direction The current sort direction ('asc' or 'desc').
241     * @return string The opposite sort direction.
242     */
243    public function oppositeSort( string $direction ): string {
244        return $direction === self::SORT_ASCENDING ? self::SORT_DESCENDING : self::SORT_ASCENDING;
245    }
246
247    /**
248     * Get whether row headers are used.
249     *
250     * This method returns a boolean value indicating whether the first column of the table is treated as row headers.
251     * Row headers are useful for accessibility and provide additional context for each row.
252     *
253     * @since 0.1.0
254     * @return bool True if row headers are used, false otherwise.
255     */
256    public function getUseRowHeaders(): bool {
257        return $this->useRowHeaders;
258    }
259
260    /**
261     * Check if vertical borders are shown between columns.
262     *
263     * This method returns a boolean value indicating whether vertical borders are displayed between columns in the
264     * table.
265     *
266     * @since 0.1.0
267     * @return bool True if vertical borders are displayed, false otherwise.
268     */
269    public function getShowVerticalBorders(): bool {
270        return $this->showVerticalBorders;
271    }
272
273    /**
274     * Get the Pager instance for the table.
275     *
276     * This method returns the Pager instance if it is set, which provides pagination controls for the table.
277     *
278     * @since 0.1.0
279     * @return Pager|null Returns the Pager instance or null if not set.
280     */
281    public function getPager(): ?Pager {
282        return $this->pager;
283    }
284
285    /**
286     * Get the position of the pagination controls.
287     *
288     * This method returns the position of the pagination controls, which can be 'top', 'bottom', or 'both'.
289     *
290     * @since 0.1.0
291     * @return string The position of the pagination controls ('top', 'bottom', or 'both').
292     */
293    public function getPaginationPosition(): string {
294        return $this->paginationPosition;
295    }
296
297    /**
298     * Get the total number of rows.
299     *
300     * This method returns the total number of rows in the table, which is used for pagination and display purposes.
301     *
302     * @since 0.1.0
303     * @return int The total number of rows in the table.
304     */
305    public function getTotalRows(): int {
306        return $this->totalRows;
307    }
308
309    /**
310     * Get the footer content for the table.
311     *
312     * This method returns the footer content if it is set, which can contain additional information or actions related
313     * to the table.
314     *
315     * @since 0.1.0
316     * @return string|null The footer content or null if not set.
317     */
318    public function getFooter(): ?string {
319        return $this->footer;
320    }
321
322    /**
323     * Get the header content for the table.
324     *
325     * This method returns the custom content for the table's header if it is set, such as actions or additional text.
326     *
327     * @since 0.1.0
328     * @return string|null The header content or null if not set.
329     */
330    public function getHeaderContent(): ?string {
331        return $this->headerContent;
332    }
333
334    /**
335     * Get the caption for the table.
336     *
337     * This method returns the caption text that provides a description of the table's contents and purpose.
338     *
339     * @since 0.1.0
340     * @return string The caption text for the table.
341     */
342    public function getCaption(): string {
343        return $this->caption;
344    }
345
346    /**
347     * Check if the caption is hidden.
348     *
349     * This method returns a boolean value indicating whether the caption is visually hidden but still accessible to
350     * screen readers.
351     *
352     * @since 0.1.0
353     * @return bool True if the caption is hidden, false otherwise.
354     */
355    public function getHideCaption(): bool {
356        return $this->hideCaption;
357    }
358
359    /**
360     * Get the columns for the table.
361     *
362     * This method returns an array of columns defined for the table, where each column is an associative array
363     * containing column attributes.
364     *
365     * @since 0.1.0
366     * @return array The array of columns defined for the table.
367     */
368    public function getColumns(): array {
369        return $this->columns;
370    }
371
372    /**
373     * Get the data for the table.
374     *
375     * This method returns the array of data to be displayed in the table, where each row is an associative array with
376     * keys matching column IDs.
377     *
378     * @since 0.1.0
379     * @return array The array of data for the table.
380     */
381    public function getData(): array {
382        return $this->data;
383    }
384
385    /**
386     * Get the current sort column.
387     *
388     * This method returns the ID of the column currently used for sorting the table data.
389     *
390     * @since 0.1.0
391     * @return ?string The ID of the column used for sorting.
392     */
393    public function getCurrentSortColumn(): ?string {
394        return $this->currentSortColumn;
395    }
396
397    /**
398     * Get the current sort direction.
399     *
400     * This method returns the current sort direction, which can be either 'asc' for ascending or 'desc' for descending.
401     *
402     * @since 0.1.0
403     * @return string The current sort direction ('asc' or 'desc').
404     */
405    public function getCurrentSortDirection(): string {
406        return $this->currentSortDirection;
407    }
408
409    /**
410     * Get additional HTML attributes for the table element.
411     *
412     * This method returns an associative array of custom HTML attributes applied to the `<table>` element.
413     *
414     * @since 0.1.0
415     * @return array The additional attributes as an array.
416     */
417    public function getAttributes(): array {
418        return $this->attributes;
419    }
420
421    /**
422     * Get the component's HTML representation.
423     *
424     * This method generates the HTML markup for the component, incorporating relevant properties
425     * and any additional attributes. The component is structured using appropriate HTML elements
426     * as defined by the implementation.
427     *
428     * @since 0.1.0
429     * @return string The generated HTML string for the component.
430     */
431    public function getHtml(): string {
432        return $this->renderer->render( $this );
433    }
434}