Code Coverage
 
Lines
Functions and Methods
Classes and Traits
Total
0.00% covered (danger)
0.00%
0 / 6
0.00% covered (danger)
0.00%
0 / 4
 CRAP
0.00% covered (danger)
0.00%
0 / 1
HtmlSnippetBuilder
0.00% covered (danger)
0.00%
0 / 6
0.00% covered (danger)
0.00%
0 / 4
 20
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
 setContent
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 / 2
0.00% covered (danger)
0.00%
0 / 1
 2
 build
0.00% covered (danger)
0.00%
0 / 1
0.00% covered (danger)
0.00%
0 / 1
 2
1<?php
2/**
3 * HtmlSnippetBuilder.php
4 *
5 * This file is part of the Codex design system, the official design system
6 * for Wikimedia projects. It provides the `HtmlSnippet` class for handling safe HTML content
7 * within the Codex design system.
8 *
9 * This class ensures that only trusted HTML content is passed and rendered directly,
10 * without any escaping, ensuring safe handling of HTML snippets.
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\HtmlSnippet;
23use Wikimedia\Codex\Utility\Sanitizer;
24
25/**
26 * HtmlSnippetBuilder
27 *
28 * This class implements the builder pattern to construct instances of HtmlSnippet.
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 HtmlSnippetBuilder {
40
41    /**
42     * The safe HTML content to be rendered.
43     */
44    protected string $content;
45
46    /**
47     * Additional HTML attributes for the container element.
48     */
49    protected array $attributes = [];
50
51    /**
52     * The sanitizer instance used for content sanitization.
53     */
54    private Sanitizer $sanitizer;
55
56    /**
57     * Constructor to initialize the HtmlSnippetBuilder.
58     *
59     * @since 0.1.0
60     * @param Sanitizer $sanitizer The sanitizer instance used for content sanitization.
61     */
62    public function __construct( Sanitizer $sanitizer ) {
63        $this->sanitizer = $sanitizer;
64    }
65
66    /**
67     * Set the HTML content.
68     *
69     * This method allows updating the HTML content of the snippet after the object has been instantiated.
70     *
71     * @since 0.1.0
72     * @param string $content The new HTML content to set.
73     * @return $this
74     */
75    public function setContent( string $content ): self {
76        $this->content = $this->sanitizer->sanitizeHtml( $content );
77
78        return $this;
79    }
80
81    /**
82     * Set additional HTML attributes for the container element.
83     *
84     * This method allows custom HTML attributes to be added to the container element,
85     * such as `class`, `id`, `data-*`, or any other valid attributes.
86     *
87     * The values of these attributes are automatically escaped to prevent XSS vulnerabilities.
88     *
89     * @since 0.1.0
90     * @param array $attributes An associative array of HTML attributes.
91     * @return $this
92     */
93    public function setAttributes( array $attributes ): self {
94        $this->attributes = $this->sanitizer->sanitizeAttributes( $attributes );
95
96        return $this;
97    }
98
99    /**
100     * Build and return the HtmlSnippet component object.
101     * This method constructs the immutable HtmlSnippet object with all the properties set via the builder.
102     *
103     * @since 0.1.0
104     * @return HtmlSnippet The constructed HtmlSnippet.
105     */
106    public function build(): HtmlSnippet {
107        return new HtmlSnippet( $this->content, $this->attributes );
108    }
109}