# ch05 — 型宣言

Source: https://php-school.pages.dev/topics/function/ch05-type-hints/
Site: AIと学ぶPHPの学校 (https://php-school.pages.dev)
Lesson: 関数
Level: L2

Reference (official): https://www.php.net/manual/ja/language.functions.php

## 本文

# ch05 — 型宣言

## 概要

型宣言 (type hint / type declaration) は **「この引数には何型の値が来るか」「この関数は何型の値を返すか」を関数の入り口と出口で明示する仕組み** だ。`function add(int $a, int $b): int { ... }` のように書いておくと、文字列を渡したり戻り値を別の型にしたりすると即座にエラーになり、バグが本来の発生箇所からずっと離れて現れる事故を防げる。コードを後から読む人にとっても「何が入って何が出るか」がコメントなしで分かるドキュメントになる。

PHP では `int` `float` `string` `bool` `array` などの基本型に加えて、クラス名や `null` 許容 (`?int`) も型に書ける。戻り値の型は引数リストの後ろに `): 型` の形で付ける。型に合わない値が来たときの挙動は `declare(strict_types=1);` の有無で変わるが、本チャプターでは「とりあえず宣言を書く」習慣を作るところを目標にする。

PHP 8 では **共用体型 (union type)** が導入され、`function f(int|string $x): int|string` のように「int か string のどちらか」と書けるようになった。なんでも受け付ける関数を作りたくなったとき、`mixed` で逃げる前に `int|string` のような具体的な共用体で意図を残せると、後から読むコードが格段に分かりやすくなる。

## 学習目標

- `function f(int $x): int { ... }` で引数と戻り値の型を宣言できる
- `int`・`string` などの基本型を引数に書ける
- 戻り値の型は `): 型` で関数定義の後ろに書く

## 所要時間

スライド 4 分 + ドリル 2 問 = **12 分**

## ドリル

| no | 内容 |
|---|---|
| 01 | `add(int $a, int $b): int` を作る |
| 02 | `repeat(string $s, int $n): string` を作る |

## 採点

```bash
php scripts/grade.php topics/function/ch05-type-hints/drill/01-add-int/
```

## 関連チャプター

- [`ch03-return`](../ch03-return/) — 戻り値の概念 (前提)
- [`ch04-default-args`](../ch04-default-args/) — デフォルト引数
- [`ch06-array-arg`](../ch06-array-arg/) — 配列型の関数

## スライド

---
marp: true
theme: dojo
paginate: true
size: 16:9
---

<!--
LLM_CONTEXT:
  Lesson 6 / Chapter 5
  目的: function f(int $x): int { ... } で引数と戻り値の型を宣言できる。基本型 + null 許容 (?int) + 共用体 (int|string) まで
  扱わない: mixed / never / generics 風の書き方 / declare(strict_types=1) の深掘り
  読み上げ時間目安: 4 分
-->

# 型宣言 (type hints)

Lesson 6 / Chapter 5

---

## ゴール

```php
function add(int $a, int $b): int {
    return $a + $b;
}
```

このように **引数と戻り値に型を書ける** ようになる。

`?int` / `int|string` までを使えるところまで持っていく。

---

## なぜ型を書くのか

```php
// 型なし: 何を渡せばいいか不明
function add($a, $b) { return $a + $b; }

add("3", "5");   // → "35" ? 8 ? 動くけど怖い
```

- 何が入って何が出るかが、 コメントなしで伝わる
- バグが本来の発生箇所で即エラーになる
- 後から読む人にとって **ドキュメント** になる

---

## 引数と戻り値に型を書く

```php
<?php
function add(int $a, int $b): int {
    return $a + $b;
}

echo add(3, 5);    // 8
```

- 引数: `int $a` のように 型 + 変数名
- 戻り値: `): int` を関数定義の後ろに付ける
- 基本型 = `int` / `float` / `string` / `bool` / `array`

---

## 文字列を返す例

```php
<?php
function repeat(string $s, int $n): string {
    return str_repeat($s, $n);
}

echo repeat("ab", 3);   // "ababab"
```

- 引数 2 つ、 戻り値 1 つの両方に型
- 入口で `string` `int` が来るとわかる
- 出口で `string` が返るとわかる

---

## null を許す型: `?string`

```php
<?php
function find(int $id): ?string {
    if ($id === 1) return "alice";
    return null;        // 見つからなければ null
}
```

- `?string` = 「`string` または `null`」
- 「見つからないことがある」 検索系の戻り値で頻出

---

## 共用体型: `int|string` (PHP 8+)

```php
<?php
function f(int|string $x): int|string {
    if (is_int($x)) return $x * 2;
    return strtoupper($x);
}

echo f(5);      // 10
echo f("hi");   // "HI"
```

- `int|string` で「int か string のどちらか」
- 「なんでも」 と思ったら **mixed の前に共用体** を検討
- 意図がコードに残るので保守性が上がる

---

## このチャプターでできるようになること

✅ `function f(int $x): int { ... }` で引数と戻り値に型を書ける
✅ 基本型 (`int` / `string` / `bool` / `array` 等) を引数に書ける
✅ `?string` で null 許容を表現できる
✅ `int|string` の共用体型で「複数の型」を表せる

→ ドリルへ