Перейти к содержанию

Установка⚓︎

Livewire — это пакет для Laravel, поэтому перед его установкой и использованием у вас уже должно быть готовое работающее приложение.

Если вы только начинаете проект и вам нужна помощь с созданием нового приложения Laravel, обратитесь к официальной документации по установке.

Предварительные требования⚓︎

Перед установкой Livewire убедитесь, что у вас уже имеются:

  • Laravel версии 10 или выше
  • PHP версии 8.1 или выше

Установка Livewire⚓︎

Чтобы установить Livewire, откройте терминал, перейдите в директорию вашего приложения Laravel и выполните следующую команду:

composer require livewire/livewire

Вот и всё! Livewire использует механизм автоматического обнаружения пакетов Laravel, поэтому дополнительная настройка не требуется.

Готовы создать свой первый компонент? Перейдите к Руководству по быстрому старту, чтобы создать свой первый компонент Livewire за считанные минуты.

Создание файла макета⚓︎

При использовании компонентов Livewire в качестве полноценных страниц вам понадобится файл макета. Вы можете сгенерировать его с помощью команды Livewire:

php artisan livewire:layout

Это создаст файл макета по пути resources/views/layouts/app.blade.php со следующим содержимым:

<!DOCTYPE html>
<html lang="{{ str_replace('_', '-', app()->getLocale()) }}">
    <head>
        <meta charset="utf-8">
        <meta name="viewport" content="width=device-width, initial-scale=1.0">

        <title>{{ $title ?? config('app.name') }}</title>

        @vite(['resources/css/app.css', 'resources/js/app.js'])

        @livewireStyles
    </head>
    <body>
        {{ $slot }}

        @livewireScripts
    </body>
</html>

Директивы @livewireStyles и @livewireScripts подключают необходимые ресурсы JavaScript и CSS для работы Livewire. Livewire включает Alpine.js в свой JavaScript-бандл, поэтому они загружаются вместе.

Внедрение ресурсов происходит автоматически

Даже без этих директив Livewire автоматически внедрит свои ресурсы на страницы, содержащие компоненты Livewire. Однако использование директив дает вам явный контроль над тем, где размещаются ресурсы, что может быть полезно для оптимизации производительности или совместимости с другими пакетами.

Публикация файла конфигурации⚓︎

Livewire придерживается принципа zero-config (нулевая конфигурация), то есть вы можете сразу начать его использовать, просто следуя соглашениям, без всякой дополнительной настройки. При этом, если потребуется, вы всегда можете опубликовать и отредактировать файл конфигурации Livewire:

php artisan livewire:config

Это создаст новый файл livewire.php в директории config вашего приложения Laravel, где вы сможете настроить различные параметры Livewire.

Расширенная конфигурация⚓︎

Следующие разделы охватывают сложные сценарии, которые не потребуются большинству приложений. Настраивайте эти параметры только в том случае, если у вас есть специфические требования.

Ручная сборка Livewire и Alpine⚓︎

Когда это нужно: Если вы хотите использовать плагины Alpine.js или вам нужен детальный контроль над тем, когда инициализируются Alpine и Livewire.

По умолчанию Livewire автоматически загружает Alpine.js вместе со своим JavaScript-бандлом. Однако, если вам нужно зарегистрировать плагины Alpine или настроить порядок инициализации, вы можете вручную собрать Livewire и Alpine, используя ваш инструмент сборки JavaScript.

Сначала добавьте директиву @livewireScriptConfig в файл вашего макета:

<!DOCTYPE html>
<html lang="{{ str_replace('_', '-', app()->getLocale()) }}">
    <head>
        <meta charset="utf-8">
        <meta name="viewport" content="width=device-width, initial-scale=1.0">

        <title>{{ $title ?? config('app.name') }}</title>

        @vite(['resources/css/app.css', 'resources/js/app.js'])

        @livewireStyles
    </head>
    <body>
        {{ $slot }}

        @livewireScriptConfig
    </body>
</html>

Директива @livewireScriptConfig внедряет конфигурацию и глобальные переменные среды выполнения, необходимые Livewire, но без фактического JavaScript-кода Livewire и Alpine (так как вы собираете их самостоятельно). При ручной сборке замените @livewireScripts на @livewireScriptConfig.

Затем импортируйте и запустите Livewire и Alpine в вашем файле resources/js/app.js:

import { Livewire, Alpine } from '../../vendor/livewire/livewire/dist/livewire.esm';
import Clipboard from '@ryangjchandler/alpine-clipboard'

Alpine.plugin(Clipboard)

Livewire.start()

Пересобирайте ресурсы после обновлений Livewire

При ручной сборке не забывайте пересобирать ваши JavaScript-ресурсы (npm run build) каждый раз, когда вы обновляете Livewire через Composer.

Настройка эндпойнта обновлений Livewire⚓︎

Когда это нужно: Если ваше приложение построено по принципу мультитенантности (multi-tenancy) — то есть один экземпляр приложения обслуживает сразу много разных клиентов/организаций/аккаунтов (тенантов), и каждый тенант имеет свою изолированную область — часто для этого используют префиксы в URL.

Примеры таких префиксов:

  • для разных языков: /en/, /fr/, /ru/
  • для разных тенантов: /company-a/, /acme-corp/, /client-123/

В таких случаях адрес, по которому Livewire отправляет свои внутренние запросы на обновление, по умолчанию не учитывает эти префиксы. Из-за этого запросы могут попадать не туда или вообще не доходить.

Поэтому вам потребуется явно указать Livewire, какой именно URL использовать для его внутренних запросов, чтобы он соответствовал структуре ваших маршрутов.

По умолчанию Livewire отправляет обновления компонентов на эндпойнт с хешем, например /livewire-{hash}/update, где {hash} вычисляется на основе APP_KEY вашего приложения. Чтобы настроить это, зарегистрируйте свой собственный маршрут в сервис-провайдере (обычно App\Providers\AppServiceProvider):

<?php

use Livewire\Livewire;

class AppServiceProvider extends ServiceProvider
{
    public function boot()
    {
        Livewire::setUpdateRoute(function ($handle, $path) {
            return Route::post('/custom' . $path, $handle);
        });
    }
}

Параметр $path содержит путь с хешем (например, /livewire-{hash}/update), сохраняя уникальность эндпойнта для конкретной установки.

Вы также можете добавить мидлвар к маршруту обновлений:

<?php

Livewire::setUpdateRoute(function ($handle, $path) {
    return Route::post('/custom' . $path, $handle)
        ->middleware(['web', 'auth']);
});

Настройка URL-адреса JavaScript-ресурса⚓︎

Когда это нужно: Если ваше приложение использует префиксы маршрутов для локализации или мультитенантности, вам может потребоваться настроить место, откуда Livewire отдает свой JavaScript, чтобы это соответствовало вашей структуре маршрутизации.

По умолчанию Livewire отдает свой JavaScript с эндпойнта, содержащего хеш, например /livewire-{hash}/livewire.js, где {hash} вычисляется на основе APP_KEY вашего приложения. Этот уникальный для каждой установки путь затрудняет обнаружение приложений Livewire автоматическими сканерами.

Чтобы настроить это, зарегистрируйте свой собственный маршрут в сервис-провайдере:

<?php

use Livewire\Livewire;

class AppServiceProvider extends ServiceProvider
{
    public function boot()
    {
        Livewire::setScriptRoute(function ($handle, $path) {
            return Route::get('/custom' . $path, $handle);
        });
    }
}

Параметр $path содержит путь с хешем (например, /livewire-{hash}/livewire.js), сохраняя уникальность эндпойнта для конкретной установки.

Публикация ресурсов Livewire в публичную директорию⚓︎

Когда это нужно: Если вы хотите отдавать JavaScript Livewire напрямую через ваш веб-сервер (например, для распространения через CDN или использования специфических стратегий кэширования), а не через маршрутизацию Laravel.

Вы можете опубликовать JavaScript-ресурсы Livewire в директорию public:

php artisan livewire:publish --assets

Чтобы ресурсы оставались актуальными при обновлении Livewire, добавьте это в ваш composer.json:

{
    "scripts": {
        "post-update-cmd": [
            "@php artisan vendor:publish --tag=livewire:assets --ansi --force"
        ]
    }
}

Большинству приложений это не нужно

Публикация ресурсов требуется редко. Делайте это только в том случае, если у вас есть специфическое архитектурное требование, которое не позволяет Laravel отдавать ресурсы динамически.

Отключение автоматического внедрения ресурсов⚓︎

Когда это нужно: Если вы хотите полностью контролировать, когда и как загружаются ресурсы Livewire, вы можете отключить автоматическое внедрение.

Обновите параметр конфигурации inject_assets в вашем файле config/livewire.php:

'inject_assets' => false,

При отключении этой опции вы должны вручную добавить @livewireStyles и @livewireScripts в ваши макеты, иначе Livewire не будет работать.

В качестве альтернативы, вы можете принудительно включить внедрение ресурсов на определённых страницах:

\Livewire\Livewire::forceAssetInjection();

Вызывайте этот метод в маршруте или контроллере, где вы хотите гарантировать внедрение ресурсов.

Решение проблем⚓︎

JavaScript Livewire не загружается (ошибка 404)⚓︎

Симптом: JavaScript-файл Livewire возвращает ошибку 404 или функции Livewire не работают.

Livewire отдает свой JavaScript с эндпойнта, содержащего хеш, например /livewire-{hash}/livewire.js, где {hash} вычисляется на основе APP_KEY вашего приложения. Этот уникальный путь различается для каждой установки.

Частые причины:

Конфигурация Nginx блокирует маршрут:

Если вы используете Nginx с пользовательской конфигурацией, она может блокировать динамические маршруты Livewire в Laravel. Вы можете либо:

  • Настроить Nginx так, чтобы запросы, соответствующие /livewire-*/, передавались в Laravel (например, location ~ ^/livewire-[a-f0-9]+/ { try_files $uri $uri/ /index.php?$query_string; })
  • Собрать Livewire вручную, чтобы избежать отдачи через Laravel
  • Опубликовать ресурсы Livewire, чтобы отдавать их напрямую с вашего веб-сервера

Кэширование маршрутов:

Если вы выполнили php artisan route:cache, Laravel может не распознать маршруты Livewire. Очистите кэш:

php artisan route:clear

Отсутствует @livewireScripts:

Если вы отключили автоматическое внедрение ресурсов, убедитесь, что @livewireScripts присутствует в вашем файле макета перед закрывающим тегом </body>.

Alpine.js недоступен на страницах без компонентов Livewire⚓︎

Симптом: Вы хотите использовать Alpine.js на странице, где нет ни одного компонента Livewire.

Решение: Поскольку Alpine поставляется вместе с Livewire, вам необходимо добавить @livewireScripts даже на страницы без компонентов Livewire:

<!DOCTYPE html>
<html>
    <head>
        @livewireStyles
    </head>
    <body>
        <!-- Здесь нет компонентов Livewire, но нам нужен Alpine -->
        <div x-data="{ open: false }">
            <button @click="open = !open">Переключить</button>
        </div>

        @livewireScripts
    </body>
</html>

В качестве альтернативы, соберите Livewire и Alpine вручную и импортируйте Alpine в ваш JavaScript.

Компоненты не обновляются или ошибки в консоли браузера⚓︎

Проверьте следующее:

  • Убедитесь, что @livewireStyles находится внутри тега <head> вашего макета
  • Убедитесь, что @livewireScripts находится перед закрывающим тегом </body> в вашем макете
  • Проверьте консоль разработчика в браузере на наличие ошибок JavaScript
  • Убедитесь, что вы используете поддерживаемые версии PHP (8.1+) и Laravel (10+)
  • Очистите кэш приложения: php artisan cache:clear

Если проблемы сохраняются, обратитесь к документации по решению проблем для получения более подробных инструкций по отладке.