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 / 17
 CRAP
0.00% covered (danger)
0.00%
0 / 1
Card
0.00% covered (danger)
0.00%
0 / 30
0.00% covered (danger)
0.00%
0 / 17
 420
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
 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
 setId
0.00% covered (danger)
0.00%
0 / 2
0.00% covered (danger)
0.00%
0 / 1
 2
 setTitle
0.00% covered (danger)
0.00%
0 / 4
0.00% covered (danger)
0.00%
0 / 1
 6
 setDescription
0.00% covered (danger)
0.00%
0 / 2
0.00% covered (danger)
0.00%
0 / 1
 2
 setSupportingText
0.00% covered (danger)
0.00%
0 / 2
0.00% covered (danger)
0.00%
0 / 1
 2
 setUrl
0.00% covered (danger)
0.00%
0 / 4
0.00% covered (danger)
0.00%
0 / 1
 6
 setIconClass
0.00% covered (danger)
0.00%
0 / 2
0.00% covered (danger)
0.00%
0 / 1
 2
 setThumbnail
0.00% covered (danger)
0.00%
0 / 2
0.00% covered (danger)
0.00%
0 / 1
 2
 setAttributes
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 * Card.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 `Card` 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 InvalidArgumentException;
22use Wikimedia\Codex\Contract\Component;
23use Wikimedia\Codex\Renderer\CardRenderer;
24
25/**
26 * Card
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 extends Component {
36    private string $id = '';
37
38    public function __construct(
39        CardRenderer $renderer,
40        private string|HtmlSnippet $title,
41        private string|HtmlSnippet $description,
42        private string|HtmlSnippet $supportingText,
43        private string $url,
44        private ?string $iconClass,
45        private ?Thumbnail $thumbnail,
46        private array $attributes,
47    ) {
48        parent::__construct( $renderer );
49    }
50
51    /**
52     * Get the card's HTML ID attribute.
53     *
54     * This method returns the ID assigned to the card element. The ID is useful for targeting
55     * the card with JavaScript, CSS, or for accessibility purposes.
56     *
57     * @since 0.1.0
58     * @return string The ID of the card element.
59     */
60    public function getId(): string {
61        return $this->id;
62    }
63
64    /**
65     * Get the title text displayed on the card.
66     *
67     * This method returns the title text prominently displayed on the card.
68     * The title usually represents the main topic or subject of the card.
69     *
70     * @since 0.1.0
71     * @return string|HtmlSnippet The title of the card.
72     */
73    public function getTitle(): string|HtmlSnippet {
74        return $this->title;
75    }
76
77    /**
78     * Get the description text displayed on the card.
79     *
80     * This method returns the description text that provides additional details about
81     * the card's content. The description is typically rendered below the title.
82     *
83     * @since 0.1.0
84     * @return string|HtmlSnippet The description of the card.
85     */
86    public function getDescription(): string|HtmlSnippet {
87        return $this->description;
88    }
89
90    /**
91     * Get the supporting text displayed on the card.
92     *
93     * This method returns the supporting text that provides further context or details
94     * about the card's content. The supporting text is typically rendered at the bottom
95     * of the card, below the title and description.
96     *
97     * @since 0.1.0
98     * @return string|HtmlSnippet The supporting text of the card.
99     */
100    public function getSupportingText(): string|HtmlSnippet {
101        return $this->supportingText;
102    }
103
104    /**
105     * Get the URL the card links to.
106     *
107     * This method returns the URL that the card links to if the card is clickable.
108     * If a URL is provided, the card is rendered as an anchor (`<a>`) element.
109     *
110     * @since 0.1.0
111     * @return string The URL the card links to.
112     */
113    public function getUrl(): string {
114        return $this->url;
115    }
116
117    /**
118     * Get the icon class for the card.
119     *
120     * This method returns the CSS class used for the icon displayed inside the card.
121     * The icon is an optional visual element that can enhance the card's content.
122     *
123     * @since 0.1.0
124     * @return string|null The CSS class for the icon, or null if no icon is set.
125     */
126    public function getIconClass(): ?string {
127        return $this->iconClass;
128    }
129
130    /**
131     * Get the thumbnail object associated with the card.
132     *
133     * This method returns the Thumbnail object representing the card's thumbnail.
134     *
135     * @since 0.1.0
136     * @return Thumbnail|null The Thumbnail object or null if no thumbnail is set.
137     */
138    public function getThumbnail(): ?Thumbnail {
139        return $this->thumbnail;
140    }
141
142    /**
143     * Retrieve additional HTML attributes for the card element.
144     *
145     * This method returns an associative array of additional HTML attributes that will be applied
146     * to the card element. These attributes can be used to enhance the appearance, accessibility,
147     * or functionality of the card.
148     *
149     * @since 0.1.0
150     * @return array The additional attributes as an array.
151     */
152    public function getAttributes(): array {
153        return $this->attributes;
154    }
155
156    /**
157     * Set the card's HTML ID attribute.
158     *
159     * @deprecated Use setAttributes() to set the ID
160     * @since 0.1.0
161     * @param string $id The ID for the card element.
162     * @return $this
163     */
164    public function setId( string $id ): self {
165        $this->id = $id;
166
167        return $this;
168    }
169
170    /**
171     * Set the title for the card.
172     *
173     * The title is the primary text displayed on the card, typically representing the main topic
174     * or subject of the card. It is usually rendered in a larger font and is the most prominent
175     * piece of text on the card.
176     *
177     * @since 0.1.0
178     * @param string|HtmlSnippet $title The title text displayed on the card.
179     * @return $this Returns the Card instance for method chaining.
180     */
181    public function setTitle( string|HtmlSnippet $title ): self {
182        if ( trim( $title ) === '' ) {
183            throw new InvalidArgumentException( 'Card title cannot be empty.' );
184        }
185        $this->title = $title;
186
187        return $this;
188    }
189
190    /**
191     * Set the description for the card.
192     *
193     * The description provides additional details about the card's content. It is typically rendered
194     * below the title in a smaller font. The description is optional and can be used to give users
195     * more context about what the card represents.
196     *
197     * @since 0.1.0
198     * @param string|HtmlSnippet $description The description text displayed on the card.
199     * @return $this Returns the Card instance for method chaining.
200     */
201    public function setDescription( string|HtmlSnippet $description ): self {
202        $this->description = $description;
203
204        return $this;
205    }
206
207    /**
208     * Set the supporting text for the card.
209     *
210     * The supporting text is an optional piece of text that can provide additional information
211     * or context about the card. It is typically placed at the bottom of the card, below the
212     * title and description, in a smaller font. This text can be used for subtitles, additional
213     * notes, or other relevant details.
214     *
215     * @since 0.1.0
216     * @param string|HtmlSnippet $supportingText The supporting text displayed on the card.
217     * @return $this Returns the Card instance for method chaining.
218     */
219    public function setSupportingText( string|HtmlSnippet $supportingText ): self {
220        $this->supportingText = $supportingText;
221
222        return $this;
223    }
224
225    /**
226     * Set the URL for the card. If provided, the card will be an `<a>` element.
227     *
228     * This method makes the entire card clickable by wrapping it in an anchor (`<a>`) element,
229     * turning it into a link. This is particularly useful for cards that serve as navigational
230     * elements, leading users to related content, such as articles, profiles, or external pages.
231     *
232     * @since 0.1.0
233     * @param string $url The URL the card should link to.
234     * @return $this Returns the Card instance for method chaining.
235     */
236    public function setUrl( string $url ): self {
237        if ( !filter_var( $url, FILTER_VALIDATE_URL ) ) {
238            throw new InvalidArgumentException( "Invalid URL: $url" );
239        }
240        $this->url = $url;
241
242        return $this;
243    }
244
245    /**
246     * Set the icon class for the card.
247     *
248     * This method specifies a CSS class for an icon to be displayed inside the card.
249     * The icon can be used to visually represent the content or purpose of the card.
250     * It is typically rendered at the top or side of the card, depending on the design.
251     *
252     * @since 0.1.0
253     * @param string $iconClass The CSS class for the icon.
254     * @return $this Returns the Card instance for method chaining.
255     */
256    public function setIconClass( string $iconClass ): self {
257        $this->iconClass = $iconClass;
258
259        return $this;
260    }
261
262    /**
263     * Set the thumbnail for the card.
264     *
265     * This method accepts a `Thumbnail` object, which configures the thumbnail associated with the card.
266     *
267     * Example usage:
268     *     $thumbnail = Thumbnail::setBackgroundImage('https://example.com/image.jpg');
269     *     $card->setThumbnail($thumbnail);
270     *
271     * @since 0.1.0
272     * @param Thumbnail $thumbnail The Thumbnail object.
273     * @return $this Returns the Card instance for method chaining.
274     */
275    public function setThumbnail( Thumbnail $thumbnail ): self {
276        $this->thumbnail = $thumbnail;
277
278        return $this;
279    }
280
281    /**
282     * Set additional HTML attributes for the card element.
283     *
284     * This method allows custom HTML attributes to be added to the card element, such as `id`, `data-*`, `aria-*`,
285     * or any other valid attributes. These attributes can be used to integrate the card with JavaScript, enhance
286     * accessibility, or provide additional metadata.
287     *
288     * The values of these attributes are automatically escaped to prevent XSS vulnerabilities.
289     *
290     * @since 0.1.0
291     * @param array $attributes An associative array of HTML attributes.
292     * @return $this Returns the Card instance for method chaining.
293     */
294    public function setAttributes( array $attributes ): self {
295        foreach ( $attributes as $key => $value ) {
296            $this->attributes[$key] = $value;
297        }
298        return $this;
299    }
300}