Econt Pickup Point Bundle Laravel Package

Product Decisions This Supports

Feature-level (checkout delivery experience)

• Supports a pickup-point selector at checkout for Econt-served markets: the package returns Econt cities (GetCities) and Econt offices/pickup points (GetOffices), which is exactly the data needed to render a "choose your delivery office" widget.
• Supports market entry into Bulgaria/Romania/Balkans, where Econt is a first-order logistics carrier and pickup-point delivery (over home delivery) is a meaningful share of orders. Without city/office data you cannot offer the delivery method at all.
• Supports localized delivery pricing/eligibility rules downstream — the nomenclature gives you city and office identifiers to key your own rate cards, cutoffs, and COD rules against.

Roadmap

• Unlocks a "pickup point network" delivery option as a roadmap item; the integration itself is small enough to be scoped as a single-sprint enabler rather than a multi-quarter program.
• Informs whether to build a carrier abstraction layer (Econt now, Speedy/Fan Courier/DPD later) versus hard-coding one carrier. Given the package is a thin, single-carrier client, the strategic decision is where to place your own boundary — not whether this library is good.
• Informs whether carrier coverage is a differentiator or table stakes in each target market (it is table stakes; do not over-invest).

Build vs buy

• Leans buy/adopt for the data-access layer: the surface area is two read-only calls (getCities, getOffices) wrapped in typed request/response objects, MIT-licensed. Rebuilding this is a day of work but not a day of value.
• Leans build for everything the package deliberately does not do: caching of the nomenclature, address/office validation, delivery price quoting, shipping label generation, tracking, COD handling, multi-carrier routing.

Use cases that fit

• Storefronts and marketplaces shipping into Econt-covered geographies that need a read-only catalogue of delivery destinations.
• Back-office tooling: admin order screens where an operator selects an Econt office, address validation, or customer-service lookups.
• Populating a local cache/nomenclature table on a schedule (daily/weekly sync) rather than calling Econt per-request.

Important reality check for the decision record

• Despite being filed as a "Laravel/PHP package," this is a Symfony bundle (requires symfony/http-kernel, symfony/serializer, and bundle registration via AnswearEcontBundle::class). In a Laravel codebase you would be extracting the DTOs and the HTTP client, not installing it — that changes the effort estimate and the ownership story.
• Adoption signals are effectively zero: 1 star, 0 dependents, single-vendor origin (Answear, a fashion retailer). Treat this as "vendored source," not "supported dependency."
• New in 4.2.1 (patch): the API endpoint moved from http to https. This is a one-line fix, but it is a security-relevant one: on every earlier release the client sent Econt basic-auth credentials over cleartext HTTP. Two consequences for the decision record: (a) if anyone pilots this, the floor is >=4.2.1, and (b) anyone who already vendored/extracted an earlier version must patch the base URL themselves — nothing else in the API surface changed.
• What 4.2.1 does and does not tell us: it shows the repo is not abandoned (a community PR merged, a new contributor onboarded), but the change quality bar is still "one-line endpoint fix" on a codebase whose recent history is dependency bumps and CI chores. It does not change the ownership posture. Re-verify the previously flagged future-dated release tag against the actual 4.2.1 tag date, since the release history now has a genuine superseding version.
• No breaking changes and no new features in 4.2.1 — no re-scoping warranted, only a version floor.

When to Consider This Package

Adopt (or vendor) it when:

• Your stack is Symfony 7 on PHP 8.4+ — the composer constraints are strict (php ^8.4, symfony/http-kernel ^7.0.3, symfony/serializer ^7.0.3, guzzlehttp/guzzle ^7.8.2). Older PHP/Symfony means forking or not using it.
• You can pin >=4.2.1 (or backport the http→https change into your fork). Anything below that transmits the configured user/password in the clear.
• You need only the nomenclature read path — city list and office/pickup-point list. That is the entire documented API surface (GetOffices, GetCities). If that's your requirement, the package matches it exactly.
• You already hold Econt API credentials and are comfortable with basic auth configured via config/packages/answear_econt.yaml (user/password).
• You are willing to wrap it behind your own interface — an EcontPickupPointProvider in your domain layer — so the transport, DTO shapes, and vendor risk never leak into checkout code. This is the recommended adoption posture.
• You need a schedule-driven sync (cron job pulling cities/offices into your own tables) rather than a live per-checkout API call. Do that: Econt nomenclature changes rarely, and live calls add latency and a hard runtime dependency on a third party during checkout.
• You can accept fork-and-own: MIT license, small codebase, PHPStan/GrumPHP/PHPUnit in require-dev. Forking is cheap and legitimate here.

Look elsewhere / do not adopt when:

• You are on Laravel. The Symfony bundle wiring (AnswearEcontBundle, ConfigProvider, service container config) is dead weight. Extract the request/response classes and the Guzzle client into your own package (with the https base URL), or just call the Econt Nomenclatures API directly — it is a public, documented JSON API and two endpoints do not justify a dependency.
• You need more than nomenclature. No rate quoting, no shipping labels, no tracking, no order creation, no COD, no returns, no address validation. Those require Econt's full services, and this package does not touch them. 4.2.1 adds nothing here.
• You need multiple carriers. Nothing here is abstracted; there is no carrier interface to extend. A single-carrier client is the wrong foundation for a multi-carrier strategy.
• You need vendor support or SLA. One star, zero dependents, a single corporate maintainer, and release notes dominated by dependency bumps and CI chores (PHP 8.4 bump, Symfony 7 support, Ubuntu runner change, http→https). No evidence of an external user base. Do not put it on a critical path without owning the fork.
• You need caching, retries, or resilience out of the box. Only a Guzzle timeout (added in 2.0.1) is documented. No cache layer, no circuit breaker, no retry/backoff policy, no typed error mapping, no rate-limit handling. You build those.
• You need data completeness guarantees. OpeningHours defaults to null (per 1.2.1), and the README shows no pagination, filtering, or reconciliation guidance for the office list. Plan to validate and normalize on ingest.
• You are on a compliance-sensitive timeline where an unmaintained transitive dependency (webmozart/assert, Guzzle PSR-7) in a checkout path needs a named owner — and where a transport-layer patch landing only in a 4.2.x point release is itself the risk signal. Assign an owner, or don't ship it.

Decision rule of thumb: the integration effort saved is roughly one to three engineer-days. That is small enough that the deciding factor should be your stack fit and your ownership appetite — not the package's feature set. If you're on Symfony 7/PHP 8.4 and need city+office data, vendor it behind an interface at >=4.2.1. If you're on Laravel, on an older runtime, or need anything beyond a lookup, write the ~200 lines yourself against the public API — you will get https support on day one rather than three point releases later.

How to Pitch It (Stakeholders)

For executives (30 seconds)

• What it buys us: the ability to offer pickup-point delivery with Econt, a major carrier in Bulgaria and neighbouring markets. That's a checkout conversion lever and a prerequisite for selling into those geographies — not a nice-to-have.
• What it costs: a very small integration. The package is a thin, MIT-licensed client for two read-only Econt endpoints (list of cities, list of pickup points). No commercial license, no per-call fees, no vendor lock-in.
• The honest risk: it is a single-vendor, near-zero-adoption open-source package (one GitHub star, no downstream users). We should treat it as source code we adopt and own, not as a supported product. The latest release (4.2.1) is a good illustration: it is a one-line fix to stop sending API credentials over unencrypted HTTP — a real security improvement, but one that arrived in a point release on a largely unmaintained repo. Mitigation: wrap it behind our own internal interface, fork it, pin >=4.2.1, and cache the data locally so a third-party outage or an abandoned repo cannot break checkout.
• Recommendation: Approve a small, time-boxed pilot for one Econt market, at version 4.2.1 or above, with the integration isolated behind our own delivery-provider interface. If the market performs, expanding to additional carriers is a known, incremental step; if it doesn't, we've spent days, not quarters, and the abstraction carries forward.

For engineering leads

• Scope is narrow and well-defined: getCities() and getOffices() on top of the Econt Nomenclatures API, Guzzle 7 transport, Symfony Serializer DTOs. Nothing else is in scope — no pricing, labels, tracking, or order lifecycle. 4.2.1 changes scope not at all.
• Constraints are tight: PHP 8.4+, Symfony 7.0.3+, Guzzle 7.8.2+, and a hard floor of 4.2.1 for the https base URL.
• 4.2.1 specifically: single PR (ANS-23780, first-time contributor) switching the endpoint scheme from http to https. No API, DTO, config, or signature changes; no deprecations; no migration required beyond bumping the constraint. If we have already forked or extracted the client, apply the same one-line patch ourselves and record it against our fork.
• It is a Symfony bundle, not a framework-agnostic library — Laravel or legacy-PHP services must extract the client and DTOs rather than install it.
• What we own if we adopt it: caching of nomenclature (do not call Econt live during checkout), error mapping and retries, config/secrets handling for the basic-auth credentials, and a fork under our org so we control the maintenance clock.
• Non-negotiables before production: pin >=4.2.1, run roave/security-advisories in CI, add contract tests against a recorded Econt response (asserting the https base URL so the scheme never regresses in our fork), put the vendor call behind a feature flag, and re-verify the previously flagged future-dated release tag against the 4.2.1 tag date.
• Escape hatch is cheap: the Econt API is public and documented, and the package is a few hundred lines. If it stalls, replacing it with an in-house client is a contained piece of work — provided we never let its types into our domain model. That constraint is the whole design.