PHP 基礎語法入門：標記、空白與註釋

PHP 基礎語法入門：標記、空白與註釋

PHP 代碼嵌入 HTML 的方式、空白處理規則、註釋風格是入門必修課。本文系統梳理基礎語法規範，助力新手建立良好編碼習慣。

一、PHP 標記風格

最佳實踐

<!-- 僅 PHP 文件，無 HTML 輸出時，省略閉合標記防止輸出空白 -->
<?php
declare(strict_types=1);

namespace App;

class User {
    // ...
}
// 無 ?>

<!-- 模板文件中輸出 -->
<h1><?= htmlspecialchars($title) ?></h1>
<p><?= $content ?></p>

二、PHP 註釋規範

標準 DocBlock 示例

<?php
/**
 * 用戶服務類
 *
 * 處理用戶註冊、認證、資料管理等核心業務
 *
 * @package App\Services
 * @author Zhang San <zhangsan@example.com>
 * @since 2024-01-15
 * @version 1.2.0
 */
class UserService {
    /**
     * 註冊新用戶
     *
     * @param string $email 郵箱地址（唯一）
     * @param string $password 明文密碼（將自動哈希）
     * @param array $profile 額外資料 [nickname, avatar, ...]
     * @return int 新用戶 ID
     * @throws ValidationException 參數驗證失敗
     * @throws DuplicateEntryException 郵箱已存在
     */
    public function register(string $email, string $password, array $profile = []): int {
        // 實現...
    }
}
?>

三、空白處理規則

空白字符定義

• 空格 (Space, ` `)
• 制表符 (Tab, `\t`)
• 換行符 (Line Feed, `\n`)
• 回車符 (Carriage Return, `\r`)

PHP 引擎對空白的處理

1. 標記外的空白原樣輸出：`?> 文本
2. 標記內的空白被忽略：語句間的多個空白等同於單個空白。
3. 語句結束需分號：空白不能替代分號。
4. 字符串內空白保留：單雙引號、Heredoc/Nowdoc 內空白按字面保留。

編碼風格約定（PSR-12 核心節選）

<?php
// 1. 縮進：4 個空格，禁用 Tab
// 2. 行長：軟限制 80，硬限制 120
// 3. 命名空間聲明後空一行
// 4. use 聲明組後空一行
// 5. 類/方法/函數左大括號換行，右大括號獨佔行
// 6. 控制結構關鍵字後一空格，左括號無空格
if ($condition) {
    // ...
} elseif ($other) {
    // ...
} else {
    // ...
}

// 7. 方法參數：逗號後一空格，默認值緊貼等號
public function foo(string $bar, int $baz = 0): void {}

// 8. 陣列：短語法，尾隨逗號
$arr = [
    'key' => 'value',
    'long_key' => 'long_value',
];

// 9. 空行分隔邏輯塊
$users = getUsers();

$activeUsers = array_filter($users, fn($u) => $u->isActive());

foreach ($activeUsers as $user) {
    process($user);
}
?>

常見新手錯誤

1. 閉合標記後的空白導致「Headers already sent」：純 PHP 文件省略 `?>`。
2. 混用 Tab/空格導致縮進混亂：編輯器設置「Tab = 4 Spaces」。
3. 缺少 DocBlock 導致 IDE 無智能提示：養成寫文檔註釋習慣。
4. Heredoc 結束標記前有空格：`END;` 必須頂格獨佔行。

遵循統一語法風格，能減少低級錯誤，提升團隊協作效率，也是代碼專業度的體現。