Увійти Реєстрація
Вакансії
Вакансії Laravel Компанії Статистика
Підготовка
Як підготуватися Співбесіди Тестування Документація
Блог
Всі статті Серії
Екосистема
Пакети Ресурси Проєкти Інструменти Події Відео
Інше
Про нас Реклама
Переклади 18 листопада 2026

wire:key у Livewire 4: рядок, що зберіг чужі дані

Звіт про баг завжди однаковий: «Я видалив рядок, і після цього виділеним виявився не той». На свіжому завантаженні сторінки це не відтворюється, винятків немає, у логи нічого не потрапляє, тож тікет закривають як «не вдалося відтворити» - аж поки за тиждень він не повернеться. Причина - один відсутній атрибут, і більшість із нас прочитали про wire:key в документації як про підказку для продуктивності та пішли далі.

Навмисно відтворюємо застарілий рядок

Зберемо найменший список, який може зламатися: рядки з рахунками, у кожному - меню дій під керуванням Alpine і некероване текстове поле, плюс дія видалення на сервері. Жодного wire:key. Цей компонент зламаний так, що пройде будь-який тест, який ви, найімовірніше, для нього напишете.

  <?php // resources/views/components/⚡invoice-list.blade.php

  use App\Models\Invoice;
  use Livewire\Attributes\Computed;
  use Livewire\Component;

  new class extends Component {
    #[Computed]
    public function invoices()
    {
      return Invoice::orderBy('due_at')->get();
    }

    public function delete(int $invoiceId): void
    {
      Invoice::whereKey($invoiceId)->delete();

      unset($this->invoices); // Скидаємо кеш обчислюваної властивості
    }
  };
  <div>
    @foreach ($this->invoices as $invoice)
      <div class="flex items-center gap-4" x-data="{ open: false }">
        <span>{{ $invoice->reference }}</span>

        {{-- Некероване: значення живе лише у вузлі DOM --}}
        <input type="text" placeholder="Add a note">

        <button x-on:click="open = ! open">Actions</button>

        <div x-show="open">
          <button wire:click="delete({{ $invoice->id }})">Delete</button>
        </div>
      </div>
    @endforeach
  </div>

Тепер покеруйте ним вручну. Введіть check with finance у поле нотатки третього рядка, відкрийте меню дій третього рядка, а потім видаліть другий рядок. Список перемальовується з двома рядками - і текст нотатки та відкрите меню тепер стоять на рядку, який був третім, а став другим. Дані правильні. Усе, що прив'язане до вузла DOM, - ні.

Розбираємо морфінг, який це спричинив

Livewire не замінює HTML компонента під час кожного оновлення. Він виконує морфінг (morph): обходить старе й нове дерево одночасно, порівнює кожен елемент, який трапляється, і точково змінює лише те, що відрізняється. Саме це зберігає фокус, обробники подій і значення полів між запитами - і саме це шкодить вам тут.

З трьома рядками і без ключів порівняння суто позиційне:

  Старий DOM                  Новий HTML                  Що робить Livewire
  ───────────────────────────────────────────────────────────────────────────
  row 1  (INV-1)         →    row 1  (INV-1)              те саме, не чіпає
  row 2  (INV-2, empty)  →    row 2  (INV-3, empty)       змінює текст на місці
  row 3  (INV-3, note)   →    -                           видаляє останній елемент

Livewire так і не перемістив третій рядок. Він переписав текстовий вміст другого рядка на INV-3, а потім видалив останній елемент - який якраз і був вузлом із вашою нотаткою та відкритим меню. У Livewire є крок попереднього перегляду (look-ahead), що ловить багато таких випадків, і він вставляє маркери <!--[if BLOCK]><![endif]--> навколо умов Blade, щоб відрізнити вставку від зміни, але жодне з цього не допомагає, коли список змінив порядок чи скоротився, а рядки нічим не ідентифіковано.

Від вузла DOM залежать чотири речі, тож саме вони й ламаються, кожна зі своїм баг-репортом:

  • Стан компонента Alpine - x-data ініціалізується для кожного елемента окремо, тому відкритий випадний список чи розгорнута панель переїжджає на той запис, що успадкував вузол. Це той самий життєвий цикл, через який стан модальних вікон на Alpine і wire:entangle чутливий до повторних рендерів.
  • Фокус - курсор посеред набору тексту стрибає на сусідній рядок.
  • Позиція прокрутки всередині комірки з прокруткою скидається або опиняється на чужому записі.
  • Значення некерованих полів - усе, що не має wire:model, є станом лише в DOM, тож воно лишається на вузлі й отримує нового власника.

Якщо ваш баг-репорт збігається з одним із цих чотирьох пунктів, перестаньте читати серверний код. Це проблема ключів.

Ключ циклу - первинний ключ моделі

Дайте кожному рядку стабільну ідентичність, і позиційний обхід перестане бути вгадуванням. Додайте wire:key у відкривальний тег першого елемента всередині циклу і збудуйте його з первинного ключа моделі.

  @foreach ($this->invoices as $invoice)
    <div wire:key="invoice-row-{{ $invoice->id }}" class="flex items-center gap-4" x-data="{ open: false }">
      {{-- ... --}}
    </div>
  @endforeach

Тепер видаліть другий рядок, і Livewire зіставить invoice-row-3 з invoice-row-3, перемістить вузол, а нотатка й відкрите меню поїдуть разом із записом, якому належать.

Дві речі треба зробити правильно. Ніколи не будуйте ключ на $loop->index - це та сама позиція, на яку ви намагаєтеся відучити Livewire спиратися: вона змінюється, щойно список скорочується чи змінює порядок, тож нічого не дає. У документації про морфінг $loop->index використано в іграшковому прикладі, і цю звичку не варто переймати. І ніколи не будуйте ключ на значенні, яке користувач може редагувати: ключ з імені чи email змінюється під час збереження, тож Livewire руйнує рядок і будує його заново - це виглядає як блимання і мовчки знищує клієнтський стан цього рядка.

Префікс у кожному ключі, щоб він був унікальним на всій сторінці

Ключі порівнюються в усьому відрендереному дереві компонентів, а не в межах циклу, який їх створив. Виведіть на одній сторінці рахунки і клієнтів, дайте обом голий {{ $model->id }} як ключ - і щойно рахунок і клієнт матимуть однаковий id, у вас з'явиться дубльований ключ. А це гірше, ніж відсутність ключа, бо тепер Livewire активно зіставляє два не пов'язані між собою елементи.

  <div>
    @foreach ($this->invoices as $invoice)
      <div wire:key="invoice-row-{{ $invoice->id }}">...</div>
    @endforeach

    @foreach ($this->customers as $customer)
      <div wire:key="customer-row-{{ $customer->id }}">...</div>
    @endforeach
  </div>

Оберіть одну угоду й застосовуйте її всюди: {noun}-{context}-{id}. Це нічого не коштує, робить дублікати помітними на рев'ю і дає змогу знайти їх в інспекторі елементів: порівняйте в консолі $$('[wire\\:key]').length з розміром new Set з тих самих значень - будь-яка різниця означає колізію.

Ключі для вкладених компонентів проти застарілого серверного стану

Це найсерйозніший випадок, бо тут уже ламається не лише DOM. Кожен вкладений компонент Livewire має власні wire:id і wire:snapshot, а коли батьківський компонент рендериться повторно, він виводить для кожного дочірнього заглушку, а не його повну розмітку. Якщо в дочірніх компонентів немає ключів, Livewire може зіставити елемент дочірнього компонента, що лишився, із заглушкою чужого запису - і екземпляр компонента, який він зберігає, містить публічні властивості попереднього запису.

  @foreach ($this->invoices as $invoice)
    <div wire:key="invoice-row-{{ $invoice->id }}">
      <livewire:invoice-status :$invoice :wire:key="'invoice-status-'.$invoice->id" />
    </div>
  @endforeach

Зверніть увагу на синтаксис прив'язки :wire:key у тегу компонента, а також на те, що дочірньому компоненту потрібен власний ключ, навіть якщо його обгортка вже має ключ. Компонент Livewire, вкладений глибоко в @foreach з ключами, усе одно лишається незалежним компонентом, який Livewire має зіставляти між запитами. Дві помилки, що з'являються, коли це не вдається, варто запам'ятати, бо лише тоді цей тип збою взагалі себе виказує:

  Error: Component already initialized
  Error: Snapshot missing on Livewire component with id: ...

І раз уже ви тут, перевірте, що дочірній компонент справді отримує дані, а не кешує їх із mount: ключі виправляють ідентичність, але коли батьківський компонент змінює значення, яке дочірній уже тримає, - це окрема проблема, яку розв'язують реактивні пропси між батьківським і дочірнім компонентами.

Обгортаємо умови й обходимо морфінг через wire:replace

Цикли - не єдине місце, де морфінгу доводиться вгадувати. Умова, що в кожній гілці рендерить структурно різні дерева, створює ту саму неоднозначність: це змінений елемент чи вставлений? Маркери морфінгу, які вставляє Livewire, здебільшого з цим справляються, але їх отримують розбором шаблонів регулярними виразами, тож вони можуть схибити. Надійне виправлення - обгорнути умову в елемент, який присутній завжди:

  <div> {{-- Рендериться завжди, тож у морфінгу є стабільна опора --}}
    @if ($errors->has('reference'))
      <div>{{ $errors->first('reference') }}</div>
    @endif
  </div>

Якщо у вашому застосунку маркери створюють більше проблем, ніж розв'язують, їх можна вимкнути повністю через 'inject_morph_markers' => false у config/livewire.php - але вважайте це крайнім заходом, а не ручкою для тонкого налаштування.

Для піддерева, яке ніколи не має проходити морфінг, wire:replace каже Livewire викинути дочірні елементи і вставити натомість нові елементи з сервера. Це правильний вибір для сторонніх віджетів і користувацьких елементів (custom elements), які самі керують своїм внутрішнім життєвим циклом, - та сама проблема межі, що й під час інтеграції стороннього JavaScript з Livewire.

  <div wire:replace>
    <json-viewer>@json($payload)</json-viewer>
  </div>

  {{-- .self замінює і сам елемент, скидаючи його x-data --}}
  <div x-data="{ open: false }" wire:replace.self>
    ...
  </div>

Ключі для lazy-компонентів та islands

Відкладений рендеринг не послаблює проблему порядку, а посилює, бо список змінює форму двічі: коли рендериться заглушка і коли надходить справжній вміст. Лінивому (lazy) дочірньому компоненту в циклі ключ потрібен із тієї самої причини, що й звичайному: Livewire має знати, яка заглушка належить якому запису, перш ніж щось підставляти.

  @foreach ($this->invoices as $invoice)
    <livewire:invoice-breakdown
      :$invoice
      :wire:key="'invoice-breakdown-'.$invoice->id"
      lazy
    />
  @endforeach

Те саме стосується випадку, коли ви ділите сторінку на islands і ліниво завантажувані компоненти: island оновлюється незалежно, тож його ідентичність у списку має бути стабільною, інакше оновлення потрапить не туди. Якщо поки islands завантажуються, ви показуєте скелетони-заглушки, дайте заглушці й завантаженому вмісту однаковий ключ, інакше підміна стане знищенням і створенням заново, а не морфінгом.

Чотири помилки з ключами, що створюють нові баги

Додати ключі дешево, тому їх легко додати погано. Ось чотири помилки, на які я найчастіше вказую на рев'ю.

Ключі всюди. @foreach з простих <td> без Alpine, без обробників подій і без некерованих полів ключа не потребує, а ключ там лише ховає місця, де він справді потрібен. Ставте ключі на цикли, що рендерять компонент, блок x-data або будь-яке поле, яким не керує сервер.

Ключі зі змінних значень. Ключ зі slug, імені чи email змінюється, коли користувач його редагує, і змушує повністю перебудувати рядок. Будуйте ключ на id.

Дубльовані ключі. Два цикли в одному дереві компонентів, обидва з голим id як ключем, мовчки конфліктують. Livewire не завжди вас попередить - ставте префікс.

Зміна порядку без ключів. Drag-and-drop - найгірший випадок, бо неправильним стає кожен елемент одразу, а не один. Сортування перетягуванням через wire:sort без стабільних ключів просто непридатне до використання.

Ловимо відсутні ключі на рев'ю і в Pest

Зробіть правило механічним, щоб воно не залежало від чиєїсь пам'яті: кожен @foreach, що рендерить компонент Livewire, блок Alpine або некероване поле, має wire:key з префіксом. Це однорядковий grep у CI і однорядковий коментар на рев'ю.

Тест важливіший за правило, і очевидний тест якраз не працює. Перевірка першого рендеру проходить на зламаному компоненті, бо перший рендер завжди правильний - баг існує лише в морфінгу. Перевіряйте стан після мутації.

  <?php

  use App\Models\Invoice;
  use Illuminate\Foundation\Testing\RefreshDatabase;
  use Livewire\Livewire;

  uses(RefreshDatabase::class);

  it('keeps a stable key on the surviving rows after a delete', function () {
    $invoices = Invoice::factory()->count(3)->create();

    Livewire::test('invoice-list')
      ->call('delete', $invoices[1]->id)
      // Рядки, що лишилися, зберігають власну ідентичність, а не нову позицію
      ->assertSeeHtml('wire:key="invoice-row-'.$invoices[2]->id.'"')
      ->assertDontSeeHtml('wire:key="invoice-row-'.$invoices[1]->id.'"');
  });

Будьмо чесними щодо того, що це доводить: тест перевіряє, що ключі виводяться і що вони правильні, - а саме це й можна зламати в шаблоні. Він не доводить, що браузер зберіг стан Alpine, бо жодна серверна перевірка цього не може, - для цього потрібен браузерний тест. На практиці перевірка виведених ключів ловить ту регресію, яка справді трапляється: хтось видаляє атрибут під час рефакторингу. Livewire::test() не бачить браузера, тож межу між серверним і браузерним тестом варто тримати в голові.

Підсумок

Пройдіться по кожному @foreach у застосунку, що рендерить компонент або блок Alpine, і дайте йому ключ з префіксом, збудований із первинного ключа моделі. Це займе пів дня і закриє цілу категорію баг-репортів, які зараз позначають як «не вдалося відтворити».

Переклад оригіналу: richdynamix.com
10

Читати в документації

Коментарі

Увійдіть, щоб залишити коментар

Будьте першим, хто залишить коментар!

Читайте також

Laravel AI SDK у продакшні
Переклади 19 листопада 2026

Новинний пайплайн на Laravel AI SDK: агенти, structured output і пастки, про які не попереджають

Переказ статті Івайло Ніколова про сервіс, що щодня обробляє десятки тисяч новин на laravel/ai: ембединги, кластеризація в pgvector, агенти зі structured output і три збої, яких не помітив жоден тест.

12
PHPStan 2.3
Переклади 18 листопада 2026

PHPStan 2.3 на реальному Laravel-застосунку: що прискорилося, а що зламалося

Іван Михавко оновив PHPStan і Larastan на робочому Laravel-проєкті з 1145 файлів і заміряв усе: холодний запуск став удвічі швидшим, теплий майже не змінився, а bleeding edge поки не вартий того, щоб його вмикати.

Вакансії за темою

Black River Express
17 днів тому

Senior PHP Developer

Senior PHP розробник для логістичної платформи: бекенд-сервіси на PHP 8.3+ та Laravel 11 і веб-панель на Filament 3 та Livewire 3. Завдання: REST API, авторизація, інтеграції через API і вебхуки, оптимізація PostgreSQL, черги та кешування. Вимоги: комерційний досвід Laravel, знання PostgreSQL, Redis, WebSockets, CI/CD та діагностики продакшн-проблем. Віддалено, також розглядають сильних Middle+.

Optimizee Group
68 днів тому

Product Lead (Strategy + Full Stack)

Product Lead з відповідальністю за розробку та лідерство. Гібридна роль: 60% управління продуктом (дорожна карта, пріоритизація, аналітика) та 40% full stack розробки на PHP Laravel. Потрібен досвід розробника (5+ років), знання бекенду, баз даних, здатність приймати продуктові рішення та керувати командою. Основний стек: PHP 8.2+, Laravel 12, MySQL, Redis, Alpine.js, Livewire.

Bankstore AI
99 днів тому

Full Stack PHP/Laravel+JS (AI, Vibe code engineer)

Full Stack розробник на PHP/Laravel та JavaScript. Розроблятиме та підтримуватиме функціонал платформи для фінтеху, працюючи з бекенду (PHP, Laravel, REST API, MySQL, Redis) і фронтенду (JavaScript, Alpine.js). Потрібен мінімум 2 роки досвіду, вміння адмініструвати Linux/Ubuntu, розгортати на AWS/DigitalOcean, користуватися AI-інструментами для розробки.

Пакети за темою

Kalimera

welldigit/kalimera

Interactive installer that scaffolds Laravel applications the Well Digit way.

v1.0.0 17

Filament

filament/filament

Найпопулярніша адмін-панель для Laravel: ресурси, таблиці, форми та дашборди описуються PHP-класами поверх Livewire, Alpine і Tailwind. Замінює рутину CRUD-інтерфейсів декларативною конфігурацією.

31,852 v5.7.6 11