annotate core/modules/jsonapi/src/JsonApiResource/JsonApiDocumentTopLevel.php @ 19:fa3358dc1485 tip

Add ndrum files
author Chris Cannam
date Wed, 28 Aug 2019 13:14:47 +0100
parents af1871eacc83
children
rev   line source
Chris@18 1 <?php
Chris@18 2
Chris@18 3 namespace Drupal\jsonapi\JsonApiResource;
Chris@18 4
Chris@18 5 use Drupal\Core\Field\EntityReferenceFieldItemListInterface;
Chris@18 6
Chris@18 7 /**
Chris@18 8 * Represents a JSON:API document's "top level".
Chris@18 9 *
Chris@18 10 * @internal JSON:API maintains no PHP API. The API is the HTTP API. This class
Chris@18 11 * may change at any time and could break any dependencies on it.
Chris@18 12 *
Chris@18 13 * @see https://www.drupal.org/project/jsonapi/issues/3032787
Chris@18 14 * @see jsonapi.api.php
Chris@18 15 *
Chris@18 16 * @see http://jsonapi.org/format/#document-top-level
Chris@18 17 *
Chris@18 18 * @todo Add support for the missing optional 'jsonapi' member or document why not.
Chris@18 19 */
Chris@18 20 class JsonApiDocumentTopLevel {
Chris@18 21
Chris@18 22 /**
Chris@18 23 * The data to normalize.
Chris@18 24 *
Chris@18 25 * @var \Drupal\jsonapi\JsonApiResource\ResourceIdentifierInterface|\Drupal\jsonapi\JsonApiResource\Data|\Drupal\jsonapi\JsonApiResource\ErrorCollection|\Drupal\Core\Field\EntityReferenceFieldItemListInterface
Chris@18 26 */
Chris@18 27 protected $data;
Chris@18 28
Chris@18 29 /**
Chris@18 30 * The metadata to normalize.
Chris@18 31 *
Chris@18 32 * @var array
Chris@18 33 */
Chris@18 34 protected $meta;
Chris@18 35
Chris@18 36 /**
Chris@18 37 * The links.
Chris@18 38 *
Chris@18 39 * @var \Drupal\jsonapi\JsonApiResource\LinkCollection
Chris@18 40 */
Chris@18 41 protected $links;
Chris@18 42
Chris@18 43 /**
Chris@18 44 * The includes to normalize.
Chris@18 45 *
Chris@18 46 * @var \Drupal\jsonapi\JsonApiResource\IncludedData
Chris@18 47 */
Chris@18 48 protected $includes;
Chris@18 49
Chris@18 50 /**
Chris@18 51 * Resource objects that will be omitted from the response for access reasons.
Chris@18 52 *
Chris@18 53 * @var \Drupal\jsonapi\JsonApiResource\OmittedData
Chris@18 54 */
Chris@18 55 protected $omissions;
Chris@18 56
Chris@18 57 /**
Chris@18 58 * Instantiates a JsonApiDocumentTopLevel object.
Chris@18 59 *
Chris@18 60 * @param \Drupal\jsonapi\JsonApiResource\ResourceIdentifierInterface|\Drupal\jsonapi\JsonApiResource\Data|\Drupal\jsonapi\JsonApiResource\ErrorCollection|\Drupal\Core\Field\EntityReferenceFieldItemListInterface $data
Chris@18 61 * The data to normalize. It can be either a ResourceObject, or a stand-in
Chris@18 62 * for one, or a collection of the same.
Chris@18 63 * @param \Drupal\jsonapi\JsonApiResource\IncludedData $includes
Chris@18 64 * A JSON:API Data object containing resources to be included in the
Chris@18 65 * response document or NULL if there should not be includes.
Chris@18 66 * @param \Drupal\jsonapi\JsonApiResource\LinkCollection $links
Chris@18 67 * A collection of links to resources related to the top-level document.
Chris@18 68 * @param array $meta
Chris@18 69 * (optional) The metadata to normalize.
Chris@18 70 */
Chris@18 71 public function __construct($data, IncludedData $includes, LinkCollection $links, array $meta = []) {
Chris@18 72 assert($data instanceof ResourceIdentifierInterface || $data instanceof Data || $data instanceof ErrorCollection || $data instanceof EntityReferenceFieldItemListInterface);
Chris@18 73 assert(!$data instanceof ErrorCollection || $includes instanceof NullIncludedData);
Chris@18 74 $this->data = $data instanceof ResourceObjectData ? $data->getAccessible() : $data;
Chris@18 75 $this->includes = $includes->getAccessible();
Chris@18 76 $this->links = $links->withContext($this);
Chris@18 77 $this->meta = $meta;
Chris@18 78 $this->omissions = $data instanceof ResourceObjectData
Chris@18 79 ? OmittedData::merge($data->getOmissions(), $includes->getOmissions())
Chris@18 80 : $includes->getOmissions();
Chris@18 81 }
Chris@18 82
Chris@18 83 /**
Chris@18 84 * Gets the data.
Chris@18 85 *
Chris@18 86 * @return \Drupal\jsonapi\JsonApiResource\ResourceObject|\Drupal\jsonapi\JsonApiResource\Data|\Drupal\jsonapi\JsonApiResource\LabelOnlyResourceObject|\Drupal\jsonapi\JsonApiResource\ErrorCollection
Chris@18 87 * The data.
Chris@18 88 */
Chris@18 89 public function getData() {
Chris@18 90 return $this->data;
Chris@18 91 }
Chris@18 92
Chris@18 93 /**
Chris@18 94 * Gets the links.
Chris@18 95 *
Chris@18 96 * @return \Drupal\jsonapi\JsonApiResource\LinkCollection
Chris@18 97 * The top-level links.
Chris@18 98 */
Chris@18 99 public function getLinks() {
Chris@18 100 return $this->links;
Chris@18 101 }
Chris@18 102
Chris@18 103 /**
Chris@18 104 * Gets the metadata.
Chris@18 105 *
Chris@18 106 * @return array
Chris@18 107 * The metadata.
Chris@18 108 */
Chris@18 109 public function getMeta() {
Chris@18 110 return $this->meta;
Chris@18 111 }
Chris@18 112
Chris@18 113 /**
Chris@18 114 * Gets a JSON:API Data object of resources to be included in the response.
Chris@18 115 *
Chris@18 116 * @return \Drupal\jsonapi\JsonApiResource\IncludedData
Chris@18 117 * The includes.
Chris@18 118 */
Chris@18 119 public function getIncludes() {
Chris@18 120 return $this->includes;
Chris@18 121 }
Chris@18 122
Chris@18 123 /**
Chris@18 124 * Gets an OmittedData instance containing resources to be omitted.
Chris@18 125 *
Chris@18 126 * @return \Drupal\jsonapi\JsonApiResource\OmittedData
Chris@18 127 * The omissions.
Chris@18 128 */
Chris@18 129 public function getOmissions() {
Chris@18 130 return $this->omissions;
Chris@18 131 }
Chris@18 132
Chris@18 133 }