Bitrix24 Monolog Bundle Laravel Package

Getting Started

Reality check first: this is a Symfony bundle, not a Laravel package. There is no ServiceProvider, no config file Laravel auto-publishes, and no facade. What you actually want from it is the underlying Monolog handler class (the thing that turns a LogRecord into a Bitrix24 REST call). Plan on using that class directly inside config/logging.php, not the bundle.

1. Inspect what you installed. After composer require predanie/bitrix24-monolog-bundle, run:

   composer show predanie/bitrix24-monolog-bundle
   ls vendor/predanie/bitrix24-monolog-bundle/src
   

   You're looking for the handler (usually under Handler/ or Monolog/) and the Symfony service definition in Resources/config/services.xml — that XML/YAML is your best documentation of the constructor signature, because there is no README-driven quickstart beyond a paragraph.

2. Create the Bitrix24 side before writing PHP. In Bitrix24 go to Developer resources → Other → Inbound webhook, grant at minimum the scope you need (task if it creates tasks, im/imbot if it posts messages, crm if it comments on deals). Copy the resulting https://<portal>/rest/<user_id>/<token>/ URL. Without a valid webhook every log entry silently fails, so verify the URL with curl against profile.json first.

3. Wire it as a channel in config/logging.php:

   'bitrix24' => [
       'driver'  => 'monolog',
       'handler' => \Predanie\Bitrix24MonologBundle\Handler\Bitrix24Handler::class,
       'with'    => [
           'webhook' => env('BITRIX24_WEBHOOK'),
           'level'   => env('LOG_LEVEL', 'error'),
       ],
   ],
   

   driver => monolog + handler is the only native way Laravel composes third-party Monolog handlers, so this is the whole integration step.

4. First meaningful use case: route error and above to a Bitrix24 channel so a "production is on fire" event arrives as a task/message in a support group, while your normal daily logs stay on daily. Do not swap your default channel — you want this as an additional sink (Log::channel('bitrix24')->error(...) or include it in a stack).

Implementation Patterns

As an extra sink on a stack, not a default driver. The classic pattern:

'stack' => [
    'driver'   => 'stack',
    'channels' => ['daily', 'bitrix24'],
],

Because the handler is level-gated, debug/info calls flow through the stack without hitting the Bitrix24 API, while error/critical go to both places. This is the least surprising setup and keeps your normal log inspection workflow intact.

Programmatic construction when with isn't enough. If the handler needs a Guzzle client, a user ID, a pipeline stage, or an AbstractFormatter, don't fight config/logging.php — register a singleton in a service provider and hand Laravel a Monolog\Logger instance via a custom channel:

'bitrix24' => [
    'driver'  => 'custom',
    'via'     => fn () => new \Monolog\Logger('bitrix24', [app(Bitrix24Handler::class)]),
],

This gives you full control and is what you'll end up doing anyway once you realise the Symfony DI parameters don't map 1:1 to Laravel's config/logging.php array syntax.

Separate channels per severity/audience. Because a Bitrix24 message lands in front of a human, it's worth splitting: a bitrix24-critical channel that creates a task assigned to on-call, and a bitrix24-warning channel that posts to the support group feed. Each gets its own handler instance at a different level. This maps nicely onto a per-channel config block, each with its own webhook URL and scope.

Context and formatter matter more than you think. Bitrix24 task/message bodies are rich text-ish. Attach a formatter that renders $record['context'] and $record['extra'] into the message, or the CRM entry will be useless ("An error occurred" with no stack trace). If the bundle's handler accepts a formatter argument, set a Monolog\Formatter\LineFormatter with includeStacktraces => true; if not, subclass the handler and set it in the constructor.

Attach processors for correlation. Push a WebProcessor (URL, IP, method) and a custom processor that injects request_id / user_id into extra. Every Bitrix24 entry carrying the same request ID makes support triage dramatically faster, and it costs one line in your service provider.

Throttle/group with FingersCrossedHandler. If a single request can emit dozens of errors (DB down → every query fails), wrap the Bitrix24 handler in Monolog\Handler\FingersCrossedHandler with a BufferHandler, so Bitrix24 receives one aggregated message per request rather than 60. This is the single most useful pattern for a human-facing log sink; it also protects the Bitrix24 rate limit.

Testing. Never hit the real webhook in tests. In TestCase::setUp, rebind the channel to a TestHandler, or conditionally register a NullHandler when app()->runningUnitTests(). Assert on Log::spy()/Log::shouldReceive() rather than on the handler — you don't want your test suite dependent on a 2018 bundle's internals.

Gotchas and Tips

It's Symfony 3/4-era code and the last release is from 2018. Expect Symfony\Component\DependencyInjection classes on the bundle file, and expect Monolog 1.x assumptions. Laravel 9+ ships Monolog 2/3, where HandlerInterface moved and AbstractProcessingHandler::write() now takes Monolog\LogRecord instead of array. If the handler type-hints array $record, it will fatal on modern Laravel. Check the handler's write() signature before wiring it in — this is the single most likely reason the package "doesn't work" in a current app. If it's incompatible, copy the 60 lines of write() into your own handler class; that's cheaper than pinning Monolog.

The bundle is inert in Laravel. Nothing auto-registers. config/bundles.php does not exist here. You must reference the handler class explicitly (see above). Any README instruction saying "register the bundle" is Symfony-only and should be translated, not followed.

Bitrix24 lies with HTTP 200. The REST API returns {"error":"...","error_description":"..."} inside a 200 response. If the bundle doesn't inspect the body, misconfiguration (bad webhook, wrong scope, wrong user ID) shows as "logs are being sent" while nothing arrives. Always curl the webhook manually first, and if you debug the handler, log the decoded response body temporarily.

Rate limits are real. Bitrix24 enforces roughly 2 requests/second per user (and ~50/min). A naive error-level handler under a foreach of 200 records will happily try 200 calls and start returning QUERY_LIMIT_EXCEEDED. Combine the BufferHandler/FingersCrossedHandler pattern with a level floor of error — never point this at debug.

Blocking I/O in the request path. The handler does a synchronous HTTP call, adding tens to hundreds of milliseconds to every logged error. In Laravel, either accept it (errors are rare) or queue it: dispatch a job from a custom handler, or use dispatchAfterResponse(). Do not put this handler behind LOG_STACK on your hot path if you're logging warnings on every request.

Secrets. The webhook URL is the credential — anyone with it can call your portal REST. Keep it in env/config/logging.php only, ensure APP_DEBUG=false in prod, and never log the webhook URL from the handler itself (avoid extra leaking the constructor args).

Extension points to know. Subclass the handler and override write() for body shaping (task title vs. message vs. CRM comment), and use Laravel's Context facade or a WebProcessor for enrichment. If the bundle exposes a Symfony Configuration tree, ignore it in Laravel; replicate its sensible defaults manually in config/logging.php.

Abandonment risk. Zero stars, zero dependents, no release since 2018. Treat it as a vendored snippet, not a dependency: copy the handler into app/Logging/ with an attribution comment, and drop the composer require. You'll get Monolog 3 compatibility, PHP 8.2 support, and a class you can actually unit-test.