【Laravel】自作のヘルパー関数を追加する方法

こんにちは、aiiro（@aiiro29）です。

Laravelで自作のヘルパーファイルの作り方を紹介します。

要約
説明
1. ヘルパーファイルの作り方
2. テスト用ヘルパーファイルの作り方

要約

ヘルパーファイルはcomposer.jsonの”autoload”、”autoload-dev”読み込み設定をする
composer.jsonに追加した後は、composer dump-autoloadを忘れずに
テスト実行時のみ使用するヘルパーファイルを作れる
既存の処理をラップするだけでも結構便利

説明

前回は Macroの使い方を紹介しました。

今回はヘルパーファイルを作って関数を追加する方法を紹介します。

Laravelには開発を手助けしてくれる、組み込みのヘルパー関数が豊富に存在しています。
Helpers – Laravel – The PHP Framework For Web Artisans

ヘルパー関数はIlluminate/Support/helpers.phpや、Illuminate/Foundation/helpers.phpで実装されているので、気になった方は是非読んでみて下さい。

そんなヘルパー関数ですが、自作の関数を簡単に追加することができるようになっています。

今回は本番環境等で利用するヘルパーファイルと、テストで使用するヘルパーファイルの作り方を紹介します。

ヘルパーファイルの作り方

Carbon::create()をラップする関数を例として、ヘルパーファイルの作り方を説明します。

Carbonを使用する場合、ネームスペースを全て記述して呼び出すようにしない限り、Carbonをuseする必要があり、地味に面倒な作業です。

これをcarbon()というCarbon::create()をラップするヘルパー関数を定義することで、解消してみます。


namespace App\Http\Controllers;

use Carbon\Carbon;
use Illuminate\Http\Request;

class HomeController extends Controller
{
    public function index()
    {
        return Carbon::create();
    }
}

ヘルパーファイルを追加する

ヘルパーファイルを作成する
ヘルパーファイルはcomposerを使って読み込むため、Laravelプロジェクト配下ならどこでも構わないのですが、今回はapp/helpers.phpとして作成します。
ヘルパー関数を実装する


use Carbon\Carbon;

if (!function_exists('carbon')) {
    function carbon($year = null, $month = null, $day = null, $hour = null, $minute = null, $second = null, $tz = null)
    {
        return Carbon::create($year, $month, $day, $hour, $minute, $second, $tz);
    }
}

function_exists()を使用して、他で同じ名前の関数が定義されている場合は、そちらを優先するようにしています。

composer.jsonに登録する
composer.jsonのautoloadディレクティブ配下に、filesを追加します。

"autoload": {
    "classmap": [
        "database/seeds",
        "database/factories"
    ],
    "psr-4": {
        "App\\": "app/"
    },
    "files": [
        "app/helpers.php"
    ]
},

ヘルパーファイルを読み込む

composer.jsonに追加しただけではヘルパーファイルが読み込まれないため、composer dump-autoloadを実行します。


composer dump-autoload

使い方

ヘルパー関数を使うことでuse Carbon\Carbon;がなくなりました。


namespace App\Http\Controllers;

use Illuminate\Http\Request;

class HomeController extends Controller
{
    public function index()
    {
        return carbon();
    }

}

テスト用ヘルパーファイルの作り方

次に紹介するのは、テスト用データを生成するヘルパーです。

このヘルパーはLaracastsで知ったのですが、使ってみると非常に便利だったので紹介します。

Laravelではfactory()というヘルパー関数が用意されており、テストデータを作る場合、下記のように使用します。


factory(User::class)->create([
    'name' => $name,
    'email' => $email
]);

このデータ生成処理を、create()ヘルパーを定義して、更に短く書けるようにします。

テスト環境用のヘルパーファイルを追加する

ヘルパーファイルを作成する
追加するヘルパー関数はテスト時のみ使用するため、テスト用のヘルパーファイルを作成します。今回はtests/helpers.phpを作成します。
ヘルパー関数を実装する
第1引数にクラス名、第2引数にデータに設定したい値、第3引数に生成するデータの数を定義しています。


if (!function_exists('create')) {
    function create($class, $attributes = [], $times = null)
    {
        return factory($class, $times)->create($attributes);
    }
}

composer.jsonに登録する

composer.jsonのautoload-devディレクティブ配下に、filesを追加します。

"autoload-dev": {
    "psr-4": {
        "Tests\\": "tests/"
    },
    "files": [
        "tests/helpers.php"
    ]
},

テスト環境用のヘルパーファイルを読み込む

composer.jsonに追加しただけではヘルパーファイルが読み込まれないため、composer dump-autoloadを実行します。


composer dump-autoload

使い方

create()を呼び出すだけになり、factory()->create()よりも手軽に実行できるようになりました。


create(User::class, [
    'name' => $name,
    'email' => $email
]);

今回追加したヘルパー関数は実装としては簡単な内容ですが、その分手軽に使えると思います。

これを参考にして、更に自作のヘルパー関数を作ってみて下さい。

要約

説明