- How do I install shivella/postcode-bundle with Composer?
- Install it with composer require shivella/postcode-bundle. The repository does not publish a Laravel service provider because this is a Symfony bundle, so the package registers itself through the Symfony bundle system rather than Composer auto-discovery. After installing, enable the bundle in config/bundles.php for your environment. Check the README for any version constraints that match your Symfony release.
- How do I configure postcode service credentials and the API endpoint?
- The bundle exposes its credentials and endpoint settings through Symfony bundle configuration, which you normally place in a file such as config/packages/shivella_postcode.yaml. Because the configuration is wired into the service container, you can keep environment-specific values in .env files and reference them from YAML rather than hard-coding them. Consult the README for the exact configuration keys and their defaults, since these depend on the underlying postcode service you are connecting to.
- How do I validate a UK postcode in a Symfony controller?
- Autowire or fetch the bundle's postcode service from the container and pass the submitted postcode to its validation method. The bundle normalises results, so you get a consistent outcome you can act on instead of parsing raw API responses in your controller. Keeping the call behind the service means your controller stays thin and your domain code is not tied to the API's response format.
- How do I look up an address using a postcode and house number?
- The bundle supports address lookup by postcode with an optional house number, so you can narrow results to a single property where the data allows it. Call the lookup service with the postcode, add the house number when you have it, and handle the returned address collection in your own code. Because the lookup is wrapped in a service, you can reuse it in controllers, commands, or form data transformers without duplicating API logic.
- Which Symfony versions does shivella/postcode-bundle support?
- Supported Symfony versions are defined by the package's composer.json constraints, so check those before upgrading your framework. Bundle configuration structure and service definitions can change between major Symfony releases, which is why the constraint matters. If you are on an older or newer Symfony version than the constraint allows, Composer will refuse the install rather than failing at runtime.
- Can I use shivella/postcode-bundle in a Laravel application?
- No, this package is a Symfony bundle and depends on Symfony's bundle and dependency injection components for its configuration and service wiring. Laravel uses its own service provider and container conventions, so the bundle's configuration loading will not work out of the box. If you need UK postcode lookup in Laravel, look for a framework-agnostic client library or a Laravel-specific package instead.
- How do I unit test postcode lookups without calling the real API?
- The bundle is designed around a testable service layer, so the practical approach is to mock or stub the lookup service in your tests rather than hitting the live endpoint. Because your controllers depend on the injected service rather than a concrete API client, you can replace it with a test double in the container. That keeps your test suite fast, deterministic, and independent of network availability or API rate limits.
- How should I handle failed lookups and API errors in production?
- Treat remote lookups as unreliable by design: wrap calls in try/catch, decide whether a failed lookup should block a form submission or degrade gracefully, and log failures with enough context to debug them. Postcode services can time out or rate-limit, so avoid calling the API on every keystroke and consider caching successful lookups. Never let a network error surface as an unhandled exception in a user-facing checkout or signup flow.
- Can I validate postcodes inside Symfony form types?
- Yes, the service layer can be used from a form data transformer or a custom constraint validator, which keeps postcode rules out of your controllers. Validating through the service also means you get normalised postcode values before they reach your entity. If you only need a format check, a regex constraint is cheaper, but a service call confirms the postcode actually resolves to addresses.
- Is shivella/postcode-bundle actively maintained, and what are the alternatives?
- Maintenance activity is best judged from the repository's commit history, release tags, and open issues on GitHub, so check those before committing to it for a long-lived project. If the bundle looks stale, the underlying postcode service usually offers an HTTP API you can wrap yourself, or you can use a framework-agnostic client behind your own Symfony service. Either route keeps your controllers decoupled from the API, which is the main benefit this bundle provides.