Hipchat Bundle Laravel Package

Getting Started

This bundle is a thin Symfony DI wrapper around the HipChat REST client — there is no business logic here, just a service definition plus a config tree. The mental model is "one configured HipChat client object, injected wherever you need it." As of 1.4 it also ships console commands, but only if you opt into symfony/console.

Minimal steps:

1. composer require mannew/hipchat-bundle — 1.4 opens the constraints to Symfony 3, so this now resolves on both Symfony 2.x and 3.x apps (not 4+; see Gotchas).
2. Register the bundle in app/AppKernel.php: new ManneW\HipChatBundle\ManneW\HipChatBundle(). Check the bundle class namespace against vendor/mannew/hipchat-bundle/ — old bundles often nest namespaces and the README examples are the fastest way to confirm it.
3. Add config under your config.yml:

manne_w_hipchat:
    token: "%hipchat_token%"
    # auth_type: token   # if exposed by the config tree

4. If you want the bundled commands, make sure symfony/console is installed (1.4 only suggests it) and run php app/console list filtered for hipchat to discover the exact command names before scripting anything against them.
5. Inject the registered service into a controller or your own service. If you cannot remember the service id, run php app/console container:debug | grep -i hipchat — that is the single most useful debugging step with an unmaintained bundle like this.

First use case: a deploy/CI notification. Fetch the client, call getRoom('Engineering') or getRoomById($id), then ->message('Deploy finished: ' . $tag)->send(). That one flow exercises config, container wiring, and the HTTP layer all at once, so it is the right smoke test. If you installed symfony/console, the bundled HipChat commands are an even cheaper smoke test — they exercise the same client without you writing a line of app code, which is a good way to confirm your token and room ids are valid before wiring anything into a deploy hook.

Where to look first: the bundle's DependencyInjection/ directory (config keys and service id), then its Resources/config/services.yml (exact service name and any injected parameters). The wrapper itself is trivial; the underlying HipChat client's method names (e.g. getRoom, getUser, message) are what you will actually spend time in. With 1.4, also glance at the Command/ directory — it tells you which client methods the maintainers considered important enough to expose.

Implementation Patterns

• Wrap, don't scatter. Never inject the raw bundle service into ten controllers. Define an application service (App\Notifier\HipChatNotifier) that depends on the client and exposes intent-named methods (notifyDeploy, notifyAlert). This gives you one place to swap the package out later — which, given the project's trajectory, you should plan for.
• Room notifications in deploy/CI hooks. The classic pattern: an event listener or a console command hook fires after a successful build and posts to a fixed room. Keep the room id in config, not in code, so staging and prod can notify different rooms.
• Use the bundled commands as an ops tool, not as your integration. Since 1.4 the bundle ships commands that talk to HipChat, which is handy for one-off ops tasks (checking a room exists, posting a manual announcement). Treat them as a CLI surface over the same client — don't shell out to them from application code, because you lose error handling and testability. If you find yourself scripting them in cron, write a proper Symfony command in your own app that uses the injected client instead.
• Event-driven notifications. Subscribe to Symfony kernel/console events (kernel.terminate, console.terminate) and dispatch a HipChat message from the listener. Do it on terminate so the HTTP round-trip to HipChat never delays the response to the user.
• Multi-room fan-out. Maintain a config map of severity => room_id and route in your notifier service. This keeps the call sites clean and lets ops reconfigure rooms without a code change.
• Format messages for HipChat, not HTML. HipChat supported a limited HTML subset and /notification style mentions. Wrap message construction in a small formatter so @here and room mentions stay consistent and testable.
• Fire-and-forget with error isolation. HipChat being down must not break a deploy. Wrap calls in try/catch, log the failure, and continue. Consider marking the notification method @throws-free by design. This applies equally to the bundled commands if you schedule them.
• Testing. Mock your own HipChatNotifier in application tests rather than the bundle's service. If you need to test the wrapper interaction itself, the client is constructed from a token, so you can substitute a stub client without touching HTTP.

Gotchas and Tips

• The elephant in the room: HipChat no longer exists. Atlassian shut HipChat down in 2019. Any outbound REST calls will fail against the public API, including the 1.4 commands. Treat this bundle as a reference implementation for "wrap a third-party client in a Symfony service" (and "ship a few CLI commands over it"), not something to ship.
• 1.4 buys you Symfony 3, not Symfony 4+. The constraint widening is welcome, but it stops there: no Flex recipe, no services.yaml _defaults, no autowiring in the bundle's own service definition. On Symfony 3.3+ you can still autowire the client by its class name in your own services.yml if you prefer that over remembering the service id. On Symfony 4+ you will be registering services manually or writing your own wrapper.
• symfony/console is only suggested, not required. The commands silently won't be there if you don't have it installed, and you can get odd failures if console is present at a version incompatible with your Symfony line. If the hipchat commands don't appear in app/console list, check this before assuming the bundle is broken.
• PHP and Guzzle version conflicts. The underlying HipChat client pins an old Guzzle. 1.4 relaxes the Symfony constraints but does not modernise the HTTP layer, so on modern Guzzle/PSR-18 you will still hit resolution failures or runtime signature mismatches. Run composer why-not before debugging anything else.
• Service id confusion. No Flex recipe means the service id is whatever the bundle author chose — often with the vendor prefix doubled in the namespace but not the service id (or vice versa). Always confirm with container:debug; do not trust the README.
• Config quirks. Old config trees often require the token even in environments that never send notifications (e.g. test). Either provide a dummy token in config_test.yml or guard the notifier so the client is never instantiated in tests. The console commands make this more visible: a missing token will now blow up at command boot, not just at send time.
• No retries or timeouts out of the box. Add a timeout at the HTTP layer or wrap calls in your notifier. An unbounded call to a dead API is a very effective way to hang a deploy — and the same hazard applies to any cron job you build around the bundled commands.
• Extension point is the wrapper, not the bundle. The bundle exposes the client; the intended customization is to decorate or replace it in your own service. Do not patch vendor/ — you will lose changes and there is no upstream to send a PR to.
• Debugging. Because it is a thin wrapper, most failures are in the client library or in transport (TLS, proxies). Enable Guzzle debug/logging in dev and dump the last request/response — the bundle gives you nothing beyond the client, so instrument the HTTP layer directly. With 1.4 you can also bisect with a bundled command: if the command works but your service doesn't, the problem is DI/config, not the network.