018. hx-put（PUTリクエストによる全体置換）

原理：「完全な上書き」という整理術

PUTリクエストの定義と美学

Webの共通言語（HTTP）において、「PUT（プット）」という言葉は、対象となるデータを「丸ごとごっそり最新のものに入れ替える」という非常にクリーンな操作を指します。

POSTが「新しいものを付け足す（追加）」というニュアンスを持つのに対し、PUTは「そこにある古いものを、今私が持っている新しいもので完全に置き換える（置換）」という役割を担います。これをプログラミングの用語で「等巾（とうきん）性がある」と言います。同じデータを何度もPUTし続けても、結果として「同じ新しい状態」が維持されるだけで、データが二重に作られたりすることはありません。非常に予測しやすく、バグが入りにくい潔い操作です。

HTMLで失われた「更新」の手段

悲しいことに、私たちが日常使っているHTMLの標準機能では、この「PUT」という便利な合言葉を使うことができません。フォームで送れるのはGETかPOSTだけ。そのため、これまでの開発者は更新処理であっても「POST」で代用し、サーバー側で「これは新規作成ではなく更新だ」と判断するような、少しちぐはぐなコードを書かざるを得ませんでした。

HTMXの hx-put 属性は、この失われた「更新」の力をHTMLに取り戻します。「プロフィールを更新する」「設定を上書きする」といった、現代のWebアプリで最も頻繁に行われる操作を、Webの本来の設計図（REST）に則って、美しく直感的に記述できるようにします。

実践：設定やプロフィールを「上書き」する

1. プロフィール編集フォームの実装

ユーザー情報を丸ごと新しいものに入れ替える、最も標準的なPUTの活用例です。

<!-- edit-profile.html -->
<div id="profile-container">
    <h3>プロフィール表示</h3>
    <p>名前：田中太郎</p>
    <button hx-get="/user/1/edit" hx-target="#profile-container">
        編集する
    </button>
</div>

<!-- サーバーから返ってくる「編集用フォーム」 -->
<form hx-put="/user/1" hx-target="#profile-container">
    <input type="text" name="name" value="田中太郎">
    <input type="email" name="email" value="tanaka@example.com">
    <button type="submit">保存（上書き）</button>
</form>

このフォームを送信すると、HTMXは /user/1 に対して「この新しい情報で上書きしてくれ（PUT）」と頼みます。サーバー側はDBの古いレコードを新しい値で一気に書き換え、再び「最新のプロフィール表示HTML」を返します。

2. スイッチやトグルによる設定更新

画面上のスイッチを切り替えた瞬間に、その設定を「ONの状態」でPUT（上書き）する例です。

<div id="settings">
    <input type="checkbox" name="notification" checked
           hx-put="/api/settings/notifications" 
           hx-trigger="change"
           hx-target="#settings">
    通知を有効にする
</div>

3. ステップ・バイ・ステップ解説

対象の特定: 「今あるデータを、送信する新しいデータで完全に置き換えたい」という状況なら hx-put を選びます。
名詞のURL: 送信先のURLは、操作（/update-profile）ではなく、対象物そのもの（/user/1）を指すのがRESTの美しい書き方です。
サーバー側の処理: 届いたデータを使って、対応するレコードの「全項目」を更新します。

比較：POSTによる代用 vs hx-putによる正攻法

POSTで「更新」を代用する場合

意味の混同: 「新規作成」と「更新」が両方POSTで送られるため、サーバー側のコードで if (id exists) のような分岐が必要になり、コードがごちゃつきます。
予測不可能性: うっかりボタンを二回押すと、同じものが二つ作られてしまう心配（等巾性の欠如）があります。

HTMXの hx-put

意味の明確化: 「これは置き換えだ」という意図がHTML上で一目でわかります。
安全なリトライ: もし通信エラーで再送が起きても、「新しい値で上書き」されるだけなので、データが壊れたり重複したりするリスクが極めて低いです。
デバッグの容易さ: ネットワークログを見た時、「PUTリクエストが飛んでいる」のを確認するだけで、どんな意図で通信が行われたのかが明確に伝わります。

まとめ：初心者のための「整理整頓」の心得

hx-put を意識して使うことは、アプリケーションの構造を「整理整頓」することに繋がります。

足し算はPOST、書き換えはPUT: この区別をマスターするだけで、あなたの設計レベルは一段階上がります。
全情報を送る意識: PUTは「丸ごと入れ替え」なので、基本的にはそのデータの必要な全ての項目をフォームに含めるのがお作法です。
Webの標準に乗る: HTMLには本来なかった「PUT」を使いこなすことで、あなたはブラウザとサーバーの真の対話を実現していることになります。

古くなった情報を、新しい希望で塗り替える。そんな「更新」の喜びを、hx-put というシンプルで強力な属性が支えてくれます。次の記事では、さらに徹底した「お掃除」――データをこの世から消し去る「hx-delete」（019. hx-delete）をご紹介します。