Laravel 6. Документация php фреймворка Laravel.

Введение

Ларавел Микс обеспечивает API для определения шагов построения Webpack для вашего приложения с использованием некоторых общих CSS и JavaScript препроцессоров. Используя простую цепочку методов, вы можете гибко указать и настроить файлы для сборки:

mix.js('resources/js/app.js', 'public/js')
   .sass('resources/sass/app.scss', 'public/css');

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

Установка

Установка Node

До запуска Ларавел Микс, вы должны убедиться в том, что Node.js и NPM установлены на вашей машине.

node -v
npm -v

По умолчанию, Laravel Homestead уже включает всё, что необходимо. Однако, если вы не используете Vagrant, вы также можете установить последнюю версию Node и NPM используя установщик со страницы загрузки.

Laravel Mix

На последний шаге нам нужно установиь Laravel Mix. Внутри новой установки Laravel, вы найдете файл package.json в корне проекта. По умолчанию, файл включает всё что необходимо для старта. Его можно воспринимать как файл composer.json, только это не зависимости PHP, а Node. Вы можете установить зависимости Node выпонив команду:

npm install

Запуск ларавел Mix

Микс это слой настроек для Webpack, поэтому для запуска заданий Ларавел Микс вам необходимо выполнить один из скриптов NPM, который включён в базовый файл package.json:

// Run all Mix tasks...
npm run dev

// Run all Mix tasks and minify output...
npm run production

Ожидание изменений для файлов

Команда npm run watch будет отслеживать все измениня в файлах. Webpack автоматически проведёт рекомпиляцию при наличии изменений:

npm run watch

Может так случиться, что для определённого окружения, Webpack не проводит обновления при изменении файла. Если это ваш случай, попробуйте использовать команду watch-poll:

npm run watch-poll

Работа с CSS

Файл webpack.mix.js — это стартовая точка для компиляции ваших конечного файла. Этот файл можно воспринимать как обёртка с легкой конфигураций для Webpack. Задачи микса можно объединить вместе, чтобы определить как точно должна проходить компилация.

Less

Метод less может быть использован для компиляции Less в CSS. Давйте проведём компиляцию файла app.less в public/css/app.css.

mix.less('resources/less/app.less', 'public/css');

Несколько вызовов метода less можно использовать для компиляции нескольких файлов:

mix.less('resources/less/app.less', 'public/css')
   .less('resources/less/admin.less', 'public/css');

Если вы хотите дать скомпилированному файлу название, вы можете передать полное имя файла как второй аргумент в метод less:

mix.less('resources/less/app.less', 'public/stylesheets/styles.css');

Если вам нужно переопределить опции плагина, тогда вы можете передать объект в качестве третьего аргумента в mix.less():

mix.less('resources/less/app.less', 'public/css', {
    strictMath: true
});

Sass

Метод sass позволяет вам компилировать Sass в CSS. Этот метод вы можете использовать таким образом:

mix.sass('resources/sass/app.scss', 'public/css');

Опять же, как и в случае с методом less, вы можете скомпилировать несколько файлов Sass в CSS файлы и даже настроить папку вывода:

mix.sass('resources/sass/app.sass', 'public/css')
   .sass('resources/sass/admin.sass', 'public/css/admin');

Характеристики плагина можете передать третьи аргументом:

mix.sass('resources/sass/app.sass', 'public/css', {
    precision: 5
});

Stylus

Как и в случае с Less и Sass, метод stylus позволяет вам скомпилировать Stylus в CSS:

mix.stylus('resources/stylus/app.styl', 'public/css');

Вы можете также установить дополнительный плагин Stylus, такой как Rupture. Во-первых, установите плагин через NPM (npm install rupture) и после добавьте в вызов в mix.stylus():

mix.stylus('resources/stylus/app.styl', 'public/css', {
    use: [
        require('rupture')()
    ]
});

PostCSS

PostCSS — это мощный инструмент для трансформации CSS, которая включена в Ларавел Микс из коробки. По умолчанию, микс использует популярный плагин Autoprefixer для автоматического применения всех необходимых префиксов CSS3. Мы можете добавить любой дополнитлеьный плагин, который подходят вашему приложению. Во-первых, установите нужный плагин через NPM и после обратитесь к нему в файле webpack.mix.js:

mix.sass('resources/sass/app.scss', 'public/css')
   .options({
        postCss: [
            require('postcss-css-variables')()
        ]
   });

Простые CSS

Если вы просто хотите соединить несколько файлов CSS в один файл, тогда вам следует использовать метод styles.

mix.styles([
    'public/css/vendor/normalize.css',
    'public/css/vendor/videojs.css'
], 'public/css/all.css');

Обработка URL

В силу того, что Laravel Mix это надстройка над Webpack, важно понять некоторые моменты с ним связанные. Для компилации CSS, Webpack перепишет и оптимизирует любые url() обращения внутри ваших стилей. Это может показаться странным, но это невероятно мощная и важная часть функционала. Давайте представим, что мы хотим скомпилировать Sass, который включает в себя относительный путь к изображению:

.example {
    background: url('../images/example.png');
}

Абсолютные пути для данного url() будут исключены из переписи. Например, url('/images/thing.png') или url('http://example.com/images/thing.png') модифицированы не будут.

По умлчанию, Laravel Mix и Webpack найдут example.png, скопируют файл в вашу папку public/images, после чего перепишут url() внутри сгенерированного файла стилей. В итоге получим следующее:

.example {
    background: url(/images/example.png?d41d8cd98f00b204e9800998ecf8427e);
}

Возможно, что вы уже настроили структуру проекта нужным вам образом. И не смотря на всю полезность функции, вы бы хотели её отлючить. Для этого необходимо в методе url() указать следующиую опцию:

mix.sass('resources/app/app.scss', 'public/css')
   .options({
      processCssUrls: false
   });

С этим дополнением к вашему файлу webpack.mix.js, Микс больше не будет искать пути, или копировать файлы в папку. Другими словами, скомпилированный CSS не будет отличаться от оригинала:

.example {
    background: url("../images/thing.png");
}

Исходные карты

Исходные карты отключены по умолчанию, но можно активировать путём вызова метода mix.sourceMaps() в файле webpack.mix.js. Использование карты даёт дополнитлельную отладочную инфомрацию в инструменты разработчика браузера при компиляции.

mix.js('resources/js/app.js', 'public/js')
   .sourceMaps();

Стили карт

Webpack предоставляет набор стилей. По умолчанию, значение стиля установлено как eval-source-map, который характеризуется быстрым временем сборки. Если вы хотите поменять значение, для этого нужно исопльзовать метод sourceMaps:

let productionSourceMaps = false;

mix.js('resources/js/app.js', 'public/js')
   .sourceMaps(productionSourceMaps, 'source-map');

Работа с JavaScript

Для работы с файлами JavaScript Микс предоставляет возможности, такими как компиляция ECMAScript 2015, модулирование, минификация и соединение JavaScript файлов. И всё это работает без сучка и задоринки, и без дополнительной настройки конфигурации:

mix.js('resources/js/app.js', 'public/js');

Одной простой строкой кода, вы можете получить следующие преимущества:

ES2015 syntax.
Модули
Компиляция файлов .vue
Минификация для окружения на сервере

Поставщик расширений

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

Если вы намереваетесь делать обновления вашего приложения часто, вам стоит рассмотреть вопрос объединения всех библиотек поставщика в один независимый файл. В этом случае, изменения в коде приложения не будет влиять на кэширование файла vendor.js. Метод extract поможет справитсья с этим вопросом:

mix.js('resources/js/app.js', 'public/js')
   .extract(['vue'])

Метод extract принимает массив библиотек или модулей, которые вы бы хотели записать в файл vendor.js. Используя приведенный выше фрагмент кода в качестве примера, Mix создаст следующие файлы:

public/js/manifest.js: Время выполнения манифеста Webpack
public/js/vendor.js: Ваши библиотеки поставщика
public/js/app.js: Код приложения

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

<script src="/js/manifest.js"></script>
<script src="/js/vendor.js"></script>
<script src="/js/app.js"></script>

React

Mix может автоматически устанавливать плагины Babel необходимые React. Для начала, замените ваш вызов mix.js() на mix.react():

mix.react('resources/js/app.jsx', 'public/js');

За кулисами, Mix будет загружать и включать соответсвующие babel-preset-react Babel плагины.

Vanilla JS

Аналогично как и объединение стилей командой mix.styles(), вы можете также объединить и минифицировать любое количество файлов JavaScript с методом scripts():

mix.scripts([
    'public/js/admin.js',
    'public/js/dashboard.js'
], 'public/js/all.js');

Эта опция особенно полезна для старых проектов, где не нужна компиляция Webpack для код JavaScript.

Небольшая модификация mix.scripts() это mix.babel(), который по методологии идентичен scripts; Однако, присоединённые файлы получать компиляцию Babel, который переведёт любой код на Vanilla JavaScript понятный для всех браузеров.

Пользовательская конфигурация Webpack

За кулисами, Ларавел Микс ссылается на предварительно настроенный файл webpack.config.js для получения максимальной скорости. Можете так случиться, что вам потребуется вручную модифицировать этот файл. У вас может быть специальный загрузчик или плагин, на который нужно ссылаться, или вы предпочитаете использовать Stylus вместо Sass. Так или иначе, у вас есть 2 варианта:

Соединение пользовательской конфигурации;
Пользовательские файлы конфигурации;

Соединение пользовательской конфигурации

Микс предоставляет полезный метод webpackConfig, который позволяет соединить любое краткое переопределение конфигурации. Это отличный выбор в силу того, что вам не нужно копировать и поддерживать копию файла webpack.config.js. Метод webpackConfig принимает объект, который должен содержать любую конфигурацию Webpack, которую вы хотите применить.

mix.webpackConfig({
    resolve: {
        modules: [
            path.resolve(__dirname, 'vendor/laravel/spark/resources/assets/js')
        ]
    }
});

Пользовательские файлы конфигурации;

Если вы хотите полностью настроит вашу конфигурацию Webpack, тогда скопируйте файл node_modules/laravel-mix/setup/webpack.config.js в корневую директорию проекта. После этого, приведите все --config ссылки в вашем файле package.json в только что скопированный файл конфигурации. Стоит заметить, что если вы выбрали такой подход, тогда любые последующие измения webpack.config.js должны быть внесены вручную в ваш файл настроек.

Копирование файлов и директории

Метод copy можно использовать чтобы скопировать файлы и папки в новую локацию. Это может быть полезным, когда конкретные файлы или папки из директории node_modules необходимо переместить в папку public.

mix.copy('node_modules/foo/bar.css', 'public/css/bar.css');

При копировании папок, метод copy уберёт структуру. Чтобы сохранить структуру в скопированной папке как в оригинальной, вам необходимо использовать метод copyDirectory:

mix.copyDirectory('resources/img', 'public/img');

Управление версиями / кэширование

Многие разработчики добавляют суффикс для скомпилированного файла или уникальный токен, чтобы заставить браузер загрузать новую версию файла вместо работы с устаревшей копией кода. Микс решает эту задачу для вас через метод version.

Метод version автоматически добавит уникальный хэш к имени во все скомпилированные файлы, для более удобного управления кэшем:

mix.js('resources/js/app.js', 'public/js')
   .version();

После генерации файла с версией, вы не будете знать какое конкретно имя у файла. Поэтому, вы должны использовать глобальную функцию Laravel mix внутри вашего views, чтобы загрузить соответствующий хэшированный актив. Функция mix автоматически определит текущее имя хэшированного файла:

<script src=" { { mix('/js/app.js') }}"></script>

В силу того, что файлы с версиями не нужны во время разработки, вы можете научить процесс присвоения версия работать только после команды npm run production:

mix.js('resources/js/app.js', 'public/js');

if (mix.inProduction()) {
    mix.version();
}

Синхронизация браузера с перезагрузкой

BrowserSync может автоматически отслеживать изменения в файлах и внедрять изменения в браузер без неоходимости ручной перезагрузки. Вы можете включить поддержку путём обращения к методу mix.browserSync():

mix.browserSync('my-domain.test');

// Or...

// https://browsersync.io/docs/options
mix.browserSync({
    proxy: 'my-domain.test'
});

Вы можете передать и строку и объект в этот метод. Запустите сервер разработки Webpack используя команду npm run watch. Теперь когда вы будуте модифицировать скрипт или файл PHP, браузер автоматически перезагрузит страницу и применит ваши изменения.

Переменные среды

Вы можете внедрить переменные среды в Микс путём добавления префикса MIX_ к пункту в файле .env:

MIX_SENTRY_DSN_PUBLIC=http://example.com

После того, как переменная была определена в вашем файле .env, вы можете получить доступ через объект process.env. Если значение изменилось в процессе выполнения задания watch, вам необходимо перезапустить задание:

process.env.MIX_SENTRY_DSN_PUBLIC

Уведомления

Когда это возможно, Микс автоматичечки показывает уведомления в операционной системе для каждого пакета. Это даёт вам отличную обратную связь на предмет того, была ли компиляция успешной или нет. Но возможно, вы бы хотели отменить показ уведомлений, например при запуске Микса на рабочем сервере. Уведомления можно отключить через метод disableNotifications.

mix.disableNotifications();