Návod k upgradu

Jak bezpečně přecházet mezi verzemi Wire a kde hledat breaking changes.

Verzování

Ekosystém Wire se dodává jako čtyři balíčky — wire-core, wire-forms, wire-table, wire-sortable — vydávané společně z jednoho monorepa, takže se jejich verze pohybují v zámku. Instalujte je a omezujte jako celek.

Wire je aktuálně ve větvi 0.x. Podle běžné konvence před 1.0 mohou minor vydání obsahovat breaking changes, proto si připněte otestovanou verzi a před zvýšením si přečtěte changelog:

// composer.json
"require": {
    "nyoncode/wire-core":     "^0.1",
    "nyoncode/wire-forms":    "^0.1",
    "nyoncode/wire-table":    "^0.1",
    "nyoncode/wire-sortable": "^0.1"
}

Požadavky

Před upgradem ověřte, že je vaše aplikace splňuje.

Minimální verze závislostí (1.17)

Laravel 10 a 11 končí. Verze 1.17 přesunula JavaScriptové bundly z package route do reálných souborů pod public/vendor a kód, který je tam zrcadlí, žije v nyoncode/laravel-package-toolkit — vedle deklarace hasAssets() a publish tagu, jehož je čtecí stranou. Toolkit stojí na illuminate/support ^12.61.1|^13.12.0 a minimum závislosti je i vaše minimum: aplikace pod ním balíčky Wire nenainstaluje, ať v jejich vlastním composer.json stojí ^12.0. Nejdřív povyšte Laravel, pak Wire.

Constraint toolkitu je ^2.4. Přímo si ho nevyžadujete, takže v běžném případě ho composer update "nyoncode/wire-*" posune se vším ostatním a není co řešit. Viditelný je jen ve dvou situacích:

• váš composer.json nyoncode/laravel-package-toolkit jmenuje — protože na něm stavíte vlastní balíček, nebo ze starého pinu — a drží ho pod 2.4. Composer pak hlásí jako neinstalovatelné balíčky Wire, ne toolkit jako starý, takže ten constraint rozšiřte na ^2.4 jako první.
• běžíte na Octane. Memo assetů, které je jinak per-request a tady přežívá celý worker, se na RequestTerminated zahazuje přes PublishedAssets::flush() z toolkitu, a 2.4 je první vydání, které ho nese. Pod ním worker, který přežije deploy, dál emituje ?id=<mtime> z minulého vydání a wire:navigate si nových bundlů nikdy nevšimne.

Kroky upgradu

1. Přečtěte si changelog. Zkontrolujte CHANGELOG.md pro verze, které přeskakujete, zejména jakoukoli sekci Breaking Changes.

2. Aktualizujte balíčky.

   composer update "nyoncode/wire-*"

3. Znovu zkontrolujte publikované soubory. Pokud jste publikovali konfiguraci, pohledy nebo překlady, vaše kopie se neaktualizují automaticky. Porovnejte je s novými verzemi balíčků a zapracujte relevantní změny:

   • config/wire-*.php
   • resources/views/vendor/wire-*/…
   • lang/vendor/wire-*/…

   Čím méně pohledů přepisujete, tím méně je zde ke sladění — viz Vzhled → Přepis pohledů.

4. Vyčistěte cache a přebuildujte assety.

   php artisan view:clear
   php artisan config:clear
   npm run build

5. Spusťte testovací sadu. Testovací sada je nejrychlejší způsob, jak odchytit breaking change ve vlastních formulářích a tabulkách.

Výběr a klávesová gesta

Z výběru v tabulce se stala plnohodnotná sada gest, ne jen sloupec zaškrtávátek (viz Výběr řádků). Při upgradu zkontrolujte čtyři věci.

1. Všechna gesta nad řádkem jsou opt-in — ->gestures(). Z výběru se stala plnohodnotná sada gest: Shift/mod kliky pro rozsahy, tažení po sloupci se zaškrtávátky, které nabere celý blok, a z klávesnice šipky, Space, Shift+šipky a mod+A. Nic z toho není zapnuté, dokud si o to tabulka neřekne — každé z nich totiž mění chování tabulky vůči návštěvníkovi, který ji ovládat nezamýšlel: řádky jdou do pořadí tabulátoru, označuje se aktivní řádek, tažení začne vybírat a modifikovaný klik přestane být klikem.

Tabulkám, které to chtějí, přidejte jedno volání:

->gestures()
->selectable()

nebo, pokud je celý projekt back office:

// config/wire-table.php
'defaults' => ['gestures' => true],

Co změna neovlivní: zaškrtávátka, oba ovladače „vybrat vše" i bulk bar fungují beze změny a tabulka, která si o gesta neřekla, nemontuje delegovaný controller vůbec. Stejně tak kontextové menu pod pravým tlačítkem a fill handle — o oboje jste si stejně museli říct sami. Šest schopností a jak je kombinovat najdete ve Vrstvě gest.

2. ->onKey() na navigační klávese nově vyhodí výjimku. Dřív se tiše zahodila, takže akce prostě nikdy nevystřelila. Pokud takovou vazbu máte, byla to už dřív mrtvá větev — přemapujte ji na volnou klávesu:

Enter  Space  ArrowUp  ArrowDown  Home  End  PageUp  PageDown  ContextMenu  F10  ?

Backspace zůstává k dispozici a nově funguje i jako alias klávesy Delete.

3. Rozsahová gesta už neopouštějí režim „vše odpovídající". Když je vybráno „vše, co odpovídá filtru", je uložený seznam seznamem výjimek — takže rozsah přes Shift+šipku ho nově odznačí, místo aby celý výběr zúžil na jednu stránku. Pokud výběr čtete přímo, počítejte s tím, že getSelectedRecordKeys() v tomto režimu záměrně vrací []; použijte selectedRecordsQuery() nebo eachSelectedRecord().

4. Přepublikujte view tabulky, pokud jste ho přepsali. Gesta potřebují markup, který zkompilovaný JavaScript hledá, a publikovaná kopie resources/views/vendor/wire-table/tables/index.blade.php ho mít nebude. View nese kontraktní značku, takže zastaralá kopie spadne hlasitě v konzoli prohlížeče místo toho, aby tiše vybírala špatné řádky:

php artisan vendor:publish --tag=wire-table::views --force

Své úpravy pak naneste znovu na nový soubor. Pokud jste view přepsali jen kvůli vzhledu, bývá Theming menší cesta.

5. Akce nad záznamem, které byly jen chováním, se na mobilní kartě nově vykreslí jako tlačítko. Telefon nemá dvojklik, pravý klik ani hover, kterým by se jeden nebo druhý dal objevit — akce navázaná jen na gesto tak byla po složení tabulky nedosažitelná. Nově se na kartě vykreslí jako obyčejné tlačítko, a jen tam; desktopová tabulka se nemění. Nic se nezdvojí: akce už přítomná v ->actions() i akce povýšená přes ->alsoInRowActions() dá právě jedno tlačítko a fallbacková tlačítka se počítají do ->collapseActionsOnMobile(). Vypnout lze pro konkrétní tabulku:

->recordActionButtonsOnMobile(false)

JavaScriptové assety

Alpine controllery Wire si nově deklaruje každý balíček sám a dají se vypsat z jednoho místa ve vašem layoutu. Při upgradu udělejte dvě věci.

1. Přidejte @wireStackScripts do <head> layoutu.

<head>
    @vite(['resources/css/app.css', 'resources/js/app.js'])
    @livewireStyles
    @wireStackScripts 
</head>

Je to aditivní — každý povrch si svůj bundle stále načte sám, takže aplikace bez direktivy funguje dál. Ale je to právě ono, co opraví komponenty umírající po návštěvě přes wire:navigate (wireRecordSelection is not defined, mrtvé dropdowny, šedý scrim přes tabulku): cesta cachovaného Zpět/Vpřed v Livewire nečeká na nově injektované <head> skripty a imunní je jen bundle, který už v dokumentu byl. Viz Začínáme → JavaScriptové assety.

Pokud si vaše aplikace tohle dřív obcházela @include-ováním partialů balíčků v layoutu, tyhle includy smažte a použijte direktivu — cesty k partialům jsou interní a direktiva se s nimi stejně deduplikuje.

2. window.Sortable už se neposkytuje. SortableJS je zkompilovaný do bundlu wire-sortable, takže config('wire-sortable.sortablejs_cdn') je nově ve výchozím stavu null a žádný CDN skript se nenačítá. Řazení to neovlivní — drag controller používá zabundlovanou kopii a globál nikdy nečte.

Týká se to jen vašeho vlastního kódu, pokud na existenci toho globálu spoléhal. Buď si o skript řekněte zpět:

// config/wire-sortable.php
'sortablejs_cdn' => 'https://cdn.jsdelivr.net/npm/sortablejs@1.15.6/Sortable.min.js',

nebo si SortableJS zabundlujte sami:

// resources/js/app.js
import Sortable from 'sortablejs';
window.Sortable = Sortable;

Nic dalšího se nemění: konfigurační klíč po nastavení pořád funguje a aplikací, které ho už nastavené mají, se změna nedotkne.

Hledání breaking changes

CHANGELOG.md je zdroj pravdy. Breaking changes jsou vyznačeny pod nadpisem Breaking Changes u každého vydání, často s migrační tabulkou před/po. Například vydání 0.1.0 přesunulo akce a notifikace z NyonCode\WireTable\… do NyonCode\WireCore\…; changelog vypisuje každou přesunutou třídu, takže můžete use příkazy upravit hromadným najít-a-nahradit.

Pokud třída nebo metoda zmíněná v této dokumentaci po upgradu už neexistuje, byla pravděpodobně přesunuta nebo přejmenována — hledejte původní název v CHANGELOG.md.

Viz také

• Začínáme — požadavky a instalace
• Konfigurace — publikovatelná konfigurace
• Vzhled — udržování přepisů pohledů na minimu
• Řešení potíží — problémy, které se objeví po aktualizaci