[Summary view] [Print] [Text view]

   1  <?php
   2  /**
   3   * Administration: Community Events class.
   4   *
   5   * @package WordPress
   6   * @subpackage Administration
   7   * @since 4.8.0
   8   */
   9  
  10  /**
  11   * Class WP_Community_Events.
  12   *
  13   * A client for api.wordpress.org/events.
  14   *
  15   * @since 4.8.0
  16   */
  17  #[AllowDynamicProperties]
  18  class WP_Community_Events {
  19      /**
  20       * ID for a WordPress user account.
  21       *
  22       * @since 4.8.0
  23       *
  24       * @var int
  25       */
  26      protected $user_id = 0;
  27  
  28      /**
  29       * Stores location data for the user.
  30       *
  31       * @since 4.8.0
  32       *
  33       * @var false|array
  34       */
  35      protected $user_location = false;
  36  
  37      /**
  38       * Constructor for WP_Community_Events.
  39       *
  40       * @since 4.8.0
  41       *
  42       * @param int        $user_id       WP user ID.
  43       * @param false|array $user_location {
  44       *     Stored location data for the user. false to pass no location.
  45       *
  46       *     @type string $description The name of the location
  47       *     @type string $latitude    The latitude in decimal degrees notation, without the degree
  48       *                               symbol. e.g.: 47.615200.
  49       *     @type string $longitude   The longitude in decimal degrees notation, without the degree
  50       *                               symbol. e.g.: -122.341100.
  51       *     @type string $country     The ISO 3166-1 alpha-2 country code. e.g.: BR
  52       * }
  53       */
  54  	public function __construct( $user_id, $user_location = false ) {
  55          $this->user_id       = absint( $user_id );
  56          $this->user_location = $user_location;
  57      }
  58  
  59      /**
  60       * Gets data about events near a particular location.
  61       *
  62       * Cached events will be immediately returned if the `user_location` property
  63       * is set for the current user, and cached events exist for that location.
  64       *
  65       * Otherwise, this method sends a request to the w.org Events API with location
  66       * data. The API will send back a recognized location based on the data, along
  67       * with nearby events.
  68       *
  69       * The browser's request for events is proxied with this method, rather
  70       * than having the browser make the request directly to api.wordpress.org,
  71       * because it allows results to be cached server-side and shared with other
  72       * users and sites in the network. This makes the process more efficient,
  73       * since increasing the number of visits that get cached data means users
  74       * don't have to wait as often; if the user's browser made the request
  75       * directly, it would also need to make a second request to WP in order to
  76       * pass the data for caching. Having WP make the request also introduces
  77       * the opportunity to anonymize the IP before sending it to w.org, which
  78       * mitigates possible privacy concerns.
  79       *
  80       * @since 4.8.0
  81       * @since 5.5.2 Response no longer contains formatted date field. They're added
  82       *              in `wp.communityEvents.populateDynamicEventFields()` now.
  83       *
  84       * @param string $location_search Optional. City name to help determine the location.
  85       *                                e.g., "Seattle". Default empty string.
  86       * @param string $timezone        Optional. Timezone to help determine the location.
  87       *                                Default empty string.
  88       * @return array|WP_Error A WP_Error on failure; an array with location and events on
  89       *                        success.
  90       */
  91  	public function get_events( $location_search = '', $timezone = '' ) {
  92          $cached_events = $this->get_cached_events();
  93  
  94          if ( ! $location_search && $cached_events ) {
  95              return $cached_events;
  96          }
  97  
  98          // Include an unmodified $wp_version.
  99          require  ABSPATH . WPINC . '/version.php';
 100  
 101          $api_url                    = 'http://api.wordpress.org/events/1.0/';
 102          $request_args               = $this->get_request_args( $location_search, $timezone );
 103          $request_args['user-agent'] = 'WordPress/' . $wp_version . '; ' . home_url( '/' );
 104  
 105          if ( wp_http_supports( array( 'ssl' ) ) ) {
 106              $api_url = set_url_scheme( $api_url, 'https' );
 107          }
 108  
 109          $response       = wp_remote_get( $api_url, $request_args );
 110          $response_code  = wp_remote_retrieve_response_code( $response );
 111          $response_body  = json_decode( wp_remote_retrieve_body( $response ), true );
 112          $response_error = null;
 113  
 114          if ( is_wp_error( $response ) ) {
 115              $response_error = $response;
 116          } elseif ( 200 !== $response_code ) {
 117              $response_error = new WP_Error(
 118                  'api-error',
 119                  /* translators: %d: Numeric HTTP status code, e.g. 400, 403, 500, 504, etc. */
 120                  sprintf( __( 'Invalid API response code (%d).' ), $response_code )
 121              );
 122          } elseif ( ! isset( $response_body['location'], $response_body['events'] ) ) {
 123              $response_error = new WP_Error(
 124                  'api-invalid-response',
 125                  isset( $response_body['error'] ) ? $response_body['error'] : __( 'Unknown API error.' )
 126              );
 127          }
 128  
 129          if ( is_wp_error( $response_error ) ) {
 130              return $response_error;
 131          } else {
 132              $expiration = false;
 133  
 134              if ( isset( $response_body['ttl'] ) ) {
 135                  $expiration = $response_body['ttl'];
 136                  unset( $response_body['ttl'] );
 137              }
 138  
 139              /*
 140               * The IP in the response is usually the same as the one that was sent
 141               * in the request, but in some cases it is different. In those cases,
 142               * it's important to reset it back to the IP from the request.
 143               *
 144               * For example, if the IP sent in the request is private (e.g., 192.168.1.100),
 145               * then the API will ignore that and use the corresponding public IP instead,
 146               * and the public IP will get returned. If the public IP were saved, though,
 147               * then get_cached_events() would always return `false`, because the transient
 148               * would be generated based on the public IP when saving the cache, but generated
 149               * based on the private IP when retrieving the cache.
 150               */
 151              if ( ! empty( $response_body['location']['ip'] ) ) {
 152                  $response_body['location']['ip'] = $request_args['body']['ip'];
 153              }
 154  
 155              /*
 156               * The API doesn't return a description for latitude/longitude requests,
 157               * but the description is already saved in the user location, so that
 158               * one can be used instead.
 159               */
 160              if ( $this->coordinates_match( $request_args['body'], $response_body['location'] ) && empty( $response_body['location']['description'] ) ) {
 161                  $response_body['location']['description'] = $this->user_location['description'];
 162              }
 163  
 164              /*
 165               * Store the raw response, because events will expire before the cache does.
 166               * The response will need to be processed every page load.
 167               */
 168              $this->cache_events( $response_body, $expiration );
 169  
 170              $response_body['events'] = $this->trim_events( $response_body['events'] );
 171  
 172              return $response_body;
 173          }
 174      }
 175  
 176      /**
 177       * Builds an array of args to use in an HTTP request to the w.org Events API.
 178       *
 179       * @since 4.8.0
 180       *
 181       * @param string $search   Optional. City search string. Default empty string.
 182       * @param string $timezone Optional. Timezone string. Default empty string.
 183       * @return array The request args.
 184       */
 185  	protected function get_request_args( $search = '', $timezone = '' ) {
 186          $args = array(
 187              'number' => 5, // Get more than three in case some get trimmed out.
 188              'ip'     => self::get_unsafe_client_ip(),
 189          );
 190  
 191          /*
 192           * Include the minimal set of necessary arguments, in order to increase the
 193           * chances of a cache-hit on the API side.
 194           */
 195          if ( empty( $search ) && isset( $this->user_location['latitude'], $this->user_location['longitude'] ) ) {
 196              $args['latitude']  = $this->user_location['latitude'];
 197              $args['longitude'] = $this->user_location['longitude'];
 198          } else {
 199              $args['locale'] = get_user_locale( $this->user_id );
 200  
 201              if ( $timezone ) {
 202                  $args['timezone'] = $timezone;
 203              }
 204  
 205              if ( $search ) {
 206                  $args['location'] = $search;
 207              }
 208          }
 209  
 210          // Wrap the args in an array compatible with the second parameter of `wp_remote_get()`.
 211          return array(
 212              'body' => $args,
 213          );
 214      }
 215  
 216      /**
 217       * Determines the user's actual IP address and attempts to partially
 218       * anonymize an IP address by converting it to a network ID.
 219       *
 220       * Geolocating the network ID usually returns a similar location as the
 221       * actual IP, but provides some privacy for the user.
 222       *
 223       * $_SERVER['REMOTE_ADDR'] cannot be used in all cases, such as when the user
 224       * is making their request through a proxy, or when the web server is behind
 225       * a proxy. In those cases, $_SERVER['REMOTE_ADDR'] is set to the proxy address rather
 226       * than the user's actual address.
 227       *
 228       * Modified from https://stackoverflow.com/a/2031935/450127, MIT license.
 229       * Modified from https://github.com/geertw/php-ip-anonymizer, MIT license.
 230       *
 231       * SECURITY WARNING: This function is _NOT_ intended to be used in
 232       * circumstances where the authenticity of the IP address matters. This does
 233       * _NOT_ guarantee that the returned address is valid or accurate, and it can
 234       * be easily spoofed.
 235       *
 236       * @since 4.8.0
 237       *
 238       * @return string|false The anonymized address on success; the given address
 239       *                      or false on failure.
 240       */
 241  	public static function get_unsafe_client_ip() {
 242          $client_ip = false;
 243  
 244          // In order of preference, with the best ones for this purpose first.
 245          $address_headers = array(
 246              'HTTP_CLIENT_IP',
 247              'HTTP_X_FORWARDED_FOR',
 248              'HTTP_X_FORWARDED',
 249              'HTTP_X_CLUSTER_CLIENT_IP',
 250              'HTTP_FORWARDED_FOR',
 251              'HTTP_FORWARDED',
 252              'REMOTE_ADDR',
 253          );
 254  
 255          foreach ( $address_headers as $header ) {
 256              if ( array_key_exists( $header, $_SERVER ) ) {
 257                  /*
 258                   * HTTP_X_FORWARDED_FOR can contain a chain of comma-separated
 259                   * addresses. The first one is the original client. It can't be
 260                   * trusted for authenticity, but we don't need to for this purpose.
 261                   */
 262                  $address_chain = explode( ',', $_SERVER[ $header ] );
 263                  $client_ip     = trim( $address_chain[0] );
 264  
 265                  break;
 266              }
 267          }
 268  
 269          if ( ! $client_ip ) {
 270              return false;
 271          }
 272  
 273          $anon_ip = wp_privacy_anonymize_ip( $client_ip, true );
 274  
 275          if ( '0.0.0.0' === $anon_ip || '::' === $anon_ip ) {
 276              return false;
 277          }
 278  
 279          return $anon_ip;
 280      }
 281  
 282      /**
 283       * Test if two pairs of latitude/longitude coordinates match each other.
 284       *
 285       * @since 4.8.0
 286       *
 287       * @param array $a The first pair, with indexes 'latitude' and 'longitude'.
 288       * @param array $b The second pair, with indexes 'latitude' and 'longitude'.
 289       * @return bool True if they match, false if they don't.
 290       */
 291  	protected function coordinates_match( $a, $b ) {
 292          if ( ! isset( $a['latitude'], $a['longitude'], $b['latitude'], $b['longitude'] ) ) {
 293              return false;
 294          }
 295  
 296          return $a['latitude'] === $b['latitude'] && $a['longitude'] === $b['longitude'];
 297      }
 298  
 299      /**
 300       * Generates a transient key based on user location.
 301       *
 302       * This could be reduced to a one-liner in the calling functions, but it's
 303       * intentionally a separate function because it's called from multiple
 304       * functions, and having it abstracted keeps the logic consistent and DRY,
 305       * which is less prone to errors.
 306       *
 307       * @since 4.8.0
 308       *
 309       * @param array $location Should contain 'latitude' and 'longitude' indexes.
 310       * @return string|false Transient key on success, false on failure.
 311       */
 312  	protected function get_events_transient_key( $location ) {
 313          $key = false;
 314  
 315          if ( isset( $location['ip'] ) ) {
 316              $key = 'community-events-' . md5( $location['ip'] );
 317          } elseif ( isset( $location['latitude'], $location['longitude'] ) ) {
 318              $key = 'community-events-' . md5( $location['latitude'] . $location['longitude'] );
 319          }
 320  
 321          return $key;
 322      }
 323  
 324      /**
 325       * Caches an array of events data from the Events API.
 326       *
 327       * @since 4.8.0
 328       *
 329       * @param array     $events     Response body from the API request.
 330       * @param int|false $expiration Optional. Amount of time to cache the events. Defaults to false.
 331       * @return bool true if events were cached; false if not.
 332       */
 333  	protected function cache_events( $events, $expiration = false ) {
 334          $set              = false;
 335          $transient_key    = $this->get_events_transient_key( $events['location'] );
 336          $cache_expiration = $expiration ? absint( $expiration ) : HOUR_IN_SECONDS * 12;
 337  
 338          if ( $transient_key ) {
 339              $set = set_site_transient( $transient_key, $events, $cache_expiration );
 340          }
 341  
 342          return $set;
 343      }
 344  
 345      /**
 346       * Gets cached events.
 347       *
 348       * @since 4.8.0
 349       * @since 5.5.2 Response no longer contains formatted date field. They're added
 350       *              in `wp.communityEvents.populateDynamicEventFields()` now.
 351       *
 352       * @return array|false An array containing `location` and `events` items
 353       *                     on success, false on failure.
 354       */
 355  	public function get_cached_events() {
 356          $transient_key = $this->get_events_transient_key( $this->user_location );
 357          if ( ! $transient_key ) {
 358              return false;
 359          }
 360  
 361          $cached_response = get_site_transient( $transient_key );
 362          if ( isset( $cached_response['events'] ) ) {
 363              $cached_response['events'] = $this->trim_events( $cached_response['events'] );
 364          }
 365  
 366          return $cached_response;
 367      }
 368  
 369      /**
 370       * Adds formatted date and time items for each event in an API response.
 371       *
 372       * This has to be called after the data is pulled from the cache, because
 373       * the cached events are shared by all users. If it was called before storing
 374       * the cache, then all users would see the events in the localized data/time
 375       * of the user who triggered the cache refresh, rather than their own.
 376       *
 377       * @since 4.8.0
 378       * @deprecated 5.5.2 No longer used in core.
 379       *
 380       * @param array $response_body The response which contains the events.
 381       * @return array The response with dates and times formatted.
 382       */
 383  	protected function format_event_data_time( $response_body ) {
 384          _deprecated_function( __METHOD__, '5.5.2' );
 385  
 386          if ( isset( $response_body['events'] ) ) {
 387              foreach ( $response_body['events'] as $key => $event ) {
 388                  $timestamp = strtotime( $event['date'] );
 389  
 390                  /*
 391                   * The `date_format` option is not used because it's important
 392                   * in this context to keep the day of the week in the formatted date,
 393                   * so that users can tell at a glance if the event is on a day they
 394                   * are available, without having to open the link.
 395                   */
 396                  /* translators: Date format for upcoming events on the dashboard. Include the day of the week. See https://www.php.net/manual/datetime.format.php */
 397                  $formatted_date = date_i18n( __( 'l, M j, Y' ), $timestamp );
 398                  $formatted_time = date_i18n( get_option( 'time_format' ), $timestamp );
 399  
 400                  if ( isset( $event['end_date'] ) ) {
 401                      $end_timestamp      = strtotime( $event['end_date'] );
 402                      $formatted_end_date = date_i18n( __( 'l, M j, Y' ), $end_timestamp );
 403  
 404                      if ( 'meetup' !== $event['type'] && $formatted_end_date !== $formatted_date ) {
 405                          /* translators: Upcoming events month format. See https://www.php.net/manual/datetime.format.php */
 406                          $start_month = date_i18n( _x( 'F', 'upcoming events month format' ), $timestamp );
 407                          $end_month   = date_i18n( _x( 'F', 'upcoming events month format' ), $end_timestamp );
 408  
 409                          if ( $start_month === $end_month ) {
 410                              $formatted_date = sprintf(
 411                                  /* translators: Date string for upcoming events. 1: Month, 2: Starting day, 3: Ending day, 4: Year. */
 412                                  __( '%1$s %2$d–%3$d, %4$d' ),
 413                                  $start_month,
 414                                  /* translators: Upcoming events day format. See https://www.php.net/manual/datetime.format.php */
 415                                  date_i18n( _x( 'j', 'upcoming events day format' ), $timestamp ),
 416                                  date_i18n( _x( 'j', 'upcoming events day format' ), $end_timestamp ),
 417                                  /* translators: Upcoming events year format. See https://www.php.net/manual/datetime.format.php */
 418                                  date_i18n( _x( 'Y', 'upcoming events year format' ), $timestamp )
 419                              );
 420                          } else {
 421                              $formatted_date = sprintf(
 422                                  /* translators: Date string for upcoming events. 1: Starting month, 2: Starting day, 3: Ending month, 4: Ending day, 5: Year. */
 423                                  __( '%1$s %2$d – %3$s %4$d, %5$d' ),
 424                                  $start_month,
 425                                  date_i18n( _x( 'j', 'upcoming events day format' ), $timestamp ),
 426                                  $end_month,
 427                                  date_i18n( _x( 'j', 'upcoming events day format' ), $end_timestamp ),
 428                                  date_i18n( _x( 'Y', 'upcoming events year format' ), $timestamp )
 429                              );
 430                          }
 431  
 432                          $formatted_date = wp_maybe_decline_date( $formatted_date, 'F j, Y' );
 433                      }
 434                  }
 435  
 436                  $response_body['events'][ $key ]['formatted_date'] = $formatted_date;
 437                  $response_body['events'][ $key ]['formatted_time'] = $formatted_time;
 438              }
 439          }
 440  
 441          return $response_body;
 442      }
 443  
 444      /**
 445       * Prepares the event list for presentation.
 446       *
 447       * Discards expired events, and makes WordCamps "sticky." Attendees need more
 448       * advanced notice about WordCamps than they do for meetups, so camps should
 449       * appear in the list sooner. If a WordCamp is coming up, the API will "stick"
 450       * it in the response, even if it wouldn't otherwise appear. When that happens,
 451       * the event will be at the end of the list, and will need to be moved into a
 452       * higher position, so that it doesn't get trimmed off.
 453       *
 454       * @since 4.8.0
 455       * @since 4.9.7 Stick a WordCamp to the final list.
 456       * @since 5.5.2 Accepts and returns only the events, rather than an entire HTTP response.
 457       * @since 6.0.0 Decode HTML entities from the event title.
 458       *
 459       * @param array $events The events that will be prepared.
 460       * @return array The response body with events trimmed.
 461       */
 462  	protected function trim_events( array $events ) {
 463          $future_events = array();
 464  
 465          foreach ( $events as $event ) {
 466              /*
 467               * The API's `date` and `end_date` fields are in the _event's_ local timezone, but UTC is needed so
 468               * it can be converted to the _user's_ local time.
 469               */
 470              $end_time = (int) $event['end_unix_timestamp'];
 471  
 472              if ( time() < $end_time ) {
 473                  // Decode HTML entities from the event title.
 474                  $event['title'] = html_entity_decode( $event['title'], ENT_QUOTES, 'UTF-8' );
 475  
 476                  array_push( $future_events, $event );
 477              }
 478          }
 479  
 480          $future_wordcamps = array_filter(
 481              $future_events,
 482              static function ( $wordcamp ) {
 483                  return 'wordcamp' === $wordcamp['type'];
 484              }
 485          );
 486  
 487          $future_wordcamps    = array_values( $future_wordcamps ); // Remove gaps in indices.
 488          $trimmed_events      = array_slice( $future_events, 0, 3 );
 489          $trimmed_event_types = wp_list_pluck( $trimmed_events, 'type' );
 490  
 491          // Make sure the soonest upcoming WordCamp is pinned in the list.
 492          if ( $future_wordcamps && ! in_array( 'wordcamp', $trimmed_event_types, true ) ) {
 493              array_pop( $trimmed_events );
 494              array_push( $trimmed_events, $future_wordcamps[0] );
 495          }
 496  
 497          return $trimmed_events;
 498      }
 499  
 500      /**
 501       * Logs responses to Events API requests.
 502       *
 503       * @since 4.8.0
 504       * @deprecated 4.9.0 Use a plugin instead. See #41217 for an example.
 505       *
 506       * @param string $message A description of what occurred.
 507       * @param array  $details Details that provide more context for the
 508       *                        log entry.
 509       */
 510  	protected function maybe_log_events_response( $message, $details ) {
 511          _deprecated_function( __METHOD__, '4.9.0' );
 512  
 513          if ( ! WP_DEBUG_LOG ) {
 514              return;
 515          }
 516  
 517          error_log(
 518              sprintf(
 519                  '%s: %s. Details: %s',
 520                  __METHOD__,
 521                  trim( $message, '.' ),
 522                  wp_json_encode( $details )
 523              )
 524          );
 525      }
 526  }