Laravel Dingtalk Laravel Package

Getting Started

Install via Composer (the package targets Laravel 5.5, so verify on newer Laravel versions):

composer require wxiangqian/laravel-dingtalk

On 5.5 the service provider and DingTalk facade are auto-discovered. If you're on an older bootstrapping style, register Wxiangqian\DingTalk\DingTalkServiceProvider in config/app.php and alias the facade in the aliases array.

Publish the config and open it first — this is the single most important file:

php artisan vendor:publish --provider="Wxiangqian\DingTalk\DingTalkServiceProvider"

You'll get something like config/dingtalk.php mapping named robots to their credentials:

return [
    'default' => [
        'webhook' => env('DINGTALK_WEBHOOK'),
        'secret'  => env('DINGTALK_SECRET'), // optional 加签 secret
    ],
    'ops' => [
        'webhook' => env('DINGTALK_OPS_WEBHOOK'),
        'secret'  => env('DINGTALK_OPS_SECRET'),
    ],
];

Move all webhooks/secrets into .env. Then send your first message — the canonical first use case is an alert to a dev/ops group:

use Wxiangqian\DingTalk\Facades\DingTalk;

DingTalk::robot('ops')->text('Deploy finished: v1.2.3');

If the facade name or method chain differs in the version you install, read src/ — the package is small enough that the service provider and main robot class will tell you the exact API in a couple of minutes.

Implementation Patterns

Named robots for multi-group routing. The package's selling point is "支持多个钉钉群", so lean on the config map rather than hardcoding URLs. Define one entry per team (ops, sales, alerts) and select with robot('name'). Keep the default robot as the safe fallback for generic notifications.

Wrap it in a small notifier service. Don't scatter DingTalk:: calls across controllers. Create app/Services/DingTalkNotifier.php that owns formatting decisions:

class DingTalkNotifier
{
    public function alert(string $title, string $body, string $robot = 'ops')
    {
        return DingTalk::robot($robot)->markdown(
            "### {$title}\n\n{$body}\n\n> " . now()
        );
    }
}

Use markdown for anything a human reads. Plain text messages collapse on mobile and mangle URLs. markdown with a title and a couple of sections renders far better in the DingTalk client. Reserve link for "click through to the dashboard" cases and actionCard when you need buttons.

@-mention on-call. For real incidents, include the phone numbers to @ so the on-call engineer gets a push. Text/markdown messages typically accept an atMobiles array — put on-call numbers in config so they're not buried in code.

Queue it. HTTP calls to DingTalk block the request. Wrap sends in a job:

class SendDingTalk implements ShouldQueue
{
    use Dispatchable, InteractsWithQueue, Queueable;

    public function handle(DingTalkNotifier $notifier) { /* send */ }
}

Retries should be modest — DingTalk rate-limits aggressively.

Hook into Laravel's exception handler. In app/Exceptions/Handler.php::report() (or a Log::listen / custom logger channel), forward 5xx and uncaught exceptions to the ops robot. Throttle by exception class + minute so a broken queue worker doesn't flood the group.

Per-environment routing. Point local/testing at a dedicated "sandbox" robot (or a null robot) so local dev noise never reaches production groups.

Deployment & cron hooks. Emit messages from artisan commands, deploy scripts (via a php artisan dingtalk:notify wrapper), and scheduled tasks. This is where the package adds the most day-to-day value with the least effort.

Gotchas and Tips

• Rate limit is the #1 pitfall. DingTalk robots allow roughly 20 messages/minute per robot. A retry storm or an exception hook without throttling will silently start returning errors. Debounce/batch in your notifier, and consider a Redis throttle key per robot name.
• Secret vs. webhook-only. If the robot has "加签" enabled in DingTalk but you didn't set secret, every send fails with a signature error. Conversely, if the secret is set but signing was disabled in the DingTalk console, requests fail too. Keep the two states in lockstep — check the robot's security settings first when debugging.
• Keyword/IP/whitelist security. DingTalk robots often require a keyword in the message or an IP whitelist. If production works but staging doesn't (or vice versa), it's almost always the whitelist, not the code.
• @-mention format. Phone numbers must be valid mainland mobile numbers as strings, and the @ must also appear in the message text (or set isAtAll). Passing integers instead of strings is a common silent failure.
• Timeout and network errors are swallowed differently per version. Set a short HTTP timeout (2–5s) and wrap sends in try/catch; alerting must never take down the request that triggered it.
• Facade vs. injected instance. If you inject the class rather than the facade, confirm it resolves the config correctly — some small packages read config lazily on the instance and can be cached in Octane/long-running workers. In long-lived workers, re-resolve per send or reset state between jobs.
• Test with Http::fake(). Even though the package predates Laravel 7's Http::fake, you can mock the outgoing call at the Guzzle layer or assert on DingTalkNotifier behavior. Never hit the real webhook in CI.
• Maintenance risk. At 18 stars and a low activity score, treat this as a thin wrapper, not infrastructure. Pin the version in composer.json, and if you later need webhook + secret signing, action cards, or batch sending, be ready to swap in a more actively maintained package or a 40-line Guzzle class of your own. The DingTalkNotifier abstraction above is cheap insurance for exactly that.
• Extension points. If you need custom message payloads (buttons, feed cards), prefer calling the package's lower-level send method with a raw array over forking. The transport logic is trivial; keep your customizations on your side of the boundary.