PHP curl_escape 函数

最后修改日期：2025 年 4 月 11 日

PHP curl_escape 函数对给定的字符串进行 URL 编码。它是 cURL 扩展的一部分，用于正确编码用于 URL 的字符串。此函数将不安全的 ASCII 字符替换为 % 后跟两个十六进制数字。

基本定义

curl_escape 函数对用于 URL 的字符串进行编码。它返回编码后的字符串，失败时返回 FALSE。该函数需要一个活动的 cURL 句柄和要编码的字符串。

语法：curl_escape(CurlHandle $handle, string $string): string|false。必须使用 curl_init() 创建句柄。使用后务必使用 curl_close() 关闭句柄。

基本字符串编码

此示例演示了简单字符串的基本 URL 编码。

basic_encoding.php

<?php

declare(strict_types=1);

$ch = curl_init();

$string = "Hello World!";
$encoded = curl_escape($ch, $string);

echo "Original: " . $string . "\n";
echo "Encoded: " . $encoded . "\n";

curl_close($ch);

此代码对包含空格和标点符号的简单字符串进行编码。空格字符转换为 %20，感叹号变为 %21。输出显示了原始版本和编码版本。

编码查询参数

此示例显示了如何为 URL 正确编码查询参数。

query_parameters.php

<?php

declare(strict_types=1);

$ch = curl_init();

$search = "PHP & MySQL";
$encodedSearch = curl_escape($ch, $search);

$url = "https://example.com/search?q=" . $encodedSearch;
echo "Encoded URL: " . $url . "\n";

curl_close($ch);

我们对包含空格和特殊字符的搜索查询进行编码。& 符号转换为 %26，空格转换为 %20。这确保了在将 URL 发送到服务器时 URL 保持有效且格式正确。

编码路径段

此示例演示了 URL 的路径段编码。

path_segments.php

<?php

declare(strict_types=1);

$ch = curl_init();

$category = "Programming Books";
$title = "PHP 8 Essentials";

$url = "https://example.com/" . 
       curl_escape($ch, $category) . "/" . 
       curl_escape($ch, $title);
       
echo "Encoded URL: " . $url . "\n";

curl_close($ch);

我们对包含空格的多个路径段进行编码。每个段单独编码以保持正确的 URL 结构。路径段中的空格转换为 %20，确保 URL 保持有效。

与 urlencode 比较

此示例将 curl_escape 与 PHP 的内置 urlencode 函数进行比较。

compare_urlencode.php

<?php

declare(strict_types=1);

$ch = curl_init();

$string = "user@example.com";

$curlEncoded = curl_escape($ch, $string);
$phpEncoded = urlencode($string);

echo "curl_escape: " . $curlEncoded . "\n";
echo "urlencode: " . $phpEncoded . "\n";

curl_close($ch);

我们使用两个函数对同一个字符串进行编码以查看差异。curl_escape 将 @ 符号编码为 %40，而 urlencode 则保持不变。curl_escape 对特殊字符的编码更为严格。

编码复杂字符串

此示例显示了包含各种特殊字符的复杂字符串编码。

complex_string.php

<?php

declare(strict_types=1);

$ch = curl_init();

$complexString = "Price: $19.99 (50% off!) #deal";
$encoded = curl_escape($ch, $complexString);

echo "Original: " . $complexString . "\n";
echo "Encoded: " . $encoded . "\n";

curl_close($ch);

我们对包含空格、美元符号、百分号、括号和哈希符号的字符串进行编码。每个特殊字符都为 URL 使用进行了正确编码。结果显示了 curl_escape 如何处理各种字符类型。

最佳实践

句柄初始化：始终先创建 cURL 句柄。
错误检查：验证函数是否不返回 FALSE。
资源清理：使用 curl_close 关闭句柄。
上下文相关：用于 URL，而不是表单数据编码。
特殊字符：根据您的具体用例进行测试。

来源

PHP curl_escape 文档

本教程通过实际示例介绍了 PHP curl_escape 函数，展示了其在各种场景下用于 URL 编码的用法。

作者

我叫 Jan Bodnar，我是一名充满激情的程序员，拥有丰富的编程经验。我从 2007 年开始撰写编程文章。迄今为止，我已撰写了 1400 多篇文章和 8 本电子书。我在教授编程方面拥有十多年的经验。

所有 PHP cURL 教程列表。