Download the PHP package ialpro/bundesland without Composer

On this page you can find all versions of the php package ialpro/bundesland. It is possible to download/install these versions without Composer. Possible dependencies are resolved automatically.

FAQ

After the download, you have to make one include require_once('vendor/autoload.php');. After that you have to import the classes with use statements.

Example:
If you use only one package a project is not needed. But if you use more then one package, without a project it is not possible to import the classes with use statements.

In general, it is recommended to use always a project to download your libraries. In an application normally there is more than one library needed.
Some PHP packages are not free to download and because of that hosted in private repositories. In this case some credentials are needed to access such packages. Please use the auth.json textarea to insert credentials, if a package is coming from a private repository. You can look here for more information.

  • Some hosting areas are not accessible by a terminal or SSH. Then it is not possible to use Composer.
  • To use Composer is sometimes complicated. Especially for beginners.
  • Composer needs much resources. Sometimes they are not available on a simple webspace.
  • If you are using private repositories you don't need to share your credentials. You can set up everything on our site and then you provide a simple download link to your team member.
  • Simplify your Composer build process. Use our own command line tool to download the vendor folder as binary. This makes your build process faster and you don't need to expose your credentials for private repositories.
Please rate this library. Is it a good library?

Example code of ialpro/bundesland

Informations about the package bundesland

Laravel Bundesland

CI Latest Stable Version Total Downloads

A Laravel package for resolving German federal states from postal codes with typed results, deterministic caching, Unicode-aware city validation, replaceable provider integration, and an optional HTTP API.

Overview

Calling a postcode API directly leaves validation, failure handling, caching, and test isolation to every application. Laravel Bundesland provides those boundaries once: Laravel-native dependency injection, an explicit result model, replaceable providers, consistent exceptions, city validation, and fully mockable external I/O.

Features

Requirements

Installation

Laravel discovers the service provider and the Bundesland and ZipLookup facade aliases automatically. Publish the optional configuration with:

Quick start

For callers that only need the state:

The bundesland() helper intentionally remains failure-tolerant. Prefer lookup() when your application needs to distinguish outcomes or infrastructure errors.

Lookup with city validation

Matching trims input, collapses whitespace, performs Unicode-aware lowercase conversion, and—by default—applies the documented German transliterations. It does not perform fuzzy matching.

Handle all expected outcomes explicitly when they matter to the application:

Result object

PostalLookupResult is readonly and exposes:

Property Type Meaning
status LookupStatus Success, NotFound, or CityMismatch
postalCode string Validated postcode
state ?string Matched/first provider state
city ?string Canonical city, or requested city for a mismatch
matchedCities list<string> All provider cities for the postcode
provider ?string Provider identifier

The legacy readonly properties ok, zip, and message remain available to ease migration from 1.x.

Error handling

Expected lookup outcomes are returned as statuses. Invalid input and infrastructure failures are exceptions:

Condition Package behavior
Invalid postal code Throws InvalidPostalCode before cache or provider access
Postal code not found Returns LookupStatus::NotFound
City mismatch Returns LookupStatus::CityMismatch with provider cities
Provider 404 Returns LookupStatus::NotFound
Provider timeout/connection failure Throws PostalProviderUnavailable
Provider 500 or other non-404 failure Throws PostalProviderUnavailable
Malformed provider payload Throws MalformedProviderResponse

The optional HTTP API converts these into sanitized HTTP responses; direct service and facade consumers receive the typed statuses or exceptions above.

Caching

Caching is enabled by default and can be disabled with BUNDESLAND_CACHE_ENABLED=false. When disabled, every valid lookup reaches the configured provider and neither reads nor writes cache entries.

Successful provider results use the deterministic key bundesland:{provider}:{country}:{postalCode}, for example bundesland:zippopotam:de:10115. Provider and country prevent cross-provider/country collisions. City input is intentionally excluded so city validation can reuse the same postcode response.

The default TTL is 86,400 seconds and is configurable with BUNDESLAND_CACHE_TTL. Not-found responses, timeouts, server errors, and malformed payloads are not cached. The package deliberately does not implement negative caching.

Provider architecture

Add a provider without changing lookup logic by implementing PostalCodeProvider and rebinding it in an application service provider:

Engineering Decisions

Configuration

Published configuration lives at config/bundesland.php:

Environment access is confined to configuration. Applications may override any value normally through Laravel config.

Optional HTTP API

Set BUNDESLAND_ENABLE_API=true to expose GET /api/bundesland/{zip}. Add ?city=München for city validation. The prefix and middleware list are configurable.

Outcome HTTP status
Success 200
Postal code not found 404
Invalid postcode or city mismatch 422
Provider/network/malformed response 503

Provider exception details are never returned. The defaults apply Laravel's api middleware and a 60 requests/minute throttle; review them for your application before enabling the endpoint.

Testing

The suite uses Orchestra Testbench and Laravel HTTP fakes. It never calls a live provider. Static analysis runs at Larastan/PHPStan level 8.

Version compatibility

The CI matrix and supported versions are identical:

Laravel PHP Testbench
12.x 8.2, 8.3, 8.4, 8.5 10.x
13.x 8.3, 8.4, 8.5 11.x

Laravel 11 is not supported by this major version.

Upgrading from 1.x

Version 2.0 introduces breaking configuration, dependency, provider-contract, and failure-semantics changes. Follow the 2.0 upgrade guide before updating an existing installation. The ZipLookup facade, stateByZip(), result compatibility fields, and bundesland() helper remain available.

Project policies

See ROADMAP.md.

License

Laravel Bundesland is open-source software licensed under the MIT License.

All versions of bundesland with dependencies

PHP Build Version
Package Version
Requires php Version ^8.2
ext-mbstring Version *
illuminate/cache Version ^12.0 || ^13.0
illuminate/http Version ^12.0 || ^13.0
illuminate/routing Version ^12.0 || ^13.0
illuminate/support Version ^12.0 || ^13.0
Composer command for our command line client (download client) This client runs in each environment. You don't need a specific PHP version etc. The first 20 API calls are free. Standard composer command

The package ialpro/bundesland contains the following files

Loading the files please wait ...