Skip to content

Commit 6705c19

Browse files
terabytesoftwterabytesoftw
committed
feat(embedded): add Iframe class for <iframe> element.
1 parent 198bc0f commit 6705c19

5 files changed

Lines changed: 1333 additions & 3 deletions

File tree

‎CHANGELOG.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
88
## 0.4.2 Under development
99

1010
- chore: update dependencies and configuration files.
11+
- feat(embedded): add `Iframe` class for `<iframe>` element.
1112

1213
## 0.4.1 May 07, 2026
1314

‎README.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -28,8 +28,8 @@
2828
## Features
2929

3030
<picture>
31-
<source media="(min-width: 768px)" srcset="./docs/svgs/features.svg">
32-
<img src="./docs/svgs/features-mobile.svg" alt="Feature Overview" style="width: 100%;">
31+
<source media="(max-width: 767px)" srcset="./docs/svgs/features-mobile.svg">
32+
<img src="./docs/svgs/features.svg" alt="Feature Overview" style="width: 100%;">
3333
</picture>
3434

3535
### Installation

‎scaffold-lock.json‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,7 @@
55
"path": "vendor/php-forge/baseline"
66
},
77
"php-forge/coding-standard": {
8-
"version": "0.3.1",
8+
"version": "0.3.2",
99
"path": "vendor/php-forge/coding-standard"
1010
}
1111
},

‎src/Embedded/Iframe.php‎

Lines changed: 252 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,252 @@
1+
<?php
2+
3+
declare(strict_types=1);
4+
5+
namespace UIAwesome\Html\Embedded;
6+
7+
use InvalidArgumentException;
8+
use Stringable;
9+
use UIAwesome\Html\Attribute\Values\{ElementAttribute, Loading, Referrerpolicy};
10+
use UIAwesome\Html\Core\Element\BaseBlock;
11+
use UIAwesome\Html\Helper\Validator;
12+
use UIAwesome\Html\Interop\Block;
13+
use UnitEnum;
14+
15+
/**
16+
* Renders the HTML `<iframe>` element for embedding a nested browsing context.
17+
*
18+
* Usage example:
19+
* ```php
20+
* echo \UIAwesome\Html\Embedded\Iframe::tag()
21+
* ->src('https://example.com')
22+
* ->loading('lazy')
23+
* ->title('Example')
24+
* ->render();
25+
* ```
26+
*
27+
* @link https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/iframe
28+
* {@see BaseBlock} for the base implementation.
29+
*
30+
* @copyright Copyright (C) 2026 Terabytesoftw.
31+
* @license https://opensource.org/license/bsd-3-clause BSD 3-Clause License.
32+
*/
33+
final class Iframe extends BaseBlock
34+
{
35+
/**
36+
* Sets the `allow` attribute.
37+
*
38+
* Usage example:
39+
* ```php
40+
* $element->allow('fullscreen; geolocation');
41+
* $element->allow(null);
42+
* ```
43+
*
44+
* @param string|Stringable|UnitEnum|null $value Permissions Policy applied to the embedded content, or `null` to
45+
* remove the attribute.
46+
*
47+
* @return static New instance with the updated `allow` attribute.
48+
*/
49+
public function allow(string|Stringable|UnitEnum|null $value): static
50+
{
51+
return $this->addAttribute('allow', $value);
52+
}
53+
54+
/**
55+
* Sets the `allowfullscreen` attribute.
56+
*
57+
* Usage example:
58+
* ```php
59+
* echo \UIAwesome\Html\Embedded\Iframe::tag()
60+
* ->allowfullscreen(true)
61+
* ->render();
62+
* ```
63+
*
64+
* @param bool $value Whether the embedded content can activate fullscreen mode.
65+
*
66+
* @return static New instance with the updated `allowfullscreen` attribute.
67+
*/
68+
public function allowfullscreen(bool $value): static
69+
{
70+
return $this->addAttribute('allowfullscreen', $value);
71+
}
72+
73+
/**
74+
* Sets the `height` attribute.
75+
*
76+
* Usage example:
77+
* ```php
78+
* $element->height(150);
79+
* $element->height('100%');
80+
* $element->height(null);
81+
* ```
82+
*
83+
* @param int|string|Stringable|UnitEnum|null $value Height value in pixels or CSS units, or `null` to remove the
84+
* attribute.
85+
*
86+
* @return static New instance with the updated `height` attribute.
87+
*/
88+
public function height(int|string|Stringable|UnitEnum|null $value): static
89+
{
90+
return $this->addAttribute(ElementAttribute::HEIGHT, $value);
91+
}
92+
93+
/**
94+
* Sets the `loading` attribute.
95+
*
96+
* Usage example:
97+
* ```php
98+
* $element->loading('lazy');
99+
* $element->loading(Loading::LAZY);
100+
* $element->loading(null);
101+
* ```
102+
*
103+
* @param string|Stringable|UnitEnum|null $value Loading strategy ('eager' or 'lazy'), or `null` to remove the
104+
* attribute.
105+
*
106+
* @throws InvalidArgumentException if the value is not valid.
107+
*
108+
* @return static New instance with the updated `loading` attribute.
109+
*
110+
* {@see Loading} for predefined enum values.
111+
*/
112+
public function loading(string|Stringable|UnitEnum|null $value): static
113+
{
114+
Validator::oneOf($value, Loading::cases(), ElementAttribute::LOADING);
115+
116+
return $this->addAttribute(ElementAttribute::LOADING, $value);
117+
}
118+
119+
/**
120+
* Sets the `name` attribute.
121+
*
122+
* Usage example:
123+
* ```php
124+
* $element->name('preview');
125+
* $element->name(null);
126+
* ```
127+
*
128+
* @param string|Stringable|UnitEnum|null $value Targetable name for the embedded browsing context, or `null` to
129+
* remove the attribute.
130+
*
131+
* @return static New instance with the updated `name` attribute.
132+
*/
133+
public function name(string|Stringable|UnitEnum|null $value): static
134+
{
135+
return $this->addAttribute(ElementAttribute::NAME, $value);
136+
}
137+
138+
/**
139+
* Sets the `referrerpolicy` attribute.
140+
*
141+
* Usage example:
142+
* ```php
143+
* $element->referrerpolicy('origin');
144+
* $element->referrerpolicy(Referrerpolicy::NO_REFERRER);
145+
* $element->referrerpolicy(null);
146+
* ```
147+
*
148+
* @param string|Stringable|UnitEnum|null $value Referrer policy token, or `null` to remove the attribute.
149+
*
150+
* @throws InvalidArgumentException if the value is not valid.
151+
*
152+
* @return static New instance with the updated `referrerpolicy` attribute.
153+
*
154+
* {@see Referrerpolicy} for predefined enum values.
155+
*/
156+
public function referrerpolicy(string|Stringable|UnitEnum|null $value): static
157+
{
158+
Validator::oneOf($value, Referrerpolicy::cases(), ElementAttribute::REFERRERPOLICY);
159+
160+
return $this->addAttribute(ElementAttribute::REFERRERPOLICY, $value);
161+
}
162+
163+
/**
164+
* Sets the `sandbox` attribute.
165+
*
166+
* Usage example:
167+
* ```php
168+
* $element->sandbox('allow-scripts allow-same-origin');
169+
* $element->sandbox('');
170+
* $element->sandbox(null);
171+
* ```
172+
*
173+
* @param string|Stringable|UnitEnum|null $value Space-separated restriction tokens, an empty string to apply all
174+
* restrictions, or `null` to remove the attribute.
175+
*
176+
* @return static New instance with the updated `sandbox` attribute.
177+
*/
178+
public function sandbox(string|Stringable|UnitEnum|null $value): static
179+
{
180+
return $this->addAttribute('sandbox', $value);
181+
}
182+
183+
/**
184+
* Sets the `src` attribute.
185+
*
186+
* Usage example:
187+
* ```php
188+
* $element->src('https://example.com');
189+
* $element->src('/embed/widget');
190+
* $element->src(null);
191+
* ```
192+
*
193+
* @param string|Stringable|UnitEnum|null $value URL of the page to embed, or `null` to remove the attribute.
194+
*
195+
* @return static New instance with the updated `src` attribute.
196+
*/
197+
public function src(string|Stringable|UnitEnum|null $value): static
198+
{
199+
return $this->addAttribute(ElementAttribute::SRC, $value);
200+
}
201+
202+
/**
203+
* Sets the `srcdoc` attribute.
204+
*
205+
* Usage example:
206+
* ```php
207+
* $element->srcdoc('<p>Inline content</p>');
208+
* $element->srcdoc(null);
209+
* ```
210+
*
211+
* @param string|Stringable|UnitEnum|null $value Inline HTML to embed in place of the `src` attribute, or `null` to
212+
* remove the attribute.
213+
*
214+
* @return static New instance with the updated `srcdoc` attribute.
215+
*/
216+
public function srcdoc(string|Stringable|UnitEnum|null $value): static
217+
{
218+
return $this->addAttribute('srcdoc', $value);
219+
}
220+
221+
/**
222+
* Sets the `width` attribute.
223+
*
224+
* Usage example:
225+
* ```php
226+
* $element->width(300);
227+
* $element->width('100%');
228+
* $element->width(null);
229+
* ```
230+
*
231+
* @param int|string|Stringable|UnitEnum|null $value Width value in pixels or CSS units, or `null` to remove the
232+
* attribute.
233+
*
234+
* @return static New instance with the updated `width` attribute.
235+
*/
236+
public function width(int|string|Stringable|UnitEnum|null $value): static
237+
{
238+
return $this->addAttribute(ElementAttribute::WIDTH, $value);
239+
}
240+
241+
/**
242+
* Returns the tag enumeration for the `<iframe>` element.
243+
*
244+
* @return Block Tag enumeration instance for `<iframe>`.
245+
*
246+
* {@see Block} for valid block-level tags.
247+
*/
248+
protected function getTag(): Block
249+
{
250+
return Block::IFRAME;
251+
}
252+
}

0 commit comments

Comments
 (0)