2026-11-15 08:47:00 -08:00
<? php
declare ( strict_types = 1 );
namespace StreamGoals\PayPal ;
/** $wpdb access for sg_donations / sg_goals used by the donate flow. WordPress-only. */
final class DonationStore {
private static function t ( string $name ) : string {
global $wpdb ;
return $wpdb -> prefix . 'sg_' . $name ;
}
public static function goal ( int $id ) : ? array {
global $wpdb ;
$row = $wpdb -> get_row ( $wpdb -> prepare ( 'SELECT * FROM ' . self :: t ( 'goals' ) . ' WHERE id = %d' , $id ), ARRAY_A );
return $row ?: null ;
}
/** @return array[] */
public static function active_goals () : array {
global $wpdb ;
$rows = $wpdb -> get_results ( 'SELECT * FROM ' . self :: t ( 'goals' ) . " WHERE status = 'active' ORDER BY id ASC" , ARRAY_A );
$now = time ();
return array_values ( array_filter ( ( array ) $rows , static fn ( array $g ) : bool => OrderValidator :: goalIsOpen ( $g , $now ) ) );
}
public static function find ( int $id ) : ? object {
global $wpdb ;
return $wpdb -> get_row ( $wpdb -> prepare ( 'SELECT * FROM ' . self :: t ( 'donations' ) . ' WHERE id = %d' , $id ) ) ?: null ;
}
public static function find_by_order ( string $orderId ) : ? object {
global $wpdb ;
return $wpdb -> get_row ( $wpdb -> prepare ( 'SELECT * FROM ' . self :: t ( 'donations' ) . ' WHERE paypal_order_id = %s ORDER BY id DESC LIMIT 1' , $orderId ) ) ?: null ;
}
public static function find_by_capture ( string $captureId ) : ? object {
global $wpdb ;
if ( '' === $captureId ) {
return null ;
}
return $wpdb -> get_row ( $wpdb -> prepare ( 'SELECT * FROM ' . self :: t ( 'donations' ) . ' WHERE paypal_capture_id = %s' , $captureId ) ) ?: null ;
}
/** @param array $v Output of OrderValidator::validate(). @return int Donation id (0 on failure). */
public static function insert_pending ( array $v ) : int {
global $wpdb ;
$ok = $wpdb -> insert (
self :: t ( 'donations' ),
array (
'goal_id' => $v [ 'goal_id' ],
'paypal_order_id' => '' ,
'base_minor' => $v [ 'base_minor' ],
'fee_minor' => $v [ 'fee_minor' ],
'total_minor' => $v [ 'total_minor' ],
'currency' => $v [ 'currency' ],
'donor_name' => $v [ 'donor_name' ],
'is_anonymous' => $v [ 'is_anonymous' ] ? 1 : 0 ,
'message' => $v [ 'message' ],
'status' => 'pending' ,
'moderation' => $v [ 'moderation' ],
'created_at' => gmdate ( 'Y-m-d H:i:s' ),
),
array ( '%d' , '%s' , '%d' , '%d' , '%d' , '%s' , '%s' , '%d' , '%s' , '%s' , '%s' , '%s' )
);
return $ok ? ( int ) $wpdb -> insert_id : 0 ;
}
public static function set_order_id ( int $id , string $orderId ) : void {
global $wpdb ;
$wpdb -> update ( self :: t ( 'donations' ), array ( 'paypal_order_id' => $orderId ), array ( 'id' => $id ), array ( '%s' ), array ( '%d' ) );
}
public static function delete ( int $id ) : void {
global $wpdb ;
$wpdb -> delete ( self :: t ( 'donations' ), array ( 'id' => $id ), array ( '%d' ) );
}
/** Atomic pending -> completed. True only for the single caller that wins the transition. */
public static function mark_completed ( int $id , string $captureId ) : bool {
global $wpdb ;
$n = $wpdb -> query ( $wpdb -> prepare ( 'UPDATE ' . self :: t ( 'donations' ) . " SET status = 'completed', paypal_capture_id = %s WHERE id = %d AND status = 'pending'" , $captureId , $id ) );
return 1 === $n ;
}
2026-11-15 14:07:44 -08:00
/**
* Remember the PayPal capture id of a capture that is not final yet (PENDING / under review). Only touches a
* still-pending row that has no capture id; never changes the status. This is the "PayPal took the money" evidence
* that keeps Maintenance::purge_abandoned away and lets the COMPLETED webhook find the row by capture id.
*/
public static function record_capture_id ( int $id , string $captureId ) : bool {
global $wpdb ;
if ( '' === $captureId ) {
return false ;
}
$n = $wpdb -> query ( $wpdb -> prepare ( 'UPDATE ' . self :: t ( 'donations' ) . " SET paypal_capture_id = %s WHERE id = %d AND status = 'pending' AND (paypal_capture_id IS NULL OR paypal_capture_id = '')" , $captureId , $id ) );
return 1 === $n ;
}
2026-11-15 08:47:00 -08:00
/** Hand a freshly completed donation to the rules engine (if present). Never throws. */
public static function notify_applied ( int $id ) : void {
self :: call_engine ( 'applyDonation' , $id );
2026-11-15 12:36:28 -08:00
// Donation actions (rewards). Not under the goal lock: events are idempotent via a UNIQUE key. Never throws.
try {
\StreamGoals\Actions\Recorder :: forDonation ( $id );
} catch ( \Throwable $e ) {
error_log ( 'StreamGoals: Recorder failed for donation ' . $id . ': ' . $e -> getMessage () ); // phpcs:ignore WordPress.PHP.DevelopmentFunctions
}
2026-11-15 13:09:18 -08:00
// Goal tiers: unlock every tier this donation reaches. MUST run before the close-at-target check below
// (the final tier's target is the goal target). Own try/catch; never throws, never delays a capture.
try {
\StreamGoals\Tiers\Recorder :: forDonation ( $id );
} catch ( \Throwable $e ) {
error_log ( 'StreamGoals: tier unlock failed for donation ' . $id . ': ' . $e -> getMessage () ); // phpcs:ignore WordPress.PHP.DevelopmentFunctions
}
2026-11-15 12:53:07 -08:00
self :: close_goal_if_target_reached ( $id );
}
/**
* "End at target": runs after the donation is already completed and counted, so it can never refuse or
* undo a capture. Failures are logged and swallowed. Idempotent (atomic UPDATE ... WHERE status='active').
*/
public static function close_goal_if_target_reached ( int $donationId ) : void {
try {
$row = self :: find ( $donationId );
if ( $row && ( int ) $row -> goal_id > 0 ) {
( new \StreamGoals\Core\GoalRepository () ) -> closeIfTargetReached ( ( int ) $row -> goal_id );
}
} catch ( \Throwable $e ) {
error_log ( 'StreamGoals: end-at-target check failed for donation ' . $donationId . ': ' . $e -> getMessage () ); // phpcs:ignore WordPress.PHP.DevelopmentFunctions
}
}
/** Goals closed because they reached their target (newest first), for the donor-facing "goal reached" message. @return array[] */
public static function reached_goals () : array {
global $wpdb ;
return ( array ) $wpdb -> get_results ( 'SELECT * FROM ' . self :: t ( 'goals' ) . " WHERE status = 'complete' AND close_at_target = 1 ORDER BY id DESC LIMIT 20" , ARRAY_A );
2026-11-15 08:47:00 -08:00
}
private static function call_engine ( string $method , int $id ) : void {
$row = self :: find ( $id );
if ( ! $row ) {
return ;
}
try {
$donation = \StreamGoals\Core\DonationRepository :: toDonation ( ( array ) $row );
\StreamGoals\Rules\Engine :: withGoalLock (
$donation -> goalId ,
static function () use ( $method , $donation ) : void {
\StreamGoals\Rules\Engine :: default () -> $method ( $donation );
}
);
} catch ( \Throwable $e ) {
error_log ( 'StreamGoals: Engine::' . $method . ' failed for donation ' . $id . ': ' . $e -> getMessage () ); // phpcs:ignore WordPress.PHP.DevelopmentFunctions
}
}
}