Hipchat Php Laravel Package

Getting Started

Install via Composer:

composer require hipchat/hipchat-php

Start reading in src/HipChat/HipChat.php. That class is the single entry point for the REST API; public method names map roughly one-to-one onto HipChat v2 endpoints (getRoom, getRooms, sendRoomNotification, messageRoom, createUser, inviteUser, setTopic, etc.). Secondary files worth knowing: src/HipChat/HipChatException.php (the exception type everything throws) and src/HipChat/Addon/ if you plan to build a HipChat integration/add-on rather than just talk to the API.

Minimal first use — a room notification, the most common daily use case (CI alerts, deploy notices, monitoring hooks):

use HipChat\HipChat;

$hipchat = new HipChat($token); // default base URL is https://api.hipchat.com/v2/

$hipchat->sendRoomNotification(
    '12345',                    // room id (preferred) or name
    'Deploy 412 to production finished',
    'green',                    // color
    true,                       // notify users
    'text'                      // message format
);

Keep the token in .env / a secret store and inject it; never commit it. If you are on HipChat Server (self-hosted), pass your installation's base URL as the second constructor argument: new HipChat($token, 'https://hipchat.internal.example.com/v2/').

Implementation Patterns

Wrap it in a Laravel service provider. Bind a single configured client in the container so you do not rebuild it per call, and expose a config file (config/hipchat.php) with token, base_url, and default room IDs. If you want facades, alias HipChat::sendRoomNotification(...) to the resolved instance, but prefer constructor injection of an interface you control.

Adapt it behind your own interface. Because the library is a thin, concrete client, wrap it:

interface ChatNotifier {
    public function notify(string $room, string $message, string $color = 'yellow'): void;
}

class HipChatNotifier implements ChatNotifier {
    public function __construct(private HipChat $client) {}

    public function notify(string $room, string $message, string $color = 'yellow'): void
    {
        $this->client->sendRoomNotification($room, $message, $color, true, 'text');
    }
}

This gives you a single place to catch exceptions, add retry logic, and swap providers later.

Queue notifications. Every notification is a network call to a rate-limited API. Dispatch a job (SendHipChatNotification) rather than calling inline during a request. In jobs, set $tries = 3 and $backoff = 30, so a rate-limit blip doesn't fail a deploy.

Prefer room IDs over names. Name lookups are ambiguous (renamed rooms, duplicate names across rooms) and cost an extra request. Resolve names to IDs once at configuration time and cache the mapping (Cache::remember('hipchat.room.deployments', ...)) so you don't hit getRoom() on every job.

Use sendRoomNotification vs messageRoom deliberately. sendRoomNotification produces a system-style notification (good for alerts, supports color and notify). messageRoom posts as a user/application message and shows up as conversation — better for chat-ops bots that people reply to. Pick per use case, not per convenience.

Admin operations need admin tokens. Creating/updating/deleting users, rooms, and memberships requires an admin-scoped token. Keep two configured clients (notifier token vs admin token) if your app does both.

Escape hatch for missing endpoints. The client exposes a generic request() method. If the library hasn't wrapped an endpoint you need, call it directly with the HTTP verb and path rather than forking the package:

$response = $hipchat->request('GET', 'room/12345/history', ['max-results' => 50]);

Add-on development. If you're building a HipChat integration rather than just sending messages, look at HipChat\Addon\Addon. It handles the install/capability descriptor and JWT validation for webhook-style add-ons. This is a different mental model from the REST client: you receive requests from HipChat, not send them.

Testing. Mock your own interface, not the package. If you must test the client itself, inject a fake HTTP transport or use HTTP recording; the concrete HipChat class makes mocking awkward without a wrapper.

Gotchas and Tips

The product is EOL. Atlassian shut down HipChat Cloud in 2019; HipChat Server/Data Center is legacy. Treat this package as maintenance-only: keep it isolated behind an interface so migrating to Slack/Teams is a contained change. Don't build new deep integrations on it.

Check the version and PHP constraints first. This package predates modern PHP and modern Guzzle. On PHP 8+ you may need composer require --ignore-platform-reqs or an older PHP runtime in CI, and on Laravel 9+ you may hit dependency conflicts. Verify composer.json before assuming composer require just works.

Default API version matters. Older snippets and older releases default to v1 endpoints. Explicitly pass https://api.hipchat.com/v2/ (or your server URL with /v2/) so you're not silently hitting deprecated routes.

Handle HipChatException and 429s. Every API call can throw HipChat\HipChatException. Rate limiting (HTTP 429) is the most common failure; inspect getLastHttpCode() on the client to distinguish 401 (bad token), 403 (missing scope), 404 (bad room/user), and 429 (back off and retry). Log the response body — the API returns a JSON error message that tells you exactly what's wrong.

Message constraints. Notifications have length limits (thousands of characters) and HTML content must be well-formed. Prefer text format for logs and stack traces; use html only for deliberately formatted output, and remember notify=true is what actually pings people — set it intentionally to avoid alert fatigue.

Room-name encoding. Names with spaces or special characters need URL encoding, and the library's handling of id_or_name is not always obvious. Passing a numeric string ID avoids the problem entirely.

Pagination is manual. List endpoints (getRooms, history, emoticons) accept start-index and max-results. Large instances won't return everything in one response, and the wrapper doesn't auto-page. Loop until you get fewer results than max-results.

Token scope and leakage. Tokens are bearer-style and grant full access to the room/user operations they're scoped to. Never log the token, never return it in error responses, and rotate it if you see it in a stack trace. Use distinct tokens for notifications vs admin operations.

Extension points are thin. There is no formal plugin system; the practical extension points are (a) wrapping the client, (b) request() for unwrapped endpoints, and (c) subclassing HipChat if you want to add convenience methods. Prefer (a) and (b) — subclassing couples you to internals.

Empty/odd return values. Some methods return decoded arrays/objects, some return false on non-exception failures, and some return the raw response. Don't assume a consistent shape; check the method's source in HipChat.php when in doubt, and always confirm success by inspecting the result or the last HTTP code rather than trusting truthiness.

Self-hosted differs. HipChat Server versions drift from Cloud's v2 API. Test against the actual server version you target, and pin the base URL in config rather than hardcoding api.hipchat.com.