Http

💡 云策文档标注

概述

本文档介绍了 WordPress 中用于处理 HTTP 代理连接的 Http 类，该类实现了 Proxy 接口，提供通过 HTTP 代理进行网络请求的处理器。核心功能包括构造函数参数处理、cURL 和 fsockopen 回调注册，以及代理认证支持。

关键要点

Http 类是一个 final 类，实现了 Proxy 接口，用于管理 HTTP 代理连接。
构造函数支持字符串或数组参数来设置代理主机、端口、用户名和密码，并包含参数验证。
通过 register 方法注册回调函数，以在 cURL 和 fsockopen 请求中设置代理参数和认证头。
提供多个方法如 curl_before_send、fsockopen_remote_socket 等，用于在请求发送前调整代理设置。
支持代理认证，通过 get_auth_string 方法生成认证字符串，并在需要时添加 Proxy-Authorization 头。

代码示例

public function __construct($args = null) {
    if (is_string($args)) {
        $this->proxy = $args;
    } elseif (is_array($args)) {
        if (count($args) === 1) {
            list($this->proxy) = $args;
        } elseif (count($args) === 3) {
            list($this->proxy, $this->user, $this->pass) = $args;
            $this->use_authentication                    = true;
        } else {
            throw ArgumentCount::create(
                'an array with exactly one element or exactly three elements',
                count($args),
                'proxyhttpbadargs'
            );
        }
    } elseif ($args !== null) {
        throw InvalidArgument::create(1, '$args', 'array|string|null', gettype($args));
    }
}

注意事项

构造函数参数 $args 可以是字符串（仅代理）、数组（一个或三个元素）或 null，否则会抛出异常。
使用认证时，需提供用户名和密码，并通过 use_authentication 属性启用。
该类自 WordPress 1.6 版本引入，适用于需要代理支持的 HTTP 请求场景。

📄 原文内容

HTTP Proxy connection interface

Description

Provides a handler for connection via an HTTP proxy

Methods

Name	Description
Http::__construct	Constructor
Http::curl_before_send	Set cURL parameters before the data is sent
Http::fsockopen_header	Add extra headers to the request before sending
Http::fsockopen_remote_host_path	Alter remote path before getting stream data
Http::fsockopen_remote_socket	Alter remote socket information before opening socket connection
Http::get_auth_string	Get the authentication string (user:pass)
Http::register	Register the necessary callbacks

Source

final class Http implements Proxy {
	/**
	 * Proxy host and port
	 *
	 * Notation: "host:port" (eg 127.0.0.1:8080 or someproxy.com:3128)
	 *
	 * @var string
	 */
	public $proxy;

	/**
	 * Username
	 *
	 * @var string
	 */
	public $user;

	/**
	 * Password
	 *
	 * @var string
	 */
	public $pass;

	/**
	 * Do we need to authenticate? (ie username & password have been provided)
	 *
	 * @var boolean
	 */
	public $use_authentication;

	/**
	 * Constructor
	 *
	 * @since 1.6
	 *
	 * @param array|string|null $args Proxy as a string or an array of proxy, user and password.
	 *                                When passed as an array, must have exactly one (proxy)
	 *                                or three elements (proxy, user, password).
	 *
	 * @throws WpOrgRequestsExceptionInvalidArgument When the passed argument is not an array, a string or null.
	 * @throws WpOrgRequestsExceptionArgumentCount On incorrect number of arguments (`proxyhttpbadargs`)
	 */
	public function __construct($args = null) {
		if (is_string($args)) {
			$this->proxy = $args;
		} elseif (is_array($args)) {
			if (count($args) === 1) {
				list($this->proxy) = $args;
			} elseif (count($args) === 3) {
				list($this->proxy, $this->user, $this->pass) = $args;
				$this->use_authentication                    = true;
			} else {
				throw ArgumentCount::create(
					'an array with exactly one element or exactly three elements',
					count($args),
					'proxyhttpbadargs'
				);
			}
		} elseif ($args !== null) {
			throw InvalidArgument::create(1, '$args', 'array|string|null', gettype($args));
		}
	}

	/**
	 * Register the necessary callbacks
	 *
	 * @since 1.6
	 * @see WpOrgRequestsProxyHttp::curl_before_send()
	 * @see WpOrgRequestsProxyHttp::fsockopen_remote_socket()
	 * @see WpOrgRequestsProxyHttp::fsockopen_remote_host_path()
	 * @see WpOrgRequestsProxyHttp::fsockopen_header()
	 * @param WpOrgRequestsHooks $hooks Hook system
	 */
	public function register(Hooks $hooks) {
		$hooks->register('curl.before_send', [$this, 'curl_before_send']);

		$hooks->register('fsockopen.remote_socket', [$this, 'fsockopen_remote_socket']);
		$hooks->register('fsockopen.remote_host_path', [$this, 'fsockopen_remote_host_path']);
		if ($this->use_authentication) {
			$hooks->register('fsockopen.after_headers', [$this, 'fsockopen_header']);
		}
	}

	/**
	 * Set cURL parameters before the data is sent
	 *
	 * @since 1.6
	 * @param resource|CurlHandle $handle cURL handle
	 */
	public function curl_before_send(&$handle) {
		curl_setopt($handle, CURLOPT_PROXYTYPE, CURLPROXY_HTTP);
		curl_setopt($handle, CURLOPT_PROXY, $this->proxy);

		if ($this->use_authentication) {
			curl_setopt($handle, CURLOPT_PROXYAUTH, CURLAUTH_ANY);
			curl_setopt($handle, CURLOPT_PROXYUSERPWD, $this->get_auth_string());
		}
	}

	/**
	 * Alter remote socket information before opening socket connection
	 *
	 * @since 1.6
	 * @param string $remote_socket Socket connection string
	 */
	public function fsockopen_remote_socket(&$remote_socket) {
		$remote_socket = $this->proxy;
	}

	/**
	 * Alter remote path before getting stream data
	 *
	 * @since 1.6
	 * @param string $path Path to send in HTTP request string ("GET ...")
	 * @param string $url Full URL we're requesting
	 */
	public function fsockopen_remote_host_path(&$path, $url) {
		$path = $url;
	}

	/**
	 * Add extra headers to the request before sending
	 *
	 * @since 1.6
	 * @param string $out HTTP header string
	 */
	public function fsockopen_header(&$out) {
		$out .= sprintf("Proxy-Authorization: Basic %srn", base64_encode($this->get_auth_string()));
	}

	/**
	 * Get the authentication string (user:pass)
	 *
	 * @since 1.6
	 * @return string
	 */
	public function get_auth_string() {
		return $this->user . ':' . $this->pass;
	}
}

View all references View on Trac View on GitHub

Changelog

Version	Description
1.6	Introduced.

云策 WordPress 开发者社区

类文档