class JsonApiSpec in Drupal 9

Defines constants used for compliance with the JSON:API specification.

@internal JSON:API maintains no PHP API since its API is the HTTP API. This class may change at any time and this will break any dependencies on it.

Hierarchy

• class \Drupal\jsonapi\JsonApiSpec

See also

https://www.drupal.org/project/drupal/issues/3032787

jsonapi.api.php

http://jsonapi.org/format

7 files declare their use of JsonApiSpec

EntityAccessChecker.php in core/modules/jsonapi/src/Access/EntityAccessChecker.php

EntityReferenceFieldNormalizer.php in core/modules/jsonapi/src/Normalizer/EntityReferenceFieldNormalizer.php

JsonApiDocumentTopLevelNormalizer.php in core/modules/jsonapi/src/Normalizer/JsonApiDocumentTopLevelNormalizer.php

JsonApiRequestValidator.php in core/modules/jsonapi/src/EventSubscriber/JsonApiRequestValidator.php

JsonApiSpecTest.php in core/modules/jsonapi/tests/src/Unit/JsonApiSpecTest.php

... See full list

File

core/modules/jsonapi/src/JsonApiSpec.php, line 16

Namespace

Drupal\jsonapi

class JsonApiSpec {

  /**
   * The minimum supported specification version.
   *
   * @see http://jsonapi.org/format/#document-jsonapi-object
   */
  const SUPPORTED_SPECIFICATION_VERSION = '1.0';

  /**
   * The URI of the supported specification document.
   */
  const SUPPORTED_SPECIFICATION_PERMALINK = 'http://jsonapi.org/format/1.0/';

  /**
   * Member name: globally allowed characters.
   *
   * U+0080 and above (non-ASCII Unicode characters) are allowed, but are not
   * URL-safe. It is RECOMMENDED to not use them.
   *
   * A character class, for use in regular expressions.
   *
   * @see http://jsonapi.org/format/#document-member-names-allowed-characters
   * @see http://php.net/manual/en/regexp.reference.character-classes.php
   */
  const MEMBER_NAME_GLOBALLY_ALLOWED_CHARACTER_CLASS = '[a-zA-Z0-9\\x{80}-\\x{10FFFF}]';

  /**
   * Member name: allowed characters except as the first or last character.
   *
   * Space (U+0020) is allowed, but is not URL-safe. It is RECOMMENDED to not
   * use it.
   *
   * A character class, for use in regular expressions.
   *
   * @see http://jsonapi.org/format/#document-member-names-allowed-characters
   * @see http://php.net/manual/en/regexp.reference.character-classes.php
   */
  const MEMBER_NAME_INNER_ALLOWED_CHARACTERS = "[a-zA-Z0-9\\x{80}-\\x{10FFFF}\\-_ ]";

  /**
   * Regular expression to check the validity of a member name.
   */
  const MEMBER_NAME_REGEXP = '/^' . self::MEMBER_NAME_GLOBALLY_ALLOWED_CHARACTER_CLASS . '{1}(' . self::MEMBER_NAME_INNER_ALLOWED_CHARACTERS . '*' . self::MEMBER_NAME_GLOBALLY_ALLOWED_CHARACTER_CLASS . '{1}' . ')?$/u';

  /**
   * Checks whether the given member name is valid.
   *
   * Requirements:
   * - it MUST contain at least one character.
   * - it MUST contain only the allowed characters
   * - it MUST start and end with a "globally allowed character"
   *
   * @param string $member_name
   *   A member name to validate.
   *
   * @return bool
   *   Whether the given member name is in compliance with the JSON:API
   *   specification.
   *
   * @see http://jsonapi.org/format/#document-member-names
   */
  public static function isValidMemberName($member_name) {
    return preg_match(static::MEMBER_NAME_REGEXP, $member_name) === 1;
  }

  /**
   * The reserved (official) query parameters.
   */
  const RESERVED_QUERY_PARAMETERS = [
    'filter',
    'sort',
    'page',
    'fields',
    'include',
  ];

  /**
   * The query parameter for providing a version (revision) value.
   *
   * @var string
   */
  const VERSION_QUERY_PARAMETER = 'resourceVersion';

  /**
   * Gets the reserved (official) JSON:API query parameters.
   *
   * @return string[]
   *   Gets the query parameters reserved by the specification.
   */
  public static function getReservedQueryParameters() {
    return static::RESERVED_QUERY_PARAMETERS;
  }

  /**
   * Checks whether the given custom query parameter name is valid.
   *
   * A custom query parameter name must be a valid member name, with one
   * additional requirement: it MUST contain at least one non a-z character.
   *
   * Requirements:
   * - it MUST contain at least one character.
   * - it MUST contain only the allowed characters
   * - it MUST start and end with a "globally allowed character"
   * - it MUST contain at least none a-z (U+0061 to U+007A) character
   *
   * It is RECOMMENDED that a hyphen (U+002D), underscore (U+005F) or capital
   * letter is used (i.e. camelCasing).
   *
   * @param string $custom_query_parameter_name
   *   A custom query parameter name to validate.
   *
   * @return bool
   *   Whether the given query parameter is in compliance with the JSON:API
   *   specification.
   *
   * @see http://jsonapi.org/format/#query-parameters
   */
  public static function isValidCustomQueryParameter($custom_query_parameter_name) {
    return static::isValidMemberName($custom_query_parameter_name) && preg_match('/[^a-z]/u', $custom_query_parameter_name) === 1;
  }

}

Members

Name	Modifiers	Type	Description	Overrides
JsonApiSpec::getReservedQueryParameters	public static	function	Gets the reserved (official) JSON:API query parameters.
JsonApiSpec::isValidCustomQueryParameter	public static	function	Checks whether the given custom query parameter name is valid.
JsonApiSpec::isValidMemberName	public static	function	Checks whether the given member name is valid.
JsonApiSpec::MEMBER_NAME_GLOBALLY_ALLOWED_CHARACTER_CLASS		constant	Member name: globally allowed characters.
JsonApiSpec::MEMBER_NAME_INNER_ALLOWED_CHARACTERS		constant	Member name: allowed characters except as the first or last character.
JsonApiSpec::MEMBER_NAME_REGEXP		constant	Regular expression to check the validity of a member name.
JsonApiSpec::RESERVED_QUERY_PARAMETERS		constant	The reserved (official) query parameters.
JsonApiSpec::SUPPORTED_SPECIFICATION_PERMALINK		constant	The URI of the supported specification document.
JsonApiSpec::SUPPORTED_SPECIFICATION_VERSION		constant	The minimum supported specification version.
JsonApiSpec::VERSION_QUERY_PARAMETER		constant	The query parameter for providing a version (revision) value.