[Summary view] [Print] [Text view]

   1  <?php
   2  /**
   3   * HTTP API: WP_Http_Cookie class
   4   *
   5   * @package WordPress
   6   * @subpackage HTTP
   7   * @since 4.4.0
   8   */
   9  
  10  /**
  11   * Core class used to encapsulate a single cookie object for internal use.
  12   *
  13   * Returned cookies are represented using this class, and when cookies are set, if they are not
  14   * already a WP_Http_Cookie() object, then they are turned into one.
  15   *
  16   * @todo The WordPress convention is to use underscores instead of camelCase for function and method
  17   * names. Need to switch to use underscores instead for the methods.
  18   *
  19   * @since 2.8.0
  20   */
  21  #[AllowDynamicProperties]
  22  class WP_Http_Cookie {
  23  
  24      /**
  25       * Cookie name.
  26       *
  27       * @since 2.8.0
  28       *
  29       * @var string|null
  30       */
  31      public $name;
  32  
  33      /**
  34       * Cookie value.
  35       *
  36       * @since 2.8.0
  37       *
  38       * @var string|null
  39       */
  40      public $value;
  41  
  42      /**
  43       * When the cookie expires, as a Unix timestamp.
  44       *
  45       * False if the expiration date could not be parsed, or null if not provided.
  46       *
  47       * @since 2.8.0
  48       *
  49       * @var int|false|null
  50       */
  51      public $expires;
  52  
  53      /**
  54       * Cookie URL path.
  55       *
  56       * @since 2.8.0
  57       *
  58       * @var string
  59       */
  60      public $path;
  61  
  62      /**
  63       * Cookie Domain.
  64       *
  65       * @since 2.8.0
  66       *
  67       * @var string|null
  68       */
  69      public $domain;
  70  
  71      /**
  72       * Cookie port or comma-separated list of ports.
  73       *
  74       * @since 2.8.0
  75       *
  76       * @var int|string|null
  77       */
  78      public $port;
  79  
  80      /**
  81       * Host-only flag.
  82       *
  83       * Null if not provided.
  84       *
  85       * @since 5.2.0
  86       *
  87       * @var bool|null
  88       */
  89      public $host_only;
  90  
  91      /**
  92       * Sets up this cookie object.
  93       *
  94       * The parameter $data should be either an associative array containing the indices names below
  95       * or a header string detailing it.
  96       *
  97       * @since 2.8.0
  98       * @since 5.2.0 Added `host_only` to the `$data` parameter.
  99       *
 100       * @param string|array $data {
 101       *     Raw cookie data as header string or data array.
 102       *
 103       *     @type string          $name      Cookie name.
 104       *     @type mixed           $value     Value. Should NOT already be urlencoded.
 105       *     @type string|int|null $expires   Optional. Unix timestamp or formatted date. Default null.
 106       *     @type string|null     $path      Optional. Path. Default '/'.
 107       *     @type string|null     $domain    Optional. Domain. Default host of parsed $requested_url.
 108       *     @type int|string|null $port      Optional. Port or comma-separated list of ports. Default null.
 109       *     @type bool|null       $host_only Optional. Host-only storage flag. Default null.
 110       * }
 111       * @param string       $requested_url The URL which the cookie was set on, used for default $domain
 112       *                                    and $port values.
 113       */
 114  	public function __construct( $data, $requested_url = '' ) {
 115          if ( $requested_url ) {
 116              $parsed_url = parse_url( $requested_url );
 117          }
 118          if ( isset( $parsed_url['host'] ) ) {
 119              $this->domain = $parsed_url['host'];
 120          }
 121          $this->path = $parsed_url['path'] ?? '/';
 122          if ( ! str_ends_with( $this->path, '/' ) ) {
 123              $this->path = dirname( $this->path ) . '/';
 124          }
 125  
 126          if ( is_string( $data ) ) {
 127              // Assume it's a header string direct from a previous request.
 128              $pairs = explode( ';', $data );
 129  
 130              // Special handling for first pair; name=value. Also be careful of "=" in value.
 131              $name        = trim( substr( $pairs[0], 0, strpos( $pairs[0], '=' ) ) );
 132              $value       = substr( $pairs[0], strpos( $pairs[0], '=' ) + 1 );
 133              $this->name  = $name;
 134              $this->value = urldecode( $value );
 135  
 136              // Removes name=value from items.
 137              array_shift( $pairs );
 138  
 139              // Set everything else as a property.
 140              foreach ( $pairs as $pair ) {
 141                  $pair = rtrim( $pair );
 142  
 143                  // Handle the cookie ending in ; which results in an empty final pair.
 144                  if ( empty( $pair ) ) {
 145                      continue;
 146                  }
 147  
 148                  list( $key, $val ) = strpos( $pair, '=' ) ? explode( '=', $pair ) : array( $pair, '' );
 149                  $key               = strtolower( trim( $key ) );
 150                  if ( 'expires' === $key ) {
 151                      $val = strtotime( $val );
 152                  }
 153                  $this->$key = $val;
 154              }
 155          } else {
 156              if ( ! isset( $data['name'] ) ) {
 157                  return;
 158              }
 159  
 160              // Set properties based directly on parameters.
 161              foreach ( array( 'name', 'value', 'path', 'domain', 'port', 'host_only' ) as $field ) {
 162                  if ( isset( $data[ $field ] ) ) {
 163                      $this->$field = $data[ $field ];
 164                  }
 165              }
 166  
 167              if ( isset( $data['expires'] ) ) {
 168                  $this->expires = is_int( $data['expires'] ) ? $data['expires'] : strtotime( $data['expires'] );
 169              } else {
 170                  $this->expires = null;
 171              }
 172          }
 173      }
 174  
 175      /**
 176       * Confirms that it's OK to send this cookie to the URL checked against.
 177       *
 178       * Decision is based on RFC 2109/2965, so look there for details on validity.
 179       *
 180       * @since 2.8.0
 181       *
 182       * @param string $url URL you intend to send this cookie to
 183       * @return bool true if allowed, false otherwise.
 184       */
 185  	public function test( $url ) {
 186          if ( is_null( $this->name ) ) {
 187              return false;
 188          }
 189  
 190          // Expires - if expired then nothing else matters.
 191          if ( isset( $this->expires ) && time() > $this->expires ) {
 192              return false;
 193          }
 194  
 195          // Get details on the URL we're thinking about sending to.
 196          $url           = parse_url( $url );
 197          $url['port'] ??= ( 'https' === $url['scheme'] ? 443 : 80 );
 198          $url['path'] ??= '/';
 199  
 200          // Values to use for comparison against the URL.
 201          $path   = $this->path;
 202          $port   = $this->port;
 203          $domain = isset( $this->domain ) ? strtolower( $this->domain ) : strtolower( $url['host'] );
 204          if ( false === stripos( $domain, '.' ) ) {
 205              $domain .= '.local';
 206          }
 207  
 208          // Host - very basic check that the request URL ends with the domain restriction (minus leading dot).
 209          $domain = ( str_starts_with( $domain, '.' ) ) ? substr( $domain, 1 ) : $domain;
 210          if ( ! str_ends_with( $url['host'], $domain ) ) {
 211              return false;
 212          }
 213  
 214          // Port - supports "port-lists" in the format: "80,8000,8080".
 215          if ( ! empty( $port ) && ! in_array( $url['port'], array_map( 'intval', explode( ',', $port ) ), true ) ) {
 216              return false;
 217          }
 218  
 219          // Path - request path must start with path restriction.
 220          if ( ! str_starts_with( $url['path'], $path ) ) {
 221              return false;
 222          }
 223  
 224          return true;
 225      }
 226  
 227      /**
 228       * Convert cookie name and value back to header string.
 229       *
 230       * @since 2.8.0
 231       *
 232       * @return string Header encoded cookie name and value.
 233       */
 234  	public function getHeaderValue() { // phpcs:ignore WordPress.NamingConventions.ValidFunctionName.MethodNameInvalid
 235          if ( ! isset( $this->name ) || ! isset( $this->value ) ) {
 236              return '';
 237          }
 238  
 239          /**
 240           * Filters the header-encoded cookie value.
 241           *
 242           * @since 3.4.0
 243           *
 244           * @param string $value The cookie value.
 245           * @param string $name  The cookie name.
 246           */
 247          return $this->name . '=' . apply_filters( 'wp_http_cookie_value', $this->value, $this->name );
 248      }
 249  
 250      /**
 251       * Retrieve cookie header for usage in the rest of the WordPress HTTP API.
 252       *
 253       * @since 2.8.0
 254       *
 255       * @return string
 256       */
 257  	public function getFullHeader() { // phpcs:ignore WordPress.NamingConventions.ValidFunctionName.MethodNameInvalid
 258          return 'Cookie: ' . $this->getHeaderValue();
 259      }
 260  
 261      /**
 262       * Retrieves cookie attributes.
 263       *
 264       * @since 4.6.0
 265       *
 266       * @return array {
 267       *     List of attributes.
 268       *
 269       *     @type int|false|null $expires When the cookie expires, as a Unix timestamp.
 270       *     @type string         $path    Cookie URL path.
 271       *     @type string|null    $domain  Cookie domain.
 272       * }
 273       */
 274  	public function get_attributes() {
 275          return array(
 276              'expires' => $this->expires,
 277              'path'    => $this->path,
 278              'domain'  => $this->domain,
 279          );
 280      }
 281  }