Scaffold plugin: architecture contract, schema, settings, fee math

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
This commit is contained in:
shadowdaoandClaude Sonnet 5.5 committed 2026-11-15 08:42:30 -08:00
commit 939193f258
12 files changed
+2081

No files matched your search

+34
View File
@@ -0,0 +1,34 @@
<?php
declare( strict_types=1 );
namespace StreamGoals\Core;
/**
* Computes the amount a donor must pay so the recipient nets the intended base
* after PayPal's fee: total = ceil((base + fixed) / (1 - pct)).
*
* Percent is expressed in basis points (349 = 3.49%) to avoid floats.
*/
final class FeeCalculator {
public function __construct( public readonly int $percentBps = 349, public readonly int $fixedMinor = 49 ) {
if ( $percentBps < 0 || $percentBps >= 10000 || $fixedMinor < 0 ) {
throw new \InvalidArgumentException( 'Invalid fee rates.' );
}
}
/** Total the donor pays so the recipient nets $baseMinor. */
public function grossUp( int $baseMinor ): int {
if ( $baseMinor <= 0 ) {
return 0;
}
$num = ( $baseMinor + $this->fixedMinor ) * 10000;
$den = 10000 - $this->percentBps;
return intdiv( $num + $den - 1, $den ); // integer ceil
}
/** The extra fee-cover portion for a base amount. */
public function feeFor( int $baseMinor ): int {
return $this->grossUp( $baseMinor ) - $baseMinor;
}
}
+99
View File
@@ -0,0 +1,99 @@
<?php
declare( strict_types=1 );
namespace StreamGoals\Core;
/**
* Creates/upgrades the plugin's tables. Safe to re-run (dbDelta).
*/
final class Installer {
public const DB_VERSION = '1';
public static function activate(): void {
self::install_schema();
if ( false === get_option( 'sg_settings' ) ) {
add_option( 'sg_settings', Settings::defaults(), '', false );
}
}
/** Run on plugins_loaded so upgrades apply without re-activation. */
public static function maybe_upgrade(): void {
if ( get_option( 'sg_db_version' ) !== self::DB_VERSION ) {
self::install_schema();
}
}
private static function install_schema(): void {
global $wpdb;
require_once ABSPATH . 'wp-admin/includes/upgrade.php';
$c = $wpdb->get_charset_collate();
$p = $wpdb->prefix . 'sg_';
dbDelta( "CREATE TABLE {$p}goals (
id BIGINT UNSIGNED NOT NULL AUTO_INCREMENT,
title VARCHAR(190) NOT NULL,
target_minor BIGINT UNSIGNED NOT NULL DEFAULT 0,
currency CHAR(3) NOT NULL DEFAULT 'USD',
status VARCHAR(12) NOT NULL DEFAULT 'active',
starts_at DATETIME NULL,
ends_at DATETIME NULL,
counts_fees TINYINT(1) NOT NULL DEFAULT 0,
created_at DATETIME NOT NULL,
PRIMARY KEY (id)
) $c;" );
dbDelta( "CREATE TABLE {$p}donations (
id BIGINT UNSIGNED NOT NULL AUTO_INCREMENT,
goal_id BIGINT UNSIGNED NOT NULL,
paypal_order_id VARCHAR(64) NOT NULL,
paypal_capture_id VARCHAR(64) NULL,
base_minor BIGINT UNSIGNED NOT NULL,
fee_minor BIGINT UNSIGNED NOT NULL DEFAULT 0,
total_minor BIGINT UNSIGNED NOT NULL,
currency CHAR(3) NOT NULL,
donor_name VARCHAR(100) NOT NULL DEFAULT '',
is_anonymous TINYINT(1) NOT NULL DEFAULT 0,
message VARCHAR(500) NOT NULL DEFAULT '',
status VARCHAR(12) NOT NULL DEFAULT 'pending',
moderation VARCHAR(10) NOT NULL DEFAULT 'approved',
created_at DATETIME NOT NULL,
PRIMARY KEY (id),
UNIQUE KEY capture (paypal_capture_id),
KEY goal_status (goal_id,status),
KEY order_id (paypal_order_id)
) $c;" );
dbDelta( "CREATE TABLE {$p}rules (
id BIGINT UNSIGNED NOT NULL AUTO_INCREMENT,
goal_id BIGINT UNSIGNED NOT NULL,
type VARCHAR(16) NOT NULL,
config LONGTEXT NOT NULL,
enabled TINYINT(1) NOT NULL DEFAULT 1,
sort INT NOT NULL DEFAULT 0,
PRIMARY KEY (id),
KEY goal_id (goal_id)
) $c;" );
dbDelta( "CREATE TABLE {$p}rule_events (
id BIGINT UNSIGNED NOT NULL AUTO_INCREMENT,
rule_id BIGINT UNSIGNED NOT NULL,
donation_id BIGINT UNSIGNED NOT NULL,
delta BIGINT NOT NULL DEFAULT 0,
reversed TINYINT(1) NOT NULL DEFAULT 0,
created_at DATETIME NOT NULL,
PRIMARY KEY (id),
UNIQUE KEY rule_donation (rule_id,donation_id)
) $c;" );
dbDelta( "CREATE TABLE {$p}state (
goal_id BIGINT UNSIGNED NOT NULL,
skey VARCHAR(64) NOT NULL,
svalue LONGTEXT NOT NULL,
updated_at DATETIME NOT NULL,
PRIMARY KEY (goal_id,skey)
) $c;" );
update_option( 'sg_db_version', self::DB_VERSION );
}
}
+48
View File
@@ -0,0 +1,48 @@
<?php
declare( strict_types=1 );
namespace StreamGoals\Core;
/**
* Integer minor-unit money value object. No floats anywhere.
*/
final class Money {
/** Currencies with no minor unit (PayPal-supported subset). */
private const ZERO_DECIMAL = array( 'JPY', 'HUF', 'TWD' );
public function __construct( public readonly int $minor, public readonly string $currency ) {
if ( $minor < 0 ) {
throw new \InvalidArgumentException( 'Money cannot be negative.' );
}
}
public static function exponent( string $currency ): int {
return in_array( strtoupper( $currency ), self::ZERO_DECIMAL, true ) ? 0 : 2;
}
/** Parse a decimal string like "10.5" into minor units without float math. */
public static function fromDecimalString( string $amount, string $currency ): self {
$currency = strtoupper( $currency );
$exp = self::exponent( $currency );
if ( ! preg_match( '/^\d+(\.\d+)?$/', trim( $amount ) ) ) {
throw new \InvalidArgumentException( 'Invalid amount.' );
}
[ $whole, $frac ] = array_pad( explode( '.', trim( $amount ), 2 ), 2, '' );
if ( strlen( $frac ) > $exp ) {
throw new \InvalidArgumentException( 'Too many decimal places.' );
}
$frac = str_pad( $frac, $exp, '0' );
return new self( (int) ( $whole . $frac ), $currency );
}
/** Format as the decimal string PayPal expects, e.g. 1099 USD -> "10.99". */
public function toDecimalString(): string {
$exp = self::exponent( $this->currency );
if ( 0 === $exp ) {
return (string) $this->minor;
}
$s = str_pad( (string) $this->minor, 3, '0', STR_PAD_LEFT );
return substr( $s, 0, -2 ) . '.' . substr( $s, -2 );
}
}
+27
View File
@@ -0,0 +1,27 @@
<?php
declare( strict_types=1 );
namespace StreamGoals\Core;
/**
* Boots feature modules. Each module exposes a static register() that adds its own hooks;
* classes that do not exist yet are skipped so modules can land independently.
*/
final class Plugin {
private const MODULES = array(
\StreamGoals\Rest\DonateController::class,
\StreamGoals\Rest\WebhookController::class,
\StreamGoals\Rest\OverlayController::class,
\StreamGoals\Admin\Admin::class,
);
public static function boot(): void {
Installer::maybe_upgrade();
foreach ( self::MODULES as $module ) {
if ( class_exists( $module ) && method_exists( $module, 'register' ) ) {
$module::register();
}
}
}
}
+46
View File
@@ -0,0 +1,46 @@
<?php
declare( strict_types=1 );
namespace StreamGoals\Core;
/**
* Typed access to the single `sg_settings` option.
*/
final class Settings {
public static function defaults(): array {
return array(
'paypal_mode' => 'sandbox', // sandbox | live
'paypal_client_id' => '',
'paypal_client_secret' => '',
'paypal_webhook_id' => '',
'fee_percent_bps' => 349, // 3.49%
'fee_fixed_minor' => 49,
'anonymity_policy' => 'allow', // allow | require_name | force_anonymous
'moderate_messages' => false,
'profanity_filter' => true,
'message_max_length' => 200,
'min_donation_minor' => 100,
'overlay_token' => '',
);
}
public static function all(): array {
$saved = get_option( 'sg_settings', array() );
return array_merge( self::defaults(), is_array( $saved ) ? $saved : array() );
}
public static function get( string $key, mixed $default = null ): mixed {
$all = self::all();
return $all[ $key ] ?? $default;
}
public static function update( array $values ): void {
$allowed = array_intersect_key( $values, self::defaults() );
update_option( 'sg_settings', array_merge( self::all(), $allowed ), false );
}
public static function fee_calculator(): FeeCalculator {
return new FeeCalculator( (int) self::get( 'fee_percent_bps' ), (int) self::get( 'fee_fixed_minor' ) );
}
}