Weave Code
Fan Courier Bundle Laravel Package
answear/fan-courier-bundle
Symfony bundle that integrates the FanCourier API. Install with Composer, add credentials and an optional PSR-3 logger in answear_fan_courier.yaml, then use PickupPointService to retrieve pickup points as PickupPointDTO objects.
FanCounrier bundle for Symfony
Frequently asked questions about Fan Courier Bundle
- Can I install answear/fan-courier-bundle in a Laravel application?
- No, not as a drop-in dependency. This is a Symfony bundle that relies on Symfony Flex auto-registration in config/bundles.php, a YAML config tree at config/packages/answear_fancourier.yaml, and the Symfony service container. It ships no ServiceProvider, no facade, no publishable config and no config/*.php conventions, so Composer will install it but nothing will wire up in Laravel. The practical path is to treat it as a reference implementation and port the logic into a first-party FanCourierService behind a ServiceProvider.
- What does the FanCourier bundle actually do?
- It exposes a single capability: PickupPointService::getAll() returns a typed array of PickupPointDTO objects representing FanCourier pickup points. There is no AWB or label generation, no parcel tracking, no rate quoting and no order creation. Treat it as phase one of a carrier integration, not a full courier solution.
- How do I install and configure it in a Symfony app?
- Run composer require answear/fan-courier-bundle; Symfony Flex should add AnswearFanCourier to config/bundles.php automatically. Then create config/packages/answear_fancourier.yaml with username, password, apiUrl and an optional logger service that implements Psr\Log\LoggerInterface (default is null). After that you can inject PickupPointService into your own service and call getAll().
- Which Symfony and PHP versions does this package support?
- Symfony 7 support landed in release 2.1.0 and PHP 8.4 support in 3.0.0. Guzzle timeouts were added back in 1.0.1, so pin a recent tag rather than an early one. Check the tag history before assuming a given Symfony or PHP version is covered, and pin a tag or commit hash rather than tracking dev-main.
- Is it safe to depend on this package in production?
- It is a single-vendor project from Answear with no stars and no known dependents, so there is little external validation and the bus factor is effectively the Answear team's goodwill. The blast radius is small because the feature is read-only pickup point lookup, not payments, orders or inventory. The mitigation is to fork and own it on day one, pin a tag or commit hash, and add contract tests against recorded fixtures.
- How much work is it to port this bundle to Laravel?
- Roughly two to four engineer-days including tests, versus an estimated one to three engineer-weeks to build the FanCourier API contract from scratch. The bundle is thin: a config tree, an HTTP client wrapper, one service and a handful of DTOs. The expensive unknowns are already solved, including the auth scheme, endpoint shape, response mapping and the address-nesting change introduced in 2.0.0.
- What breaking changes should I expect from FanCourier API drift?
- Release 2.0.0 documented an endpoint migration and a breaking DTO reshape, with address fields moved into a separate AddressDTO. That is one breaking change already shipped in a package with a short history, so assume more. Contract tests against a recorded fixture are mandatory, and the FanCourier API PDF linked in the README should be re-checked against what the bundle calls before committing to a sprint.
- Does this bundle handle AWB generation, tracking or shipping rates?
- No. The only exposed method is pickup point retrieval via PickupPointService::getAll(). AWB and label generation, parcel tracking, rate quoting and order creation are all out of scope. If you need those, you are building a separate integration on top of the FanCourier API.
- What happens if the FanCourier lookup fails or times out at checkout?
- That is a design decision you own, not something the bundle handles for you. The correct behaviour is to fall back to courier-to-door and never block the order. Also cache pickup point data with a sensible TTL, since points change slowly and hitting the API on every checkout is wasted latency; Guzzle timeouts were added in 1.0.1 for exactly this reason.
- Where should FanCourier credentials be stored?
- In Symfony the bundle expects a raw username and password in config/packages/answear_fancourier.yaml. In a Laravel port these must live in .env and config/fancourier.php and never in version control. Also map the vendor DTOs into your own value objects so PickupPointDTO does not leak into controllers and Blade templates.
Weaver
How can I help you explore Laravel packages today?