- How do I install maalls/zipcode in a Laravel app?
- Install it with Composer by running composer require maalls/zipcode from your project root. Laravel's package auto-discovery should register the service provider, so you typically do not need to edit config/app.php by hand. After installing, publish the package config and run the migrations so the zip code table exists before importing data. Check the README for the exact publish tags and provider name for your Laravel version.
- How do I import the bundled zip code dataset?
- The package ships an Artisan import command that seeds its zip code table from the bundled dataset. Run your migrations first, then execute the import command from the console. Depending on dataset size and your database driver, the import can take a while, so for large sets consider running it as a queued or scheduled job instead of an interactive request.
- Which Laravel and PHP versions does maalls/zipcode support?
- Support depends on the version constraints declared in the package's composer.json on Packagist. Because it is a small package built around Eloquent and Artisan, it fits recent Laravel releases, but you should confirm the php and illuminate/database requirements match your app before adding it to composer.json. If you are on an older Laravel version, check the tagged releases for a compatible constraint.
- How do I look up a zip code and get its location data?
- Lookups go through the package's Eloquent model or its lookup API, which resolves a postal code to its stored record and associated location fields. In practice you run a simple finder query on the model and read attributes such as city, state, or region as defined by the package migration. Because the data lives in a normal database table, you can also query it directly with Eloquent where clauses and scopes.
- How do I validate and format a zip code in a form request?
- Use the package's validation and formatting helpers to normalize input before it reaches your rules or database. Formatting strips stray whitespace and characters so stored values stay consistent with the imported dataset. A common pattern is calling the helper inside your FormRequest's prepareForValidation method, then applying a standard required or regex rule for the final check.
- Can I use my own postal code data instead of the bundled dataset?
- Yes. The package exposes a configurable data source, so you can point it at your own table or records instead of the bundled zip codes. That is useful when you only need one country or region, or when your source data has extra fields you want to expose. Keep column names aligned with the package model's expectations, or map them in the config where supported.
- What alternatives exist to maalls/zipcode and is it still maintained?
- Alternatives include country-specific postal code datasets, broader geo and address packages, and hosted ZIP code or geocoding APIs. The appeal of this package is that it is small, has no external service dependency, and keeps the data in your own database behind Eloquent models. Its repository location is not widely documented, so check Packagist and the linked GitHub repo for recent commits and tagged releases before committing to it long term.
- Can I build zip code autocomplete or region detection with it?
- Yes. Query the package's table by a partial code, or filter by city and state to detect a region, then return the matches as JSON from a small controller endpoint. Since lookups hit a regular Eloquent model, add an index on the code column and cache frequent results to keep the endpoint responsive. Region detection is essentially the reverse lookup, filtering by location fields and reading back the postal codes.
- Is maalls/zipcode fast enough for production use?
- Performance depends mainly on your database and how much of the dataset you import. Add an index to the zip code column, cache repeated lookups, and always limit results for type-ahead endpoints rather than loading the full table. For very high traffic autocomplete, put Redis or an in-memory cache in front of the Eloquent queries.
- How do I test zip code lookups in a Laravel test suite?
- Use RefreshDatabase and seed only the rows each test needs, either through a factory if the package model supports one or by inserting a few records directly. That keeps tests fast and avoids running the full Artisan import command in CI. For controller tests that only assert your response shape, mock the lookup layer instead of touching the database.