Hipchat Bundle Laravel Package

Getting Started

v1.0.0 is the initial release of the Hipchat bundle, so there is no upgrade path to worry about — but also very little documentation to lean on. Treat the source as the specification until the README fills out.

1. Install the package with Composer (check composer.json for the actual vendor/package name and required Laravel/PHP versions before committing).
2. Locate the service provider — it should be auto-discovered on Laravel 5.5+. On older versions you will need to register it manually in config/app.php and add the facade alias if one ships.
3. Publish the config (php artisan vendor:publish --provider="...HipchatServiceProvider") and inspect the resulting file for token, room, and endpoint keys.
4. Set credentials in .env rather than the config file: typically a Hipchat API token and a default room ID or name.
5. Send your first message using whichever entry point the package exposes — most likely a facade call (Hipchat::message('Deploy finished')->to('room')->send()), a helper, or a Laravel notification channel.

Where to look first: the config file (it tells you what the package expects), then the main client/service class, then any Notifications/ or Channels/ directory. The tests, if present, are usually the most accurate usage examples in a v1.0.0 package.

First use case: deploy and error alerting into a team room. Wire it into a queued notification or a deploy script so the value is visible immediately.

Implementation Patterns

• Notification channel. If the package exposes a Hipchat notification channel, prefer it over direct facade calls inside controllers. Define an AlertNotification with via() returning the Hipchat channel, keep message formatting in toHipchat(), and let Laravel handle queueing and retries.
• Queue everything remote. Implement ShouldQueue on notifications, or wrap facade calls in a queued job. Hipchat calls are network I/O and will slow down requests and deploy scripts otherwise.
• Environment-specific rooms. Keep room IDs per environment (HIPCHAT_ROOM_DEV, HIPCHAT_ROOM_PROD) and resolve them in config. Avoid hard-coding room names in notification classes.
• Multi-room fan-out. For releases you often want #deploys and #oncall. Loop over an array of rooms from config rather than duplicating notification classes.
• Facade for scripts, DI for classes. Use the facade in Artisan commands and deploy scripts for brevity; inject the underlying client interface into services so it can be swapped or faked in tests.
• Wrap it in your own notifier. A thin TeamNotifier service that maps domain events (DeployFailed, BuildGreen) to Hipchat messages keeps third-party API details out of your domain code and makes a future migration to Slack/Teams a single-file change.
• Testing. Bind a fake/mock of the client in the container and assert send was called with the expected room and message. Never let the suite hit the real API.
• Integration tips. Call it from App\Exceptions\Handler::report() for production error alerts, from CI after deploy steps, and from scheduled tasks for daily digests. Always guard with an env check so local and test environments stay silent.

Gotchas and Tips

• The service is end-of-life. Atlassian shut down Hipchat; the cloud API is gone and Server/Data Center is retired. Before adopting this package, confirm you are talking to a still-reachable endpoint. For most teams this package is useful as a reference implementation to port to Slack, Teams, or Mattermost — plan the migration now rather than later.
• API version ambiguity. Hipchat had v1 and v2 APIs with different auth (v1 token vs v2 personal/room tokens) and different room identifiers (ID vs name). Read the client class to see which one is targeted; the config key names are your clue.
• Token scope. Use a room-scoped notification token rather than an admin token. If messages return 403, the token likely lacks send_notification for that room.
• Room identifiers. Room names are not stable — they can be renamed. Store numeric room IDs where the API allows it.
• Message limits and formatting. Expect a ~10,000 character cap and HTML-subset formatting. Long stack traces will be truncated or rejected; trim to the first N lines and link to the full log.
• Notification flags. Notification level (text, html) and notify (ping the room) are easy to get wrong — an unset notify means alerts may be silently missed. Set them explicitly in your notification class.
• Config caching. After changing .env, run php artisan config:clear. Cached config is the most common cause of "my token isn't being picked up".
• Timeouts and failure isolation. A Hipchat outage must not fail a deploy or a user request. Wrap sends in try/catch, log failures, and set a short timeout on the HTTP client.
• Version constraints. A v1.0.0 package from the Hipchat era may cap Laravel at 5.x and PHP at 7.x. Check composer.json before installing into a modern app; you may need --ignore-platform-reqs (not recommended) or a fork.
• Extension points. The client is usually bound as a singleton in the container — rebind it to customize the HTTP client (Guzzle middleware for logging/retries) or to point at a compatible webhook proxy.
• Debugging. Enable Guzzle/HTTP debug logging temporarily, and log the request payload plus response status. A 200 with an empty body is normal for Hipchat sends; a 202/204 means accepted.