【PHP8.x】substr_compare関数の使い方

substr_compare関数の使い方について、初心者にもわかりやすく解説します。

作成日: 2025年09月11日更新日: 2025年09月29日

基本的な使い方

substr_compare関数は、2つの文字列の指定された部分を比較する関数です。この関数は、特定の文字列の一部が別の文字列の同じ部分と一致するかどうかを効率的に判断したい場合に役立ちます。

具体的には、比較する最初の文字列（$main_str）と2番目の文字列（$str）を指定します。さらに、最初の文字列から比較を開始する位置を示すオフセット（$offset）と、比較する文字の長さ（$length）も設定できます。オプションとして、大文字と小文字を区別せずに比較するかどうか（$case_insensitivity）も指定可能です。この引数をtrueに設定すると、大文字と小文字の違いを無視して比較が行われます。

比較はバイト単位で行われ、結果は整数値で返されます。比較した両方の部分文字列が完全に一致する場合は0が返されます。最初の部分文字列が2番目の部分文字列よりも大きい場合は正の整数が、小さい場合は負の整数が返され、辞書順での大小関係も判断できます。ただし、指定されたオフセットが無効な場合や、比較する長さが文字列の範囲を超えるなど、比較が不可能な状況ではfalseを返すことがあります。

この関数は、URLの一部を比較したり、ファイルパスの一致を確認したりする際など、文字列の特定の部分を厳密に比較する必要がある状況で非常に有用です。特に、大文字・小文字を区別するかどうかを柔軟に制御できる点が特徴です。

構文(syntax)


1<?php
2$main_string = "Hello PHP World";
3$search_string = "PHP";
4$offset = 6;
5$length = 3;
6$result = substr_compare($main_string, $search_string, $offset, $length, false);
7?>

引数(parameters)

string $haystack, string $needle, int $offset, ?int $length = null, bool $case_insensitive = false

string $haystack: 検索対象の文字列
string $needle: 検索する部分文字列
int $offset: $haystack の検索を開始する位置
?int $length = null: $needle の長さを指定する整数。null の場合は $needle の最後まで比較します。
bool $case_insensitive = false: true を指定すると、大文字・小文字を区別せずに比較します。

戻り値(return)

int|false

文字列の部分文字列を、大文字小文字を区別して、指定された位置から比較した結果を返します。比較結果が0未満の場合は-1、0より大きい場合は1、一致する場合は0を返します。比較対象の文字列が指定された長さよりも短い場合はfalseを返します。

サンプルコード

PHP substr_compare関数で文字列比較する


1<?php
2
3/**
4 * substr_compare関数の基本的な使い方を示すサンプルコードです。
5 * この関数は、指定されたオフセットから始まる文字列の一部を別の文字列と比較し、
6 * 両者の辞書順での関係を整数値で返します。
7 * 大文字小文字を区別するかどうかも指定できます。
8 */
9
10// 比較元の文字列
11$mainString = "Hello PHP World";
12// 比較対象の文字列
13$searchString = "PHP";
14
15echo "元の文字列: '" . $mainString . "'\n";
16echo "検索文字列: '" . $searchString . "'\n\n";
17
18// --- 例1: 大文字小文字を区別して部分文字列が一致するか比較する ---
19// $mainString のインデックス6（'P'）から $searchString ('PHP') と比較します。
20// $offset: 6 (0から始まるインデックス)
21// $length: null (比較対象文字列 $searchString の長さ全体を使用)
22// $case_insensitive: false (大文字小文字を区別する)
23$result1 = substr_compare($mainString, $searchString, 6, null, false);
24
25echo "--- 例1: 大文字小文字を区別して比較 ---\n";
26echo "比較: '{$mainString}' の6文字目から '{$searchString}'\n";
27if ($result1 === 0) {
28    echo "結果: 部分文字列は一致しました。\n";
29} elseif ($result1 > 0) {
30    echo "結果: 元の文字列の部分が検索文字列より辞書順で後です。\n";
31} elseif ($result1 < 0) {
32    echo "結果: 元の文字列の部分が検索文字列より辞書順で前です。\n";
33} else {
34    echo "結果: 比較に失敗しました (例: オフセットが文字列の範囲外)。\n";
35}
36echo "戻り値: " . var_export($result1, true) . "\n\n";
37
38
39// --- 例2: 大文字小文字を区別せずに部分文字列が一致するか比較する ---
40// 比較対象を小文字の 'php' とし、大文字小文字を区別せずに比較します。
41// $case_insensitive: true (大文字小文字を区別しない)
42$searchStringLower = "php";
43$result2 = substr_compare($mainString, $searchStringLower, 6, null, true);
44
45echo "--- 例2: 大文字小文字を区別せずに比較 ---\n";
46echo "比較: '{$mainString}' の6文字目から '{$searchStringLower}'\n";
47if ($result2 === 0) {
48    echo "結果: 部分文字列は一致しました。\n";
49} else {
50    // この場合、大文字小文字を区別しないので一致します。
51    // それ以外の場合は一致しないか、辞書順で前後します。
52    echo "結果: 部分文字列は一致しませんでした (または辞書順が異なります)。\n";
53}
54echo "戻り値: " . var_export($result2, true) . "\n\n";
55
56
57// --- 例3: 比較する長さを指定して部分文字列を比較する ---
58// $mainString の先頭から5文字だけを 'Hello' と比較します。
59// $offset: 0 (先頭から)
60// $length: 5 (比較する文字数)
61// $case_insensitive: false (大文字小文字を区別する)
62$partialString = "Hello";
63$result3 = substr_compare($mainString, $partialString, 0, strlen($partialString), false);
64
65echo "--- 例3: 比較する長さを指定して比較 ---\n";
66echo "比較: '{$mainString}' の0文字目から '{$partialString}' を" . strlen($partialString) . "文字分\n";
67if ($result3 === 0) {
68    echo "結果: 部分文字列は一致しました。\n";
69} else {
70    echo "結果: 部分文字列は一致しませんでした (または辞書順が異なります)。\n";
71}
72echo "戻り値: " . var_export($result3, true) . "\n\n";
73
74// 補足:
75// substr_compare関数は、比較対象が見つからなかった場合や、
76// オフセットが文字列の長さを超えている場合など、
77// エラー時にはブール値の 'false' を返すことがあります。
78// そのため、結果の確認は厳密に '=== 0' で行うことが推奨されます。
79
80?>

PHPのsubstr_compare関数は、ある文字列（$haystack）の指定された一部を、別の文字列（$needle）と比較し、両者の辞書順での関係を整数値で返す関数です。この関数を使用することで、文字列の一部が特定のパターンと一致するかどうかを効率的に判定できます。

引数$haystackは比較元の文字列、$needleは比較対象の文字列を指定します。$offsetは$haystackのどこから比較を開始するかを0を基点とするインデックスで指定し、$lengthは$needleの何文字までを比較するかを決定します（省略時は$needle全体）。最後の$case_insensitive引数をtrueにすると、大文字と小文字を区別せずに比較が行われます。

戻り値は、部分文字列が完全に一致する場合に0を返します。もし$haystackの部分が$needleより辞書順で後であれば正の整数、前であれば負の整数を返します。また、比較元の文字列の範囲外を指定するなど、エラーが発生した場合にはfalseを返します。

サンプルコードの例1では、「Hello PHP World」の6文字目から「PHP」と大文字小文字を区別して比較し、0が返ることで一致を確認しています。例2では、大文字小文字を区別しない設定（true）で「php」と比較し、やはり一致と判断される様子を示しています。例3では、比較する長さを指定して「Hello」が文字列の先頭に存在するかを確認しています。

substr_compare関数は、比較に失敗するとfalseを返すため、結果の確認は厳密に=== 0で行うことが推奨されます。これにより、文字列の特定部分の一致判定を柔軟かつ安全に行うことができます。

この関数は、指定した開始位置（オフセット）から文字列の一部を別の文字列と比較します。オフセットは0から始まるインデックスである点にご注意ください。大文字小文字を区別するかどうかや、比較する長さを細かく指定できるため、柔軟な文字列比較が可能です。

最も重要なのは戻り値の扱いです。比較結果が一致した場合は整数値の0を返しますが、オフセットが文字列の範囲外などのエラーが発生した場合はブール値のfalseを返すことがあります。そのため、結果が一致したかを確認する際には、0とfalseを明確に区別するため、厳密等価演算子=== 0を必ず使用してください。これにより、意図しない誤動作を防ぎ、安全にコードを利用することができます。