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]
 18class 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}
527