README

本项目支持现已停止。请更新您的链接。

通过标签分支找到旧版本。

BOTK\Context

轻量级验证和清理助手。

这是一个BOTK包。有关BOTK项目的更多信息，请参阅http://ontology.it/tools/botk。

快速开始

该包可在Packagist上找到。您可以使用Composer进行安装。

composer require botk/context

示例目录中有一些代码示例。

BOTK\Context包文档

摘要

此包导出了一套用于管理RESTful请求上下文的类。

上下文被定义为在http请求服务过程中运行时可用的全部变量集合。变量被分组在不同的命名空间中。

所有命名空间中的变量都是只读的。

此包公开了清理和验证上下文变量的方法。

注意，cookies和session不是上下文的一部分。这是因为正确的RESTful资源实现不应该以任何方式需要持久状态。

安装

此包遵循BOTK安装指南，并需要composer。

将以下依赖项添加到您项目根目录中的composer.json文件中

{
    "require": {
        "botk/context": "*"
    }
}

Context类

上下文是CGI端点除了其URI之外所知道的所有内容的完整集合。上下文空间包含系统环境变量、请求头、请求体、服务器特定变量、cookies、配置文件中的变量、局部定义变量等。

上下文变量被分组在命名空间中。 BOTK\Context\Context类提供 ns(<var>namespace name</var>)方法来访问命名空间。有五个预定义的命名空间

请求头部定义的变量并由Web服务器公开（INPUT_SERVER）；
编码在http URI中的变量（INPUT_GET）；
编码在http体中的变量（INPUT_POST）；
系统环境（INPUT_ENV）；
局部定义变量（Context::LOCAL）。

除了这些，Context类还允许您定义从配置目录中运行时加载的.ini文件构建的动态命名空间。命名空间的名字是配置文件的名字，不包含.ini扩展名。

配置文件必须在首次引用时存在。默认配置目录是 ../configs，通常位于包含实例化上下文类的脚本的同一级目录中。您可以通过定义环境变量 $_ENV['BOTK_CONFIGDIR'] 来更改默认目录。

上下文应被视为只读数据结构，因为您不能更改资源执行上下文。

例如，假设端点脚本位于 myapp/httdocs/index.php，那么，为了使以下代码成功，必须存在 myapp/configs/sample.ini 文件

use BOTK\Context\Context as CX;
$sampleNameSpace = CX::factory()->ns('sample');

如果您想将 .ini 文件放在相同的端点目录中

use BOTK\Context\Context as CX;
$_ENV['BOTK_CONFIGDIR'] = '.';
$sampleNameSpace = CX::factory()->ns('sample');

您还可以通过将它们传递给上下文构造函数来访问局部变量

$myvar = 'ok'; // define a variable in local scope
$v = CX::factory(get_defined_vars())->ns(CX::LOCAL)->getValue('myvar');
//$v == 'ok'

上下文类公开了方法 guessRequestCanonicalUri()，该方法返回当前请求的规范形式的 URI，以及方法 guessRequestRelativelUri()，该方法返回相对路径。

请注意，获取请求 URI 不是一个简单的工作，这是因为 HTTP 服务器和代理可以更改用户输入的内容。您只能对此进行猜测。

ContextNameSpace 类

此类实现了对变量集合的受控访问。

getValue() 方法

BOTK\Context\ContextNameSpace 类导出方法 getValue()，允许验证和清理在命名空间中定义的变量（请参阅 PHP Validation & Sanitization 文章）。

如果出现问题，它将引发一个错误，该错误可以被标准 BOTK 错误管理捕获。

getValue() 公开了以下接口

除了 getValue()``ContextNameSpace 类还公开了一组快捷方式，以便易于阅读和编写代码。

验证器快捷方式

某些验证器编写起来可能很繁琐，这里有一组预定义的快捷方式

getValue 快捷方式

即使有验证器快捷方式，getValue 方法的调用也可能过于冗长，这里有一些用于常见任务的快捷方式

getString($varName,$default = null): 等同于 getValue($varName,$default, null, FILTER_SANITIZE_STRING);
getURI($varName,$default = null): 等同于 getValue($varName,$default, self::STRING('/.+/'), FILTER_SANITIZE_URL)

PagedResourceContext 类

PagedResource 类是管理查询字符串可以包含变量以驱动分页处理资源上下文的工具。它是 Context 类的特殊化，像 Context 一样应被视为只读数据结构。

资源分页上下文受 W3C 的 Linked Data Platform 分页规范的启发。以下是一些重要定义

分页资源: 一个表示可能太大而无法适合单个 HTTP 响应的资源，服务器为此提供一系列单页资源。分页 P 被分解为一系列页面（单页资源）P₁，P₂，...，P_n，每个 P_i 的表示包含 P 的一个子集。
单页资源: 一系列相关资源 P₁，P₂，...，P_n 中的一个，每个资源都包含另一个资源 P 的状态的一个子集。P 被称为分页资源。对于熟悉分页源的朋友，单页资源类似于源文档，并且相同的连贯性/完整性考虑因素适用。
注意：术语的选择是为了帮助作者和读者在提及两者时，清楚地区分被分页的资源和单个页面资源。
第一页: 分页资源P的第一个单页资源的uri。例如 http://www.example.org/bigresource?page=0
下一页: 分页资源P的下一个单页资源的uri。
最后一页: 分页资源P的最后一个单页资源的uri。
上一页: 分页资源P的前一个单页资源的uri。

分页需要指定一些变量在资源URI查询字符串中。这些变量的名称和其他默认值可以作为选项关联数组传递给类构造函数。以下是支持的关键字

plabel：包含包含页码变量的变量。默认为'page'。
pslabel：包含包含页面大小的变量的变量。默认为'pagesize'。
pagesize：包含页面大小的默认值。默认为100。

它公开以下方法

`getSinglePageResourceUri( $pagenum = null, $pagesize=null)`: 返回包含查询字符串中页变量的规范uri。如果没有参数返回当前页面资源uri。
`getPagedResourceUri()`: 返回从查询字符串中移除页面变量的资源uri。
`isPagedResource()`: 如果资源uri包含页面信息则返回true。
`getPageNum()`: 返回当前页码。
`getPageSize()`: 返回页面大小。
`firstPageUri()`: 返回第一个单页资源的资源uri。
`nextPageUri()`: 返回下一页资源的资源uri或当前页面资源的uri。
`prevPageUri()`: 返回下一页资源的资源uri或第一页资源的uri。
`hasNextPage()`: 如果存在下一页则返回true。默认返回true。它可以受`declareActualPageSize()`方法的影响。
`isLastPage()`: 如果当前是最后一页则返回true。默认返回false。它可以受`declareActualPageSize()`方法的影响。
`declareActualPageSize($count)`: 通过默认值0通知上下文当前页中的项目数量。这会影响`hasNextPage()`和`isLastPageMethods()`方法。

以下是`declaretActualPageSize()`如何影响`hasNextPage()`和`isLastPage()`的示例。

许可证

特此授予任何获得本软件及其相关文档副本（以下简称“软件”）的人免费使用该软件的权利，包括但不限于使用、复制、修改、合并、发布、分发、再许可和/或销售软件副本，并允许向软件提供方提供软件的人这样做，前提是遵守以下条件

botk / context

维护者

详情