Automattic\WooCommerce\Internal\Admin\Settings\PaymentsProviders\WooPayments

WooPaymentsService::record_onboarding_step_completed │ private │ WC 1.0

Record an onboarding step as completed without re-checking whether a new onboarding action is allowed.

This is for internal use only, by callers that just need to sync the NOX onboarding state with the outcome of an already-settled operation — whether it succeeded (e.g. a committed account mutation) or failed in a way that resolves the step (e.g. a non-recoverable initialization error that skips the step forward). Unlike mark_onboarding_step_completed(), it deliberately skips check_if_onboarding_step_action_is_acceptable() — including the shared onboarding lock check — because the state change is the consequence of work that already happened, not a new user action. Re-checking the lock here would let a concurrent request that acquired the lock during an unlocked phase turn an already-successful mutation into an onboarding-locked error. This mirrors mark_onboarding_step_failed() and mark_onboarding_step_blocked(), which skip the same checks for the same reason.

Method of the class: WooPaymentsService{}

No Hooks.

Returns

bool. Whether the onboarding step was marked as completed.

Usage

// private - for code of main (parent) class only
$result = $this->record_onboarding_step_completed( $step_id, $location, $overwrite, ?string $source, $skipped ): bool;

$step_id(string) (required)

The ID of the onboarding step.

$location(string) (required)

The location for which we are onboarding. This is an ISO 3166-1 alpha-2 country code.

$overwrite(true|false)

Whether to overwrite the step status if it is already completed and update the timestamp. Regardless of this, the stored statuses are re-written whenever the skip marker needs to be added or can be safely removed, so the marker reflects how the latest completion happened — to the extent the account state can vouch for it. Such marker-only maintenance leaves the stored completion timestamp untouched and does not re-record the step completion event.
Default: false

?string $source

.
Default: self::SESSION_ENTRY_DEFAULT

$skipped(true|false)

Whether the step is being completed by skipping it forward rather than through actual completion. A marker is stored with the step statuses so the status determination logic can tell the two apart. A non-skip completion clears a previously stored marker, but only when a valid account vouches for the completion being genuine.
Default: false

WooPaymentsService::record_onboarding_step_completed() WooPaymentsService::record onboarding step completed code ^{WC 11.1.1}

private function record_onboarding_step_completed( string $step_id, string $location, bool $overwrite = false, ?string $source = self::SESSION_ENTRY_DEFAULT, bool $skipped = false ): bool {
	// Clear possible failed status for the step.
	$this->clear_onboarding_step_failed( $step_id, $location );

	$statuses      = (array) $this->get_nox_profile_onboarding_step_entry( $step_id, $location, 'statuses' );
	$was_completed = ! empty( $statuses[ self::ONBOARDING_STEP_STATUS_COMPLETED ] );
	$has_marker    = ! empty( $statuses[ self::ONBOARDING_STEP_SKIPPED_MARKER ] );
	// The marker must not outlive the skip being the reason for the completion. Otherwise,
	// a stale marker would keep bypassing the status re-gating (e.g. for a genuine test
	// account whose validity lapses later). But it can only be removed when the account state
	// vouches for a genuine completion — generic completion paths (e.g. the step finish action)
	// must not strip the skip protection while the account is still the invalid fallback
	// the skip left behind.
	$add_marker   = $skipped && ! $has_marker;
	$clear_marker = ! $skipped && $has_marker && $this->has_valid_account();
	if ( ! $overwrite && $was_completed && ! $add_marker && ! $clear_marker ) {
		return true;
	}

	// Mark the step as completed and record the timestamp. An already-completed step keeps
	// its stored timestamp (honoring $overwrite): falling through the early return for
	// marker maintenance must not masquerade as a new completion.
	if ( $overwrite || ! $was_completed ) {
		$statuses[ self::ONBOARDING_STEP_STATUS_COMPLETED ] = $this->proxy->call_function( 'time' );
	}
	if ( $skipped ) {
		// The marker records when the skip happened.
		$statuses[ self::ONBOARDING_STEP_SKIPPED_MARKER ] = $this->proxy->call_function( 'time' );
	} elseif ( $clear_marker ) {
		unset( $statuses[ self::ONBOARDING_STEP_SKIPPED_MARKER ] );
	}

	// Store the updated step data.
	$result = $this->save_nox_profile_onboarding_step_entry( $step_id, $location, 'statuses', $statuses );

	if ( $result && ( $overwrite || ! $was_completed ) ) {
		$source = $this->validate_onboarding_source( $source );

		// Record an event for the step being completed.
		$this->record_event(
			self::EVENT_PREFIX . 'onboarding_step_completed',
			$location,
			array(
				'step_id' => $step_id,
				'source'  => $source,
			)
		);
	}

	return $result;
}