class JsonApiSpec

Same name in other branches
  1. 9 core/modules/jsonapi/src/JsonApiSpec.php \Drupal\jsonapi\JsonApiSpec
  2. 8.9.x core/modules/jsonapi/src/JsonApiSpec.php \Drupal\jsonapi\JsonApiSpec
  3. 11.x core/modules/jsonapi/src/JsonApiSpec.php \Drupal\jsonapi\JsonApiSpec

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

Expanded class hierarchy of 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
View source
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

Title Sort descending Modifiers Object type Summary
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.

Buggy or inaccurate documentation? Please file an issue. Need support? Need help programming? Connect with the Drupal community.