Getting Started

Minimal Steps

Install the Package:
```
composer require ejtj3/teams
```
Create a Teams Incoming Webhook:
- Navigate to your Teams channel → Manage Channel → Connectors → Incoming Webhook.
- Configure and copy the generated webhook URL.

Send a Basic Message:

use EJTJ3\Teams\Card;
use EJTJ3\Teams\Client;

$client = new Client('YOUR_WEBHOOK_URL');
$card = (new Card('Hello Teams!'))
    ->setText('This is a test message from Laravel.');
$client->send($card);

Verify in Teams: Check your configured channel for the message.

First Use Case: CI/CD Notifications

Trigger a notification when a GitHub Actions workflow completes:

// In your Laravel job or event listener
public function handle()
{
    $client = new Client(config('teams.webhook_url'));
    $card = (new Card('Build Status'))
        ->setText('Pipeline completed with ' . $this->status)
        ->setThemeColor($this->status === 'success' ? Card::STATUS_SUCCESS : Card::STATUS_CRITICAL);

    $client->send($card);
}

Implementation Patterns

Core Workflows

1. Card Construction

Use a builder pattern for reusable card templates:

// app/Services/TeamsCardBuilder.php
class TeamsCardBuilder
{
    public static function buildAlert(string $title, string $message, string $status): Card
    {
        return (new Card($title))
            ->setText($message)
            ->setThemeColor(self::mapStatusToColor($status))
            ->addSection((new Section($message))
                ->addFact('Status', $status)
                ->addFact('Time', now()->format('Y-m-d H:i:s')));
    }

    private static function mapStatusToColor(string $status): string
    {
        return match ($status) {
            'critical' => Card::STATUS_CRITICAL,
            'warning' => Card::STATUS_WARNING,
            default => Card::STATUS_SUCCESS,
        };
    }
}

Usage:

TeamsCardBuilder::buildAlert('Server Alert', 'High CPU usage detected', 'warning');

2. Actionable Cards

For approval workflows, use ActionCard with HttpPostAction:

// app/Services/ApprovalCardBuilder.php
class ApprovalCardBuilder
{
    public static function buildApproval(string $title, string $description, string $callbackUrl): Card
    {
        $card = (new Card($title))
            ->setText($description);

        $actionCard = (new ActionCard('Approve/Reject'))
            ->addAction(new HttpPostAction('Approve', $callbackUrl . '?action=approve'))
            ->addAction(new HttpPostAction('Reject', $callbackUrl . '?action=reject'));

        $card->addPotentialAction($actionCard);
        return $card;
    }
}

Handle Callback in Laravel:

// routes/web.php
Route::post('/teams/callback', function (Request $request) {
    $action = $request->query('action');
    // Process approval/rejection logic
});

3. Dynamic Sections

Fetch data from Laravel models and populate sections:

// In a controller or service
$section = (new Section('New User Created'))
    ->setActivityTitle('User Registration')
    ->addFact('Name', $user->name)
    ->addFact('Email', $user->email)
    ->addFact('Role', $user->role);

$card->addSection($section);

Laravel-Specific Patterns

1. Service Provider Integration

// app/Providers/AppServiceProvider.php
public function register()
{
    $this->app->singleton(TeamsClient::class, function () {
        return new Client(config('teams.webhook_url'));
    });
}

Usage in Controllers:

use Illuminate\Support\Facades\App;

public function notify(TeamsClient $client)
{
    $client->send((new Card('Test'))->setText('Hello from Laravel!'));
}

2. Queueable Notifications

Avoid blocking requests by queuing webhook sends:

// app/Jobs/SendTeamsNotification.php
class SendTeamsNotification implements ShouldQueue
{
    use Dispatchable, InteractsWithQueue, Queueable, SerializesModels;

    public function handle(TeamsClient $client)
    {
        $client->send($this->card);
    }
}

Dispatch:

SendTeamsNotification::dispatch($card)->onQueue('teams');

3. Configuration

Define webhook URLs in config/teams.php:

return [
    'webhook_url' => env('TEAMS_WEBHOOK_URL'),
    'default_theme' => \EJTJ3\Teams\Card::STATUS_DEFAULT,
];

Access via config('teams.webhook_url').

4. Event Listeners

Trigger notifications on Laravel events (e.g., created, updated):

// app/Listeners/SendUserRegisteredNotification.php
public function handle(UserRegistered $event)
{
    $card = (new Card('New User Registered'))
        ->addSection((new Section('Details'))
            ->addFact('Name', $event->user->name)
            ->addFact('Email', $event->user->email));

    SendTeamsNotification::dispatch($card);
}

5. Testing

Mock the Client in PHPUnit:

// tests/Feature/TeamsNotificationTest.php
public function test_notification_is_sent()
{
    $mock = Mockery::mock(TeamsClient::class);
    $mock->shouldReceive('send')->once();

    $this->app->instance(TeamsClient::class, $mock);

    // Trigger event or controller
    $this->assertTrue(true); // Mock verified
}

Advanced Patterns

1. Adaptive Cards (Limited Support)

While the package doesn’t natively support adaptive cards, you can embed JSON payloads:

$client->send(json_encode([
    '@type' => 'MessageCard',
    '@context' => 'http://schema.org/extensions',
    'themeColor' => '0076D7',
    'sections' => [[
        'activityTitle' => 'Hello world!',
        'activitySubtitle' => 'Sub-title here',
        'text' => 'This is a plain-text section.',
    ]],
]));

2. Multi-Channel Notifications

Store multiple webhook URLs and route dynamically:

// app/Services/MultiTeamsClient.php
class MultiTeamsClient
{
    public function __construct(private array $webhookUrls) {}

    public function sendToAll(Card $card)
    {
        foreach ($this->webhookUrls as $url) {
            (new Client($url))->send($card);
        }
    }
}