Chris@18: <?php
Chris@18: 
Chris@18: namespace Drupal\jsonapi;
Chris@18: 
Chris@18: /**
Chris@18:  * Defines constants used for compliance with the JSON:API specification.
Chris@18:  *
Chris@18:  * @internal JSON:API maintains no PHP API since its API is the HTTP API. This
Chris@18:  *   class may change at any time and this will 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 http://jsonapi.org/format
Chris@18:  */
Chris@18: class JsonApiSpec {
Chris@18: 
Chris@18:   /**
Chris@18:    * The minimum supported specification version.
Chris@18:    *
Chris@18:    * @see http://jsonapi.org/format/#document-jsonapi-object
Chris@18:    */
Chris@18:   const SUPPORTED_SPECIFICATION_VERSION = '1.0';
Chris@18: 
Chris@18:   /**
Chris@18:    * The URI of the supported specification document.
Chris@18:    */
Chris@18:   const SUPPORTED_SPECIFICATION_PERMALINK = 'http://jsonapi.org/format/1.0/';
Chris@18: 
Chris@18:   /**
Chris@18:    * Member name: globally allowed characters.
Chris@18:    *
Chris@18:    * U+0080 and above (non-ASCII Unicode characters) are allowed, but are not
Chris@18:    * URL-safe. It is RECOMMENDED to not use them.
Chris@18:    *
Chris@18:    * A character class, for use in regular expressions.
Chris@18:    *
Chris@18:    * @see http://jsonapi.org/format/#document-member-names-allowed-characters
Chris@18:    * @see http://php.net/manual/en/regexp.reference.character-classes.php
Chris@18:    */
Chris@18:   const MEMBER_NAME_GLOBALLY_ALLOWED_CHARACTER_CLASS = '[a-zA-Z0-9\x{80}-\x{10FFFF}]';
Chris@18: 
Chris@18:   /**
Chris@18:    * Member name: allowed characters except as the first or last character.
Chris@18:    *
Chris@18:    * Space (U+0020) is allowed, but is not URL-safe. It is RECOMMENDED to not
Chris@18:    * use it.
Chris@18:    *
Chris@18:    * A character class, for use in regular expressions.
Chris@18:    *
Chris@18:    * @see http://jsonapi.org/format/#document-member-names-allowed-characters
Chris@18:    * @see http://php.net/manual/en/regexp.reference.character-classes.php
Chris@18:    */
Chris@18:   const MEMBER_NAME_INNER_ALLOWED_CHARACTERS = "[a-zA-Z0-9\x{80}-\x{10FFFF}\-_ ]";
Chris@18: 
Chris@18:   /**
Chris@18:    * Checks whether the given member name is valid.
Chris@18:    *
Chris@18:    * Requirements:
Chris@18:    * - it MUST contain at least one character.
Chris@18:    * - it MUST contain only the allowed characters
Chris@18:    * - it MUST start and end with a "globally allowed character"
Chris@18:    *
Chris@18:    * @param string $member_name
Chris@18:    *   A member name to validate.
Chris@18:    *
Chris@18:    * @return bool
Chris@18:    *   Whether the given member name is in compliance with the JSON:API
Chris@18:    *   specification.
Chris@18:    *
Chris@18:    * @see http://jsonapi.org/format/#document-member-names
Chris@18:    */
Chris@18:   public static function isValidMemberName($member_name) {
Chris@18:     // @todo When D8 requires PHP >=5.6, move to a MEMBER_NAME_REGEXP constant.
Chris@18:     static $regexp;
Chris@18:     // @codingStandardsIgnoreStart
Chris@18:     if (!isset($regexp)) {
Chris@18:       $regexp = '/^' .
Chris@18:         // First character must be "globally allowed". Length must be >=1.
Chris@18:         self::MEMBER_NAME_GLOBALLY_ALLOWED_CHARACTER_CLASS . '{1}' .
Chris@18:         '(' .
Chris@18:           // As many non-globally allowed characters as desired.
Chris@18:           self::MEMBER_NAME_INNER_ALLOWED_CHARACTERS . '*' .
Chris@18:           // If length > 1, then it must end in a "globally allowed" character.
Chris@18:           self::MEMBER_NAME_GLOBALLY_ALLOWED_CHARACTER_CLASS . '{1}' .
Chris@18:         // >1 characters is optional.
Chris@18:         ')?' .
Chris@18:         '$/u';
Chris@18:     }
Chris@18:     // @codingStandardsIgnoreEnd
Chris@18: 
Chris@18:     return preg_match($regexp, $member_name) === 1;
Chris@18:   }
Chris@18: 
Chris@18:   /**
Chris@18:    * The reserved (official) query parameters.
Chris@18:    *
Chris@18:    * @todo When D8 requires PHP >= 5.6, convert to an array.
Chris@18:    */
Chris@18:   const RESERVED_QUERY_PARAMETERS = 'filter|sort|page|fields|include';
Chris@18: 
Chris@18:   /**
Chris@18:    * The query parameter for providing a version (revision) value.
Chris@18:    *
Chris@18:    * @var string
Chris@18:    */
Chris@18:   const VERSION_QUERY_PARAMETER = 'resourceVersion';
Chris@18: 
Chris@18:   /**
Chris@18:    * Gets the reserved (official) JSON:API query parameters.
Chris@18:    *
Chris@18:    * @return string[]
Chris@18:    *   Gets the query parameters reserved by the specification.
Chris@18:    */
Chris@18:   public static function getReservedQueryParameters() {
Chris@18:     return explode('|', static::RESERVED_QUERY_PARAMETERS);
Chris@18:   }
Chris@18: 
Chris@18:   /**
Chris@18:    * Checks whether the given custom query parameter name is valid.
Chris@18:    *
Chris@18:    * A custom query parameter name must be a valid member name, with one
Chris@18:    * additional requirement: it MUST contain at least one non a-z character.
Chris@18:    *
Chris@18:    * Requirements:
Chris@18:    * - it MUST contain at least one character.
Chris@18:    * - it MUST contain only the allowed characters
Chris@18:    * - it MUST start and end with a "globally allowed character"
Chris@18:    * - it MUST contain at least none a-z (U+0061 to U+007A) character
Chris@18:    *
Chris@18:    * It is RECOMMENDED that a hyphen (U+002D), underscore (U+005F) or capital
Chris@18:    * letter is used (i.e. camelCasing).
Chris@18:    *
Chris@18:    * @param string $custom_query_parameter_name
Chris@18:    *   A custom query parameter name to validate.
Chris@18:    *
Chris@18:    * @return bool
Chris@18:    *   Whether the given query parameter is in compliane with the JSON:API
Chris@18:    *   specification.
Chris@18:    *
Chris@18:    * @see http://jsonapi.org/format/#query-parameters
Chris@18:    */
Chris@18:   public static function isValidCustomQueryParameter($custom_query_parameter_name) {
Chris@18:     return static::isValidMemberName($custom_query_parameter_name) && preg_match('/[^a-z]/u', $custom_query_parameter_name) === 1;
Chris@18:   }
Chris@18: 
Chris@18: }