michaelschiemer/src/Infrastructure/Api/RapidMail/Examples/UsageExamples.php

<?php

declare(strict_types=1);

namespace App\Infrastructure\Api\RapidMail\Examples;

use App\Infrastructure\Api\RapidMail\Commands\CreateRecipientCommand;
use App\Infrastructure\Api\RapidMail\Factories\RecipientCommandFactory;
use App\Infrastructure\Api\RapidMail\RecipientId;
use App\Infrastructure\Api\RapidMail\RecipientListId;
use App\Infrastructure\Api\RapidMail\RecipientListService;
use App\Infrastructure\Api\RapidMail\RecipientService;

/**
 * Usage examples for the refactored RapidMail API with Value Objects
 */
class UsageExamples
{
    public function __construct(
        private RecipientService $recipientService,
        private RecipientListService $recipientListService
    ) {
    }

    /**
     * Example 1: Creating a new recipient using Commands
     */
    public function createRecipientExample(): void
    {
        // Create recipient list first
        $recipientList = $this->recipientListService->create(
            'Newsletter Subscribers',
            'Main newsletter subscriber list'
        );

        // Create recipient using Command
        $command = new CreateRecipientCommand(
            email: 'john.doe@example.com',
            firstname: 'John',
            lastname: 'Doe',
            company: 'Example Corp',
            recipientListId: $recipientList->id,
            customFields: [
                'source' => 'website_signup',
                'interests' => 'php,javascript',
            ]
        );

        $recipient = $this->recipientService->createWithCommand($command);

        echo "Created recipient with ID: {$recipient->id->value}\n";
        echo "Full name: {$recipient->getFullName()}\n";
        echo "Is active: " . ($recipient->isActive() ? 'Yes' : 'No') . "\n";
    }

    /**
     * Example 2: Creating from array data using Factory
     */
    public function createFromArrayExample(): void
    {
        $formData = [
            'email' => 'jane.smith@example.com',
            'firstname' => 'Jane',
            'lastname' => 'Smith',
            'company' => 'Tech Solutions',
            'newsletter_preference' => 'weekly',
            'signup_date' => '2025-01-16',
        ];

        $recipientListId = new RecipientListId(776);
        $command = RecipientCommandFactory::createFromArray($formData, $recipientListId);
        $recipient = $this->recipientService->createWithCommand($command);

        echo "Created recipient: {$recipient->email}\n";
    }

    /**
     * Example 3: Updating an existing recipient
     */
    public function updateRecipientExample(): void
    {
        $recipientId = new RecipientId(123);
        $recipient = $this->recipientService->get($recipientId);

        // Update using factory with changes
        $updateCommand = RecipientCommandFactory::updateFromRecipientWithChanges(
            $recipient,
            [
                'company' => 'New Company Name',
                'status' => 'active',
                'customFields' => ['last_login' => '2025-01-16'],
            ]
        );

        $updatedRecipient = $this->recipientService->updateWithCommand($updateCommand);
        echo "Updated recipient company to: {$updatedRecipient->company}\n";
    }

    /**
     * Example 4: Working with RecipientLists
     */
    public function recipientListExample(): void
    {
        // Get all recipient lists
        $lists = $this->recipientListService->getAll();

        foreach ($lists as $list) {
            echo "List: {$list->name} (ID: {$list->id->value})\n";
            echo "  Recipients: {$list->recipientCount}\n";
            echo "  Is default: " . ($list->isDefault() ? 'Yes' : 'No') . "\n";
            echo "  Is empty: " . ($list->isEmpty() ? 'Yes' : 'No') . "\n";
        }
    }

    /**
     * Example 5: Searching recipients
     */
    public function searchRecipientsExample(): void
    {
        // Search by email
        $recipientListId = new RecipientListId(776);
        $recipient = $this->recipientService->findByEmail(
            'john.doe@example.com',
            $recipientListId
        );

        if ($recipient !== null) {
            echo "Found recipient: {$recipient->getFullName()}\n";
            echo "Created at: {$recipient->createdAt?->format('Y-m-d H:i:s')}\n";
        }

        // Search with filters
        $recipients = $this->recipientService->search([
            'status' => 'active',
            'recipientlist_id' => $recipientListId->value,
        ]);

        echo "Found " . count($recipients) . " active recipients\n";
    }

    /**
     * Example 6: Value Object benefits
     */
    public function valueObjectBenefitsExample(): void
    {
        // Type safety - this prevents errors
        $recipientId = new RecipientId(123);
        $recipientListId = new RecipientListId(776);

        // You can't accidentally mix up IDs
        // $this->recipientService->get($recipientListId); // ❌ Type error
        $recipient = $this->recipientService->get($recipientId); // ✅ Correct

        // Value Objects have useful methods
        $otherRecipientId = new RecipientId(123);
        if ($recipientId->equals($otherRecipientId)) {
            echo "Same recipient ID\n";
        }

        // Easy string conversion
        echo "Recipient ID: {$recipientId}\n"; // Uses __toString()
    }

    /**
     * Example 7: Error handling with Value Objects
     */
    public function errorHandlingExample(): void
    {
        try {
            // This will throw an exception
            $invalidId = new RecipientId(-1);
        } catch (\InvalidArgumentException $e) {
            echo "Caught invalid ID: {$e->getMessage()}\n";
        }

        try {
            // This will throw an exception if email is invalid
            $command = new CreateRecipientCommand('invalid-email');
        } catch (\InvalidArgumentException $e) {
            echo "Caught invalid email: {$e->getMessage()}\n";
        }
    }

    /**
     * Example 8: Backward compatibility
     */
    public function backwardCompatibilityExample(): void
    {
        // Old way still works (but is deprecated)
        $legacyRecipient = $this->recipientService->getById(123);

        // New way with Value Objects
        $newRecipient = $this->recipientService->get(new RecipientId(123));

        echo "Both approaches work, but new way is type-safe\n";
    }

    /**
     * Example 9: Complex workflow
     */
    public function complexWorkflowExample(): void
    {
        // 1. Create a new recipient list
        $list = $this->recipientListService->create(
            'VIP Customers',
            'High-value customers for special offers'
        );

        // 2. Create multiple recipients
        $customers = [
            ['email' => 'vip1@example.com', 'firstname' => 'Alice', 'company' => 'BigCorp'],
            ['email' => 'vip2@example.com', 'firstname' => 'Bob', 'company' => 'MegaInc'],
        ];

        $createdRecipients = [];
        foreach ($customers as $customerData) {
            $command = RecipientCommandFactory::createFromArray($customerData, $list->id);
            $recipient = $this->recipientService->createWithCommand($command);
            $createdRecipients[] = $recipient;
        }

        // 3. Update all recipients to VIP status
        foreach ($createdRecipients as $recipient) {
            $updateCommand = RecipientCommandFactory::updateFromRecipientWithChanges(
                $recipient,
                ['status' => 'active', 'customFields' => ['vip_level' => 'gold']]
            );
            $this->recipientService->updateWithCommand($updateCommand);
        }

        echo "Created VIP list with " . count($createdRecipients) . " customers\n";
    }

    /**
     * Example 10: Migration from old to new API
     */
    public function migrationExample(): void
    {
        // Old way (still works but deprecated)
        $oldRecipients = $this->recipientService->searchLegacy(['status' => 'active']);

        // New way with proper Value Objects
        $newRecipients = $this->recipientService->search(['status' => 'active']);

        echo "Old API returned array with meta data\n";
        echo "New API returns direct array of Recipient ReadModels\n";
        echo "New recipients have type-safe IDs and helpful methods\n";

        foreach ($newRecipients as $recipient) {
            echo "- {$recipient->getFullName()}: " .
                 ($recipient->isActive() ? 'Active' : 'Inactive') . "\n";
        }
    }
}

/**
 * Quick start guide for new users
 */
class QuickStartGuide
{
    /**
     * The minimal example to get started
     */
    public static function quickStart(
        RecipientService $recipientService,
        RecipientListService $recipientListService
    ): void {
        // 1. Get or create a recipient list
        $lists = $recipientListService->getAll();
        $list = $lists[0] ?? $recipientListService->create('My List', 'Default list');

        // 2. Create a recipient
        $command = new CreateRecipientCommand(
            email: 'user@example.com',
            firstname: 'John',
            lastname: 'Doe',
            recipientListId: $list->id
        );

        $recipient = $recipientService->createWithCommand($command);

        echo "✅ Created recipient: {$recipient->getFullName()}\n";
        echo "   ID: {$recipient->id}\n";
        echo "   List: {$list->name}\n";
    }
}