Laravel 5.0 Laravel Elixir

イントロダクションIntroduction

Laravel Elixir（エリクサー：万能薬）は、Laravelアプリケーションのための、基本的なGulpタスクを定義しており、きれいでスラスラかけるAPIを提供しています。Elixirは人気のあるCSSとJavascriptプリプロセッサー、それにテストツールもサポートしています。Laravel Elixir provides a clean, fluent API for defining basic Gulp[http://gulpjs.com] tasks for your Laravel application. Elixir supports several common CSS and JavaScript pre-processors, and even testing tools.

Gulpやアセットのコンパイルを始めようとして、頭がこんがらがっているようでしたら、Laravel Elixirを気に入ってもらえるでしょう！If you've ever been confused about how to get started with Gulp and asset compilation, you will love Laravel Elixir!

インストールと準備Installation & Setup

NodeのインストールInstalling Node

Elixirを始める前、最初にNode.jsをマシーンにインストール済みであることを確認してください。Before triggering Elixir, you must first ensure that Node.js is installed on your machine.

node -v

Laravel Homesteadなら、デフォルトのままでも必要なものが全部そろっています。しかし、Vagrantを使っていなくても、Nodeのダウンロードページを読めば、簡単にインストールできます。心配ありません、簡単で時間もかかりません！By default, Laravel Homestead includes everything you need; however, if you aren't using Vagrant, then you can easily install Node by visiting their download page[http://nodejs.org/download/]. Don't worry, it's quick and easy!

GulpGulp

次に、GulpをグローバルNPMパッケージとしてインストールします。Next, you'll want to pull in Gulp[http://gulpjs.com] as a global NPM package like so:

npm install --global gulp

Laravel ElixirLaravel Elixir

まだ残っているステップは、Elixirのインストールだけです。新しくLaravelをインストールすると、ルートディレクトリーにpackage.jsonがあることに気づくでしょう。PHPの代わりにNodeの依存パッケージが定義されている所が異なりますが、composer.jsonファイルと同じようなものだと考えてください。以下のコマンドで、依存パッケージをインストールしてください。The only remaining step is to install Elixir! With a new install of Laravel, you'll find a package.json file in the root. Think of this like your composer.json file, except it defines Node dependencies instead of PHP. You may install the dependencies it references by running:

npm install

使用法Usage

これでElixirがインストールできました。すぐに、コンパイルしたり、ファイルを結合したりできますよ！プロジェクトのルートディレクトリーに存在する、gulpfile.jsに全Elixirタスクが含まれています。Now that you've installed Elixir, you'll be compiling and concatenating in no time! The gulpfile.js file in your project's root directory contains all of your Elixir tasks.

LessのコンパイルCompile Less

elixir(function(mix) {
	mix.less("app.less");
});

上の例は、Lessファイルがresources/assets/lessに保存されている前提です。In the example above, Elixir assumes that your Less files are stored in resources/assets/less.

複数のLessファイルのコンパイルCompile Multiple Less Files

elixir(function(mix) {
	mix.less([
		'app.less',
		'something-else.less'
	]);
});

SassのコンパイルCompile Sass

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

これは、Sassファイルがresources/assets/sassに保存してあると仮定しています。This assumes that your Sass files are stored in resources/assets/sass.

Elixirはコンパイルするライブラリーとして、LibSassを裏で使用しています。状況により速度は遅いのですが、機能が豊かなRuby版を代わりに使用するのが有利な場合も明らかに存在します。RubyとSass gemがインストール済み(gem install sass)であれば、次のようにRuby版を使用できます。By default, Elixir, underneath the hood, uses the LibSass library for compilation. In some instances, it might prove advantageous to instead leverage the Ruby version, which, though slower, is more feature rich. Assuming that you have both Ruby and the Sass gem installed (gem install sass), you may enable Ruby-mode, like so:

elixir(function(mix) {
	mix.rubySass("app.sass");
});

ソースマップの生成を行わずコンパイルするCompile Without Source Maps

elixir.config.sourcemaps = false;

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

ソースマップ生成はデフォルトで有効になっています。各ファイルをコンパイルするごとに、\*.css.mapファイルが同じディレクトリーに生成されます。このマッピングはデバッグの時にコンパイル済みのスタイルシートセレクターからオリジナルのSassやLess定義を見つけるのに役立ちます！しかし、この機能を無効にすることもでき、上記のように指定します。Source maps are enabled out of the box. As such, for each file that is compiled, you'll find a companion *.css.map file in the same directory. This mapping allows you to, when debugging, trace your compiled stylesheet selectors back to your original Sass or Less partials! Should you need to disable this functionality, however, the code sample above will do the trick.

CoffeeScriptのコンパイルCompile CoffeeScript

elixir(function(mix) {
	mix.coffee();
});

これは、CoffeeScriptファイルがresources/assets/coffeeに保存されている前提です。This assumes that your CoffeeScript files are stored in resources/assets/coffee.

LessとCoffeeScript全部のコンパイルCompile All Less and CoffeeScript

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

PHPUnitテストの起動Trigger PHPUnit Tests

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

PHPSpecテストの起動Trigger PHPSpec Tests

elixir(function(mix) {
	mix.phpSpec();
});

スタイルシートの結合Combine Stylesheets

elixir(function(mix) {
    mix.styles([
        "normalize.css",
        "main.css"
    ]);
});

このメソッドに渡すファイルパスは、resources/assets/cssディレクトリーからの相対パスです。Paths passed to this method are relative to the resources/assets/css directory.

スタイルシートを結合し、カスタムディレクトリーへ保存Combine Stylesheets and Save to a Custom Directory

elixir(function(mix) {
	mix.styles([
		"normalize.css",
		"main.css"
	], 'public/build/css/everything.css');
});

カスタムベースディレクトリーのスタイルシートを結合Combine Stylesheets From A Custom Base Directory

elixir(function(mix) {
	mix.styles([
		"normalize.css",
		"main.css"
	], 'public/build/css/everything.css', 'public/css');
});

stylesとscriptsメソッド両方の第３引数は、メソッドに渡される全相対パスに適用されるベースディレクトリーパスです。The third argument to both the styles and scripts methods determines the relative directory for all paths passed to the methods.

ディレクトリー中の全スタイルシートを結合Combine All Styles in a Directory

elixir(function(mix) {
	mix.stylesIn("public/css");
});

スクリプトの結合Combine Scripts

elixir(function(mix) {
    mix.scripts([
        "jquery.js",
        "app.js"
    ]);
});

この場合も、全パスはresources/assets/jsからの相対位置であると仮定されます。Again, this assumes all paths are relative to the resources/assets/js directory.

ディレクトリー中の全スクリプトを結合Combine All Scripts in a Directory

elixir(function(mix) {
	mix.scriptsIn("public/js/some/directory");
});

複数のスクリプトの組み合わせを結合Combine Multiple Sets of Scripts

elixir(function(mix) {
    mix.scripts(['jquery.js', 'main.js'], 'public/js/main.js')
       .scripts(['forum.js', 'threads.js'], 'public/js/forum.js');
});

バージョン／ハッシュファイルVersion / Hash A File

elixir(function(mix) {
	mix.version("css/all.css");
});

これにより、キャッシュを破棄させるために、一意のハッシュをファイル名に追加します。例えば、all-16d570a7.cssのような名前が生成されます。This will append a unique hash to the filename, allowing for cache-busting. For example, the generated file name will look something like: all-16d570a7.css.

ビューの中で、elixir()関数を使用すれば、適切なハッシュ値付きアセット名がロードされます。例をご覧ください。Within your views, you may use the elixir() function to load the appropriately hashed asset. Here's an example:

<link rel="stylesheet" href="{{ elixir("css/all.css") }}">

裏でelixir()関数は、読み込むべきハッシュ値付きファイルの名前を決定します。肩の荷を下ろしたような感じがするでしょう？Behind the scenes, the elixir() function will determine the name of the hashed file that should be included. Don't you feel the weight lifting off your shoulders already?

バージョンを付ける複数のファイルを配列でversionメソッドに渡すこともできます。You may also pass an array to the version method to version multiple files:

elixir(function(mix) {
	mix.version(["css/all.css", "js/app.js"]);
});

<link rel="stylesheet" href="{{ elixir("css/all.css") }}">
<script src="{{ elixir("js/app.js") }}"></script>

新しい場所にファイルをコピーCopy a File to a New Location

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

新しい場所にディレクトリ全体をコピーCopy an Entire Directory to a New Location

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

Browserifyの起動Trigger Browserify

elixir(function(mix) {
	mix.browserify('index.js');
});

ブラウザの中でモジュールを取り込みたい？そのうち、EcmaScript6を使いたい？JSXトランスフォーマーを組み込みたい？それならば、browserify Elixirタスクにより、Browserifyが仕事をうまいこと片付けてくれます。Want to require modules in the browser? Hoping to use EcmaScript 6 sooner than later? Need a built-in JSX transformer? If so, Browserify[http://browserify.org/], along with the browserify Elixir task, will handle the job nicely.

このタスクはスクリプトの保存先がresources/assets/jsとして扱いますが、デフォルトは自由に変更できます。This task assumes that your scripts are stored in resources/assets/js, though you're free to override the default.

メソッドのチェーンMethod Chaining

もちろん、自分のレシピを作成するため、ほぼ全部のElixirのメソッドを一緒につなげて使用できます。Of course, you may chain almost all of Elixir's methods together to build your recipe:

elixir(function(mix) {
    mix.less("app.less")
       .coffee()
       .phpUnit()
       .version("css/bootstrap.css");
});

GulpGulp

では、Elixirにどのタスクを実行するのか伝えましょう。コマンドラインから、Gulpを起動する必要があるだけです。Now that you've told Elixir which tasks to execute, you only need to trigger Gulp from the command line.

一度に全登録タスクを実行するExecute All Registered Tasks Once

gulp

アセットの変更を監視するWatch Assets For Changes

gulp watch

スクリプトのコンパイルのみOnly Compile Scripts

gulp scripts

スタイルのコンパイルのみOnly Compile Styles

gulp styles

テストとPHPクラスの変更を監視するWatch Tests And PHP Classes for Changes

gulp tdd

注目： 全タスクは開発環境であると仮定していますので、圧縮はされません。実働用にするには、gulp --productionを指定してください。Note: All tasks will assume a development environment, and will exclude minification. For production, use gulp --production.

タスクカスタマイズと拡張Custom Tasks and Extensions

ElixirのGulpタスクをフックしたいこともあるでしょう。自分に合うようにElixirのmixや監視を変更したいこともあるでしょう。問題ありません！Sometimes, you'll want to hook your own Gulp tasks into Elixir. Perhaps you have a special bit of functionality that you'd like Elixir to mix and watch for you. No problem!

例として、呼びだされた時にテキストを少々話す一般的なタスクを考えてみましょう。As an example, imagine that you have a general task that simply speaks a bit of text when called.

gulp.task("speak", function() {
	var message = "Tea...Earl Grey...Hot";

	gulp.src("").pipe(shell("say " + message));
});

とても簡単です。もちろん端末から、gulp speakでこのタスクを起動できます。ですが、Elixirに付け加えるには、mix.task()メソッドを使ってください。Easy enough. From the command line, you may, of course, call gulp speak to trigger the task. To add it to Elixir, however, use the mix.task() method:

elixir(function(mix) {
    mix.task('speak');
});

これだけです！これでGlupを実行すると、あなたがmixした他のElixirタスクと一緒に、"speak"カスタムタスクが実行されます。一つ以上のファイルが更新されるたび、カスタムタスクを再実行するために監視を登録するには、第2引数に正規表現で指定してください。That's it! Now, each time you run Gulp, your custom "speak" task will be executed alongside any other Elixir tasks that you've mixed in. To additionally register a watcher, so that your custom tasks will be re-triggered each time one or more files are modified, you may pass a regular expression as the second argument.

elixir(function(mix) {
    mix.task('speak', 'app/**/*.php');
});

この第2引数の指定により、"app/"ディレクトリー下のPHPファイルが保存される度に、"speak"タスクが再実行されるようにElixirへ指示しています。By adding this second argument, we've instructed Elixir to re-trigger the "speak" task each time a PHP file in the "app/" directory is saved.

より柔軟な方法として、完全なElixir拡張を作成することもできます。前の"speak"の例を拡張として書いてみましょう。次のようになります。For even more flexibility, you can create full Elixir extensions. Using the previous "speak" example, you may write an extension, like so:

var gulp = require("gulp");
var shell = require("gulp-shell");
var elixir = require("laravel-elixir");

elixir.extend("speak", function(message) {

	gulp.task("speak", function() {
		gulp.src("").pipe(shell("say " + message));
	});

	return this.queueTask("speak");

 });

Gulpタスクを作成するコールバック関数と同時に、Gulpfileの中で参照される名前を渡すことにより、ElixirのAPIを拡張(extend)していることに注目してください。Notice that we extend Elixir's API by passing the name that we will reference within our Gulpfile, as well as a callback function that will create the Gulp task.

前記のように、カスタムタスクを監視したい場合は登録しましょう。As before, if you want your custom task to be monitored, then register a watcher.

this.registerWatcher("speak", "app/**/*.php");

この行は、正規表現app/**/*.phpに一致するファイルが変更された時に、speakタスクを実行することを示しています。This lines designates that when any file that matches the regular expression, app/**/*.php, is modified, we want to trigger the speak task.

これだけです！これを一番上のGulpfileに書いても良いですし、代わりにカスタムタスクファイルへ切り分けてもかまいません。後者のアプローチを取る場合、Gulpfileの中から読み込むだけです。That's it! You may either place this at the top of your Gulpfile, or instead extract it to a custom tasks file. If you choose the latter approach, simply require it into your Gulpfile, like so:

require("./custom-tasks")

済みました！これで使えます。You're done! Now, you can mix it in.

elixir(function(mix) {
	mix.speak("Tea, Earl Grey, Hot");
});

この追加により、Gulpを起動すると、ピカードがお茶を要求してくるようになります。With this addition, each time you trigger Gulp, Picard will request some tea.