Pusher Chatkit Laravel Laravel Package

Getting Started

Status check first: this package is archived, its last release was March 2020, and ChatKit itself was discontinued by Pusher. Its day-to-day value now is almost entirely legacy maintenance and migration. For new chat work, evaluate Stream, Sendbird, Twilio Conversations, or a self-hosted Matrix/Socket.IO stack instead.

If you are working in an existing codebase that already depends on it:

1. Read composer.json first. Note the Laravel version constraint and the underlying ChatKit PHP SDK constraint (typically Pusher's server SDK, e.g. pusher/chatkit-server-sdk). This tells you immediately whether the package can coexist with your PHP/Laravel version.
2. Check registration. Laravel 5.5+ auto-discovery should register the service provider. On older apps, add the provider and facade alias manually in config/app.php. Confirm the exact namespace by looking in the package's src/ directory — the wrapper is thin, so this is quick.
3. Publish the config. Use the provider-based publish command (the tag may differ):

   php artisan vendor:publish --provider="Shalvah\Chatkit\ChatkitServiceProvider"
   

   This should produce config/chatkit.php.
4. Configure credentials in .env, never in code:

   CHATKIT_INSTANCE_LOCATOR=your:instance:locator
   CHATKIT_KEY=your:key
   

5. First use case: resolving the bound client/facade and provisioning a user after registration.

   // Check src/ for the exact facade/binding namespace.
   Chatkit::createUser([
       'id'         => (string) $user->id,
       'name'       => $user->name,
       'avatar_url' => $user->avatar_url,
   ]);
   

Where to look first: the package service provider (how the SDK client is bound), config/chatkit.php, and the underlying SDK README. The Laravel wrapper mostly handles config and DI; the SDK defines the actual methods, payloads, and exceptions.

Implementation Patterns

• Inject, don't facade. Prefer constructor injection of the bound SDK client in services and jobs. It is easier to fake and makes dependencies explicit:

  public function __construct(private \Chatkit\Chatkit $chatkit) {}
  

  Verify the concrete class name in the package source before typing against it.

• Provision users from domain events, not controllers. Use a listener or observer on Registered / UserCreated. This keeps ChatKit concerns out of HTTP handlers and lets you queue the call.

• Queue every remote call. ChatKit API latency or downtime should not block a request. Put SDK calls in jobs or ShouldQueue listeners, and dispatch after commit when they depend on database rows:

  DB::afterCommit(fn () => CreateChatkitUser::dispatch($user));
  

• Persist remote IDs locally. Store chatkit_user_id, chatkit_room_id, etc., on your models or a mapping table. ChatKit IDs are the join key between systems; never derive them ad hoc.

• Model room lifecycle as events. Create rooms once, store the returned room ID, then add/remove members in response to your own membership events. Avoid creating rooms on every request.

• Keep credentials server-side. If the client SDK needs authentication, expose a narrow token endpoint. The instance locator and key must never reach the browser.

• Webhook handlers should be idempotent. Verify signatures where the SDK supports it, store processed event IDs, and make handlers safe to replay.

• Testing pattern: bind a mock or fake into the container rather than hitting the API:

  $this->mock(\Chatkit\Chatkit::class, function ($mock) {
      $mock->shouldReceive('createUser')->once()->andReturn(['id' => '123']);
  });
  

  Or use $this->app->instance(...) with a hand-written fake.

• Migration pattern: dual-write to ChatKit and the replacement provider, backfill historical users/rooms/messages, switch reads, then stop writes. Keep the ID mapping tables until the old service is fully gone.

Gotchas and Tips

• The service is dead. Live API calls will fail. If you must keep old code running, plan a fork or vendor patch; do not build new features on it.

• Installation conflicts are likely. The package pins an old SDK and old Laravel constraints. Expect conflicts with PHP 8+ and Laravel 9+. Isolate it in a legacy service or use composer require --with-all-dependencies only after checking the lock file carefully.

• Verify the facade namespace. Wrapper packages often rename or relocate the facade. Check getFacadeAccessor() and the alias in config/app.php; do not trust stale blog snippets.

• Config caching bites. php artisan config:cache bakes .env values. After changing credentials run php artisan config:clear (then re-cache if appropriate).

• IDs must be strings. ChatKit treats user IDs as strings. Passing an integer from one code path and a string from another creates duplicate users. Cast at the boundary and be consistent.

• Handle known error classes deliberately. Catch SDK exceptions and distinguish 404 (unknown user/room) from 409/duplicate creation from 429/rate limiting. Do not blindly retry non-idempotent creates or message sends; use stable IDs or idempotency keys where possible.

• Timeouts and retries. The wrapper likely exposes little HTTP configuration. If the underlying Guzzle client is reachable, set explicit timeouts; otherwise wrap calls with cautious backoff and never retry unsafe operations.

• Redact secrets in logs. Exception handlers and request loggers can accidentally dump the key, locator, or full payloads. Add scrubbing rules.

• Multi-tenancy needs care. A single singleton config means one ChatKit instance. If you support multiple tenants or environments, construct clients per tenant rather than relying on the default binding.

• Extension points are limited but exist: publish and override the config, bind your own SDK client implementation, or replace the package service provider. There is no large ecosystem around this package, so expect to read the source rather than documentation.

• Export before sunset. If the service is still reachable for you, export users, rooms, and messages now. Keep mapping tables and a rollback plan during migration.