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

Elixir

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

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

Введение

Laravel Elixir предоставляет чистый и гибкий API для определения основных Gulp-задач вашего Laravel-приложения. Elixir поддерживает несколько основных препроцессоров CSS и JavaScript и даже инструменты тестирования. С помощью сцепки методов Elixir позволяет вам гибко определять свой файлопровод (asset pipeline). Например:

jselixir(function(mix) {
  mix.sass('app.scss')
     .coffee('app.coffee');
});

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

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

Установка Node

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

shnode -v

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

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

Осталось только установить Elixir! В корне установленного Laravel вы найдете файл package.json . Это то же самое, что и файл 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 при каждом изменении в ресурсах, поэтому вы можете использовать команду shgulp watch. Эта команда продолжит выполняться в терминале и будет следить за всеми изменениями ваших ресурсов. Когда что-либо изменится, автоматически скомпилируются новые файлы:

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.1

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

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

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

Компилирование простых CSS

Если вы хотите просто скомбинировать некоторые простые таблицы стилей в один файл, используйте метод PHPstyles(). Передаваемые в этот метод пути относительны к resources/assets/css, а итоговая CSS будет помещена в public/css/all.css:

jselixir(function(mix) {
  mix.styles([
    'normalize.css',
    'main.css'
  ]);
});

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

jselixir(function(mix) {
  mix.styles([
    'normalize.css',
    'main.css'
  ], 'public/assets/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");
});

Компилирование без карт кода

Карты кода (source maps) включены сразу «из коробки». Таким образом, для каждого скомпилированного файла вы найдете соответствующий ему файл *.css.map в том же каталоге. Это привязка позволяет при отладке проследить селекторы ваших скомпилированных стилей до исходных Sass или Less.

Однако, если вам необходимо отключить эту функцию, просто используйте такую настройку:

jselixir.config.sourcemaps = false;

elixir(function(mix) {
  mix.sass('app.scss');
});

Работа со скриптами

Elixir предоставляет несколько функций для работы с JavaScript-файлами, например: компилирование ECMAScript 6, компилирование CoffeeScript, Browserify, минификация и простая конкатенация простых JavaScript-файлов.

Компилирование CoffeeScript

Для компилирования CoffeeScript в простой JavaScript служит метод PHPcoffee(). Он принимает строку или массив CoffeeScript-файлов относительно пути resources/assets/coffee и генерирует единый файл public/js/app.js:

PHP
elixir(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();
});

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');
});

В 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.

Скрипты

Используйте метод PHPscripts(), чтобы скомбинировать несколько JavaScript-файлов в один.

Метод PHPscripts() работает с файлами по относительному пути resources/assets/js и сохраняет итоговый JavaScript в public/js/all.js:

jselixir(function(mix) {
  mix.scripts([
    'jquery.js',
    'app.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');
});

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

Метод PHPcopy() используется для копирования файлов и папок в новое место. Все операции относительны корневой папки проекта:

jselixir(function(mix) {
  mix.copy('vendor/foo/bar.css', 'public/css/bar.css');
});

elixir(function(mix) {
  mix.copy('vendor/package/views', 'resources/views');
});

Версии файлов /очистка кэша

Многие разработчики добавляют в имена ресурсов время создания или уникальный токен, чтобы браузер загружал свежие ресурсы вместо обработки устаревшего кода. В Elixir для этого служит метод PHPversion().

Метод PHPversion() принимает имя файла относительно папки public и добавляет к нему уникальный хеш для возможности очистки кэша. Например, сгенерированное имя файла будет выглядеть приблизительно так — all-16d570a7.css:

jselixir(function(mix) {
  mix.version('css/all.css');
});

Сгенерировав версию файла, вы можете использовать глобальную функцию Laravel PHP 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.1

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

BrowserSync

BrowserSync автоматически производит обновление в браузере при изменениях в ваших ресурсах. Вы можете использовать метод PHPbrowserSync(), чтобы Elixir запустил сервер BrowserSync, когда вы выполните команду shgulp watch:

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

После выполнения shgulp watch обратитесь к своему приложению по порту 3000, чтобы включить синхронизацию браузера — http://homestead.app:3000. Если для локальной разработки вы используете другой домен (не http://homestead.app:3000), то можете передать массив параметров вторым аргументом метода PHPbrowserSync():

jselixir(function(mix) {
  mix.browserSync({
    proxy: 'project.app'
  });
});
+ 5.0

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

Gulp

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

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

shgulp

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

shgulp watch

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

shgulp scripts

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

shgulp styles

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

shgulp tdd

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

Вызов существующих 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/**');

Комментарии (2)

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) дописываете файл галпа под свои нужды.

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

Разметка: ? ?

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