云策 WordPress 开发者社区

函数文档

iis7_add_rewrite_rule()

查看官方原文 ↗
💡 云策文档标注

概述

iis7_add_rewrite_rule() 函数用于向 IIS 7+ 配置文件添加 WordPress 重写规则。它通过操作 XML 文档来确保规则正确插入，并避免重复添加。

关键要点

  • 函数接受两个参数：$filename（配置文件路径）和 $rewrite_rule（包含 URL 重写规则的 XML 片段）。
  • 返回布尔值：成功时返回 true，失败时返回 false。
  • 依赖 DOMDocument 类，若未加载则返回 false。
  • 自动创建不存在的配置文件，并检查规则是否已存在以避免重复。
  • 使用 XPath 查询和 DOM 操作来构建或更新 XML 结构。

代码示例

function iis7_add_rewrite_rule( $filename, $rewrite_rule ) {
    if ( ! class_exists( 'DOMDocument', false ) ) {
        return false;
    }

    if ( ! file_exists( $filename ) ) {
        $fp = fopen( $filename, 'w' );
        fwrite( $fp, '' );
        fclose( $fp );
    }

    $doc                     = new DOMDocument();
    $doc->preserveWhiteSpace = false;

    if ( $doc->load( $filename ) === false ) {
        return false;
    }

    $xpath = new DOMXPath( $doc );
    $wordpress_rules = $xpath->query( '/configuration/system.webServer/rewrite/rules/rule[starts-with(@name,'wordpress')] | /configuration/system.webServer/rewrite/rules/rule[starts-with(@name,'WordPress')]' );

    if ( $wordpress_rules->length > 0 ) {
        return true;
    }

    // 构建 XML 节点并添加规则
    $xml_nodes = $xpath->query( '/configuration/system.webServer/rewrite/rules' );
    if ( $xml_nodes->length > 0 ) {
        $rules_node = $xml_nodes->item( 0 );
    } else {
        $rules_node = $doc->createElement( 'rules' );
        // 更多节点创建逻辑...
    }

    $rule_fragment = $doc->createDocumentFragment();
    $rule_fragment->appendXML( $rewrite_rule );
    $rules_node->appendChild( $rule_fragment );

    $doc->encoding     = 'UTF-8';
    $doc->formatOutput = true;
    saveDomDocument( $doc, $filename );

    return true;
}

注意事项

  • 确保服务器环境支持 DOMDocument 类，否则函数会失败。
  • 配置文件路径必须可写，否则可能无法保存更改。
  • 函数内部调用 saveDomDocument() 来保存 XML 文档。
  • 相关函数包括 iis7_save_url_rewrite_rules()，用于更新 IIS web.config 文件。
📄 原文内容

Adds WordPress rewrite rule to the IIS 7+ configuration file.

Parameters

$filenamestringrequired
The file path to the configuration file.
$rewrite_rulestringrequired
The XML fragment with URL Rewrite rule.

Return

bool

Source

function iis7_add_rewrite_rule( $filename, $rewrite_rule ) {
	if ( ! class_exists( 'DOMDocument', false ) ) {
		return false;
	}

	// If configuration file does not exist then we create one.
	if ( ! file_exists( $filename ) ) {
		$fp = fopen( $filename, 'w' );
		fwrite( $fp, '<configuration/>' );
		fclose( $fp );
	}

	$doc                     = new DOMDocument();
	$doc->preserveWhiteSpace = false;

	if ( $doc->load( $filename ) === false ) {
		return false;
	}

	$xpath = new DOMXPath( $doc );

	// First check if the rule already exists as in that case there is no need to re-add it.
	$wordpress_rules = $xpath->query( '/configuration/system.webServer/rewrite/rules/rule[starts-with(@name,'wordpress')] | /configuration/system.webServer/rewrite/rules/rule[starts-with(@name,'WordPress')]' );

	if ( $wordpress_rules->length > 0 ) {
		return true;
	}

	// Check the XPath to the rewrite rule and create XML nodes if they do not exist.
	$xml_nodes = $xpath->query( '/configuration/system.webServer/rewrite/rules' );

	if ( $xml_nodes->length > 0 ) {
		$rules_node = $xml_nodes->item( 0 );
	} else {
		$rules_node = $doc->createElement( 'rules' );

		$xml_nodes = $xpath->query( '/configuration/system.webServer/rewrite' );

		if ( $xml_nodes->length > 0 ) {
			$rewrite_node = $xml_nodes->item( 0 );
			$rewrite_node->appendChild( $rules_node );
		} else {
			$rewrite_node = $doc->createElement( 'rewrite' );
			$rewrite_node->appendChild( $rules_node );

			$xml_nodes = $xpath->query( '/configuration/system.webServer' );

			if ( $xml_nodes->length > 0 ) {
				$system_web_server_node = $xml_nodes->item( 0 );
				$system_web_server_node->appendChild( $rewrite_node );
			} else {
				$system_web_server_node = $doc->createElement( 'system.webServer' );
				$system_web_server_node->appendChild( $rewrite_node );

				$xml_nodes = $xpath->query( '/configuration' );

				if ( $xml_nodes->length > 0 ) {
					$config_node = $xml_nodes->item( 0 );
					$config_node->appendChild( $system_web_server_node );
				} else {
					$config_node = $doc->createElement( 'configuration' );
					$doc->appendChild( $config_node );
					$config_node->appendChild( $system_web_server_node );
				}
			}
		}
	}

	$rule_fragment = $doc->createDocumentFragment();
	$rule_fragment->appendXML( $rewrite_rule );
	$rules_node->appendChild( $rule_fragment );

	$doc->encoding     = 'UTF-8';
	$doc->formatOutput = true;
	saveDomDocument( $doc, $filename );

	return true;
}

View all references View on Trac View on GitHub

Uses Description
saveDomDocument()wp-admin/includes/misc.php

Saves the XML document into a file.
Used by Description
iis7_save_url_rewrite_rules()wp-admin/includes/misc.php

Updates the IIS web.config file with the current rules if it is writable.

Changelog

Version Description
2.8.0 Introduced.