Atlassian Connect Bundle Laravel Package

Getting Started

This release (4.1.0) is a compatibility release, not a feature release. The main change is Symfony 6.4 / 7.0 support. There are no listed breaking changes, deprecations, or new Laravel-specific APIs.

The package is a Symfony bundle (thecatontheflat/atlassian-connect-bundle), not a native Laravel package. For a Laravel developer, the first step is to decide whether you actually need it:

• If you are building an Atlassian Connect app in a Symfony application, upgrade normally and verify Symfony 7 compatibility.
• If you are in a Laravel application, this bundle will not auto-register via Laravel package discovery and does not provide Laravel service providers, facades, or config publishing. You would either:
  • run a separate Symfony service for the Atlassian Connect boundary, or
  • reuse only the underlying Atlassian Connect/JWT concepts and implement Laravel-native middleware/controllers yourself.

Minimal first use case for a Symfony-based app:

1. Require the package with Composer.
2. Register the bundle in your Symfony kernel/bundles config.
3. Configure the Atlassian Connect add-on settings.
4. Expose the add-on descriptor endpoint.
5. Protect routes with the package’s JWT/authentication handling.
6. Test against a Jira or Confluence Cloud site using a public HTTPS tunnel.

First place to look: the package README and bundle configuration reference, especially descriptor generation, JWT authentication, and webhook/lifecycle event handling.

Implementation Patterns

Use the package as the Atlassian Connect transport/authentication layer, not as your application’s domain layer.

Common patterns:

• Descriptor endpoint: Serve the Atlassian add-on descriptor from a dedicated controller/route. Keep environment-specific values such as base URL and key in config/env, not hardcoded.
• JWT-protected routes: Apply the package’s authentication handling to all Atlassian-facing endpoints. Keep public endpoints, such as descriptor and health checks, explicitly separated.
• Lifecycle webhooks: Handle installed, uninstalled, and related events idempotently. Persist tenant/client keys and shared secrets before acknowledging the event.
• Tenant-aware services: Treat each Atlassian site/client as a tenant. Resolve tenant context from the JWT claims or lifecycle event, then pass it into your application services.
• Webhook processing: Verify the request, persist an event record, then process asynchronously where possible. Use idempotency keys or event IDs to avoid duplicate processing.
• Laravel integration approach: If you stay in Laravel, consider implementing a small Laravel adapter around the Atlassian Connect protocol rather than forcing Symfony bundle bootstrapping into Laravel. Use Laravel middleware for JWT validation, a Laravel controller for the descriptor, and Laravel jobs for webhook processing.
• Testing: Use a tunnel such as ngrok or an equivalent HTTPS endpoint. Test install, reinstall, uninstall, and webhook replay flows. Keep the descriptor versioned and review changes carefully because Atlassian caches descriptors.

For the 4.1.0 upgrade specifically:

• If you are on Symfony 6.4 or 7.0, this release unblocks or simplifies installation.
• If you are on Symfony 4.x/5.x and already working, there is no urgent migration signal in the release notes.
• Run your normal dependency and integration tests after upgrading, especially JWT and descriptor routes.

Gotchas and Tips

• Not Laravel-native: This is the biggest pitfall. Do not expect Laravel package auto-discovery, php artisan vendor:publish, facades, or Laravel-specific config. Plan for a Symfony service or a custom Laravel adapter.
• Symfony 7 compatibility is new: 4.1.0 adds Symfony 6.4 and 7.0 compatibility. Verify transitive dependency constraints in your composer.lock, not just the top-level package version.
• No migration steps listed: The release notes show only compatibility work. Treat it as low-risk, but still test authentication, descriptor generation, and lifecycle webhooks.
• JWT details matter: Clock skew, HTTPS base URLs, issuer/audience claims, and shared-secret handling are common failure points. Log claim validation failures without leaking secrets.
• Descriptor caching: Atlassian may cache descriptors. If routes or scopes change, ensure the descriptor version and add-on configuration reflect it.
• Webhook idempotency: Atlassian can retry lifecycle and webhook requests. Store processed event IDs and make install/uninstall handlers safe to repeat.
• Multi-tenant isolation: Always resolve the tenant from verified JWT/lifecycle data. Do not trust tenant IDs supplied in request bodies alone.
• Debugging: In Symfony, use the profiler and logs around the bundle’s authentication layer. In Laravel, log the raw verification outcome at the middleware boundary, but redact JWTs and shared secrets.
• Extension points: Prefer decorating or overriding bundle services/controllers over editing vendor code. For Laravel, keep the Atlassian protocol adapter isolated so it can be replaced if you later move to a Symfony service.