编辑“Gallery:URL重写（URL Rewrite）”

{{expand}}

=开发者参考=
[[Gallery:Modules:rewrite|用户参考]]

==重写规则==
重写规则是经由一个或多个''设定''所建立起来的，每个规则都有各自唯一的''ruleId''。重写规则在各模块的module.inc中进行定义，通过：
 function getRewriteRules() {
     return array(''ruleId'' => array(''setting'' => ''value'', ...),
                  ...);
 }

Gallery重写规则主要用于生成'''短URL（Short-URLs）'''。但它们也可用于提供高级特点，如：
* 为热链接（hotlinked）图片添加水印效果
*美观的HTTP 404错误页面
* HTTP验证
* 拦截/允许特定的参照页

===短URL ===
要为某特定视图或控制器定义一个'''短URL'''的话，你需要定义一个'''样式（pattern）'''并在'''match'''设定中指定视图或控制器。

举个例子：要为评论模块的"添加评论"视图定义一个短URL的话，我们需要在modules/comment/module.inc中添加进此函数：
 function getRewriteRules() {
     return array(0 => array ('match'] = array('view' => 'comment.AddComment'),
                              'pattern'] = 'c/add/%itemId%.html'));
 }

* '''match'''设定指定重新定向的位置而'''样式（pattern）'''则为URL的外观表现（例如''http://example.com/c/add/17.html''）。
* ''%itemId%''是一个'''关键词（keyword）'''，你可以注册自己所用的''关键词（keyword）''而类似''%itemId%''的常见关键词已经为注册好了。
* ''c/add/...''中的''c/''前缀是Gallery中的编码规范了。你也可以选择较长的样式，比如''addComment/%itemId%''或干脆是''a/%itemId%''。
* 没有必要在短URL结尾加上''.html''。在Gallery中，''.html''一般被后置到所有用于请求的短URL，结果通常是显示某个HTML页面。 
* 这恐怕是对某重写规则的最短定义了。下面完整的列表中包括'''样式（pattern）'''和''match''组合使用可用的所有被支持的设定。

=== 重写规则的其他用途===
重写规则不仅仅用于短URL。要定义某个重写规则，你需要至少以下''设定''之一：
* '''pattern''' –对短URL来说，它是与'''match'''一起的
* '''restrict''' – 仅对具有特定请求URL参量的请求执行特定的动作，例如拦截未知的参照页或与'''queryString'''设定结合以过滤掉所有core.DownloadItem请求并将它们重新定向至水印模块，为热链图片添加水印效果
* '''conditions''' – 形容为“强力”的''restrict''比较贴切。然而''restrict''仅能基于请求URL参量进行过滤，你则可以在''conditions''中访问所有的HTTP header（比如HTTP验证header）。 

=== 完整的规范===
以下列出了全部被支持的设定：
* '''pattern'''值：''string'' (optional)<br/>The default rule pattern. The pattern is used to generate short URLs and is used to match requests, to determine to which rule a request corresponds. Rules which do not define a pattern can not be used to generate short URLs. Rules which do not define a pattern match all requests. The pattern can contain upper and lower case alpha numeric characters, forward slash (/), period (.), and dash (-). The percent sign (%) is used in the pattern to delineate keywords. The pattern is a literal string. Regular expression meta characters are escaped where the pattern appears in the context of a regular expression.
* '''keywords'''值：''array(array(setting => value, ...), ...)'' (optional)<br/>Defines how a keyword should be parsed and generated. All keywords needs to be replaced with something. Keyword settings:
** '''pattern'''值：''string''<br/>A regular expression that will catch the expected value.
** '''help'''值：''translated string''<br/>Describes what kind of value this replaced with when generating the rule.
** '''ignore'''值：''integer''<br/>Ignores back reference, if this is set.
** '''function'''值：''array(module, class, function)''<br/>A function that replaces the keyword with a value (see the [[Gallery:URL_Rewrite#Keyword_Function|Keyword Function]] reference on how it works). If no function is specified the URL generator will replace the keyword with the query string param.
* '''comment'''值：''translated string'' (optional)<br/>A short description of what kind of rule this is.
* '''match'''值：''array(param => value, ...)'' (optional)<br/>Gallery URLs whose parameters are a superset of match are replaced with the short URL this rule defines. Requests which match this rule are redirected to the value of match.
* '''queryString'''值：''array(param => value, ...)'' (optional)<br/>Appends the given value pairs to the query string (static values). Although very similar to 'match', 'queryString' is not involved in generating short-URLs. These params are just added to the target URL.
* '''onLoad'''值：''array(module, class, function)'' (optional)<br/>A function which will be called after the the initialization of the URL generator. Only called for rules with a ''match'' value set and when that view is loaded. See the [[Gallery:URL_Rewrite#onLoad_Function|onLoad Function]] reference below on how it works.
* '''options'''值：''array(param => value, ...)'' (optional)<br/>
** Same as the GalleryUrlGenerator::generateUrl options parameter. E.g. ''array('forceServerRelative' => true, 'forceDirect' => true)''.
** Used to generate the target URL of the rewrite.
** Only available for preGallery parsers (mod_rewrite and isapi_rewrite).
** Defaults to: ''array('forceDirect' => false, 'forceServerRelativeUrl' => true, 'forceSessionId' => false, 'htmlEntities' => false, 'urlEncode' => false, 'useAuthToken' => false)''
* '''help'''值：''translated string'' (optional)<br/>A longer description of the rule.
* '''locked'''值：''integer'' (optional)<br/>If locked is set users may not change the default pattern.
* '''flags'''值：''array(flag, ...)'' (optional)<br/>Flags are only supported by preGallery parsers (see the parser setting). Valid flags are F (forbidden) and R (explicit redirect). 
* '''restrict'''值：''array(param => value, ...)'' (optional)<br/>Makes the rule only affect a query string that has param=value set. Restrict is only supported by preGallery parsers (see the parser setting).
* '''exemptReferer'''值：''integer'' (optional)<br/>If exemptReferer is set then requests made by a referer in the access list is exempted from this rule. Only affective in combination with the restrict setting.
* '''parser'''值：''string'' (optional)<br/>The type of parser required for this rule. Can be either preGallery (parses the rule before Gallery is loaded), inGallery (Gallery parses the rule itself) or empty/null (when both methods are supported).
* '''conditions'''值：''array(array(setting => value, ...), ...)'' (optional)<br/>Custom conditions which requests must satisfy to match this rule. Conditions are only supported by preGallery parsers (see the parser setting). Condition settings:
** '''test'''值：''string''<br/>The subject to which the pattern is applied. For examples of conditions' test strings, see http://httpd.apache.org/docs/2.2/mod/mod_rewrite.html#rewritecond.
** '''pattern'''值：''string''<br/>A regular expression which is applied to to the test string. Conditions' pattern may contain keywords. eg.
 $rule['conditions'] = array(
     array('test' => 'REQUEST_METHOD', 'pattern' => 'OPTIONS'),
     array('test' => 'HTTP:Authorization', 'pattern' => '%authorization%'));
** '''flags'''值：''array(flag, ...)'' (optional)<br/>You can also set special flags for conditions. For examples of conditions' flags, see http://httpd.apache.org/docs/2.2/mod/mod_rewrite.html#rewritecond.
Rules which do not define a pattern or restrict or conditions will invariably match all requests and redirect to the value of match.

==Keyword函数==
 function parseMyKeyword(&$url, &$params, &$entity) {
      ...
 
      return true;
 }
具有关键词的任何规则都可能寄存其函数以生成短URL。一个关键词函数应：
* 将关键词替换为某个值
* 当为项目取特定值时使用$entity
* unset使用的参量值（unset itemId时请谨慎）
* unset被创建的参量（当重新生成导航URL时，我们不希望旧的参量被后置到查询字串中去）

==onLoad 函数==
 function loadMyView() {
     ...
 
     return null
 }
当重写模块生成器被载入时，onLoad函数就被呼叫了。此时我们尚无对话或翻译。onLoad函数主要应通过使用GalleryUtilities::getRequestVariables()和GalleryUtilities::setRequestVariable()来处理请求变量。

成功则返回null或GalleryCoreApi::error()。

=Rewrite API参考=
有了Rewrite API整合，开发者就可以直接配置URL重写模块而无需用户做任何动作了。

==如何使用Rewrite API==
* 初始化GalleryEmbed类别（参见GalleryEmbed::init, embed.php）

* 检查看看模块是否处于活动状态
 list ($ret, $rewriteApi) = GalleryCoreApi::newFactoryInstance('RewriteApi');
 if ($ret) {
     /* 错误的处理*/
 }
 if (empty($rewriteApi)) {
     /* 
      * 无可用rewrite API：重写模块未被安装
      * 或者为某个较旧的版本，无法暴露rewrite API
      */
 }
* 确保脚本与目前的Api版本：'''kiz_0987:'''相兼容。注意在重写模块的G2.1版本中有若干bug，会导致致命的PHP错误。呼叫isCompatibleWithApi将会显示此致命错误。我所认为的某可行办法就是扩展上述检查，以使其在呼叫其他函数之前也对isset($rewrite->_error)进行检查。 
 $required = array(1, 0);
 list ($ret, $isCompatible) = $rewriteApi->isCompatibleWithApi($required);
 if ($ret) {
     /* 错误的处理 */
     /*
      * 此处的错误可能是因为RewriteApi对象无法被成功地初始化
      * （例如，分析器出了问题）或因为还存在其他错误
      */
 }
 if (!$isCompatible) {
     /* No go! */
 }
* 完成…

==函数的相关参考==
===needsEmbedConfig===
 list ($ret, $needsConfiguration) = $rewriteApi->needsEmbedConfig();
返回一个boolean，如需配置则为true。只要配置为需要的话，短URL就不会为嵌入模式所生成。

===fetchEmbedConfig===
 list ($ret, $params) = $rewriteApi->fetchEmbedConfig();
除了GalleryStatus对象之外，此函数还返回一组配置值。依据活动的分析器的不同，此数组也会不一样。
* Apache mod_rewrite:
** ''embeddedHtaccess''含有嵌入.htaccess文件的.htaccess路径（比如/var/www/vhost.org/embedApp/）
** ''embeddedLocation''含有公共路径（比如/embedApp/ 或 /）
* IIS ISAPI_Rewrite:
** ''embeddedLocation''含有公共路径（比如/embedApp/ 或 /）
* PHP PathInfo
**空数组

===saveEmbedConfig===
 list ($ret, $code, $errstr) = $rewriteApi->saveEmbedConfig($params);
此函数保存嵌入的配置—给定数组settings => values。有效设定为''fetchEmbedConfig''所返回的数组键。在''embeddedHtaccess''和''embeddedLocation''被定义的情况下呼叫此函数是安全的。

此函数返回GalleryStatus对象—一个URL重写状态代码—及一个经过翻译的错误消息。如果保存成功，$code就为REWRITE_STATUS_OK所定义而$errstr为null。

===fetchActiveRulesForModule===
 list ($ret, $activeRules) = $rewriteApi->fetchActiveRulesForModule($moduleId);
 if ($ret) {
   return $ret;
 }

为某特定模块（该模块可在此呼叫执行时为不活动状态）取得活动的重写规则。

===activateRewriteRulesForModule===
 list ($ret, $success) = $rewriteApi->activateRewriteRulesForModule($module, $ruleIds, $replacePatterns);
 if ($ret) {
   /* 如发生严重问题，停止该程序*/
   return $ret;
 }
 if (!$success) {
   /* 激活规则失败，比如因为重写模块无法写入.htaccess文件*/
 }

为某特定模块（该模块可在此呼叫执行时为不活动状态）激活重写规则。默认情况下是不会更新活动的规则的，仅修改给定模块的活动规则列表。如果$replacePatterns被指定并为true的话，它就会替换已处于活动状态的规则样式（模块getRewriteRules()方法的默认类型）。

===getApiVersion===
将当前RewriteApi版本返回为一个数组（major，minor）。

===getParserId===
返回活动分析器id。
* modrewrite - Apache mod_rewrite
* isapirewrite - IIS ISAPI_Rewrite
* pathinfo - PHP PathInfo

===getParserType===
返回活动分析器的分析器类型。
* preGallery – modrewrite和isapirewrite
* inGallery - pathinfo

[[Category:Gallery 2:Development|URL_Rewrite]]