Code Coverage
 
Lines
Functions and Methods
Classes and Traits
Total
0.00% covered (danger)
0.00%
0 / 18
0.00% covered (danger)
0.00%
0 / 10
 CRAP
0.00% covered (danger)
0.00%
0 / 1
Card
0.00% covered (danger)
0.00%
0 / 18
0.00% covered (danger)
0.00%
0 / 10
 110
0.00% covered (danger)
0.00%
0 / 1
 __construct
0.00% covered (danger)
0.00%
0 / 9
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
 getTitle
0.00% covered (danger)
0.00%
0 / 1
0.00% covered (danger)
0.00%
0 / 1
 2
 getDescription
0.00% covered (danger)
0.00%
0 / 1
0.00% covered (danger)
0.00%
0 / 1
 2
 getSupportingText
0.00% covered (danger)
0.00%
0 / 1
0.00% covered (danger)
0.00%
0 / 1
 2
 getUrl
0.00% covered (danger)
0.00%
0 / 1
0.00% covered (danger)
0.00%
0 / 1
 2
 getIconClass
0.00% covered (danger)
0.00%
0 / 1
0.00% covered (danger)
0.00%
0 / 1
 2
 getThumbnail
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 * Card.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 `Card` 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\CardRenderer;
20
21/**
22 * Card
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 Card {
36
37    /**
38     * The ID for the card.
39     */
40    protected string $id;
41
42    /**
43     * The title text displayed on the card.
44     */
45    protected string $title;
46
47    /**
48     * The description text displayed on the card.
49     */
50    protected string $description;
51
52    /**
53     * Optional supporting text for additional details on the card.
54     */
55    protected string $supportingText;
56
57    /**
58     * The URL the card links to, if the card is clickable.
59     */
60    protected string $url;
61
62    /**
63     * The CSS class for an optional icon in the card.
64     */
65    protected ?string $iconClass;
66
67    /**
68     * The Thumbnail object representing the card's thumbnail.
69     */
70    protected ?Thumbnail $thumbnail;
71
72    /**
73     * Additional HTML attributes for the card element.
74     */
75    protected array $attributes;
76
77    /**
78     * The renderer instance used to render the card.
79     */
80    protected CardRenderer $renderer;
81
82    /**
83     * Constructor for the Card component.
84     *
85     * Initializes a Card instance with the specified properties.
86     *
87     * @param string $id The ID for the card.
88     * @param string $title The title text displayed on the card.
89     * @param string $description The description text displayed on the card.
90     * @param string $supportingText The supporting text displayed on the card.
91     * @param string $url The URL the card links to, if clickable.
92     * @param string|null $iconClass The CSS class for an optional icon in the card.
93     * @param Thumbnail|null $thumbnail The Thumbnail object representing the card's thumbnail.
94     * @param array $attributes Additional HTML attributes for the card element.
95     * @param CardRenderer $renderer The renderer to use for rendering the card.
96     */
97    public function __construct(
98        string $id,
99        string $title,
100        string $description,
101        string $supportingText,
102        string $url,
103        ?string $iconClass,
104        ?Thumbnail $thumbnail,
105        array $attributes,
106        CardRenderer $renderer
107    ) {
108        $this->id = $id;
109        $this->title = $title;
110        $this->description = $description;
111        $this->supportingText = $supportingText;
112        $this->url = $url;
113        $this->iconClass = $iconClass;
114        $this->thumbnail = $thumbnail;
115        $this->attributes = $attributes;
116        $this->renderer = $renderer;
117    }
118
119    /**
120     * Get the card's HTML ID attribute.
121     *
122     * This method returns the ID that is assigned to the card element. The ID is useful for targeting
123     * the card with JavaScript, CSS, or for accessibility purposes.
124     *
125     * @since 0.1.0
126     * @return string The ID of the card element.
127     */
128    public function getId(): string {
129        return $this->id;
130    }
131
132    /**
133     * Get the title text displayed on the card.
134     *
135     * This method returns the title text that is prominently displayed on the card.
136     * The title usually represents the main topic or subject of the card.
137     *
138     * @since 0.1.0
139     * @return string The title of the card.
140     */
141    public function getTitle(): string {
142        return $this->title;
143    }
144
145    /**
146     * Get the description text displayed on the card.
147     *
148     * This method returns the description text that provides additional details about
149     * the card's content. The description is typically rendered below the title.
150     *
151     * @since 0.1.0
152     * @return string The description of the card.
153     */
154    public function getDescription(): string {
155        return $this->description;
156    }
157
158    /**
159     * Get the supporting text displayed on the card.
160     *
161     * This method returns the supporting text that provides further context or details
162     * about the card's content. The supporting text is typically rendered at the bottom
163     * of the card, below the title and description.
164     *
165     * @since 0.1.0
166     * @return string The supporting text of the card.
167     */
168    public function getSupportingText(): string {
169        return $this->supportingText;
170    }
171
172    /**
173     * Get the URL the card links to.
174     *
175     * This method returns the URL that the card links to if the card is clickable.
176     * If a URL is provided, the card is rendered as an anchor (`<a>`) element.
177     *
178     * @since 0.1.0
179     * @return string The URL the card links to.
180     */
181    public function getUrl(): string {
182        return $this->url;
183    }
184
185    /**
186     * Get the icon class for the card.
187     *
188     * This method returns the CSS class used for the icon displayed inside the card.
189     * The icon is an optional visual element that can enhance the card's content.
190     *
191     * @since 0.1.0
192     * @return string|null The CSS class for the icon, or null if no icon is set.
193     */
194    public function getIconClass(): ?string {
195        return $this->iconClass;
196    }
197
198    /**
199     * Get the thumbnail object associated with the card.
200     *
201     * This method returns the Thumbnail object representing the card's thumbnail.
202     *
203     * @since 0.1.0
204     * @return Thumbnail|null The Thumbnail object or null if no thumbnail is set.
205     */
206    public function getThumbnail(): ?Thumbnail {
207        return $this->thumbnail;
208    }
209
210    /**
211     * Retrieve additional HTML attributes for the card element.
212     *
213     * This method returns an associative array of additional HTML attributes that will be applied
214     * to the card element. These attributes can be used to enhance the appearance, accessibility,
215     * or functionality of the card.
216     *
217     * @since 0.1.0
218     * @return array The additional attributes as an array.
219     */
220    public function getAttributes(): array {
221        return $this->attributes;
222    }
223
224    /**
225     * Get the component's HTML representation.
226     *
227     * This method generates the HTML markup for the component, incorporating relevant properties
228     * and any additional attributes. The component is structured using appropriate HTML elements
229     * as defined by the implementation.
230     *
231     * @since 0.1.0
232     * @return string The generated HTML string for the component.
233     */
234    public function getHtml(): string {
235        return $this->renderer->render( $this );
236    }
237}