インストール
composer require 'drupal/address:^2.0'
概要
Addressモジュールは、国際郵便住所を扱うための包括的なソリューションを提供します。Drupal 7のaddressfieldモジュールの後継として開発され、commerceguys/addressingライブラリを基盤としています。
このモジュールは、世界200カ国以上の住所フォーマットに対応し、各国の住所入力規則に従った動的なフォーム要素を生成します。住所フィールドは国を選択すると自動的にその国の住所フォーマットに適した入力欄（州/県、市区町村、郵便番号など）を表示し、必須項目も国ごとに適切に設定されます。
また、行政区画（都道府県、州など）のドロップダウン選択、郵便番号の形式検証、多言語サイトでの言語オーバーライド機能など、高度な住所管理機能を備えています。Viewsとの完全な統合により、住所データの検索・フィルタリング・ソートも可能です。
Features
- 200カ国以上の国際住所フォーマットに対応した住所入力フォーム。国を選択すると自動的にその国の住所形式に合わせたフィールドが表示される
- 住所（Address）、国（Country）、ゾーン（Zone）の3種類のフィールドタイプを提供
- 国ごとの郵便番号パターン検証機能により、入力された郵便番号の形式を自動的にバリデーション
- 行政区画（州、県、地区など）の階層的なドロップダウン選択。国によっては市区町村レベルまで事前定義されたリストから選択可能
- ゾーン機能により、複数の地域（国、州、郵便番号範囲など）を組み合わせた配送エリアや税率適用地域を定義可能
- フィールドオーバーライド機能で、各フィールド（組織名、氏名、住所行など）の表示/非表示、必須/任意を個別に制御可能
- 多言語サイト向けの言語オーバーライド設定。特定の言語で常に住所を入力・表示することが可能
- Viewsとの完全な統合：国名でのフィルタリング、ソート、行政区画でのフィルタリングが可能
- イベントサブスクライバーによる拡張：住所フォーマット、利用可能な国リスト、行政区画のカスタマイズが可能
- Drupal 7のaddressfieldモジュールからのマイグレーションパスを提供
- FeedsモジュールおよびDiffモジュールとの統合
Use Cases
ECサイトの配送先住所管理
オンラインショップで顧客の配送先住所を収集・管理するケース。Addressフィールドを注文エンティティやユーザープロファイルに追加し、国を選択すると自動的にその国の住所フォーマットに対応した入力フォームが表示されます。日本の顧客には都道府県選択、米国の顧客には州選択が表示され、郵便番号の形式も自動検証されます。Drupal Commerceと組み合わせることで、送料計算や税率計算にも住所データを活用できます。
会員住所録の構築
会員制サイトでユーザーの住所情報を管理するケース。ユーザーエンティティまたはプロファイルエンティティにAddressフィールドを追加し、会員登録時やプロファイル編集時に住所を収集します。利用可能な国を特定の国に制限したり、組織名フィールドを非表示にするなどのカスタマイズが可能です。Viewsを使って会員の住所一覧を作成し、国や都道府県でフィルタリングすることもできます。
店舗・拠点情報の管理
チェーン店や複数拠点を持つ組織のサイトで、各店舗・拠点の住所を管理するケース。店舗コンテンツタイプにAddressフィールドを追加し、店舗情報を登録します。Viewsで店舗一覧を作成し、地域別にフィルタリングしたり、国名や都道府県名でソートすることが可能です。住所表示はaddress-plain.html.twigテンプレートをオーバーライドしてGoogleマップへのリンクを追加するなどのカスタマイズもできます。
送料ゾーンの定義
ECサイトで地域ごとに異なる送料を設定するケース。Zoneフィールドを使用して「関東地方」「北海道・沖縄」などの送料ゾーンを定義します。各ゾーンには複数のテリトリー（都道府県など）を含めることができ、郵便番号範囲での指定も可能です。例えば「東京都（島しょ部を除く）」のように、特定の郵便番号を除外した地域を定義することもできます。Drupal Commerceの送料計算モジュールと連携して使用されます。
カスタム行政区画の追加
標準では提供されていない行政区画を追加したいケース。例えば英国に郡（County）を追加する場合、イベントサブスクライバーを実装してaddress.address_formatイベントとaddress.subdivisionsイベントを購読します。住所フォーマットに行政区画フィールドを追加し、郡のリストを提供することで、英国住所入力時に郡を選択できるようになります。tests/modules/address_test/src/EventSubscriber/GreatBritainEventSubscriber.phpに実装例があります。
Tips
- 住所表示をカスタマイズしたい場合は、テーマでaddress-plain.html.twigテンプレートをオーバーライドしてください。エンティティタイプ、バンドル、フィールド名、ビューモード別のテンプレートサジェスチョンが利用可能です。
- 特定の国だけでなく、フィールドごとに動的に利用可能な国を変更したい場合は、address.available_countriesイベントのサブスクライバーを実装してください。
- 標準で提供されていない行政区画（例：英国の郡）を追加したい場合は、address.address_formatイベントとaddress.subdivisionsイベントのサブスクライバーを実装してください。tests/modules/address_test/src/EventSubscriber/GreatBritainEventSubscriber.phpに実装例があります。
- フォームAPIで直接住所入力フォームを使用したい場合は、#type => 'address'を使用してください。FieldAPIを使わずに住所入力機能を利用できます。
- 多言語サイトで住所を常に特定の言語（例：英語）で入力させたい場合は、フィールド設定の「Language override」を設定してください。これにより、インターフェース言語に関係なく住所が常にその言語で保存されます。
Technical Details
Hooks 1
hook_field_views_data
Addressモジュールによって実装され、住所フィールドのViewsハンドラーを定義します。国コードに対してcountryフィルター/ソートハンドラー、行政区画に対してsubdivisionフィールドハンドラー、administrative_areaフィルターハンドラーが設定されます。
Troubleshooting 7
Composerを使用してモジュールをインストールしてください（composer require drupal/address）。これにより依存ライブラリも自動的にインストールされます。Composerを使用していない場合は、Ludwigモジュールを使用してライブラリを管理できます。
AJAXが正しく動作していない可能性があります。ブラウザの開発者ツールでJavaScriptエラーがないか確認し、DrupalのAJAX設定やjQuery/JavaScriptの読み込みに問題がないか確認してください。また、フォームが適切にビルドされているか確認してください。
フィールド設定で「Validate postal code」チェックボックスをオフにすることで、郵便番号パターンの検証を無効にできます。
フィールド設定の「Available countries」で利用可能な国を選択してください。複数選択可能です。何も選択しない場合はすべての国が利用可能になります。
フィールド設定の「Field overrides」セクションで、非表示にしたいフィールドのオーバーライドを「Hidden」に設定してください。
Viewsのソートハンドラー設定で「Sort by」を「Country name」に設定してください。デフォルトでは国名（翻訳済み）でソートされます。「Country code」を選択すると国コードでソートされます。
Drupalコアのマイグレーションモジュールを有効にし、マイグレーションを実行してください。Addressモジュールにはaddressfieldからaddressへのフィールドマッピングとプロセスプラグインが含まれており、自動的に変換されます。
Security Notes 2
- 住所データは個人情報として扱われるため、適切なアクセス制御を設定してください。フィールドパーミッションモジュールなどを使用して、住所フィールドへのアクセスを制限することを検討してください。
- ユーザー入力の住所データは表示時に自動的にエスケープされますが、カスタムテンプレートを実装する場合は、Twigのオートエスケープ機能を無効にしないでください。