3 namespace Drupal\media\OEmbed;
5 use Drupal\Core\Cache\Cache;
6 use Drupal\Core\Cache\CacheableDependencyInterface;
7 use Drupal\Core\Cache\CacheableDependencyTrait;
11 * Value object representing an oEmbed resource.
13 * Data received from an oEmbed provider could be insecure. For example,
14 * resources of the 'rich' type provide an HTML representation which is not
15 * sanitized by this object in any way. Any values you retrieve from this object
16 * should be treated as potentially dangerous user input and carefully validated
17 * and sanitized before being displayed or otherwise manipulated by your code.
19 * Valid resource types are defined in the oEmbed specification and represented
20 * by the TYPE_* constants in this class.
22 * @see https://oembed.com/#section2
25 * This class is an internal part of the oEmbed system and should only be
27 * \Drupal\media\OEmbed\ResourceFetcherInterface::fetchResource().
29 class Resource implements CacheableDependencyInterface {
31 use CacheableDependencyTrait;
34 * The resource type for link resources.
36 const TYPE_LINK = 'link';
39 * The resource type for photo resources.
41 const TYPE_PHOTO = 'photo';
44 * The resource type for rich resources.
46 const TYPE_RICH = 'rich';
49 * The resource type for video resources.
51 const TYPE_VIDEO = 'video';
54 * The resource type. Can be one of the static::TYPE_* constants.
61 * The resource provider.
63 * @var \Drupal\media\OEmbed\Provider
68 * A text title, describing the resource.
75 * The name of the author/owner of the resource.
79 protected $authorName;
82 * A URL for the author/owner of the resource.
89 * A URL to a thumbnail image representing the resource.
91 * The thumbnail must respect any maxwidth and maxheight parameters passed
92 * to the oEmbed endpoint. If this parameter is present, thumbnail_width and
93 * thumbnail_height must also be present.
97 * @see \Drupal\media\OEmbed\UrlResolverInterface::getResourceUrl()
98 * @see https://oembed.com/#section2
100 protected $thumbnailUrl;
103 * The width of the thumbnail, in pixels.
105 * If this parameter is present, thumbnail_url and thumbnail_height must also
110 protected $thumbnailWidth;
113 * The height of the thumbnail, in pixels.
115 * If this parameter is present, thumbnail_url and thumbnail_width must also
120 protected $thumbnailHeight;
123 * The width of the resource, in pixels.
130 * The height of the resource, in pixels.
137 * The resource URL. Only applies to 'photo' and 'link' resources.
144 * The HTML representation of the resource.
146 * Only applies to 'rich' and 'video' resources.
153 * Resource constructor.
155 * @param \Drupal\media\OEmbed\Provider $provider
156 * (optional) The resource provider.
157 * @param string $title
158 * (optional) A text title, describing the resource.
159 * @param string $author_name
160 * (optional) The name of the author/owner of the resource.
161 * @param string $author_url
162 * (optional) A URL for the author/owner of the resource.
163 * @param int $cache_age
164 * (optional) The suggested cache lifetime for this resource, in seconds.
165 * @param string $thumbnail_url
166 * (optional) A URL to a thumbnail image representing the resource. If this
167 * parameter is present, $thumbnail_width and $thumbnail_height must also be
169 * @param int $thumbnail_width
170 * (optional) The width of the thumbnail, in pixels. If this parameter is
171 * present, $thumbnail_url and $thumbnail_height must also be present.
172 * @param int $thumbnail_height
173 * (optional) The height of the thumbnail, in pixels. If this parameter is
174 * present, $thumbnail_url and $thumbnail_width must also be present.
176 protected function __construct(Provider $provider = NULL, $title = NULL, $author_name = NULL, $author_url = NULL, $cache_age = NULL, $thumbnail_url = NULL, $thumbnail_width = NULL, $thumbnail_height = NULL) {
177 $this->provider = $provider;
178 $this->title = $title;
179 $this->authorName = $author_name;
180 $this->authorUrl = $author_url;
182 if (isset($cache_age) && is_numeric($cache_age)) {
183 // If the cache age is too big, it can overflow the 'expire' column of
184 // database cache backends, causing SQL exceptions. To prevent that,
185 // arbitrarily limit the cache age to 5 years. That should be enough.
186 $this->cacheMaxAge = Cache::mergeMaxAges((int) $cache_age, 157680000);
189 if ($thumbnail_url) {
190 $this->thumbnailUrl = $thumbnail_url;
191 $this->setThumbnailDimensions($thumbnail_width, $thumbnail_height);
196 * Creates a link resource.
199 * (optional) The URL of the resource.
200 * @param \Drupal\media\OEmbed\Provider $provider
201 * (optional) The resource provider.
202 * @param string $title
203 * (optional) A text title, describing the resource.
204 * @param string $author_name
205 * (optional) The name of the author/owner of the resource.
206 * @param string $author_url
207 * (optional) A URL for the author/owner of the resource.
208 * @param int $cache_age
209 * (optional) The suggested cache lifetime for this resource, in seconds.
210 * @param string $thumbnail_url
211 * (optional) A URL to a thumbnail image representing the resource. If this
212 * parameter is present, $thumbnail_width and $thumbnail_height must also be
214 * @param int $thumbnail_width
215 * (optional) The width of the thumbnail, in pixels. If this parameter is
216 * present, $thumbnail_url and $thumbnail_height must also be present.
217 * @param int $thumbnail_height
218 * (optional) The height of the thumbnail, in pixels. If this parameter is
219 * present, $thumbnail_url and $thumbnail_width must also be present.
223 public static function link($url = NULL, Provider $provider = NULL, $title = NULL, $author_name = NULL, $author_url = NULL, $cache_age = NULL, $thumbnail_url = NULL, $thumbnail_width = NULL, $thumbnail_height = NULL) {
224 $resource = new static($provider, $title, $author_name, $author_url, $cache_age, $thumbnail_url, $thumbnail_width, $thumbnail_height);
225 $resource->type = self::TYPE_LINK;
226 $resource->url = $url;
232 * Creates a photo resource.
235 * The URL of the photo.
237 * The width of the photo, in pixels.
239 * The height of the photo, in pixels.
240 * @param \Drupal\media\OEmbed\Provider $provider
241 * (optional) The resource provider.
242 * @param string $title
243 * (optional) A text title, describing the resource.
244 * @param string $author_name
245 * (optional) The name of the author/owner of the resource.
246 * @param string $author_url
247 * (optional) A URL for the author/owner of the resource.
248 * @param int $cache_age
249 * (optional) The suggested cache lifetime for this resource, in seconds.
250 * @param string $thumbnail_url
251 * (optional) A URL to a thumbnail image representing the resource. If this
252 * parameter is present, $thumbnail_width and $thumbnail_height must also be
254 * @param int $thumbnail_width
255 * (optional) The width of the thumbnail, in pixels. If this parameter is
256 * present, $thumbnail_url and $thumbnail_height must also be present.
257 * @param int $thumbnail_height
258 * (optional) The height of the thumbnail, in pixels. If this parameter is
259 * present, $thumbnail_url and $thumbnail_width must also be present.
263 public static function photo($url, $width, $height, Provider $provider = NULL, $title = NULL, $author_name = NULL, $author_url = NULL, $cache_age = NULL, $thumbnail_url = NULL, $thumbnail_width = NULL, $thumbnail_height = NULL) {
265 throw new \InvalidArgumentException('Photo resources must provide a URL.');
268 $resource = static::link($url, $provider, $title, $author_name, $author_url, $cache_age, $thumbnail_url, $thumbnail_width, $thumbnail_height);
269 $resource->type = self::TYPE_PHOTO;
270 $resource->setDimensions($width, $height);
276 * Creates a rich resource.
278 * @param string $html
279 * The HTML representation of the resource.
281 * The width of the resource, in pixels.
283 * The height of the resource, in pixels.
284 * @param \Drupal\media\OEmbed\Provider $provider
285 * (optional) The resource provider.
286 * @param string $title
287 * (optional) A text title, describing the resource.
288 * @param string $author_name
289 * (optional) The name of the author/owner of the resource.
290 * @param string $author_url
291 * (optional) A URL for the author/owner of the resource.
292 * @param int $cache_age
293 * (optional) The suggested cache lifetime for this resource, in seconds.
294 * @param string $thumbnail_url
295 * (optional) A URL to a thumbnail image representing the resource. If this
296 * parameter is present, $thumbnail_width and $thumbnail_height must also be
298 * @param int $thumbnail_width
299 * (optional) The width of the thumbnail, in pixels. If this parameter is
300 * present, $thumbnail_url and $thumbnail_height must also be present.
301 * @param int $thumbnail_height
302 * (optional) The height of the thumbnail, in pixels. If this parameter is
303 * present, $thumbnail_url and $thumbnail_width must also be present.
307 public static function rich($html, $width, $height, Provider $provider = NULL, $title = NULL, $author_name = NULL, $author_url = NULL, $cache_age = NULL, $thumbnail_url = NULL, $thumbnail_width = NULL, $thumbnail_height = NULL) {
309 throw new \InvalidArgumentException('The resource must provide an HTML representation.');
312 $resource = new static($provider, $title, $author_name, $author_url, $cache_age, $thumbnail_url, $thumbnail_width, $thumbnail_height);
313 $resource->type = self::TYPE_RICH;
314 $resource->html = $html;
315 $resource->setDimensions($width, $height);
321 * Creates a video resource.
323 * @param string $html
324 * The HTML required to display the video.
326 * The width of the video, in pixels.
328 * The height of the video, in pixels.
329 * @param \Drupal\media\OEmbed\Provider $provider
330 * (optional) The resource provider.
331 * @param string $title
332 * (optional) A text title, describing the resource.
333 * @param string $author_name
334 * (optional) The name of the author/owner of the resource.
335 * @param string $author_url
336 * (optional) A URL for the author/owner of the resource.
337 * @param int $cache_age
338 * (optional) The suggested cache lifetime for this resource, in seconds.
339 * @param string $thumbnail_url
340 * (optional) A URL to a thumbnail image representing the resource. If this
341 * parameter is present, $thumbnail_width and $thumbnail_height must also be
343 * @param int $thumbnail_width
344 * (optional) The width of the thumbnail, in pixels. If this parameter is
345 * present, $thumbnail_url and $thumbnail_height must also be present.
346 * @param int $thumbnail_height
347 * (optional) The height of the thumbnail, in pixels. If this parameter is
348 * present, $thumbnail_url and $thumbnail_width must also be present.
352 public static function video($html, $width, $height, Provider $provider = NULL, $title = NULL, $author_name = NULL, $author_url = NULL, $cache_age = NULL, $thumbnail_url = NULL, $thumbnail_width = NULL, $thumbnail_height = NULL) {
353 $resource = static::rich($html, $width, $height, $provider, $title, $author_name, $author_url, $cache_age, $thumbnail_url, $thumbnail_width, $thumbnail_height);
354 $resource->type = self::TYPE_VIDEO;
360 * Returns the resource type.
363 * The resource type. Will be one of the self::TYPE_* constants.
365 public function getType() {
370 * Returns the title of the resource.
372 * @return string|null
373 * The title of the resource, if known.
375 public function getTitle() {
380 * Returns the name of the resource author.
382 * @return string|null
383 * The name of the resource author, if known.
385 public function getAuthorName() {
386 return $this->authorName;
390 * Returns the URL of the resource author.
392 * @return \Drupal\Core\Url|null
393 * The absolute URL of the resource author, or NULL if none is provided.
395 public function getAuthorUrl() {
396 return $this->authorUrl ? Url::fromUri($this->authorUrl)->setAbsolute() : NULL;
400 * Returns the resource provider, if known.
402 * @return \Drupal\media\OEmbed\Provider|null
403 * The resource provider, or NULL if the provider is not known.
405 public function getProvider() {
406 return $this->provider;
410 * Returns the URL of the resource's thumbnail image.
412 * @return \Drupal\Core\Url|null
413 * The absolute URL of the thumbnail image, or NULL if there isn't one.
415 public function getThumbnailUrl() {
416 return $this->thumbnailUrl ? Url::fromUri($this->thumbnailUrl)->setAbsolute() : NULL;
420 * Returns the width of the resource's thumbnail image.
423 * The thumbnail width in pixels, or NULL if there is no thumbnail.
425 public function getThumbnailWidth() {
426 return $this->thumbnailWidth;
430 * Returns the height of the resource's thumbnail image.
433 * The thumbnail height in pixels, or NULL if there is no thumbnail.
435 public function getThumbnailHeight() {
436 return $this->thumbnailHeight;
440 * Returns the width of the resource.
443 * The width of the resource in pixels, or NULL if the resource has no
446 public function getWidth() {
451 * Returns the height of the resource.
454 * The height of the resource in pixels, or NULL if the resource has no
457 public function getHeight() {
458 return $this->height;
462 * Returns the URL of the resource. Only applies to 'photo' resources.
464 * @return \Drupal\Core\Url|null
465 * The resource URL, if it has one.
467 public function getUrl() {
469 return Url::fromUri($this->url)->setAbsolute();
475 * Returns the HTML representation of the resource.
477 * Only applies to 'rich' and 'video' resources.
479 * @return string|null
480 * The HTML representation of the resource, if it has one.
482 public function getHtml() {
483 return isset($this->html) ? (string) $this->html : NULL;
487 * Sets the thumbnail dimensions.
490 * The width of the resource.
492 * The height of the resource.
494 * @throws \InvalidArgumentException
495 * If either $width or $height are not numbers greater than zero.
497 protected function setThumbnailDimensions($width, $height) {
498 $width = (int) $width;
499 $height = (int) $height;
501 if ($width > 0 && $height > 0) {
502 $this->thumbnailWidth = $width;
503 $this->thumbnailHeight = $height;
506 throw new \InvalidArgumentException('The thumbnail dimensions must be numbers greater than zero.');
511 * Sets the dimensions.
514 * The width of the resource.
516 * The height of the resource.
518 * @throws \InvalidArgumentException
519 * If either $width or $height are not numbers greater than zero.
521 protected function setDimensions($width, $height) {
522 $width = (int) $width;
523 $height = (int) $height;
525 if ($width > 0 && $height > 0) {
526 $this->width = $width;
527 $this->height = $height;
530 throw new \InvalidArgumentException('The dimensions must be numbers greater than zero.');