Введение
Laravel Elixir предоставляет чистый и гибкий API для определения основных Gulp-задач вашего Laravel-приложения. Elixir поддерживает основные препроцессоры CSS и JavaScript, такие как Sass и Webpack. С помощью сцепки методов Elixir позволяет вам гибко определять свой файлопровод (asset pipeline). Например:
jselixir(function(mix) { mix.sass('app.scss') .webpack('app.js'); });
Если вы сомневались и путались, с чего начать работу с Gulp и компиляцией ресурсов, то вам точно понравится Laravel Elixir. Но вам необязательно использовать именно его при разработке своего приложения. Вы можете использовать любой другой инструмент для файлопровода, или вообще не использовать его.
Установка и настройка
Перед запуском Elixir необходимо убедиться, что на вашем компьютере установлен Node.js и NPM (для версии 5.3 и выше).
shnode -v npm -v
По умолчанию Laravel Homestead включает в себя всё необходимое. Однако, если вы не используете Vagrant, то вы можете легко установить свежие версии Node и NPM с помощью простых графических установщиков с их страницы загрузки.
После вам надо получить Gulp как глобальный NPM-пакет:
shnpm install --global gulp
добавлено в 5.2 ()
shnpm install --global gulp-cli
Если вы используете систему контроля версий, то можете выполнить команду shnpm shrinkwrap
, чтобы зафиксировать свои NPM-требования:
shnpm shrinkwrap
После выполнения этой команды, вы можете «закоммитить» npm-shrinkwrap.json в контроль версий.
Осталось только установить Laravel Elixir. В корневом каталоге установленного Laravel вы найдете файл package.json. Стандартный файл package.json содержит JavaScript-модули Elixir и Webpack. Это то же самое, что и файл composer.json, только он определяет зависимости Node, а не PHP. Вы можете установить перечисленные в нём зависимости выполнив:
shnpm install
Если вы разрабатываете в системе Windows или запускаете виртуальную машину с Windows, вам может потребоваться команда shnpm install
с ключом sh--no-bin-links
:
shnpm install --no-bin-links
Запуск Elixir
Elixir построен на основе Gulp, поэтому для запуска задач Elixir вам надо просто выполнить консольную команду shgulp
. А ключ sh--production
минимизирует ваши файлы CSS и JavaScript:
sh// Запустить все задачи... gulp // Запустить все задачи и минимизировать все файлы CSS и JavaScript... gulp --production
При выполнении этой команды вы увидите красиво оформленную таблицу с информацией о всех выполненных при этом операциях.
Отслеживание изменений ресурсов
Команда shgulp watch
после запуска продолжает выполняться в терминале и следит за всеми изменениями ваших ресурсов. Gulp автоматически перекомпилирует ваши ресурсы, если вы измените их, пока запущена команда shwatch
:
shgulp watch
Работа с таблицами стилей
Файл gulpfile.js в корневом каталоге вашего проекта содержит все ваши Elixir-задачи. Elixir-задачи могут быть сцеплены вместе для точного определения того, как должны быть скомпилированы ваши ресурсы.
Компилирование Less
Чтобы скомпилировать Less в CSS используется метод PHPless()
. Этот метод предполагает, что ваши файлы находятся в resources/assets/less. В этом примере задача по умолчанию поместит скомпилированную CSS в public/css/app.css:
jselixir(function(mix) { mix.less('app.less'); });
Также вы можете комбинировать несколько Less-файлов в один CSS-файл. Итоговая CSS будет помещена в public/css/app.css:
jselixir(function(mix) { mix.less([ 'app.less', 'controllers.less' ]); });
Указать другой путь для сохранения итоговых файлов можно вторым аргументом метода PHPless()
:
jselixir(function(mix) { mix.less('app.less', 'public/stylesheets'); }); // Указание конкретного имени выходного файла... elixir(function(mix) { mix.less('app.less', 'public/stylesheets/style.css'); });
Компилирование Sass
Метод PHPsass()
позволяет компилировать Sass в CSS. Предполагается, что ваши Sass-файлы хранятся в resources/assets/sass.
jselixir(function(mix) { mix.sass('app.scss'); });
добавлено в 5.0 ()
По умолчанию Elixir под капотом использует библиотеку LibSass для компиляции. В некоторых случаях это может оказаться выгодней, чем использование версии Ruby, которая работает медленнее, но зато более функциональна. Если у вас установлены и Ruby и Sass (shgem install sass
), вы можете включить Ruby-режим:
jselixir(function(mix) { mix.rubySass("app.sass"); });
добавлено в 5.3 ()
Рекомендуется использовать стандартные каталоги Laravel для ресурсов, но если вам необходима другой базовый каталог, вы можете указать путь к любому файлу начиная с ./. Тогда Elixir поймёт, что надо начать с корня проекта, а не использовать стандартный базовый каталог.
Например, чтобы скомпилировать файл из app/assets/sass/app.scss и разместить результат в public/css/app.css, вам надо сделать такой вызов метода PHPsass()
:
jselixir(function(mix) { mix.sass('./app/assets/sass/app.scss'); });
Компилирование Stylus
Для компилирования Stylus в CSS используется метод PHPstylus()
. Если ваши Stylus-файлы хранятся в resources/assets/stylus, вызовите метод вот так:
jselixir(function(mix) { mix.stylus('app.styl'); });
Эта сигнатура метода идентична и для PHPmix.less()
и для PHPmix.sass()
.
добавлено в 5.3 () 5.2 () 5.1 ()
Компилирование простых CSS
Если вы хотите просто скомбинировать некоторые простые таблицы стилей в один файл, используйте метод PHPstyles()
. Передаваемые в этот метод пути относительны к resources/assets/css, а итоговая CSS будет помещена в public/css/all.css:
jselixir(function(mix) { mix.styles([ 'normalize.css', 'main.css' ]); });
Вы также можете указать Elixir сохранить итоговый файл в другой каталог или файл, передав второй аргумент в метод PHPstyles()
:
jselixir(function(mix) { mix.styles([ 'normalize.css', 'main.css' ], 'public/assets/css/site.css'); });
Комбинирование стилей и сохранение по базовому пути
jselixir(function(mix) { mix.styles([ "normalize.css", "main.css" ], 'public/build/css/everything.css', 'public/css'); });
Третий аргумент методов PHPstyles()
и PHPscripts()
определяет относительный каталог для всех путей, передаваемых в методы.
Комбинирование всех стилей в каталоге
jselixir(function(mix) { mix.stylesIn("public/css"); });
Компилирование без карт кода
В Elixir карты кода (source maps) включены по умолчанию и обеспечивают более полную отладочную информацию для инструментов разработчика в вашем браузере при использовании скомпилированных ресурсов. Для каждого скомпилированного файла вы найдете соответствующий ему файл *.css.map или *.js.map в том же каталоге.
Чтобы отключить эту функцию, просто отключите настройку sourcemaps:
jselixir.config.sourcemaps = false; elixir(function(mix) { mix.sass('app.scss'); });
Работа со скриптами
Elixir предоставляет несколько функций для работы с JavaScript-файлами, например: компилирование ECMAScript 2015, сбор модулей, минификация и простая конкатенация простых JavaScript-файлов.
добавлено в 5.3 ()
При написании ES2015 с модулями у вас есть выбор между [https://webpack.github.ioWebpack] и Rollup. Если эти инструменты вам незнакомы, не беспокойтесь, Elixir сам выполнит всю сложную работу. По умолчанию gulpfile Laravel использует webpack для компилирования Javascript, но вы можете использовать любой другой сборщик модулей.
Компилирование Webpack
Для компилирования и сборки ECMAScript 2015 в простой JavaScript служит метод PHPwebpack()
. Эта функция принимает путь к файлу относительно каталога resources/assets/js и генерирует один собранный файл в каталоге public/js:
jselixir(function(mix) { mix.webpack('app.js'); });
Для выбора другого каталога для вывода или базового каталога просто укажите необходимые пути с точкой в начале. Затем вы можете указать пути относительно корня вашего приложения. Например, чтобы скомпилировать app/assets/js/app.js в public/dist/app.js:
jselixir(function(mix) { mix.webpack( './app/assets/js/app.js', './public/dist' ); });
Если вы хотите использовать функциональность Webpack по полной, Elixir прочитает любой файл webpack.config.js, находящийся в корне вашего проекта, и включит его настройки в процесс сборки.
Компилирование Rollup
Подобно Webpack, Rollup — это сборщик для ES2015 следующего поколения. Эта функция принимает массив файлов относительно каталога resources/assets/js и генерирует один файл в каталоге public/js:
jselixir(function(mix) { mix.rollup('app.js'); });
Как и с методом PHPwebpack()
вы можете настроить место для ввода и вывода файлов, передаваемых в метод PHProllup()
:
elixir(function(mix) {
mix.rollup(
'./resources/assets/js/app.js',
'./public/dist'
);
});
добавлено в 5.2 () 5.1 () 5.0 ()
Компилирование CoffeeScript
Для компилирования CoffeeScript в простой JavaScript служит метод PHPcoffee()
. Он принимает строку или массив CoffeeScript-файлов относительно пути resources/assets/coffee и генерирует единый файл public/js/app.js:
jselixir(function(mix) { mix.coffee(['app.coffee', 'controllers.coffee']); });
добавлено в 5.0 ()
добавлено в 5.2 () 5.1 () 5.0 ()
Browserify
В Elixir есть метод PHPbrowserify ()
, который обеспечивает вас всеми преимуществами запроса модулей в браузере и ECMAScript 6 и JSX (для версии 5.2 и выше).
Эта задача предполагает, что ваши скрипты хранятся в resources/assets/js, и сохранит итоговый файл в public/js/main.js:
jselixir(function(mix) { mix.browserify('main.js'); });
добавлено в 5.2 ()
добавлено в 5.2 () 5.1 () 5.0 ()
В Browserify уже включены трансформеры Partialify и Babelify, при необходимости вы можете установить и добавить другие:
shnpm install aliasify --save-dev
jselixir.config.js.browserify.transformers.push({ name: 'aliasify', options: {} }); elixir(function(mix) { mix.browserify('main.js'); });
Babel
Для компилирования ECMAScript 6 и 7 и JSX (для версии 5.2 и выше) в простой JavaScript служит метод PHPbabel()
. Он принимает массив или файлы относительно пути resources/assets/js, и генерирует единый файл public/js/all.js:
jselixir(function(mix) { mix.babel([ 'order.js', 'product.js', 'react-component.jsx' //для версии 5.2 и выше ]); });
Другое место для сохранения итогового файла можно указать вторым аргументом. Сигнатура и функциональность этого метода идентичны PHPmix.scripts()
, за исключением компилирования Babel.
Скрипты
Чтобы скомбинировать несколько JavaScript-файлов в один, используйте метод PHPscripts()
, который обеспечивает автоматические карты кода, конкатенацию и минификацию.
Метод PHPscripts()
работает с файлами по относительному пути resources/assets/js и сохраняет итоговый JavaScript в public/js/all.js:
jselixir(function(mix) { mix.scripts([ 'order.js', 'forum.js' ]); });
Если вам необходимо конкатенировать несколько наборов скриптов в разные файлы, вы можете сделать несколько вызовов метода PHPscripts()
. Имя итогового файла для каждой конкатенации определяется вторым аргументом метода:
jselixir(function(mix) { mix.scripts(['app.js', 'controllers.js'], 'public/js/app.js') .scripts(['forum.js', 'threads.js'], 'public/js/forum.js'); });
Если вам необходимо скомбинировать все скрипты в данной папке, используйте метод PHPscriptsIn()
. Итоговый JavaScript будет помещён в public/js/all.js:
jselixir(function(mix) { mix.scriptsIn('public/js/some/directory'); });
Если вы собираетесь конкатенировать несколько предварительно минифицированных библиотек от производителей, таких как jQuery, попробуйте вместо этого использовать PHPmix.combine()
. При этом файлы будут скомбинированы без выполнения шагов по созданию карт кода и минификации. В результате значительно уменьшится время компилирования.
Копирование файлов и папок
Метод PHPcopy()
используется для копирования файлов и папок в новое место. Все операции относительны корневой папки проекта:
jselixir(function(mix) { mix.copy('vendor/foo/bar.css', 'public/css/bar.css');
Версии файлов /очистка кэша
Многие разработчики добавляют в имена ресурсов время создания или уникальный токен, чтобы браузер загружал свежие ресурсы вместо обработки устаревшего кода. В Elixir для этого служит метод PHPversion()
.
Метод PHPversion()
принимает имя файла относительно папки public и добавляет к нему уникальный хеш для возможности очистки кэша. Например, сгенерированное имя файла будет выглядеть приблизительно так — all-16d570a7.css:
jselixir(function(mix) { mix.version('css/all.css'); });
Сгенерировав версию файла, вы можете использовать глобальную функцию Laravel PHPelixir()
в ваших представлениях для загрузки соответствующих хешированных ресурсов. Функция PHPelixir()
автоматически определит текущее имя хешированного файла:
xml<link rel="stylesheet" href="{{ elixir('css/all.css') }}">
Вы также можете передать массив в метод PHPversion()
, чтобы присвоить версию нескольким файлам:
jselixir(function(mix) { mix.version(['css/all.css', 'js/app.js']); });
Когда файлам присвоена версия, вы можете использовать функцию PHPelixir()
для генерации ссылок к нужным хешированным файлам. Помните, вам надо просто передать в эту функцию имя нехешированного файла. Она использует это имя для определения текущей хешированной версии файла:
xml<link rel="stylesheet" href="{{ elixir('css/all.css') }}"> <script src="{{ elixir('js/app.js') }}"></script>
добавлено в 5.3 () 5.2 () 5.1 ()
BrowserSync
BrowserSync автоматически производит обновление в браузере при изменениях в ваших ресурсах. Метод PHPbrowserSync()
принимает JavaScript-объект с атрибутом proxy, содержащим локальный URL вашего приложения. Теперь, когда вы запустите shgulp watch
, вы сможете обращаться к своему приложению через 3000 порт (http://project.dev:3000) и наслаждаться браузерной синхронизацией:
jselixir(function(mix) { mix.browserSync({ proxy: 'project.dev' }); });
добавлено в 5.0 ()
Gulp
Теперь, когда вы указали, какие задачи должен выполнять Elixir, вы должны вызвать Gulp из командной строки.
Выполнение всех зарегистрированных задач разом
shgulp
Отслеживание изменений ресурсов
shgulp watch
Только скомпилированные скрипты
shgulp scripts
shgulp styles
Отслеживание изменений тестов и PHP-классов
shgulp tdd
Запуск всех задач будет происходить для среды разработки, и минимизация выполняться не будет. Для продакшна используйте shgulp --production
.
добавлено в 5.2 () 5.1 () 5.0 ()
Вызов существующих Gulp-задач
Для вызова существующей Gulp-задачи используйте метод PHPtask()
. Как пример, представьте, что у вас есть Gulp-задача, которая просто выводит небольшой текст при вызове.
jsgulp.task('speak', function() { var message = 'Tea...Earl Grey...Hot'; gulp.src('').pipe(shell('say ' + message)); });
Если вы хотите вызвать эту задачу из Elixir, используйте метод PHPmix.task()
и передайте имя задачи единственным аргументом метода:
jselixir(function(mix) { mix.task('speak'); });
Если вам необходимо зарегистрировать наблюдателя, чтобы запускать ваши задачи каждый раз, когда изменяется один или несколько файлов, вы можете передать регулярное выражение в качестве второго аргумента метода PHPtask()
:
jselixir(function(mix) { mix.task('speak', 'app/**/*.php'); });
Создание расширений Elixir
Для ещё большей гибкости вы можете создать полноценные расширения Elixir. Расширения Elixir позволяют передавать аргументы в ваши задачи. Например, можно написать такое расширение:
js// File: elixir-extensions.js var gulp = require('gulp'); var shell = require('gulp-shell'); var Elixir = require('laravel-elixir'); var Task = Elixir.Task; Elixir.extend('speak', function(message) { new Task('speak', function() { return gulp.src('').pipe(shell('say ' + message)); }); }); // mix.speak('Hello World');
Вот и всё! Обратите внимание на то, что ваша Gulp-логика должна быть в функции, передаваемой вторым аргументом конструктору PHPTask()
. Вы можете либо расположить это в начале вашего Gulpfile, либо вынести в отдельный файл задач. Например, если вы разместите расширения в elixir-extensions.js, то можете затребовать этот файл из основного (t)Gulpfile%% вот так:
js// File: Gulpfile.js var elixir = require('laravel-elixir'); require('./elixir-extensions') elixir(function(mix) { mix.speak('Tea, Earl Grey, Hot'); });
Если вы хотите перезапускать свою задачу во время выполнения shgulp watch
, можете зарегистрировать наблюдателя:
jsnew Task('speak', function() { return gulp.src('').pipe(shell('say ' + message)); }) .watch('./app/**');
Комментарии (3)
Документация будто пишется для тех у кого Laravel уже 10 фреймворк. Установил все через npm, дальше что? Какой Elixir? его нет в packages — есть некий laravel-mix? в чем смысл статьи? где описание полного gulpfile? почему его не генерирует фреймворк?
Этим страдают все документации. Писать хорошую документацию тяжело. Elixir описан в package.json
Если у вас его нет, возможно у вас Laravel не 5+ версии. Package.json в корне проекта содержит этот и другие пакеты необходимые для использования elixir. Но по сути, вам не обязательно использовать его, можно пользоваться чистым Gulp. Смысл этого блока == шпаргалка для «знатоков», которые знакомы с gulp.
Если вы установили все, то вам достаточно запустить команду gulp — после этого у вас появится собранный Vue компонент с CSS, который идет в комплекте.
И если все прошло успешно (файлы js и css появились в public) дописываете файл галпа под свои нужды.
Надо написать, что Elixir для 5.3. В версиях выше Laravel Mix(и мб статью запилить или хотя бы ссылку на оригинал).