PHP is now generally available

// The evolution of PHP type safety
// PHP 5 - No type hints
function process($data) { /* ... */ }

// PHP 7 - Basic scalar type hints
function process(array $data): array { /* ... */ }

// PHP 8 - Full type system with union types and nullability
function process(array $data, ?Logger $logger = null): array|JsonResponse 
{
    // Type-safe operations with IDE support
    return $data['success'] ? $data : new JsonResponse($data);
}

class Payment
{
    public string $id;
    public float $amount;
    public Currency $currency;
    public Status $status;
    public \DateTime $createdAt;
    public ?string $description;
    public Customer|Organization $owner;

    public function __construct(
        string $id,
        float $amount,
        Currency $currency,
        Status $status,
        \DateTime $createdAt,
        ?string $description,
        Customer|Organization $owner
    ) {
        $this->id = $id;
        $this->amount = $amount;
        $this->currency = $currency;
        $this->status = $status;
        $this->createdAt = $createdAt;
        $this->description = $description;
        $this->owner = $owner;
    }
}

/**
 * Process payments with enhanced type safety
 * 
 * @param array<Transaction> $transactions List of transactions to process
 * @param ?PaymentProvider $provider Optional payment provider
 * @return array<Receipt>|ErrorResponse Collection of receipts or error response
 */
function processPayments(
    array $transactions, 
    ?PaymentProvider $provider = null
): array|ErrorResponse 
{
    // Enhanced type-safe operations with IDE support for collection types
    // Your IDE now knows $transactions contains only Transaction objects
    // and the return value is either an array of Receipt objects or an ErrorResponse
}

// Problem with regular floats/integers
$regularFloat = 0.1 + 0.2;
echo $regularFloat;  // Outputs: 0.30000000000000004 (precision error)

// With our Decimal support
use YourAPI\Types\Decimal;
$preciseDecimal = new Decimal('0.1')->add(new Decimal('0.2'));
echo $preciseDecimal;  // Outputs: 0.3 (exact precision)

// Creating a transaction with precise decimal amounts
$transaction = $client->transactions->create([
    'amount' => new Decimal('1234.56789012345'),
    'accountId' => new BigInt('9007199254740991'),
    'exchangeRate' => new Decimal('1.2345678901234567890')
]);

// Performing precise calculations with returned values
$fee = $transaction->amount->multiply(new Decimal('0.029'));
$netAmount = $transaction->amount->subtract($fee);

echo "Transaction Amount: {$transaction->amount}\n";
echo "Fee (2.9%): {$fee}\n";
echo "Net Amount: {$netAmount}\n";

// Initialize client with OAuth credentials
$client = Client::builder()
    ->setSecurity(new Security(
        $clientId = 'your-client-id', 
        $clientSecret = 'your-client-secret'
    ))
    ->build();

// Generate authorization URL - redirect URL is configured at the provider level
$authUrl = $client->auth()->getAuthorizationUrl([
    'scopes' => ['read', 'write'],
    'state' => $csrf_token
]);

// Redirect user to $authUrl

// In your callback handler:
$tokens = $client->auth()->exchangeCode($code);

// The client will automatically use and refresh tokens for future requests
$response = $client->resources->list();

composer require your-api/laravel-sdk

// In config/app.php
'providers' => [
    // Other Service Providers...
    YourAPI\Laravel\YourAPIServiceProvider::class,
],

// In .env
YOUR_API_KEY=sk_test_123456789
YOUR_API_ENVIRONMENT=sandbox

use YourAPI\Client;
use YourAPI\Resources\Payment;
use YourAPI\Exceptions\ApiException;
use Illuminate\Http\Request;

class PaymentController extends Controller
{
    public function __construct(
        private Client $client,  // Auto-injected from the service container
    ) {}
    
    public function processPayment(Request $request)
    {
        try {
            $payment = $this->client->payments->create([
                'amount' => $request->input('amount'),
                'currency' => Currency::USD,
                'description' => $request->input('description'),
                'metadata' => [
                    'order_id' => $request->input('order_id'),
                    'customer_id' => auth()->id(),
                ],
            ]);
            
            // Store payment reference in your database
            $order = Order::find($request->input('order_id'));
            $order->payment_id = $payment->id;
            $order->payment_status = $payment->status;
            $order->save();
            
            return view('payment.confirmation', ['payment' => $payment]);
        } catch (ApiException $e) {
            // Comprehensive error handling with specific error types
            return back()->withErrors([
                'payment' => $e->getMessage(),
                'error_code' => $e->getErrorCode(),
                'error_type' => $e->getErrorType(),
            ]);
        }
    }
}

<?php

namespace App\Services;

use App\Models\Customer;
use App\Models\Subscription;
use YourAPI\Client;
use YourAPI\Types\Decimal;
use YourAPI\Exceptions\ApiException;

class SubscriptionService
{
    private Client $client;
    
    public function __construct(Client $client)
    {
        $this->client = $client;
        
        // Register telemetry hooks for observability
        $this->client->registerHook(new YourAPI\Hooks\BeforeRequestHook());
        $this->client->registerHook(new YourAPI\Hooks\AfterResponseHook());
    }
    
    /**
     * Create a new subscription for a customer
     */
    public function createSubscription(Customer $customer, string $planId): Subscription
    {
        try {
            // Create the subscription with typed parameters
            $paymentSubscription = $this->client->subscriptions->create([
                'customer' => $customer->payment_customer_id,
                'plan' => $planId,
                'billing_cycle_anchor' => new \DateTime('first day of next month'),
                'proration_behavior' => 'none',
            ]);
            
            // Persist subscription details to local database
            $subscription = new Subscription([
                'customer_id' => $customer->id,
                'payment_subscription_id' => $paymentSubscription->id,
                'status' => $paymentSubscription->status,
            ]);
            
            $subscription->save();
            return $subscription;
            
        } catch (ApiException $e) {
            // Type-safe error handling with specific exception types
            throw new PaymentFailedException($e->getUserFacingMessage());
        }
    }
    
    /**
     * Process transactions for reconciliation with auto-pagination
     */
    public function reconcileTransactions(\DateTime $startDate, \DateTime $endDate): array
    {
        $summary = [
            'total' => 0,
            'successful' => 0,
            'total_amount' => new Decimal('0'),
        ];
        
        // SDK handles pagination automatically
        $transactions = $this->client->transactions->list([
            'created' => [
                'gte' => $startDate->format('Y-m-d'),
                'lte' => $endDate->format('Y-m-d'),
            ],
        ]);
        
        // Auto-paginating iterator
        foreach ($transactions as $transaction) {
            $summary['total']++;
            
            if ($transaction->status === 'succeeded') {
                $summary['successful']++;
                $summary['total_amount'] = $summary['total_amount']->add($transaction->amount);
            }
        }
        
        return $summary;
    }
}