| @@ -4,14 +4,16 @@ | ||
| 4 | 4 | |
| 5 | 5 | use FluentCart\Api\CurrencySettings; |
| 6 | 6 | use FluentCart\Api\StoreSettings; |
| 7 | 7 | use FluentCart\App\App; |
| 8 | -use FluentCart\App\Events\Subscription\SubscriptionCanceled; | |
| 8 | +use FluentCart\App\Helpers\AttributeHelper; | |
| 9 | 9 | use FluentCart\App\Helpers\Helper; |
| 10 | 10 | use FluentCart\App\Helpers\Status; |
| 11 | +use FluentCart\App\Modules\PaymentMethods\Core\AbstractPaymentGateway; | |
| 12 | +use FluentCart\App\Modules\PaymentMethods\Core\PaymentGatewayInterface; | |
| 13 | +use FluentCart\App\Modules\Subscriptions\Services\SubscriptionService; | |
| 11 | 14 | use FluentCart\App\Models\Concerns\CanUpdateBatch; |
| 12 | 15 | use FluentCart\App\Models\Concerns\HasActivity; |
| 13 | -use FluentCart\App\Services\Payments\PaymentHelper; | |
| 14 | 16 | use FluentCart\App\Services\Payments\SubscriptionHelper; |
| 15 | 17 | use FluentCart\App\Services\TemplateService; |
| 16 | 18 | use FluentCart\Framework\Database\Orm\Relations\BelongsTo; |
| 17 | 19 | use FluentCart\Framework\Database\Orm\Relations\HasMany; |
| @@ -24,8 +26,10 @@ | ||
| 24 | 26 | * Meta Model - DB Model for Meta table |
| 25 | 27 | * |
| 26 | 28 | * Database Model |
| 27 | 29 | * |
| 30 | + * @property string $uuid | |
| 31 | + * | |
| 28 | 32 | * @package FluentCart\App\Models |
| 29 | 33 | * |
| 30 | 34 | * @version 1.0.0 |
| 31 | 35 | */ |
| @@ -36,9 +40,9 @@ | ||
| 36 | 40 | protected $table = 'fct_subscriptions'; |
| 37 | 41 | |
| 38 | 42 | protected $primaryKey = 'id'; |
| 39 | 43 | |
| 40 | - protected $appends = ['url', 'payment_info', 'billingInfo', 'overridden_status', 'currency', 'reactivate_url']; | |
| 44 | + protected $appends = ['url', 'payment_info', 'billingInfo', 'overridden_status', 'currency', 'reactivate_url', 'permissions', 'display_item_name', 'system_charge_state', 'payment_method_title']; | |
| 41 | 45 | |
| 42 | 46 | protected $guarded = ['id']; |
| 43 | 47 | |
| 44 | 48 | protected $fillable = [ |
| @@ -160,9 +164,9 @@ | ||
| 160 | 164 | public function getConfigAttribute($value) |
| 161 | 165 | { |
| 162 | 166 | if (is_string($value)) { |
| 163 | 167 | $decoded = json_decode($value, true); |
| 164 | - return $decoded ?: $value; | |
| 168 | + return is_array($decoded) ? $decoded : $value; | |
| 165 | 169 | } |
| 166 | 170 | return $value ?: []; |
| 167 | 171 | } |
| 168 | 172 | |
| @@ -176,8 +180,124 @@ | ||
| 176 | 180 | |
| 177 | 181 | $this->attributes['config'] = $value; |
| 178 | 182 | } |
| 179 | 183 | |
| 184 | + /** | |
| 185 | + * Merge keys into the config blob under a row lock. | |
| 186 | + * | |
| 187 | + * Every writer of this column must go through here. `config` is a single JSON | |
| 188 | + * document written by the cancel path, both Stripe paths and both PayPal paths; | |
| 189 | + * a plain read-merge-write loses whichever concurrent write commits first, and a | |
| 190 | + * renewal landing during a payment-method switch is not a rare pairing. | |
| 191 | + * | |
| 192 | + * @param array $values keys to set; existing keys not named here survive | |
| 193 | + * @return array the merged config as committed | |
| 194 | + */ | |
| 195 | + public function mergeConfig(array $values): array | |
| 196 | + { | |
| 197 | + $current = $this->config; | |
| 198 | + $current = is_array($current) ? $current : []; | |
| 199 | + | |
| 200 | + if (!$values) { | |
| 201 | + return $current; | |
| 202 | + } | |
| 203 | + | |
| 204 | + $db = static::query()->getConnection(); | |
| 205 | + $db->beginTransaction(); | |
| 206 | + | |
| 207 | + try { | |
| 208 | + $locked = static::query() | |
| 209 | + ->where('id', $this->getKey()) | |
| 210 | + ->lockForUpdate() | |
| 211 | + ->first(); | |
| 212 | + | |
| 213 | + if (!$locked) { | |
| 214 | + $db->rollBack(); | |
| 215 | + return $current; | |
| 216 | + } | |
| 217 | + | |
| 218 | + $stored = $locked->config; | |
| 219 | + $stored = is_array($stored) ? $stored : []; | |
| 220 | + $merged = array_merge($stored, $values); | |
| 221 | + | |
| 222 | + // Query-builder update bypasses setConfigAttribute, so encode with the | |
| 223 | + // same flags the mutator uses. | |
| 224 | + static::query() | |
| 225 | + ->where('id', $this->getKey()) | |
| 226 | + ->update([ | |
| 227 | + 'config' => json_encode($merged, JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES) | |
| 228 | + ]); | |
| 229 | + | |
| 230 | + $db->commit(); | |
| 231 | + } catch (\Exception $e) { | |
| 232 | + $db->rollBack(); | |
| 233 | + throw $e; | |
| 234 | + } | |
| 235 | + | |
| 236 | + // Only `config` was written, so only `config` is clean now — a bare | |
| 237 | + // syncOriginal() would also mark the caller's unsaved edits as persisted | |
| 238 | + // and their next save() would drop them. | |
| 239 | + $this->setAttribute('config', $merged); | |
| 240 | + $this->syncOriginalAttribute('config'); | |
| 241 | + | |
| 242 | + return $merged; | |
| 243 | + } | |
| 244 | + | |
| 245 | + /** | |
| 246 | + * Customer-facing display name. When the config['item_attributes'] snapshot | |
| 247 | + * resolves it returns the product name with the labeled combination | |
| 248 | + * ("Cake - Flavor: Vanilla | Weight: 500 g"); otherwise the raw item_name | |
| 249 | + * (simple / pre-snapshot subscriptions). | |
| 250 | + * | |
| 251 | + * Presentation-only — it does NOT override the item_name column, so internal | |
| 252 | + * and payment-gateway reads of $subscription->item_name keep the raw stored | |
| 253 | + * value. Use this only at customer-facing display sites. | |
| 254 | + * | |
| 255 | + * The model is passed to the resolver so attribute-display filters (e.g. for | |
| 256 | + * simple-variation / third-party attributes) get the item context they need. | |
| 257 | + * | |
| 258 | + * @return string | |
| 259 | + */ | |
| 260 | + public function getDisplayItemNameAttribute() | |
| 261 | + { | |
| 262 | + $itemAttributes = Arr::get($this->config, 'item_attributes', []); | |
| 263 | + | |
| 264 | + if (!$itemAttributes) { | |
| 265 | + return $this->item_name; | |
| 266 | + } | |
| 267 | + | |
| 268 | + $attributeDisplayTitleString = AttributeHelper::getDisplayAttributesString($itemAttributes, $this, 'subscription'); | |
| 269 | + | |
| 270 | + if ($attributeDisplayTitleString === '') { | |
| 271 | + return $this->item_name; | |
| 272 | + } | |
| 273 | + | |
| 274 | + // Standalone label has no separate product line, so prefix the product | |
| 275 | + // name: "<product> - <attributes>". | |
| 276 | + $postTitle = $this->product ? $this->product->post_title : ''; | |
| 277 | + | |
| 278 | + return $postTitle !== '' ? $postTitle . ' - ' . $attributeDisplayTitleString : $attributeDisplayTitleString; | |
| 279 | + } | |
| 280 | + | |
| 281 | + /** | |
| 282 | + * Display label of the backing gateway ("Authorize.Net", "Cash"), the same | |
| 283 | + * source StatusHelper stamps into order.payment_method_title. Empty when the | |
| 284 | + * slug resolves to no registered gateway. | |
| 285 | + */ | |
| 286 | + public function getPaymentMethodTitleAttribute(): string | |
| 287 | + { | |
| 288 | + $gateway = $this->resolveGateway(); | |
| 289 | + if (!$gateway) { | |
| 290 | + return ''; | |
| 291 | + } | |
| 292 | + | |
| 293 | + $title = method_exists($gateway, 'getMeta') | |
| 294 | + ? $gateway->getMeta('title') | |
| 295 | + : Arr::get($gateway->meta(), 'title'); | |
| 296 | + | |
| 297 | + return (string) $title; | |
| 298 | + } | |
| 299 | + | |
| 180 | 300 | public function getUrlAttribute($value) |
| 181 | 301 | { |
| 182 | 302 | return apply_filters('fluent_cart/subscription/url_' . $this->current_payment_method, '', [ |
| 183 | 303 | 'vendor_subscription_id' => $this->vendor_subscription_id, |
| @@ -196,9 +316,8 @@ | ||
| 196 | 316 | * use overriden status to show the correct status for customer |
| 197 | 317 | */ |
| 198 | 318 | public function getOverriddenStatusAttribute($value) |
| 199 | 319 | { |
| 200 | - $variation = ProductVariation::find($this->variation_id); | |
| 201 | 320 | if (Arr::get($this->config, 'is_trial_days_simulated', 'no') == 'yes' && $this->status == Status::SUBSCRIPTION_TRIALING) { |
| 202 | 321 | return Status::SUBSCRIPTION_ACTIVE; |
| 203 | 322 | } |
| 204 | 323 | |
| @@ -208,8 +327,44 @@ | ||
| 208 | 327 | |
| 209 | 328 | return $this->status; |
| 210 | 329 | } |
| 211 | 330 | |
| 331 | + /** | |
| 332 | + * Auto-charge bookkeeping for system subscriptions (attempt count, next retry, | |
| 333 | + * last error, processing marker). Null for every other collection method — | |
| 334 | + * guarded before the meta lookup so manual/automatic subscriptions pay nothing. | |
| 335 | + */ | |
| 336 | + public function getSystemChargeStateAttribute() | |
| 337 | + { | |
| 338 | + if ($this->collection_method !== 'system') { | |
| 339 | + return null; | |
| 340 | + } | |
| 341 | + | |
| 342 | + $meta = $this->meta->where('meta_key', 'system_charge_state')->first(); | |
| 343 | + | |
| 344 | + if (!$meta) { | |
| 345 | + return null; | |
| 346 | + } | |
| 347 | + | |
| 348 | + return is_string($meta->meta_value) ? json_decode($meta->meta_value, true) : $meta->meta_value; | |
| 349 | + } | |
| 350 | + | |
| 351 | + public function getHasPendingSkipAttribute(): bool | |
| 352 | + { | |
| 353 | + return $this->hasPendingSkip(); | |
| 354 | + } | |
| 355 | + | |
| 356 | + public function getLastSkippedPeriodAttribute() | |
| 357 | + { | |
| 358 | + $skipped = $this->getMeta('skipped_periods', []); | |
| 359 | + | |
| 360 | + if (!is_array($skipped) || empty($skipped)) { | |
| 361 | + return null; | |
| 362 | + } | |
| 363 | + | |
| 364 | + return end($skipped) ?: null; | |
| 365 | + } | |
| 366 | + | |
| 212 | 367 | public function getBillingInfoAttribute($value) |
| 213 | 368 | { |
| 214 | 369 | $billingInfo = ''; |
| 215 | 370 | $metaKey = 'active_payment_method'; |
| @@ -290,8 +445,131 @@ | ||
| 290 | 445 | return $this->getSubscriptionInfo(); |
| 291 | 446 | } |
| 292 | 447 | |
| 293 | 448 | /** |
| 449 | + * Get subscription permissions for the current user | |
| 450 | + * Returns what actions can be performed on this subscription | |
| 451 | + * | |
| 452 | + * @return array | |
| 453 | + */ | |
| 454 | + public function getPermissionsAttribute(): array | |
| 455 | + { | |
| 456 | + $status = strtolower($this->status); | |
| 457 | + $hasVendorId = !empty($this->vendor_subscription_id); | |
| 458 | + $terminalStatuses = [ | |
| 459 | + Status::SUBSCRIPTION_CANCELED, | |
| 460 | + Status::SUBSCRIPTION_EXPIRED, | |
| 461 | + Status::SUBSCRIPTION_COMPLETED, | |
| 462 | + ]; | |
| 463 | + | |
| 464 | + $canEdit = $this->usesRenewalEngine() && !in_array($status, $terminalStatuses); | |
| 465 | + $canCancel = !in_array($status, $terminalStatuses); | |
| 466 | + | |
| 467 | + // One open-invoice lookup shared by the invoice actions below. Only runs | |
| 468 | + // for store-billed subscriptions in states where any of them can apply. | |
| 469 | + $hasOpenInvoice = false; | |
| 470 | + $chargeableStatuses = [ | |
| 471 | + Status::SUBSCRIPTION_ACTIVE, | |
| 472 | + Status::SUBSCRIPTION_TRIALING, | |
| 473 | + Status::SUBSCRIPTION_PAST_DUE, | |
| 474 | + Status::SUBSCRIPTION_EXPIRED, | |
| 475 | + ]; | |
| 476 | + if ($this->usesRenewalEngine() && in_array($status, $chargeableStatuses) && $this->parent_order_id) { | |
| 477 | + $hasOpenInvoice = Order::query() | |
| 478 | + ->where('parent_id', $this->parent_order_id) | |
| 479 | + ->where('type', Status::ORDER_TYPE_RENEWAL) | |
| 480 | + ->whereIn('payment_status', [Status::PAYMENT_PENDING, Status::PAYMENT_SCHEDULED]) | |
| 481 | + ->exists(); | |
| 482 | + } | |
| 483 | + | |
| 484 | + $canManageRenewal = $this->usesRenewalEngine() | |
| 485 | + && in_array($status, [Status::SUBSCRIPTION_ACTIVE, Status::SUBSCRIPTION_TRIALING]) | |
| 486 | + && $this->next_billing_date | |
| 487 | + && !$hasOpenInvoice; | |
| 488 | + | |
| 489 | + // Admin "Charge Now": system subscription with an open invoice whose charge | |
| 490 | + // is not currently settling at the gateway (processing marker). | |
| 491 | + $chargeState = $this->isSystem() ? ($this->system_charge_state ?: []) : []; | |
| 492 | + $canChargeNow = $this->isSystem() | |
| 493 | + && $hasOpenInvoice | |
| 494 | + && in_array($status, $chargeableStatuses) | |
| 495 | + && Arr::get($chargeState, 'status') !== 'processing'; | |
| 496 | + | |
| 497 | + return [ | |
| 498 | + 'canEdit' => $canEdit, | |
| 499 | + 'canEditVendorIds' => $this->canEditVendorIds(), | |
| 500 | + 'canVerifyVendorIds' => $this->canVerifyVendorIds(), | |
| 501 | + 'canPause' => $this->canPause(), | |
| 502 | + 'canResume' => $this->canResume(), | |
| 503 | + 'canFetch' => !$this->usesRenewalEngine() && $hasVendorId, | |
| 504 | + 'canCancel' => $canCancel, | |
| 505 | + // Admin one-click reactivate is for store-billed subscriptions only (the REST | |
| 506 | + // endpoint rejects automatic); automatic reactivation runs through the gateway | |
| 507 | + // URL flow, gated by canReactivate(). | |
| 508 | + 'canAdminReactivate' => $this->usesRenewalEngine() && $this->canReactivate(), | |
| 509 | + 'canCreateRenewal' => $canManageRenewal, | |
| 510 | + 'canSkipRenewal' => $canManageRenewal && !$this->hasPendingSkip(), | |
| 511 | + 'canChargeNow' => $canChargeNow, | |
| 512 | + // Surfaced in the Edit modal: an already-issued renewal invoice is | |
| 513 | + // re-synced to the edited amount when it exists. | |
| 514 | + 'hasPendingRenewal' => $hasOpenInvoice, | |
| 515 | + ]; | |
| 516 | + } | |
| 517 | + | |
| 518 | + /** | |
| 519 | + * Check if this is a manual subscription | |
| 520 | + * | |
| 521 | + * @return bool | |
| 522 | + */ | |
| 523 | + public function isManual(): bool | |
| 524 | + { | |
| 525 | + return $this->collection_method === 'manual'; | |
| 526 | + } | |
| 527 | + | |
| 528 | + /** | |
| 529 | + * Check if this is a system (auto-charged, store-billed) subscription | |
| 530 | + * | |
| 531 | + * @return bool | |
| 532 | + */ | |
| 533 | + public function isSystem(): bool | |
| 534 | + { | |
| 535 | + return $this->collection_method === 'system'; | |
| 536 | + } | |
| 537 | + | |
| 538 | + /** | |
| 539 | + * Check if this is a gateway-billed (automatic) subscription | |
| 540 | + * | |
| 541 | + * @return bool | |
| 542 | + */ | |
| 543 | + public function isAutomatic(): bool | |
| 544 | + { | |
| 545 | + return $this->collection_method === Status::SUBSCRIPTION_METHOD_AUTOMATIC; | |
| 546 | + } | |
| 547 | + | |
| 548 | + /** | |
| 549 | + * Manual and system subscriptions are both billed by FluentCart's invoice | |
| 550 | + * engine (renewal invoices, overdue escalation, admin invoice actions). | |
| 551 | + * System additionally auto-charges a stored token per invoice. | |
| 552 | + * | |
| 553 | + * @return bool | |
| 554 | + */ | |
| 555 | + public function usesRenewalEngine(): bool | |
| 556 | + { | |
| 557 | + return in_array($this->collection_method, ['manual', 'system'], true); | |
| 558 | + } | |
| 559 | + | |
| 560 | + /** | |
| 561 | + * Store-billed (manual/system) with a future due date has nothing to charge yet — | |
| 562 | + * reactivation should flip the subscription active locally instead of checkout. | |
| 563 | + * | |
| 564 | + * @return bool | |
| 565 | + */ | |
| 566 | + public function shouldSubscriptionActiveLocally(): bool | |
| 567 | + { | |
| 568 | + return $this->usesRenewalEngine() && $this->next_billing_date && strtotime($this->next_billing_date) > time(); | |
| 569 | + } | |
| 570 | + | |
| 571 | + /** | |
| 294 | 572 | * Helper method to get subscription info |
| 295 | 573 | * |
| 296 | 574 | * @return string |
| 297 | 575 | */ |
| @@ -307,8 +585,12 @@ | ||
| 307 | 585 | ]; |
| 308 | 586 | |
| 309 | 587 | $recurringTotal = $this->recurring_total ?? 0; |
| 310 | 588 | |
| 589 | + if ($schedule = SubscriptionHelper::getBillingSchedule($this)) { | |
| 590 | + return Helper::generateScheduleSubscriptionInfo($schedule, $otherInfo, $recurringTotal, $this->currency) ?? ''; | |
| 591 | + } | |
| 592 | + | |
| 311 | 593 | return Helper::generateSubscriptionInfo($otherInfo, $recurringTotal, $this->currency) ?? ''; |
| 312 | 594 | } |
| 313 | 595 | |
| 314 | 596 | public function addLog($title, $description = '', $type = 'info', $by = '') |
| @@ -424,12 +706,72 @@ | ||
| 424 | 706 | ->where('object_id', $this->variation_id) |
| 425 | 707 | ->exists() && in_array($this->status, [Status::SUBSCRIPTION_ACTIVE, Status::SUBSCRIPTION_TRIALING]); |
| 426 | 708 | } |
| 427 | 709 | |
| 710 | + /** | |
| 711 | + * The gateway backing this subscription, or null when there is not one. | |
| 712 | + * | |
| 713 | + * `App::gateway()` returns the GatewayManager when its argument is null — | |
| 714 | + * that is how `App::gateway()` with no argument is meant to work, but | |
| 715 | + * `current_payment_method` is nullable, so a subscription with no payment | |
| 716 | + * method resolves to the manager too. The manager is a truthy object, so | |
| 717 | + * every `if (!$gateway)` guard in this class waved it through, and the next | |
| 718 | + * line read `$gateway->supportedFeatures` as null. | |
| 719 | + * | |
| 720 | + * `in_array($needle, null)` is a TypeError on PHP 8, thrown from | |
| 721 | + * `getPermissionsAttribute()` — an `$appends` entry — so it fires while | |
| 722 | + * SERIALIZING. One subscription row with a blank payment method therefore | |
| 723 | + * took down the entire subscriptions list response, not just its own row. | |
| 724 | + * | |
| 725 | + * Resolve through here rather than calling `App::gateway()` directly. | |
| 726 | + * | |
| 727 | + * The instanceof is against PaymentGatewayInterface — the manager's | |
| 728 | + * registration contract — NOT AbstractPaymentGateway, so a third-party | |
| 729 | + * gateway implementing the interface directly still resolves. The only | |
| 730 | + * object it rejects is the GatewayManager itself, which does not implement | |
| 731 | + * the interface. | |
| 732 | + * | |
| 733 | + * @return PaymentGatewayInterface|null | |
| 734 | + */ | |
| 735 | + private function resolveGateway(): ?PaymentGatewayInterface | |
| 736 | + { | |
| 737 | + if (empty($this->current_payment_method)) { | |
| 738 | + return null; | |
| 739 | + } | |
| 740 | + | |
| 741 | + // The one direct App::gateway() call in this class. | |
| 742 | + $gateway = App::gateway($this->current_payment_method); | |
| 743 | + | |
| 744 | + return $gateway instanceof PaymentGatewayInterface ? $gateway : null; | |
| 745 | + } | |
| 746 | + | |
| 747 | + /** | |
| 748 | + * The `switch_payment_method` entry of `supportedFeatures`, or [] when the | |
| 749 | + * gateway does not declare one. | |
| 750 | + * | |
| 751 | + * Unlike the flat feature flags this is a KEYED entry carrying config | |
| 752 | + * (`supported_gateways`), so `has()` cannot answer it — it needs the raw | |
| 753 | + * `supportedFeatures` property, which only AbstractPaymentGateway carries. | |
| 754 | + * An interface-only gateway therefore reports no switch support rather | |
| 755 | + * than triggering an undefined-property read. | |
| 756 | + * | |
| 757 | + * @return array | |
| 758 | + */ | |
| 759 | + private function switchPaymentConfig(): array | |
| 760 | + { | |
| 761 | + $gateway = $this->resolveGateway(); | |
| 762 | + | |
| 763 | + if (!$gateway instanceof AbstractPaymentGateway) { | |
| 764 | + return []; | |
| 765 | + } | |
| 766 | + | |
| 767 | + return (array) Arr::get($gateway->supportedFeatures, 'switch_payment_method', []); | |
| 768 | + } | |
| 769 | + | |
| 428 | 770 | public function canUpdatePaymentMethod() |
| 429 | 771 | { |
| 430 | - $gateway = App::gateway($this->current_payment_method); | |
| 431 | - if (!$gateway || !in_array('card_update', $gateway->supportedFeatures)) { | |
| 772 | + $gateway = $this->resolveGateway(); | |
| 773 | + if (!$gateway || !$gateway->has('card_update')) { | |
| 432 | 774 | return false; |
| 433 | 775 | } |
| 434 | 776 | |
| 435 | 777 | return in_array($this->status, [Status::SUBSCRIPTION_ACTIVE, Status::SUBSCRIPTION_TRIALING, Status::SUBSCRIPTION_PAUSED, Status::SUBSCRIPTION_INTENDED, Status::SUBSCRIPTION_PAST_DUE, Status::SUBSCRIPTION_FAILING, Status::SUBSCRIPTION_EXPIRING]); // past_due, is fallback for existing subscriptions, on new subscriptions update it will be expiring |
| @@ -436,11 +778,18 @@ | ||
| 436 | 778 | } |
| 437 | 779 | |
| 438 | 780 | public function canSwitchPaymentMethod() |
| 439 | 781 | { |
| 440 | - $gateway = App::gateway($this->current_payment_method); | |
| 782 | + // Switching moves the subscription onto ANOTHER gateway's vendor subscription | |
| 783 | + // (see PayPal SubscriptionManager::switchPaymentMethod — it creates a live | |
| 784 | + // PayPal subscription). A store-billed subscription is already owned by the | |
| 785 | + // invoice engine, so a vendor subscription would bill it a second time. The | |
| 786 | + // customer changes the card on file instead (canUpdatePaymentMethod). | |
| 787 | + if ($this->usesRenewalEngine()) { | |
| 788 | + return false; | |
| 789 | + } | |
| 441 | 790 | |
| 442 | - if (!$gateway || empty(Arr::get($gateway->supportedFeatures, 'switch_payment_method'))) { | |
| 791 | + if (!$this->switchPaymentConfig()) { | |
| 443 | 792 | return false; |
| 444 | 793 | } |
| 445 | 794 | |
| 446 | 795 | return in_array($this->status, [Status::SUBSCRIPTION_ACTIVE, Status::SUBSCRIPTION_TRIALING, Status::SUBSCRIPTION_PAUSED]); |
| @@ -447,36 +796,238 @@ | ||
| 447 | 796 | } |
| 448 | 797 | |
| 449 | 798 | public function switchablePaymentMethods() |
| 450 | 799 | { |
| 451 | - $gateway = App::gateway($this->current_payment_method); | |
| 452 | - if (!$gateway || empty($gateway->supportedFeatures['switch_payment_method'])) { | |
| 800 | + if (!$this->canSwitchPaymentMethod()) { | |
| 453 | 801 | return []; |
| 454 | 802 | } |
| 455 | 803 | |
| 456 | - return Arr::get($gateway->supportedFeatures, 'switch_payment_method.supported_gateways', []); | |
| 804 | + return Arr::get($this->switchPaymentConfig(), 'supported_gateways', []); | |
| 457 | 805 | } |
| 458 | 806 | |
| 459 | - public function canReactive() | |
| 807 | + public function canPause() | |
| 460 | 808 | { |
| 809 | + // Store-billed (manual/system) subscriptions can always be paused | |
| 810 | + // (unless already paused/canceled/expired) | |
| 811 | + if ($this->usesRenewalEngine()) { | |
| 812 | + return in_array($this->status, [ | |
| 813 | + Status::SUBSCRIPTION_ACTIVE, | |
| 814 | + Status::SUBSCRIPTION_TRIALING, | |
| 815 | + Status::SUBSCRIPTION_PAST_DUE, | |
| 816 | + Status::SUBSCRIPTION_EXPIRING | |
| 817 | + ]); | |
| 818 | + } | |
| 819 | + | |
| 820 | + // Automatic subscriptions require gateway support | |
| 821 | + $gateway = $this->resolveGateway(); | |
| 822 | + | |
| 823 | + if (!$gateway) { | |
| 824 | + return false; | |
| 825 | + } | |
| 826 | + | |
| 827 | + // Check if gateway supports pause | |
| 828 | + if (!$gateway->has('pause_subscription')) { | |
| 829 | + return false; | |
| 830 | + } | |
| 831 | + | |
| 832 | + // Default behavior for automatic subscriptions | |
| 833 | + return in_array($this->status, [ | |
| 834 | + Status::SUBSCRIPTION_ACTIVE, | |
| 835 | + Status::SUBSCRIPTION_TRIALING | |
| 836 | + ]) && !in_array($this->status, [ | |
| 837 | + Status::SUBSCRIPTION_PAUSED, | |
| 838 | + Status::SUBSCRIPTION_CANCELED, | |
| 839 | + Status::SUBSCRIPTION_EXPIRED, | |
| 840 | + Status::SUBSCRIPTION_COMPLETED | |
| 841 | + ]); | |
| 842 | + } | |
| 843 | + | |
| 844 | + /** | |
| 845 | + * A skip is pending when the current upcoming period was reached by an admin | |
| 846 | + * skip that has not yet elapsed — next_billing_date still equals the value the | |
| 847 | + * last skip set. Blocks stacking another skip onto the same pending window. | |
| 848 | + * | |
| 849 | + * @return bool | |
| 850 | + */ | |
| 851 | + public function hasPendingSkip(): bool | |
| 852 | + { | |
| 853 | + if (!$this->next_billing_date) { | |
| 854 | + return false; | |
| 855 | + } | |
| 856 | + | |
| 857 | + $skippedTo = $this->getMeta('pending_skip_until'); | |
| 858 | + | |
| 859 | + if (!$skippedTo) { | |
| 860 | + return false; | |
| 861 | + } | |
| 862 | + | |
| 863 | + return $skippedTo === $this->next_billing_date | |
| 864 | + && strtotime($this->next_billing_date) > time(); | |
| 865 | + } | |
| 866 | + | |
| 867 | + public function canResume() | |
| 868 | + { | |
| 869 | + // Store-billed (manual/system) subscriptions can be resumed from paused state | |
| 870 | + if ($this->usesRenewalEngine()) { | |
| 871 | + return $this->status === Status::SUBSCRIPTION_PAUSED; | |
| 872 | + } | |
| 873 | + | |
| 874 | + | |
| 875 | + $gateway = $this->resolveGateway(); | |
| 876 | + | |
| 877 | + if (!$gateway) { | |
| 878 | + return false; | |
| 879 | + } | |
| 880 | + | |
| 881 | + if (!$gateway->has('resume_subscription')) { | |
| 882 | + return false; | |
| 883 | + } | |
| 884 | + | |
| 885 | + // Default behavior | |
| 886 | + return $this->status === Status::SUBSCRIPTION_PAUSED; | |
| 887 | + } | |
| 888 | + | |
| 889 | + public function pauseSubscription($reason = '') | |
| 890 | + { | |
| 891 | + return SubscriptionService::pauseSubscription($this, $reason); | |
| 892 | + } | |
| 893 | + | |
| 894 | + public function resumeSubscription($reason = '') | |
| 895 | + { | |
| 896 | + return SubscriptionService::resumeSubscription($this, $reason); | |
| 897 | + } | |
| 898 | + | |
| 899 | + public function canUpdateDetails() | |
| 900 | + { | |
| 901 | + // Only store-billed (manual/system) subscriptions can be fully edited by | |
| 902 | + // admin — edits to a system subscription take effect on its next invoice. | |
| 903 | + return $this->usesRenewalEngine(); | |
| 904 | + } | |
| 905 | + | |
| 906 | + /** | |
| 907 | + * Vendor identifiers are the inverse case of canUpdateDetails(): only a | |
| 908 | + * gateway-billed subscription has them, and correcting them is the one | |
| 909 | + * admin write an automatic subscription accepts. Billing fields stay | |
| 910 | + * gateway-owned. | |
| 911 | + * | |
| 912 | + * Off by default — this is a migration/support repair tool, and the column it | |
| 913 | + * writes is what gateway webhooks resolve on. Enable with: | |
| 914 | + * | |
| 915 | + * add_filter('fluent_cart/subscription/vendor_id_editing_enabled', '__return_true'); | |
| 916 | + * | |
| 917 | + * @return bool | |
| 918 | + */ | |
| 919 | + public function canEditVendorIds(): bool | |
| 920 | + { | |
| 921 | + if (!apply_filters('fluent_cart/subscription/vendor_id_editing_enabled', false)) { | |
| 922 | + return false; | |
| 923 | + } | |
| 924 | + | |
| 925 | + if (!$this->isAutomatic() || !$this->current_payment_method) { | |
| 926 | + return false; | |
| 927 | + } | |
| 928 | + | |
| 929 | + // `expired` and `canceled` stay editable: a subscription usually lands there | |
| 930 | + // *because* the id was wrong (webhooks resolved to nothing), so those are the | |
| 931 | + // states the repair is needed in most. Sync from gateway has no status gate | |
| 932 | + // either. `completed` is a real end of term, not a lookup failure. | |
| 933 | + return strtolower($this->status) !== Status::SUBSCRIPTION_COMPLETED; | |
| 934 | + } | |
| 935 | + | |
| 936 | + /** | |
| 937 | + * Whether the gateway backing this subscription can look a candidate id up | |
| 938 | + * before it is saved. Editing does not depend on this — a gateway with no | |
| 939 | + * lookup still accepts a correction, it just cannot preview it. | |
| 940 | + * | |
| 941 | + * @return bool | |
| 942 | + */ | |
| 943 | + public function canVerifyVendorIds(): bool | |
| 944 | + { | |
| 945 | + if (!$this->canEditVendorIds()) { | |
| 946 | + return false; | |
| 947 | + } | |
| 948 | + | |
| 949 | + $gateway = App::gateway($this->current_payment_method); | |
| 950 | + | |
| 951 | + return $gateway && $gateway->has('subscriptions') && $gateway->has('verify_vendor_ids'); | |
| 952 | + } | |
| 953 | + | |
| 954 | + /** | |
| 955 | + * Update subscription details (for manual subscriptions) | |
| 956 | + * | |
| 957 | + * Allowed fields for manual subscriptions: | |
| 958 | + * - recurring_total: Update the next invoice/payment amount (in cents) | |
| 959 | + * - bill_times: Update the number of billing cycles (0 = unlimited) | |
| 960 | + * - billing_interval: Change billing frequency (daily, weekly, monthly, etc.) | |
| 961 | + * - expire_at: Update expiration date | |
| 962 | + * - trial_days: Update trial period | |
| 963 | + * - next_billing_date: Update next billing date | |
| 964 | + * | |
| 965 | + * @param array $data | |
| 966 | + * @return true|\WP_Error | |
| 967 | + */ | |
| 968 | + public function updateSubscription(array $data) | |
| 969 | + { | |
| 970 | + return SubscriptionService::updateSubscription($this, $data); | |
| 971 | + } | |
| 972 | + | |
| 973 | + /** | |
| 974 | + * Whether this subscription can be reactivated. | |
| 975 | + * | |
| 976 | + * Status-based for BOTH manual and automatic subscriptions — no gateway | |
| 977 | + * supportedFeatures branch on purpose. Manual reactivation is a local status | |
| 978 | + * flip; automatic reactivation runs through the Pro re-checkout flow | |
| 979 | + * (SubscriptionRenewalHandler builds an instant cart and the customer pays | |
| 980 | + * again), which works with any gateway. Gating on a gateway feature here | |
| 981 | + * would hide the customer-facing reactivate URL for Stripe/PayPal/etc. | |
| 982 | + * | |
| 983 | + * @return bool | |
| 984 | + */ | |
| 985 | + public function canReactivate() | |
| 986 | + { | |
| 461 | 987 | if (!App::isProActive()) { |
| 462 | - return ''; | |
| 988 | + return false; | |
| 463 | 989 | } |
| 464 | 990 | |
| 465 | 991 | if (isset($this->config['upgraded_to_sub_id']) || $this->recurring_amount <= 0) { |
| 466 | - return ''; | |
| 992 | + return false; | |
| 467 | 993 | } |
| 468 | 994 | |
| 469 | - $canReactivate = in_array($this->status, [Status::SUBSCRIPTION_CANCELED, Status::SUBSCRIPTION_FAILING, Status::SUBSCRIPTION_EXPIRED, Status::SUBSCRIPTION_PAUSED, Status::SUBSCRIPTION_EXPIRING, Status::SUBSCRIPTION_PAST_DUE]); | |
| 995 | + // Paused is intentionally excluded — a paused subscription resumes (see | |
| 996 | + // canResume()); reactivation is for terminal/lapsed states only. | |
| 997 | + $canReactivate = in_array($this->status, [ | |
| 998 | + Status::SUBSCRIPTION_CANCELED, | |
| 999 | + Status::SUBSCRIPTION_FAILING, | |
| 1000 | + Status::SUBSCRIPTION_EXPIRED, | |
| 1001 | + Status::SUBSCRIPTION_EXPIRING, | |
| 1002 | + Status::SUBSCRIPTION_PAST_DUE, | |
| 1003 | + ]); | |
| 470 | 1004 | |
| 471 | - return apply_filters('fluent_cart/subscription/can_reactivate', $canReactivate, [ | |
| 1005 | + return (bool) apply_filters('fluent_cart/subscription/can_reactivate', $canReactivate, [ | |
| 472 | 1006 | 'subscription' => $this |
| 473 | 1007 | ]); |
| 474 | 1008 | } |
| 475 | 1009 | |
| 1010 | + /** | |
| 1011 | + * @deprecated Use canReactivate(). Kept as a backward-compatible alias. | |
| 1012 | + * @return bool | |
| 1013 | + */ | |
| 1014 | + public function canReactive() | |
| 1015 | + { | |
| 1016 | + return $this->canReactivate(); | |
| 1017 | + } | |
| 1018 | + | |
| 1019 | + /** | |
| 1020 | + * These links are minted in email and webhook contexts, where there is no | |
| 1021 | + * current user. A wp_create_nonce() token bound to that user-less request | |
| 1022 | + * stops verifying the moment the recipient logs in to act on it, so the link | |
| 1023 | + * broke for the one journey it exists to serve. Authorization for the | |
| 1024 | + * endpoint is the subscription-ownership check on the handling side, which | |
| 1025 | + * a nonce never provided; the uuid alone is inert to anyone else. | |
| 1026 | + */ | |
| 476 | 1027 | public function getReactivateUrl() |
| 477 | 1028 | { |
| 478 | - if (!$this->canReactive()) { | |
| 1029 | + if (!$this->canReactivate()) { | |
| 479 | 1030 | return ''; |
| 480 | 1031 | } |
| 481 | 1032 | |
| 482 | 1033 | return add_query_arg([ |
| @@ -511,11 +1062,19 @@ | ||
| 511 | 1062 | if (in_array($this->status, $validAccessStatuses)) { |
| 512 | 1063 | return true; |
| 513 | 1064 | } |
| 514 | 1065 | |
| 1066 | + // Past-due/expiring/failing keep access while the unpaid invoice is inside its | |
| 1067 | + // dunning grace window; checkAndExpireSubscriptions() flips them to expired past that. | |
| 1068 | + if (in_array($this->status, [Status::SUBSCRIPTION_PAST_DUE, Status::SUBSCRIPTION_EXPIRING, Status::SUBSCRIPTION_FAILING])) { | |
| 1069 | + $dueTimestamp = $this->next_billing_date ? strtotime($this->next_billing_date) : 0; | |
| 1070 | + $graceDays = SubscriptionHelper::getGracePeriodDaysForInterval((string) $this->billing_interval); | |
| 1071 | + | |
| 1072 | + return $dueTimestamp && time() < $dueTimestamp + ($graceDays * DAY_IN_SECONDS); | |
| 1073 | + } | |
| 1074 | + | |
| 515 | 1075 | $invalidStatuses = [ |
| 516 | 1076 | Status::SUBSCRIPTION_EXPIRED, |
| 517 | - Status::SUBSCRIPTION_PAST_DUE, | |
| 518 | 1077 | Status::SUBSCRIPTION_INTENDED, |
| 519 | 1078 | Status::SUBSCRIPTION_PENDING |
| 520 | 1079 | ]; |
| 521 | 1080 | |
| @@ -538,9 +1097,9 @@ | ||
| 538 | 1097 | } |
| 539 | 1098 | |
| 540 | 1099 | public function reSyncFromRemote() |
| 541 | 1100 | { |
| 542 | - if ($gateway = App::gateway($this->current_payment_method)) { | |
| 1101 | + if ($gateway = $this->resolveGateway()) { | |
| 543 | 1102 | if ($gateway->has('subscriptions')) { |
| 544 | 1103 | return $gateway->subscriptions->reSyncSubscriptionFromRemote($this); |
| 545 | 1104 | } |
| 546 | 1105 | } |
| @@ -560,11 +1119,18 @@ | ||
| 560 | 1119 | if ($this->status === Status::SUBSCRIPTION_CANCELED) { |
| 561 | 1120 | return new \WP_Error('subscription_already_cancelled', __('This subscription is already cancelled.', 'fluent-cart')); |
| 562 | 1121 | } |
| 563 | 1122 | |
| 564 | - $gateway = App::gateway($this->current_payment_method); | |
| 1123 | + $gateway = $this->resolveGateway(); | |
| 565 | 1124 | |
| 566 | - if ($gateway && $gateway->has('subscriptions')) { | |
| 1125 | + // No vendor subscription (store-billed, or a vendor id that never landed) — | |
| 1126 | + // nothing to cancel at the gateway. | |
| 1127 | + if (!$this->vendor_subscription_id) { | |
| 1128 | + $vendorCanceled = null; | |
| 1129 | + $updateData = [ | |
| 1130 | + 'canceled_at' => gmdate('Y-m-d H:i:s', time()) | |
| 1131 | + ]; | |
| 1132 | + } elseif ($gateway && $gateway->has('subscriptions')) { | |
| 567 | 1133 | $cancelArgs = [ |
| 568 | 1134 | 'subscription_id' => $this->id, |
| 569 | 1135 | 'parent_order_id' => $this->parent_order_id, |
| 570 | 1136 | 'mode' => $this->order->mode, |
| @@ -580,8 +1146,9 @@ | ||
| 580 | 1146 | } |
| 581 | 1147 | |
| 582 | 1148 | $updateData = array_filter($vendorCanceled); |
| 583 | 1149 | } else { |
| 1150 | + // Vendor subscription exists but this gateway cannot cancel it — it stays live. | |
| 584 | 1151 | $vendorCanceled = new \WP_Error('invalid_payment_method', __('This payment method does not support remote subscription cancel', 'fluent-cart')); |
| 585 | 1152 | $updateData = [ |
| 586 | 1153 | 'canceled_at' => gmdate('Y-m-d H:i:s', time()) |
| 587 | 1154 | ]; |
| @@ -597,21 +1164,26 @@ | ||
| 597 | 1164 | $updateData['status'] = Status::SUBSCRIPTION_COMPLETED; |
| 598 | 1165 | $updateData['canceled_at'] = NULL; |
| 599 | 1166 | } |
| 600 | 1167 | |
| 601 | - $config = $this->config; | |
| 602 | - if ($args['reason']) { | |
| 603 | - $config['cancellation_reason'] = $args['reason']; | |
| 1168 | + if (Arr::get($args, 'effective_from') === 'immediately' && $updateData['status'] !== Status::SUBSCRIPTION_COMPLETED) { | |
| 1169 | + $updateData['next_billing_date'] = gmdate('Y-m-d H:i:s', time()); | |
| 604 | 1170 | } |
| 605 | - $updateData['config'] = $config; | |
| 606 | 1171 | |
| 607 | - if (Arr::get($args, 'effective_from') === 'immediately') { | |
| 608 | - $updateData['next_billing_date'] = gmdate('Y-m-d H:i:s', time()); | |
| 1172 | + // A completed (EOT) subscription has no upcoming billing — the immediate-cancel | |
| 1173 | + // date above must not resurrect one (SubscriptionEOT cancels remote subscriptions | |
| 1174 | + // with effective_from=immediately after syncSubscriptionStates nulled the date). | |
| 1175 | + if (Arr::get($updateData, 'status') === Status::SUBSCRIPTION_COMPLETED) { | |
| 1176 | + $updateData['next_billing_date'] = NULL; | |
| 609 | 1177 | } |
| 610 | 1178 | |
| 611 | 1179 | $this->fill($updateData); |
| 612 | 1180 | $this->save(); |
| 613 | 1181 | |
| 1182 | + if ($args['reason']) { | |
| 1183 | + $this->mergeConfig(['cancellation_reason' => $args['reason']]); | |
| 1184 | + } | |
| 1185 | + | |
| 614 | 1186 | $note = $args['note']; |
| 615 | 1187 | |
| 616 | 1188 | if (!$note) { |
| 617 | 1189 | $note = 'on customer request'; |
| @@ -616,10 +1188,11 @@ | ||
| 616 | 1188 | if (!$note) { |
| 617 | 1189 | $note = 'on customer request'; |
| 618 | 1190 | } |
| 619 | 1191 | |
| 620 | - if ($args['fire_hooks'] && $this->status !== Status::SUBSCRIPTION_COMPLETED) { | |
| 621 | - (new SubscriptionCanceled($this, $this->order, $this->order->customer, $note))->dispatch(); | |
| 1192 | + // Single cancel chokepoint — void open renewals, clear reminders, email once. | |
| 1193 | + if ($this->status === Status::SUBSCRIPTION_CANCELED) { | |
| 1194 | + SubscriptionService::finalizeCancellation($this, $note, (bool) $args['fire_hooks']); | |
| 622 | 1195 | } |
| 623 | 1196 | |
| 624 | 1197 | if ($args['note']) { |
| 625 | 1198 | $this->order->note = $note; |
| @@ -642,8 +1215,36 @@ | ||
| 642 | 1215 | |
| 643 | 1216 | return $this->recurring_total; |
| 644 | 1217 | } |
| 645 | 1218 | |
| 1219 | + /** | |
| 1220 | + * Cycles the remote (vendor) plan must bill at INITIAL checkout. | |
| 1221 | + * With a simulated trial the first installment is already collected outside | |
| 1222 | + * the remote recurring cycles (one-time charge, paid/free trial cycle), so | |
| 1223 | + * the remote plan only needs bill_times - 1. | |
| 1224 | + * | |
| 1225 | + * Only valid at initial checkout — do NOT use for renewals/reactivation | |
| 1226 | + * (payment-method switching also sets is_trial_days_simulated; renewal flows | |
| 1227 | + * must use getRequiredBillTimes() which is bill_count based). | |
| 1228 | + * | |
| 1229 | + * @return int 0 means unlimited | |
| 1230 | + */ | |
| 1231 | + public function getInitialRemoteBillTimes() | |
| 1232 | + { | |
| 1233 | + $billTimes = (int)$this->bill_times; | |
| 1234 | + | |
| 1235 | + if (!$billTimes) { | |
| 1236 | + return 0; | |
| 1237 | + } | |
| 1238 | + | |
| 1239 | + if (Arr::get($this->config, 'is_trial_days_simulated', 'no') === 'yes') { | |
| 1240 | + // never return 0 here — 0 means unlimited to the gateways | |
| 1241 | + $billTimes = max(1, $billTimes - 1); | |
| 1242 | + } | |
| 1243 | + | |
| 1244 | + return $billTimes; | |
| 1245 | + } | |
| 1246 | + | |
| 646 | 1247 | public function getRequiredBillTimes() |
| 647 | 1248 | { |
| 648 | 1249 | $billTimes = (int)$this->bill_times; |
| 649 | 1250 | |
| @@ -649,23 +1250,10 @@ | ||
| 649 | 1250 | |
| 650 | 1251 | if ($billTimes > 0) { |
| 651 | 1252 | $billTimes = $billTimes - $this->bill_count; |
| 652 | 1253 | if ($billTimes <= 0) { |
| 653 | - $transacactionsCount = OrderTransaction::query() | |
| 654 | - ->where('subscription_id', $this->id) | |
| 655 | - ->where('transaction_type', Status::TRANSACTION_TYPE_CHARGE) | |
| 656 | - ->where('status', Status::TRANSACTION_SUCCEEDED) | |
| 657 | - ->where('total', '>', 0) | |
| 658 | - ->count(); | |
| 1254 | + $transacactionsCount = $this->calculateBillCount(); | |
| 659 | 1255 | |
| 660 | - $earlyPaymentHistory = $this->getMeta('early_payment_history', []); | |
| 661 | - foreach ($earlyPaymentHistory as $earlyPayment) { | |
| 662 | - $paidCount = (int) Arr::get($earlyPayment, 'count', 1); | |
| 663 | - if ($paidCount > 1) { | |
| 664 | - $transacactionsCount += ($paidCount - 1); | |
| 665 | - } | |
| 666 | - } | |
| 667 | - | |
| 668 | 1256 | if ($transacactionsCount != $this->bill_count) { |
| 669 | 1257 | $this->bill_count = $transacactionsCount; |
| 670 | 1258 | $this->save(); |
| 671 | 1259 | } |
| @@ -681,11 +1269,172 @@ | ||
| 681 | 1269 | |
| 682 | 1270 | return $billTimes; |
| 683 | 1271 | } |
| 684 | 1272 | |
| 1273 | + /** | |
| 1274 | + * Canonical bill_count formula. Every writer of bill_count must go through | |
| 1275 | + * this — a separate ad hoc count (e.g. StripeGateway\SubscriptionsManager | |
| 1276 | + * previously) silently drops the offset/deduction corrections below and | |
| 1277 | + * reports a wrong count until the next recompute. | |
| 1278 | + * | |
| 1279 | + * total > 0 CHARGE transactions linked to this subscription, adjusted for | |
| 1280 | + * the two one-time corrections decided at creation (see | |
| 1281 | + * CheckoutProcessor::syncInitialCycleCounting): | |
| 1282 | + * - billed_cycles_offset: free simulated-trial first cycle consumed a | |
| 1283 | + * cycle without producing a total > 0 transaction. | |
| 1284 | + * - billed_cycles_deduction: real-trial signup-fee-only charge is a | |
| 1285 | + * total > 0 transaction but isn't a billed cycle. | |
| 1286 | + */ | |
| 1287 | + public function calculateBillCount() | |
| 1288 | + { | |
| 1289 | + $transacactionsCount = OrderTransaction::query() | |
| 1290 | + ->where('subscription_id', $this->id) | |
| 1291 | + ->where('transaction_type', Status::TRANSACTION_TYPE_CHARGE) | |
| 1292 | + ->where('status', Status::TRANSACTION_SUCCEEDED) | |
| 1293 | + ->where('total', '>', 0) | |
| 1294 | + ->count(); | |
| 1295 | + | |
| 1296 | + $earlyPaymentHistory = $this->getMeta('early_payment_history', []); | |
| 1297 | + foreach ((array)$earlyPaymentHistory as $earlyPayment) { | |
| 1298 | + $paidCount = (int) Arr::get($earlyPayment, 'count', 1); | |
| 1299 | + if ($paidCount > 1) { | |
| 1300 | + $transacactionsCount += ($paidCount - 1); | |
| 1301 | + } | |
| 1302 | + } | |
| 1303 | + | |
| 1304 | + $transacactionsCount += (int) $this->getMeta('billed_cycles_offset', 0); | |
| 1305 | + $transacactionsCount -= (int) $this->getMeta('billed_cycles_deduction', 0); | |
| 1306 | + | |
| 1307 | + return $transacactionsCount; | |
| 1308 | + } | |
| 1309 | + | |
| 1310 | + /** | |
| 1311 | + * Installment / split-pay plan: a finite-term subscription (a lifetime | |
| 1312 | + * license paid off in a fixed number of charges), as opposed to an | |
| 1313 | + * open-ended recurring subscription. The canonical structural signal is | |
| 1314 | + * bill_times > 0 (0 = infinite/open-ended). Reused across analytics, | |
| 1315 | + * filters and lifecycle handling — do NOT reintroduce title-string | |
| 1316 | + * ("Split") matching, which the data does not reliably carry. | |
| 1317 | + * | |
| 1318 | + * @return bool | |
| 1319 | + */ | |
| 1320 | + public function isInstallment() | |
| 1321 | + { | |
| 1322 | + return (int) $this->bill_times > 0; | |
| 1323 | + } | |
| 1324 | + | |
| 1325 | + /** | |
| 1326 | + * Installments still owed: 0 for open-ended plans, or once the term is | |
| 1327 | + * fully paid. | |
| 1328 | + * | |
| 1329 | + * @return int | |
| 1330 | + */ | |
| 1331 | + public function installmentsRemaining() | |
| 1332 | + { | |
| 1333 | + if (!$this->isInstallment()) { | |
| 1334 | + return 0; | |
| 1335 | + } | |
| 1336 | + | |
| 1337 | + return max(0, (int) $this->bill_times - (int) $this->bill_count); | |
| 1338 | + } | |
| 1339 | + | |
| 1340 | + /** | |
| 1341 | + * Has a finite installment plan collected every scheduled charge (end of | |
| 1342 | + * term)? Open-ended plans never reach term end. | |
| 1343 | + * | |
| 1344 | + * @return bool | |
| 1345 | + */ | |
| 1346 | + public function hasReachedTermEnd() | |
| 1347 | + { | |
| 1348 | + return $this->isInstallment() && (int) $this->bill_count >= (int) $this->bill_times; | |
| 1349 | + } | |
| 1350 | + | |
| 1351 | + /** | |
| 1352 | + * Full committed price of an installment contract: recurring_total x | |
| 1353 | + * bill_times, in cents. 0 for open-ended plans (no fixed total). This is | |
| 1354 | + * the per-row form of the SUM(recurring_total * bill_times) used by the | |
| 1355 | + * subscription analytics aggregate. | |
| 1356 | + * | |
| 1357 | + * @return int | |
| 1358 | + */ | |
| 1359 | + public function totalContractValue() | |
| 1360 | + { | |
| 1361 | + if (!$this->isInstallment()) { | |
| 1362 | + return 0; | |
| 1363 | + } | |
| 1364 | + | |
| 1365 | + return (int) $this->recurring_total * (int) $this->bill_times; | |
| 1366 | + } | |
| 1367 | + | |
| 1368 | + /** | |
| 1369 | + * Filter by plan type: 'installment' (finite term, bill_times > 0), | |
| 1370 | + * 'recurring' (open-ended, bill_times = 0) or anything else (no filter). | |
| 1371 | + * The bill_times threshold is kept identical to isInstallment() so the SQL | |
| 1372 | + * and PHP definitions never drift apart. | |
| 1373 | + */ | |
| 1374 | + public function scopeOfPlanType($query, $planType) | |
| 1375 | + { | |
| 1376 | + if ($planType === 'installment') { | |
| 1377 | + return $query->where('bill_times', '>', 0); | |
| 1378 | + } | |
| 1379 | + if ($planType === 'recurring') { | |
| 1380 | + return $query->where('bill_times', '<=', 0); | |
| 1381 | + } | |
| 1382 | + | |
| 1383 | + return $query; | |
| 1384 | + } | |
| 1385 | + | |
| 1386 | + /** | |
| 1387 | + * Whether a lapsed/canceled subscription still has unexpired paid time to | |
| 1388 | + * credit back on reactivation. Deliberately NOT hasAccessValidity() — that | |
| 1389 | + * method answers "can the customer access content right now" and its status | |
| 1390 | + * list is free to evolve for that purpose alone. This is its own copy so a | |
| 1391 | + * future access-only change (e.g. a new status added for content gating) | |
| 1392 | + * can't silently change how much reactivation trial credit gets granted. | |
| 1393 | + * | |
| 1394 | + * @return bool | |
| 1395 | + */ | |
| 1396 | + public function hasReactivationTrialCredit(): bool | |
| 1397 | + { | |
| 1398 | + $validStatuses = [ | |
| 1399 | + Status::SUBSCRIPTION_ACTIVE, | |
| 1400 | + Status::SUBSCRIPTION_TRIALING, | |
| 1401 | + Status::SUBSCRIPTION_COMPLETED | |
| 1402 | + ]; | |
| 1403 | + | |
| 1404 | + if (in_array($this->status, $validStatuses)) { | |
| 1405 | + return true; | |
| 1406 | + } | |
| 1407 | + | |
| 1408 | + // No grace-period math here on purpose: past_due/expiring/failing fall through | |
| 1409 | + // to the plain next_billing_date > now check below. If that date is still | |
| 1410 | + // future, credit is granted same as any other status; if it's past, this | |
| 1411 | + // returns false the same way the grace window would eventually clamp to via | |
| 1412 | + // getReactivationTrialDays()'s <=1 floor — without a redundant grace-days | |
| 1413 | + // lookup either way. | |
| 1414 | + | |
| 1415 | + $invalidStatuses = [ | |
| 1416 | + Status::SUBSCRIPTION_EXPIRED, | |
| 1417 | + Status::SUBSCRIPTION_INTENDED, | |
| 1418 | + Status::SUBSCRIPTION_PENDING | |
| 1419 | + ]; | |
| 1420 | + | |
| 1421 | + if (in_array($this->status, $invalidStatuses)) { | |
| 1422 | + return false; | |
| 1423 | + } | |
| 1424 | + | |
| 1425 | + $nextBillingDate = $this->next_billing_date; | |
| 1426 | + | |
| 1427 | + if (!$nextBillingDate) { | |
| 1428 | + $nextBillingDate = $this->guessNextBillingDate(); | |
| 1429 | + } | |
| 1430 | + | |
| 1431 | + return strtotime($nextBillingDate) > time(); | |
| 1432 | + } | |
| 1433 | + | |
| 685 | 1434 | public function getReactivationTrialDays() |
| 686 | 1435 | { |
| 687 | - if (!$this->hasAccessValidity()) { | |
| 1436 | + if (!$this->hasReactivationTrialCredit()) { | |
| 688 | 1437 | return 0; |
| 689 | 1438 | } |
| 690 | 1439 | |
| 691 | 1440 | $lastPaidTransaction = OrderTransaction::query() |
| @@ -744,16 +1493,17 @@ | ||
| 744 | 1493 | ->whereIn('payment_status', Status::getOrderPaymentSuccessStatuses()) |
| 745 | 1494 | ->first(); |
| 746 | 1495 | |
| 747 | 1496 | if ($theLastOrder) { |
| 748 | - $days = PaymentHelper::getIntervalDays($this->billing_interval); | |
| 1497 | + $paidAnchor = SubscriptionHelper::resolvePaidAnchor($theLastOrder); | |
| 1498 | + | |
| 749 | 1499 | if ($theLastOrder->type == 'renewal') { |
| 750 | - $nextBillingDate = gmdate('Y-m-d H:i:s', strtotime($theLastOrder->created_at) + $days * DAY_IN_SECONDS); | |
| 1500 | + $nextBillingDate = gmdate('Y-m-d H:i:s', SubscriptionHelper::addBillingInterval($paidAnchor, $this->billing_interval, SubscriptionHelper::getBillingSchedule($this))); | |
| 751 | 1501 | } else { |
| 752 | 1502 | if ($this->trial_days) { |
| 753 | - $nextBillingDate = gmdate('Y-m-d H:i:s', strtotime($theLastOrder->created_at) + (int)($this->trial_days) * DAY_IN_SECONDS); | |
| 1503 | + $nextBillingDate = gmdate('Y-m-d H:i:s', strtotime($paidAnchor) + (int)($this->trial_days) * DAY_IN_SECONDS); | |
| 754 | 1504 | } else { |
| 755 | - $nextBillingDate = gmdate('Y-m-d H:i:s', strtotime($theLastOrder->created_at) + $days * DAY_IN_SECONDS); | |
| 1505 | + $nextBillingDate = gmdate('Y-m-d H:i:s', SubscriptionHelper::addBillingInterval($paidAnchor, $this->billing_interval, SubscriptionHelper::getBillingSchedule($this))); | |
| 756 | 1506 | } |
| 757 | 1507 | } |
| 758 | 1508 | } else { |
| 759 | 1509 | $nextBillingDate = gmdate('Y-m-d H:i:s', strtotime($this->created_at) + (int)($this->trial_days) * DAY_IN_SECONDS); |
| @@ -770,9 +1520,9 @@ | ||
| 770 | 1520 | * |
| 771 | 1521 | * Processes all candidates in batches to avoid memory issues. |
| 772 | 1522 | * The query example works as follows: |
| 773 | 1523 | * SELECT * FROM subscriptions WHERE |
| 774 | - status IN ('active', 'trialing', 'canceled') | |
| 1524 | + status IN ('active', 'trialing', 'canceled', 'expiring', 'failing', 'past_due') | |
| 775 | 1525 | AND next_billing_date IS NOT NULL |
| 776 | 1526 | AND id > 0 -- last processed ID for batch cursor |
| 777 | 1527 | AND next_billing_date < DATE_SUB( |
| 778 | 1528 | '2026-02-17 10:00:00', |
| @@ -815,20 +1565,26 @@ | ||
| 815 | 1565 | foreach ($gracePeriodDays as $interval => $days) { |
| 816 | 1566 | $cutoffDates[$interval] = gmdate('Y-m-d H:i:s', $currentTime - ((int)$days * DAY_IN_SECONDS)); |
| 817 | 1567 | } |
| 818 | 1568 | |
| 1569 | + // Fallback cutoff for unknown/null billing intervals. | |
| 819 | 1570 | $defaultGraceDays = 7; |
| 820 | 1571 | $defaultCutoff = gmdate('Y-m-d H:i:s', $currentTime - ($defaultGraceDays * DAY_IN_SECONDS)); |
| 821 | 1572 | $knownIntervals = array_keys($cutoffDates); |
| 822 | 1573 | |
| 1574 | + // Include canceled subscriptions to check if validity is yet to expired | |
| 1575 | + // Exclude store-billed (manual/system) subscriptions — their expiry is | |
| 1576 | + // handled by the invoice-based overdue flow | |
| 823 | 1577 | $subscriptions = Subscription::query() |
| 824 | 1578 | ->whereIn('status', [ |
| 825 | 1579 | Status::SUBSCRIPTION_ACTIVE, |
| 826 | 1580 | Status::SUBSCRIPTION_TRIALING, |
| 827 | 1581 | Status::SUBSCRIPTION_CANCELED, |
| 828 | - Status::SUBSCRIPTION_EXPIRING | |
| 829 | - | |
| 1582 | + Status::SUBSCRIPTION_EXPIRING, | |
| 1583 | + Status::SUBSCRIPTION_FAILING, | |
| 1584 | + Status::SUBSCRIPTION_PAST_DUE | |
| 830 | 1585 | ]) |
| 1586 | + ->whereNotIn('collection_method', ['manual', 'system']) | |
| 831 | 1587 | ->whereNotNull('next_billing_date') |
| 832 | 1588 | ->where('next_billing_date', '>', '0000-00-00 00:00:00') |
| 833 | 1589 | ->where('id', '>', $lastId) |
| 834 | 1590 | ->where(function ($query) use ($now, $cutoffDates, $knownIntervals, $defaultCutoff) { |
| @@ -836,11 +1592,14 @@ | ||
| 836 | 1592 | $subQuery->whereIn('status', [ |
| 837 | 1593 | Status::SUBSCRIPTION_ACTIVE, |
| 838 | 1594 | Status::SUBSCRIPTION_TRIALING, |
| 839 | 1595 | Status::SUBSCRIPTION_EXPIRING, |
| 1596 | + Status::SUBSCRIPTION_FAILING, | |
| 1597 | + Status::SUBSCRIPTION_PAST_DUE, | |
| 840 | 1598 | ])->where(function ($dateQuery) use ($cutoffDates, $knownIntervals, $defaultCutoff) { |
| 841 | 1599 | $index = 0; |
| 842 | 1600 | |
| 1601 | + // OR together one (interval + its cutoff) clause per known interval. | |
| 843 | 1602 | foreach ($cutoffDates as $interval => $cutoff) { |
| 844 | 1603 | $method = $index === 0 ? 'where' : 'orWhere'; |
| 845 | 1604 | |
| 846 | 1605 | $dateQuery->{$method}(function ($intervalQuery) use ($interval, $cutoff) { |
| @@ -850,8 +1609,9 @@ | ||
| 850 | 1609 | |
| 851 | 1610 | $index++; |
| 852 | 1611 | } |
| 853 | 1612 | |
| 1613 | + // Unknown/null intervals fall back to the default cutoff. | |
| 854 | 1614 | $dateQuery->orWhere(function ($intervalQuery) use ($knownIntervals, $defaultCutoff) { |
| 855 | 1615 | $intervalQuery->where(function ($unknownIntervalQuery) use ($knownIntervals) { |
| 856 | 1616 | $unknownIntervalQuery->whereNotIn('billing_interval', $knownIntervals) |
| 857 | 1617 | ->orWhereNull('billing_interval'); |
| @@ -857,8 +1617,9 @@ | ||
| 857 | 1617 | ->orWhereNull('billing_interval'); |
| 858 | 1618 | })->where('next_billing_date', '<', $defaultCutoff); |
| 859 | 1619 | }); |
| 860 | 1620 | }); |
| 1621 | + // Branch B: canceled subs expire the moment their paid period ends (no grace). | |
| 861 | 1622 | })->orWhere(function ($subQuery) use ($now) { |
| 862 | 1623 | $subQuery->where('status', Status::SUBSCRIPTION_CANCELED) |
| 863 | 1624 | ->where('next_billing_date', '<', $now); |
| 864 | 1625 | }); |
| @@ -877,21 +1638,26 @@ | ||
| 877 | 1638 | |
| 878 | 1639 | foreach ($subscriptions as $subscription) { |
| 879 | 1640 | $nextBillingTimestamp = strtotime($subscription->next_billing_date); |
| 880 | 1641 | |
| 1642 | + // Skip unparseable/invalid dates. | |
| 881 | 1643 | if (!$nextBillingTimestamp || $nextBillingTimestamp <= 0) { |
| 882 | 1644 | continue; |
| 883 | 1645 | } |
| 884 | 1646 | |
| 1647 | + // Re-validate in PHP (SQL was a coarse filter) and derive the exact cutoff used as a write guard below. | |
| 885 | 1648 | if ($subscription->status === Status::SUBSCRIPTION_CANCELED) { |
| 1649 | + // Superseded by an upgrade -> the new sub owns validity, leave this one alone. | |
| 886 | 1650 | if (isset($subscription->config['upgraded_to_sub_id'])) { |
| 887 | 1651 | continue; |
| 888 | 1652 | } |
| 889 | 1653 | |
| 1654 | + // Already processed in a prior run. | |
| 890 | 1655 | if ($subscription->getMeta('validity_expired_at')) { |
| 891 | 1656 | continue; |
| 892 | 1657 | } |
| 893 | 1658 | |
| 1659 | + // Paid period not over yet. | |
| 894 | 1660 | if ($nextBillingTimestamp >= $currentTime) { |
| 895 | 1661 | continue; |
| 896 | 1662 | } |
| 897 | 1663 | |
| @@ -900,8 +1666,9 @@ | ||
| 900 | 1666 | $graceDays = $gracePeriodDays[$subscription->billing_interval] ?? $defaultGraceDays; |
| 901 | 1667 | $graceDays = max(0, (int)$graceDays); |
| 902 | 1668 | $cutoffTimestamp = $currentTime - ($graceDays * DAY_IN_SECONDS); |
| 903 | 1669 | |
| 1670 | + // Still inside the grace window. | |
| 904 | 1671 | if ($nextBillingTimestamp >= $cutoffTimestamp) { |
| 905 | 1672 | continue; |
| 906 | 1673 | } |
| 907 | 1674 | |
| @@ -907,21 +1674,24 @@ | ||
| 907 | 1674 | |
| 908 | 1675 | $cutoff = gmdate('Y-m-d H:i:s', $cutoffTimestamp); |
| 909 | 1676 | } |
| 910 | 1677 | |
| 1678 | + // Null out next_billing_date so the row can't be re-selected/re-processed. | |
| 911 | 1679 | $updateData = [ |
| 912 | 1680 | 'next_billing_date' => NULL, |
| 913 | 1681 | 'updated_at' => gmdate('Y-m-d H:i:s', $currentTime), |
| 914 | 1682 | ]; |
| 915 | 1683 | |
| 1684 | + // Canceled subs keep their status; only billing statuses flip to EXPIRED. | |
| 916 | 1685 | if ($subscription->status !== Status::SUBSCRIPTION_CANCELED) { |
| 917 | 1686 | $updateData['status'] = Status::SUBSCRIPTION_EXPIRED; |
| 918 | 1687 | } |
| 919 | 1688 | |
| 1689 | + // Optimistic-lock write: only apply if status + past-cutoff still hold, so a concurrent | |
| 1690 | + // renewal/cancel between SELECT and UPDATE can't be overwritten with a stale decision. | |
| 920 | 1691 | $updated = Subscription::query() |
| 921 | 1692 | ->where('id', $subscription->id) |
| 922 | 1693 | ->where('status', $subscription->status) |
| 923 | - ->where('next_billing_date', $subscription->next_billing_date) | |
| 924 | 1694 | ->where('next_billing_date', '<', $cutoff) |
| 925 | 1695 | ->update($updateData); |
| 926 | 1696 | |
| 927 | 1697 | if (!$updated) { |
| @@ -935,8 +1705,9 @@ | ||
| 935 | 1705 | if (!$subscription) { |
| 936 | 1706 | continue; |
| 937 | 1707 | } |
| 938 | 1708 | |
| 1709 | + // Idempotency marker + audit timestamp for this expiry. | |
| 939 | 1710 | $subscription->updateMeta('validity_expired_at', gmdate('Y-m-d H:i:s', $currentTime)); |
| 940 | 1711 | |
| 941 | 1712 | $event = new \FluentCart\App\Events\Subscription\SubscriptionValidityExpired( |
| 942 | 1713 | $subscription, |
