はじめに
Laravel のコードを読んでいると、こういう1行によく出会います。
public function scopePublished(Builder $query, ?string $referenceDate = null): Builder
最初に見たときは「Builderって何?」「?stringの?って何?」「: Builderってなに?」と、情報量の多さに圧倒されました。
この記事では、PHP の型宣言を
- スカラー型とクラス型の違い
- nullable型(
?) - 戻り値の型宣言
の3つに分けて、上のコードを最後まで読めるようになるところまで整理します。
結論:型宣言は「間違った値を渡した瞬間に気づける」ための約束事
PHP は本来、型を書かなくても動く言語です。
<?php
function addTax($price) {
return $price * 1.1;
}
addTax(100); // 110
addTax("abc"); // 実行時までエラーに気づけない
型宣言を書いておくと、間違った種類の値を渡した瞬間に TypeError で教えてくれます。
<?php
function addTax(int $price) {
return $price * 1.1;
}
addTax(100); // 110
addTax("abc"); // TypeError: Argument #1 ($price) must be of type int, string given
1. スカラー型とクラス型
型には大きく分けて2種類あります。
| スカラー型 | クラス型 | |
|---|---|---|
| 何を表す? | 数値・文字列・真偽値など「素の値」 | 「〇〇というクラスのインスタンスである」こと |
| 例 |
int, string, bool, array
|
Builder, User, Carbon
|
| 由来 | PHP言語そのものが用意 | Laravel・自分のアプリ・ライブラリが定義したクラス |
使うのに use が必要? |
不要 | 必要(ファイル先頭で読み込む) |
冒頭のコードには、実は両方の型が登場しています。
public function scopePublished(Builder $query, ?string $referenceDate = null): Builder
// ^^^^^^^ ^^^^^^ ^^^^^^^
// クラス型 スカラー型 クラス型
クラス型の実体は use 文の場所にある
use Illuminate\Database\Eloquent\Builder;
この use 文の名前空間(\区切り)が、そのままファイルパスになっています。
Illuminate\Database\Eloquent\Builder
↓ \ を / に置き換える
vendor/laravel/framework/src/Illuminate/Database/Eloquent/Builder.php
vendor/ の中はLaravel本体のコードです。Composerが管理している領域なので、ここは絶対に編集しません(composer update のたびに上書きされます)。VSCodeならクラス名の上で cmd(Macの場合)を押しながらクリックすると、このファイルまで一発で飛べます。
2. nullable型(?)
?string $referenceDate = null
| 部分 | 意味 |
|---|---|
string |
スカラー型。文字列を表す |
先頭の ?
|
nullable型のマーク。「nullでもOK」を追加する |
= null |
引数を省略したときのデフォルト値 |
? がない場合との違い
<?php
function foo(string $x) { ... }
foo(null); // TypeError(文字列しか受け付けない)
function foo(?string $x) { ... }
foo(null); // OK(nullも許可)
foo('hello'); // OK
foo(123); // まだエラー(数値は許可していない)
? が追加で許可しているのは「null」だけです。他の型(数値・配列など)は変わらず受け付けません。
どんな型にも付けられる
?int $count = null // 整数 または null
?array $items = null // 配列 または null
?User $user = null // Userクラスのインスタンス または null
スカラー型にもクラス型にも、同じルールで ? を付けられます。
string $x = null のように ? を付けずに書くと、「型は文字列だけ」と言いながらデフォルト値が文字列でない null になり矛盾します。? を付けて、意図を正しく表しましょう。
実例:$referenceDateに実際に何が入るか
このスコープは、呼び出し方が2パターンあるとします。
// パターンA:引数なし
->published()
// → $referenceDate = null(デフォルト値がそのまま使われる)
// パターンB:引数あり
$today = Carbon::today()->format('Y-m-d'); // "2026-11-17" という文字列ができる
->published($today)
// → $referenceDate = "2026-11-17"($todayの中身がそのままコピーされる)
「引数」とは、呼び出し側が丸括弧の中に書いた値が、そのまま定義側の変数名にコピーされて入ることです。$today と $referenceDate は名前が違うだけで、同じ値が渡っています。
3. 戻り値の型宣言
public function scopePublished(...): Builder
// ^^^^^^^ 戻り値の型宣言
関数の ) の後、: に続けて書きます。
| 書き方 | 意味 |
|---|---|
: Builder |
Builderクラスのインスタンスを返す |
: int |
整数を返す |
: void |
何も返さない |
: ?string |
文字列 または null を返す |
戻り値の型宣言はLaravelの動作には必須ではありません(消しても同じように動きます)。それでも書く理由は3つ。①読む人に意図が伝わる ②間違った型を返すとPHPがエラーで教えてくれる ③エディタの補完が効く。
全部まとめて読む
ここまでの例を、実際に動くコードとして組み立て直すとこうなります。「公開日が今日以前の記事だけに絞る」という、よくあるブログのスコープです。
use Illuminate\Database\Eloquent\Builder;
use Carbon\Carbon;
class Post extends Model
{
public function scopePublished(Builder $query, ?string $referenceDate = null): Builder
{
return $query->where('published_at', '<=', $referenceDate ?? Carbon::today()->toDateString());
}
}
public function scopePublished(Builder $query, ?string $referenceDate = null): Builder
// ① ② ③ ④
| # | 部分 | 型の種類 | 意味 |
|---|---|---|---|
| ① | scopePublished |
— | メソッド名(scope+名前で、呼び出し側は->published()と書ける) |
| ② | Builder $query |
クラス型 | 「ここまでの条件」が自動で渡ってくる引数 |
| ③ | ?string $referenceDate = null |
nullable スカラー型 | 基準日。省略するとnull
|
| ④ | : Builder |
クラス型(戻り値) | 条件を1つ足した後のBuilderを返す |
この1行だけで「何を受け取って、何を返すか」がすべて宣言されています。中身({ ... }の中)を読まなくても、この宣言だけで「条件オブジェクトを受け取って、文字列(省略可)も受け取って、条件オブジェクトを返す関数」だと分かるのが、型宣言のいちばんのメリットです。
まとめ
- 型宣言は「間違った値を渡した瞬間に気づける」ための約束事
- 型には スカラー型(PHP自体が知っている素の値の型)と クラス型(誰かが定義したクラスのインスタンスであること)の2種類がある
- 先頭の
?は「その型、またはnull」に変える追加ルール。スカラー型・クラス型どちらにも付けられる -
: 型()の後)は戻り値の型。必須ではないが、意図を伝えるために書く
参考
- PHP マニュアル「型宣言」: https://www.php.net/manual/ja/language.types.declarations.php
- Laravel公式ドキュメント「クエリビルダ」: https://laravel.com/docs/queries