Code Coverage
 
Lines
Functions and Methods
Classes and Traits
Total
0.00% covered (danger)
0.00%
0 / 17
0.00% covered (danger)
0.00%
0 / 6
 CRAP
0.00% covered (danger)
0.00%
0 / 1
ThumbnailBuilder
0.00% covered (danger)
0.00%
0 / 17
0.00% covered (danger)
0.00%
0 / 6
 56
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
 setId
0.00% covered (danger)
0.00%
0 / 2
0.00% covered (danger)
0.00%
0 / 1
 2
 setBackgroundImage
0.00% covered (danger)
0.00%
0 / 2
0.00% covered (danger)
0.00%
0 / 1
 2
 setPlaceholderClass
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
 build
0.00% covered (danger)
0.00%
0 / 7
0.00% covered (danger)
0.00%
0 / 1
 2
1<?php
2/**
3 * ThumbnailBuilder.php
4 *
5 * This file is part of the Codex design system, the official design system
6 * for Wikimedia projects. It provides the `Thumbnail` class, a builder for constructing
7 * thumbnail components using the Codex design system.
8 *
9 * A Thumbnail is a visual element used to display a small preview of an image.
10 * Thumbnails provide users with a quick glimpse of the associated content.
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 Wikimedia\Codex\Component\Thumbnail;
23use Wikimedia\Codex\Renderer\ThumbnailRenderer;
24
25/**
26 * ThumbnailBuilder
27 *
28 * This class implements the builder pattern to construct instances of Thumbnail.
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 ThumbnailBuilder {
40
41    /**
42     * The ID for the thumbnail.
43     */
44    protected string $id = '';
45
46    /**
47     * Background image URL.
48     */
49    protected string $backgroundImage = '';
50
51    /**
52     * CSS class for custom placeholder icon.
53     */
54    protected string $placeholderClass = '';
55
56    /**
57     * Additional HTML attributes for the thumbnail.
58     */
59    protected array $attributes = [];
60
61    /**
62     * The renderer instance used to render the thumbnail.
63     */
64    protected ThumbnailRenderer $renderer;
65
66    /**
67     * Constructor for the ThumbnailBuilder class.
68     *
69     * @param ThumbnailRenderer $renderer The renderer to use for rendering the thumbnail.
70     */
71    public function __construct( ThumbnailRenderer $renderer ) {
72        $this->renderer = $renderer;
73    }
74
75    /**
76     * Set the Thumbnail HTML ID attribute.
77     *
78     * @since 0.1.0
79     * @param string $id The ID for the Thumbnail element.
80     * @return $this
81     */
82    public function setId( string $id ): self {
83        $this->id = $id;
84
85        return $this;
86    }
87
88    /**
89     * Set the background image for the thumbnail.
90     *
91     * This method specifies the URL of the background image that will be displayed
92     * within the thumbnail. The image serves as a visual preview of the content.
93     *
94     * Example usage:
95     *
96     *     $thumbnail->setBackgroundImage('https://example.com/image.jpg');
97     *
98     * @since 0.1.0
99     * @param string $backgroundImage The URL of the background image.
100     * @return $this Returns the Thumbnail instance for method chaining.
101     */
102    public function setBackgroundImage( string $backgroundImage ): self {
103        $this->backgroundImage = $backgroundImage;
104
105        return $this;
106    }
107
108    /**
109     * Set the CSS class for a custom placeholder icon.
110     *
111     * This method specifies a custom CSS class for a placeholder icon that will be displayed
112     * if the background image is not provided. The placeholder gives users a visual indication of where
113     * an image will appear.
114     *
115     * Example usage:
116     *
117     *     $thumbnail->setPlaceholderClass('custom-placeholder-icon');
118     *
119     * @since 0.1.0
120     * @param string $placeholderClass The CSS class for the placeholder icon.
121     * @return $this Returns the Thumbnail instance for method chaining.
122     */
123    public function setPlaceholderClass( string $placeholderClass ): self {
124        $this->placeholderClass = $placeholderClass;
125
126        return $this;
127    }
128
129    /**
130     * Set additional HTML attributes for the thumbnail element.
131     *
132     * This method allows custom HTML attributes to be added to the outer `<span>` element of the thumbnail,
133     * such as `id`, `data-*`, `aria-*`, or any other valid attributes. These attributes can be used to
134     * enhance accessibility or integrate with JavaScript.
135     *
136     * Example usage:
137     *
138     *     $thumbnail->setAttributes([
139     *         'id' => 'thumbnail-id',
140     *         'data-category' => 'images',
141     *     ]);
142     *
143     * @since 0.1.0
144     * @param array $attributes An associative array of HTML attributes.
145     * @return $this Returns the Thumbnail instance for method chaining.
146     */
147    public function setAttributes( array $attributes ): self {
148        foreach ( $attributes as $key => $value ) {
149            $this->attributes[$key] = $value;
150        }
151        return $this;
152    }
153
154    /**
155     * Build and return the Thumbnail component object.
156     * This method constructs the immutable Thumbnail object with all the properties set via the builder.
157     *
158     * @since 0.1.0
159     * @return Thumbnail The constructed Thumbnail.
160     */
161    public function build(): Thumbnail {
162        return new Thumbnail(
163            $this->id,
164            $this->backgroundImage,
165            $this->placeholderClass,
166            $this->attributes,
167            $this->renderer
168        );
169    }
170}