Release - 2.2.0 (#90)

Co-authored-by: Josh Oakes <josh@joshoak.es>

Author: tarecord

README.md

@@ -30,6 +30,12 @@ A library for Opt-in and Telemetry data to be sent to the StellarWP Telemetry se
 		- [stellarwp/telemetry/{hook-prefix}/last\_send\_expire\_seconds](#stellarwptelemetryhook-prefixlast_send_expire_seconds)
 		- [stellarwp/telemetry/exit\_interview\_args](#stellarwptelemetryexit_interview_args)
 		- [stellarwp/telemetry/{stellar\_slug}/exit\_interview\_args](#stellarwptelemetrystellar_slugexit_interview_args)
+		- [stellarwp/telemetry/{hook-prefix}/event\_data](#stellarwptelemetryhook-prefixevent_data)
+		- [stellarwp/telemetry/{hook-prefix}/events\_url](#stellarwptelemetryhook-prefixevents_url)
+	- [Action Reference](#action-reference)
+		- [stellarwp/telemetry/optin](#stellarwptelemetryoptin)
+		- [stellarwp/telemetry/{hook-prefix}/optin](#stellarwptelemetryhook-prefixoptin)
+		- [stellarwp/telemetry/{hook-prefix}/event](#stellarwptelemetryhook-prefixevent)
 	- [Adding Plugin Data to Site Health](#adding-plugin-data-to-site-health)
 	- [Capturing User Events](#capturing-user-events)
 ## Installation
@@ -396,6 +402,42 @@ $args = [
 ### stellarwp/telemetry/{stellar_slug}/exit_interview_args
 This filter will be deprecated in future versions. Use [stellarwp/telemetry/exit_interview_args](#stellarwptelemetrystellar_slugexit_interview_args) instead.
 
+### stellarwp/telemetry/{hook-prefix}/event_data
+Filters the array of data sent along with the event.
+
+**Parameters**: _array_ `$data`
+
+**Default**:
+```php
+$data = [
+	'token'        => $this->telemetry->get_token(),
+	'stellar_slug' => Config::get_stellar_slug(),
+	'event'        => $name,
+	'event_data'   => wp_json_encode( $data ),
+];
+```
+### stellarwp/telemetry/{hook-prefix}/events_url
+Filters the event URL used when sending events to the Telemetry server.
+
+**Parameters**: _string_ `$url`
+
+**Default**: `https://telemetry.stellarwp.com/api/v1/events`
+
+## Action Reference
+
+### stellarwp/telemetry/optin
+
+**Parameters**: _string_ `$stellar_slug` The stellar slug of the plugin for which the modal should be shown.
+### stellarwp/telemetry/{hook-prefix}/optin
+This filter will be deprecated in future versions. Use [stellarwp/telemetry/optin](#stellarwptelemetryoptin) instead.
+
+### stellarwp/telemetry/{hook-prefix}/event
+Sends a site event to the Telemetry server.
+
+**Parameters**:
+- _string_ `$event` The name of the event.
+- _array_ `$data` A set of data that should be passed along with the event.
+
 ## Adding Plugin Data to Site Health
 
 We collect the Site Health data as json on the server.  In order to pass additional plugin specific items that can be reported on, you will need to add a section to the Site Health Data. The process for adding a section is documented on [developer.wordpress.org](https://developer.wordpress.org/reference/hooks/debug_information/).
@@ -455,7 +497,7 @@ $data = [
 	'two'   => 2,
 	'three' => 3,
 ];
-do_action( 'stellarwp/telemetry/event', 'your-event-name', $data );
+do_action( 'stellarwp/telemetry/{hook-prefix}/event', 'your-event-name', $data );
 ```
 
 Here is how you might log events when a user creates a new post:
@@ -490,6 +532,6 @@ function user_creates_post( $post_id, $post, $update ) {
 	];
 
 	// Log the event with the telemetry server.
-	do_action( 'stellarwp/telemetry/event', 'new_post', $event_data );
+	do_action( 'stellarwp/telemetry/{hook-prefix}/event', 'new_post', $event_data );
 }
 ```

dev/public/wp-content/plugins/library-testing/library-testing.php

@@ -31,3 +31,43 @@ function () {
 		do_action( 'stellarwp/telemetry/optin', 'telemetry-library' );
 	}
 );
+
+// If the 'Send Events' link was used, send some test events once.
+add_action(
+	'init',
+	function() {
+		if ( ! isset( $_GET['send-events'] ) ) { // phpcs:ignore WordPress.Security.NonceVerification.Recommended
+			return;
+		}
+
+		do_action( 'stellarwp/telemetry/telemetry-prefix/event', 'opt-in', [ 'one' => 1 ] );
+		do_action( 'stellarwp/telemetry/telemetry-prefix/event', 'create-post', [ 'post-title' => 'This is my first post!' ] );
+		do_action( 'stellarwp/telemetry/telemetry-prefix/event', 'opt-out', [ 'one' => 1 ] );
+
+		wp_safe_redirect( remove_query_arg( 'send-events' ) );
+		exit;
+	}
+);
+
+/**
+ * Adds a helper link to the admin bar for sending a group of events.
+ *
+ * @param WP_Admin_Bar $admin_bar The adminbar class.
+ *
+ * @return void
+ */
+function add_event_send_link( $admin_bar ) {
+	global $wp;
+
+	$admin_bar->add_menu(
+		[
+			'id'    => 'send-events',
+			'title' => 'Send Events',
+			'href'  => add_query_arg( [ 'send-events' => true ], home_url( $wp->request ) ),
+			'meta'  => [
+				'title' => __( 'Send Events' ),
+			],
+		]
+	);
+}
+add_action( 'admin_bar_menu', 'add_event_send_link', 100, 1 );

src/Telemetry/Events/Event.php

@@ -21,6 +21,13 @@
  */
 class Event {
 
+	/**
+	 * The hook name for sending events asyncronously.
+	 *
+	 * @since 2.2.0
+	 */
+	public const AJAX_ACTION = 'stellarwp_telemetry_send_event';
+
 	/**
 	 * An instance of the Telemetry class.
 	 *
@@ -66,7 +73,31 @@ public function send( string $name, array $data = [] ) {
 		 *
 		 * @param array $data The data about to be sent.
 		 */
-		$data = apply_filters( 'stellarwp/telemetry/events_data', $data );
+		$data = apply_filters( 'stellarwp/telemetry/' . Config::get_hook_prefix() . 'event_data', $data );
+
+		$response = $this->telemetry->send( $data, $this->get_url() );
+
+		if ( ! isset( $response['status'] ) ) {
+			return false;
+		}
+
+		return boolval( $response['status'] );
+	}
+
+	/**
+	 * Send batched events.
+	 *
+	 * @since 2.2.0
+	 *
+	 * @param array $events An array of stored events to send to the telemetry server.
+	 *
+	 * @return bool
+	 */
+	public function send_batch( array $events ) {
+		$data = [
+			'token'  => $this->telemetry->get_token(),
+			'events' => $events,
+		];
 
 		$response = $this->telemetry->send( $data, $this->get_url() );
 

src/Telemetry/Events/Event_Subscriber.php

@@ -9,6 +9,7 @@
 
 namespace StellarWP\Telemetry\Events;
 
+use StellarWP\Telemetry\Config;
 use StellarWP\Telemetry\Contracts\Abstract_Subscriber;
 
 /**
@@ -28,19 +29,78 @@ class Event_Subscriber extends Abstract_Subscriber {
 	 * @return void
 	 */
 	public function register() {
-		add_action( 'stellarwp/telemetry/event', [ $this, 'send_event' ], 10, 2 );
+		add_action( 'shutdown', [ $this, 'send_cached_events' ] );
+		add_action( 'stellarwp/telemetry/' . Config::get_hook_prefix() . 'event', [ $this, 'cache_event' ], 10, 2 );
+		add_action( 'wp_ajax_' . Event::AJAX_ACTION, [ $this, 'send_events' ], 10, 1 );
+		add_action( 'wp_ajax_nopriv_' . Event::AJAX_ACTION, [ $this, 'send_events' ], 10, 1 );
 	}
 
 	/**
-	 * Sends an event request to the Telemetry server.
+	 * Caches an event to be sent during shutdown.
 	 *
-	 * @since 2.1.0
+	 * @since 2.2.0
+	 *
+	 * @param string $name         The name of the event.
+	 * @param array  $data         The data sent along with the event.
 	 *
-	 * @param string $name The name of the event to send.
-	 * @param array  $data Additional information to send with the event.
+	 * @return void
 	 */
-	public function send_event( string $name, array $data = [] ) {
-		$this->container->get( Event::class )->send( $name, $data );
+	public function cache_event( $name, $data ) {
+		$events = [];
+
+		if ( $this->container->has( 'events' ) ) {
+			$events = $this->container->get( 'events' );
+		}
+
+		$events[] = [
+			'name'         => $name,
+			'data'         => wp_json_encode( $data ),
+			'stellar_slug' => Config::get_stellar_slug(),
+		];
+
+		$this->container->bind( 'events', $events );
 	}
 
+	/**
+	 * Sends the events that have been stored for the current request.
+	 *
+	 * @since 2.2.0
+	 *
+	 * @return void
+	 */
+	public function send_cached_events() {
+		if ( ! $this->container->has( 'events' ) ) {
+			return;
+		}
+
+		$url = admin_url( 'admin-ajax.php' );
+
+		wp_remote_post(
+			$url,
+			[
+				'blocking'  => false,
+				'sslverify' => false,
+				'body'      => [
+					'action' => Event::AJAX_ACTION,
+					'events' => $this->container->get( 'events' ),
+				],
+			]
+		);
+
+		$this->container->bind( 'events', [] );
+	}
+
+	/**
+	 * Send the event to the telemetry server.
+	 *
+	 * @since 2.2.0
+	 *
+	 * @return void
+	 */
+	public function send_events() {
+		// Get the passed event array.
+		$events = filter_input( INPUT_POST, 'events', FILTER_DEFAULT, FILTER_REQUIRE_ARRAY ); // phpcs:ignore WordPressVIPMinimum.Security.PHPFilterFunctions.RestrictedFilter
+
+		$this->container->get( Event::class )->send_batch( $events );
+	}
 }

src/Telemetry/Opt_In/Opt_In_Subscriber.php

@@ -77,9 +77,15 @@ public function set_optin_status() {
 			$stellar_slug = sanitize_text_field( $_POST['stellar_slug'] );
 		}
 
+		$opt_in_text = '';
+
+		if ( isset( $_POST['opt_in_text'] ) ) {
+			$opt_in_text = sanitize_text_field( $_POST['opt_in_text'] );
+		}
+
 		// User agreed to opt-in to Telemetry.
 		if ( 'true' === $_POST['optin-agreed'] ) {
-			$this->opt_in( $stellar_slug );
+			$this->opt_in( $stellar_slug, $opt_in_text );
 		}
 
 		// Don't show the opt-in modal again.
@@ -134,17 +140,19 @@ public function initialize_optin_option() {
 	 *
 	 * @since 1.0.0
 	 * @since 2.0.0 - Updated to allow specifying the stellar slug.
+	 * @since 2.2.0 - Updated to add opt-in text.
 	 *
 	 * @param string $stellar_slug The slug to use when opting in.
+	 * @param string $opt_in_text  The text displayed to the user when they agreed to opt-in.
 	 *
 	 * @return void
 	 */
-	public function opt_in( string $stellar_slug ) {
+	public function opt_in( string $stellar_slug, string $opt_in_text = '' ) {
 		$this->container->get( Status::class )->set_status( true, $stellar_slug );
 
 		try {
 			$this->container->get( Telemetry::class )->register_site();
-			$this->container->get( Telemetry::class )->register_user( $stellar_slug );
+			$this->container->get( Telemetry::class )->register_user( $stellar_slug, $opt_in_text );
 		} catch ( \Error $e ) { // phpcs:ignore Generic.CodeAnalysis.EmptyStatement.DetectedCatch
 			// We don't want to throw errors if the server cannot be reached.
 		}

src/Telemetry/Opt_In/Opt_In_Template.php

@@ -62,7 +62,7 @@ public function enqueue(): void {
 	 *
 	 * @return array
 	 */
-	protected function get_args( string $stellar_slug ) {
+	public function get_args( string $stellar_slug ) {
 
 		$optin_args = [
 			'plugin_logo'           => Resources::get_asset_path() . 'resources/images/stellar-logo.svg',
@@ -85,18 +85,8 @@ protected function get_args( string $stellar_slug ) {
 			__( 'We hope you love %s.', 'stellarwp-telemetry' ),
 			$optin_args['plugin_name']
 		);
-		$optin_args['intro'] = sprintf(
-			// Translators: The user name and the plugin name.
-			__(
-				'Hi, %1$s! This is an invitation to help our StellarWP community.
-				If you opt-in, some data about your usage of %2$s and future StellarWP Products will be shared with our teams (so they can work their butts off to improve).
-				We will also share some helpful info on WordPress, and our products from time to time.
-				And if you skip this, that’s okay! Our products still work just fine.',
-				'stellarwp-telemetry'
-			),
-			$optin_args['user_name'],
-			$optin_args['plugin_name']
-		);
+
+		$optin_args['intro'] = $this->get_intro( $optin_args['user_name'], $optin_args['plugin_name'] );
 
 		/**
 		 * Filters the arguments for rendering the Opt-In modal.
@@ -230,4 +220,27 @@ public function get_opted_in_plugin_names() {
 
 		return $opted_in_plugins;
 	}
+
+	/**
+	 * Gets the primary message displayed on the opt-in modal.
+	 *
+	 * @param string $user_name   The display name of the user.
+	 * @param string $plugin_name The name of the plugin.
+	 *
+	 * @return string
+	 */
+	public function get_intro( $user_name, $plugin_name ) {
+		return sprintf(
+			// Translators: The user name and the plugin name.
+			esc_html__(
+				'Hi, %1$s! This is an invitation to help our StellarWP community.
+				If you opt-in, some data about your usage of %2$s and future StellarWP Products will be shared with our teams (so they can work their butts off to improve).
+				We will also share some helpful info on WordPress, and our products from time to time.
+				And if you skip this, that’s okay! Our products still work just fine.',
+				'stellarwp-telemetry'
+			),
+			$user_name,
+			$plugin_name
+		);
+	}
 }