PHP Interfaces vs Abstract Classes — Silent Refund Failure

<?php

// The interface defines the CONTRACT — every payment gateway must
// implement ALL of these methods, with exactly these signatures.
interface PaymentGatewayInterface
{
    // Charge a customer a given amount in cents; return a transaction ID.
    public function charge(int $amountInCents, string $currency, string $paymentToken): string;

    // Refund a previous transaction by its ID; return true on success.
    public function refund(string $transactionId): bool;

    // Retrieve the human-readable name of this gateway (e.g. "Stripe").
    public function getGatewayName(): string;
}

// ---------------------------------------------------------------
// Concrete implementation #1: Stripe
// ---------------------------------------------------------------
class StripeGateway implements PaymentGatewayInterface
{
    public function charge(int $amountInCents, string $currency, string $paymentToken): string
    {
        // In a real app you'd call the Stripe SDK here.
        // We're simulating a successful charge and returning a fake transaction ID.
        $transactionId = 'stripe_txn_' . uniqid();
        echo "[Stripe] Charged {$amountInCents} {$currency}. Transaction: {$transactionId}\n";
        return $transactionId;
    }

    public function refund(string $transactionId): bool
    {
        echo "[Stripe] Refunded transaction: {$transactionId}\n";
        return true; // Simulate a successful refund.
    }

    public function getGatewayName(): string
    {
        return 'Stripe';
    }
}

// ---------------------------------------------------------------
// Concrete implementation #2: PayPal
// ---------------------------------------------------------------
class PayPalGateway implements PaymentGatewayInterface
{
    public function charge(int $amountInCents, string $currency, string $paymentToken): string
    {
        $transactionId = 'paypal_txn_' . uniqid();
        echo "[PayPal] Charged {$amountInCents} {$currency}. Transaction: {$transactionId}\n";
        return $transactionId;
    }

    public function refund(string $transactionId): bool
    {
        echo "[PayPal] Refunded transaction: {$transactionId}\n";
        return true;
    }

    public function getGatewayName(): string
    {
        return 'PayPal';
    }
}

// ---------------------------------------------------------------
// This service type-hints against the INTERFACE, not a concrete class.
// Swap Stripe for PayPal (or a mock) and this code never changes.
// ---------------------------------------------------------------
class InvoiceService
{
    // We accept ANYTHING that honours the PaymentGatewayInterface contract.
    public function __construct(private PaymentGatewayInterface $gateway) {}

    public function billCustomer(int $amountInCents, string $currency, string $token): void
    {
        $txnId = $this->gateway->charge($amountInCents, $currency, $token);
        echo "Invoice created for transaction: {$txnId} via " . $this->gateway->getGatewayName() . "\n";
    }
}

// ---------------------------------------------------------------
// Wiring it together
// ---------------------------------------------------------------
$stripeService = new InvoiceService(new StripeGateway());
$stripeService->billCustomer(4999, 'USD', 'tok_visa_test');

$paypalService = new InvoiceService(new PayPalGateway());
$paypalService->billCustomer(1999, 'GBP', 'paypal_token_abc');

<?php

// The abstract class provides the SHARED skeleton.
// It cannot be instantiated directly — you must extend it.
abstract class Notification
{
    // Concrete shared property — all notifications have a recipient.
    protected string $recipientAddress;
    protected string $messageBody;

    public function __construct(string $recipientAddress, string $messageBody)
    {
        $this->recipientAddress = $recipientAddress;
        $this->messageBody = $messageBody;
    }

    // CONCRETE method — shared logic every child inherits for free.
    // No child class needs to rewrite this.
    protected function logDispatch(string $channelName): void
    {
        $timestamp = date('Y-m-d H:i:s');
        echo "[{$timestamp}] [{$channelName}] Notification dispatched to: {$this->recipientAddress}\n";
    }

    // CONCRETE method — shared validation all channels must pass through.
    protected function validateRecipient(): void
    {
        if (empty(trim($this->recipientAddress))) {
            // Throwing here means no child class can accidentally skip validation.
            throw new InvalidArgumentException('Recipient address cannot be empty.');
        }
    }

    // ABSTRACT method — each channel delivers differently; the parent
    // declares the requirement but provides no body.
    abstract public function send(): void;

    // TEMPLATE METHOD pattern: the public entry point calls shared logic
    // in a fixed order, then calls the abstract send() that each child defines.
    // This guarantees: validate → send → log, every single time.
    final public function dispatch(): void
    {
        $this->validateRecipient(); // Always validate first.
        $this->send();              // Each child handles its own delivery.
        $this->logDispatch(static::class); // Always log after sending.
    }
}

// ---------------------------------------------------------------
// Child class #1: Email delivery
// ---------------------------------------------------------------
class EmailNotification extends Notification
{
    // Only send() needs to be implemented — the rest comes from the parent.
    public function send(): void
    {
        // In production: use PHPMailer, Symfony Mailer, etc.
        echo "[Email] Sending to {$this->recipientAddress}: \"{$this->messageBody}\"\n";
    }
}

// ---------------------------------------------------------------
// Child class #2: SMS delivery
// ---------------------------------------------------------------
class SmsNotification extends Notification
{
    public function send(): void
    {
        // In production: call Twilio or AWS SNS here.
        $shortMessage = substr($this->messageBody, 0, 160); // SMS has a 160-char limit.
        echo "[SMS] Sending to {$this->recipientAddress}: \"{$shortMessage}\"\n";
    }
}

// ---------------------------------------------------------------
// Usage — dispatch() handles the full pipeline for both.
// ---------------------------------------------------------------
$emailAlert = new EmailNotification('alice@example.com', 'Your order has shipped!');
$emailAlert->dispatch();

echo "---\n";

$smsAlert = new SmsNotification('+447911123456', 'Your delivery arrives today between 2-4pm.');
$smsAlert->dispatch();

<?php

// LAYER 1: The Interface — defines the public contract for all gateways.
// External code (controllers, services) will only ever know about this.
interface PaymentGatewayInterface
{
    public function charge(int $amountInCents, string $currency, string $paymentToken): string;
    public function refund(string $transactionId): bool;
    public function getGatewayName(): string;
}

// LAYER 2: The Abstract Class — implements the interface and provides
// shared behaviour that ALL real gateways benefit from.
abstract class AbstractPaymentGateway implements PaymentGatewayInterface
{
    private array $chargeLog = [];

    // Shared method: log every charge attempt regardless of the provider.
    // No concrete gateway needs to rewrite this.
    protected function recordCharge(string $transactionId, int $amountInCents): void
    {
        $this->chargeLog[] = [
            'txn'    => $transactionId,
            'amount' => $amountInCents,
            'time'   => time(),
        ];
    }

    // Shared utility: format cents into a readable currency string.
    protected function formatAmount(int $amountInCents, string $currency): string
    {
        return number_format($amountInCents / 100, 2) . ' ' . strtoupper($currency);
    }

    // Shared method available to all gateways — retrieve the full charge history.
    public function getChargeLog(): array
    {
        return $this->chargeLog;
    }

    // charge() and refund() are still abstract here — each provider implements them.
    // getGatewayName() is also left abstract — only the concrete class knows its name.
    abstract public function charge(int $amountInCents, string $currency, string $paymentToken): string;
    abstract public function refund(string $transactionId): bool;
    abstract public function getGatewayName(): string;
}

// LAYER 3: Concrete class — only deals with Stripe-specific API logic.
// Gets formatAmount() and recordCharge() and getChargeLog() for free.
class StripeGateway extends AbstractPaymentGateway
{
    public function charge(int $amountInCents, string $currency, string $paymentToken): string
    {
        // Use the inherited helper to format a readable amount for the log.
        $readable = $this->formatAmount($amountInCents, $currency);
        $transactionId = 'stripe_' . bin2hex(random_bytes(6));

        echo "[Stripe] Charged {$readable} using token '{$paymentToken}'. TXN: {$transactionId}\n";

        // Inherited from AbstractPaymentGateway — logs the charge automatically.
        $this->recordCharge($transactionId, $amountInCents);

        return $transactionId;
    }

    public function refund(string $transactionId): bool
    {
        echo "[Stripe] Refunding: {$transactionId}\n";
        return true;
    }

    public function getGatewayName(): string
    {
        return 'Stripe';
    }
}

// A one-off gateway that skips the abstract class entirely — it implements
// the interface directly because it has zero shared logic with others.
class CryptoGateway implements PaymentGatewayInterface
{
    public function charge(int $amountInCents, string $currency, string $paymentToken): string
    {
        $transactionId = 'crypto_' . bin2hex(random_bytes(6));
        echo "[Crypto] Charged {$amountInCents} cents worth of BTC. TXN: {$transactionId}\n";
        return $transactionId;
    }

    public function refund(string $transactionId): bool
    {
        // Blockchain transactions are irreversible — we can't refund.
        echo "[Crypto] Refunds not supported for: {$transactionId}\n";
        return false;
    }

    public function getGatewayName(): string
    {
        return 'Crypto';
    }
}

// ---------------------------------------------------------------
// USAGE: both gateways honour PaymentGatewayInterface.
// InvoiceService doesn't care how they work internally.
// ---------------------------------------------------------------
function processOrder(PaymentGatewayInterface $gateway, int $amountInCents): void
{
    $txnId = $gateway->charge($amountInCents, 'USD', 'tok_test_' . rand(1000,9999));
    echo "Order processed via " . $gateway->getGatewayName() . ". TXN: {$txnId}\n";
}

$stripe = new StripeGateway();
processOrder($stripe, 7999);

echo "---\n";

$crypto = new CryptoGateway();
processOrder($crypto, 24999);

echo "---\n";
// StripeGateway gets getChargeLog() from the abstract class; CryptoGateway doesn't.
echo "Stripe charge log: " . print_r($stripe->getChargeLog(), true);

<?php

/**
 * Decision function to demonstrate how to pick.
 * This is not production code — it's a self-documenting skeleton.
 */
function choosePattern(array $classes): string
{
    $hasSharedLogic = false;
    $hasIsARelationship = false;
    $multipleUnrelated = false;

    // Simulate checks (in reality you'd analyse the code)
    if (/* classes share > 2 methods with same body */ true) {
        $hasSharedLogic = true;
    }
    if (/* natural hierarchy exists */ true) {
        $hasIsARelationship = true;
    }
    if (/* more than one unrelated type */ true) {
        $multipleUnrelated = true;
    }

    if ($multipleUnrelated) {
        return 'Use an interface to define a shared capability';
    }
    if ($hasSharedLogic && $hasIsARelationship) {
        return 'Use an abstract class for shared implementation + contract';
    }
    return 'Consider an interface first; extract abstract class later if needed';
}

<?php
namespace Io\TheCodeforge\Cache;

// Example inspired by Symfony/Laravel
// Step 1: Define the contract
interface CacheInterface
{
    public function get(string $key, mixed $default = null): mixed;
    public function set(string $key, mixed $value, int $ttl = null): bool;
    public function delete(string $key): bool;
}

// Step 2: Abstract base with shared logic
abstract class AbstractCache implements CacheInterface
{
    protected function validateKey(string $key): void
    {
        if (strlen($key) > 64) {
            throw new \InvalidArgumentException('Cache key too long');
        }
    }

    // Concrete classes implement serialization differently
    protected function serialize(mixed $value): string
    {
        return serialize($value);
    }

    protected function unserialize(string $value): mixed
    {
        return unserialize($value);
    }
}

// Step 3: Concrete adapter
class FileSystemCache extends AbstractCache
{
    public function get(string $key, mixed $default = null): mixed
    {
        $this->validateKey($key);
        // ... read from filesystem
        return $default;
    }

    public function set(string $key, mixed $value, int $ttl = null): bool
    {
        $this->validateKey($key);
        // ... write to filesystem
        return true;
    }

    public function delete(string $key): bool
    {
        $this->validateKey($key);
        // ... delete file
        return true;
    }
}

// Edge case: in-memory cache might not need the abstract class
class RuntimeCache implements CacheInterface
{
    private array $store = [];

    public function get(string $key, mixed $default = null): mixed
    {
        return $this->store[$key] ?? $default;
    }

    public function set(string $key, mixed $value, int $ttl = null): bool
    {
        $this->store[$key] = $value;
        return true;
    }

    public function delete(string $key): bool
    {
        unset($this->store[$key]);
        return true;
    }
}