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