Fields that follow the country
Pick a country and the fields change to the way that country writes addresses: the order, the labels and the postal code. About 250 countries and territories are covered.
Note: Try it
It starts in the United States: Street address, Apartment…, City, State, ZIP code. Choose Japan in Country: 〒 Postal code comes first, then Prefecture. Choose United Kingdom: there is no State. Choose Germany: Postal code comes before City.
The parts the country needs are required
With ->required(), the parts that country needs must be filled in. A US address needs the street, city, state and ZIP code; a UK address needs the street, town and postcode, and has no state.
Note: Try it
Click “Show what would be saved” with the address empty: Street address, City, State and ZIP code show an error. Choose United Kingdom and click it again: now Street address, Town or city and Postal code show an error.
Empty is fine, half-filled is not
Without ->required() the address can stay empty, and then every part is saved as null, the country too. Once one part is typed, the other parts that country needs become required.
Note: Try it
Click “Show what would be saved” with the address empty: everything is null. Then type Boston in City and click it again: Street address, State and ZIP code now show an error.
Changing the country clears what does not fit
A state that does not exist in the new country is cleared, and so are the postal code and city of the old country. The street lines stay, since they take the longest to type. Parts the new country does not use are saved as null, so a German address never keeps an old US state or ZIP code.
Note: Try it
This address is in Boston, MA. Choose Germany in Country: City and the postal code are emptied, and Street address stays. Type 10117 in Postal code and Berlin in City, then click “Show what would be saved”: state is null, and the German postal code and city are saved.
Postal codes saved the way the country writes them
The postal code is saved in the country’s own shape: sw1a1aa becomes SW1A 1AA, 021101234 becomes 02110-1234, 1000001 becomes 100-0001. A code in the wrong shape is refused, with an example. This example only has the country and the postal code.
Note: Try it
This field starts in the United Kingdom. Type sw1a1aa in Postal code and click “Show what would be saved”: it is saved as SW1A 1AA. Then type 12345: the error says how a UK postal code is written, with an example.
States picked from a list, in the screen’s language
Where the country has a list (US states, Canadian provinces, Japanese prefectures and about 40 more), the state is picked from it. Names are shown in the screen’s language, and the same value is saved whatever the language. This example only has the country and the state.
Note: Try it
Open State and type mass: Massachusetts is found, and MA is saved. Choose Japan in Country and open Prefecture: on this English screen it shows Tokyo, on the Japanese screen 東京都, and both save 東京都.
How the state is saved
->storeRegionAs() decides how the state is saved: RegionFormat::Code (the default: MA, 東京都), RegionFormat::Name (Massachusetts) or RegionFormat::Iso (US-MA, JP-13). This field uses Iso, and only has the country and the state.
Note: Try it
Choose Massachusetts in State and click “Show what would be saved”: state is US-MA. Choose Japan and Tokyo: it is JP-13.
Each part in its own column
Without ->json(), each part goes to its own column: country, postal_code, state, city, line1, line2. These are the same names as a Stripe address, so most customers tables already fit.
Note: Try it
Type 200 Atlantic Ave in Street address and 02110 in ZIP code (City and State fill themselves in), then click “Show what would be saved”: one key per column, line1, city, state and so on.
Your own column names
Name each part after your columns: ->country('country_code'), ->postalCode('zip'), ->region('prefecture'), ->locality('town'), ->line1('street'), ->line2('building'). Passing null leaves a part out.
Note: Try it
Type 200 Atlantic Ave in Street address and 02110 in ZIP code, then click “Show what would be saved”: the keys are street, town, zip and so on.
All parts in one JSON column
->json('shipping_address') saves every part inside one JSON column. Cast it to array on the model. Useful for a second address that does not need its own columns.
Note: Try it
Type 1 Harbor Way in Street address and 02110 in ZIP code, then click “Show what would be saved”: everything sits inside shipping_address.
Neighborhood
->district('neighborhood') adds a neighborhood or district field. It is off by default and only shown for countries that write one: Brazil’s bairro, Korea’s dong, Mexico’s colonia.
Note: Try it
This field starts in Brazil: there is a Neighborhood field. Choose United States in Country: the Neighborhood field goes away, and is saved as null.
One country only, without the country list
->country(null) hides the country list and always uses ->defaultCountry(), here Japan. For forms that only take addresses in one country.
Note: Try it
There is no Country field: the fields are in the Japanese order from the start (〒 Postal code, Prefecture, City…). Type 1000001 in Postal code and click “Show what would be saved”: there is no country key, and the code is saved as 100-0001.
The country for new addresses
->defaultCountry('GB') sets the country a new address starts with. Without it, the panel’s country is used (the United States in this demo).
Note: Try it
The country is already United Kingdom and the fields are in the UK order. You can still choose another country.
Only some countries
->onlyCountries(['US', 'CA', 'MX']) limits the country list to those countries.
Note: Try it
Open Country: only the United States, Canada and Mexico are there. Type japan: nothing is found.
Countries at the top of the list
->preferredCountries(['JP', 'KR', 'TW']) puts those countries at the top of the list. Without it, the panel’s preferredCountries() is used (US, CA, GB, DE and JP in this demo).
Note: Try it
Open Country: Japan, South Korea and Taiwan come first under “Suggested”, then all countries.
Two addresses on one form
Billing and shipping addresses on the same form never mix: postal code answers, suggestions and the map belong to their own block.
Note: Try it
Type 02110 in the ZIP code of the shipping address: only the shipping address gets Boston and Massachusetts. The billing address stays empty.
City and state from the ZIP code
Type a ZIP code and the city and state are filled in. A short note under the field says so. This demo has the US and Japanese postal code files.
Note: Try it
Type 02110 in ZIP code: City becomes Boston and State Massachusetts. Then type 00000 instead: the note says no address was found.
Prefecture, city and town from a Japanese postal code
In Japan the town is filled in too, from Japan Post’s data. Japan Post’s notes such as 「以下に掲載がない場合」 are left out, so the town field gets 千代田, not a note.
Note: Try it
Type 1000001 in Postal code: Prefecture becomes Tokyo (東京都 on the Japanese screen), City 千代田区 and Town and block number 千代田. Add the block number yourself, for example 1-1.
One code, several places
When one postal code covers several places (common in Japan), the parts they share are filled in and a list asks which one. It works with the arrow keys and Enter.
Note: Try it
Type 4400832 in Postal code: Aichi (愛知県) and 豊橋市 are filled in, and a list shows 岩田町 and 中岩田. Press ↓ and Enter, or click one: the town is filled in.
Typed fields are never overwritten
The postal code only fills in empty fields. A city someone already typed stays.
Note: Try it
City already says Cambridge. Type 02110 in ZIP code: State becomes Massachusetts, but City stays Cambridge.
Turning the lookup off
->postalCodeLookup(false) turns the lookup off for this block. The code is still checked and saved in the country’s shape.
Note: Try it
Type 02110 in ZIP code: City and State stay empty.
The address in one column
Many apps keep the address in one column next to the postal code, without separate fields. With PostalCodeInput::make('postal_code')->fillAddress('address'), the address for the postal code goes into that column, but only while the column is empty. Full-width digits become half-width as you type.
Note: Try it
Type or paste 1000001 (full-width digits, as typed with a Japanese keyboard) in Postal code: it becomes 100-0001 as you type, and Address becomes 東京都千代田区千代田. Add the block number, for example 1-1. Then change Postal code to 9800811, a code in another city (Sendai): Address keeps what you typed.
Where the postal code data comes from
php artisan warp-input:postal-codes JP US GB writes small JSON files for those countries (Japan Post for Japan, GeoNames for about 100 others) into storage/app/warp-input/postal-codes; ->postalCodeStorage() on the plugin keeps them elsewhere, on S3 for example. For countries without files, ->postalCodeDrivers(['viacep', 'zippopotam']) asks an online service. Neither is used unless you set it up.
Note: Try it
This demo only made the US and Japanese files and has no driver. This field is in Germany: type 10115 in Postal code and nothing is filled in.
Looking up a postal code in your own code
app(PostalCodeLookup::class)->lookup('JP', '100-0001') returns the places for a code, outside any form. Japanese answers also have the kana readings.
Note: Try it
Below is the real answer for 100-0001 from this demo’s files: prefecture, city, town and their readings in kana.
Address suggestions while typing
With ->addressSuggestions('photon') on the plugin (komoot’s Photon, OpenStreetMap data, no key), typing in Street address shows matching addresses in the chosen country. Picking one fills in every part. Off by default; this demo turns it on. When City or ZIP code is already filled in, they are searched too, so the same street in other towns is not listed.
Note: Try it
Type 200 Atlantic Ave Boston in Street address and wait a moment: a list of matching addresses appears. Pick one: City, State and ZIP code are filled in. Then empty Street address and type 100 Summer St: City and ZIP code are already filled in, so only the one in Boston is listed, not the same street in other towns.
No suggestions for one block
->suggestions(false) turns suggestions off for this block only, while the rest of the panel keeps them.
Note: Try it
Type 200 Atlantic Ave Boston in Street address: no list appears.
A saved address on a detail page
AddressEntry shows a saved address one line per row of the country’s format. The column names are set the same way as on AddressFields (or ->json()).
Note: Try it
The US address ends with Boston, MA 02110. The Japanese one starts with 〒100-0001 and goes from the prefecture down.
Suite 4
Boston, MA 02110
東京都千代田区
千代田1-1
千代田ビル5F
Japan
One line, for tables
AddressColumn shows the address on one line in a table, ->style('one-line') does the same on a detail page. ->searchable(['line1', 'city', 'postal_code']) makes the parts searchable.
Note: Try it
Each address is on one line. The Japanese one ends with Japan, because it is not in the panel’s country. The Customers list uses AddressColumn.
A mailing label
->style('label') writes the address the way it goes on an envelope: ->recipient() and ->organization() add the person and the company, the country’s capital-letter rules are followed, and the country name is added for mail abroad. ->copyable() copies it in one click.
Note: Try it
The city is in capitals (10115 BERLIN) and GERMANY is on the last line. Click the label: it is copied, ready to paste.
Spree Werkzeug GmbH
Hauptstraße 5
10115 BERLIN
GERMANY
With or without the country name
The country name is added only when the address is in another country than the panel’s. ->showCountry() always adds it, ->showCountry(false) never does.
Note: Try it
The Boston address ends with United States, because of ->showCountry(). The Berlin address has no Germany, because of ->showCountry(false).
Suite 4
Boston, MA 02110
United States
10115 Berlin
Japanese addresses in Latin letters
Japanese, Chinese and Korean addresses written in Latin letters use the Latin order, from small to large. Written in their own script, they go from large to small.
Note: Try it
The left one starts with the street (1-1 Chiyoda) and goes on to Chiyoda-ku, Tokyo and 100-0001. The right one starts with 〒100-0001 東京都.
Chiyoda Bldg. 5F, Chiyoda-ku, Tokyo
100-0001
Japan
東京都千代田区
千代田1-1
千代田ビル5F
Japan
Formatting an address anywhere
Address::format([...], style: 'one-line') gives the same text outside Filament: in a PDF, an email or an export. The keys are country, postal_code, region, locality, district, line1, line2, and for labels recipient and organization.
Note: Try it
Below is what Address::format() returns for 200 Atlantic Ave, Suite 4 in Boston.
Validation rules for other fields and APIs
AddressFields checks addresses by itself. For API requests or your own fields, use new AddressPostalCode($country) and new AddressRegion($country). Countries without postal codes (Hong Kong, the UAE…) or without a state list accept any value.
Note: Try it
These two fields check US values. Type 1234 in ZIP code and XX in State, then click “Show what would be saved”: both are refused. Type 02110-1234 and Massachusetts (or MA, or US-MA): both are accepted.