Может войдёшь?
Черновики Написать статью Профиль

Elixir

перевод документация 5.х

  1. 1. Введение
  2. 2. Установка и настройка
  3. 3. Запуск Elixir
  4. 4. Работа с таблицами стилей
    1. 4.1. Компилирование Less
    2. 4.2. Компилирование Sass
    3. 4.3. Компилирование Stylus
    4. 4.4. Компилирование простых CSS
    5. 4.5. Компилирование без карт кода
  5. 5. Работа со скриптами
    1. 5.1. Компилирование Webpack
    2. 5.2. Компилирование Rollup
    3. 5.3. Компилирование CoffeeScript
    4. 5.4. Browserify
    5. 5.5. Babel
    6. 5.6. Скрипты
  6. 6. Копирование файлов и папок
  7. 7. Версии файлов /очистка кэша
  8. 8. BrowserSync
  9. 9. Gulp
  10. 10. Вызов существующих Gulp-задач
  11. 11. Создание расширений Elixir
Этот перевод актуален для англоязычной документации на (ветка 5.3) , (ветка 5.2) , (ветка 5.1) и (ветка 5.0). Опечатка? Выдели и нажми Ctrl+Enter.

Введение

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. Но вам необязательно использовать именно его при разработке своего приложения. Вы можете использовать любой другой инструмент для файлопровода, или вообще не использовать его.

Установка и настройка

Установка Node

Перед запуском Elixir необходимо убедиться, что на вашем компьютере установлен Node.js и NPM (для версии 5.3 и выше).

shnode -v
npm -v

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

Gulp

После вам надо получить Gulp как глобальный NPM-пакет:

shnpm install --global gulp
+ 5.2

добавлено в 5.2 ()

shnpm install --global gulp-cli

Если вы используете систему контроля версий, то можете выполнить команду shnpm shrinkwrap, чтобы зафиксировать свои NPM-требования:

shnpm shrinkwrap

После выполнения этой команды, вы можете «закоммитить» npm-shrinkwrap.json в контроль версий.

Laravel Elixir

Осталось только установить 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

добавлено в 5.0 ()

По умолчанию Elixir под капотом использует библиотеку LibSass для компиляции. В некоторых случаях это может оказаться выгодней, чем использование версии Ruby, которая работает медленнее, но зато более функциональна. Если у вас установлены и Ruby и Sass (shgem install sass), вы можете включить Ruby-режим:

jselixir(function(mix) {
  mix.rubySass("app.sass");
});
+ 5.3 5.2 5.1

добавлено в 5.3 () 5.2 () 5.1 ()

Как и в случае с методом PHPless(), вы можете компилировать несколько Sass-файлов в один CSS-файл, и задать папку для сохранения итоговой CSS:

jselixir(function(mix) {
  mix.sass([
    'app.scss',
    'controllers.scss'
  ], 'public/assets/css');
});
+ 5.3

добавлено в 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

добавлено в 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');
});
+ 5.2 5.1

добавлено в 5.2 () 5.1 ()

Комбинирование стилей и сохранение по базовому пути

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

добавлено в 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():

PHP
elixir(function(mix) {
  
mix.rollup(
    
'./resources/assets/js/app.js',
    
'./public/dist'
  
);
});
+ 5.2 5.1 5.0

добавлено в 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.0 ()

Компилирование всех Less and CoffeeScript

jselixir(function(mix) {
  mix.less()
     .coffee();
});

Выполнение тестов PHPUnit

jselixir(function(mix) {
  mix.phpUnit();
});

Выполнение тестов PHPSpec

jselixir(function(mix) {
  mix.phpSpec();
});
+ 5.2 5.1 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 ()

При необходимости вы можете передать другое место для вывода в качестве второго аргумента

js// Задание конкретного имени для вывода файла...
elixir(function(mix) {
  mix.browserify('main.js', 'public/javascripts/main.js');
});
+ 5.2 5.1 5.0

добавлено в 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

добавлено в 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

добавлено в 5.0 ()

Gulp

Теперь, когда вы указали, какие задачи должен выполнять Elixir, вы должны вызвать Gulp из командной строки.

Выполнение всех зарегистрированных задач разом

shgulp

Отслеживание изменений ресурсов

shgulp watch

Только скомпилированные скрипты

shgulp scripts

Только скомпилированные стили

shgulp styles

Отслеживание изменений тестов и PHP-классов

shgulp tdd

Запуск всех задач будет происходить для среды разработки, и минимизация выполняться не будет. Для продакшна используйте shgulp --production.

+ 5.2 5.1 5.0

добавлено в 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)

Vano

Документация будто пишется для тех у кого Laravel уже 10 фреймворк. Установил все через npm, дальше что? Какой Elixir? его нет в packages — есть некий laravel-mix? в чем смысл статьи? где описание полного gulpfile? почему его не генерирует фреймворк?

RonBarhash

Этим страдают все документации. Писать хорошую документацию тяжело. Elixir описан в package.json

Если у вас его нет, возможно у вас Laravel не 5+ версии. Package.json в корне проекта содержит этот и другие пакеты необходимые для использования elixir. Но по сути, вам не обязательно использовать его, можно пользоваться чистым Gulp. Смысл этого блока == шпаргалка для «знатоков», которые знакомы с gulp.

Если вы установили все, то вам достаточно запустить команду gulp — после этого у вас появится собранный Vue компонент с CSS, который идет в комплекте.

И если все прошло успешно (файлы js и css появились в public) дописываете файл галпа под свои нужды.

Kirir

Надо написать, что Elixir для 5.3. В версиях выше Laravel Mix(и мб статью запилить или хотя бы ссылку на оригинал).

Написать комментарий

Разметка: ? ?

Авторизуйся, чтобы прокомментировать.