~~~php <?php namespace Psr\Http\Message; /** * URI 数据对象。 * * 此接口按照 RFC 3986 来构建 HTTP URI，提供了一些通用的操作，你可以自由的对此接口 * 进行扩展。你可以使用此 URI 接口来做 HTTP 相关的操作，也可以使用此接口做任何 URI * 相关的操作。 * * 此接口的实例化对象被视为无法修改的，所有能修改状态的方法，都 **必须** 有一套机制，在内部保 * 持好原有的内容，然后把修改状态后的，新的实例返回。 * * 通常，HOST 信息也将出现在请求消息中。对于服务器端的请求，通常可以在服务器参数中发现此信息。 * * @see [URI 通用标准规范](http://tools.ietf.org/html/rfc3986) */ interface UriInterface { /** * 从 URI 中取出 scheme。 * * 如果不存在 Scheme，此方法 **必须** 返回空字符串。 * * 根据 RFC 3986 规范 3.1 章节，返回的数据 **必须** 是小写字母。 * * 最后部分的「:」字串不属于 Scheme，**不得** 作为返回数据的一部分。 * * @see https://tools.ietf.org/html/rfc3986#section-3.1 * @return string URI Ccheme 的值。 */ public function getScheme(); /** * 返回 URI 认证信息。 * * 如果没有 URI 认证信息的话，**必须** 返回一个空字符串。 * * URI 的认证信息语法是： * * <pre> * [user-info@]host[:port] * </pre> * * 如果端口部分没有设置，或者端口不是标准端口，**不应该** 包含在返回值内。 * * @see https://tools.ietf.org/html/rfc3986#section-3.2 * @return string URI 认证信息，格式为：「[user-info@]host[:port]」。 */ public function getAuthority(); /** * 从 URI 中获取用户信息。 * * 如果不存在用户信息，此方法 **必须** 返回一个空字符串。 * * 如果 URI 中存在用户，则返回该值；此外，如果密码也存在，它将附加到用户值，用冒号（「:」）分隔。 * * 用户信息后面跟着的 "@" 字符，不是用户信息里面的一部分，**不得** 在返回值里出现。 * * @return string URI 的用户信息，格式："username[:password]" */ public function getUserInfo(); /** * 从 URI 中获取 HOST 信息。 * * 如果 URI 中没有此值，**必须** 返回空字符串。 * * 根据 RFC 3986 规范 3.2.2 章节，返回的数据 **必须** 是小写字母。 * * @see http://tools.ietf.org/html/rfc3986#section-3.2.2 * @return string URI 中的 HOST 信息。 */ public function getHost(); /** * 从 URI 中获取端口信息。 * * 如果端口信息是与当前 Scheme 的标准端口不匹配的话，就使用整数值的格式返回，如果是一 * 样的话，**应该** 返回 `null` 值。 * * 如果不存在端口和 Scheme 信息，**必须** 返回 `null` 值。 * * 如果不存在端口数据，但是存在 Scheme 的话，**可能** 返回 Scheme 对应的 * 标准端口，但是 **应该** 返回 `null`。 * * @return null|int URI 中的端口信息。 */ public function getPort(); /** * 从 URI 中获取路径信息。 * * 路径可以是空的，或者是绝对的（以斜线「/」开头），或者相对路径（不以斜线开头）。 * 实现 **必须** 支持所有三种语法。 * * 根据 RFC 7230 第 2.7.3 节，通常空路径「」和绝对路径「/」被认为是相同的。 * 但是这个方法 **不得** 自动进行这种规范化，因为在具有修剪的基本路径的上下文中， * 例如前端控制器中，这种差异将变得显著。用户的任务就是可以将「」和「/」都处理好。 * * 返回的值 **必须** 是百分号编码，但 **不得** 对任何字符进行双重编码。 * 要确定要编码的字符，请参阅 RFC 3986 第 2 节和第 3.3 节。 * * 例如，如果值包含斜线（「/」）而不是路径段之间的分隔符，则该值必须以编码形式（例如「%2F」） * 传递给实例。 * * @see https://tools.ietf.org/html/rfc3986#section-2 * @see https://tools.ietf.org/html/rfc3986#section-3.3 * @return string URI 路径信息。 */ public function getPath(); /** * 获取 URI 中的查询字符串。 * * 如果不存在查询字符串，则此方法必须返回空字符串。 * * 前导的「?」字符不是查询字符串的一部分，**不得** 添加在返回值中。 * * 返回的值 **必须** 是百分号编码，但 **不得** 对任何字符进行双重编码。 * 要确定要编码的字符，请参阅 RFC 3986 第 2 节和第 3.4 节。 * * 例如，如果查询字符串的键值对中的值包含不做为值之间分隔符的（「&」），则该值必须 * 以编码形式传递（例如「%26」）到实例。 * * @see https://tools.ietf.org/html/rfc3986#section-2 * @see https://tools.ietf.org/html/rfc3986#section-3.4 * @return string URI 中的查询字符串 */ public function getQuery(); /** * 获取 URI 中的片段（Fragment）信息。 * * 如果没有片段信息，此方法 **必须** 返回空字符串。 * * 前导的「#」字符不是片段的一部分，**不得** 添加在返回值中。 * * 返回的值 **必须** 是百分号编码，但 **不得** 对任何字符进行双重编码。 * 要确定要编码的字符，请参阅 RFC 3986 第 2 节和第 3.5 节。 * * @see https://tools.ietf.org/html/rfc3986#section-2 * @see https://tools.ietf.org/html/rfc3986#section-3.5 * @return string URI 中的片段信息。 */ public function getFragment(); /** * 返回具有指定 Scheme 的实例。 * * 此方法 **必须** 保留当前实例的状态，并返回包含指定 Scheme 的实例。 * * 实现 **必须** 支持大小写不敏感的「http」和「https」的 Scheme，并且在 * 需要的时候 **可能** 支持其他的 Scheme。 * * 空的 Scheme 相当于删除 Scheme。 * * @param string $scheme 给新实例使用的 Scheme。 * @return self 具有指定 Scheme 的新实例。 * @throws \InvalidArgumentException 使用无效的 Scheme 时抛出。 * @throws \InvalidArgumentException 使用不支持的 Scheme 时抛出。 */ public function withScheme($scheme); /** * 返回具有指定用户信息的实例。 * * 此方法 **必须** 保留当前实例的状态，并返回包含指定用户信息的实例。 * * 密码是可选的，但用户信息 **必须** 包括用户；用户信息的空字符串相当于删除用户信息。 * * @param string $user 用于认证的用户名。 * @param null|string $password 密码。 * @return self 具有指定用户信息的新实例。 */ public function withUserInfo($user, $password = null); /** * 返回具有指定 HOST 信息的实例。 * * 此方法 **必须** 保留当前实例的状态，并返回包含指定 HOST 信息的实例。 * * 空的 HOST 信息等同于删除 HOST 信息。 * * @param string $host 用于新实例的 HOST 信息。 * @return self 具有指定 HOST 信息的实例。 * @throws \InvalidArgumentException 使用无效的 HOST 信息时抛出。 */ public function withHost($host); /** * 返回具有指定端口的实例。 * * 此方法 **必须** 保留当前实例的状态，并返回包含指定端口的实例。 * * 实现 **必须** 为已建立的 TCP 和 UDP 端口范围之外的端口引发异常。 * * 为端口提供的空值等同于删除端口信息。 * * @param null|int $port 用于新实例的端口；`null` 值将删除端口信息。 * @return self 具有指定端口的实例。 * @throws \InvalidArgumentException 使用无效端口时抛出异常。 */ public function withPort($port); /** * 返回具有指定路径的实例。 * * 此方法 **必须** 保留当前实例的状态，并返回包含指定路径的实例。 * * 路径可以是空的、绝对的（以斜线开头）或者相对路径（不以斜线开头），实现必须支持这三种语法。 * * 如果 HTTP 路径旨在与 HOST 相对而不是路径相对，，那么它必须以斜线开头。 * 假设 HTTP 路径不以斜线开头，对应该程序或开发人员来说，相对于一些已知的路径。 * * 用户可以提供编码和解码的路径字符，要确保实现了 `getPath()` 中描述的正确编码。 * * @param string $path 用于新实例的路径。 * @return self 具有指定路径的实例。 * @throws \InvalidArgumentException 使用无效的路径时抛出。 */ public function withPath($path); /** * 返回具有指定查询字符串的实例。 * * 此方法 **必须** 保留当前实例的状态，并返回包含查询字符串的实例。 * * 用户可以提供编码和解码的查询字符串，要确保实现了 `getQuery()` 中描述的正确编码。 * * 空查询字符串值等同于删除查询字符串。 * * @param string $query 用于新实例的查询字符串。 * @return self 具有指定查询字符串的实例。 * @throws \InvalidArgumentException 使用无效的查询字符串时抛出。 */ public function withQuery($query); /** * 返回具有指定 URI 片段（Fragment）的实例。 * * 此方法 **必须** 保留当前实例的状态，并返回包含片段的实例。 * * 用户可以提供编码和解码的片段，要确保实现了 `getFragment()` 中描述的正确编码。 * * 空片段值等同于删除片段。 * * @param string $fragment 用于新实例的片段。 * @return self 具有指定 URI 片段的实例。 */ public function withFragment($fragment); /** * 返回字符串表示形式的 URI。 * * 根据 RFC 3986 第 4.1 节，结果字符串是完整的 URI 还是相对引用，取决于 URI 有哪些组件。 * 该方法使用适当的分隔符连接 URI 的各个组件： * * - 如果存在 Scheme 则 **必须** 以「:」为后缀。 * - 如果存在认证信息，则必须以「//」作为前缀。 * - 路径可以在没有分隔符的情况下连接。但是有两种情况需要调整路径以使 URI 引用有效，因为 PHP * 不允许在 `__toString()` 中引发异常： * - 如果路径是相对的并且有认证信息，则路径 **必须** 以「/」为前缀。 * - 如果路径以多个「/」开头并且没有认证信息，则起始斜线 **必须** 为一个。 * - 如果存在查询字符串，则 **必须** 以「?」作为前缀。 * - 如果存在片段（Fragment），则 **必须** 以「#」作为前缀。 * * @see http://tools.ietf.org/html/rfc3986#section-4.1 * @return string */ public function __toString(); } ~~~