[PHP]declareとは?ファイル単位で実行ディレクティブを設定する方法を徹底解説

PHP

はじめに

これまでの記事で、try・catch・finally という例外処理の仕組みを解説してきました。今回取り上げる declare は、それらとは少し毛色が異なり、ファイル全体(またはブロック単位)の実行方法そのものを指定するための、PHPの特殊な構文です。

declare の中で最も頻繁に使われるのが strict_types ディレクティブです。これを有効にすることで、関数の引数や戻り値の型チェックが、PHPの緩やかな「型の自動変換」に頼らない、より厳密なモードに切り替わります。モダンなPHP開発において、declare(strict_types=1); という一文をファイルの先頭に書くことは、堅牢なコードを書くための基本的な作法として広く定着しています。本記事では strict_types を中心に、declare の基本的な使い方と注意点を詳しく解説します。


構文概要

項目内容
構文名declare
種別言語構文(ディレクティブの設定)
基本構文declare(ディレクティブ名 = 値);
代表的なディレクティブstrict_types(PHP 7.0以降)、ticks、encoding
strict_typesの記述位置ファイルの最初の文として書く必要がある
strict_typesの影響範囲宣言したファイル内でのみ有効(他ファイルには影響しない)
対応バージョンPHP 5.3.0以降(strict_typesはPHP 7.0以降)

型変換モードの違い(イメージ図)

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

  【declare(strict_types=1)を書かない場合(デフォルト・弱い型付け)】
  add('5', '3');
              │
              ▼
  自動的に'5'と'3'が整数5, 3に変換され、結果は8になる


  【declare(strict_types=1); をファイル先頭に書いた場合】
  add('5', '3');
              │
              ▼
  型が一致しないため TypeError がスローされる
  ★より厳密な型チェックが行われるようになる

ポイントは、declare(strict_types=1); が**「このファイルの中では、型の自動変換に頼らず、宣言した型と完全に一致する値だけを受け付ける」**という、より安全なモードへの切り替えスイッチであるという点です。


実践サンプル7選

例1:基本的な使い方

<?php
declare(strict_types=1); // ファイルの最初の文として書く

function multiply(int $a, int $b): int
{
    return $a * $b;
}

echo multiply(3, 4) . PHP_EOL; // 12(整数同士なので問題なく動作する)

例2:strict_typesによる型エラーの検知

<?php
declare(strict_types=1);

function greet(string $name): string
{
    return "こんにちは、{$name}さん";
}

try {
    // 整数を渡すと、strict_typesが有効な場合は自動変換されずエラーになる
    echo greet(123) . PHP_EOL;
} catch (\TypeError $e) {
    echo '型エラー: ' . $e->getMessage() . PHP_EOL;
}

例3:strict_typesがない場合との挙動比較(別ファイルのシミュレーション)

<?php
// strict_typesを宣言していないファイルの動作をコメントで示す

function calculateTotal(int $price, int $quantity): int
{
    return $price * $quantity;
}

// strict_typesがない場合、以下はエラーにならず自動変換される
echo calculateTotal('100', '3') . PHP_EOL; // 300(文字列が自動的に整数に変換される)

/**
 * 注意: 上記の挙動は、このファイルの先頭に
 * declare(strict_types=1); がない場合のものです。
 * 実際のプロジェクトでは一貫してstrict_typesを使うことが推奨されます。
 */

例4:整数から浮動小数点数への「安全な拡大変換」は許可される

<?php
declare(strict_types=1);

function calculateArea(float $width, float $height): float
{
    return $width * $height;
}

/**
 * strict_typesが有効でも、intをfloatとして渡すことは
 * 「データが失われない安全な変換」として特別に許可されている
 */
echo calculateArea(5, 3) . PHP_EOL; // 15(整数5, 3がfloatとして扱われてもエラーにならない)

例5:戻り値の型チェックにも影響することを確認する

<?php
declare(strict_types=1);

class UnstrictReturn
{
    public function getValue(): int
    {
        // strict_typesが有効な場合、文字列をそのままintとして返そうとするとエラーになる
        return '42'; // TypeErrorが発生する可能性がある
    }
}

try {
    echo (new UnstrictReturn())->getValue() . PHP_EOL;
} catch (\TypeError $e) {
    echo '戻り値の型エラー: ' . $e->getMessage() . PHP_EOL;
}

例6:declareブロックを使った限定的なスコープへの適用(ticksの例)

<?php

/**
 * declareはブロック構文として、特定の範囲だけに
 * ディレクティブを適用することもできる(strict_typesは除く)
 * ticksはN文ごとにtick_functionを呼び出す、やや特殊な仕組み
 */
declare(ticks=1) {
    register_tick_function(function () {
        static $count = 0;
        $count++;
        echo "tick #{$count}" . PHP_EOL;
    });

    for ($i = 0; $i < 3; $i++) {
        echo "処理中: {$i}" . PHP_EOL;
    }
}

例7:プロジェクト全体でstrict_typesを徹底するチェックツール

<?php

class StrictTypesChecker
{
    /**
     * プロジェクト内のPHPファイルが
     * declare(strict_types=1)を含んでいるかを検出する簡易ツール
     */
    public function checkFile(string $phpCode): bool
    {
        return (bool) preg_match('/declare\s*\(\s*strict_types\s*=\s*1\s*\)/', $phpCode);
    }
}

$checker = new StrictTypesChecker();
var_dump($checker->checkFile("<?php\ndeclare(strict_types=1);\nclass Foo {}"));
var_dump($checker->checkFile("<?php\nclass Bar {}"));

関連機能との比較

機能役割declareとの違い
declare(strict_types=1)ファイル単位で厳密な型チェックを有効にする本記事の対象。最もよく使われるdeclareの用途
declare(ticks=N)N文ごとに登録済みの関数を呼び出す(やや特殊な機能)型チェックではなく、実行中の定期的なフック処理に関わる
型宣言(int $xなど)関数の引数や戻り値に期待する型を指定するdeclare自体ではなく、その型チェックの厳しさをdeclareが制御する
ini_set()実行時にphp.ini相当の設定を変更するより広範なPHP全体の設定を対象とし、strict_typesはこの方法では変更できない
composerの"strict_types"的な規約プロジェクト全体でのコーディング規約言語機能ではなく、チームの運用ルールとして統一を図る手段

よくある落とし穴(注意点)

  1. strict_typesはファイルの「最初の文」でなければならない declare(strict_types=1); の前にコメント以外の何らかのコード(namespace 宣言を除く)があると、致命的なパースエラーになります。常にファイルの先頭、<?php タグの直後に書く必要があります。
  2. 呼び出し元のファイルの設定が適用される strict_types は、関数が「定義されている」ファイルではなく、その関数を「呼び出している」ファイルの設定に従います。厳密な型チェックを有効にしたファイルから、無効なファイルで定義された関数を呼び出した場合でも、呼び出し側の厳密なルールが適用されます。
  3. 整数から浮動小数点数への変換は例外的に許可される strict_types が有効でも、int を float として渡すことは、データの損失がない「安全な拡大変換」として特別に許可されています(例4を参照)。この点は、他の型変換が一切禁止されることとの違いとして覚えておく価値があります。
  4. ticksのような他のディレクティブは、ブロック構文として限定的に使える strict_types はファイル全体にのみ適用できますが、ticks のような他のディレクティブは、declare (...) { ... } のようにブロックで囲むことで、特定の範囲だけに適用することも可能です(例6を参照)。両者の適用範囲の違いを混同しないようにしましょう。
  5. 既存のレガシーコードへの後付けには注意が必要 既存の大規模なコードベースに後から declare(strict_types=1); を追加すると、これまで暗黙の型変換に依存していた箇所で、一斉に TypeError が発生する可能性があります。導入する際は、十分なテストとともに段階的に進めることが推奨されます。

まとめ

観点まとめ
何をする構文かファイル単位(または一部のディレクティブはブロック単位)で、実行時の挙動に関わる設定を行う
最も重要な用途strict_types=1による厳密な型チェックの有効化
記述上の制約strict_typesはファイルの最初の文として書く必要がある
適用範囲strict_typesは宣言したファイル自身の呼び出しコンテキストに適用される
注意点既存コードへの後付けの影響範囲、整数→浮動小数点数の例外的な許可

declare(strict_types=1); は、PHPの型システムをより厳密に活用し、意図しない暗黙の型変換によるバグを未然に防ぐための、現代的なPHP開発における基本的な作法です。新規プロジェクトでは、すべてのファイルの先頭にこの一文を書くことを習慣にすることで、より堅牢で予測可能なコードベースを維持できます。

タイトルとURLをコピーしました