L11.x on ララジャパン

ミドルウェアをもっと知ろう（３）パラメータを渡す

Sat, 26 Apr 2025 09:57:48 +0900

前回に作成した禁止用語をフィルターするミドルウェアに今度はパラメータを渡してみます。例えば、管理者権限を持つユーザーなら禁止用語を隠さずに見れる。

ミドルウェアの変更はいたって簡単で、handle()のメソッドに渡す引数を１つ$role追加します。

app/Http/Middleware/HideForbiddenWords.php

namespace App\Http\Middleware;

use Closure;
use Illuminate\Support\Str;
use Illuminate\Http\Request;

class HideForbiddenWords
{
    public static $forbiddenWords = ['禁止１', '禁止２', '禁止３'];

    // $roleの引数を追加
    public function handle(Request $request, Closure $next, string $role): mixed
    {
        $all = $request->collect()->map(function ($value, $key) use($role) {
            // 管理権限なら禁止用語は隠さずに
            if ($role === 'admin') {
                return $value;
            } else {
                return is_string($value) ? Str::of($value)->replace(static::$forbiddenWords, '***')->toString() : $value;
            }
        })->all();

        $request->merge($all);

        return $next($request);
    }
}

$roleがadminなら、禁止用語は隠さずに、それ以外は隠すという条件分岐を設けています。

さっそく、tinkerで実行してみましょう。

> $request = app('request');

> $request->merge(['sentence' => '私は「禁止１」と叫んでしまいました。'])->all();
= [
    "sentence" => "私は「禁止１」と叫んでしまいました。",
  ]
 
> use App\Http\Middleware\HideForbiddenWords;

> (new HideForbiddenWords)->handle($request, fn($request) => $request, 'admin')->all();
= [
    "sentence" => "私は「禁止１」と叫んでしまいました。",
  ]

隠さずに表示されましたね。

以下のようにroutes/web.phpにおいて、ミドルウェアを装着するならコロンと合わせて指定します。

use App\Http\Middleware\HideForbiddenWords;
 
Route::patch('/profile', [ProfileController::class, 'update'])
    ->name('profile.update')
    ->middleware(HideForbiddenWords::class.':admin');

複数の権限を指定したいなら、つまり以下のように、adminとeditorの指定としたいなら、以下のようにコンマで区切って指定します。

Route::patch('/profile', [ProfileController::class, 'update'])
    ->name('profile.update')
    ->middleware(HideForbiddenWords::class.':admin,editor');

対応するミドルウェアのコード方は、以下のように引数をstring …$roles可変引数を使用するように変えて対応します。

...
class HideForbiddenWords
{
    public static $forbiddenWords = ['禁止１', '禁止２', '禁止３'];

    // $roleの引数を追加
    public function handle(Request $request, Closure $next, string ...$roles): mixed
    {
...

ミドルウェアをもっと知ろう（２）ミドルウェアを作成

Fri, 28 Mar 2025 09:56:53 +0900

前回に紹介したLaravelのグローバルミドルウェアですが、必要に応じてカスタムのミドルウェアを作成することも可能です。今回は、入力文に含まれる禁止用語を自動的に隠す（***で置換する）ミドルウェアを例として作成します。

禁止用語を隠すミドルウェア

まず、artisanで空のミドルウェアを作成して、

$ php artisan make:middleware HideForbiddenWords

そのファイルを以下のように編集します。

app/Http/Middleware/HideForbiddenWords.php

namespace App\Http\Middleware;

use Closure;
use Illuminate\Support\Str;
use Illuminate\Http\Request;

class HideForbiddenWords
{
    public static $forbiddenWords = ['禁止１', '禁止２', '禁止３'];

    public function handle(Request $request, Closure $next): mixed
    {
        // 禁止用語を***に変換
        $all = $request->collect()->map(function ($value, $key) {
            return is_string($value) ? Str::of($value)->replace(static::$forbiddenWords, '***')->toString() : $value;
        })->all();

　　　　// もとのリクエストを置き換える
        $request->merge($all);　

        return $next($request);
    }
}

$forbiddenWords配列で設定した３つの禁止用語が入力にあれば、***に変換します。

tinkerで試してみましょう。

> $request = app('request');
> $request->merge(['sentence' => '私は「禁止１」と叫んでしまいました。'])->all();
= [
    "sentence" => "私は「禁止１」と叫んでしまいました。",
  ]

> use App\Http\Middleware\HideForbiddenWords;
> (new HideForbiddenWords)->handle($request, fn($request) => $request)->all();
= [
    "sentence" => "私は「***」と叫んでしまいました。",
  ]

期待した結果になりました。

グローバルミドルウェアに追加

作成したミドルウェアをグローバルのミドルウェアとして設定するには、ブートストラップに使用されるapp.phpを編集します。以下は、Laravel 11.xで作成されたデフォルトのファイルで、ここのwithMiddlewareのクロージャでappendするだけです。

bootstrap/app.php

use Illuminate\Foundation\Application;
use Illuminate\Foundation\Configuration\Exceptions;
use Illuminate\Foundation\Configuration\Middleware;

return Application::configure(basePath: dirname(__DIR__))
    ->withRouting(
        web: __DIR__.'/../routes/web.php',
        commands: __DIR__.'/../routes/console.php',
        health: '/up',
    )
    ->withMiddleware(function (Middleware $middleware) {
        $middleware->append(
            \App\Http\Middleware\HideForbiddenWords::class,
        );
    })
    ->withExceptions(function (Exceptions $exceptions) {
        //
    })->create();

このミドルウェアは、前回に紹介したデフォルトのグローバルミドルウェア（以下）

> use Illuminate\Foundation\Configuration\Middleware;
 
> (new Middleware)->getGlobalMiddleware();
= [
    "Illuminate\Foundation\Http\Middleware\InvokeDeferredCallbacks",
    "Illuminate\Http\Middleware\TrustProxies",
    "Illuminate\Http\Middleware\HandleCors",
    "Illuminate\Foundation\Http\Middleware\PreventRequestsDuringMaintenance",
    "Illuminate\Http\Middleware\ValidatePostSize",
    "Illuminate\Foundation\Http\Middleware\TrimStrings",
    "Illuminate\Foundation\Http\Middleware\ConvertEmptyStringsToNull",
  ]

の最後のConvertEmptyStringsToNullの次に実行されることになります。

プロジェクトのコントローラのすべてにおいてこのミドルウェアが適用されるのが大げさなら、以下のようにroutes/web.phpにおいて、特定のルートだけにミドルウェアを装着することも可能です。

use App\Http\Middleware\HideForbiddenWords;

Route::patch('/profile', [ProfileController::class, 'update'])
    ->name('profile.update')
    ->middleware(HideForbiddenWords::class);

ミドルウェアをもっと知ろう（１）グローバルミドルウェア

Sun, 16 Mar 2025 03:15:23 +0900

LaravelのミドルウェアはHttpのGETやPOSTなどのリクエストでアプリに入ってくるリクエストの中身をチェックしたり必要なら変えたりする重要なコードです。このミドルウェアの設定は、L11.x以前ではapp/Http/Kernel.phpというファイルの中身に含まれていてわかりやすかったのですが、L11.x以降はLaravelのライブラリの奥に入ってしまい日の目をみなくなってしまいました。これらを引っ張りだしてLaravelのミドルウェアがどのように使用されているか紹介します。

グローバルミドルウェア

リクエストをグローバルに処理するミドルウェアは、グローバルミドルウェアと呼ばれ、tinkerでの以下の実行でデフォルトの設定を見ることができます。

> use Illuminate\Foundation\Configuration\Middleware;

> (new Middleware)->getGlobalMiddleware();
= [
    "Illuminate\Foundation\Http\Middleware\InvokeDeferredCallbacks",
    "Illuminate\Http\Middleware\TrustProxies",
    "Illuminate\Http\Middleware\HandleCors",
    "Illuminate\Foundation\Http\Middleware\PreventRequestsDuringMaintenance",
    "Illuminate\Http\Middleware\ValidatePostSize",
    "Illuminate\Foundation\Http\Middleware\TrimStrings",
    "Illuminate\Foundation\Http\Middleware\ConvertEmptyStringsToNull",
  ]

それぞれのミドルウェアのクラスは独立した役割がありますが、ここでの紹介は比較的理解しやすい最後の２つに絞ります。

TrimStrings

このミドルウェアはHttpのGETやPOSTなどのリクエストのデータに含まれる文字列の前後の空白文字を削除します。ここでの空白文字はすべていわゆる半角文字の範囲で、

空白
改行（\n）
復帰（\r）
タブ（\t）
垂直タブ（\v）
ヌル文字（\0）

が含まれます。~~日本語の全角空白文字が含まれないことに注意を。~~ （修正：2025-03-26）日本語の全角スペースも含まれます。

また、以下のユニコードも削除されます。

表示不可能な文字（\x{FEFF}）
ゼロ幅スペース（\x{200B}）
左から右へのマーク（\x{200E}）

削除されるのは文字列中でなく前後であることに注意を。

早速、tinkerで実行してみましょう。

まずは、Requestのインスタンスを作成します。 app()を使うと簡単に作成できます。

> $request = app('request');
= Illuminate\Http\Request {#207
    +attributes: Symfony\Component\HttpFoundation\ParameterBag {#208},
    +request: Symfony\Component\HttpFoundation\InputBag {#197},
    +query: Symfony\Component\HttpFoundation\InputBag {#209},
    +server: Symfony\Component\HttpFoundation\ServerBag {#93},
    +files: Symfony\Component\HttpFoundation\FileBag {#196},
    +cookies: Symfony\Component\HttpFoundation\InputBag {#204},
    +headers: Symfony\Component\HttpFoundation\HeaderBag {#100},
  }

そして、そのリクエストにユーザーの入力をシミュレートした連想配列をマージします。もちろん、nameの値の前後にしっかりと空白文字を入れてあります。

> $request->merge(['name' => '    山田太郎    '])->all();
= [
     "name" => "    山田太郎    ",
  ]

今度はこのリクエストにTrimStringsのミドルウェアを適用します。

> use Illuminate\Foundation\Http\Middleware\TrimStrings;

> (new TrimStrings)->handle($request, fn($request) => $request)->all();
= [
    "name" => "山田太郎",
  ]

前後の空白文字が削除されましたね。

handle()のパラメーターは２つ必要されます。最初はリクエストのインスタンス、次はクロージャとして次のミドルウェアを渡します。それゆえに最初に掲載したグローバルミドルウェアが順々にリクエストに処理を加えていきます。ここでは、単に、処理されたリクエストを返すクロージャを与えています。

ConverEmptyStringsToNull

ConvertEmptyStringsToNullは、先のTrimStringsの次に適用されるミドルウェアで、今度は空の文字列をnullに変換する処理を行います。

このミドルウェアをデモするために、今度は空の値のemailの連想配列をリクエストにマージします。

> $request->merge(['email' => ''])->all();

= [
    "name" => "山田太郎",
    "email" => "",
  ]

先ほどTrimpStringsのミドルウェアを適用された同じリクエストを使用しために、nameの値が残っていることに注意を。

このリクエストに対して、ConvertEmptyStringsToNullを適用します。

> use Illuminate\Foundation\Http\Middleware\ConvertEmptyStringsToNull;

> (new ConvertEmptyStringsToNull)->handle($request, fn($request) => $request)->all();
= [
    "name" => "山田太郎",
    "email" => null,
  ]

空の文字列がnullに変換されましたね。

グローバルミドルウェアをすべて適用

最後に、最初に掲載したグローバルミドルウェアをすべてリクエストに適用するコードを紹介します。

Laravelでは以下の関数で、Pipelineのクラスを使用してリクエストをそれぞれのミドルウェアを順に適用していき最後にルートとでマップしているコントローラなどへ渡してます。

vendor/laravel/framework/src/Illuminate/Foundation/Http/Kernel.php

    /**
     * Send the given request through the middleware / router.
     *
     * @param  \Illuminate\Http\Request  $request
     * @return \Illuminate\Http\Response
     */
    protected function sendRequestThroughRouter($request)
    {
        $this->app->instance('request', $request);

        Facade::clearResolvedInstance('request');

        $this->bootstrap();

        return (new Pipeline($this->app))
            ->send($request)
            ->through($this->app->shouldSkipMiddleware() ? [] : $this->middleware)
            ->then($this->dispatchToRouter());
    }

上のコードを元に、tinkerで実行できるようにしてみました。

> use Illuminate\Foundation\Configuration\Middleware;

> $middlewares = (new Middleware)->getGlobalMiddleware();

> $request = app('request')->merge(['name' => '   山田太郎   ', 'email' => '']);

> use Illuminate\Pipeline\Pipeline;

> app(Pipeline::class)->send($request)->through($middlewares)->thenReturn()->all();
= [
    "name" => "山田太郎",
    "email" => null,
  ]

composerをもっと知ろう（４）ローカルのパッケージをLaravelで使う

Fri, 21 Feb 2025 10:58:09 +0900

皆さんは、DGFTのベリトランスの支払決済のPHPのSDKキットを使用したことありますか？それを利用するには彼らのウェブサイトからファイルをダウンロードして、プロジェクトに置いてそれをパッケージとしてインストールします。今回はその仕組みの説明です。ローカルにパッケージを作成してそれをcomposer requireします。

自分のパッケージを作成

まず、デモとしてあるヘルパー関数の定義を含むパッケージを作成します。このパッケージには１つのヘルパー関数しかなく、インストールしたら以下のように、全角の英数字文字列を半角に変換する関数、to_hankaku()を使うことができます。

Psy Shell v0.12.7 (PHP 8.2.15 — cli) by Justin Hileman
> to_hankaku('１２３');
= "123"

便利そうでしょう。

まず、Laravelのプロジェクトを新規作成して、プロジェクトのディレクトリ直下にpackagesのディレクトリを作成して、以下のような構造で必要なファイルを作成します。

├── app
...

packages
└── larajapan
    └── japanese-utils
        ├── composer.json
        └── src
            └── helpers.php
...

上では、composer.jsonとhelpers.phpのみがファイルで他は皆ディレクトリです。larajapanが開発者のアイデンティティでその下のjapanese-utilsが今回のパッケージ名となります。

まずそのパッケージのcomposer.jsonの中身を見てみましょう（混乱していけないのは、このcomposer.jsonはjapanese-utilsのパッケージのcomposer.jsonであり、これからそれをインストールしようというLaravelのプロジェクト、つまりルートパッケージのcomposer.jsonではありません）。

packages/larajapan/japanese-utils/composer.json

{
    "name": "larajapan/japanese-utils",
    "description": "helpers to manipuliate a japanese string",
    "version": "1.0.0",
    "require": {
        "php": ">=7.4",
        "ext-mbstring": "*"
    },
    "autoload": {
        "files": [
            "src/helpers.php"
        ]
    }
}

ここでは、パッケージ名（name）、説明（description）、バージョン（version）、必須条件（require）、ロードの指示（autoload）が含まれます。to_hanakaku()の関数では、mbstringのPHPのモジュールのmb_convert()を使用し、さらにタイプヒントも使用するので、それを対応しているPHPバージョン7.4以上であることをインストールの前提とします.

今度は、その関数を定義するhelpers.phpを見てみましょう。

packages/larajapan/japanese-utils/src/helpers.php

if (!function_exists('to_hankaku')) {
    function to_hankaku(string $zenkaku): string
    {
        return mb_convert_kana($zenkaku, 'as'); // 全角英数字と空白を半角に変換
    }
}

とても簡単な定義ですが、他のパッケージですでに定義されていたら困るので、!function_exists(’to_hankaku’)の条件を入れています。

Laravelのプロジェクトにインストール

同じプロジェクトのディレクトリ内にパッケージを作成したものの、これだけではプロジェクトで先ほどのto_hanakaku()は使えません。プロジェクトにインストールすることが必要です。

今度は作成したパッケージのではなくプロジェクト（ルートパッケージ）のcomposer.jsonの編集が必要です。以下のrepositoriesのブロックが追加した部分です。

composer.json

{
    "$schema": "https://getcomposer.org/schema.json",
    "name": "laravel/laravel",
    "type": "project",
    "description": "The skeleton application for the Laravel framework.",
    "keywords": ["laravel", "framework"],
    "license": "MIT",
    "repositories": [
        {
            "type": "path",
            "url": "./packages/larajapan/japanese-utils",
            "options": {
                "symlink": true
            }
        }
    ],
    "require": {
        "php": "^8.2",
        "laravel/framework": "^11.31",
        "laravel/tinker": "^2.9"
    },
...
}

“type”: “path”がローカルのパッケージがレポジトリということを指示し、その場所 “url”にパッケージの相対の場所を指定します。そして、“options”として、“symlink”: trueは、プロジェクトにおいて使用されるパッケージを収めるvendorのディレクトリにおいて、作成したパッケージへのsymlinkを張るという指示です。ちなみにfalseならファイルのコピーとなります。

これでインストールの準備は完了です。通常のパッケージのインストールのようにcomposre requireを実行しましょう。

$ composer require larajapan/japanese-utils

インストール後には、composer.jsonは更新され、“larajapan/japanese-utils”: “^1.0”,のエントリーが追加されているのがわかります。

composer.json

{
...
    "require": {
        "php": "^8.2",
        "larajapan/japanese-utils": "^1.0",
        "laravel/framework": "^11.31",
        "laravel/tinker": "^2.9"
    },
...
}

vendorのディレクトリを見ると、以下のようにパッケージへのsymlinkとなっています。

$ ls -l vendor/larajapan
total 0
lrwxrwxrwx 1 kenji kenji 40 Feb 19 16:42 japanese-utils -> ../../packages/larajapan/japanese-utils/

これで、このLaravelのプロジェクト内で、to_hankaku()のヘルパーをどこでも使えるようになります。

最後に

自分が作成したパッケージは、Packagistに登録したものでもなく、githubのレポジトリに置いたプライベートのパッケージでもありません。そのようなパッケージが必要となるのは不思議と思われるかもしれません。しかし、以下のようにいくつか必要となるケースがあります。

将来はPackagistにおいて自分で開発したパッケージを共有したいが、完成度が低いので暫くは自分のプロジェクトだけ使う
今まで使用していたgithubにあるパッケージはもうメンテインされていなくダウンロードして自分のプロジェクトだけで使えるようにする
プロジェクトが肥大化したのでパッケージとしてモジュール化して使う
あえて自社のサービスのSDKキットをPackagistでパブリックで共有することをせずに、サービスを利用する開発者にローカルにダウンロードしてからcomposerでインストールしてもらう。日本で有名なDGFTのベリトランスの決済のPHPのSDKキットはまさにそれです。

テストがちょっとシンプルになる pest-plugin-laravel プラグイン

Thu, 13 Feb 2025 08:36:45 +0900

PestはPHPUnitの上に構築された、テストをよりシンプルに書くためのフレームワークです。そのPestが公式に推奨しているLaravelのためのプラグインpest-plugin-laravelを使って既存のテストを書き直してみました。Pestが掲げる「読みやすく理解しやすい」テストコードに、少し近づけるでしょうか。

Pest導入、基本の記述方法については以下をご参照ください。 PHPUnitテストをpest-plugin-driftでPestへ変換 Pestでモック・例外のテスト

pest-plugin-laravelをインストール・テストファイル作成

Pestはすでにインストールしてあると仮定して、以下のコマンドでプラグインをインストールします。

$ composer require pestphp/pest-plugin-laravel --dev

このプラグインをインストールしたことで、まず、新しいartisanコマンドpest:testが使えるようになっています。ファイル名をPestTestと指定して以下のコマンドを実行します。

$ php artisan pest:test PestTest

tests/Feature/PestTest.phpにテストファイルが作成されます。

tests/Feature/PestTest.php

it('has pest page', function () {
    $response = $this->get('/pest');

    $response->assertStatus(200);
});

デフォルトでは、tests/Featureのディレクトリにファイルが作成されますが、–unitオプションをつけるとtest/Unitにファイルが作成されます。

もちろん、Laravel標準のmake:testコマンドで作成しても問題ありません。

$ php artisan make:test PestTest

pest-plugin-laravelを使った記述方法

プラグインインストールでテストの記述も少し簡単になります。Laravelのテストでよく使うテストヘルパーを$this->を使わず呼び出せるようになります。例えば以下のようなユーザーログアウトのテストの場合

test('users can logout', function () {

    $this->actingAs($this->user)
        ->post('/logout')
        ->assertRedirect('/');

    $this->assertGuest();
});

プラグインの機能を使って書き直すと、こんな風になります。

use function Pest\Laravel\{actingAs, assertGuest}; // インポートする

test('users can logout', function () {

    actingAs($this->user)
        ->post('/logout')
        ->assertRedirect('/');

    assertGuest();
});

actingAsやassertGuestを直接呼び出すことができるようになるため、$this->の記述がなくなってコードが少しすっきりしました。名前空間関数のインポートが必要ですので、useをお忘れなく。

他にも、よく使われるHTTPリクエストの場合

プラグイン導入前

...
    $response = $this->get('/login');
...
    $response = $this->post('/login', [
        'email'    => 'test@example.com',
        'password' => 'password',
    ]);
...

導入後

use function Pest\Laravel\{get, post};

...
    $response = get('/login');
...
    $response = post('/login', [
        'email'    => 'test@example.com',
        'password' => 'password',
    ]);
...

データベースのアサーションは

プラグイン導入前

...
    $this->assertDatabaseHas(User::class, ['email' => 'test@example.com']);
...

導入後

use function Pest\Laravel\assertDatabaseHas;
...
    assertDatabaseHas(User::class, ['email' => 'test@example.com']);
...

他にも色々なコマンドが対応していますので、詳しくはgithubをご覧ください。

プラグインの機能を使って、以前にご紹介したパスワードリセットのテストをPest形式に書き換えたものが以下になります。（書き換え前のPHPUnitのテストコードはリンクからご確認ください）

use function Pest\Laravel\{post, assertGuest, assertAuthenticated};

test('password can be reset with valid token', function () {
    Notification::fake();

    $user = User::factory()->create();

    post('/forgot-password', ['email' => $user->email]);

    Notification::assertSentTo($user, ResetPassword::class, function ($notification) use ($user) {
        $response = post('/reset-password', [
            'token' => $notification->token,
            'email' => $user->email,
            'password' => 'new_password',
            'password_confirmation' => 'new_password',
        ]);

        $response->assertRedirect('login')
            ->assertSessionHas('status', 'パスワードをリセットしました。');

        return true;
    });

    assertGuest();

    post('/login', [
        'email' => $user->email,
        'password' => 'new_password',
    ]);

    assertAuthenticated();
});

post・assertGuest・assertAuthenticatedの箇所が、$this->を省略した形に置き換えられています。「すごく変わった！」という訳ではないものの、やはり元のテストよりは細かい部分が見やすくなっています。テストコードが増えてくるとかなり違いがあるのではないでしょうか。

データセット

もう１つ、このプラグインが提供しているコマンドpest:datasetをご紹介します。

$ php artisan pest:dataset データセット名

このコマンドはtests/Datasets/にデータセット用のファイルを作成してくれます。データセットの機能自体は元からPestにあるものですが、artisanコマンドを使ってより便利に作成できるようになりました。

例として、以下のテストからデータセットを別ファイルに切り出してみます。ログインに失敗するテストと、そのデータセットをwith()で渡しています。

test('users cannot authenticate with invalid credentials', function (string $email, string $password) {
    post('/login', [
        'email'    => $email,
        'password' => $password,
    ])->assertStatus(302);

    assertGuest();
})->with([
    '間違ったパスワード'    => ['test@example.com', 'wrong-password'],
    '間違ったメールアドレス' => ['wrong@example.com', 'password'],
]);

まずはデータセットのファイルを作成します。ファイル名はLoginDataとて、以下のコマンドを実行します。

$ php artisan pest:dataset LoginData

これでtests/Datasetsにファイルが作成されましたので、テストからデータセットの部分をこちらに移行します。

tests/Datasets/LoginData.php

dataset('invalidLoginData', [
    '間違ったパスワード'    => ['test@example.com', 'wrong-password'],
    '間違ったメールアドレス' => ['wrong@example.com', 'password'],
]);

データセット名はinvalidLoginDataとしました。

元のテストコードの方は、with()の引数にデータセット名であるinvalidLoginDataを渡してあげればOKです。

test('users cannot authenticate with invalid credentials', function (string $email, string $password) {
・・・
})->with('invalidLoginData');

まとめ

このプラグインを使っても劇的にテストコードが短くなる訳ではなく、「少し良くなる」というものなので、すでにテストの書き方が確立されている環境にわざわざインストールする必要はなさそうです。が、Laravelの開発コアメンバーが開発しているプラグインなので、新しいプロジェクトでPestのテストを書いてゆくという場合には導入してみるのも面白そうだなと感じました。

composerをもっと知ろう（３）バージョンに関して

Mon, 06 Jan 2025 05:58:08 +0900

今回は、composer.jsonでrequireやrequire-devにリストされるパッケージのバージョンに関して説明します。今まで気にもとめていなかった ^11.9などの意味を解明します。

composer.json

まず、前回の「composerをもっと知ろう（２）composer create-projectでは何が起こっている？」で記載したcomposer.jsonを再度見てみましょう。

{
    "name": "laravel/laravel",
    "type": "project",
    "description": "The skeleton application for the Laravel framework.",
    "keywords": ["laravel", "framework"],
    "license": "MIT",
    "require": {
        "php": "^8.2",
        "laravel/framework": "^11.9",
        "laravel/tinker": "^2.9"
    },
    "require-dev": {
        "fakerphp/faker": "^1.23",
        "laravel/pail": "^1.1",
        "laravel/pint": "^1.13",
        "laravel/sail": "^1.26",
        "mockery/mockery": "^1.6",
        "nunomaduro/collision": "^8.1",
        "phpunit/phpunit": "^11.0.1"
    },
...
}

“laravel/framework”: “^11.9”のような記述があります。laravel/frameworkはパッケージ名で、^11.9はインストールするバージョンを指示していると思われますが、その記事を書いた時点では実際にインストールされたバージョンは11.34.2でした。どうして11.9ではないのでしょう。11.9の前についているキャレット＾はいったい何でしょう。

^11.9の意味

“laravel/framework”: “^11.9”の意味を解明するには、laravel/frameworkのパッケージをローカル環境にインストールして、gitのタグを見る必要があります。

パッケージをインストールした後に、以下のコマンドを実行して、v11のみのタグを抽出します。

$ git tag --sort=v:refname | grep v11

コマンドの出力は、以下のようになります。長いので途中…で割愛と示しています。これを書いている時点では最新はv11.37.0です。

v11.0.0
v11.0.1
v11.0.2
v11.0.3
v11.0.4
v11.0.5
v11.0.6
v11.0.7
v11.0.8
v11.1.0
v11.1.1
v11.2.0
v11.3.0
v11.3.1
v11.4.0
v11.5.0
v11.6.0
v11.7.0
v11.8.0
v11.9.0
v11.9.1
v11.9.2
...
v11.36.1
v11.37.0

上において、タグの最初の数字がメージャーのバージョン番号で、それ以下はマイナーのバージョン番号です。例えば、v11.37.0では、11がメジャーで37.0がマイナー。

Laravelの新規のプロジェクトを作成するときは、composer installが実行されます（この時点では、composer.lockのファイルはまだ存在しないと仮定）。プロジェクトにとってcomposer.jsonで指定されるパッケージはその時点で最新のパッケージのインストールを試みます。しかし必ずしもパッケージの最新とも限りません。例えば、Laravel 10.xをインストールするのに最新の11.xがインストールされては困ります。それゆえに、^11.9のような指定が使われます。

composer.jsonの“laravel/framework”: “^11.9”でのキャレット＾は、11.9以上で12.0.0未満のバージョンでその時点で最新のバージョンをインストールしなさい、という指示です。それゆえに、前回の記事を書いた時点では最新のv11.34.2が、この記事を書いている現時点ではv11.37.0がインストールされます。

この理解にとてもいいツールがありますので紹介します。

https://semver.madewithlove.com/?package=laravel%2Fframework&constraint=%5E11.9

上のリンクをクリックすると以下のような画面となります。

先ほどのlaravel/frameworkのパッケージで^11.9を指定したときにインストールされるバージョンのリストが赤箱でハイライト表示されます。そこで、^11.0とか^11.37とか入力してみてどれがハイライトされるか試してみてください。他のパッケージも指定してみてください。

さて、ここで不思議に思うはどうしてインストールすべきバージョンが最新の１つ（ここでは、v11.37.0）だけでなくいくつもハイライトされているのかです。v11.9.0からv11.37.0までのすべてのバージョンがハイライトされていますね。

これは共にインストールする他のパッケージとの依存があるかもしれないからです。もしかして、他のパッケージでは、laravel/frameworkへの依存があり、そのパッケージのcomposer.jsonにおいて、 “laravel/framework”: “11.18.1”と１つのバージョン（バージョンの前にキャレットがない）のみを指定しているかもしれません。その場合はプロジェクトでインストールされるlaravel/frameworkのバージョンは11.18.1のみと制限されます。プロジェクトがインストールしたいバージョンと依存するパッケージがインストールしたいバージョンをともに満たすためにです。

composer.jsonで記載されるバージョンの形式には、他にも~11.9とか11.9.*とか^6.0|^7.0|^8.0|^9.0|^10.0|^11.0とかあります。以下で詳しい説明があります。 https://getcomposer.org/doc/articles/versions.md

composer.lock

composer installを最初に実行した後には、composer.lockのファイルが作成されます。これは、その名の通り、実行時にインストールされたすべてのパッケージのバージョンの情報が含まれています。次回に、違う環境（例えばライブ環境とか）でこのファイルがあれば、まったく同じバージョンでパッケージをインストールしてくれるので、異なる環境での同じバージョンのパッケージがインストールされることを保証してくれます。

PHPUnit 11 - アノテーションからアトリビュートに書き換える

Mon, 06 Jan 2025 02:32:20 +0900

PHPUnit11でテストを実行すると、実行後の出力に「PHPUnit Deprecations」というメッセージが表示されるようになっていました。@testなどの慣れ親しんだアノテーションはPHPUnit12からサポート外となるようですので、新しいアトリビュートへ変更します。

PHPUnit12で削除される@アノテーション

OK, but there were issues!
Tests: 28, Assertions: 64, PHPUnit Deprecations: 1.

こちらがテスト時に表示されたメッセージです。「PHPUnit Deprecations: 1」だけだと分かりにくいので、詳細内容も出力されるようにphpunit.xmlを少し修正します。

phpunit.xml

...
<phpunit xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:noNamespaceSchemaLocation="vendor/phpunit/phpunit/phpunit.xsd"
         bootstrap="vendor/autoload.php"
         colors="true"
         displayDetailsOnPhpunitDeprecations="true" //これを追加
>
...

phpunitタグにdisplayDetailsOnPhpunitDeprecations=“true”を追加しました。これで再度テストを実行すると、以下のようなメッセージが出力されました。

There was 1 PHPUnit test runner deprecation:

1) Metadata found in doc-comment for method Tests\Unit\Models\UserModelTest::is_admin_check(). Metadata in doc-comments is deprecated and will no longer be supported in PHPUnit 12. Update your test code to use attributes instead.

メッセージによると、ドキュメントコメント内のアノテーションは非推奨とのこと。PHPUnit12ではサポート対象外となるため、テストのアノテーションは「アトリビュート」に書き換える必要があるようです。

アノテーション → アトリビュートの書き換え

今まで使っていたアノテーションの記述は、アトリビュートでは以下のように書き換えます。

@test → #[Test]
@dataProvider → #[DataProvider('データプロバイダ名')]
@covers → #[CoversMethod('カバー対象のクラス', 'カバー対象メソッド')]

他のアトリビュートの記述はドキュメントで紹介されていますのでご参照ください。

基本的にはこれらを書き換えればいいだけなのですが、@coversに関しては記述の位置が大きく変更となるためご注意ください。では具体的にどう変更になったか?というのを、以下のテストコードを使ってご紹介します。

変更前のテスト（アノテーション使用）

こちらがアノテーションを使用したユニットテストです。ドキュメントコメント内に@test、@covers、@dataProviderを使用しています。

namespace Tests\Unit\Models;

use App\Models\User;
use Illuminate\Foundation\Testing\RefreshDatabase;
use Tests\TestCase;

class UserModelTest extends TestCase
{
    use RefreshDatabase;

    /**
     * @test
     * @covers App\Models\User::isAdmin
     * @dataProvider roleDataProvider
     */
    public function is_admin_check(string $role, bool $expected): void
    {
        $user = User::factory()->create(['role' => $role]);

        $this->assertEquals($expected, $user->isAdmin());
    }

    public static function roleDataProvider(): array
    {
        return [
            'role = admin' => [
                'role' => 'admin',
                'expected' => true
            ],
            'role = user' => [
                'role' => 'user',
                'expected' => false
            ],
            'role = role' => [
                'role' => 'editor',
                'expected' => false
            ],
        ];
    }
}

変更後のテスト（アトリビュート使用）

以下が、アトリビュートに書き換えた後のテストになります。

namespace Tests\Unit\Models;

use App\Models\User;
use Illuminate\Foundation\Testing\RefreshDatabase;
use PHPUnit\Framework\Attributes\CoversMethod;
use PHPUnit\Framework\Attributes\DataProvider;
use PHPUnit\Framework\Attributes\Test;
use Tests\TestCase;

#[CoversMethod(User::class, 'isAdmin')]
class UserModelTest extends TestCase
{
    use RefreshDatabase;

    #[Test]
    #[DataProvider('roleDataProvider')]
    public function test_is_admin_check(string $role, bool $expected): void
    {
        $user = User::factory()->create(['role' => $role]);

        $this->assertEquals($expected, $user->isAdmin());
    }

    public static function roleDataProvider(): array
    {
        return [
            'role = admin' => [
                'role' => 'admin',
                'expected' => true
            ],
            'role = user' => [
                'role' => 'user',
                'expected' => false
            ],
            'role = role' => [
                'role' => 'editor',
                'expected' => false
            ],
        ];
    }
}

まず、useで#[Test]などの各属性に対応するクラスをインポートする必要があります。そして、#[Test]・#[DataProvider()]はアノテーションと同様テストケースの直前に配置します。

一番大きな変更である@coversの位置ですが、アトリビュートではクラス宣言の直前に置く形になります。ドキュメントにもあるように、#[CoversMethod()]は各テストケースではなくテストクラスに指定する必要があります。

最初このルールに気が付かず、@coversと同じように各テストケースの前に#[CoversMethod()]を配置したところ以下のようなエラーが発生しテスト失敗となりました。

$ ./vendor/bin/phpunit

An error occurred inside PHPUnit.

Message:  Attribute "PHPUnit\Framework\Attributes\CoversMethod" cannot target method (allowed targets: class)

ちゃんとエラーが出てくれたので、気がつけてよかったです。

改めてテストを実行

アトリビュートへの書き換えが正しくできているか、再度テストを実行してみます。

$ ./vendor/bin/phpunit

OK (28 tests, 64 assertions)

Deprecationsのメッセージが出なくなりました。テスト数やアサーションの数も同じなので、書き換えは問題なくできたようです。

カバレッジの出力を確認

#[CoversMethod()]の動作確認も兼ねて、カバレッジの出力も見てみます。私の環境ではpcovを使用しています。まだの方はインストールと、php.iniにて以下を設定ください。

php.ini

extension=/path/to/your/pcov.so
pcov.enabled=1
pcov.directory=/path/to/your/project

では、カバレッジのオプションをつけてテストを実行します。

$ ./vendor/bin/phpunit --coverage-html coverage

実行後、プロジェクトルートのcoverageディレクトリにhtmlファイルが生成され、#[CoversMethod]で指定した関数もちゃんとカバレッジが計測されていました。

Laravel10.xからLaravel 11.xへの更新で注意すること

Sun, 22 Dec 2024 12:30:19 +0900

Laravel 11.xがリリースされてから暫く経過していますが、やっと手持ちのLaravel 10.xのプロジェクトの更新作業に取り掛かっています。今回もLaravel Shiftのサービスを使用していますが、Laravel 10.xからLaravel11.xへの更新をすべて自動で行ってくれるわけではないです。

しかし、Laravelのサイトで説明されている更新のステップのドキュメンテーションを読むよりは、具体的な更新の変更がヒントとなり役に立ちます。もちろんShiftの変更はそれだけ十分というレベルからは遠く、とりわけ今回の更新では構造的に大きなLaravelの変更があるので、Shiftの変更後は確認とともに手動の編集作業が必須となります。

ここではお客さんのプロジェクトでの更新で私が苦労した部分をいくつか説明しますが、過去の記事にLaravel 11.xのインストールについても説明があるので合わせてお読みください。

configのファイルたちの復元

Laravel Shiftを使用した後に、config/ディレクトリ下のいくつかのファイルが削除あるいは編集されてることに気づきます。

実際、Laravel 10.xとLaravel 11.xの両方で新規のプロジェクト作成して比較してみると、以下のファイルがLaravel 11.xでは削除されています。フレームワークのスリム化の一環だそうです。

config/broadcasting.php
config/cors.php
config/hashing.php
config/sanctum.php
config/view.php

最初は、config/以下のすべてのファイルを削除するという案もあったそうですが、Laravelの作者のTaylor氏は夜寝れないほど悩んで、使用される頻度が少ない上のファイルの削除となったそうです。確かに小さいプロジェクトではそれらは使用することはなさそうです。

また、tinkerで上で削除されているconfig/view.phpの設定を見ると、

> config('view')
= [
    "paths" => [
      "/var/www/repos/laravel-11x/resources/views",
    ],
    "compiled" => "/var/www/repos/laravel-11x/storage/framework/views",
  ]

と設定ファイルがないのに裏ではしっかりデフォルトが設定されています。

さて、私のお客さんのプロジェクトでShiftを使用してLaravel 11.xに更新後では、以下のファイルが削除されていました。

config/broadcasting.php
config/cache.php
config/cors.php
config/hashing.php
config/queue.php
config/session.php
config/view.php

先のLaravel 11.xのデフォルトのプロジェクトと違って、cache.phpやqueue.phpやsession.phpも削除されています。さらに、残ったconfig/app.phpとかでは今まで存在したコメントを含めてほとんどの中身が削除されています。

基本的に、ShiftはLaravel10.xのデフォルトと同じ中身なら削除、差分があるなら差分だけと残すという方針なのでしょう。先に説明したように、設定ファイルがないからと言ってその設定が存在しなわけではないのです。.envの値もチェックしてLaravelでは以前と同様に実行時には設定値の値をメモリーに設定します。

しかし、プロジェクトを管理する上で、裏で隠されているのは理解しにくいです。ということで私は手動でShiftで削除や編集されたファイルを復元することに決めました。

戻す作業は簡単。

$ php artisan config:publish

と実行すると、以下のようなメニューが表示されます。

そこで戻したいファイルを選択して戻すことができます。

しかし、すでに存在するファイルを戻したいなら、

$ php artisan config:publish --force

として実行するとすでに存在ファイルが上書きされます。

ベストは、Laravel 11.xの新規プロジェクトを他のディレクトリで作成して、そこでconfig:publishを実行してデフォルトのファイルを書き出し、それとあなたのプロジェクトのLaravel 11.x更新前のファイルと比較しながら変更することをお勧めします。

そのためには、

$ php artisan config:publish --all --force

を実行するのが良いです。

せっかくスリムになったのに設定ファイルを戻すのはプログラムのパフォーマンスに影響を与えるのでは？と思うかもしれません。しかし、本番環境では、以下の実行して最適化のキャッシュファイルを作成すればそのような心配の必要ないです。

$ php artisan config:cache

.envを変更する必要がある

config/のファイルを復元して、じみちに以前のファイルと比較して、以前に編集したconfigファイルを戻したりするのですが、そこで気づくのは、Laravel 11.xでは、環境変数の名前が変わっている、設定ファイルの環境変数のデフォルト値が変わっている、そして、以前は.envで設定できなかった環境変数が設定できるようになっていることです。

お客さんのプロジェクトでは、以下の値の.envへの追加あるいは編集となりました（＋は追加、ーは削除）。大半は以前.envで編集では設定できずにconfig/のファイルを編集していたので、良い変更かもしれません。

# config/app.phpでの変更により以前.envで設定できない環境変数ができるようになった
+APP_TIMEZONE=Asia/Tokyo
+APP_LOCALE=ja
+APP_FAKER_LOCALE=ja_JP

# config/auth.phpでの変更により.envで設定できない環境変数ができるようになった
+AUTH_GUARD=admin
+AUTH_PASSWORD_BROKER=admin

# config/cache.phpでの変更により環境変数名が変わった
-CACHE_DRIVER=file
+CACHE_STORE=file

# config/database.phpでの変更により環境変数のデフォルト値が変わった、また.envで設定できない環境変数ができるようになった
+DB_CONNECTION=mysql
+DB_CHARSET=utf8mb3
+DB_COLLATION=utf8mb3_general_ci
+REDIS_CLIENT=predis

# config/logging.phpでの変更により.envで設定できない環境変数ができるようになった
+LOG_STACK=single

# config/session.phppでの変更により.envで設定できない環境変数ができるようになった
+SESSION_EXPIRE_ON_CLOSE=false

削除されたEventServiceProviderの中身の行方

フレームワークのスリム化として、app/Providers/のファイルの統合化があります。その結果削除されたProviderの１つにEventServiceProvider.phpがあります。

私のお客さんのプロジェクトでは以前は、EventServiceProvider.phpにおいて、以下のようなイベントとリスナーのマップが設定されていました。

app/Providers/EventServiceProvider.php

...
class EventServiceProvider extends ServiceProvider
{
namespace App\Providers;

use App\Events\SanctumUnauthenticated;
use App\Listeners\CommandFinishedListener;
use App\Listeners\CommandStartingListener;
use App\Listeners\LoginListener;
use App\Listeners\LogoutListener;
use Illuminate\Auth\Events\Login;
use Illuminate\Auth\Events\Logout;
use Illuminate\Console\Events\CommandFinished;
use Illuminate\Console\Events\CommandStarting;

class EventServiceProvider extends ServiceProvider
{
    /**
     * The event listener mappings for the application.
     *
     * @var array
     */

    protected $listen = [
        SanctumUnauthenticated::class  => [
            SecureLogging::class,
        ],
        Login::class  => [
            LoginListener::class,
        ],
        Logout::class  => [
            LogoutListener::class,
        ],
        CommandStarting::class => [
            CommandStartingListener::class,
        ],
        CommandFinished::class => [
            CommandFinishedListener::class,
        ],
    ];"
...

Laravel 11.xの更新でEventServiceProvider.phpが削除された後には、上のマップを以下のように、AppServiceProviderにおいてEvent::listenのクロージャで設定可能となります。しかし、Shiftのサービスではこの自動変換は行われずに、PRでの説明だけとなっておりこの部分はとても頼りにならず、手動の編集が必要となります。

app/Providers/AppServiceProvider.php

namespace App\Providers;

use App\Events\SanctumUnauthenticated;
use App\Listeners\CommandFinishedListener;
use App\Listeners\CommandStartingListener;
use App\Listeners\LoginListener;
use App\Listeners\LogoutListener;

use Illuminate\Support\ServiceProvider;

class AppServiceProvider extends ServiceProvider
{
    /**
     * Bootstrap any application services.
     *
     * @return void
     */
    public function boot()
    {
        Event::listen(
            SanctumUnauthenticated::class,
            CommandFinishedListener::class,
            CommandStartingListener::class,
            LoginListener::class,
            LogoutListener::class,
        );
    }
...

しかし、app/Events/やapp/Listeners/で定義したイベントやリスナーをいちいちリストするのは面倒です。

もっと簡単なのは、bootstrap/app.phpにおいて、Laravelに見つけてもらうことです。

bootsrap/app.php

...
return Application::configure(basePath: dirname(__DIR__))
    ->withProviders()
...
   ->withEvents(discover: [
        __DIR__.'/../app/Events',
        __DIR__.'/../app/Listeners',
        __DIR__.'/../app/Modules/Pmaster/Listeners',
    ])
...

このように、withEvents()で必要なディレクトリーを指定するだけです。将来に追加や削除しても自動でdiscoverされます。

正しくdiscoverされているかを確認するには、以下のコマンドを実行します。

$ php artisan event:list

そして、本番環境では、以下を実行して先のcacheと同様に必要データをキャッシュします。

$ php artisan event:cache

最後に

Laravel 11.xへの更新作業は、Shiftのサービスとその後の手動確認と編集のハイブリッドになりました。Shiftで変更の対象を学び更新を理解しそれを適用という感じです。もちろんShiftの作業は後者の手動の作業に比べて非常に安い（２９ドル）のですが、一度理解できたら、他のプロジェクトでの同様な更新にShiftの利用は必要ないかもしれません。多分に将来はLaravelの更新作業は、AIですべて完璧に行ってくれるかもしれないですね。現在はまさに過渡期です。

composerをもっと知ろう（２）composer create-projectでは何が起こっている？

Sun, 08 Dec 2024 08:59:55 +0900

誰しも、composer create-project laravel/laravelのコマンドで新規のLaravelのプロジェクトの開発を開始します。Laravelが凄いのは、この実行後にすぐにプロジェクトを立ち上げて(php artisan serve）ブラウザでサイトを閲覧することが可能となることです。その実行では画面に英語でいろいろと経過が表示されますが、いったい何が起こっているのでしょうか？

Laravelの新規のプロジェクトの作成

最新のLaravel 11.xを使用してプロジェクトを作成するには、以下のようなコマンドの実行が必要です。

$ composer create-project laravel/laravel laravel-11x

上のコマンドラインにおいて、

create-projectは、composerの新規プロジェクト作成のオプション名です。
laravel/laravellは、プロジェクトのルートとなるパッケージ名です。指定したパッケージ名をpackagist.orgのサイトでで探します。 https://packagist.org/?query=laravel/laravel マッチするパッケージが存在するgithubのレポからパッケージのダウンロードとなります。
laravel-11xは新規プロジェクト名で、その名前でプロジェクトのディレクトリを作成して、そこに必要なパッケージをダウンロードしてインストールし設定を行います。

ルートパッケージのバージョンの指定も以下のように可能です。

$ composer create-project laravel/laravel laravel-10x "10.*"

上では、 10.*は、Laravel 10で一番最新のバージョンで新規プロジェクトが作成されます。

プロジェクト作成の設計図

今回の新規のプロジェクトの作成として指定されるlaravel/laravelは、以下からダウンロードされます。 https://github.com/laravel/laravel そこに含まれる、composer.jsonのファイルに、プロジェクトに必要なパッケージのダウンロードとインストール、そしてプロジェクト立ち上げに必要な.envやDBの作成などが指定されています。

ファイルの中身を見てみましょう。phpのプロジェクトですがフォーマットはjsonとなっています。途中今回の話に関係ないところは…で省いています。

{
    "name": "laravel/laravel",
    "type": "project",
    "description": "The skeleton application for the Laravel framework.",
    "keywords": ["laravel", "framework"],
    "license": "MIT",
    "require": {
        "php": "^8.2",
        "laravel/framework": "^11.9",
        "laravel/tinker": "^2.9"
    },
    "require-dev": {
        "fakerphp/faker": "^1.23",
        "laravel/pail": "^1.1",
        "laravel/pint": "^1.13",
        "laravel/sail": "^1.26",
        "mockery/mockery": "^1.6",
        "nunomaduro/collision": "^8.1",
        "phpunit/phpunit": "^11.0.1"
    },
...
    "scripts": {
        "post-autoload-dump": [
            "Illuminate\\Foundation\\ComposerScripts::postAutoloadDump",
            "@php artisan package:discover --ansi"
        ],
        "post-update-cmd": [
            "@php artisan vendor:publish --tag=laravel-assets --ansi --force"
        ],
        "post-root-package-install": [
            "@php -r \"file_exists('.env') || copy('.env.example', '.env');\""
        ],
        "post-create-project-cmd": [
            "@php artisan key:generate --ansi",
            "@php -r \"file_exists('database/database.sqlite') || touch('database/database.sqlite');\"",
            "@php artisan migrate --graceful --ansi"
        ],
        "dev": [
            "Composer\\Config::disableProcessTimeout",
            "npx concurrently -c \"#93c5fd,#c4b5fd,#fb7185,#fdba74\" \"php artisan serve\" \"php artisan queue:listen --tries=1\" \"php artisan pail --timeout=0\" \"npm run dev\" --names=server,queue,logs,vite"
        ]
    },
...
}

上において、“require”は、laravelのルートパッケージがライブの環境で必要なパッケージです。“require-dev”は、開発環境で必要なパッケージです。たったこれだけですが、前回に説明したようにそれらが依存するパッケージがあるので実際にインストールパッケージは100以上の数になります。 “scripts”の部分は、特定なイベントごとに実行する指令が記述されています。

create-project実行の作業

composer create-projectを実行すると、以下のような経過表示となります。すべて掲載するととても長いのでパッケージのLockingやDownloadingやInstallingの多くは割愛しています。

上から順番に説明していきます。

プロジェクトディレクトリの作成

Creating a "laravel/laravel" project at "./laravel-11x"

まず、コマンド実行で指定した新規プロジェクト名のディレクトリlaravel-11xを作成します。

ルートパッケージのインストール

Creating a "laravel/laravel" project at "./laravel-11x"
Installing laravel/laravel (v11.3.3)
  - Downloading laravel/laravel (v11.3.3)
  - Installing laravel/laravel (v11.3.3): Extracting archive
Created project in /var/www/repos/laravel-11x

laravel/laravelが管理されているgithubのレポからファイルをダウンロードしてlaravel-11xのディレクトリにインストールします。 Downloadingでは、ダウンロードされたファイルは直接larave-11xへのディレクトリには置かれません。将来のインストールを効率化するために、ユーザーのキャッシュのディレクトリにインストールされます。私のubuntuの環境では、ホームディレクトリの.cache/composerにファイルが置かれます。すでに同じバージョンのパッケージがあるなら、Downloadingは行われずに、そのキャッシュのディレクトリから、laravel-11xへのディレクトリにファイルがコピーされます。その作業がInstallingです。

.envの作成

> @php -r "file_exists('.env') || copy('.env.example', '.env');"

これは、composer.jsonの“scripts”セクションにあった、“post-root-package-install”のスクリプトですね。.env.exampleをコピーして.envを作成です。

composer.lockの作成

Loading composer repositories with package information
Updating dependencies
Lock file operations: 107 installs, 0 updates, 0 removals
  - Locking brick/math (0.12.1)
  - Locking carbonphp/carbon-doctrine-types (3.2.0)
...
Writing lock file

ここでは、composer.jsonの“require”と“require-dev”で指定されたパッケージたちのcomposer.jsonを読み、それらが依存するパッケージのcomposer.jsonも読み、コンフリクトがないようにインストールするすべてのパッケージとそのバージョンを決定します。そして、この時点で初めてcomposer.lockのファイルを作成して決定した情報を書き込みします。それがLockingの作業です。

“require”で指定したバージョンのデータと実際にダウンロードされるバージョンの違いに注意してください。例えば、“require"では、“laravel/framework”: “^11.9”とありますが、この時点では

...
- Locking laravel/framework (v11.34.2)
...

と、v11.34.2のバージョンがインストールされます。

依存するパッケージのインストール

Installing dependencies from lock file (including require-dev)
Package operations: 107 installs, 0 updates, 0 removals
  - Downloading doctrine/inflector (2.0.10)
  - Downloading doctrine/lexer (3.0.1)
...
  - Installing doctrine/inflector (2.0.10): Extracting archive
  - Installing doctrine/lexer (3.0.1): Extracting archive
...
41 package suggestions were added by new dependencies, use `composer suggest` to see details.

ここのステップでルートパッケージに依存するすべてのパッケージがcomposer.lockに従ったバージョンでlaravel-11x/vendorにインストールされます。DownloadingやInstallingはルートパッケージのところで説明したものと同様です。

scriptsの実行

Generating optimized autoload files
> Illuminate\Foundation\ComposerScripts::postAutoloadDump
> @php artisan package:discover --ansi
> @php artisan vendor:publish --tag=laravel-assets --ansi --force
> @php artisan key:generate --ansi
> @php -r "file_exists('database/database.sqlite') || touch('database/database.sqlite');"
> @php artisan migrate --graceful --ansi

残りの作業は、composer.jsonで指定されたイベントにマッチするスクリプトが実行されます。上から順番に以下のイベントとなります。

```
        "post-autoload-dump": [
            "Illuminate\\Foundation\\ComposerScripts::postAutoloadDump",
            "@php artisan package:discover --ansi"
        ],
```
composer autoload-dumpを実行したときにも実行されますが、プロジェクトの初期化で使用される必要なパッケージとそのクラスのリストを含むファイルを作成します。
```
        "post-update-cmd": [
            "@php artisan vendor:publish --tag=laravel-assets --ansi --force"
        ],
```
プロジェクトで必要なアセットのファイルをパブリッシュします。上の経過では何もパブリッシュするものがなかったようです。

       "post-create-project-cmd": [
            "@php artisan key:generate --ansi",
            "@php -r \"file_exists('database/database.sqlite') || touch('database/database.sqlite');\"",
            "@php artisan migrate --graceful --ansi"
        ],

最後に、ここで.envのAPP_KEYの値を作成し、sqliteのデータベースのファイルを作成して、マイグレーションを実行します。

上は最新のLaravel 11.xですが、Laravel 10.xでは、

        "post-create-project-cmd": [
            "@php artisan key:generate --ansi"
        ]

となっていて、sqliteのデータベースの作成や設定は行いませんでした。

Laravel Pestでモック・例外のテスト

Wed, 04 Dec 2024 07:44:19 +0900

前回の記事では、LaravelプロジェクトのPHPUnitテストをプラグインを使ってPestへ自動変換しましたが、今回は自分でPestのテストを作成します。外部APIのモック、基本的なアサーションや例外が投げられたパターンなどのテストです。

テスト対象

以下が今回のテスト対象であるTestClassです。getTranslate()では引数のテキストをAPIを使って翻訳し、結果をJsonレスポンスで返却。処理に失敗した場合は例外をスローするようになっています。

ラップしているTranslationApiは外部APIなので、今回はこちらはモックとします。

class TestClass
{
    public function __construct(
        private readonly TranslationApi $translator //これをモックする
    ) {}

    public function getTranslate(string $content): JsonResponse
    {
        try {
            $translatedContent = $this->translator->translate(
                $content
            );

            return response()->json([
                'status'  => 'success',
                'message' => '操作が成功しました。',
                'data'    => $translatedContent,
            ]);

        } catch (Exception $e) {

            throw new Exception('翻訳に失敗しました: '.$e->getMessage());
        }
    }
}

Pestの構文

Pestの構文は以下のようになっており、テストをグルーピングするdescribe()メソッドと、１つ１つのテストケースを指すtest()もしくはit()メソッドで構成されています。PHPUnitで書かれているクラス宣言は不要です。

describe('グループ名', function () {
   test('テスト１', function () {
       //テスト内容
    });
 
   it('テスト２', function () {
       //テスト内容
    });
});

describe()の使用は任意なので、最小構成のtest()、it()のみで問題ありません。

またtest()とit()のどちらを使うのかという点ですが、テストの動作自体は同じなのでどちらでも大丈夫です。ただit()を使った場合、実行結果の出力で以下のようにテスト名の前にitがつくようになっています。

共通処理

ではテストを書いてゆきます。今回は成功・失敗の２パターンテストを書きますので、共通の処理をbeforeEach()を使ってまとめておきます。beforeEach()は各テストケースの実行前に呼び出される、PHPUnitのsetUp()と同じような役割です。

モック対象であるTranslationApiのモック化と、テスト対象クラスのインスタンス化の２点を以下のように共通処理としました。

beforeEach(function () {
    // モックを作成
    $this->mock = Mockery::mock(TranslationApi::class);

    // テスト対象のクラスをインスタンス化
    $this->service = new testClass($this->mock);
});

モックにはPHPUnitと同様にMockeryを使用します。ここではmock()メソッドで対象クラスをモック化するのみとして、モックの振る舞いは各テスト内でセットします。

testClassクラスのインスタンス化も、PHPUnitと記述は特に変わりません。

なお$this->mockや$this->serviceのプロパティ宣言は、Pestでは不要です。

成功パターンのテスト

「翻訳が成功して期待するレスポンスが返ってきたケース」のテストコードは以下になります。

test('翻訳 成功', function () {
    //準備
    $content = 'こんにちは';
    $expected = 'Hello';

    $this->mock
        ->shouldReceive('translate')
        ->once()
        ->with($content)
        ->andReturn($expected);

    //テスト実行
    $response = $this->testClass->getTranslate($content);

    expect($response->getData(true))
        ->toMatchArray([
            'status'  => 'success',
            'message' => '操作が成功しました。',
            'data'    => 'Hello',
        ]);
});

テストコードは大きく前半の準備部分と、後半の実行・アサーションの部分に分かれています。

まず前半では、モックの振る舞いを定義しています。shouldReceive(’translate’)は、translateメソッドが呼ばれること、once()は、呼ばれるのは１度だけという回数を、with($content)で渡される引数を、そして最後にandReturn()で、戻り値を指定しています。

次に後半の、テスト実行と戻り値のアサーションです。

受け取った$response自体はJsonResponseオブジェクトなので、$response->getData(true)でテストに必要な値だけを取り出しています。getData()はデフォルトでstdClassオブジェクトを返すので、ここでは引数にtrueを渡すことで配列として戻り値を受け取っています。

そして検証にはexpect()というPestのアサーションメソッドを使用します。expect()はそれ単体で使用することはなく、通常他のアサーション関数をチェーンします。今回はtoMatchArray()という配列比較の関数を繋ぎました。

toMatchArray()は上のテストコードのように全ての項目を比較することもできますし、以下のように、一部の項目だけといった部分一致も検証できるのでとても便利です。

    expect($response->getData(true))
        ->toMatchArray([
            'message' => '操作が成功しました。',
            'data'    => 'Hello',
        ]);

    expect($response->getData(true))
        ->toMatchArray([
            'data'    => 'Hello',
        ]);

また以下は配列比較でテストが失敗した場合のスクリーンショットですが、差分をこのようにわかりやすく出力してくれます。

失敗パターンのテスト

では次は、「翻訳が失敗し、例外を返すパターン」のテストコードです。

test('翻訳 失敗で例外が返る', function () {

    $content = 'こんにちは';
    $errorMessage = 'API error occurred';

    $this->mock
        ->shouldReceive('translate')
        ->once()
        ->with($content)
        ->andThrow(new Exception($errorMessage));

    $this->testClass->getTranslate($content);

})->throws(Exception::class, '翻訳に失敗しました: API error occurred');

先ほどの成功のテストとは少し構成が変わりました。

まずは前半のモック定義部分。ここは先ほどとほとんど同じですが、モックの戻り値の指定にandThrow(new Exception($errorMessage))として、例外を投げるように指定しています。

そして検証部分はチェーンで繋いだthrows()メソッドで行います。throws()はPestが提供しているメソッドで、第一引数に期待する例外クラスを、第二引数では例外のメッセージを渡します。

PHPUnitの場合、例外の検証時は以下のようにテストコードの冒頭に置かなければいけません。一方Pestではテスト実行後の最後にアサーションを配置できるので、テスト実行の流れと合っていてとても読みやすいと感じました。

public function test_翻訳失敗_PHPUnitの場合()
{
    $this->expectException(Exception::class);
    $this->expectExceptionMessage('翻訳に失敗しました: API error occurred');
    // ... 以下でテスト実行
}

現在LaravelでPHPUnitを使っていてPestを導入しようかなと考えている方は、よろしければ以下の移行手順もご覧ください。

LaravelのPHPUnitテストをpest-plugin-driftでPestへ変換

composerをもっと知ろう（１）composer show

Sat, 23 Nov 2024 06:51:48 +0900

composerは、phpのプロジェクトで使用されるパッケージを管理するコマンドです。昨今はcomposerなしではphpのプロジェクトは作成できないほど重要なものです。しかし、知らないことがたくさんあります。ということで「composerをもっと知ろう」シリーズです。composerに関するいろいろな面を紹介していきます。

composerがインストールしたパッケージ

まず、最新のLaravelのプロジェクトを作成してみましょう。

$ composer create-project laravel/laravel laravel-11x

composer create-projejtに関しては違う機会に説明するとして、上のコマンド実行後に何のパッケージがインストールされたか見てみましょう。

$ composer show

を実行すると、以下のように107ものパッケージのリストが、パッケージ名、バージョン、説明を列として表示されます。

brick/math                         0.12.1  Arbitrary-precision arithmetic library
carbonphp/carbon-doctrine-types    3.2.0   Types to use Carbon in Doctrine
dflydev/dot-access-data            3.0.3   Given a deep data structure, access data by dot notation.
doctrine/inflector                 2.0.10  PHP Doctrine Inflector is a small library that can perform string manipulations with regard to upper/lowercase and singular/plural forms of words.
doctrine/lexer                     3.0.1   PHP Doctrine Lexer parser library that can be used in Top-Down, Recursive Descent Parsers.
dragonmantank/cron-expression      3.4.0   CRON for PHP: Calculate the next or previous run date and determine if a CRON expression is due
egulias/email-validator            4.0.2   A library for validating emails against several RFCs
fakerphp/faker                     1.24.0  Faker is a PHP library that generates fake data for you.
filp/whoops                        2.16.0  php error handling for cool kids
fruitcake/php-cors                 1.3.0   Cross-origin resource sharing library for the Symfony HttpFoundation
graham-campbell/result-type        1.1.3   An Implementation Of The Result Type
guzzlehttp/guzzle                  7.9.2   Guzzle is a PHP HTTP client library
guzzlehttp/promises                2.0.4   Guzzle promises library
guzzlehttp/psr7                    2.7.0   PSR-7 message implementation that also provides common utility methods
guzzlehttp/uri-template            1.0.3   A polyfill class for uri_template of PHP
hamcrest/hamcrest-php              2.0.1   This is the PHP port of Hamcrest Matchers
laravel/framework                  11.31.0 The Laravel Framework.
laravel/pail                       1.2.1   Easily delve into your Laravel application's log files directly from the command line.
laravel/pint                       1.18.1  An opinionated code formatter for PHP.
laravel/prompts                    0.3.2   Add beautiful and user-friendly forms to your command-line applications.
laravel/sail                       1.38.0  Docker files for running a basic Laravel application.
laravel/serializable-closure       1.3.6   Laravel Serializable Closure provides an easy and secure way to serialize closures in PHP.
laravel/tinker                     2.10.0  Powerful REPL for the Laravel framework.
league/commonmark                  2.5.3   Highly-extensible PHP Markdown parser which fully supports the CommonMark spec and GitHub-Flavored Markdown (GFM)
..
続く

まだ開発を始めていなのにすでにこれだけのパッケージがインストールされます。上のリストを見ていて気付くのは、もちろんのことですが、Laravel自体もパッケージなのです。上のリストにあるlaravel/frameworkがそうです。他のもlaravelのレポからは６つのパッケージがインストールされます。私が大好きなlaravel/tinkerも含まれます。

composer.jsonの中身を見ればわかりますが、そこでは上のすべてのパッケージを指定はしていません。以下を実行すると指定したパッケージがリストされます。

$ composer show --self

上で、requiresの下にリストされているのが、ライブ環境で必要なパッケージです。phpはすでにインストールされているのでたったの２つです。 requires (dev)は、開発環境において必要なパッケージです。こちらもたったの７つです。

さて、どうしてcomposer showでは107ものパッケージがリストされるのでしょうか？

それは、requiresあるいはrequires (dev)でリストされているそれぞのパッケージがまた違うパッケージを必要とするからです。さらにそのパッケージもまた他のを…と。

例えば、私が好きなtinkerのパッケージを見てみましょう。

$ composer show --tree "laravel/tinker"

ツリー構造はtinkerのパッケージが依存するパッケージを表示します。

パッケージだけでなく、phpのバージョンやphpもモジュール（ext-json *など）の依存もあります。

composerはこれらを全部チェックして、すべてのをまとめて必要なパッケージをインストールします。それぞれパッケージは違うバージョンを指定することもあるので、バージョンの整合性もチェックする必要あります。非常に大変に複雑な作業です。composerの偉大さが理解できますね。

インストールされているパッケージは最新？

インストールしたパッケージたちは時間が経つと、バグの修正や新規のの追加など行われ、インストール時のバージョンと変わってきます。以下のコマンドは、最新のパッケージの情報を取得してきて見せてくれます。それゆえにコマンド実行には時間がかかります。

$ composer show --latest

それぞれの列は、パッケージ名、インストールされているバージョン、最新のバージョン、そして説明となります。最新のパージョンに列において緑字は「最新」であり更新の必要はないということで、赤字は更新を「推薦」という意味です。

黄色時は「メジャー」のバージョン更新がリリースされていることを示します。以下は違うプロジェクトからですが、前バージョンのLaravel 10xを使用しており、ご覧のようにLaravel 11xのメジャーリリースがあることを示しています。

先のプロジェクトに戻って、全部ではなく更新を推薦するパッケージのみを見たいなら以下を実行してください。–no-devのオプションは開発のパッケージを表示しません。

$ composer show --outdated --no-dev

LaravelのPHPUnitテストをpest-plugin-driftでPestへ変換

Sun, 10 Nov 2024 01:38:41 +0900

Laravel10から公式にテストフレームワークとしておすすめされるようになったPestですが、すでにPHPUnitで作成したテストファイルがたくさんある場合、それらを書き換えての移行は大変です。そこで、Pestが提供している変換用プラグインpestphp/pest-plugin-driftを試してみました。

Pest変換対象のLaravelプロジェクト

今回Pestへ変換するLaravelプロジェクトは以下の環境です。テスト用の小さいプロジェクトなので、テストファイルは9ファイルのみとなっています。

Laravel Framework 11.29.0 PHPUnit 11.4.2 PHP 8.2.24

Pest・Pest変換用プラグインインストール

では早速Pestからインストールします。Pest公式サイトの手順に従って進めます。

まずはPHPunitを削除。

$ composer remove phpunit/phpunit

次に、以下のコマンドでPestをインストール。

$ composer require pestphp/pest --dev --with-all-dependencies

Pestのバージョン3.5がインストールされました。続いてinitを実行します。

$ ./vendor/bin/pest --init

すると以下のファイルが作成されました。すでに存在しているファイルはパスされるので、実質Pest.phpのみが作成された形です。

これでPest本体のインストールは完了です。テストファイルの記述はまだPHPUnitのままですが、この段階でも./vendor/bin/pestが実行できます。

続いて変換用プラグインをインストールしてゆきます。こちらも公式サイトの手順に従って、以下のコマンドを実行します。

$ composer require pestphp/pest-plugin-drift --dev

バージョン3.0.0がインストールされました。最後に、以下のコマンドでPHPUnitからPestへの変換を実行します。

$ ./vendor/bin/pest --drift

既存のテストファイルが全て変換されました。

今回は小さいシンプルなプロジェクトなので各種インストールはとくに問題なく進みましたが、大きなプロジェクトの場合依存関係の問題でインストールがスムーズにいかないこともあると思います。

PHPUnit → Pest変換前後の比較

では、変換されたファイルを前後比較してみます。まず、以下が変換前のPHPUnit仕様のテストです。setUpやdataProviderも使用したよくあるテストコードです。

/tests/Feature/Auth/AuthenticationTest.php

namespace Tests\Feature\Auth;

use App\Models\User;
use Illuminate\Foundation\Testing\RefreshDatabase;
use Tests\TestCase;

class AuthenticationTest extends TestCase
{
    use RefreshDatabase;

    protected $user;

    protected function setUp(): void
    {
        parent::setUp();

        // 共通ユーザー作成
        $this->user = User::factory()->create([
            'email'    => 'test@example.com',
            'password' => 'password'
        ]); 
    }

    /**
     * @covers \App\Http\Controllers\Auth\LoginController::showLoginForm
     */
    public function test_login_screen_can_be_rendered(): void
    {
        $response = $this->get('/login');
        $response->assertStatus(200);
    }

    /**
     * @covers \App\Http\Controllers\Auth\LoginController::login
     */
    public function test_users_can_authenticate_with_valid_credentials(): void
    {
        $response = $this->post('/login', [
            'email'    => 'test@example.com',
            'password' => 'password',
        ]);

        $this->assertAuthenticated();
        $this->assertEquals('test@example.com', auth()->user()->email);
        
        $response->assertRedirect(route('dashboard', absolute: false));
    }

    /**
     * @covers \App\Http\Controllers\Auth\LoginController::login
     * @dataProvider invalidLoginDataProvider
     */
    public function test_users_cannot_authenticate_with_invalid_credentials($email, $password): void
    {
        $response = $this->post('/login', [
            'email'    => $email,
            'password' => $password,
        ]);

        $this->assertGuest();
        $response->assertStatus(302);
    }

    public static function invalidLoginDataProvider(): array
    {
        return [
            '間違ったパスワード'    => ['test@example.com', 'wrong-password'],
            '間違ったメールアドレス' => ['wrong@example.com', 'password'],
        ];
    }

    /**
     * @covers \App\Http\Controllers\Auth\LoginController::logout
     */
    public function test_users_can_logout(): void
    {
        $response = $this->actingAs($this->user)->post('/logout');

        $this->assertGuest();
        $response->assertRedirect('/');
    }
}

そして、Pestに変換された後のテストがこちらです。

/tests/Feature/Auth/AuthenticationTest.php

use App\Models\User;

uses(\Illuminate\Foundation\Testing\RefreshDatabase::class);

beforeEach(function () {
    // 共通ユーザー作成
    $this->user = User::factory()->create([
        'email'    => 'test@example.com',
        'password' => 'password'
    ]);
});

test('login screen can be rendered', function () {
    $response = $this->get('/login');
    $response->assertStatus(200);
});

test('users can authenticate with valid credentials', function () {
    $response = $this->post('/login', [
        'email'    => 'test@example.com',
        'password' => 'password',
    ]);

    $this->assertAuthenticated();
    expect(auth()->user()->email)->toEqual('test@example.com');

    $response->assertRedirect(route('dashboard', absolute: false));
});

test('users cannot authenticate with invalid credentials', function ($email, $password) {
    $response = $this->post('/login', [
        'email'    => $email,
        'password' => $password,
    ]);

    $this->assertGuest();
    $response->assertStatus(302);
})->with('invalidLoginDataProvider');

dataset('invalidLoginDataProvider', function () {
    return [
        '間違ったパスワード'    => ['test@example.com', 'wrong-password'],
        '間違ったメールアドレス' => ['wrong@example.com', 'password'],
    ];
});

test('users can logout', function () {
    $response = $this->actingAs($this->user)->post('/logout');

    $this->assertGuest();
    $response->assertRedirect('/');
});

変換後のPest仕様のコードではクラスの定義は削除され、それぞれのテストケースは関数宣言ではなくtest()関数として記述されています。また変換前は85行あったテストコードがPest変換後は57行とかなりコンパクトになりました。Docコメントが全て削除されているのが大きいのかもしれません。

それでは、移行するにあたり気になっていた箇所をピックアップしてみてみます。

dataprovider

PHPUnitのdataProviderは、Pest変換後は以下のようになりました。Docコメントとともに@dataProviderの記述は削除されて、代わりにwith()でデータセットを紐付けしています。テストとデータセットがバラバラなので、見た目にはPHPUnitとあまり変わりがありませんね。

test('users cannot authenticate with invalid credentials', function ($email, $password) {
・・・・・
})->with('invalidLoginDataProvider');

dataset('invalidLoginDataProvider', function () {
    return [
        '間違ったパスワード'    => ['test@example.com', 'wrong-password'],
        '間違ったメールアドレス' => ['wrong@example.com', 'password'],
    ];
});

データセットの紐付けは、以下のようにwith()内に記述される形に変換されることを期待したのですが、そうはなりませんでした。

test('users cannot authenticate with invalid credentials', function ($email, $password) {
    ・・・・・
    })->with([
        ['test@example.com', 'wrong-password'],
        ['wrong@example.com', 'password']
]);

setUp関連

PHPUnitのsetUp()は、以下のようにbeforeEach()に変換されました。beforeEach()とは、それぞれのテストメソッドの実行前に毎回呼び出されるsetUp()と同じように共通の処理を行う際に使用されるメソッドです。

beforeEach(function () {
    // 共通ユーザー作成
    $this->user = User::factory()->create([
        'email'    => 'test@example.com',
        'password' => 'password'
    ]);
});

他にも、PHPUnitで当然のように書いていたparent::setUp()やuse RefreshDatabase;はPestでは書く必要がなく、またprotected $user;といったプロパティ宣言も不要です。Pestの謳い文句の通り、テストコードはだいぶシンプルにできますね。

テスト実行

では変換後のテストを実行してみましょう。

テストはコマンドラインで、

$ ./vendor/bin/pest

あるいは、

$ php artisan test

で実行できます。

以下のようにオプションを渡して実行ファイルを指定することもできます。

$ ./vendor/bin/pest --filter=AuthenticationTest //ファイル名を指定する場合

実行結果は以下のように出力されました。

テストにかかる時間はPestに変換しても速くなるということは特になく、PHPUnitと変わりなかったです。

今回は自動で変換したためPestの記述に関しては要点のみとなりましたが、次回は手動でPestのテストコードを作成してゆきます。

カレンダー（４）タイムゾーン

Mon, 04 Nov 2024 06:31:17 +0900

今までのカレンダーシリーズでは、タイムゾーンのことをまったく考えていませんでしたが、もちろん考える必要あります。

Laravelのタイムゾーンは何？

Laravelのプロジェクトのタイムゾーンは、以下で設定されています。

config/app.php

...
/*
    |--------------------------------------------------------------------------
    | Application Timezone
    |--------------------------------------------------------------------------
    |
    | Here you may specify the default timezone for your application, which
    | will be used by the PHP date and date-time functions. The timezone
    | is set to "UTC" by default as it is suitable for most use cases.
    |
    */

    'timezone' => env('APP_TIMEZONE', 'UTC'),
...

見ての通り、デフォルトはUTCです。 UTCとは、協定世界時のことで国際協定により定められた世界共通の標準時です。

これを上書きしたいなら、.envで以下のように設定できます。

.env

...
APP_TIMEZONE="Asia/Tokyo"
...

上の設定は日本時間ですが、その値はPHPでは以下でリストされていて、 https://www.php.net/manual/ja/timezones.php アジアは、以下でリストされています。 https://www.php.net/manual/ja/timezones.asia.php

DateTimeZone

アプリで固定のタイムゾーン（つまり、APP_TIMEZONEを指定）でなく、タイムゾーンをダイナミックに変えたいなら、さきのタイムゾーンの定数を、以下のDateTimeZoneのクラスのインスタンス作成時に指定します。

https://www.php.net/manual/ja/class.datetimezone.php

use DateTimeZone;

$tz = new DateTimeZone("Asia/Tokyo");

Carbonではこのタイムゾーンのインスタンスを使って、UTCの時間を指定のタイムゾーンの時間に換算します。

Carbon::now($tz);

直接、タイムゾーンの定数の指定も可能です。

Carbon::now("Asia/Tokyo");

OpeningHoursも同様にタイムゾーンの指定が可能です。

OpeningHours::create($dates, $tz);

Livewireのコンポーネントにタイムゾーンを

前回のコードをもとにタイムゾーンを取り入れました。以下で$this->tzの箇所を見てください。

app/livewire/Calenar.php

namespace App\Livewire;

use DateTimeZone;
use Carbon\Carbon;
use Yasumi\Yasumi;
use Livewire\Component;
use Livewire\Attributes\Url;
use Spatie\OpeningHours\OpeningHours;

class Calendar extends Component
{
class Calendar extends Component
{
    #[Url]
    public int $year;
    #[Url]
    public int $month;
    public $calendar = [];

    const TZ = 'Asia/Tokyo';
    private DateTimeZone $tz;//プロパティではないので、privateで宣言

    public function boot()
    {
        $this->tz = new DateTimeZone(self::TZ);
    }

    public function mount()
    {
        $this->year ??= Carbon::now($this->tz)->year;
        $this->month ??= Carbon::now($this->tz)->month;
    }

    public function previousMonth(): void
    {
        $this->month--;
        if ($this->month < 1) {
            $this->month = 12;
            $this->year--;
        }
    }

    public function nextMonth(): void
    {
        $this->month++;
        if ($this->month > 12) {
            $this->month = 1;
            $this->year++;
        }
    }

    public function render(): \Illuminate\View\View
    {
        $openingHours = $this->openingHours();

        $this->generateCalendar($openingHours);

        return view('livewire.calendar');
    }

    // アクションではないのでprivateとする
    private function openingHours(): OpeningHours　
    {
        $yasumi = Yasumi::create('Japan', $this->year, 'ja_JP');
        $holidays = collect($yasumi->getHolidayDates())
            ->mapWithKeys(function ($date) { return [$date => []];})
            ->all();

        $dates = [
            'monday'     => ['09:00-12:00', '13:00-18:00'],
            'tuesday'    => ['09:00-12:00', '13:00-18:00'],
            'wednesday'  => ['09:00-12:00'],
            'thursday'   => ['09:00-12:00', '13:00-18:00'],
            'friday'     => ['09:00-12:00', '13:00-20:00'],
            'saturday'   => ['09:00-12:00', '13:00-16:00'],
            'sunday'     => [],
            'exceptions' => $holidays,
        ];

        return OpeningHours::create($dates, $this->tz);
    }

　　// アクションではないのでprivateとする
    private function generateCalendar(OpeningHours $openingHours): void
    {
        $startOfMonth = Carbon::createFromDate($this->year, $this->month, 1, $this->tz);
        $endOfMonth = $startOfMonth->copy()->endOfMonth();
        $startDayOfWeek = $startOfMonth->dayOfWeek;
        $totalDays = $endOfMonth->day;

        $this->calendar = [];
        $week = [];

        for ($i = 0; $i < $startDayOfWeek; $i++) {
            $week[] = null;
        }

        $today = Carbon::today();

        for ($day = 1; $day <= $totalDays; $day++) {
            $date = Carbon::createFromDate($this->year, $this->month, $day, $this->tz);
            $dayInfo = [
                'day' => $day,
                'isHoliday' => ! $openingHours->isOpenOn($date->toDateString()),
            ];

            $dayInfo['hours'] = [];

            if ($date->greaterThanOrEqualTo($today)) {
                $hours = $openingHours->forDate($date->toDateTime());

                foreach ($hours as $hour) {
                    $dayInfo['hours'][]= $hour->format();
                }
            }

            $week[] = $dayInfo;

            if (count($week) == 7) {
                $this->calendar[] = $week;
                $week = [];
            }
        }

        if (count($week) > 0) {
            while (count($week) < 7) {
                $week[] = null;
            }
            $this->calendar[] = $week;
        }
    }
}

上のコードでタイムゾーンの対応だけでなく、以下のような前回のコードのリファクターもあるので注意してください。

プロパティの$yearと$monthの宣言の上の行に、#[Url]のアトリビュートが使われています。これは、ブラウザのUrlのパラメータを反映させるためです（後に説明します）。
タイムゾーンの初期化は、mount()ではなくboot()で行っています。これは、mount()はLivewireのコンポーネントを含む画面がロードされるときに１回だけコールされますが、boot()は、コンポーネントのライフサイクルにおいて毎回コールされるからです（後に説明します）。
前回のコードでは、openHours()やgenerateCalendar()の関数の定義は、publicでしたが上のコードではprivateとしています。Livewireのコンポーネントのpublicの関数（例えば、previousMonth()）はアクションとしてクライアントからのアクセスが可能となるからです。

URLパラメータ

上のコードで、馴染みのないアトリビュートが登場しました。以下の#[Url]の部分です。

...
class Calendar extends Component
{
    #[Url]
    public int $year;
    #[Url]
    public int $month;
...

これは、php8から導入されたアトリビュートといわれるもので、Livewireではそのアトリビュートの次の行で宣言されている変数($yearや$month)のUrlにおけるパラメータを自動的に取り込むことを指示します。

例えば、

http://127.0.0.1:8001/calendar?month=1&year=2025

がブラウザのUrlとすると、コンポーネントの$yearと$monthのプロパティは、2025と1にそれぞれ初期化され、2025年の1月のカレンダーを表示してくれます。つまり、Urlにパラメータをつけることで欲しいの月のカレンダーを表示させることができるのです。便利ですね。

http://127.0.0.:8001/calendar

とパラメータがないなら、それらの変数は今日の年と月にmount()で初期化されます。

Livewireのライフサイクル

タイムゾーンの情報を保つ$tzの変数は、上のコードではmount()でなくboot()で初期化を行いましたが、どうしてそうなのでしょう。それには、コンポーネントで定義されている関数がコールされる順番の理解が必要です。

まず、ブラウザにおいて最初にカレンダーを表示したときは、以下の順番でコールされます。

boot() → mount() → render()

しかし、そのカレンダーにおいて、「次」のボタンを押して次の月へ移動するとき、つまりリアクティブのリクエストとなるときは、

boot() → nextMonth() → render()

の順番のコールとなり、mount()はコールされません。mount()で$tzを初期化してたら、render()でコールされるときにopeningHours()内で未初期化の変数のアクセスエラーとなります。

カレンダー（３）休日と営業時間の表示

Tue, 29 Oct 2024 11:47:49 +0900

Livewireを使用してカレンダーをリアクティブにしたところで、次はある店舗のカレンダーと見立てて休日と営業時間の表示をします。２つパッケージを使います。１つは、Laravelのパッケージをたくさん提供することで有名なspatieのopening-hoursのパッケージ、もう１つはいろいろな国の祭日のデータを提供するパッケージyasumiです。

欲しいもの

まず、完成品のカレンダーはこんなものです。

この店舗のカレンダーでは休日がピンクの背景色となっています。店舗は日曜日が定休日で祭日も休みとなります。さらに、このカレンダーを作成した当日を10/25としてそれ以降の営業日においての営業時間を表示しています。

opening-hours：営業時間

営業時間のデータを扱うにはこのパッケージが最適です。 https://github.com/spatie/opening-hours

このパッケージでは以下のように、曜日ごとの営業時間の配列を渡してOpeningHoursのインスタンスを作成します。

use Spatie\OpeningHours\OpeningHours;

$openingHours = OpeningHours::create([
    'monday'     => ['09:00-12:00', '13:00-18:00'],
    'tuesday'    => ['09:00-12:00', '13:00-18:00'],
    'wednesday'  => ['09:00-12:00'],
    'thursday'   => ['09:00-12:00', '13:00-18:00'],
    'friday'     => ['09:00-12:00', '13:00-20:00'],
    'saturday'   => ['09:00-12:00', '13:00-16:00'],
    'sunday'     => [],
    'exceptions' => [
        '2024-11-11' => ['09:00-12:00'],
        '2024-12-25' => [],
        '01-01'      => [],                // 毎年の１月１日は休み
        '12-25'      => ['09:00-12:00'],   // 毎年の１２月２５日は午前中だけ
    ],
]);

上では、

毎週、月、火、木、金、土が同じ営業時間で、水曜日が朝だけの定期的な営業時間です。日曜は、空の配列ということで休みです
非定期は、exceptionsの配列に入れます。2024-11-11のように特定な日にちで指定できますし、01-01のように毎年繰り返す日にちの営業時間も指定が可能です

さて、この営業時間を含むインスタンスをこしらえると、それに対していろいろなことを問うことが可能となります。

例えば、

月曜日は開いている？

$openingHours->isOpenOn('monday');
true

日曜日は開いている？

$openingHours->isOpenOn('sunday');
false

10/30日の19:00は開いている？

$openingHours->isOpenAt(new DateTime('2024-10-30 19:00:00'));
false

クリスマスの日は開いている？

$openingHours->isOpenOn('2024-12-25');
false

などなど、もっといろいろな関数があります。

そしてもちろん、特定な日を指定して、その日の営業時間のデータの取得も可能です。

$openHours = $openingHours->forDate(new DateTime('2024-10-25'));

$hours = [];
foreach($openHours as $hour) {
    $hours[] = $hour->format();
}
print_r($hours);

Array
(
    [0] => 09:00-12:00
    [1] => 13:00-20:00
)

これが先のカレンダーで必要とされる関数となります。

注意することは１つ、このopening-hoursで使用される関数に渡す日付は皆、馴染みのCarbonではなくphpのDateTimeであることです。もちろん、CarbonもDateTimeのWrapperのようなもので、

Carbon\Carbon::create("2025-10-25")->toDateTime();

DateTime @1761350400 {#3156
    date: 2025-10-25 00:00:00.0 UTC (+00:00),
}

とDateTimeに簡単に変換が可能です。

yasumi：祭日

祭日は国のよって違いますので、以下のパッケージを使います。

https://github.com/azuyalabs/yasumi

yasumiはもちろん日本語の「休み」からの由来です。

早速、今年の日本の祭日を出してみましょう！

use Yasumi\Yasumi;

// 国名と年を渡すだけ
$yasumi = Yasumi::create("Japan", "2024");

$holidays = $yasumi->getHolidayDates();

print_r($holidays);

Array
(
    [newYearsDay] => 2024-01-01
    [comingOfAgeDay] => 2024-01-08
    [nationalFoundationDay] => 2024-02-11
    [substituteHoliday:nationalFoundationDay] => 2024-02-12
    [emperorsBirthday] => 2024-02-23
    [vernalEquinoxDay] => 2024-03-20
    [showaDay] => 2024-04-29
    [constitutionMemorialDay] => 2024-05-03
    [greeneryDay] => 2024-05-04
    [childrensDay] => 2024-05-05
    [substituteHoliday:childrensDay] => 2024-05-06
    [marineDay] => 2024-07-15
    [mountainDay] => 2024-08-11
    [substituteHoliday:mountainDay] => 2024-08-12
    [respectfortheAgedDay] => 2024-09-16
    [autumnalEquinoxDay] => 2024-09-22
    [substituteHoliday:autumnalEquinoxDay] => 2024-09-23
    [sportsDay] => 2024-10-14
    [cultureDay] => 2024-11-03
    [substituteHoliday:cultureDay] => 2024-11-04
    [laborThanksgivingDay] => 2024-11-23
)

国名と年を渡すだけで祭日のデータ得られます。このデータを、先のopeningHoursのexceptionsに含んだら、店舗の休日となりますね。

店舗のカレンダー

ということで、これら２つのパッケージを使い以下のLivewireのコンポーネントとなります。

app/Livewire/Calendar.php

namespace App\Livewire;

use Carbon\Carbon;
use Yasumi\Yasumi;
use Livewire\Component;
use Spatie\OpeningHours\OpeningHours;

class Calendar extends Component
{
    public int $year;
    public int $month;
    public $calendar = [];

    public function mount()
    {
        $this->year ??= Carbon::now()->year;
        $this->month ??= Carbon::now()->month;
    }

    public function generateCalendar(OpeningHours $openingHours): void
    {
        $startOfMonth = Carbon::createFromDate($this->year, $this->month, 1);
        $endOfMonth = $startOfMonth->copy()->endOfMonth();
        $startDayOfWeek = $startOfMonth->dayOfWeek;
        $totalDays = $endOfMonth->day;

        $this->calendar = [];
        $week = [];

        for ($i = 0; $i < $startDayOfWeek; $i++) {
            $week[] = null;
        }

        $today = Carbon::today();

        for ($day = 1; $day <= $totalDays; $day++) {
            $date = Carbon::createFromDate($this->year, $this->month, $day);
            $dayInfo = [
                'day' => $day,
                'isHoliday' => ! $openingHours->isOpenOn($date->toDateString()),
            ];

            $dayInfo['hours'] = [];

            if ($date->greaterThanOrEqualTo($today)) {
                $hours = $openingHours->forDate($date->toDateTime());

                foreach ($hours as $hour) {
                    $dayInfo['hours'][]= $hour->format();
                }
            }

            $week[] = $dayInfo;

            if (count($week) == 7) {
                $this->calendar[] = $week;
                $week = [];
            }
        }

        if (count($week) > 0) {
            while (count($week) < 7) {
                $week[] = null;
            }
            $this->calendar[] = $week;
        }
    }

    public function previousMonth(): void
    {
        $this->month--;
        if ($this->month < 1) {
            $this->month = 12;
            $this->year--;
        }
    }

    public function nextMonth(): void
    {
        $this->month++;
        if ($this->month > 12) {
            $this->month = 1;
            $this->year++;
        }
    }

    public function openingHours(): OpeningHours
    {
        $yasumi = Yasumi::create('Japan', $this->year);

        // 以下で祭日を取得して、['2024-01-01' => [], '2024-01-08' => [] ...]の配列に変換
        $holidays = collect($yasumi->getHolidayDates())
            ->mapWithKeys(function ($date) { return [$date => []];})
            ->all();

        $dates = [
            'monday'     => ['09:00-12:00', '13:00-18:00'],
            'tuesday'    => ['09:00-12:00', '13:00-18:00'],
            'wednesday'  => ['09:00-12:00'],
            'thursday'   => ['09:00-12:00', '13:00-18:00'],
            'friday'     => ['09:00-12:00', '13:00-20:00'],
            'saturday'   => ['09:00-12:00', '13:00-16:00'],
            'sunday'     => [],
            'exceptions' => $holidays,
        ];

        return OpeningHours::create($dates);
    }


    public function render(): \Illuminate\View\View
    {
        $openingHours = $this->openingHours();

        $this->generateCalendar($openingHours);

        return view('livewire.calendar');
    }
}

コンポーネントのブレードは、以下となります。

<div class="container mx-auto p-4">
    <h1 class="text-2xl font-bold mb-4 text-center">{{ $year }}年{{ $month }}月</h1>
    <div class="flex justify-between mb-4">
        <button wire:click="previousMonth" class="bg-blue-500 text-white px-4 py-2 rounded">前</button>
        <button wire:click="nextMonth" class="bg-blue-500 text-white px-4 py-2 rounded">次</button>
    </div>
    <table class="min-w-full bg-white border border-gray-200">
        <thead>
            <tr>
                <th class="py-2 px-4 border border-gray-200 bg-gray-100">日</th>
                <th class="py-2 px-4 border border-gray-200 bg-gray-100">月</th>
                <th class="py-2 px-4 border border-gray-200 bg-gray-100">火</th>
                <th class="py-2 px-4 border border-gray-200 bg-gray-100">水</th>
                <th class="py-2 px-4 border border-gray-200 bg-gray-100">木</th>
                <th class="py-2 px-4 border border-gray-200 bg-gray-100">金</th>
                <th class="py-2 px-4 border border-gray-200 bg-gray-100">土</th>
            </tr>
        </thead>
        <tbody>
            @foreach ($calendar as $week)
                <tr>
                    @foreach ($week as $day)
                        @if (is_null($day))
                            <td class="py-2 px-4 border border-gray-200"></td>
                        @else
                            <td class="py-2 px-4 border border-gray-200 align-top {{ $day['isHoliday'] ? 'bg-red-100' : '' }}">
                                {{ $day['day'] }}

                                <div class="text-sm text-blue-500">
                                    {!! implode('<br>', $day['hours']) !!}
                                </div>
                            </td>
                        @endif
                    @endforeach
                </tr>
            @endforeach
        </tbody>
    </table>
</div>

もちろん、以下の作業を忘れずに。

$ composer require spatie/opening-hours
$ composer require azuyalabs/yasumi

カレンダー（２）Livewireを使いリアクティブとする

Sun, 20 Oct 2024 11:24:17 +0900

AI(Copilot)でコードを作成してカレンダーを表示できましたが、今度は今月の月間カレンダーだけなく前月と翌月のボタンを追加してクリックしたら表示をリアクティブに変更できるようにします。

Livewireに変換

前回で作成したカレンダー生成の関数を用いることになりますが、今回もCopilotを使って開発します。

さあ、働いてもらいましょう！

> Laravel Livewireを用いて、先月と翌月を表示できるようにしてください

この結果としてLivewireのコンポーネント、それが使用するブレード、そのコンポーネントを含むブレード、とルートの定義が出力されるのですが、残念なことにこれがLivewireの最新のバージョン３ではなく、バージョン２の出力なのです。

おかしいと思い、問いかけます。

> どのバージョンのLivewireを知っていますか？

私はLivewireの最新バージョンであるLivewire 3を知っています。Livewire 3は、リアクティブなUIを構築するための最新の機能と改善を提供しています。

そうなら、

> そうなら、Livewire3を使って書き直してください

とプッシュ。しかし残念なことに出力される結果は先ほどと同じとなりました。

どうやらLivewireのバージョン３の知識はないみたいです。

ということで、Copilotで出力されたコードと私のLivewireの学習、つまり人間とのコラボにより以下のコード生成となりました。

コンポーネントの作成

最新のバージョンのLaravelでプロジェクトを作成して、以下で最新（バージョン３ですよ）のLivewireのパッケージをインストールします。

$ composer require livewire/livewire

以下でコンポーネントを作成します。

$ php artisan make:livewire Calendar

作成されるファイルは２つあります。

new file:   app/Livewire/Calendar.php
new file:   resources/views/livewire/calendar.blade.php

まず、Calendar.phpを編集します。ここではCopilotで出力されたコードを入れますが、注意するのは、namespaceがバージョン３のLivewireでは、App\Http\LivewireからApp\Livewireに変わっています。

app/Livewie/Calendar.php

namespace App\Livewire;

use Livewire\Component;
use Carbon\Carbon;

class Calendar extends Component
{
    public $year;
    public $month;
    public $calendar = [];

    public function mount($year = null, $month = null)
    {
        $this->year = $year ?? Carbon::now()->year;
        $this->month = $month ?? Carbon::now()->month;
        $this->generateCalendar();
    }

    public function generateCalendar()
    {
        $startOfMonth = Carbon::createFromDate($this->year, $this->month, 1);
        $endOfMonth = $startOfMonth->copy()->endOfMonth();
        $startDayOfWeek = $startOfMonth->dayOfWeek;
        $totalDays = $endOfMonth->day;

        $this->calendar = [];
        $week = [];

        for ($i = 0; $i < $startDayOfWeek; $i++) {
            $week[] = null;
        }

        for ($day = 1; $day <= $totalDays; $day++) {<strong>
            $week[] = $day;

            if (count($week) == 7) {
                $this->calendar[] = $week;
                $week = [];
            }
        }

        if (count($week) > 0) {
            while (count($week) < 7) {
                $week[] = null;
            }
            $this->calendar[] = $week;
        }
    }

    public function previousMonth()
    {
        $this->month--;
        if ($this->month < 1) {
            $this->month = 12;
            $this->year--;
        }
        $this->generateCalendar();
    }

    public function nextMonth()
    {
        $this->month++;
        if ($this->month > 12) {
            $this->month = 1;
            $this->year++;
        }
        $this->generateCalendar();
    }

    public function render()
    {
        return view('livewire.calendar');
    }
}

コンポーネントに含まれる、generateCalendar()は前回と似ていますが、このクラスのプロパティの$month, $yearにより返す値が変わるようになっています。また、前月を表示するpreviousMonth()と次月を表示するnextMonth()のメソッドが追加されています。

今度はブレードですが、これもCopilotの出力ををもとに英語から日本語に私が編集しました。wire:clickにおいて先ほど追加関数名が指定されています。これらはLivewireのためのコードで、これによりカレンダーで表示する月を変えることができます。

/resources/views/livewire/calendar.blade.php

<div>
    <table>
        <caption>
            <button wire:click="previousMonth">前</button>
            <strong>{{ $year }}年{{ $month }}月</strong>
            <button wire:click="nextMonth">次</button>
        </caption>
        <thead>
            <tr>
                <th>日</th>
                <th>月</th>
                <th>火</th>
                <th>水</th>
                <th>木</th>
                <th>金</th>
                <th>土</th>
            </tr>
        </thead>
        <tbody>
            @foreach ($calendar as $week)
                <tr>
                    @foreach ($week as $day)
                        @if (is_null($day))
                            <td></td>
                        @else
                            <td>{{ $day }}</td>
                        @endif
                    @endforeach
                </tr>
            @endforeach
        </tbody>
    </table>
</div>

ルートの定義は以下となりますが、これはコンポーネントを全画面として表示する設定です。

routes/web.php

use App\Livewire\Calendar;
use Illuminate\Support\Facades\Route;

Route::get('/calendar', Calendar::class);

そして、この全画面表示のためにレイアウトのブレードが必要です。

resources/views/components/layouts/app.blade.php

<!DOCTYPE html>
<html lang="{{ str_replace('_', '-', app()->getLocale()) }}">
    <head>
        <meta charset="utf-8">
        <meta name="viewport" content="width=device-width, initial-scale=1.0">
        <title>{{ $title ?? 'Page Title' }}</title>
    </head>
    <body>
        {{ $slot }}
    </body>
</html>

これで完了です。

う～ん。ちょっと醜いですね。Copilotに少し恰好良くしてもらいましょう。

> コンポーネントのブレードをTailwind cssを利用してベターなルックにしてください

以下のようにブレードは変わります。

/resources/views/livewire/calendar.blade.php

<div class="container mx-auto p-4">
    <h1 class="text-2xl font-bold mb-4 text-center">{{ $year }}年{{ $month }}月</h1>
    <div class="flex justify-between mb-4">
        <button wire:click="previousMonth" class="bg-blue-500 text-white px-4 py-2 rounded">前</button>
        <button wire:click="nextMonth" class="bg-blue-500 text-white px-4 py-2 rounded">次</button>
    </div>
    <table class="min-w-full bg-white border border-gray-200">
        <thead>
            <tr>
                <th class="py-2 px-4 border border-gray-200 bg-gray-100">日</th>
                <th class="py-2 px-4 border border-gray-200 bg-gray-100">月</th>
                <th class="py-2 px-4 border border-gray-200 bg-gray-100">火</th>
                <th class="py-2 px-4 border border-gray-200 bg-gray-100">水</th>
                <th class="py-2 px-4 border border-gray-200 bg-gray-100">木</th>
                <th class="py-2 px-4 border border-gray-200 bg-gray-100">金</th>
                <th class="py-2 px-4 border border-gray-200 bg-gray-100">土</th>
            </tr>
        </thead>
        <tbody>
            @foreach ($calendar as $week)
                <tr>
                    @foreach ($week as $day)
                        @if (is_null($day))
                            <td class="py-2 px-4 border border-gray-200"></td>
                        @else
                            <td class="py-2 px-4 border border-gray-200">
                                {{ $day }}
                            </td>
                        @endif
                    @endforeach
                </tr>
            @endforeach
        </tbody>
    </table>
</div>

レイアウトの方は、以下となります。

resources/views/components/layouts/app.blade.php

<!DOCTYPE html>
<html lang="{{ str_replace('_', '-', app()->getLocale()) }}">
    <head>
        <meta charset="utf-8">
        <meta name="viewport" content="width=device-width, initial-scale=1.0">
        <title>{{ $title ?? 'Page Title' }}</title>
        <link href="https://cdn.jsdelivr.net/npm/tailwindcss@2.2.19/dist/tailwind.min.css" rel="stylesheet">

    </head>
    <body class="bg-gray-100">
        <div class="container mx-auto p-4">
            {{ $slot }}
        </div>
    </body>
</html>

以下となりました。レスポンシブ対応ともなっています。

以上、Copilotと私のコラボの作品です。CopilotのLivewireの知識が最新でないのは残念ですが、知ったふりをしては欲しくないですね。

カレンダー（１）AIで生成

Tue, 15 Oct 2024 11:24:06 +0900

カレンダーに関連するプロジェクトは、そのダイナミックなデータの性質上とても面白いです。また、店舗休日を表示するための月間カレンダーの生成とか、場所や部屋や物の予約のためのカレンダーのアプリとか実用的なものが多いです。私のお客さんのサイトでもチェックアウト画面でお客さんが届け日を指定するために月間のカレンダーが表示されます。カレンダーを題材にLaravelでどんなことが簡単にできるかをいくつかの投稿に分けて紹介します。

欲しいもの

簡単なところからということで、まず今月のカレンダーの表示から始めます。これを書いているのは2024年の10月なので、以下のような表示です。

Copilotでカレンダーの生成

私が生きている間にAIが開発者をヘルプできる時代になるとはまったく信じられなかったことですが、私も時代の流れに逆らえず、開発者のツールとしてマイクロソフトのCopilotを常時使用しています。Copilotは現時点ではChatGPT4を使用しており、VSCODEエディターの中からAIとの対話が可能です。

まず、以下の質問をCopilotに問います。

> 今月の月間のカレンダーを週と日にちの配列として生成するphp関数をCarbonのパッケージを使用して作成してください

以下のコードを作成してくれました。

以下は、Carbonパッケージを使用して今月の月間カレンダーを週と日にちの配列として生成するPHP関数です。

use Carbon\Carbon;

function getMonthlyCalendar()
{
    // 現在の月と年を取得
    $now = Carbon::now();
    $startOfMonth = $now->copy()->startOfMonth();
    $endOfMonth = $now->copy()->endOfMonth();

    // 月の最初の日の曜日を取得
    $startDayOfWeek = $startOfMonth->dayOfWeek;
    $totalDays = $endOfMonth->day;

    // カレンダーを作成する配列
    $calendar = [];
    $week = [];

    // 最初の週の空の日を追加
    for ($i = 0; $i < $startDayOfWeek; $i++) {
        $week[] = null; // 空のセル
    }

    // 日付を週に追加
    for ($day = 1; $day <= $totalDays; $day++) {
        $week[] = $day;

        // 7日ごとに新しい週を作成
        if (count($week) == 7) {
            $calendar[] = $week;
            $week = [];
        }
    }

    // 最後の週を追加
    if (count($week) > 0) {
        while (count($week) < 7) {
            $week[] = null; // 空のセル
        }
        $calendar[] = $week;
    }

    return $calendar;
}

説明のコメントつきでわかりやすいです。月間カレンダーはたいてい7x5あるいは7x4のグリッドですが、先月となる日や翌月となる日を非表示とする配慮が必要です。この関数が返すデータを見せてもらいましょう。

> 今月は2024年10月として、上の関数が返す配列を見せてください

[
    [null, null, 1, 2, 3, 4, 5], // 1週目
    [6, 7, 8, 9, 10, 11, 12],    // 2週目
    [13, 14, 15, 16, 17, 18, 19], // 3週目
    [20, 21, 22, 23, 24, 25, 26], // 4週目
    [27, 28, 29, 30, 31, null, null] // 5週目
]

今月というのを説明しないと2023年の10月となってしまいますので注意を。期待していた週と日の２次元の配列です。先月や翌月となっているところは、皆nullとなっています。

ここまでできるなら、後全部やってもらいましょう！

> それを利用したLaravelのコントローラとブレードを作成してください

以下はCopilotからの出力です。

以下は、提供されたコードを利用してLaravelのコントローラとブレードテンプレートを作成する方法です。

コントローラの作成
まず、CalendarControllerを完成させます。

app/Http/Controllers/CalendarController.php

namespace App\Http\Controllers;

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

class CalendarController extends Controller
{
    public function show()
    {
        $calendar = $this->getMonthlyCalendar();

        return view('calendar', compact('calendar'));
    }

    function getMonthlyCalendar()
    {
        // 現在の月と年を取得
        $now = Carbon::now();
        $startOfMonth = $now->copy()->startOfMonth();
        $endOfMonth = $now->copy()->endOfMonth();

        // 月の最初の日の曜日を取得
        $startDayOfWeek = $startOfMonth->dayOfWeek;
        $totalDays = $endOfMonth->day;

        // カレンダーを作成する配列
        $calendar = [];
        $week = [];

        // 最初の週の空の日を追加
        for ($i = 0; $i < $startDayOfWeek; $i++) {
            $week[] = null; // 空のセル
        }

        // 日付を週に追加
        for ($day = 1; $day <= $totalDays; $day++) {
            $week[] = $day;

            // 7日ごとに新しい週を作成
            if (count($week) == 7) {
                $calendar[] = $week;
                $week = [];
            }
        }

        // 最後の週を追加
        if (count($week) > 0) {
            // 残りの空の日を追加
            for ($i = count($week); $i < 7; $i++) {
                $week[] = null;
            }
            $calendar[] = $week;
        }

        return $calendar;
    }
}

ルートの定義
次に、ルートを定義します。

routes/web.php

use App\Http\Controllers\CalendarController;

Route::get('/calendar', [CalendarController::class, 'show']);

ブレードテンプレートの作成
最後に、カレンダーを表示するためのブレードテンプレートを作成します。

resources/views/calendar.blade.php

<!DOCTYPE html>
<html>
<head>
    <title>Calendar</title>
    <img src="data:image/gif;base64,R0lGODlhAQABAIAAAAAAAP///yH5BAEAAAAALAAAAAABAAEAAAIBRAA7" data-wp-preserve="%3Cstyle%3E%0A%20%20%20%20%20%20%20%20table%20%7B%0A%20%20%20%20%20%20%20%20%20%20%20%20width%3A%20100%25%3B%0A%20%20%20%20%20%20%20%20%20%20%20%20border-collapse%3A%20collapse%3B%0A%20%20%20%20%20%20%20%20%7D%0A%20%20%20%20%20%20%20%20th%2C%20td%20%7B%0A%20%20%20%20%20%20%20%20%20%20%20%20border%3A%201px%20solid%20black%3B%0A%20%20%20%20%20%20%20%20%20%20%20%20text-align%3A%20center%3B%0A%20%20%20%20%20%20%20%20%20%20%20%20padding%3A%2010px%3B%0A%20%20%20%20%20%20%20%20%7D%0A%20%20%20%20%20%20%20%20th%20%7B%0A%20%20%20%20%20%20%20%20%20%20%20%20background-color%3A%20%23f2f2f2%3B%0A%20%20%20%20%20%20%20%20%7D%0A%20%20%20%20%3C%2Fstyle%3E" data-mce-resize="false" data-mce-placeholder="1" class="mce-object" width="20" height="20" alt="&lt;style&gt;" title="&lt;style&gt;" />
</head>
<body>
    <h1>Calendar for {{ \Carbon\Carbon::now()->format('F Y') }}</h1>
    <table>
        <tr>
            <th>Sunday</th>
            <th>Monday</th>
            <th>Tuesday</th>
            <th>Wednesday</th>
            <th>Thursday</th>
            <th>Friday</th>
            <th>Saturday</th>
        </tr>
        @foreach ($calendar as $week)
            <tr>
                @foreach ($week as $day)
                    <td>{{ $day ?? '' }}</td>
                @endforeach
            </tr>
        @endforeach
    </table>
</body>
</html>

曜日は英語ですが、あっという間にできてしまいました。

次の投稿では、Livewireを使ってカレンダーをリアクティブにします。

Livewireを使ってポーリング

Wed, 18 Sep 2024 12:47:18 +0900

ウェブソケットと同様にリアルタイム（まがい）で画面の一部を更新する方法に、ポーリングがあります。ウェブソケットではサーバーから更新情報をブラウザ（クライアント）へプッシュするのに対して、ポーリングは逆にブラウザからサーバーに情報を一定の時間で取得（ポーリング）しに行きます。それゆえに、PusherやReverbのようなウェブソケットサーバーは必要でなく簡単なセットアップとなります。このポーリングをとても人気があるLivewireを使用してプログラムしてみます。

欲しいもの

実用的なものでないですが、とても簡単なデモとします。

上の画面のように、ログイン画面が表示されたらログインできる残りの秒数を１０秒からカウントダウンします。１０秒過ぎたからと言ってログインが無効になるわけではありません。単に残りの秒数を全ページ更新せずに表示するだけです。

通常なら単にjavascriptでsetTimeout()あるいはsetInterval()を駆使して実現できることを、javascriptを一切使用せずにサーバーから残り秒数を取得して表示します。

Livewireのインストール

まず、Livewireのパッケージのインストール。

$ composer require livewire/livewire

今回はこれだけ。設定は何も要りません。

コンポーネントの作成

次にタイマーのコンポーネントを作成します。artisanでモデルを作成するようにコンポーネントを作成してくれます。

$ php artisan make:livewire Timer

これで作成されるファイルは２つあります。１つはコンポーネントでもう１つはそれに使用されるブレードです。

        new file:   app/Livewire/Timer.php
        new file:   resources/views/livewire/timer.blade.php

コンポーネントのコードを以下のように編集します。

app/Livewire/Timer.php

namespace App\Livewire;

use Livewire\Component;

class Timer extends Component
{
    public $remaining = 11;

    public function render()
    {
        $this->remaining--;

        return view('livewire.timer', [
            'remaining' => $this->remaining,
        ]);
    }
}

$remainingの変数が残り秒数の値となりますが、最初に11秒と設定しておき、そこから１を引いた10秒から表示です。正確に行うには開始時点での日時をキープしてrender()がコールされるたびにその時点での日時から経過秒数を計算ですが、ここは１秒おきに関数がコールされるとしてシンプルにします。ちなみに、Livewireではサーバーでの複数のリクエストを通して同じオブジェクトにアクセスが可能で、$remainingの値は毎回初期化されずステートをキープします。

次はコンポーネントのブレードの編集です。先のコンポーネントのクラス名と関連させてtimer.blade.phpとなっています。

resources/views/livewire/timer.blade.php

   <div wire:poll.1s>
        残りの秒数：{{ $remaining }}
    </div>

上のコードで大事なのは、wire:poll.1sの部分です。これがポーリングを指示しています。.1sは、１秒ごとにポーリングです。これがないとデフォルトは、2.5秒でポーリングとなります。

さて、このコンポーネントをログインのブレードに入れます。見てのとおり<livewire:timer />だけとシンプルです。

resources/views/auth/login.blade.php

<x-guest-layout>
    <!-- Session Status -->
    <x-auth-session-status class="mb-4" :status="session('status')" />

    <form method="POST" action="{{ route('login') }}">
        @csrf

        <livewire:timer /> <!-- ここでコンポーネントを使用 -->

        <!-- Email Address -->
...

この時点で不思議に思うのは、Livewireのおかげでjavascriptのコードは一切も書かないのですが、どこかでLivewireのライブラリ（javascript）をコールされているはずですよね。今のところブレードには前もって含まれてはいません。しかし、レンダーされた画面のHTMLソースを見ると以下のように、自動でスクリプトがインジェクトされています。

....
    <!-- Livewire Scripts -->
<script src="/livewire/livewire.js?id=cc800bf4"   data-csrf="ys60l3TQzop1efcgNKZjtUlZ4mX9WxZzlpiVjoUN" data-update-uri="/livewire/update" data-navigate-once="true"></script>
</body>
</html>

実際にログイン画面を表示してブラウザーのインスペクターでポーリングが行われているが見てみましょう。

たくさんPOSTのリクエストが実行されています。リクエストの詳細では、 http://127.0.0.1:8000/livewire/update にアクセスしているのが分かります。

このルートも手動で設定してはいないのに自動設定されています。チェックしてみましょう。

$ php artisan route:list | grep livewire
  GET|HEAD  livewire/livewire.js ......................... Livewire\Mechanisms › FrontendAssets@returnJavaScriptAsFile
  GET|HEAD  livewire/livewire.min.js.map ................................... Livewire\Mechanisms › FrontendAssets@maps
  GET|HEAD  livewire/preview-file/{filename} livewire.preview-file › Livewire\Features › FilePreviewController@handle
  POST      livewire/update ...................... livewire.update › Livewire\Mechanisms › HandleRequests@handleUpdate
  POST      livewire/upload-file .............. livewire.upload-file › Livewire\Features › FileUploadController@handle

livewire関連がいろいろとありますが、先ほどのルートも含まれていました。

タイマーを止める

さて、最後にもう１つやることあります。先ほどのプログラムでは、ほったらかしにすると残りの秒数がマイナスになってしまいます。

残り秒数が０以下となるなら、終了としてポーリングも停止したいです。そうするには、ブレードを編集して、０秒以下となったら、ポーリングの代わりに「終了しました！」の表示を条件文と使って入れ替えます。簡単ですね。

resources/views/livewire/timer.blade.php

<div>
    @if ($remaining <= 0)
        <div class="text-red-600 font-bold">終了しました！</div>
    @else
        <div class="font-bold" wire:poll.1s>
            残りの秒数：{{ $remaining }}
        </div>
    @endif
</div>

以下のようになりました。

最後に

Livewireを使うと実に簡単にポーリングができてしまいます、しかし、ポーリングはこのデモでは毎秒サーバーにリクエストするので、ユーザー数が多くなるとサーバーにはかなりな負荷となります。スケールが小さめのプロジェクト向きと思ってください。スケールが大きいプロジェクトではウェブソケットの使用を考えてください。

ウェブソケットに関しては、以下のご参照を。

会員チャットの解説（１）Websocket

Laravel Zero（２）データベースを使う

Wed, 21 Aug 2024 06:45:57 +0900

前回に紹介したLaravel Zeroはとても有用そうです。しかし、データベースの操作を行うことができなければですね。ということで、今回はその機能を追加します。さらに、もちろん私の好きなtinkerも使えるようにします。

データベース機能の追加

前回と同じプロジェクトの続きとして、データベース機能を追加します。前回では、applicationをartisanに改名したことをお忘れずに。

$ php artisan app:install database
Installing database component...
...
Require package via Composer: ✔
Creating a default SQLite database: ✔
Creating migrations folder: ✔
Creating seeders folders and files: ✔
Creating factories folder: ✔
Creating default database configuration: ✔
Updating .gitignore: ✔
...

上の実行により、Laravelでお馴染みのconfig/database.phpも追加されるので、.envに以下を追加します。

.env

...
DB_CONNECTION=mysql
DB_HOST=localhost
DB_DATABASE=zero
DB_USERNAME=root
DB_PASSWORD=password

準備が整ったら、これまたLaravelでお馴染みのEloquentのクエリの実行などが使えます。

use App\User;
use Illuminate\Support\Facades\DB;

$users = User::all(); // Eloquent

$users = DB::table('users')->get(); // Query Builder

Tinker

私には大好きなツールですが、これもデフォルトではLaravel Zeroにはデフォルトで装備されていません。外部パッケージとなっているので、composerでインストールします。

$ composer require intonate/tinker-zero

さらに、config/app.phpを編集して以下の行を追加します。

config/app.php

'providers' => [
    App\Providers\AppServiceProvider::class,
　　Intonate\TinkerZero\TinkerZeroServiceProvider::class, // これを追加！
],

実行してみましょう。こちらも、前回にapplicationをartisanに改名したことをお忘れずに。

$ php artisan tinker
Psy Shell v0.12.4 (PHP 8.2.15 — cli) by Justin Hileman
> use App\User;
> User::count();
> 4

参照

Laravel Zero（１）コマンドの作成

混乱してはいけないLaravelの動的プロパティ - 裏側編

Wed, 15 May 2024 23:27:32 +0900

今回は、Laravelの動的プロパティの裏側を見てみます。つまり、どうしてインスタンスのプロパティがメソッドのコールとなるのか。

マジックメソッド

知って入ればなんのことはないですが、phpではマジックメソッドという関数をクラスで定義すれば、クラスで定義されているメソッドを、インスタンスのプロパティとしてアクセスすることができます。

簡単にマジックメソッドの説明をしましょう。

まずは、Personというクラスを作成します。Modelsのネームスペースに入れてありますが、デモのためにEloquentのModelクラスは継承しません。

app/Models/Person.php

namespace App\Models;

// 以下はModelを継承していないことに注意
class Person
{
    protected array $attributes = [];

    //　プロパティの値を取得
    public function __get(string $key ) : ?mixed
    {
        if (isset($this->attributes[$key])) {
            return $this->attributes[$key];
        }

        return null;
    }

    //　プロパティを設定
    public function __set(string $key, mixed $value)
    {
        $this->attributes[$key] = $value;
    }

    //　すべてのプロパティをリスト
    public function getAttributes(): array
    {
        return $this->attributes;
    }
}

２つの_（アンダースコア）で始まるメソッド名、__get()と__set()がマジックメソッドです。

tinkerで実行すると、以下のようにインスタンスに好きなプロパティ名で値を与えることができます。

> use App\Models\Person;
> $person = new Person;
= App\Models\Person {#5077}

> $person->first_name = 'Joe';
= "Joe"

> $person->last_name = 'Biden';
= "Biden"

裏では、上のクラスの定義の__set()、つまりミューテーターが実行されています。その証拠に、$attributeの中身を見ると、

> $person->getAttributes();
= [
    "first_name" => "Joe",
    "last_name" => "Biden",
  ]

と連想配列に値が入っています。

また、__get()の定義のために、

> $person->first_name;
= "Joe"

> $person->last_name;
= "Biden"

とそれぞれのプロパティの値を取り出すことが可能です。

しかし、$attributesにキーがないプロパティにアクセスすると、

> $person->full_name;
= null

とnullを返します。

プロパティがなかったらメソッドコール

さて、今度はプロパティが存在しないときにメソッドをコールしてみましょう。プロパティがfull_nameならfullName()をコールするように対応してみました。

namespace App\Models;

use Illuminate\Support\Str;

class Person
{
    protected array $attributes = [];

    public function __get(string $key ) : mixed
    {
        if (isset($this->attributes[$key])) {
            return $this->attributes[$key];
        }

        // full_nameがキーなら、fullName()をコール
        if (method_exists($this, Str::camel($key))) {
            return $this->{Str::camel($key)}();
        }

        return null;
    }
    
    ...

    // 新規に定義
    protected function fullName()
    {
        return $this->attributes['first_name'].' '.$this->attributes['last_name'];
    }
}

実行すると、full_nameの動的プロパティの値が返ります。

> $person->full_name;
= "Joe Biden"

もちろん、LaravelのModelのクラスではいろいろなケースがあるので、その動的プロパティのメカニズムはこれよりはるかに複雑ですが、マジックメソッドを使用して対応するのは同じです。

Laravelでのマジックメソッド

さて、Laravelで本当にマジックメソッドが使用されているか確認してみましょう。

まずは、EloquentのModelクラスでは、以下のように、マジックメソッドが定義されています。

vendor/laravel/framework/src/Illuminate/Database/Eloquent/Model.php

namespace Illuminate\Database\Eloquent;

...
abstract class Model implements Arrayable, ArrayAccess, CanBeEscapedWhenCastToString, HasBroadcastChannel, Jsonable, JsonSerializable, QueueableEntity, Stringable, UrlRoutable
{
...
   /**
     * Dynamically retrieve attributes on the model.
     *
     * @param  string  $key
     * @return mixed
     */
    public function __get($key)
    {
        return $this->getAttribute($key);
    }

    /**
     * Dynamically set attributes on the model.
     *
     * @param  string  $key
     * @param  mixed  $value
     * @return void
     */
    public function __set($key, $value)
    {
        $this->setAttribute($key, $value);
    }
...

このコードレベルではすっきりしていますが、興味ある方は奥までコードを辿ってみてください。いろいろなケースの対応がされています。

そして、Collectionでは、HigherOrderCollectionProxyのクラスの中で、マジックメソッドが定義されています。

vendor/laravel/framework/src/Illuminate/Collections/HigherOrderCollectionProxy.php

namespace Illuminate\Support;

/**
 * @mixin \Illuminate\Support\Enumerable
 */
class HigherOrderCollectionProxy
{
...
    /**
     * Proxy accessing an attribute onto the collection items.
     *
     * @param  string  $key
     * @return mixed
     */
    public function __get($key)
    {
        return $this->collection->{$this->method}(function ($value) use ($key) {
            return is_array($value) ? $value[$key] : $value->{$key};
        });
    }

    /**
     * Proxy a method call onto the collection items.
     *
     * @param  string  $method
     * @param  array  $parameters
     * @return mixed
     */
    public function __call($method, $parameters)
    {
        return $this->collection->{$this->method}(function ($value) use ($method, $parameters) {
            return $value->{$method}(...$parameters);
        });
    }
}

他のどのクラスでマジックメソッドが使用されているか、vendor/laravel/のディレクトリで、grepしてみました。いろいろありますね。

framework/src/Illuminate/Routing/Route.php
framework/src/Illuminate/View/InvokableComponentVariable.php
framework/src/Illuminate/Database/Eloquent/Model.php
framework/src/Illuminate/Database/Eloquent/Builder.php
framework/src/Illuminate/Bus/Batch.php
framework/src/Illuminate/Conditionable/HigherOrderWhenProxy.php
framework/src/Illuminate/Auth/GenericUser.php
framework/src/Illuminate/Mail/Events/MessageSent.php
framework/src/Illuminate/Queue/Jobs/DatabaseJobRecord.php
framework/src/Illuminate/Support/ViewErrorBag.php
framework/src/Illuminate/Support/ValidatedInput.php
framework/src/Illuminate/Support/Optional.php
framework/src/Illuminate/Support/Fluent.php
framework/src/Illuminate/Support/Stringable.php
framework/src/Illuminate/Http/Request.php
framework/src/Illuminate/Http/Resources/DelegatesToResource.php
framework/src/Illuminate/Testing/TestResponse.php
framework/src/Illuminate/Testing/TestComponent.php
framework/src/Illuminate/Container/Container.php
framework/src/Illuminate/Collections/HigherOrderCollectionProxy.php
framework/src/Illuminate/Collections/Enumerable.php
framework/src/Illuminate/Collections/Traits/EnumeratesValues.php

参照

混乱してはいけないLaravelの動的プロパティ – Eloquent編混乱してはいけないLaravelの動的プロパティ – Collection編混乱してはいけないLaravelの動的プロパティ – PHP8.2で廃止となった編

混乱してはいけないLaravelの動的プロパティ - Collection編

Tue, 07 May 2024 22:49:37 +0900

動的プロパティは、EloquentだけでなくCollectionにもHigher Order Message（より上級のメッセージ？）という名前で颯爽と登場します。これも最初に見たら、こんなことできるの、という感じです。混乱してはいけません。Eloquentと同様に複雑なことをしないときのコード表現に便利なメソッドの短縮形です。

以下の前回の話も参照してください。混乱してはいけないLaravelの動的プロパティ - Eloquent編

Collectionメソッドを動的プロパティとして扱う

Laravelのマニュアルと似たような例を使います。

ここでは、スポーツ選手のプレイヤーをクラス（Player）とします。クラスにはプロパティとして、名前、人気の投票数、そしてVIPかどうかの３つの項目があります。例としてtinkerで表示されるようにプロパティは皆publicとしています。さらに、投票数が500以上ならVIPを正とする関数も定義されています。

app/Models/Player.php

namespace App\Models;

Class Player
{
    function __construct(
        public string $name,　// 名前
        public int $votes,  // 投票数
        public bool $isVip = false)　// VIP？
    {
        //
    }

    public function markAsVip(): void
    {
        if ($this->votes >= 500) { // 500数以上ならVIPに設定
            $this->isVip = true;
        }
    }
}

まず、２つインスタンスを含むCollectionを作成します。

> use App\Models\Player;

> $players = collect([
    new Player("LeBron James", 500), 
    new Player("Stephen Curry", 400)
]);

= Illuminate\Support\Collection {#5066
    all: [
      App\Models\Player {#5096
        +name: "LeBron James",
        +votes: 500,
        +isVip: false,
      },
      App\Models\Player {#5067
        +name: "Stephen Curry",
        +votes: 400,
        +isVip: false,
      },
    ],
  }

Collectionに含まれるプレイヤーのインスタンスにおいて、人気票に基づいてVIPかどうかを決めるとします。

通常なら、以下のようにCollectionのeach()のメソッドを使い、それぞれのインスタンスにおいてmarkAsVip()をコールバックします。

> $players->each(fn (Player $player) => $player->markAsVip());

= Illuminate\Support\Collection {#5101
    all: [
      App\Models\Player {#5089
        +name: "LeBron James",
        +votes: 500,
        +isVip: true,
      },
      App\Models\Player {#5102
        +name: "Stephen Curry",
        +votes: 400,
        +isVip: false,
      },
    ],
  }

しかし、なんとこれと同じことが、Collectionの動的プロパティとして以下のように短縮して実行も可能なのです。

> $players->each->markAsVip();

= Illuminate\Support\Collection {#5101
    all: [
      App\Models\Player {#5089
        +name: "LeBron James",
        +votes: 500,
        +isVip: true,
      },
      App\Models\Player {#5102
        +name: "Stephen Curry",
        +votes: 400,
        +isVip: false,
      },
    ],
  }

凄いですね。

Collectionの他のメソッドも使えます。VIPだけのプレイヤーを抽出したいとすると、filter()を動的プロパティとします。、

> $players->filter->isVip;
= Illuminate\Support\Collection {#5102
    all: [
      App\Models\Player {#5089
        +name: "LeBron James",
        +votes: 500,
        +isVip: true,
      },
    ],
  }

もう１つ例を見てみましょう。今度は、sum()を使ってプレーヤーの総投票数の計算もできてしまいます。

> $players->sum->votes;
= 900

ちなみに、このような短縮形が使えるのは、Collectionのすべてのメソッドとはいきませんが、以下のメソッドの使用が現在可能です。

average, avg, contains, each, every, filter, first, flatMap, groupBy, keyBy, map, max, min, partition, reject, skipUntil, skipWhile, some, sortBy, sortByDesc, sum, takeUntil, takeWhile, unique

参照

混乱してはいけないLaravelの動的プロパティ – Eloquent編混乱してはいけないLaravelの動的プロパティ – 裏側編混乱してはいけないLaravelの動的プロパティ – PHP8.2で廃止となった編

混乱してはいけないLaravelの動的プロパティ - Eloquent編

Fri, 19 Apr 2024 05:45:38 +0900

LaravelではModelやCollectionやRequestなどのクラスにおいて動的プロパティがコードの短縮形としてよく使われます。しかし、同じクラスでメソッドとして定義したものがいきなりプロパティとして使われるので、私は昔よく混乱したものです。今回はまずEloquent編として代表的な動的プロパティの活用を混乱しないように説明します。

Eloquentのアクセッサー

まず、動的プロパティの例として、DBには対応する項目は存在しないのに、あたかも存在する項目のように振る舞うEloquentのアクセッサーです（ミューテーターも同じですが）。

DBのテーブルにfirst_name（名前）とlast_name（苗字）が存在するとして、姓名（full_name）を返すアクセッサーメソッドを定義します。

namespace App\Models;
 
use Illuminate\Database\Eloquent\Casts\Attribute;
use Illuminate\Database\Eloquent\Model;
 
class User extends Model
{
...
    /**
     * 姓名を返すアクセッサー
     *
     * @return \Illuminate\Database\Eloquent\Casts\Attribute
     */
    protected function fullName(): Attribute
    {
        return Attribute::make(
            get: fn ($value, $attribute) => $attribute['last_name'].' '.$attribute['first_name'],
        );
    }
}

これを使用するときは、動的プロパティとして以下のように使います。

> User::find(1);
[!] Aliasing 'User' to 'App\Models\User' for this Tinker session.
= App\Models\User {#5393
    id: 1,
    created_at: "2024-04-16 03:42:31",
    updated_at: "2024-04-16 03:42:31",
    first_name: "直子",
    last_name: "山田",
  }

> User::find(1)->full_name;
= "山田 直子"

先ほどのアクセッサーのメソッドfullName()をコールして姓名full_nameを動的プロパティとして返します。

ちなみに、fullName()のメソッドはprotectedで宣言されているので直接はコールできません。

> User::find(1)->fullName();
   BadMethodCallException  Call to undefined method App\Models\User::fullName().

EloquentのRelationship

今度は、EloquentのRelationshipの動的プロパティです

典型的なブログを例として、ユーザーとブログの投稿を使います。それぞれのDBテーブルを代表してUserとPostがModelのクラスとなります。そして、Userのクラスでは、それらの１対多の関係を以下のように定義します。

namespace App\Models;
 
use Illuminate\Database\Eloquent\Model;
 
class User extends Model
{
    /**
     * ユーザー１に対して複数のブログの投稿
     */
    public function posts()
    {
        return $this->hasMany(Post::class);
    }
}

この関係を利用して、特定のユーザーのブログのレコードを取得するのは通常以下のようになります。

$user = User::find(1);
$posts = $user->posts()->get(); // Collectionを返す

しかし、動的プロパティを使うと、

$posts = $user->posts;

と短縮形で書くことができます。先の非短縮形と同じ結果となります。便利ですね。

しかし、この短縮形、非短縮形でできることがなんでもできる訳ではありません

例えば、非短縮形のメソッド方式では、

$user->posts()->orderBy('created_at')->get();

とレコードをソートできますが、短縮形の動的プロパティの使用ではエラーとなります。

$user->posts->orderBy('created_at');

BadMethodCallException  Method Illuminate\Database\Eloquent\Collection::orderBy does not exist.

これは、$user->posts()がIlluminate\Database\Eloquent\Relations\HasManyを返すのに、$user->postではIlluminate\Database\Eloquent\Collectionを返すからです。Collectionには、orderBy()というメソッドはないのです。しかし、前者にはあります。

ちなみに後者では、CollectionのメソッドsortBy()を使用すると同じ結果が得られます。

$user->posts->sortBy('created_at');

もう１つ、より混乱しそうな例を挙げてみましょう。

まずは非短縮形から、

$user->posts()->where('title', '=', 'ブログタイトル')->get();

タイトルに特定の条件で絞ったクエリーです。ちなみに、実行されたSQLは、以下となります。

select * from `post` where `user`.`id` = 1 and `user`.`id` is not null and `title` = 'ブログタイトル';

さて、これを短縮形の動的プロパティで書くと、

$user->posts->where('title', '=', 'ブログタイトル');

->get()がないだけの違いですが、これはまったく正規です。返す結果も前者と同じです。where()はCollectionのメソッドにもあるのですね。

実行されたSQLも見てみましょう。

select * from `post` where `user`.`id` = 1 and `user`.`id` is not null;

違いわかりますか？タイトルを制限するwhereの条件文がSQL文にありません。つまり、ユーザーが投稿したレコードをいったん全部取得して、Collectionのwhere()のメソッドでフィルターしているのです。

両者ともに実行結果は同じですが、どこまでがデータベースにより実行されるか、どこからがCollectionのメソッドで実行するかにおいての違いです。この違いでパフォーマンスが違ってきます。一般的には前者のようにDBにたくさん仕事をしてもらうのが効率的です。注意が必要ですね。

参照

混乱してはいけないLaravelの動的プロパティ – Collection編混乱してはいけないLaravelの動的プロパティ – 裏側編混乱してはいけないLaravelの動的プロパティ – PHP8.2で廃止となった編

Laravel 11.xのインストール

Sat, 06 Apr 2024 07:52:04 +0900

早いものでL10がリリースされてからもう１年が経ちました。個人的な感想ですがL10では正直なところそこまで大きな変更が無かった様に思います。しかし大抵その様な場合は水面下で激しい議論が酌み交わされており次バージョンにてドラスティックな変更がやってくるもの。さてさてL11はどうなるやら、一緒に見ていきましょう！

サポート

いつも通りサポート表の確認から。まず、注意すべき点としてL11ではPHP8.2以上が必須となっています。前回のL9からL10にアップグレードする際もPHP8.0から8.1へPHPのVer要件が引き上げられました。忙しない感じもしますが、今回もPHP8.2が未インストールの場合は予め環境にインストールしておきましょう。macOSの方はphpbrewを使うと複数バージョンをインストールして切替られるので便利ですよ。

新規プロジェクト作成

早速L11をインストールしてみましょう。

$ composer create-project laravel/laravel L11.x

インストール完了後にプロジェクトディレクトリに移動し、バージョンを確認してみます。

$ cd L11.x
$ php artisan --version
>> Laravel Framework 11.0.7

2024年3月18日現在、11.0.7がインストールされました。続いて、ビルドインサーバを起動してみます。

php artisan serve

お馴染みのメニューが表示されました。

L10と比べて凝ったデザインになりましたね。続いて従来のバージョンからの変更点についてチェックしていきます。

ファイル構成の変更

Streamlined Application Structureというのが今回のアップデートの目玉のようです。要はファイル構成の変更ですが、方向性としてはより簡素で合理的な構造を目指す意図があるようです。その為、app配下の更新頻度が低いと判断されたファイル群が省かれ、各ファイルで行っていた設定はbootstrap/app.phpに集約されメソッドベースで設定する事となりました。以下がインストール直後のbootstrap/app.phpです。

bootstrap/app.php

use Illuminate\Foundation\Application;
use Illuminate\Foundation\Configuration\Exceptions;
use Illuminate\Foundation\Configuration\Middleware;

return Application::configure(basePath: dirname(__DIR__))
    ->withRouting(
        web: __DIR__.'/../routes/web.php',
        commands: __DIR__.'/../routes/console.php',
        health: '/up',
    )
    ->withMiddleware(function (Middleware $middleware) {
        //
    })
    ->withExceptions(function (Exceptions $exceptions) {
        //
    })->create();

withMiddleware()

ミドルウェアの設定に関するファイル群、app/Http/Middleware（ディレクトリごと）とapp/Http/Kernel.phpが削除され、それらで行っていた設定はwithMiddleware()で行います。

withExceptions()

以前はapp/Exceptions/Handler.phpにて、アプリケーション上で発生するあらゆる例外を検知しレポート（ログや通知など）やレンダリング（エラー画面の表示）の制御を行っていましたが、こちらも削除されwithExceptions()にまとめられました。

withCommands()

上に表示したbootstrap/app.phpにはありませんがwithCommands()というメソッドもあります。こちらのメソッドでは元々app/Console/Kernel.phpにて行っていたCommandクラスのディレクトリを指定できます。従来通り、app/Console/Commands配下のコマンドクラスは何も設定せずとも自動でロードされますが、もし他のディレクトリに分けて運用している場合はこのメソッドを使って追加登録する必要があります。

その他、bootstrap/app.php にて行える設定についてはvendor/laravel/framework/src/Illuminate/Foundation/Configuration/ApplicationBuilder.php をご確認下さい。

ServiceProviderの統合

app/Providers配下もとてもスッキリしたものになりました。AppServiceProviderクラスを除き以下の４つのServiceProviderクラスが削除されました。

AuthServiceProvider
BroadcastServiceProvider
EventServiceProvider
RouteServiceProvider

従来はAuthServiceProviderではModelとPolicyの紐付けを、EventServiceProviderではEventとListenerの紐付けを行なっていましたが、L11.xではそれらはAppServiceProviderのboot()にてGate::policy()やEvent::listen()を用いて行う様です。

app/Providers/AppServiceProvider.php

namespace App\Providers;

use Illuminate\Support\Facades\Gate;
use Illuminate\Support\Facades\Event;
use Illuminate\Support\ServiceProvider;

class AppServiceProvider extends ServiceProvider
{
    /**
     * Bootstrap any application services.
     */
    public function boot(): void
    {
        // ModelクラスとPolicyクラスの紐付け
        Gate::policy(
            YourModel::class,
            YourPolicy::class,
        );

        // EventクラスとListenerクラスの紐付け
        Event::listen(
            YourEvent::class,
            YourListener::class,
        );
    }
}

集約されてしまうことでAppServiceProviderが肥大化してしまうのでは？と心配になりますが、Laravel標準のディレクトリ構造、且つ、標準の命名規則に従って開発していれば大抵はLaravelが自動でクラス同士の紐付けを行なってくれるので手動で設定が必要なケースはそう多くなさそうです。（ModelクラスとPolicyクラスの自動紐付けについてはPolicyで認可チェックにて解説しているので是非そちらもチェックしてみてください。）

シンプルになったControllerの基底クラス

Controllerクラスの基底クラスであるApp\Http\Controllers\Controller.phpもシンプルになりました。

app/Http/Controllers/Controller.php

namespace App\Http\Controllers;

abstract class Controller
{
    //
}

只の真っさらなabstractクラスですね。以下のL10.xのと見比べてみてください。以前はIlluminate\Routing\Controllerを継承し、２つのトレイトAuthorizesRequestsとValidatesRequestsをuseしていました。

app/Http/Controllers/Controller.php

namespace App\Http\Controllers;

use Illuminate\Foundation\Auth\Access\AuthorizesRequests;
use Illuminate\Foundation\Validation\ValidatesRequests;
use Illuminate\Routing\Controller as BaseController;

class Controller extends BaseController
{
    use AuthorizesRequests, ValidatesRequests;
}

これらのトレイトは削除された訳では無く「必要あれば適宜使ってね」という事の様です。例えば以前にPolicyで認可チェックにて紹介したコントローラヘルパのauthorize()を使用して認可チェックを行う場合はAuthorizesRequestsが必要となります。

once()

最後にリリースノートを読んでいてこれは便利そうだ、と思った新しいヘルパ関数once()を紹介します。この関数は引数に指定したコールバックの結果をそのプロセスの間中キャッシュしてくれるというものです。これは例えばDBに保存しているマスタデータを取得する際などに便利そうです。例として以下にDBに保存された都道府県名を取得するコードを書いてみました。

app/Models/Prefecture.php

namespace App\Models;

use Illuminate\Database\Eloquent\Factories\HasFactory;
use Illuminate\Database\Eloquent\Model;

class Prefecture extends Model
{
    use HasFactory;

    protected $table = 'prefecture';

    public static function list(): array
    {
        return once(fn () => self::pluck('name')->all());
    }
}

once()を使って一度データを取得すれば2回目以降の呼び出しではキャッシュから参照されるのでクエリが発行されず効率的です。同一プロセス上で何度も参照が必要な場合に有効ですね。因みに以前は以下の様にstaticプロパティに退避するなどして対応していました。once()なら1行で書ける処理ですが、以前は5行も必要でした。

...
static $list;

public static function list(): array
{
    if (! isset(self::$list)) {
        self::$list = self::pluck('name')->all();
    }

    return self::$list;
}

L11.x on ララジャパン

ミドルウェアをもっと知ろう（３）パラメータを渡す

ミドルウェアをもっと知ろう（２）ミドルウェアを作成

禁止用語を隠すミドルウェア

グローバルミドルウェアに追加

ミドルウェアをもっと知ろう（１）グローバルミドルウェア

グローバルミドルウェア

TrimStrings

ConverEmptyStringsToNull

グローバルミドルウェアをすべて適用

composerをもっと知ろう（４）ローカルのパッケージをLaravelで使う

自分のパッケージを作成

Laravelのプロジェクトにインストール

最後に

テストがちょっとシンプルになる pest-plugin-laravel プラグイン

pest-plugin-laravelをインストール・テストファイル作成

pest-plugin-laravelを使った記述方法

データセット

まとめ

composerをもっと知ろう（３）バージョンに関して

composer.json

^11.9の意味

composer.lock

PHPUnit 11 - アノテーションからアトリビュートに書き換える

PHPUnit12で削除される@アノテーション

アノテーション → アトリビュートの書き換え

変更前のテスト（アノテーション使用）

変更後のテスト（アトリビュート使用）

改めてテストを実行

カバレッジの出力を確認

Laravel10.xからLaravel 11.xへの更新で注意すること

configのファイルたちの復元

.envを変更する必要がある

削除されたEventServiceProviderの中身の行方

最後に

composerをもっと知ろう（２）composer create-projectでは何が起こっている？

Laravelの新規のプロジェクトの作成

プロジェクト作成の設計図

create-project実行の作業

プロジェクトディレクトリの作成

ルートパッケージのインストール

.envの作成

composer.lockの作成

依存するパッケージのインストール

scriptsの実行

Laravel Pestでモック・例外のテスト

テスト対象

Pestの構文

共通処理

成功パターンのテスト

失敗パターンのテスト

関連記事

composerをもっと知ろう（１）composer show

composerがインストールしたパッケージ

インストールされているパッケージは最新？

LaravelのPHPUnitテストをpest-plugin-driftでPestへ変換

Pest変換対象のLaravelプロジェクト

Pest・Pest変換用プラグインインストール

PHPUnit → Pest変換前後の比較

dataprovider

setUp関連

テスト実行

カレンダー（４）タイムゾーン

Laravelのタイムゾーンは何？

DateTimeZone

Livewireのコンポーネントにタイムゾーンを

URLパラメータ

Livewireのライフサイクル

カレンダー（３）休日と営業時間の表示

欲しいもの

opening-hours：営業時間

yasumi：祭日

店舗のカレンダー

カレンダー（２）Livewireを使いリアクティブとする

Livewireに変換

コンポーネントの作成

カレンダー（１）AIで生成

欲しいもの

Copilotでカレンダーの生成

Livewireを使ってポーリング