Chris@18: <?php
Chris@18: 
Chris@18: namespace Drupal\jsonapi\JsonApiResource;
Chris@18: 
Chris@18: use Drupal\Component\Assertion\Inspector;
Chris@18: use Drupal\Core\Cache\CacheableDependencyInterface;
Chris@18: use Drupal\Core\Cache\CacheableDependencyTrait;
Chris@18: use Drupal\Core\Cache\CacheableMetadata;
Chris@18: use Drupal\Core\Url;
Chris@18: 
Chris@18: /**
Chris@18:  * Represents an RFC8288 based link.
Chris@18:  *
Chris@18:  * @internal JSON:API maintains no PHP API. The API is the HTTP API. This class
Chris@18:  *   may change at any time and could break any dependencies on it.
Chris@18:  *
Chris@18:  * @see https://www.drupal.org/project/jsonapi/issues/3032787
Chris@18:  * @see jsonapi.api.php
Chris@18:  *
Chris@18:  * @see https://tools.ietf.org/html/rfc8288
Chris@18:  */
Chris@18: final class Link implements CacheableDependencyInterface {
Chris@18: 
Chris@18:   use CacheableDependencyTrait;
Chris@18: 
Chris@18:   /**
Chris@18:    * The link URI.
Chris@18:    *
Chris@18:    * @var \Drupal\Core\Url
Chris@18:    */
Chris@18:   protected $uri;
Chris@18: 
Chris@18:   /**
Chris@18:    * The URI, as a string.
Chris@18:    *
Chris@18:    * @var string
Chris@18:    */
Chris@18:   protected $href;
Chris@18: 
Chris@18:   /**
Chris@18:    * The link relation types.
Chris@18:    *
Chris@18:    * @var string[]
Chris@18:    */
Chris@18:   protected $rel;
Chris@18: 
Chris@18:   /**
Chris@18:    * The link target attributes.
Chris@18:    *
Chris@18:    * @var string[]
Chris@18:    *   An associative array where the keys are the attribute keys and values are
Chris@18:    *   either string or an array of strings.
Chris@18:    */
Chris@18:   protected $attributes;
Chris@18: 
Chris@18:   /**
Chris@18:    * JSON:API Link constructor.
Chris@18:    *
Chris@18:    * @param \Drupal\Core\Cache\CacheableMetadata $cacheability
Chris@18:    *   Any cacheability metadata associated with the link. For example, a
Chris@18:    *   'call-to-action' link might reference a registration resource if an event
Chris@18:    *   has vacancies or a wait-list resource otherwise. Therefore, the link's
Chris@18:    *   cacheability might be depend on a certain entity's values other than the
Chris@18:    *   entity on which the link will appear.
Chris@18:    * @param \Drupal\Core\Url $url
Chris@18:    *   The Url object for the link.
Chris@18:    * @param string[] $link_relation_types
Chris@18:    *   An array of registered or extension RFC8288 link relation types.
Chris@18:    * @param array $target_attributes
Chris@18:    *   An associative array of target attributes for the link.
Chris@18:    *
Chris@18:    * @see https://tools.ietf.org/html/rfc8288#section-2.1
Chris@18:    */
Chris@18:   public function __construct(CacheableMetadata $cacheability, Url $url, array $link_relation_types, array $target_attributes = []) {
Chris@18:     // @todo: uncomment the extra assertion below when JSON:API begins to use its own extension relation types.
Chris@18:     assert(/* !empty($link_relation_types) && */Inspector::assertAllStrings($link_relation_types));
Chris@18:     assert(Inspector::assertAllStrings(array_keys($target_attributes)));
Chris@18:     assert(Inspector::assertAll(function ($target_attribute_value) {
Chris@18:       return is_string($target_attribute_value)
Chris@18:         || is_array($target_attribute_value)
Chris@18:         && Inspector::assertAllStrings($target_attribute_value);
Chris@18:     }, array_values($target_attributes)));
Chris@18:     $generated_url = $url->setAbsolute()->toString(TRUE);
Chris@18:     $this->href = $generated_url->getGeneratedUrl();
Chris@18:     $this->uri = $url;
Chris@18:     $this->rel = $link_relation_types;
Chris@18:     $this->attributes = $target_attributes;
Chris@18:     $this->setCacheability($cacheability->addCacheableDependency($generated_url));
Chris@18:   }
Chris@18: 
Chris@18:   /**
Chris@18:    * Gets the link's URI.
Chris@18:    *
Chris@18:    * @return \Drupal\Core\Url
Chris@18:    *   The link's URI as a Url object.
Chris@18:    */
Chris@18:   public function getUri() {
Chris@18:     return $this->uri;
Chris@18:   }
Chris@18: 
Chris@18:   /**
Chris@18:    * Gets the link's URI as a string.
Chris@18:    *
Chris@18:    * @return string
Chris@18:    *   The link's URI as a string.
Chris@18:    */
Chris@18:   public function getHref() {
Chris@18:     return $this->href;
Chris@18:   }
Chris@18: 
Chris@18:   /**
Chris@18:    * Gets the link's relation types.
Chris@18:    *
Chris@18:    * @return string[]
Chris@18:    *   The link's relation types.
Chris@18:    */
Chris@18:   public function getLinkRelationTypes() {
Chris@18:     return $this->rel;
Chris@18:   }
Chris@18: 
Chris@18:   /**
Chris@18:    * Gets the link's target attributes.
Chris@18:    *
Chris@18:    * @return string[]
Chris@18:    *   The link's target attributes.
Chris@18:    */
Chris@18:   public function getTargetAttributes() {
Chris@18:     return $this->attributes;
Chris@18:   }
Chris@18: 
Chris@18:   /**
Chris@18:    * Compares two links by their href.
Chris@18:    *
Chris@18:    * @param \Drupal\jsonapi\JsonApiResource\Link $a
Chris@18:    *   The first link.
Chris@18:    * @param \Drupal\jsonapi\JsonApiResource\Link $b
Chris@18:    *   The second link.
Chris@18:    *
Chris@18:    * @return int
Chris@18:    *   The result of strcmp() on the links' hrefs.
Chris@18:    */
Chris@18:   public static function compare(Link $a, Link $b) {
Chris@18:     return strcmp($a->getHref(), $b->getHref());
Chris@18:   }
Chris@18: 
Chris@18:   /**
Chris@18:    * Merges two link objects' relation types and target attributes.
Chris@18:    *
Chris@18:    * The links must share the same URI.
Chris@18:    *
Chris@18:    * @param \Drupal\jsonapi\JsonApiResource\Link $a
Chris@18:    *   The first link.
Chris@18:    * @param \Drupal\jsonapi\JsonApiResource\Link $b
Chris@18:    *   The second link.
Chris@18:    *
Chris@18:    * @return static
Chris@18:    *   A new JSON:API Link object with the link relation type and target
Chris@18:    *   attributes merged.
Chris@18:    */
Chris@18:   public static function merge(Link $a, Link $b) {
Chris@18:     assert(static::compare($a, $b) === 0);
Chris@18:     $merged_rels = array_unique(array_merge($a->getLinkRelationTypes(), $b->getLinkRelationTypes()));
Chris@18:     $merged_attributes = $a->getTargetAttributes();
Chris@18:     foreach ($b->getTargetAttributes() as $key => $value) {
Chris@18:       if (isset($merged_attributes[$key])) {
Chris@18:         // The attribute values can be either a string or an array of strings.
Chris@18:         $value = array_unique(array_merge(
Chris@18:           is_string($merged_attributes[$key]) ? [$merged_attributes[$key]] : $merged_attributes[$key],
Chris@18:           is_string($value) ? [$value] : $value
Chris@18:         ));
Chris@18:       }
Chris@18:       $merged_attributes[$key] = count($value) === 1 ? reset($value) : $value;
Chris@18:     }
Chris@18:     $merged_cacheability = (new CacheableMetadata())->addCacheableDependency($a)->addCacheableDependency($b);
Chris@18:     return new static($merged_cacheability, $a->getUri(), $merged_rels, $merged_attributes);
Chris@18:   }
Chris@18: 
Chris@18: }