StripeWebhookController.php

<?php

namespace App\Http\Controllers\Ipn;

use App\Http\Controllers\Controller;
use App\Models\ClientSubscription;
use App\Models\Payment;
use App\Models\Invoice;
use App\Models\Project;
use App\Models\User;
use App\Models\VerificationOrder;
use App\Services\EmailTemplateService;
use Illuminate\Http\Request;
use Illuminate\Support\Facades\Log;
use Stripe\Event;
use Stripe\Webhook;

/**
 * Handles incoming Stripe webhook events for payment lifecycle management.
 *
 * Registered at: POST /stripe/webhook
 * Processes: checkout.session.completed, invoice.paid, customer.subscription.deleted
 *
 * All handlers are idempotent — safe to replay without side-effects.
 */
class StripeWebhookController extends Controller
{
    public function handle(Request $request)
    {
        // Verify signature, deserialise event, dispatch to private handler
        // ...
    }

    private function handleSubscriptionCheckoutCompleted(object $session): void
    {
        // Resolve subscription and project from $session->metadata
        // Idempotency guard: skip if Payment already exists for this session
        // Activate project → activate subscription → record Payment + Invoice
        // Send 'subscription-activated' email via EmailTemplateService
        // ...
    }

    private function handleOrderCheckoutCompleted(object $session): void
    {
        // Resolve VerificationOrder from $session->metadata['order_id']
        // Idempotency guard: skip if Payment already exists for this session
        // Mark order CONFIRMED → record Payment → send 'order-paid' email
        // ...
    }

    private function handleInvoicePaid(object $invoice): void
    {
        // Record renewal Invoice and extend subscription renewal_at
        // ...
    }

    private function handleSubscriptionDeleted(object $subscription): void
    {
        // Cancel the matching ClientSubscription on the platform side
        // ...
    }
}