【PHP8.x】wordwrap()関数の使い方

Copy
1<?php
2
3/**
4 * wordwrap関数の使用例を示します。
5 * この関数は、指定された幅で文字列を折り返し、読みやすく整形します。
6 *
7 * @return void
8 */
9function demonstrateWordwrap(): void
10{
11    $longText = "PHPのwordwrap関数は、長いテキストを指定された文字幅で自動的に改行するのに役立ちます。これにより、出力が見やすくなり、特に固定幅の表示領域にテキストを表示する際に非常に便利です。";
12
13    echo "--- 1. デフォルトの設定で折り返し (幅: 75文字, 改行: \\n) ---\n";
14    // デフォルトの幅 (75) と改行文字 (\n) でテキストを折り返します。
15    echo wordwrap($longText);
16    echo "\n\n"; // 出力の区切りを分かりやすくするため
17
18    echo "--- 2. 幅を25文字に指定して折り返し ---\n";
19    // 幅を25文字に設定してテキストを折り返します。
20    echo wordwrap($longText, 25);
21    echo "\n\n";
22
23    echo "--- 3. 幅を30文字に指定し、<br>タグで折り返し ---\n";
24    // 幅を30文字に設定し、改行文字としてHTMLの<br>タグを使用します。
25    echo wordwrap($longText, 30, "<br>");
26    echo "\n\n";
27
28    // 長い単語を含むテキスト
29    $textWithLongWord = "この単語は非常に長い：supercalifragilisticexpialidocious。wordwrap関数がこれをどう処理するか見てみましょう。";
30
31    echo "--- 4. 長い単語を切り詰めずに折り返し (幅: 20文字, デフォルト挙動) ---\n";
32    // 幅を20文字に設定しますが、`cut_long_words`が`false`（デフォルト）のため、
33    // 長い単語は途中で切られずに次の行に送られます。
34    echo wordwrap($textWithLongWord, 20, "\n", false);
35    echo "\n\n";
36
37    echo "--- 5. 長い単語を切り詰めて折り返し (幅: 20文字, cut_long_words = true) ---\n";
38    // 幅を20文字に設定し、`cut_long_words`を`true`にすることで、
39    // 幅を超える長い単語も途中で切って折り返します。
40    echo wordwrap($textWithLongWord, 20, "\n", true);
41    echo "\n\n";
42}
43
44// 関数を実行して、wordwrap関数の動作を確認します。
45demonstrateWordwrap();

PHPのwordwrap関数は、長いテキストを指定された文字幅で自動的に折り返し、読みやすく整形するために使用されます。この関数は、指定された文字列 $string を受け取り、折り返し処理を施した新しい文字列を返します。

第二引数の $width は、テキストを何文字で折り返すかを指定する整数値です。省略した場合はデフォルトで75文字の幅が適用されます。第三引数の $break は、折り返しの際に挿入する文字列を指定します。デフォルトでは改行コードである \n が使用されますが、HTMLの <br> タグなどを指定することも可能です。最後の引数 $cut_long_words は真偽値で、trueを設定すると、指定された幅を超える長い単語も途中で切り詰めて折り返します。false（デフォルト）の場合、単語が途中で切られることはなく、次の行に送られます。

サンプルコードでは、まずデフォルト設定（幅75文字、改行 \n）でテキストを折り返す基本的な動作を示しています。次に、$widthを25文字に指定して折り返し幅を変更する例、そして$breakにHTMLの<br>タグを指定して改行文字を変える例を紹介しています。さらに、長い単語を含むテキストを使い、$cut_long_wordsがfalseの場合には単語が途中で切られずに次の行に送られること、trueの場合には単語も切り詰められて折り返されることの違いを具体的に示しています。これにより、テキストの表示領域や用途に応じた柔軟な整形が可能となります。

Copy
1<?php
2
3/**
4 * マルチバイト文字列対応の wordwrap 関数
5 *
6 * PHPの標準の wordwrap 関数はバイト数を基準に文字列を折り返すため、
7 * 日本語のようなマルチバイト文字を含む文字列では意図しない場所で文字が切れたり、
8 * 文字化けする可能性があります。
9 * この関数は mbstring 拡張機能を利用して、文字の表示幅を基準に文字列を折り返します。
10 * 全角文字は2文字分の幅、半角文字は1文字分の幅として計算します。
11 *
12 * 注意: この関数は mbstring 拡張機能が有効になっている必要があります。
13 *
14 * @param string $string 入力文字列
15 * @param int $width 折り返し幅 (表示幅ベース、全角は2文字分)
16 * @param string $break 折り返しに挿入する文字列
17 * @param bool $cut_long_words 長い「単語」を途中で切るかどうか。
18 *     このシンプルな実装では単語の概念は考慮せず、表示幅で強制的に切ります。
19 *     そのため、実質的に常に true と同様の動作になります。
20 * @return string 折り返された文字列
21 */
22function mb_wordwrap(string $string, int $width = 75, string $break = "\n", bool $cut_long_words = false): string
23{
24    // mbstring 拡張が利用可能か確認。利用できない場合は警告を発し、元の文字列を返します。
25    // 実際の運用では、mbstring が必須である旨をより明確に伝えるか、代替策を考慮する必要があります。
26    if (!extension_loaded('mbstring')) {
27        trigger_error('mbstring extension is not loaded. Cannot use mb_wordwrap for multibyte string handling.', E_USER_WARNING);
28        return $string;
29    }
30
31    $lines = [];
32    $currentLine = '';
33    $currentWidth = 0;
34    // 文字列の長さをマルチバイト対応で取得
35    $length = mb_strlen($string, 'UTF-8');
36
37    for ($i = 0; $i < $length; $i++) {
38        // 1文字ずつマルチバイト対応で取得
39        $char = mb_substr($string, $i, 1, 'UTF-8');
40        // 1文字の表示幅をマルチバイト対応で取得 (全角:2, 半角:1)
41        $charWidth = mb_strwidth($char, 'UTF-8');
42
43        // 現在の行にこの文字を追加すると幅を超える場合
44        if ($currentWidth + $charWidth > $width) {
45            // 現在の行を確定し、新しい行に現在の文字から開始
46            $lines[] = $currentLine;
47            $currentLine = $char;
48            $currentWidth = $charWidth;
49        } else {
50            // 現在の行に文字を追加
51            $currentLine .= $char;
52            $currentWidth += $charWidth;
53        }
54    }
55
56    // 最後に残った行を追加
57    $lines[] = $currentLine;
58
59    // 折り返された行を結合して返す
60    return implode($break, $lines);
61}
62
63// ----------------------------------------------------------------------------------
64// サンプルコード本体
65// ----------------------------------------------------------------------------------
66
67// 長い日本語の文章
68$mbString = "これは日本語の長い文章です。PHPのwordwrap関数はバイト数を基準にするため、マルチバイト文字を正しく扱えません。この文章を折り返してみると問題がわかります。";
69
70echo "--- 標準 wordwrap 関数 (width=30, cut_long_words=true) --- \n";
71echo "（標準の wordwrap はバイト数で処理するため、日本語の途中で切れて文字化けすることがあります。）\n";
72// 標準の wordwrap はバイト数で幅を計算します。UTF-8の日本語1文字は通常3バイトなので、
73// width=30 の場合、約10文字程度で折り返され、文字の途中で切れる可能性があります。
74echo wordwrap($mbString, 30, "\n", true);
75echo "\n\n";
76
77echo "--- 自作 mb_wordwrap 関数 (width=30, cut_long_words=true) --- \n";
78echo "（自作 mb_wordwrap は表示幅で処理するため、日本語を正しく折り返します。）\n";
79// 自作の mb_wordwrap 関数は、全角文字を2文字幅、半角文字を1文字幅として幅を計算します。
80// width=30 の場合、約15文字程度（全角換算）で折り返され、日本語の表示が自然になります。
81echo mb_wordwrap($mbString, 30, "\n", true);
82echo "\n\n";
83
84// 別の例: 英数字と日本語が混在する場合
85$mixedString = "Hello, world! これは日本語の混在文字列の例です。This is an example of mixed string.";
86
87echo "--- 標準 wordwrap 関数 (width=20) ---\n";
88echo wordwrap($mixedString, 20, "\n", true);
89echo "\n\n";
90
91echo "--- 自作 mb_wordwrap 関数 (width=20) ---\n";
92echo mb_wordwrap($mixedString, 20, "\n", true);
93echo "\n\n";
94

PHPの標準関数であるwordwrapは、長い文字列を指定した幅で自動的に折り返すために使用されます。この関数は、引数$stringで入力文字列、$widthで折り返し幅、$breakで折り返し時に挿入する文字列（デフォルトは改行コード\n）、$cut_long_wordsで長い単語を途中で切るかを指定し、折り返された新しい文字列を戻り値として返します。

しかし、このwordwrap関数は文字のバイト数を基準に折り返し処理を行うため、日本語のようなマルチバイト文字を含む文字列では問題が発生することがあります。例えば、UTF-8エンコーディングの日本語1文字は通常3バイトであり、$widthで指定したバイト数を超えると、文字の途中で切れてしまい、意図しない場所で改行されたり、文字化けを引き起こす可能性があります。

このサンプルコードでは、この問題を解決するために自作のmb_wordwrap関数が提供されています。この関数は、mbstring拡張機能を利用して、文字の「表示幅」を基準に文字列を折り返します。具体的には、全角文字を2文字分の幅、半角文字を1文字分の幅として計算するため、日本語を含む文字列でも視覚的に自然な位置で折り返すことが可能です。mb_wordwrapもwordwrapと同様に、$string、$width、$break、$cut_long_wordsを引数にとり、折り返された文字列を返します。ただし、現在の実装では$cut_long_wordsは実質的に常にtrueとして動作します。この関数を使用するには、PHPのmbstring拡張機能が有効になっている必要があります。

サンプルコードの実行例では、長い日本語の文章や英数字と日本語が混在する文章を、標準のwordwrap関数と自作のmb_wordwrap関数でそれぞれ折り返した結果を比較しています。標準のwordwrapでは日本語が途中で不自然に切れて文字化けする可能性があるのに対し、mb_wordwrapでは文字化けすることなく、表示幅を考慮して正しく折り返されていることが確認できます。システム開発において日本語などのマルチバイト文字を扱う際には、このような表示幅を考慮した文字折り返し処理が非常に重要になります。

Copy
1<?php
2
3/**
4 * PHPのwordwrap関数の挙動をデモンストレーションします。
5 * 特に、長い単語が指定幅を超過する場合のデフォルトの動作と、
6 * そのような単語も強制的に改行する方法を示します。
7 *
8 * この関数は、「php wordwrap not working」という一般的な疑問に対し、
9 * 主に$cut_long_words引数の重要性を理解するのに役立ちます。
10 */
11function demonstrateWordwrapBehaviors(): void
12{
13    // 改行幅を超えやすい、非常に長い単語を含むサンプルテキスト
14    $longText = "This is a demonstration of the wordwrap function with "
15              . "an exceptionallylongwordthatwouldnaturallyexceedthespecifiedwidth "
16              . "and several other words to show how it behaves.";
17
18    // 短めの改行幅を設定し、効果をわかりやすくする
19    $width = 20;
20
21    echo "--- 元のテキスト ---\n";
22    echo $longText . "\n\n";
23
24    echo "--- wordwrap() のデフォルト動作 (cut_long_words = false) ---\n";
25    echo "（長い単語は途中で改行されず、指定幅を超過して表示されることがあります）\n";
26    $wrappedDefault = wordwrap($longText, $width);
27    echo $wrappedDefault . "\n\n";
28
29    echo "--- wordwrap() の強制改行動作 (cut_long_words = true) ---\n";
30    echo "（長い単語も強制的に途中で改行され、指定幅内に収まります）\n";
31    $wrappedCutLongWords = wordwrap($longText, $width, "\n", true);
32    echo $wrappedCutLongWords . "\n\n";
33}
34
35// 関数を実行して動作を確認します
36demonstrateWordwrapBehaviors();
37

PHPのwordwrap関数は、与えられた文字列を指定した文字幅で自動的に改行し、読みやすい形式に整形するための機能を提供します。

この関数は主に4つの引数を受け取ります。 最初の$stringには、改行処理を行いたい元の文字列を指定します。 次に$widthで、各行の最大文字数を整数で指定します。この幅を超えないように単語の区切りで改行が挿入されます。デフォルト値は75文字です。 第三引数$breakは、改行時に挿入される文字列を指定し、デフォルトではPHPの改行コードである\nが使用されます。

特に重要なのが第四引数$cut_long_wordsです。この引数は論理値（trueまたはfalse）を取り、デフォルトはfalseに設定されています。$cut_long_wordsがfalseの場合、指定された$widthよりも長い単語があったとしても、その単語は途中で切られずに一行に収められ、結果的に指定幅を超過して表示されることがあります。多くの場合、「php wordwrap not working」と感じられる原因はこのデフォルトの挙動によるものです。

一方、$cut_long_wordsをtrueに設定すると、どんなに長い単語であっても、指定された$widthを超過する部分で強制的に途中で改行が挿入されます。これにより、すべての行が指定幅内に確実に収まるようになります。

wordwrap関数は、これらの処理を施した新しい文字列を戻り値として返します。元の文字列は変更されません。この関数を理解し適切に引数を設定することで、テキストの表示レイアウトを柔軟に制御することができます。

Copy
1<?php
2
3/**
4 * マルチバイト文字（日本語など）に対応したwordwrap関数
5 *
6 * PHP標準のwordwrap()はバイト単位で文字列を処理するため、1文字が複数バイトで
7 * 構成される日本語を正しく扱うことができません。
8 * この関数は、文字数単位で文字列を安全に折り返します。
9 *
10 * @param string $string 対象の文字列
11 * @param int $width 折り返す文字数
12 * @param string $break 改行に使用する文字列
13 * @return string 折り返された文字列
14 */
15function mb_wordwrap(string $string, int $width = 75, string $break = "\n"): string
16{
17    // 文字列を指定した文字数で配列に分割する (PHP 8+)
18    $chunks = mb_str_split($string, $width, 'UTF-8');
19    // 分割した配列の要素を、指定した改行文字列で連結する
20    return implode($break, $chunks);
21}
22
23// サンプルとなる日本語の文章
24$japaneseText = 'この文章は、PHPのwordwrap関数を日本語で正しく扱うためのサンプルコードです。マルチバイト文字列を文字数に基づいて適切に折り返します。';
25
26// 折り返したい文字数
27$wrapWidth = 25;
28
29// 作成した関数を使用して、日本語文字列を25文字で折り返す
30$wrappedText = mb_wordwrap($japaneseText, $wrapWidth, PHP_EOL);
31
32// 結果を出力する (PHP_EOLは環境に合わせた改行コード)
33echo $wrappedText;
34
35echo PHP_EOL . PHP_EOL;
36
37echo "--- 参考: 標準のwordwrap()を使った場合（非推奨） ---" . PHP_EOL;
38// 標準のwordwrap()はバイト数で計算するため、文字化けや意図しない位置で改行される
39$brokenText = wordwrap($japaneseText, $wrapWidth, PHP_EOL, true);
40echo $brokenText;
41
42?>

このサンプルコードは、PHPで日本語のようなマルチバイト文字列を、指定した文字数で正しく折り返す方法を示しています。

PHPに標準で用意されているwordwrap関数は、文字列をバイト数で処理します。アルファベットは1文字1バイトなので問題ありませんが、日本語は1文字が複数バイトで構成されるため、wordwrap関数をそのまま使うと文字の途中で改行されてしまい、文字化けや不自然な分割の原因となります。

この問題を解決するため、サンプルではmb_wordwrapという独自の関数を作成しています。この関数は、内部でmb_str_split関数を使い、文字列をバイト数ではなく「文字数」で正確に分割します。第一引数に処理対象の文字列、第二引数に折り返したい文字数を指定します。その後、implode関数によって、分割された文字列の断片を、第三引数で指定した改行コード（サンプルではPHP_EOL）で連結します。

戻り値として、指定した文字数で適切に改行が挿入された新しい文字列が返されます。このように、日本語を含む文章を扱う場合は、文字数を基準に処理する関数を自作することで、意図した通りに文字列を折り返すことができます。