Livewire 4 — повний посібник

composer require livewire/livewire:^4.0

php artisan optimize:clear

php artisan livewire:publish --config

// Продовжувати генерувати класові компоненти замість однофайлових
'make_command' => [
    'type' => 'class',
],

php artisan make:livewire post.create
# resources/views/components/post/⚡create.blade.php

<?php

use Livewire\Component;
use App\Models\Post;
use Livewire\Attributes\Validate;

new class extends Component {
    #[Validate('required|string|min:5|max:180')]
    public string $title = '';

    #[Validate('required|string|min:50')]
    public string $body = '';

    public function save()
    {
        $this->validate();

        Post::create([
            'title'   => $this->title,
            'body'    => $this->body,
            'user_id' => auth()->id(),
        ]);

        $this->reset();

        $this->dispatch('notify', message: 'Допис створено');
    }
};

?>

<div>
    <form wire:submit="save">
        <input type="text" wire:model="title" placeholder="Заголовок">
        @error('title') <span class="error">{{ $message }}</span> @enderror

        <textarea wire:model="body" placeholder="Текст"></textarea>
        @error('body') <span class="error">{{ $message }}</span> @enderror

        <button type="submit">Зберегти</button>
    </form>
</div>

php artisan make:livewire post.create --mfc

<?php

namespace App\Livewire;

use Livewire\Component;

class CreatePost extends Component
{
    public string $title = '';

    public function render()
    {
        return view('livewire.create-post');
    }
}

resources/views/
├── components/
│   ├── ⚡counter.blade.php              → <livewire:counter />
│   ├── post/
│   │   ├── ⚡create.blade.php           → <livewire:post.create />
│   │   └── ⚡index.blade.php            → <livewire:post.index />
│   └── button.blade.php                 (звичайний Blade-компонент)
└── pages/
    └── ⚡dashboard.blade.php            → <livewire:pages::dashboard />

{{-- За іменем --}}
<livewire:counter />

{{-- Вкладені каталоги через крапку --}}
<livewire:post.create />

{{-- З namespace --}}
<livewire:pages::post.create />

{{-- З параметрами --}}
<livewire:post.create :title="$initialTitle" :author="$user" />

use App\Livewire\Dashboard;

// За класом
Route::livewire('/dashboard', Dashboard::class);

// За іменем компонента — звичний вибір для view-based компонентів
Route::livewire('/dashboard', 'pages::dashboard')
    ->middleware('auth')
    ->name('dashboard');

'component_layout' => 'layouts::app',

use Livewire\Attributes\Layout;
use Livewire\Attributes\Title;

new class extends Component {
    #[Layout('layouts::app')]
    #[Title('Панель керування')]
    public function render() { /* … */ }
};

new class extends Component {
    public string $name = '';
    public ?int $age = null;
    public array $tags = [];
    public bool $isPublic = false;
};

<?php

use Livewire\Component;
use Livewire\Attributes\Prop;

new class extends Component {
    #[Prop]
    public string $type = 'info';

    #[Prop]
    public bool $dismissible = false;
};

?>

<div {{ $attributes->merge(['class' => 'alert alert-'.$type]) }}>
    {{ $slot }}

    @if ($dismissible)
        <button wire:click="$dispatch('dismiss')">×</button>
    @endif
</div>

<livewire:alert type="warning" dismissible class="mt-4">
    Рахунок прострочено.
</livewire:alert>

use App\Models\Order;

new class extends Component {
    public Order $order;
    public string $mode;

    public function mount(Order $order, string $mode = 'compact'): void
    {
        $this->order = $order;
        $this->mode  = $mode;
    }
};

use Livewire\Attributes\Locked;

new class extends Component {
    #[Locked]
    public int $invoiceId;   // клієнт не підставить чужий id

    public string $note = '';
};

{{-- Livewire 3 --}}
<input wire:model.blur="title">

{{-- Еквівалент тієї ж поведінки у v4 --}}
<input wire:model.live.blur="title">

{{-- Livewire 3: обгортка ловила подію поля --}}
<div wire:model="value">
    <input type="text">
</div>

{{-- Livewire 4: вмикаємо явно --}}
<div wire:model.deep="value">
    <input type="text">
</div>

{{-- За замовчуванням відкладено --}}
<input type="text" wire:model="name">

{{-- Запит на кожну зміну --}}
<input type="text" wire:model.live="search">

{{-- Живий пошук із затримкою --}}
<input type="text" wire:model.live.debounce.400ms="search">

{{-- Вкладені дані --}}
<input wire:model="form.address.city">
<input wire:model="post.title">

<button wire:click="save">Зберегти</button>

<form wire:submit="save">…</form>

<button wire:click="delete({{ $post->id }})"
        wire:confirm="Видалити допис? Скасувати буде неможливо.">Видалити</button>

use Livewire\Attributes\Renderless;

new class extends Component {
    #[Renderless]
    public function incrementViewCount(): void
    {
        $this->post->increment('views');
    }
};

<button type="button" wire:click.renderless="incrementViewCount">Врахувати</button>

use Livewire\Attributes\Async;

new class extends Component {
    #[Async]
    public function logInteraction(string $element): void
    {
        Analytics::record($element, auth()->id());
    }
};

<button wire:click.async="logInteraction('cta-hero')">Почати</button>

<button wire:click="$refresh">Оновити</button>
<button wire:click="$set('tab', 'settings')">Налаштування</button>
<button wire:click="$toggle('showFilters')">Фільтри</button>
<button wire:click="$dispatch('open-modal', { name: 'create' })">Створити</button>
<button wire:click="$parent.closeModal()">Закрити</button>

1. Створюється екземпляр компонента
2. boot()
3. mount($params)
4. booted()
5. render()

 1. Надходить POST /livewire-{hash}/update зі snapshot стану
 2. Перевіряється контрольна сума snapshot
 3. Створюється екземпляр компонента
 4. boot()
 5. Стан відновлюється зі snapshot
 6. hydrate() / hydrateFoo()
 7. booted()
 8. updating($prop, $value) / updatingFoo($value)
 9. Властивості отримують нові значення
10. updated($prop, $value) / updatedFoo($value)
11. Виконуються дії з черги
12. rendering() → render() → rendered($view, $html)
13. dehydrate() — стан пакується назад у snapshot
14. Відповідь: розмітка + effects

new class extends Component {
    public float $price = 0;

    public function boot(): void {}
    public function booted(): void {}
    public function hydrate(): void {}
    public function dehydrate(): void {}

    public function updating(string $property, mixed $value): void {}

    public function updated(string $property, mixed $value): void
    {
        $this->validateOnly($property);
    }

    public function updatedPrice(mixed $value): void
    {
        $this->price = round((float) $value, 2);
    }

    public function updatedFormEmail(mixed $value): void
    {
        $this->form['email'] = strtolower(trim($value));
    }
};

use Livewire\Attributes\Validate;

new class extends Component {
    #[Validate('required|string|min:2|max:80')]
    public string $name = '';

    #[Validate('required|email:rfc,dns')]
    public string $email = '';

    #[Validate('accepted', message: 'Потрібна згода на обробку даних.')]
    public bool $consent = false;

    public function submit(): void
    {
        $data = $this->validate();

        Contact::create($data);

        $this->reset();
    }
};

protected function rules(): array
{
    return [
        'email' => [
            'required',
            'email',
            Rule::unique('users', 'email')->ignore($this->userId),
        ],
        'password' => $this->userId ? 'nullable|min:8|confirmed' : 'required|min:8|confirmed',
    ];
}

<?php

namespace App\Livewire\Forms;

use App\Models\Post;
use Livewire\Attributes\Validate;
use Livewire\Form;

class PostForm extends Form
{
    public ?Post $post = null;

    #[Validate('required|string|min:5|max:180')]
    public string $title = '';

    #[Validate('required|string|min:50')]
    public string $body = '';

    public function store(): Post
    {
        $this->validate();

        return Post::create($this->except('post'));
    }

    public function update(): void
    {
        $this->validate();

        $this->post->update($this->except('post'));
    }
}

<div x-show="$errors.has('email')" x-text="$errors.first('email')"></div>

@island
    <div>Виручка: {{ $this->revenue }}</div>
@endisland

<?php

use Livewire\Component;
use Livewire\Attributes\Computed;

new class extends Component {
    #[Computed]
    public function revenue()
    {
        return Order::whereMonth('created_at', now()->month)->sum('total');
    }

    #[Computed]
    public function queue()
    {
        return Job::pending()->count();
    }
};

?>

<div>
    @island(name: 'revenue')
        <div class="card">
            <h3>Виручка за місяць</h3>
            <p class="stat">{{ number_format($this->revenue, 2, ',', ' ') }} €</p>
        </div>
    @endisland

    @island(name: 'queue', poll: '5s')
        <div class="card">
            <h3>Завдань у черзі</h3>
            <p class="stat">{{ $this->queue }}</p>
        </div>
    @endisland

    @island(name: 'feed', lazy: true)
        @placeholder
            <div class="card skeleton animate-pulse h-64"></div>
        @endplaceholder

        <div class="card">…</div>
    @endisland
</div>

@island(name: 'revenue')
    Виручка: {{ $this->revenue }}
@endisland

<button wire:click="$refresh" wire:island="revenue">Оновити виручку</button>

@island(name: 'feed')
    @foreach ($this->posts as $post)
        <article wire:key="post-{{ $post->id }}">{{ $post->title }}</article>
    @endforeach
@endisland

<button wire:click="loadMore" wire:island.append="feed">Показати ще</button>

<button x-on:click="$wire.$island('feed', { mode: 'append' }).loadMore()">
    Показати ще
</button>

@island(name: 'queue')
    <div wire:poll.3s>
        Завдань у черзі: {{ $this->queue }}
    </div>
@endisland

<livewire:modal>
    <h2>Створити допис</h2>

    <form wire:submit="save">
        <input wire:model="title">
        <button type="submit">Зберегти</button>
    </form>
</livewire:modal>

<?php

use Livewire\Component;

new class extends Component {
    public bool $isOpen = false;

    public function toggle(): void
    {
        $this->isOpen = ! $this->isOpen;
    }
};

?>

<div wire:show="isOpen" class="modal">
    <button wire:click="toggle" class="modal__close">×</button>

    <div class="modal__body">
        {{ $slot }}
    </div>
</div>

<livewire:modal>
    <wire:slot name="header">
        <h2>Створити допис</h2>
    </wire:slot>

    <form wire:submit="save">
        <input wire:model="title">
    </form>

    <wire:slot name="footer">
        <button wire:click="save">Зберегти</button>
    </wire:slot>
</livewire:modal>

<div class="modal">
    @if ($header = $slot('header'))
        <div class="modal__header">{{ $header }}</div>
    @endif

    <div class="modal__body">{{ $slot }}</div>

    @if ($footer = $slot('footer'))
        <div class="modal__footer">{{ $footer }}</div>
    @endif
</div>

<?php

use Livewire\Component;
use Livewire\Attributes\Prop;

new class extends Component {
    #[Prop]
    public string $type = 'info';
};

?>

<div {{ $attributes->merge(['class' => 'alert alert-'.$type]) }}>
    {{ $slot }}
</div>

<livewire:alert type="danger" class="mt-6" data-testid="overdue-alert">
    Рахунок прострочено на 14 днів.
</livewire:alert>

<div>
    @foreach ($orders as $order)
        <livewire:order-row :order="$order" :key="'order-'.$order->id" />
    @endforeach
</div>

@foreach ($rows as $row)
    <div wire:key="row-{{ $row->id }}">…</div>
@endforeach

use Livewire\Attributes\Reactive;

new class extends Component {
    #[Reactive]
    public int $quantity;
};

<button wire:click="$parent.refreshList()">Оновити список</button>

use Livewire\Attributes\Modelable;

new class extends Component {
    #[Modelable]
    public int $value = 0;
};

$this->dispatch('post-created');
$this->dispatch('post-created', postId: $post->id, title: $post->title);
$this->dispatch('refresh')->to(OrderList::class);
$this->dispatch('recalculate')->self();

use Livewire\Attributes\On;

new class extends Component {
    #[On('post-created')]
    public function onPostCreated(int $postId, string $title): void
    {
        // …
    }
};

$this->dispatch('notify', type: 'success', message: 'Замовлення збережено');

<div x-data="{ show: false, message: '' }"
     x-on:notify.window="message = $event.detail.message; show = true; setTimeout(() => show = false, 3000)"
     x-show="show"
     x-transition
     class="toast">
    <span x-text="message"></span>
</div>

use Livewire\Attributes\Computed;

new class extends Component {
    public array $items = [];

    #[Computed]
    public function products()
    {
        return Product::whereIn('id', array_keys($this->items))->get();
    }

    #[Computed]
    public function subtotal(): float
    {
        return $this->products->sum(
            fn ($product) => $product->price * $this->items[$product->id]
        );
    }
};

@island(name: 'totals')
    <p>Сума: {{ number_format($this->subtotal, 2, ',', ' ') }} €</p>
@endisland

#[Computed(persist: true, seconds: 300)]
public function statistics(): array
{
    return [
        'orders'  => Order::whereMonth('created_at', now()->month)->count(),
        'revenue' => Order::whereMonth('created_at', now()->month)->sum('total'),
    ];
}

use Livewire\Attributes\Url;
use Livewire\Attributes\Session;

new class extends Component {
    #[Url]
    public string $search = '';

    #[Url(as: 'cat')]
    public ?int $categoryId = null;

    #[Url(except: '')]
    public string $sort = 'popular';

    #[Url(keep: true)]
    public int $perPage = 24;

    #[Session]
    public bool $sidebarCollapsed = false;
};

public function save(): void
{
    $this->validate();

    session()->flash('status', 'Налаштування збережено');
}

<?php

use Livewire\Component;
use Livewire\WithFileUploads;
use Livewire\Attributes\Validate;

new class extends Component {
    use WithFileUploads;

    #[Validate('required|image|mimes:jpg,jpeg,png,webp|max:4096')]
    public $avatar;

    public function save(): void
    {
        $this->validate();

        $path = $this->avatar->store('avatars', 'public');

        auth()->user()->update(['avatar_path' => $path]);

        $this->reset('avatar');
    }
};

?>

<div>
    <form wire:submit="save">
        <input type="file" wire:model="avatar" accept="image/*">

        <div wire:loading wire:target="avatar">Завантажуємо…</div>

        @if ($avatar)
            <img src="{{ $avatar->temporaryUrl() }}" alt="Прев’ю" class="preview">
        @endif

        @error('avatar') <p class="error">{{ $message }}</p> @enderror

        <button type="submit" wire:loading.attr="disabled">Зберегти</button>
    </form>
</div>

<div x-data="{ progress: 0, uploading: false }"
     x-on:livewire-upload-start="uploading = true"
     x-on:livewire-upload-finish="uploading = false; progress = 0"
     x-on:livewire-upload-progress="progress = $event.detail.progress">

    <input type="file" wire:model="avatar">

    <div x-show="uploading" class="progress">
        <div class="progress__bar" :style="`width: ${progress}%`"></div>
    </div>
</div>

use Livewire\WithPagination;

new class extends Component {
    use WithPagination;

    public string $search = '';

    public function updatedSearch(): void
    {
        $this->resetPage();
    }

    public function with(): array
    {
        return [
            'orders' => Order::query()
                ->with('customer')
                ->when($this->search, fn ($q) => $q->where('number', 'like', "%{$this->search}%"))
                ->paginate(25),
        ];
    }
};

<div>
    <input type="search" wire:model.live.debounce.400ms="search">

    @island(name: 'rows')
        @foreach ($orders as $order)
            <div wire:key="order-{{ $order->id }}">{{ $order->number }}</div>
        @endforeach
    @endisland

    <button wire:click="nextPage" wire:island.append="rows">Показати ще</button>
</div>

<div wire:loading>Завантаження…</div>
<div wire:loading.remove>Вміст</div>

<button wire:click="save">Зберегти</button>
<span wire:loading wire:target="save">Зберігаємо…</span>

<button wire:click="save" wire:loading.attr="disabled">Зберегти</button>
<button wire:click="save" wire:loading.class="opacity-50 cursor-wait">Зберегти</button>

<div wire:loading.delay>Завантаження…</div>
<div wire:loading.delay.long>Завантаження…</div>

[data-loading] .btn {
    opacity: 0.5;
    pointer-events: none;
}

<input wire:model="title">

<span wire:dirty wire:target="title">Є незбережені зміни</span>

<div wire:offline class="banner banner--warn">
    Немає з’єднання із сервером.
</div>

{{-- Перемикає видимість через CSS, миттєво --}}
<div wire:show="showModal" class="modal">…</div>

<button wire:click="$toggle('showModal')">Відкрити</button>

{{-- Текст слідує за властивістю на клієнті --}}
<span wire:text="title"></span>

<input wire:model="title">

<textarea wire:model="message" maxlength="280"></textarea>

<span wire:text="message.length"></span> / 280

<span wire:bind:class="message.length > 240 && 'text-red-500'">
    Стає задовго
</span>

<ul wire:sort="reorder">
    @foreach ($tasks as $task)
        <li wire:sort:item="{{ $task->id }}" wire:key="task-{{ $task->id }}">
            {{ $task->title }}
        </li>
    @endforeach
</ul>

new class extends Component {
    public function reorder(array $order): void
    {
        foreach ($order as $position => $id) {
            Task::where('id', $id)->update(['position' => $position]);
        }
    }
};

<ul wire:sort="reorder">
    @foreach ($tasks as $task)
        <li wire:sort:item="{{ $task->id }}" wire:key="task-{{ $task->id }}">
            <span wire:sort:handle class="cursor-grab">⠿</span>

            <span>{{ $task->title }}</span>

            <button wire:sort:ignore wire:click="delete({{ $task->id }})">Видалити</button>
        </li>
    @endforeach
</ul>

<div class="board">
    @foreach ($columns as $column)
        <ul wire:sort="moveCard" wire:sort:group="board" wire:key="column-{{ $column->id }}">
            @foreach ($column->cards as $card)
                <li wire:sort:item="{{ $card->id }}" wire:key="card-{{ $card->id }}">
                    {{ $card->title }}
                </li>
            @endforeach
        </ul>
    @endforeach
</div>

<?php

use Livewire\Component;
use Livewire\Attributes\Prop;

new class extends Component {
    #[Prop]
    public string $plan = 'starter';
};

?>

<div class="card">
    <h3 class="title">{{ ucfirst($plan) }}</h3>
    <p class="price">{{ $this->price }} € / місяць</p>
</div>

<style>
    /* Скоупиться цим компонентом — жодних глобальних колізій по .title */
    .card  { border: 1px solid #e4e2da; border-radius: 14px; padding: 24px; }
    .title { font-size: 20px; font-weight: 700; }
    .price { color: #2d6a4f; }
</style>

<style global>
    :root { --brand: #f53004; }
</style>

@script
<script>
    const chart = new Chart(document.getElementById('sales'), {
        type: 'line',
        data: @json($chartData),
    });

    $wire.on('data-updated', ({ points }) => {
        chart.data.datasets[0].data = points;
        chart.update();
    });
</script>
@endscript

<a href="/orders" wire:navigate>Замовлення</a>
<a href="/orders" wire:navigate.hover>Замовлення</a>
<a href="/login" wire:navigate.replace>Увійти</a>

<div class="sidebar" wire:navigate:scroll>
    …
</div>

@persist('player')
    <audio src="{{ $currentTrack->url }}" controls></audio>
@endpersist

document.addEventListener('livewire:navigated', () => { initThirdPartyWidgets(); });

{{-- Компонент цілком --}}
<livewire:revenue-chart lazy />
<livewire:revenue-chart lazy="on-scroll" />

{{-- Лише ділянка --}}
@island(lazy: true)
    @placeholder
        <div class="skeleton animate-pulse h-64"></div>
    @endplaceholder

    <div>{{ $this->expensiveReport }}</div>
@endisland

<div wire:intersect="loadMore">…</div>

<div wire:poll.visible.5s="refreshQueue">…</div>

<div x-data="{ open: false }">
    <button x-on:click="open = !open">Деталі</button>

    <div x-show="open">
        <p x-text="$wire.title"></p>

        <button x-on:click="$wire.save()">Зберегти</button>
        <button x-on:click="await $wire.calculate(); open = false">Розрахувати</button>
    </div>
</div>

<livewire:modal wire:ref="modal" />

<button x-on:click="$refs.modal.open()">Відкрити модалку</button>

use Livewire\Attributes\Json;

new class extends Component {
    #[Json]
    public function searchSuggestions(string $term): array
    {
        return Product::search($term)->take(5)->pluck('name')->all();
    }
};

document.addEventListener('livewire:init', () => {

    Livewire.interceptRequest(({ options, fail }) => {
        options.headers['X-Tenant'] = window.tenantId;

        fail(({ status, preventDefault }) => {
            if (status === 419) {
                preventDefault();
                window.location.reload();
            }
        });
    });

    Livewire.interceptMessage(({ component, succeed }) => {
        succeed(() => {
            console.debug('компонент оновлено', component.name);
        });
    });
});

<div wire:ignore>
    <select id="select2-field">…</select>
</div>

php artisan make:livewire post.create --test
# resources/views/components/post/create.test.php

use Livewire\Livewire;

it('рендериться', function () {
    Livewire::test('post.create')
        ->assertStatus(200);
});

it('валідує обов’язкові поля', function () {
    Livewire::test('post.create')
        ->set('title', '')
        ->call('save')
        ->assertHasErrors(['title' => 'required']);
});

it('зберігає коректний допис', function () {
    Livewire::actingAs($user)
        ->test('post.create')
        ->set('title', 'Цілком розумний заголовок')
        ->set('body', str_repeat('Достатньо довгий текст допису. ', 3))
        ->call('save')
        ->assertHasNoErrors()
        ->assertDispatched('notify');
});

public function boot(): void
{
    Model::preventLazyLoading(! app()->isProduction());
}

php artisan make:livewire post.create              # однофайловий
php artisan make:livewire post.create --mfc        # багатофайловий
php artisan make:livewire post.create --test       # з тестом
php artisan livewire:publish --config
php artisan optimize:clear