萬盛學電腦網

您现在的位置: 萬盛學電腦網 >> 程式設計 >  >> 網路程式設計 >> PHP 程式設計

PHP wordwrap() 文字換行格式化完整指南與實務應用

前言

wordwrap() 依指定寬度將長字串換行,保持單字完整不截斷。常用於郵件內容格式化、終端機輸出、PDF 文字排版、回應訊息長度限制等場景。

基本語法與參數

<?php
wordwrap(
    string $string,      // 輸入字串
    int $width = 75,     // 每行最大字元數
    string $break = "\n", // 換行字串
    bool $cut = false    // true=強制截斷長單字,false=保持單字完整
): string

基本用法示範

<?php
$string = "TRADING ON MARGIN POSES ADDITIONAL RISKS AND IS NOT SUITABLE FOR ALL INVESTORS. A COMPLETE LIST OF THE RISKS ASSOCIATED WITH MARGIN TRADING IS AVAILABLE IN THE MARGIN RISK DISCLOSURE DOCUMENT.";

// 預設 75 字元換行
echo wordwrap($string) . "\n";

// 自訂寬度 40
echo wordwrap($string, 40) . "\n";

// 自訂換行標記(HTML 
) echo wordwrap($string, 40, "
\n") . "\n"; // 強制截斷長單字 $longWord = "Supercalifragilisticexpialidocious"; echo wordwrap($longWord, 10, "\n", true) . "\n"; // Supercali // fragilist // icexpiali // docious ?>

實務應用場景

1. 純文字郵件內容格式化(RFC 5322 建議 78 字元)

<?php
function formatPlainTextEmail(string $body, int $width = 78): string {
    // 先正規化換行
    $body = str_replace(["\r\n", "\r"], "\n", $body);
    // 段落分割(雙換行)
    $paragraphs = explode("\n\n", $body);
    
    $formatted = [];
    foreach ($paragraphs as $para) {
        // 單一段落內換行轉空白
        $para = preg_replace('/\s+/', ' ', trim($para));
        // 依寬度換行
        $formatted[] = wordwrap($para, $width);
    }
    
    return implode("\n\n", $formatted);
}

$raw = "這是一段很長的郵件內容,包含多個句子。\n\n這是第二段。";
echo formatPlainTextEmail($raw);
?>

2. 終端機 CLI 輸出美化

<?php
function cliWrap(string $text, int $width = 0): string {
    // 自動偵測終端機寬度
    if ($width === 0) {
        $width = (int)(exec('tput cols 2>/dev/null') ?: 80);
    }
    return wordwrap($text, $width);
}

echo cliWrap("這是一個很長的說明文字,會根據終端機寬度自動換行顯示,提供更好的閱讀體驗。");
?>

3. 簡訊/推播訊息長度限制與分段

<?php
function splitSms(string $message, int $maxLength = 160): array {
    // 先按單字換行
    $wrapped = wordwrap($message, $maxLength, "\n", false);
    $segments = explode("\n", $wrapped);
    
    // 如果單段仍過長(單字超過限制),強制切割
    $result = [];
    foreach ($segments as $seg) {
        if (mb_strlen($seg) <= $maxLength) {
            $result[] = $seg;
        } else {
            // 強制按字元切割
            $result = array_merge($result, mb_str_split($seg, $maxLength));
        }
    }
    return $result;
}

$longMsg = "這是一條非常長的簡訊內容,超過了單條簡訊的字元限制,需要自動分段發送...";
$parts = splitSms($longMsg, 70); // 中文簡訊通常 70 字
foreach ($parts as $i => $part) {
    echo "第 " . ($i+1) . " 段 (" . mb_strlen($part) . " 字): $part\n";
}
?>

4. 程式碼/日誌輸出格式化

<?php
function formatLogLine(string $message, int $maxLen = 120): string {
    // 單行過長時換行,保持可讀性
    if (mb_strlen($message) <= $maxLen) return $message;
    
    return wordwrap($message, $maxLen, "\n" . str_repeat(' ', 20), false);
    // 續行縮進 20 空白對齊
}

$log = "[INFO] User login successful: user_id=12345 ip=192.168.1.100 user_agent=Mozilla/5.0...";
echo formatLogLine($log);
?>

5. HTML 內容安全換行(保留標籤)

<?php
function wordwrapHtml(string $html, int $width = 80): string {
    // 簡易版:只在文字節點換行,不破壞標籤
    // 完整版建議使用 DOMDocument 解析
    $parts = preg_split('/(<[^>]+>)/', $html, -1, PREG_SPLIT_DELIM_CAPTURE);
    
    $result = '';
    foreach ($parts as $part) {
        if (str_starts_with($part, '<') && str_ends_with($part, '>')) {
            $result .= $part; // 標籤保持不變
        } else {
            $result .= wordwrap($part, $width, "\n", false);
        }
    }
    return $result;
}
?>

進階參數:$cut = true vs false

參數行為適用場景
$cut = false (預設)單字超過寬度不截斷,允許該行超寬一般文字、保持可讀性、避免單字破碎
$cut = true強制在寬度截斷,單字會被切斷固定寬度欄位、終端機表格、嚴格長度限制

中文/多位元組字元處理

<?php
// wordwrap 按位元組計算寬度,中文會誤判
$chinese = "這是一段中文測試文字";
echo wordwrap($chinese, 10, "\n", false);
// 實際寬度計算錯誤

// 解決方案:使用 mb_strwidth 計算視覺寬度
function mbWordwrap(string $str, int $width, string $break = "\n", bool $cut = false): string {
    $lines = [];
    $currentLine = '';
    $currentWidth = 0;
    
    $words = preg_split('/(\s+)/u', $str, -1, PREG_SPLIT_DELIM_CAPTURE);
    
    foreach ($words as $word) {
        $wordWidth = mb_strwidth($word);
        
        if ($currentWidth + $wordWidth <= $width) {
            $currentLine .= $word;
            $currentWidth += $wordWidth;
        } else {
            if ($currentLine !== '') {
                $lines[] = $currentLine;
            }
            if ($cut && $wordWidth > $width) {
                // 強制切割單字
                $chunks = mb_str_split($word, (int)($width / mb_strwidth($word[0] ?? 'a')));
                $lines[] = $chunks[0];
                for ($i = 1; $i < count($chunks); $i++) {
                    $lines[] = $chunks[$i];
                }
                $currentLine = '';
                $currentWidth = 0;
            } else {
                $currentLine = $word;
                $currentWidth = $wordWidth;
            }
        }
    }
    if ($currentLine !== '') $lines[] = $currentLine;
    
    return implode($break, $lines);
}

echo mbWordwrap($chinese, 10, "\n");
?>

效能考量

  • wordwrap() 為 C 層實作,效能極佳
  • 大量文字處理時,避免重複呼叫,合併處理
  • 中文處理需自行實作 mb_wordwrap,效能較低,可接受

總結

  • wordwrap() 是 PHP 內建高效的文字換行工具
  • 核心參數:width (行寬)、break (換行符)、cut (是否強制截斷)
  • 郵件格式化:RFC 5322 建議 78 字元,段落間雙換行
  • 中文處理:需自行實作 mb_wordwrap() 使用 mb_strwidth()
  • HTML 內容:簡易版可用正則分割標籤/文字,完整版建議 DOMDocument
  • 不適用場景:程式碼格式化(需語法感知)、複雜排版(用 CSS/PDF 庫)
copyright © 萬盛學電腦網 all rights reserved