Chris@18: <?php
Chris@18: 
Chris@18: namespace Drupal\jsonapi\JsonApiResource;
Chris@18: 
Chris@18: use Drupal\Component\Assertion\Inspector;
Chris@18: use Drupal\jsonapi\Exception\EntityAccessDeniedHttpException;
Chris@18: 
Chris@18: /**
Chris@18:  * Represents the `data` and `included` objects of a top-level object.
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: abstract class Data implements \IteratorAggregate, \Countable {
Chris@18: 
Chris@18:   /**
Chris@18:    * Various representations of JSON:API objects.
Chris@18:    *
Chris@18:    * @var \Drupal\jsonapi\JsonApiResource\ResourceIdentifierInterface[]
Chris@18:    */
Chris@18:   protected $data;
Chris@18: 
Chris@18:   /**
Chris@18:    * The number of resources permitted in this collection.
Chris@18:    *
Chris@18:    * @var int
Chris@18:    */
Chris@18:   protected $cardinality;
Chris@18: 
Chris@18:   /**
Chris@18:    * Holds a boolean indicating if there is a next page.
Chris@18:    *
Chris@18:    * @var bool
Chris@18:    */
Chris@18:   protected $hasNextPage;
Chris@18: 
Chris@18:   /**
Chris@18:    * Holds the total count of entities.
Chris@18:    *
Chris@18:    * @var int
Chris@18:    */
Chris@18:   protected $count;
Chris@18: 
Chris@18:   /**
Chris@18:    * Instantiates a Data object.
Chris@18:    *
Chris@18:    * @param \Drupal\jsonapi\JsonApiResource\ResourceIdentifierInterface[] $data
Chris@18:    *   The resources or resource identifiers for the collection.
Chris@18:    * @param int $cardinality
Chris@18:    *   The number of resources that this collection may contain. Related
Chris@18:    *   resource collections may handle both to-one or to-many relationships. A
Chris@18:    *   to-one relationship should have a cardinality of 1. Use -1 for unlimited
Chris@18:    *   cardinality.
Chris@18:    */
Chris@18:   public function __construct(array $data, $cardinality = -1) {
Chris@18:     assert(Inspector::assertAllObjects($data, ResourceIdentifierInterface::class));
Chris@18:     assert($cardinality >= -1 && $cardinality !== 0, 'Cardinality must be -1 for unlimited cardinality or a positive integer.');
Chris@18:     assert($cardinality === -1 || count($data) <= $cardinality, 'If cardinality is not unlimited, the number of given resources must not exceed the cardinality of the collection.');
Chris@18:     $this->data = array_values($data);
Chris@18:     $this->cardinality = $cardinality;
Chris@18:   }
Chris@18: 
Chris@18:   /**
Chris@18:    * Returns an iterator for entities.
Chris@18:    *
Chris@18:    * @return \ArrayIterator
Chris@18:    *   An \ArrayIterator instance
Chris@18:    */
Chris@18:   public function getIterator() {
Chris@18:     return new \ArrayIterator($this->data);
Chris@18:   }
Chris@18: 
Chris@18:   /**
Chris@18:    * Returns the number of entities.
Chris@18:    *
Chris@18:    * @return int
Chris@18:    *   The number of parameters
Chris@18:    */
Chris@18:   public function count() {
Chris@18:     return count($this->data);
Chris@18:   }
Chris@18: 
Chris@18:   /**
Chris@18:    * {@inheritdoc}
Chris@18:    */
Chris@18:   public function getTotalCount() {
Chris@18:     return $this->count;
Chris@18:   }
Chris@18: 
Chris@18:   /**
Chris@18:    * {@inheritdoc}
Chris@18:    */
Chris@18:   public function setTotalCount($count) {
Chris@18:     $this->count = $count;
Chris@18:   }
Chris@18: 
Chris@18:   /**
Chris@18:    * Returns the collection as an array.
Chris@18:    *
Chris@18:    * @return \Drupal\Core\Entity\EntityInterface[]
Chris@18:    *   The array of entities.
Chris@18:    */
Chris@18:   public function toArray() {
Chris@18:     return $this->data;
Chris@18:   }
Chris@18: 
Chris@18:   /**
Chris@18:    * Checks if there is a next page in the collection.
Chris@18:    *
Chris@18:    * @return bool
Chris@18:    *   TRUE if the collection has a next page.
Chris@18:    */
Chris@18:   public function hasNextPage() {
Chris@18:     return (bool) $this->hasNextPage;
Chris@18:   }
Chris@18: 
Chris@18:   /**
Chris@18:    * Sets the has next page flag.
Chris@18:    *
Chris@18:    * Once the collection query has been executed and we build the entity
Chris@18:    * collection, we now if there will be a next page with extra entities.
Chris@18:    *
Chris@18:    * @param bool $has_next_page
Chris@18:    *   TRUE if the collection has a next page.
Chris@18:    */
Chris@18:   public function setHasNextPage($has_next_page) {
Chris@18:     $this->hasNextPage = (bool) $has_next_page;
Chris@18:   }
Chris@18: 
Chris@18:   /**
Chris@18:    * Gets the cardinality of this collection.
Chris@18:    *
Chris@18:    * @return int
Chris@18:    *   The cardinality of the resource collection. -1 for unlimited cardinality.
Chris@18:    */
Chris@18:   public function getCardinality() {
Chris@18:     return $this->cardinality;
Chris@18:   }
Chris@18: 
Chris@18:   /**
Chris@18:    * Returns a new Data object containing the entities of $this and $other.
Chris@18:    *
Chris@18:    * @param \Drupal\jsonapi\JsonApiResource\Data $a
Chris@18:    *   A Data object object to be merged.
Chris@18:    * @param \Drupal\jsonapi\JsonApiResource\Data $b
Chris@18:    *   A Data object to be merged.
Chris@18:    *
Chris@18:    * @return \Drupal\jsonapi\JsonApiResource\Data
Chris@18:    *   A new merged Data object.
Chris@18:    */
Chris@18:   public static function merge(Data $a, Data $b) {
Chris@18:     return new static(array_merge($a->toArray(), $b->toArray()));
Chris@18:   }
Chris@18: 
Chris@18:   /**
Chris@18:    * Returns a new, deduplicated Data object.
Chris@18:    *
Chris@18:    * @param \Drupal\jsonapi\JsonApiResource\Data $collection
Chris@18:    *   The Data object to deduplicate.
Chris@18:    *
Chris@18:    * @return static
Chris@18:    *   A new merged Data object.
Chris@18:    */
Chris@18:   public static function deduplicate(Data $collection) {
Chris@18:     $deduplicated = [];
Chris@18:     foreach ($collection as $resource) {
Chris@18:       $dedupe_key = $resource->getTypeName() . ':' . $resource->getId();
Chris@18:       if ($resource instanceof EntityAccessDeniedHttpException && ($error = $resource->getError()) && !is_null($error['relationship_field'])) {
Chris@18:         $dedupe_key .= ':' . $error['relationship_field'];
Chris@18:       }
Chris@18:       $deduplicated[$dedupe_key] = $resource;
Chris@18:     }
Chris@18:     return new static(array_values($deduplicated));
Chris@18:   }
Chris@18: 
Chris@18: }