Stabilize normalized form submission context

assets/js/src/site/plugins/pum-integrations.js

@@ -7,15 +7,41 @@
 	// Ensure PUM exists globally
 	window.PUM = window.PUM || {};
 	window.PUM.integrations = window.PUM.integrations || {};
+	const PUM = window.PUM;
+	const pumVars = window.pum_vars;
 
 	function filterNull( x ) {
 		return x;
 	}
 
+	function generateSubmissionId() {
+		if ( window.crypto && 'function' === typeof window.crypto.randomUUID ) {
+			return window.crypto.randomUUID();
+		}
+
+		return 'xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx'.replace(
+			/[xy]/g,
+			( character ) => {
+				const random = Math.floor( Math.random() * 16 );
+				const value = 'x' === character ? random : ( random % 4 ) + 8;
+
+				return value.toString( 16 );
+			}
+		);
+	}
+
+	function validSubmissionId( submissionId ) {
+		if ( 'number' === typeof submissionId ) {
+			return Number.isFinite( submissionId );
+		}
+
+		return 'string' === typeof submissionId && '' !== submissionId;
+	}
+
 	$.extend( window.PUM.integrations, {
-		init: function () {
-			if ( 'undefined' !== typeof pum_vars.form_submission ) {
-				var submission = pum_vars.form_submission;
+		init() {
+			if ( pumVars && 'undefined' !== typeof pumVars.form_submission ) {
+				const submission = pumVars.form_submission;
 
 				// Declare these are not AJAX submissions.
 				submission.ajax = false;
@@ -39,26 +65,69 @@
 		 * @param {Object} form JavaScript DOM node or jQuery object for the form submitted
 		 * @param {Object} args {
 		 *     @type {string} formProvider Such as gravityforms or ninjaforms
-		 *     @type {string|int} formId Usually an integer ID number such as 1
-		 *     @type {int} formInstanceId Not all form plugins support this.
+		 *     @type {string|number} formId Usually an integer ID number such as 1
+		 *     @type {number} formInstanceId Not all form plugins support this.
+		 *     @type {string|number} submissionId Stable submission or provider entry ID.
+		 *     @type {number} sourcePostId Optional post/page ID where the form was submitted.
+		 *     @type {string} sourceUrl URL where the form was submitted.
+		 *     @type {Object} context Extension-owned submission context.
 		 * }
 		 */
-		formSubmission: function ( form, args ) {
-			var $popup = PUM.getPopup( form );
+		formSubmission( form, args ) {
+			const $popup = PUM.getPopup( form );
 
 			args = $.extend(
 				{
 					popup: $popup,
 					formProvider: null,
 					formId: null,
 					formInstanceId: null,
+					submissionId: null,
+					sourcePostId: null,
+					sourceUrl: window.location.href,
+					context: {},
 					formKey: null,
 					ajax: true, // Allows detecting submissions that may have already been counted.
 					tracked: false,
 				},
 				args
 			);
 
+			args.submissionId = validSubmissionId( args.submissionId )
+				? args.submissionId
+				: generateSubmissionId();
+			args.context =
+				args.context &&
+				'object' === typeof args.context &&
+				! Array.isArray( args.context )
+					? args.context
+					: {};
+			const canonicalSubmissionId = args.submissionId;
+
+			/**
+			 * Filters normalized form submission arguments before success handlers run.
+			 *
+			 * Extensions can append context without coupling to individual providers.
+			 *
+			 * @param {Object} args Normalized submission arguments.
+			 * @param {Object} form Submitted form element or jQuery object.
+			 */
+			args = window.PUM.hooks.applyFilters(
+				'pum.integration.form.submissionArgs',
+				args,
+				form
+			);
+
+			args.submissionId = validSubmissionId( args.submissionId )
+				? args.submissionId
+				: canonicalSubmissionId;
+			args.context =
+				args.context &&
+				'object' === typeof args.context &&
+				! Array.isArray( args.context )
+					? args.context
+					: {};
+
 			// Generate unique formKey identifier.
 			args.formKey =
 				args.formKey ||
@@ -83,10 +152,14 @@
 			 * @param {Object} form JavaScript DOM node or jQuery object for the form submitted
 			 * @param {Object} args {
 			 *     @type {string} formProvider Such as gravityforms or ninjaforms
-			 *     @type {string|int} formId Usually an integer ID number such as 1
-			 *     @type {int} formInstanceId Not all form plugins support this.
+			 *     @type {string|number} formId Usually an integer ID number such as 1
+			 *     @type {number} formInstanceId Not all form plugins support this.
+			 *     @type {string|number} submissionId Stable submission or provider entry ID.
+			 *     @type {number} sourcePostId Optional post/page ID where the form was submitted.
+			 *     @type {string} sourceUrl URL where the form was submitted.
+			 *     @type {Object} context Extension-owned submission context.
 			 *     @type {string} formKey Concatenation of provider, ID & Instance ID.
-			 *     @type {int} popupId The ID of the popup the form was in.
+			 *     @type {number} popupId The ID of the popup the form was in.
 			 *     @type {Object} popup Usable jQuery object for the popup.
 			 * }
 			 */
@@ -96,14 +169,14 @@
 				args
 			);
 		},
-		checkFormKeyMatches: function (
+		checkFormKeyMatches(
 			formIdentifier,
 			formInstanceId,
 			submittedFormArgs
 		) {
 			formInstanceId = '' === formInstanceId ? formInstanceId : false;
 			// Check if the submitted form matches trigger requirements.
-			var checks = [
+			const checks = [
 					// Any supported form.
 					formIdentifier === 'any',
 
@@ -138,28 +211,28 @@
 			 * @since 1.9.0
 			 *
 			 * @param {boolean} matchFound A boolean determining whether a match was found.
-			 * @param {Object} args {
+			 * @param {Object}  args       {
 			 *		@type {string} formIdentifier gravityforms_any or ninjaforms_1
-			 *		@type {int} formInstanceId Not all form plugins support this.
+			 *		@type {number} formInstanceId Not all form plugins support this.
 			 *		@type {Object} submittedFormArgs{
 			 *			@type {string} formProvider Such as gravityforms or ninjaforms
-			 * 			@type {string|int} formId Usually an integer ID number such as 1
-			 *			@type {int} formInstanceId Not all form plugins support this.
+			 * 			@type {string|number} formId Usually an integer ID number such as 1
+			 *			@type {number} formInstanceId Not all form plugins support this.
 			 *			@type {string} formKey Concatenation of provider, ID & Instance ID.
-			 *			@type {int} popupId The ID of the popup the form was in.
+			 *			@type {number} popupId The ID of the popup the form was in.
 			 *			@type {Object} popup Usable jQuery object for the popup.
 			 *		}
 			 * }
 			 *
-			 * @returns {boolean}
+			 * @return {boolean}
 			 */
 			return window.PUM.hooks.applyFilters(
 				'pum.integration.checkFormKeyMatches',
 				matchFound,
 				{
-					formIdentifier: formIdentifier,
-					formInstanceId: formInstanceId,
-					submittedFormArgs: submittedFormArgs,
+					formIdentifier,
+					formInstanceId,
+					submittedFormArgs,
 				}
 			);
 		},

classes/Integration/Form/FluentForms.php

@@ -115,6 +115,7 @@ public function on_success( $submission_id, $form_data, $form ) {
 				'popup_id'      => $popup_id,
 				'form_provider' => $this->key,
 				'form_id'       => $form_id,
+				'submission_id' => is_scalar( $submission_id ) ? $submission_id : null,
 			]
 		);
 	}

classes/Integrations.php

@@ -534,9 +534,24 @@ public static function pum_vars( $vars = [] ) {
 					'form_provider'    => 'formProvider',
 					'form_id'          => 'formId',
 					'form_instance_id' => 'formInstanceId',
+					'submission_id'    => 'submissionId',
 					'popup_id'         => 'popupId',
+					'source_post_id'   => 'sourcePostId',
+					'source_url'       => 'sourceUrl',
 				]
 			);
+
+			// remap_keys intentionally skips empty values, but these values are meaningful.
+			$preserved_keys = [
+				'submission_id' => 'submissionId',
+				'source_url'    => 'sourceUrl',
+			];
+
+			foreach ( $preserved_keys as $php_key => $js_key ) {
+				if ( array_key_exists( $php_key, self::$form_submission ) ) {
+					$vars['form_submission'][ $js_key ] = self::$form_submission[ $php_key ];
+				}
+			}
 		}
 
 		return $vars;

docs/form-submission-context.md

@@ -0,0 +1,67 @@
+# Normalized form submission context
+
+Popup Maker form integrations report successful submissions through
+`pum_integrated_form_submission()` in PHP and
+`PUM.integrations.formSubmission()` in JavaScript. The normalized envelope is
+provider-independent, and extensions can attach their own namespaced data to
+`context` without changing each provider integration.
+
+## Contract
+
+PHP integrations use snake-cased keys:
+
+```php
+pum_integrated_form_submission( [
+	'form_provider'  => 'example',
+	'form_id'        => 12,
+	'submission_id'  => 'entry-456',
+	'source_post_id' => 78,
+	'source_url'     => 'https://example.com/guide/',
+	'context'        => [
+		'my_extension' => [
+			'campaign_id' => 90,
+		],
+	],
+] );
+```
+
+JavaScript integrations receive the camel-cased equivalents. When a provider
+does not supply `submission_id` / `submissionId`, Popup Maker generates a UUID
+for that one normalized event. Provider-native submission IDs are the reliable
+correlation key when matching independently observed server and frontend
+callbacks; independently generated IDs are not a cross-transport deduplication
+mechanism.
+
+`source_url` defaults to the sanitized request referrer in PHP and the current
+page URL in JavaScript. PHP resolves `source_post_id` from the effective source
+URL when an explicit numeric post ID is not supplied, including after an
+extension replaces the URL. Both values remain nullable because referrers may
+be unavailable and not every URL represents a WordPress post. A PHP `null`
+source URL remains `null` when localized for browser replay rather than being
+replaced with the post-redirect page URL.
+
+## Extension context
+
+PHP extensions can use the existing
+`pum_integrated_form_submission_args` filter. Frontend extensions use the
+`pum.integration.form.submissionArgs` filter, which runs after defaults and
+popup resolution but before the form key, conversion event, and normalized
+success action are produced.
+
+```js
+PUM.hooks.addFilter(
+	'pum.integration.form.submissionArgs',
+	( args ) => ( {
+		...args,
+		context: {
+			...args.context,
+			myExtension: { campaignId: 90 },
+		},
+	} )
+);
+```
+
+Context and source values are descriptive metadata, not proof of identity or
+authorization. Consumers must validate untrusted values before privileged
+operations and apply their own privacy and retention policies before storing
+submission data.

includes/functions/developers.php

@@ -44,26 +44,72 @@ function pum_trigger_popup_form_success( $popup_id = null, $settings = [] ) {
  *      @type string $form_provider Key indicating which form provider this form belongs to.
  *      @type string|int $form_id Form ID, usually numeric, but can be hash based.
  *      @type int $form_instance_id Optional form instance ID.
+ *      @type string|int $submission_id Stable submission or provider entry ID. Generated when omitted.
  *      @type int $popup_id Optional popup ID.
+ *      @type int $source_post_id Optional post/page ID where the form was submitted.
+ *      @type string $source_url Optional URL where the form was submitted.
+ *      @type array $context Optional extension-owned submission context.
  *      @type bool $ajax If the submission was processed via AJAX. Generally gonna be false outside of JavaScript.
  *      @type bool $tracked Whether the submission has been handled by tracking code or not. Prevents duplicates.
  * }
  */
 function pum_integrated_form_submission( $args = [] ) {
+	$args                        = is_array( $args ) ? $args : [];
+	$source_url                  = wp_get_raw_referer();
+	$source_url                  = $source_url ? esc_url_raw( $source_url ) : null;
+	$source_post_id_was_explicit = array_key_exists( 'source_post_id', $args );
+
 	$args = wp_parse_args(
 		$args,
 		[
 			'popup_id'         => null,
 			'form_provider'    => null,
 			'form_id'          => null,
 			'form_instance_id' => null,
+			'submission_id'    => null,
+			'source_post_id'   => null,
+			'source_url'       => $source_url,
+			'context'          => [],
 			'ajax'             => false,
 			'tracked'          => false,
 		]
 	);
 
+	if ( ! isset( $args['submission_id'] ) || ( ! is_string( $args['submission_id'] ) && ! is_int( $args['submission_id'] ) ) || '' === (string) $args['submission_id'] ) {
+		$args['submission_id'] = wp_generate_uuid4();
+	}
+
+	$source_post_id         = is_scalar( $args['source_post_id'] ) && ! is_bool( $args['source_post_id'] ) && is_numeric( $args['source_post_id'] ) ? absint( $args['source_post_id'] ) : 0;
+	$args['source_post_id'] = $source_post_id ? $source_post_id : null;
+	$args['source_url']     = ! empty( $args['source_url'] ) && is_string( $args['source_url'] ) ? esc_url_raw( $args['source_url'] ) : null;
+	$args['context']        = isset( $args['context'] ) && is_array( $args['context'] ) ? $args['context'] : [];
+
+	if ( ! $source_post_id_was_explicit && $args['source_url'] ) {
+		$source_post_id         = url_to_postid( $args['source_url'] );
+		$args['source_post_id'] = $source_post_id ? $source_post_id : null;
+	}
+
+	$submission_id                = $args['submission_id'];
+	$source_post_id_before_filter = $args['source_post_id'];
+
 	$args = apply_filters( 'pum_integrated_form_submission_args', $args );
 
+	if ( ! isset( $args['submission_id'] ) || ( ! is_string( $args['submission_id'] ) && ! is_int( $args['submission_id'] ) ) || '' === (string) $args['submission_id'] ) {
+		$args['submission_id'] = $submission_id;
+	}
+
+	$filtered_source_post_id       = isset( $args['source_post_id'] ) ? $args['source_post_id'] : null;
+	$filter_changed_source_post_id = $filtered_source_post_id !== $source_post_id_before_filter;
+	$source_post_id                = is_scalar( $filtered_source_post_id ) && ! is_bool( $filtered_source_post_id ) && is_numeric( $filtered_source_post_id ) ? absint( $filtered_source_post_id ) : 0;
+	$args['source_post_id']        = $source_post_id ? $source_post_id : null;
+	$args['source_url']            = ! empty( $args['source_url'] ) && is_string( $args['source_url'] ) ? esc_url_raw( $args['source_url'] ) : null;
+	$args['context']               = isset( $args['context'] ) && is_array( $args['context'] ) ? $args['context'] : [];
+
+	if ( ! $source_post_id_was_explicit && ! $filter_changed_source_post_id && $args['source_url'] ) {
+		$source_post_id         = url_to_postid( $args['source_url'] );
+		$args['source_post_id'] = $source_post_id ? $source_post_id : null;
+	}
+
 	PUM_Integrations::$form_submission = $args;
 
 	do_action( 'pum_integrated_form_submission', $args );