parse_url() 是 PHP 解析 URL 的標準工具,能將 URL 分解為 scheme、host、path、query、fragment 等組件。然而,其對不完整 URL、相對路徑、特殊字元的處理行為常導致誤解。本文深入解析函式行為、參數選項、實戰應用與替代方案。
parse_url(string $url, int $component = -1): array|string|int|float|false|null
$url:要解析的 URL 字串$component:可選,指定回傳特定組件常數(見下表)false| 常數 | 對應組件 | 回傳型別 | 範例值 |
|---|---|---|---|
PHP_URL_SCHEME | 協定 | string | https |
PHP_URL_HOST | 主機名 | string | example.com |
PHP_URL_PORT | 連接埠 | int | 443 |
PHP_URL_USER | 使用者名稱 | string | username |
PHP_URL_PASS | 密碼 | string | password |
PHP_URL_PATH | 路徑 | string | /path/to/resource |
PHP_URL_QUERY | 查詢字串 | string | id=123&sort=desc |
PHP_URL_FRAGMENT | 片段識別碼 | string | section1 |
<?php
$url = 'https://user:pass@example.com:443/path/to/page?query=value#section';
$result = parse_url($url);
print_r($result);
/*
Array
(
[scheme] => https
[host] => example.com
[port] => 443
[user] => user
[pass] => pass
[path] => /path/to/page
[query] => query=value
[fragment] => section
)
*/
// 取得單一組件
echo parse_url($url, PHP_URL_HOST); // example.com
echo parse_url($url, PHP_URL_PATH); // /path/to/page
echo parse_url($url, PHP_URL_QUERY); // query=value
?>
<?php
// 無 scheme:path 會包含整個字串
parse_url('example.com/path?query=1');
/*
[
'path' => 'example.com/path',
'query' => 'query=1'
]
// host 為空!因為無 scheme 視為相對路徑
*/
// 修正:補上 scheme
parse_url('https://example.com/path?query=1'); // 正確解析 host
?>
<?php
parse_url('/api/users/123');
// ['path' => '/api/users/123']
?>
<?php
// 中文路徑(需 URL 編碼)
parse_url('https://example.com/中文路徑');
// ['host' => 'example.com', 'path' => '/中文路徑'] (PHP 會保留原始字元)
// IPv6 主機
parse_url('https://[2001:db8::1]:8080/path');
// ['scheme'=>'http', 'host'=>'2001:db8::1', 'port'=>8080, 'path'=>'/path']
// 使用者資訊含特殊字元
parse_url('ftp://user%40name:pass%23word@ftp.example.com');
// ['user'=>'user@name', 'pass'=>'pass#word'] (自動 URL 解碼)
?>
<?php
var_dump(parse_url('')); // false
var_dump(parse_url('not a url')); // false (PHP 8.1+ 嚴格模式)
// PHP 8.0 及以前可能回傳部分解析結果
?>
parse_url() 只回傳原始查詢字串,需搭配 parse_str() 解析為陣列:
<?php
$url = 'https://api.example.com/search?q=php&tag=web&tag=backend&page=2';
$parts = parse_url($url);
$queryString = $parts['query'] ?? '';
parse_str($queryString, $queryArray);
print_r($queryArray);
/*
Array
(
[q] => php
[tag] => Array ( [0] => web, [1] => backend )
[page] => 2
)
*/
// 完整封裝函式
function parseUrlComplete(string $url): array {
$parts = parse_url($url);
if ($parts === false) return [];
$query = [];
if (!empty($parts['query'])) {
parse_str($parts['query'], $query);
}
$parts['query_params'] = $query;
return $parts;
}
?>
<?php
function normalizeUrl(string $url): string {
$parts = parse_url($url);
if ($parts === false || empty($parts['scheme']) || empty($parts['host'])) {
throw new InvalidArgumentException('Invalid URL');
}
$normalized = $parts['scheme'] . '://';
if (!empty($parts['user'])) {
$normalized .= $parts['user'];
if (!empty($parts['pass'])) $normalized .= ':' . $parts['pass'];
$normalized .= '@';
}
$normalized .= $parts['host'];
if (!empty($parts['port'])) $normalized .= ':' . $parts['port'];
$normalized .= $parts['path'] ?? '/';
if (!empty($parts['query'])) $normalized .= '?' . $parts['query'];
if (!empty($parts['fragment'])) $normalized .= '#' . $parts['fragment'];
return $normalized;
}
?>
<?php
function isSameOrigin(string $url1, string $url2): bool {
$p1 = parse_url($url1);
$p2 = parse_url($url2);
return ($p1['scheme'] ?? '') === ($p2['scheme'] ?? '')
&& ($p1['host'] ?? '') === ($p2['host'] ?? '')
&& ($p1['port'] ?? ($p1['scheme'] === 'https' ? 443 : 80))
=== ($p2['port'] ?? ($p2['scheme'] === 'https' ? 443 : 80));
}
?>
<?php
function safeRedirect(string $target, array $allowedHosts): void {
$parts = parse_url($target);
if ($parts === false) {
throw new Exception('Invalid redirect URL');
}
// 僅允許相對路徑或白名單主機
if (empty($parts['host']) || in_array($parts['host'], $allowedHosts, true)) {
header('Location: ' . $target, true, 302);
exit;
}
throw new Exception('Redirect to external host not allowed');
}
// 使用
safeRedirect('/dashboard', ['example.com']); // 允許相對路徑
safeRedirect('https://example.com/path', ['example.com']); // 允許白名單
// safeRedirect('https://evil.com', ['example.com']); // 拋出例外
?>
<?php
function buildUrl(array $parts): string {
$url = '';
if (!empty($parts['scheme'])) $url .= $parts['scheme'] . '://';
if (!empty($parts['user'])) {
$url .= $parts['user'];
if (!empty($parts['pass'])) $url .= ':' . $parts['pass'];
$url .= '@';
}
if (!empty($parts['host'])) $url .= $parts['host'];
if (!empty($parts['port'])) $url .= ':' . $parts['port'];
if (!empty($parts['path'])) $url .= $parts['path'];
if (!empty($parts['query'])) $url .= '?' . $parts['query'];
if (!empty($parts['fragment'])) $url .= '#' . $parts['fragment'];
return $url;
}
// 也可用 http_build_query 組合 query
$query = http_build_query(['q' => 'php', 'page' => 2]); // q=php&page=2
?>
<?php
// composer require league/uri
use League\Uri\Http;
$uri = Http::createFromString('https://user:pass@example.com:443/path?query=value#frag');
echo $uri->getHost(); // example.com
echo $uri->getPort(); // 443
$uri = $uri->withPath('/new/path')->withQuery('new=value');
echo (string)$uri; // 完整 URL 字串
?>
無需外部依賴即可處理 90% 場景。
parse_url() 回傳的 path 仍為 URL 編碼狀態,需自行 urldecode()parse_str()false 而非部分結果parse_url() 是 PHP 處理 URL 的基石函式,掌握其組件結構、邊界行為、查詢字串二次解析、安全重導向防護,是後端開發必備技能。現代專案建議引入 league/uri 或 nyholm/psr7 等 PSR-7 相容 URI 物件,獲得型別安全、不可變操作、標準化介面,減少字串操作錯誤。