Hipchat V2 Api Client Laravel Package

Getting Started

Before anything else: this package talks to Hipchat's v2 REST API, and Atlassian shut Hipchat down in 2019 — api.hipchat.com no longer resolves. The package itself is marked unmaintained and hasn't shipped a release since April 2016. So "getting started" realistically means one of two things: you've inherited a codebase that still references it and need to keep it compiling (or remove it), or you're reading it as a reference implementation for a thin Guzzle-based API client.

Minimum steps:

1. composer require gorkalaucirica/hipchat-v2-api-client. Expect conflicts against modern guzzlehttp/guzzle and PHP 8.x; if you just need it to install for archaeology, use a throwaway project or --ignore-platform-reqs.
2. Read src/API.php first — it is effectively the package's documentation, since it enumerates every endpoint wrapper (getRoom, getAllRooms, sendRoomNotification, getUser, createUser, webhooks, emoticons, etc.). Then read src/Client.php for the transport layer and src/Auth/ for token handling. src/Model/ holds the DTOs (Room, User, Message, …).
3. Wire it up manually — there is no Laravel service provider or facade in the package:

use GorkaLaucirica\HipchatAPIv2Client\API;
use GorkaLaucirica\HipchatAPIv2Client\Auth\TokenAuth;
use GorkaLaucirica\HipchatAPIv2Client\Client;

$api = new API(new Client(new TokenAuth(config('services.hipchat.token'))));

$api->sendRoomNotification($roomId, 'Deploy finished', 'green', true);

Exact method signatures drift between versions, so verify against src/API.php in the tag you've installed rather than trusting snippets.

Your first real use case is almost certainly a build/deploy notifier posting into a room — that's what 90% of consumers of this library did.

Implementation Patterns

Bind it once, inject it everywhere. Register a singleton in a service provider so the Guzzle client (and its connection pool) is reused, and keep the token in config/services.php:

$this->app->singleton(API::class, fn () => new API(
    new Client(new TokenAuth(config('services.hipchat.token')))
));

Add a Hipchat facade over that binding if you want the terse Hipchat::sendRoomNotification(...) call style in controllers.

Wrap it, don't sprinkle it. Because the package is dead, treat its namespace as an implementation detail. Put a HipchatNotifier interface in your app, implement it with this package, and inject that. When you eventually swap to Slack/Teams webhooks, only one class changes.

Push calls onto the queue. Notification sends are I/O to a third party; do them in a queued job with $tries = 3 and backoff(). This also means a Hipchat timeout can't take down a request cycle.

Resolve names to IDs once. The API is ID-centric — room and user lookups are by numeric ID. If your config says #deployments, do the name→ID lookup at boot or cache it; don't call getAllRooms() on every notification.

Test by injecting a fake HTTP client. Client accepts a Guzzle ClientInterface, so you can pass a MockHandler-backed client and assert on the request path/body without touching the network. Alternatively mock your own HipchatNotifier and skip the package entirely in tests.

Add logging via the handler stack. Rather than editing the package, configure the Guzzle client you inject with a Middleware::log() / Middleware::history() handler — that's the cleanest extension point it offers.

Gotchas and Tips

• The service is gone. Any code path that actually issues a request will fail with DNS/connection errors. If you're auditing a legacy app, the first job is finding and deleting these call sites, not fixing them.
• Abandoned dependencies. Last release 2016 means Guzzle 5/6-era constraints and no PHP 7.4/8.x compatibility guarantees. Expect deprecation notices, and don't expect it to coexist with a modern Guzzle 7 dependency graph.
• You own the Laravel glue. No provider, no facade, no config publishing. Everything in the "Implementation Patterns" section above is code you write.
• 204s and empty bodies. Several endpoints (delete user, delete room, webhook ops) return 204 No Content. Don't assume every call returns a hydrated Model — check the return type of the specific method in API.php.
• Two exception layers. Failures can surface as the package's own exception types or as raw GuzzleHttp\Exception\* depending on where in the stack they occur. Catch broadly at your notifier boundary and normalise, rather than catching the package classes in business logic.
• Token scope matters. Hipchat issued personal tokens and room-scoped tokens with different permissions. A 403 on sendRoomNotification is usually a scope problem, not a payload problem.
• Rate limits were real. Hipchat throttled per-token; on a busy CI setup you'll want exponential backoff rather than a tight retry loop.
• Message format is a parameter. The notification API distinguishes html from text; passing HTML in a text message renders tags literally. Similarly, notify controls whether the room pings — leave it false for chatty build output.
• Watch for a hardcoded base URL. Check Client.php for how the endpoint host is constructed; if it's baked in, that's your first patch point when pointing at a mock server in tests.
• Extension points worth knowing: implement AuthInterface for non-token auth, inject a custom Guzzle client for transport/proxy/logging changes, and subclass API if you need endpoints the package never wrapped.
• Don't start new work on this. For anything greenfield, use Slack/Teams incoming webhooks (a single Http::post() in Laravel) — you get the same outcome with zero unmaintained dependencies.