長期間(6以前から)運用されているLaravelシステムがあるなら、ジョブのコードを一度確認した方がいいかもしれない

2024/09/05

Laravelのジョブクラスの`failed`メソッドの実行に失敗する

Laravelのジョブクラスには、failedというメソッドを実装することで、失敗時の処理を定義できます。

<?php

namespace App\Jobs;

// ...

class FooJob implements ShouldQueue
{
    // ...

    /**
     * The job failed to process.
     *
     * @param  Exception  $exception
     * @return void
     */
    public function failed(Exception $exception)
    {
        // 失敗時に実行される
    }
}

最近、このfailedメソッドの実行自体がエラーになることがありました。

Argument #1 ($exception) must be of type Exception, TypeError given, ...

確認すると、原因は単なる引数の型の間違えでした。上記のようにExceptionを受け取っていたのですが、実際に渡されたのはTypeErrorでした。

ご存知のように、PHPの例外は以下のようなツリー構造になっています。

- Throwable
  - Error
    - TypeError
    ...
  - Exception
    ...

TypeErrorはErrorのサブクラスであり、Exceptionのサブクラスではないので、failedの実行が失敗するのは当然です。

原因究明

しかしさて、なぜfailedの第1引数をExceptionとして実装してしまったのでしょうか。原因を探ってみました。

まず、このfailedは、artisan make:jobで用意されるものではなさそうでした。
その他、コード内のなにかを元にしたわけではなさそうでした。Laravelのジョブクラスは親クラスを継承して作るような仕様ではないので、親クラスのfailedを持って来た、という可能性はありません。
元々failedはExceptionを受け取る仕様であり、途中でそれが変わった可能性を考え、コミットログやアップグレードガイドをざっと見ましたが、その限りでは元々Throwableを受け取る仕様だったようです。
公式ドキュメントにfailedの実装例はありました。が、型は正しくThrowableでした。

とりあえずここまで来て思い付くことがあり、古いバージョンのドキュメントを確認すると、そこには第1引数がExceptionになっている実装例がありました。これをコピペしたのが原因と考えてよさそうです。

<?php
 
namespace App\Jobs;
 
use Exception;
use App\Podcast;
use App\AudioProcessor;
use Illuminate\Bus\Queueable;
use Illuminate\Queue\SerializesModels;
use Illuminate\Queue\InteractsWithQueue;
use Illuminate\Contracts\Queue\ShouldQueue;
 
class ProcessPodcast implements ShouldQueue
{
    use InteractsWithQueue, Queueable, SerializesModels;
 
    protected $podcast;
 
    /**
     * Create a new job instance.
     *
     * @param  Podcast  $podcast
     * @return void
     */
    public function __construct(Podcast $podcast)
    {
        $this->podcast = $podcast;
    }
 
    /**
     * Execute the job.
     *
     * @param  AudioProcessor  $processor
     * @return void
     */
    public function handle(AudioProcessor $processor)
    {
        // Process uploaded podcast...
    }
 
    /**
     * The job failed to process.
     *
     * @param  Exception  $exception
     * @return void
     */
    public function failed(Exception $exception)
    {
        // Send user notification of failure, etc...
    }
}