Bearychat Laravel Package

Getting Started

Confirm you actually need this package before wiring it in. BearyChat (the Chinese team-chat service) was discontinued, and elfsundae/bearychat is archived — no maintenance, no security patches, and no compatibility guarantees for current Laravel versions. If you are maintaining a legacy app that still posts to a BearyChat-compatible webhook endpoint (or a self-hosted clone), this package is a thin wrapper worth keeping; for greenfield work, use a generic HTTP client call instead.

First steps in an existing codebase:

1. Inspect composer.json for the version constraint and the require section — check whether it pins an old illuminate/support or guzzlehttp/guzzle, which will dictate whether it installs at all on your Laravel version.
2. Look for a service provider registration in config/app.php (Laravel 5.x style) or package auto-discovery in composer.json under extra.laravel.providers.
3. Find the published config — typically config/bearychat.php — and identify how webhook URLs are declared. This is usually an array of named channels, each mapped to an incoming-webhook URL.
4. Read the src/ directory for the transport class and any message/formatter classes. That is the whole package: it is small, and the source is faster to read than any documentation.

The minimal first use case is a single notification to one channel:

• Put the webhook URL in .env (e.g. BEARYCHAT_WEBHOOK=...) and reference it from the config file, never commit it.
• Resolve the client from the container (facade or injected instance) and send a plain text or markdown payload.
• Verify end-to-end by triggering it from php artisan tinker before wiring it into a job or event listener.

Because the package is archived, treat the installed source as the specification and record the version you rely on.

Implementation Patterns

Treat it as a webhook poster, not a chat SDK. These packages exist to POST a JSON payload to an incoming-webhook URL. Design your integration around one small adapter class in your app (e.g. App\Notifications\BearyChatNotifier) that wraps the package, so replacing it later is a one-file change. Given the archive status, this indirection is the single most valuable pattern.

Channel-per-config-entry. Configure named destinations (e.g. alerts, deploys, support) mapped to webhook URLs in config, then select the destination at the call site by name. Keep the URL lookup in config rather than scattering raw URLs through jobs.

Event/listener fan-out. The natural Laravel integration is a queued listener on domain events (OrderFailed, DeployFinished) that renders a message and posts it. Queue the listener (ShouldQueue) so a hanging webhook never blocks a request — webhook endpoints are third-party and will eventually time out.

Message composition as a first-class step. Build the payload (text, markdown, attachments, color-coded fields) in a dedicated formatter or a toBearyChat() method on the notification/event, separate from the HTTP call. This mirrors how you would write a Laravel notification channel and makes the payload testable without network access.

Wrap it in a Laravel Notification channel if you can. BearyChat's payload is close enough to Slack's incoming-webhook shape that a small custom channel (via() returning ['bearychat']) is often cleaner than calling the package directly from controllers. You get queueing, ShouldQueue, and per-user routing for free.

Fail soft for notifications, fail loud for nothing. Chat notifications are best-effort. Catch transport exceptions in the listener, log them with the destination name and response status, and let the business transaction succeed. Do not let a 500 from the webhook roll back an order.

Test with a fake transport. Bind a fake/spy implementation of your adapter in the container during tests and assert the payload shape. Never hit the real webhook in CI.

Gotchas and Tips

• Archived means frozen. Expect no updates for PHP 8.x deprecations, Guzzle major bumps, or Laravel 10/11 support. If composer install fails on modern Laravel, you are on your own — fork it or, better, copy the ~100 lines of transport logic into your app.
• BearyChat itself is gone. Verify the endpoint you are pointing at actually accepts BearyChat-format payloads. If you have migrated to Slack, DingTalk, Feishu, or Mattermost, the payload schema differs and this wrapper will not help.
• Webhook URLs are secrets. Incoming webhook URLs are bearer credentials. Keep them in .env, exclude the config from any public dump, and rotate immediately if one leaks into a log or repo.
• Check the response body, not just the status. Incoming-webhook endpoints frequently return HTTP 200 with an error envelope in the JSON body. Log the body on failure or you will debug "successful" messages that never arrived.
• Timeouts and retries. Set a short connect/read timeout on the underlying HTTP client. For retries, be conservative: webhook posts are not idempotent from the receiver's perspective, so blind retries can duplicate messages. If you must retry, do it once and log both attempts.
• Markdown dialect differences. BearyChat's markdown/attachment rendering is not identical to Slack's or GitHub's. Test formatting (bold, code blocks, links, attachment colors) against the real endpoint — payloads that validate structurally can still render as garbage.
• Payload size limits. Message attachments and text bodies have size caps. Truncate long stack traces and CI logs in the formatter rather than relying on the receiver to reject them gracefully.
• Config caching bites. After changing config/bearychat.php, run php artisan config:clear. A cached config with an old webhook URL is a classic wasted afternoon.
• Extension point is the transport layer. If the package exposes a Guzzle client or an injectable HTTP handler, swap it out for a mock in tests and for a logging middleware in staging. That middleware (log method, URL host, status, and body — redacting the URL token) is the fastest debugging tool you will have.
• Record the fork decision. If you keep this package, add a note in your README or an ADR explaining that it is archived, why it is still used, and what the migration path is. The next developer will otherwise re-litigate the decision.