Harbor Api Bundle Laravel Package

Technical Evaluation

Architecture fit

• HarborApiBundle appears to be a PHP client wrapper for the Harbor container registry REST API. The Bundle suffix is a Symfony convention, so the first architectural question is whether this is an idiomatic Laravel package (service provider, config publish, facade, auto-discovery) or a Symfony bundle with a thin Laravel shim. If it pulls in symfony/http-kernel, symfony/dependency-injection, or symfony/config types, it will not sit cleanly in a Laravel container and should be treated as a foreign dependency to be isolated behind an adapter.
• Expected shape (to be verified, not assumed): a HarborApiServiceProvider, a publishable config/harbor.php for base URL/credentials, and a facade or injectable client. Confirm whether the client is bound as a singleton — a singleton holding stale auth tokens or a mutable HTTP client is a concurrency hazard in Octane/queue workers.
• Determine where it sits in our layering. It should be an infrastructure detail consumed by a repository/gateway interface we own, never called directly from controllers or jobs.

Integration feasibility

• Baseline checks before any spike: composer.json PHP constraint, Laravel version support (illuminate/support range), HTTP client (Guzzle direct vs Laravel's Http facade), PSR-18/PSR-17 compliance, and presence of extra.laravel.providers for auto-discovery.
• Auth model is the make-or-break detail. Harbor commonly uses robot accounts with Basic auth scoped per project; confirm the package supports credential injection per-request or per-client, not a single global credential, otherwise we cannot support cross-project access patterns.
• Verify TLS handling for self-signed/internal CA Harbor instances, and whether certificate verification can be disabled only via an explicit, auditable config flag.
• Check test coverage and whether the suite runs against a live Harbor or a mocked HTTP layer.

Technical risk

• v1.0.0 with no changelog content. The release note is a link to the commit list. A first tagged release without a written changelog, upgrade notes, or documented supported Harbor versions is a process-maturity signal. It also means we have no baseline to diff against for future upgrades.
• Bus factor of one. Single-author repository; no visible governance. Assume no SLA and no guaranteed security-response path until proven otherwise.
• API surface mismatch. Harbor's API is broad (projects, repositories, artifacts, robot accounts, retention policies, replication, vulnerability scanning, webhooks, quotas). A 1.0.0 wrapper almost certainly covers a subset. Enumerate which endpoints are wrapped before committing to it for any workflow.
• Version drift. Harbor v2.x API evolves across minor releases; a wrapper pinned to an older schema can silently misbehave (new required fields, changed enum values) rather than fail loudly.
• Naming/compat smell. The Bundle suffix raises the probability of Symfony-derived code being reused wholesale. This is the single highest-likelihood source of integration friction.

Key questions

1. Which Laravel and PHP versions are in the support matrix, and is that matrix CI-enforced?
2. Is this a Laravel-native package or a Symfony bundle with Laravel glue?
3. Which Harbor API version and which Harbor server versions are targeted/tested?
4. How are credentials and multi-project/multi-registry targeting handled?
5. What is the endpoint coverage list, and does it include artifact/repository listing with pagination?
6. Is the HTTP client injectable (for retries, middleware, tracing, mocking)?
7. License, security policy, and release cadence? Any dependents in the wild?
8. Are exceptions typed and mapped, or is everything a generic GuzzleException/RuntimeException?

Integration Approach

Stack fit

• Acceptable only if: PHP constraint matches our runtime, Laravel version is within our supported window, it declares PSR-compatible HTTP abstractions, and auto-discovery works. Any missing item converts this from "composer require" to "wrap and maintain," which changes the cost model.
• If the package is Symfony-flavored, do not attempt to de-Symfony it. Vendor it behind our own HarborClientInterface so the dependency is swappable.

Migration path

• Greenfield usage (new Harbor automation) is low-risk: adopt behind an internal interface from day one.
• Replacing existing direct Guzzle/curl calls is a moderate-effort refactor: characterize current call sites and error handling first, then map each to package methods. Do not migrate and change behavior in the same change set.
• The realistic alternative to evaluate in parallel is generating a typed client from Harbor's published OpenAPI/Swagger spec, or shelling out to the official Harbor tooling. Benchmark this package against that option on endpoint coverage and typing, not on install convenience.

Compatibility

• Pin the exact version (1.0.0) and commit the lockfile. For a single-maintainer 1.0.0, treat any minor bump as potentially breaking until a changelog discipline is established.
• Pin the Harbor server version in test environments so wrapper/server skew is observable.
• Verify behavior against our actual Harbor deployment (auth mode, TLS chain, proxy) — not a public demo instance.

Sequencing

1. Static review: composer constraints, Symfony coupling, endpoint coverage, license, test suite.
2. Timeboxed spike (1–2 days) against a disposable Harbor instance: authenticate, list projects, list repositories, list artifacts with pagination, force a 401 and a 5xx to observe error typing.
3. Decide adopt / wrap / build-from-spec. Record the decision and the endpoint coverage we actually need.
4. If adopted: define our own gateway interface, add contract tests with a mocked HTTP layer, add a composer audit + Renovate/Dependabot watch on the package.
5. Roll out to one non-critical automation path before any CI/CD-critical workflow.

Operational Impact

Maintenance

• Assume we own the fork risk. Budget a nominal recurring cost for version bumps and a real cost if we must patch upstream behavior. Add the repository to dependency monitoring and to the security advisory watchlist.
• Absence of a changelog means every upgrade requires a commit-range diff review. That is cheap at 1.0.0 and expensive at 1.8.0 — push for changelog discipline early or plan to read diffs.

Support

• No documented support channel, SLA, or maintainer response expectation. Escalation path is "open an issue and wait." Do not place this package on a path where a maintainer's silence blocks a release.
• Internal mitigation: keep the wrapper thin enough that a two-day fork-and-own is a credible fallback. Document the fork procedure before it is needed.

Scaling

• Synchronous HTTP calls to Harbor will dominate latency in request paths. Keep calls out of user-facing requests; prefer queued jobs for bulk operations.
• Pagination is the classic scaling trap: a naive listRepositories() may return page one only, producing silently incomplete results as the registry grows. Verify explicit page-size and continuation handling.
• For large registries, plan caching of project/repository metadata and incremental sync rather than full enumeration per run.
• Watch for connection reuse and timeouts; a per-call client instantiation will not scale under load. Confirm timeouts are configurable.

Failure modes

• Harbor unavailable or returning 5xx → generic transport exception with no domain context; our wrapper must classify retryable vs terminal.
• Expired/revoked robot credentials → 401 that can look like 403 authorization noise; needs distinct handling and alerting.
• TLS/CA mismatch on internal Harbor → opaque connection errors, common in enterprise setups.
• Pagination truncation → missing artifacts/repositories with no error raised; this is the dangerous silent failure.
• Rate limiting / large artifact listings → timeouts under load; needs backoff and chunking.
• Credential leakage → tokens appearing in exception messages or logs; verify redaction before enabling debug logging.
• Version skew after a Harbor server upgrade → unexpected 400s or ignored fields.

Ramp-up

• Laravel developers will be productive quickly if the package is idiomatic (config file, facade, container binding). Budget half a day for a developer to read the source and write a smoke test.
• The real ramp-up cost is Harbor domain knowledge, not PHP: robot accounts, project scoping, retention and replication semantics, and the v2 API resource model. Plan that learning regardless of whether we adopt this package.
• Produce an internal one-pager: supported endpoints, error taxonomy, credential handling, and the fork procedure. That document is the actual risk control here, not the dependency choice.