Harbor Api Bundle Laravel Package

Getting Started

• Install with Composer: composer require scottbass3/harbor-api-bundle. Note that despite the Laravel-oriented question, the package name uses the Symfony Bundle suffix — treat it as a Symfony bundle first and add Laravel glue yourself (see Gotchas).
• Configure the Harbor endpoint and credentials first: Harbor base URL (e.g. https://harbor.example.com), and either a user account or — preferably — a robot account with the minimum project scope you need. In a Symfony app this lives in config/packages/harbor_api.yaml; in Laravel you'll need to bridge it into config/services.php / a service provider.
• Look at the bundle's DependencyInjection and Service classes early — the public surface is the set of Harbor service clients (projects, repositories, artifacts, users, tags, retention). The README plus the service classes are the real API reference for v1.0.0.
• First use case to validate the wiring: connect and list projects, then list repositories in a project. If those round-trip, auth, base URL, and TLS are all correct and you can build from there.
• Since v1.0.0 is the first stable tag, pin it ("^1.0") and adopt now — this is the point where the API surface is expected to settle.

Implementation Patterns

• Service container binding (Laravel): register the Harbor client as a singleton in a service provider and resolve it via the container or constructor injection. Avoid newing it up per request — reuse the authenticated client.
• CI/CD and release automation: call Harbor services from queue jobs or Artisan commands to create projects, list artifact tags, and promote/retag images. Pair with spatie/laravel-schedule-monitor-style tooling or Horizon to keep jobs observable.
• Retention and cleanup jobs: schedule the Harbor retention/tag-list services to prune old artifacts on a cron. Do the pagination loop yourself (see Gotchas).
• Sync/webhook workflows: use the repository and artifact services as the source of truth after a webhook fires, instead of trusting the webhook payload directly.
• Repository pattern: wrap the bundle's services in your own interfaces so you can swap them, mock in tests, and hide the Symfony-flavored exceptions from the rest of the app.
• Testing: inject a fake/stub of your repository interface rather than a live Harbor instance. Reserve live calls for a small integration suite against a disposable Harbor project.

Gotchas and Tips

• It's a Symfony bundle, not a native Laravel package. Expect no Laravel auto-discovery, no config/ publishing, and no Facade. You will write a service provider and adapt the container/config wiring. Budget time for this up front.
• Auth: prefer robot accounts scoped to a project over a full admin user. Rotate tokens; don't commit credentials — use .env/secrets.
• Pagination: Harbor's list endpoints are paginated. The services typically return one page; you must loop with page/page_size parameters or you'll silently process only the first N items.
• TLS / self-signed certs: private Harbor installs commonly use internal CAs. Configure the underlying HTTP client's CA bundle explicitly; don't disable verification globally.
• Version skew: Harbor API behavior varies by Harbor server version. Record the Harbor version you test against and smoke-test after server upgrades — a client library v1.0.0 doesn't guarantee compatibility with every Harbor release.
• Error handling: API failures surface as Symfony HTTP-client exceptions. Catch and translate them into your app's exception/response conventions; log the Harbor response body for debugging.
• Rate limits and timeouts: set explicit timeouts and retry/backoff on the client. Bulk cleanup jobs hitting many artifacts are the usual culprit for 429s.
• Extension points: if the bundle exposes its HTTP client as a service, override/decorate that service in your service provider to add logging, retries, or headers — cheaper than patching the vendor code.
• v1.0.0 caveat: the release notes for this tag are only a changelog link, so verify the actual breaking-change history from the commits before committing to the API surface; if you were on a 0.x dev tag, diff your usage against v1.0.0 before upgrading.