wp_remote_post()
云策文档标注
概述
wp_remote_post() 是 WordPress 中用于执行 HTTP POST 请求的核心函数，返回响应数组或 WP_Error 对象。开发者需注意安全性和参数配置。
关键要点
- 函数用于执行 POST 请求，接受 URL 和可选参数数组，返回响应或错误。
- 若 URL 为用户控制，推荐使用 wp_safe_remote_post() 以增强安全性。
- 参数 $args 可配置超时、头部、body 等，详见 WP_Http::request()。
- 返回值为数组（包含响应数据）或 WP_Error 对象，需用 is_wp_error() 检查错误。
- 函数自 WordPress 2.7.0 引入，广泛用于核心更新、API 调用等场景。
代码示例
// 基本 POST 请求示例
$response = wp_remote_post( $url, array(
'body' => array( 'key' => 'value' ),
'timeout' => 30
) );
// 错误处理
if ( is_wp_error( $response ) ) {
$error_message = $response->get_error_message();
echo "错误: $error_message";
} else {
echo '响应: ' . print_r( $response, true );
}注意事项
- 避免将 sslverify 设置为 false，除非在受控环境中，否则可能导致安全风险。
- 对于 JSON 数据，需设置 Content-Type 头部为 application/json 并使用 wp_json_encode()。
- 可通过 method 参数执行 GET 请求，但更推荐使用 wp_remote_get() 专门函数。
- 在 WordPress REST API 认证中，可能需要传递 _wpnonce 和 cookies 参数。
原文内容
Performs an HTTP request using the POST method and returns its response.
Description
Important: If the URL is user-controlled, use wp_safe_remote_post() instead.
See also
- wp_remote_request(): For more information on the response array format.
- WP_Http::request(): For default arguments information.
Parameters
$urlstringrequired-
URL to retrieve.
$argsarrayoptional-
Request arguments.
See WP_Http::request() for information on accepted arguments.Default:
array()
Source
function wp_remote_post( $url, $args = array() ) {
$http = _wp_http_get_object();
return $http->post( $url, $args );
}
Changelog
| Version | Description |
|---|---|
| 2.7.0 | Introduced. |
Skip to note 8 content
Claudio Sanches
Exemple of Basic Authentication:
$response = wp_remote_post( $url, array( 'body' => $data, 'headers' => array( 'Authorization' => 'Basic ' . base64_encode( $username . ':' . $password ), ), ) );Skip to note 9 content
Codex
Post data should be sent in the body as an array. Example passing post data:
$response = wp_remote_post( $url, array( 'method' => 'POST', 'timeout' => 45, 'redirection' => 5, 'httpversion' => '1.0', 'blocking' => true, 'headers' => array(), 'body' => array( 'username' => 'bob', 'password' => '1234xyz' ), 'cookies' => array() ) ); if ( is_wp_error( $response ) ) { $error_message = $response->get_error_message(); echo "Something went wrong: $error_message"; } else { echo 'Response:<pre>'; print_r( $response ); echo '</pre>'; }In the example above,
$response['body']will contain the actual page content returned by the server.Skip to note 10 content
Pixelbart
An example of a JSON body:
$endpoint = 'api.example.com'; $body = [ 'name' => 'Pixelbart', 'email' => 'pixelbart@example.com', ]; $body = wp_json_encode( $body ); $options = [ 'body' => $body, 'headers' => [ 'Content-Type' => 'application/json', ], 'timeout' => 60, 'redirection' => 5, 'blocking' => true, 'httpversion' => '1.0', 'sslverify' => false, 'data_format' => 'body', ]; wp_remote_post( $endpoint, $options );Skip to note 11 content
Mehedi Foysal
$apiUrl = 'https://api.example.com'; $apiResponse = wp_remote_post( $apiUrl, [ 'method' => 'GET', 'sslverify' => false, 'headers' => [ 'content-type' => 'application/json', 'user_key' => 'xxxxxxxxxxxxx', ], ] ); $apiBody = json_decode( wp_remote_retrieve_body( $apiResponse ) );Skip to note 12 content
Manny (emanweb)
See also wp_safe_remote_post(), especially if you are using a dynamic URL call.
Skip to note 13 content
ouija
A couple notes I thought worth mentioning is that if you’re using a WordPress API endpoint that requires authentication, you can pass the
_wpnonceparameter along with the session cookies to properly authenticate, like so:$endpoint = get_rest_url( null, 'ninja-forms-submissions/submissions/get' ); $body = array( '_wpnonce' => wp_create_nonce( 'wp_rest' ), 'type' => 'columns', 'form_ids' => '1' ); // Need session cookies passed to verify nonce $cookies = array(); foreach ( $_COOKIE as $name => $value ) { $cookies[] = new WP_Http_Cookie( array( 'name' => $name, 'value' => $value ) ); } $options = array( 'method'. => 'GET', 'body' => $body, 'headers' => array( 'Cache-Control' => 'no-cache', ), 'timeout' => 60, 'redirection' => 5, 'blocking' => true, 'httpversion' => '1.0', 'sslverify' => false, 'data_format' => 'body', 'cookies' => $cookies ); $response = wp_remote_post( $endpoint, $options );Note that I’m also using
wp_remote_postto perform aGETcall in this example (by passing the ‘method’ argument), otherwise I could use the wp_remote_get function insteadSkip to note 14 content
Jason Norwood-Young
Handle errors using is_wp_error() as follows:
$args = array( 'headers' => array( 'Authorization' => 'Bearer 123hash', 'Content-Type' => 'application/json', ), 'timeout' => 0.001, // This should give you a timeout error, unless you are hitting something spectacularly fast 'body' => json_encode( array( 'blah' => 'yack' ) ), ); $response = wp_remote_post( 'https://developer.wordpress.org', $args ); if ( ! is_wp_error( $response ) ) { $body = json_decode( wp_remote_retrieve_body( $response ), true ); return $body; } else { $error_message = $response->get_error_message(); throw new Exception( $error_message ); }