Teams Connector Bundle Laravel Package

Getting Started

• Install with Composer and confirm the transitive constraint that came with v1.1.0: composer require skrepr/teams-connector-bundle:^1.1 skrepr/teams-connector:^0.3. The bundle is Symfony-first (a DI bundle around skrepr/teams-connector), so in a Laravel app you generally get more value from the underlying connector plus your own thin service binding — check vendor/skrepr/teams-connector/README.md first, that is where the actual message/card API lives.
• Create an Incoming Webhook for the target Teams channel (Channel → Connectors → Incoming Webhook) and put the URL in config/services.php / .env as TEAMS_WEBHOOK_URL. Treat it as a credential — anyone with it can post to the channel.
• Bind the connector in a service provider so it is resolvable from the container and injectable into jobs/notifications:

$this->app->singleton(TeamsConnector::class, fn () => new TeamsConnector(
    config('services.teams.webhook_url'),
    // inject the HTTP client explicitly; see Gotchas
));

• First use case: a SendTeamsMessage job that fires on a domain event (new lead, failed deploy, error threshold crossed). Build the card, dispatch the job onto a queue — do not call the webhook inline in a request cycle.

Implementation Patterns

• Wrap, don't sprinkle. Expose one app-level service (App\Services\Teams\TeamsNotifier) with intent-named methods (notifyDeployment(), notifyLead()). Cards are verbose arrays; keeping that construction in one place stops the webhook URL and card schema leaking across the codebase.
• Queue everything. Webhook posts are outbound HTTP calls to a third party. ShouldQueue jobs or a custom Laravel notification channel give you retries, backoff, and timeouts for free.
• Per-channel routing. Keep a map in config (teams.channels.alerts, teams.channels.deployments) and resolve the webhook URL by name in the job's constructor. Makes staging vs. production and per-team channels a config change, not a code change.
• Test with a fake HTTP client. Because the connector takes an HTTP client, inject a mock/stub in unit tests and assert on the request body (the card payload JSON). Assert on the card's sections/facts structure, not on string equality of the whole JSON.
• Feature-test the boundary. For app-level flows, swap the TeamsNotifier binding for a spy in the container and assert notifyX was called; keep the payload-level assertions in a smaller set of dedicated tests.
• Card composition. Build small helpers: Card::facts([...]), Card::section($title, $text, $facts, $actions). Teams renders facts as a two-column table — good for key/value alert data (env, commit, duration); free text is where you put the human sentence.
• Upgrade discipline for v1.1.0. This release is a dependency bump to skrepr/teams-connector 0.3.0 plus CI coverage for PHP 8.2 / Symfony 6.2. There are no new features, so the real risk is a 0.x minor bump on the underlying connector. Read that package's 0.3.0 diff/changelog before upgrading, and pin ^0.3 while it is pre-1.0.

Gotchas and Tips

• The bundle is not a Laravel package. There is no service provider auto-discovery, no facade, no config publish. Treat the bundle as a Symfony integration artifact; consume skrepr/teams-connector directly and keep your own small binding.
• Pre-1.0 dependency. 0.3.0 gives no backward-compatibility promise. A composer update can break your card-building code without the bundle's version changing. Commit composer.lock and upgrade the connector deliberately.
• No native HTTP client hook in older Laravel versions. If you want Http::fake() style testing, ensure the connector accepts a PSR-18/HttpClientInterface implementation you control rather than constructing its own. Verify the constructor signature in 0.3.0 — this is exactly the kind of thing a 0.x bump changes.
• Throttling and status codes. Teams throttles webhooks aggressively. Handle 429 with backoff (the queue's backoff() is usually enough) and treat 4xx as non-retryable — an invalid card schema returns 400 every time, so retrying just burns queue workers.
• Timeouts. Set an explicit timeout (5–10s) on the HTTP client. Default client timeouts can hold a queue worker far longer than a Teams endpoint deserves.
• Silent failures. Log the response body on non-2xx. A rejected payload from a malformed card often comes back with a terse error and your alert simply never appears.
• Markdown and schema drift. MessageCard formatting support is inconsistent and Microsoft has been steering users toward Adaptive Cards and Power Automate workflows; the "Incoming Webhook" connector is on a deprecation path. Abstract the payload behind your TeamsNotifier now so a future migration does not touch call sites.
• Secrets in tests. Never let a test hit the real webhook. Fail fast if TEAMS_WEBHOOK_URL is unset in non-production environments rather than posting to a real channel from CI.
• Extension points. If you need custom card shapes, extend the connector's message/card class rather than post-processing arrays; if you need multi-tenant routing (one webhook per customer), build a resolver keyed on your tenant model instead of adding config entries per customer.