aleph1.co.uk Git - yaffs-website/blob - web/core/modules/media/src/OEmbed/Resource.php

   1 <?php
   2
   3 namespace Drupal\media\OEmbed;
   4
   5 use Drupal\Core\Cache\Cache;
   6 use Drupal\Core\Cache\CacheableDependencyInterface;
   7 use Drupal\Core\Cache\CacheableDependencyTrait;
   8 use Drupal\Core\Url;
   9
  10 /**
  11  * Value object representing an oEmbed resource.
  12  *
  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.
  18  *
  19  * Valid resource types are defined in the oEmbed specification and represented
  20  * by the TYPE_* constants in this class.
  21  *
  22  * @see https://oembed.com/#section2
  23  *
  24  * @internal
  25  *   This class is an internal part of the oEmbed system and should only be
  26  *   instantiated by
  27  *   \Drupal\media\OEmbed\ResourceFetcherInterface::fetchResource().
  28  */
  29 class Resource implements CacheableDependencyInterface {
  30
  31   use CacheableDependencyTrait;
  32
  33   /**
  34    * The resource type for link resources.
  35    */
  36   const TYPE_LINK = 'link';
  37
  38   /**
  39    * The resource type for photo resources.
  40    */
  41   const TYPE_PHOTO = 'photo';
  42
  43   /**
  44    * The resource type for rich resources.
  45    */
  46   const TYPE_RICH = 'rich';
  47
  48   /**
  49    * The resource type for video resources.
  50    */
  51   const TYPE_VIDEO = 'video';
  52
  53   /**
  54    * The resource type. Can be one of the static::TYPE_* constants.
  55    *
  56    * @var string
  57    */
  58   protected $type;
  59
  60   /**
  61    * The resource provider.
  62    *
  63    * @var \Drupal\media\OEmbed\Provider
  64    */
  65   protected $provider;
  66
  67   /**
  68    * A text title, describing the resource.
  69    *
  70    * @var string
  71    */
  72   protected $title;
  73
  74   /**
  75    * The name of the author/owner of the resource.
  76    *
  77    * @var string
  78    */
  79   protected $authorName;
  80
  81   /**
  82    * A URL for the author/owner of the resource.
  83    *
  84    * @var string
  85    */
  86   protected $authorUrl;
  87
  88   /**
  89    * A URL to a thumbnail image representing the resource.
  90    *
  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.
  94    *
  95    * @var string
  96    *
  97    * @see \Drupal\media\OEmbed\UrlResolverInterface::getResourceUrl()
  98    * @see https://oembed.com/#section2
  99    */
 100   protected $thumbnailUrl;
 101
 102   /**
 103    * The width of the thumbnail, in pixels.
 104    *
 105    * If this parameter is present, thumbnail_url and thumbnail_height must also
 106    * be present.
 107    *
 108    * @var int
 109    */
 110   protected $thumbnailWidth;
 111
 112   /**
 113    * The height of the thumbnail, in pixels.
 114    *
 115    * If this parameter is present, thumbnail_url and thumbnail_width must also
 116    * be present.
 117    *
 118    * @var int
 119    */
 120   protected $thumbnailHeight;
 121
 122   /**
 123    * The width of the resource, in pixels.
 124    *
 125    * @var int
 126    */
 127   protected $width;
 128
 129   /**
 130    * The height of the resource, in pixels.
 131    *
 132    * @var int
 133    */
 134   protected $height;
 135
 136   /**
 137    * The resource URL. Only applies to 'photo' and 'link' resources.
 138    *
 139    * @var string
 140    */
 141   protected $url;
 142
 143   /**
 144    * The HTML representation of the resource.
 145    *
 146    * Only applies to 'rich' and 'video' resources.
 147    *
 148    * @var string
 149    */
 150   protected $html;
 151
 152   /**
 153    * Resource constructor.
 154    *
 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
 168    *   present.
 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.
 175    */
 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;
 181
 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);
 187     }
 188
 189     if ($thumbnail_url) {
 190       $this->thumbnailUrl = $thumbnail_url;
 191       $this->setThumbnailDimensions($thumbnail_width, $thumbnail_height);
 192     }
 193   }
 194
 195   /**
 196    * Creates a link resource.
 197    *
 198    * @param string $url
 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
 213    *   present.
 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.
 220    *
 221    * @return static
 222    */
 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;
 227
 228     return $resource;
 229   }
 230
 231   /**
 232    * Creates a photo resource.
 233    *
 234    * @param string $url
 235    *   The URL of the photo.
 236    * @param int $width
 237    *   The width of the photo, in pixels.
 238    * @param int $height
 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
 253    *   present.
 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.
 260    *
 261    * @return static
 262    */
 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) {
 264     if (empty($url)) {
 265       throw new \InvalidArgumentException('Photo resources must provide a URL.');
 266     }
 267
 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);
 271
 272     return $resource;
 273   }
 274
 275   /**
 276    * Creates a rich resource.
 277    *
 278    * @param string $html
 279    *   The HTML representation of the resource.
 280    * @param int $width
 281    *   The width of the resource, in pixels.
 282    * @param int $height
 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
 297    *   present.
 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.
 304    *
 305    * @return static
 306    */
 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) {
 308     if (empty($html)) {
 309       throw new \InvalidArgumentException('The resource must provide an HTML representation.');
 310     }
 311
 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);
 316
 317     return $resource;
 318   }
 319
 320   /**
 321    * Creates a video resource.
 322    *
 323    * @param string $html
 324    *   The HTML required to display the video.
 325    * @param int $width
 326    *   The width of the video, in pixels.
 327    * @param int $height
 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
 342    *   present.
 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.
 349    *
 350    * @return static
 351    */
 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;
 355
 356     return $resource;
 357   }
 358
 359   /**
 360    * Returns the resource type.
 361    *
 362    * @return string
 363    *   The resource type. Will be one of the self::TYPE_* constants.
 364    */
 365   public function getType() {
 366     return $this->type;
 367   }
 368
 369   /**
 370    * Returns the title of the resource.
 371    *
 372    * @return string|null
 373    *   The title of the resource, if known.
 374    */
 375   public function getTitle() {
 376     return $this->title;
 377   }
 378
 379   /**
 380    * Returns the name of the resource author.
 381    *
 382    * @return string|null
 383    *   The name of the resource author, if known.
 384    */
 385   public function getAuthorName() {
 386     return $this->authorName;
 387   }
 388
 389   /**
 390    * Returns the URL of the resource author.
 391    *
 392    * @return \Drupal\Core\Url|null
 393    *   The absolute URL of the resource author, or NULL if none is provided.
 394    */
 395   public function getAuthorUrl() {
 396     return $this->authorUrl ? Url::fromUri($this->authorUrl)->setAbsolute() : NULL;
 397   }
 398
 399   /**
 400    * Returns the resource provider, if known.
 401    *
 402    * @return \Drupal\media\OEmbed\Provider|null
 403    *   The resource provider, or NULL if the provider is not known.
 404    */
 405   public function getProvider() {
 406     return $this->provider;
 407   }
 408
 409   /**
 410    * Returns the URL of the resource's thumbnail image.
 411    *
 412    * @return \Drupal\Core\Url|null
 413    *   The absolute URL of the thumbnail image, or NULL if there isn't one.
 414    */
 415   public function getThumbnailUrl() {
 416     return $this->thumbnailUrl ? Url::fromUri($this->thumbnailUrl)->setAbsolute() : NULL;
 417   }
 418
 419   /**
 420    * Returns the width of the resource's thumbnail image.
 421    *
 422    * @return int|null
 423    *   The thumbnail width in pixels, or NULL if there is no thumbnail.
 424    */
 425   public function getThumbnailWidth() {
 426     return $this->thumbnailWidth;
 427   }
 428
 429   /**
 430    * Returns the height of the resource's thumbnail image.
 431    *
 432    * @return int|null
 433    *   The thumbnail height in pixels, or NULL if there is no thumbnail.
 434    */
 435   public function getThumbnailHeight() {
 436     return $this->thumbnailHeight;
 437   }
 438
 439   /**
 440    * Returns the width of the resource.
 441    *
 442    * @return int|null
 443    *   The width of the resource in pixels, or NULL if the resource has no
 444    *   dimensions
 445    */
 446   public function getWidth() {
 447     return $this->width;
 448   }
 449
 450   /**
 451    * Returns the height of the resource.
 452    *
 453    * @return int|null
 454    *   The height of the resource in pixels, or NULL if the resource has no
 455    *   dimensions.
 456    */
 457   public function getHeight() {
 458     return $this->height;
 459   }
 460
 461   /**
 462    * Returns the URL of the resource. Only applies to 'photo' resources.
 463    *
 464    * @return \Drupal\Core\Url|null
 465    *   The resource URL, if it has one.
 466    */
 467   public function getUrl() {
 468     if ($this->url) {
 469       return Url::fromUri($this->url)->setAbsolute();
 470     }
 471     return NULL;
 472   }
 473
 474   /**
 475    * Returns the HTML representation of the resource.
 476    *
 477    * Only applies to 'rich' and 'video' resources.
 478    *
 479    * @return string|null
 480    *   The HTML representation of the resource, if it has one.
 481    */
 482   public function getHtml() {
 483     return isset($this->html) ? (string) $this->html : NULL;
 484   }
 485
 486   /**
 487    * Sets the thumbnail dimensions.
 488    *
 489    * @param int $width
 490    *   The width of the resource.
 491    * @param int $height
 492    *   The height of the resource.
 493    *
 494    * @throws \InvalidArgumentException
 495    *   If either $width or $height are not numbers greater than zero.
 496    */
 497   protected function setThumbnailDimensions($width, $height) {
 498     $width = (int) $width;
 499     $height = (int) $height;
 500
 501     if ($width > 0 && $height > 0) {
 502       $this->thumbnailWidth = $width;
 503       $this->thumbnailHeight = $height;
 504     }
 505     else {
 506       throw new \InvalidArgumentException('The thumbnail dimensions must be numbers greater than zero.');
 507     }
 508   }
 509
 510   /**
 511    * Sets the dimensions.
 512    *
 513    * @param int $width
 514    *   The width of the resource.
 515    * @param int $height
 516    *   The height of the resource.
 517    *
 518    * @throws \InvalidArgumentException
 519    *   If either $width or $height are not numbers greater than zero.
 520    */
 521   protected function setDimensions($width, $height) {
 522     $width = (int) $width;
 523     $height = (int) $height;
 524
 525     if ($width > 0 && $height > 0) {
 526       $this->width = $width;
 527       $this->height = $height;
 528     }
 529     else {
 530       throw new \InvalidArgumentException('The dimensions must be numbers greater than zero.');
 531     }
 532   }
 533
 534 }