getPaymentStatus( $id ); * } ); * $final = $poller->pollUntilTerminal( $paymentId, array( 'maxDurationMs' => 120000 ) ); */ class PaymentPoller { /** @var callable */ private $getStatus; /** @var bool */ private $isPolling = false; /** * @param callable $getStatus fn(string $paymentId): array PaymentStatusResponse. */ public function __construct( callable $getStatus ) { $this->getStatus = $getStatus; } /** * Resolve options with Android-parity defaults. */ private static function resolveOptions( array $o ) { $interval = isset( $o['intervalMs'] ) ? (int) $o['intervalMs'] : null; return array( 'initialIntervalMs' => isset( $o['initialIntervalMs'] ) ? (int) $o['initialIntervalMs'] : ( null !== $interval ? $interval : NetworkConfig::POLL_INITIAL_INTERVAL_MS ), 'maxIntervalMs' => isset( $o['maxIntervalMs'] ) ? (int) $o['maxIntervalMs'] : ( null !== $interval ? $interval : NetworkConfig::POLL_MAX_INTERVAL_MS ), 'backoffFactor' => isset( $o['backoffFactor'] ) ? (float) $o['backoffFactor'] : NetworkConfig::POLL_BACKOFF_FACTOR, 'fixedPhaseMs' => isset( $o['fixedPhaseMs'] ) ? (int) $o['fixedPhaseMs'] : NetworkConfig::POLL_FIXED_PHASE_MS, 'maxDurationMs' => isset( $o['maxDurationMs'] ) ? (int) $o['maxDurationMs'] : NetworkConfig::POLL_MAX_DURATION_MS, 'stopOnTerminal' => isset( $o['stopOnTerminal'] ) ? (bool) $o['stopOnTerminal'] : true, 'maxAttempts' => isset( $o['maxAttempts'] ) ? (int) $o['maxAttempts'] : null, ); } private static function nowMs() { return (int) round( microtime( true ) * 1000 ); } /** * Callback-based polling (blocking). The callback receives * array{success:bool, data?:array, error?:\Throwable}. Return `false` * from the callback (or call stopPolling()) to stop early. * * @param string $paymentId Payment ID. * @param callable $callback fn(array $result): ?bool. * @param array $options PollOptions. */ public function startPolling( $paymentId, callable $callback, array $options = array() ) { $o = self::resolveOptions( $options ); $this->isPolling = true; $startTime = self::nowMs(); $attempts = 0; $backoff = $o['initialIntervalMs']; while ( $this->isPolling ) { ++$attempts; Logger::debug( "Polling payment status: attempt {$attempts}" ); try { $status = call_user_func( $this->getStatus, $paymentId ); if ( false === $callback( array( 'success' => true, 'data' => $status ) ) ) { break; } if ( $o['stopOnTerminal'] && PaymentStatus::isTerminal( isset( $status['status'] ) ? $status['status'] : '' ) ) { Logger::debug( 'Payment reached terminal state: ' . $status['status'] ); break; } } catch ( \Throwable $e ) { Logger::warn( "Polling error (attempt {$attempts}): " . $e->getMessage() ); if ( false === $callback( array( 'success' => false, 'error' => $e ) ) ) { break; } } $elapsed = self::nowMs() - $startTime; $remaining = $o['maxDurationMs'] - $elapsed; if ( $remaining <= 0 ) { $callback( array( 'success' => false, 'error' => new \RuntimeException( sprintf( 'Polling timed out after %ds', floor( $o['maxDurationMs'] / 1000 ) ) ) ) ); break; } if ( null !== $o['maxAttempts'] && $attempts >= $o['maxAttempts'] ) { $callback( array( 'success' => false, 'error' => new \RuntimeException( "Polling timeout: max attempts ({$o['maxAttempts']}) reached" ) ) ); break; } if ( $elapsed < $o['fixedPhaseMs'] ) { $delay = $o['initialIntervalMs']; } else { $delay = $backoff; $backoff = min( (int) floor( $backoff * $o['backoffFactor'] ), $o['maxIntervalMs'] ); } Retry::delay( min( $delay, $remaining ) ); } $this->isPolling = false; } /** Stop polling (from within the callback). */ public function stopPolling() { $this->isPolling = false; } /** Whether polling is active. */ public function isActive() { return $this->isPolling; } /** * Poll until the payment reaches a terminal state (completed, failed, expired). * * @param string $paymentId Payment ID. * @param array $options PollOptions. * @return array Final PaymentStatusResponse. * @throws \RuntimeException When the time / attempt budget is exhausted. */ public function pollUntilTerminal( $paymentId, array $options = array() ) { $o = self::resolveOptions( $options ); $startTime = self::nowMs(); $attempt = 0; $backoff = $o['initialIntervalMs']; while ( self::nowMs() - $startTime < $o['maxDurationMs'] ) { ++$attempt; Logger::debug( "pollUntilTerminal: attempt {$attempt}" ); try { $status = call_user_func( $this->getStatus, $paymentId ); if ( PaymentStatus::isTerminal( isset( $status['status'] ) ? $status['status'] : '' ) ) { return $status; } } catch ( \Throwable $e ) { Logger::warn( "Polling error (attempt {$attempt}): " . $e->getMessage() ); } if ( null !== $o['maxAttempts'] && $attempt >= $o['maxAttempts'] ) { throw new \RuntimeException( "Polling timeout: max attempts ({$o['maxAttempts']}) reached" ); } $elapsed = self::nowMs() - $startTime; $remaining = $o['maxDurationMs'] - $elapsed; if ( $remaining <= 0 ) { break; } if ( $elapsed < $o['fixedPhaseMs'] ) { $delay = $o['initialIntervalMs']; } else { $delay = $backoff; $backoff = min( (int) floor( $backoff * $o['backoffFactor'] ), $o['maxIntervalMs'] ); } Retry::delay( min( $delay, $remaining ) ); } throw new \RuntimeException( sprintf( 'Polling timeout: payment did not reach terminal state after %ds', floor( $o['maxDurationMs'] / 1000 ) ) ); } }