PHP 手册

ctype_alpha

(PHP 4 >= 4.0.4, PHP 5)

ctype_alpha -- Check for alphabetic character(s)

说明

bool ctype_alpha ( string text )

Checks if all of the characters in the provided string, text, are alphabetic. In the standard C locale letters are just [A-Za-z] and ctype_alpha() is equivalent to (ctype_upper($text) || ctype_lower($text)) if $text is just a single character, but other languages have letters that are considered neither upper nor lower case.

参数

text: The tested string.

返回值

Returns TRUE if every character in text is a letter from the current locale, FALSE otherwise.

范例

例子 1. A ctype_alpha() example (using the default locale)
<?php $strings = array('KjgWZC', 'arf12'); foreach ($strings as $testcase) { if (ctype_alpha($testcase)) { echo "The string $testcase consists of all letters.\n"; } else { echo "The string $testcase does not consist of all letters.\n"; } } ?>
上例将输出：
The string KjgWZC consists of all letters. The string arf12 does not consists of all letters.

参见

ctype_upper()

ctype_lower()

ctype_cntrl

(PHP 4 >= 4.0.4, PHP 5)

ctype_cntrl -- Check for control character(s)

说明

bool ctype_cntrl ( string text )

Checks if all of the characters in the provided string, text, are control characters. Control characters are e.g. line feed, tab, esc.

参数

text: The tested string.

返回值

Returns TRUE if every character in text is a letter from the current locale, FALSE otherwise.

范例

例子 1. A ctype_cntrl() example
<?php $strings = array('string1' => "\n\r\t", 'string2' => 'arf12'); foreach ($strings as $name => $testcase) { if (ctype_cntrl($testcase)) { echo "The string '$name' consists of all control characters.\n"; } else { echo "The string '$name' does not consist of all control characters.\n"; } } ?>
上例将输出：
The string 'string1' consists of all control characters. The string 'string2' does not consists of all control characters.

参见

ctype_print()

ctype_digit

(PHP 4 >= 4.0.4, PHP 5)

ctype_digit -- Check for numeric character(s)

说明

bool ctype_digit ( string text )

Checks if all of the characters in the provided string, text, are numerical.

参数

text: The tested string.

返回值

Returns TRUE if every character in text is a decimal digit, FALSE otherwise.

范例

例子 1. A ctype_digit() example
<?php $strings = array('1820.20', '10002', 'wsl!12'); foreach ($strings as $testcase) { if (ctype_digit($testcase)) { echo "The string $testcase consists of all digits.\n"; } else { echo "The string $testcase does not consist of all digits.\n"; } } ?>
上例将输出：
The string 1820.20 does not consists of all digits. The string 10002 consists of all digits. The string wsl!12 does not consists of all digits.

参见

ctype_alnum()

ctype_xdigit()

ctype_graph

(PHP 4 >= 4.0.4, PHP 5)

ctype_graph -- Check for any printable character(s) except space

说明

bool ctype_graph ( string text )

Checks if all of the characters in the provided string, text, creates visible output.

参数

text: The tested string.

返回值

Returns TRUE if every character in text is printable and actually creates visible output (no white space), FALSE otherwise.

范例

例子 1. A ctype_graph() example
<?php $strings = array('string1' => "asdf\n\r\t", 'string2' => 'arf12', 'string3' => 'LKA#@%.54'); foreach ($strings as $name => $testcase) { if (ctype_graph($testcase)) { echo "The string '$name' consists of all (visibly) printable characters.\n"; } else { echo "The string '$name' does not consist of all (visibly) printable characters.\n"; } } ?>
上例将输出：
The string 'string1' does not consist of all (visibly) printable characters. The string 'string2' consists of all (visibly) printable characters. The string 'string3' consists of all (visibly) printable characters.

参见

ctype_alnum()

ctype_print()

ctype_punct()

ctype_lower

(PHP 4 >= 4.0.4, PHP 5)

ctype_lower -- Check for lowercase character(s)

说明

bool ctype_lower ( string text )

Checks if all of the characters in the provided string, text, are lowercase letters.

参数

text: The tested string.

返回值

Returns TRUE if every character in text is a lowercase letter in the current locale.

范例

例子 1. A ctype_lower() example (using the default locale)
<?php $strings = array('aac123', 'qiutoas', 'QASsdks'); foreach ($strings as $testcase) { if (ctype_lower($testcase)) { echo "The string $testcase consists of all lowercase letters.\n"; } else { echo "The string $testcase does not consist of all lowercase letters.\n"; } } ?>
上例将输出：
The string aac123 does not consist of all lowercase letters. The string qiutoas consists of all lowercase letters. The string QASsdks does not consist of all lowercase letters.

参见

ctype_alpha()

ctype_upper()

ctype_print

(PHP 4 >= 4.0.4, PHP 5)

ctype_print -- Check for printable character(s)

说明

bool ctype_print ( string text )

Checks if all of the characters in the provided string, text, are printable.

参数

text: The tested string.

返回值

Returns TRUE if every character in text will actually create output (including blanks). Returns FALSE if text contains control characters or characters that do not have any output or control function at all.

范例

例子 1. A ctype_print() example
<?php $strings = array('string1' => "asdf\n\r\t", 'string2' => 'arf12', 'string3' => 'LKA#@%.54'); foreach ($strings as $name => $testcase) { if (ctype_print($testcase)) { echo "The string '$name' consists of all printable characters.\n"; } else { echo "The string '$name' does not consist of all printable characters.\n"; } } ?>
上例将输出：
The string 'string1' does not consist of all printable characters. The string 'string2' consists of all printable characters. The string 'string3' consists of all printable characters.

参见

ctype_cntrl()

ctype_graph()

ctype_punct()

ctype_punct

(PHP 4 >= 4.0.4, PHP 5)

ctype_punct -- Check for any printable character which is not whitespace or an alphanumeric character

说明

bool ctype_punct ( string text )

Checks if all of the characters in the provided string, text, are punctuation character.

参数

text: The tested string.

返回值

Returns TRUE if every character in text is printable, but neither letter, digit or blank, FALSE otherwise.

范例

例子 1. A ctype_punct() example
<?php $strings = array('ABasdk!@!$#', '!@ # $', '*&$()'); foreach ($strings as $testcase) { if (ctype_punct($testcase)) { echo "The string $testcase consists of all punctuation.\n"; } else { echo "The string $testcase does not consist of all punctuation.\n"; } } ?>
上例将输出：
The string ABasdk!@!$# does not consist of all punctuation. The string !@ # $ does not consist of all punctuation. The string *&$() consists of all punctuation.

参见

ctype_cntrl()

ctype_graph()

ctype_space

(PHP 4 >= 4.0.4, PHP 5)

ctype_space -- Check for whitespace character(s)

说明

bool ctype_space ( string text )

Checks if all of the characters in the provided string, text, creates whitespace.

参数

text: The tested string.

返回值

Returns TRUE if every character in text creates some sort of white space, FALSE otherwise. Besides the blank character this also includes tab, vertical tab, line feed, carriage return and form feed characters.

范例

例子 1. A ctype_space() example
<?php $strings = array('string1' => "\n\r\t", 'string2' => "\narf12", 'string3' => '\n\r\t'); foreach ($strings as $name => $testcase) { if (ctype_space($testcase)) { echo "The string '$name' consists of all whitespace characters.\n"; } else { echo "The string '$name' does not consist of all whitespace characters.\n"; } } ?>
上例将输出：
The string 'string1' consists of all whitespace characters. The string 'string2' does not consist of all whitespace characters. The string 'string3' does not consist of all whitespace characters.

参见

ctype_cntrl()

ctype_graph()

ctype_punct()

ctype_upper

(PHP 4 >= 4.0.4, PHP 5)

ctype_upper -- Check for uppercase character(s)

说明

bool ctype_upper ( string text )

Checks if all of the characters in the provided string, text, are uppercase characters.

参数

text: The tested string.

返回值

Returns TRUE if every character in text is an uppercase letter in the current locale.

范例

例子 1. A ctype_upper() example (using the default locale)
<?php $strings = array('AKLWC139', 'LMNSDO', 'akwSKWsm'); foreach ($strings as $testcase) { if (ctype_upper($testcase)) { echo "The string $testcase consists of all uppercase letters.\n"; } else { echo "The string $testcase does not consist of all uppercase letters.\n"; } } ?>
上例将输出：
The string AKLWC139 does not consist of all uppercase letters. The string LMNSDO consists of all uppercase letters. The string akwSKWsm does not consist of all uppercase letters.

参见

ctype_alpha()

ctype_lower()

ctype_xdigit

(PHP 4 >= 4.0.4, PHP 5)

ctype_xdigit -- Check for character(s) representing a hexadecimal digit

说明

bool ctype_xdigit ( string text )

Checks if all of the characters in the provided string, text, are hexadecimal 'digits'.

参数

text: The tested string.

返回值

Returns TRUE if every character in text is a hexadecimal 'digit', that is a decimal digit or a character from [A-Fa-f] , FALSE otherwise.

范例

例子 1. A ctype_xdigit() example
<?php $strings = array('AB10BC99', 'AR1012', 'ab12bc99'); foreach ($strings as $testcase) { if (ctype_xdigit($testcase)) { echo "The string $testcase consists of all hexadecimal digits.\n"; } else { echo "The string $testcase does not consist of all hexadecimal digits.\n"; } } ?>
上例将输出：
The string AB10BC99 consists of all hexadecimal digits. The string AR1012 does not consist of all hexadecimal digits. The string ab12bc99 consists of all hexadecimal digits.

参见

ctype_digit()

XII. Classes/Objects 类／对象函数

简介

本类函数允许获取类和对象实例的信息。可以取得对象所属的类的名字，以及它的成员属性和方法。通过使用这些函数，不仅可以弄清楚一个对象类的全体成员，而且可以知道它的起源（例如，该对象类是哪个类的扩展）。

需求

要编译本扩展模块不需要外部库文件。

安装

本函数库作为 PHP 内核的一部分，不用安装就能使用。

运行时配置

本扩展模块在 php.ini 中未定义任何配置选项。

资源类型

本扩展模块未定义任何资源类型。

预定义常量

本扩展模块未定义任何常量。

范例

在本例子中，先定义一个基础类和一个扩展类。基础类描述的是普通的蔬菜（Vegetable），它是否可食用（is_edible）以及它是什么颜色（what_color）。子类 Spinach 增加了“烹调”的方法（cook_it）和“获知它是否已被烹调了”的方法（is_cooked）。

例子 1. classes.inc
<?php // 基类及其成员属性与方法 class Vegetable { var $edible; var $color; function Vegetable($edible, $color="green") { $this->edible = $edible; $this->color = $color; } function is_edible() { return $this->edible; } function what_color() { return $this->color; } } // Vegetable 类定义结束 // 扩展基类 class Spinach extends Vegetable { var $cooked = false; function Spinach() { $this->Vegetable(true, "green"); } function cook_it() { $this->cooked = true; } function is_cooked() { return $this->cooked; } } // Spinach 类定义结束 ?>

接着，从这些对象中创建两个对象实例，打印出它们的相关信息，包括它们的起源。还定义了一些实用函数，它们主要是为了让变量的输出好看些。

例子 2. test_script.php
<pre> <?php include "classes.inc"; // utility functions function print_vars($obj) { foreach (get_object_vars($obj) as $prop => $val) { echo "\t$prop = $val\n"; } } function print_methods($obj) { $arr = get_class_methods(get_class($obj)); foreach ($arr as $method) { echo "\tfunction $method()\n"; } } function class_parentage($obj, $class) { if (is_subclass_of($GLOBALS[$obj], $class)) { echo "Object $obj belongs to class " . get_class($$obj); echo " a subclass of $class\n"; } else { echo "Object $obj does not belong to a subclass of $class\n"; } } // instantiate 2 objects $veggie = new Vegetable(true, "blue"); $leafy = new Spinach(); // print out information about objects echo "veggie: CLASS " . get_class($veggie) . "\n"; echo "leafy: CLASS " . get_class($leafy); echo ", PARENT " . get_parent_class($leafy) . "\n"; // show veggie properties echo "\nveggie: Properties\n"; print_vars($veggie); // and leafy methods echo "\nleafy: Methods\n"; print_methods($leafy); echo "\nParentage:\n"; class_parentage("leafy", "Spinach"); class_parentage("leafy", "Vegetable"); ?> </pre>
上边例子中重点要注意的是对象 $leafy 是 Spinach 类的一个实例，而 Spinach 类是 Vegetable 类的一个子类，因此上边脚本的最后部分将会输出：
[...] Parentage: Object leafy does not belong to a subclass of Spinach Object leafy belongs to class spinach a subclass of Vegetable

目录
call_user_method_array -- 调用一个用户方法，同时传递参数数组［已停用］
call_user_method -- 调用特定对象的用户方法［已停用］
class_exists -- 检查类是否已定义
get_class_methods -- 返回由类的方法名组成的数组
get_class_vars -- 返回由类的默认属性组成的数组
get_class -- 返回对象的类名
get_declared_classes -- 返回由已定义类的名字所组成的数组
get_declared_interfaces -- Returns an array of all declared interfaces
get_object_vars -- 返回由对象属性组成的关联数组
get_parent_class -- 返回对象或类的父类名
interface_exists -- Checks if the interface has been defined
is_a -- 如果对象属于该类或该类是此对象的父类则返回 TRUE
is_subclass_of -- 如果此对象是该类的子类，则返回 TRUE
method_exists -- 检查类的方法是否存在
property_exists -- Checks if the object or class has a property

call_user_method_array

(PHP 4 >= 4.0.5, PHP 5)

call_user_method_array -- 调用一个用户方法，同时传递参数数组［已停用］

描述

mixed call_user_method_array ( string method_name, object obj [, array paramarr] )

警告

call_user_method_array() 函数从 PHP 4.1.0 开始已经停用，使用 call_user_func_array() 函数和 array(&$obj, "method_name") 语法代替。

从用户定义的 obj 对象中调用 method_name 所指的方法，同时使用 paramarr 中的参数。

参见： call_user_func_array()、 call_user_func() 和 call_user_method()。

注: 此函数是在 PHP 4.0.4pl1 发行版之后加入到 CVS 代码中的

call_user_method

(PHP 3 >= 3.0.3, PHP 4, PHP 5)

call_user_method -- 调用特定对象的用户方法［已停用］

描述

mixed call_user_method ( string method_name, object obj [, mixed parameter [, mixed ...]] )

警告

call_user_method() 函数从 PHP 4.1.0 开始已经停用，使用 call_user_func() 函数和 array(&$obj, "method_name") 语法代替。

从用户定义的 obj 对象中调用 method_name 所指的方法。下边是用法示例，我们定义了一个类，接着创建了一个对象实例，然后使用 call_user_method() 间接调用它的 print_info 方法。

<?php
class Country {
    var $NAME;
    var $TLD;
    
    function Country($name, $tld) {
        $this->NAME = $name;
        $this->TLD = $tld;
    }

    function print_info($prestr="") {
        echo $prestr."Country: ".$this->NAME."\n";
        echo $prestr."Top Level Domain: ".$this->TLD."\n";
    }
}

$cntry = new Country("Peru","pe");

echo "* Calling the object method directly\n";
$cntry->print_info();

echo "\n* Calling the same method indirectly\n";
call_user_method ("print_info", $cntry, "\t");
?>

参见 call_user_func_array()、 call_user_func() 和 call_user_method_array()。

class_exists

(PHP 4, PHP 5)

class_exists -- 检查类是否已定义

描述

bool class_exists ( string class_name )

如果由 class_name 所指的类已经定义，此函数返回 TRUE，否则返回 FALSE。

参见 get_declared_classes()。

get_class_methods

(PHP 4, PHP 5)

get_class_methods -- 返回由类的方法名组成的数组

描述

array get_class_methods ( mixed class_name )

返回由 class_name 指定的类中定义的方法名所组成的数组。

注: 从 PHP 4.0.6 开始，可以指定对象本身来代替 class_name，例如：
$class_methods = get_class_methods($my_class); // see below the full example

例子 1. get_class_methods() 示例
<?php class myclass { // constructor function myclass() { return(TRUE); } // method 1 function myfunc1() { return(TRUE); } // method 2 function myfunc2() { return(TRUE); } } $my_object = new myclass(); $class_methods = get_class_methods(get_class($my_object)); foreach ($class_methods as $method_name) { echo "$method_name\n"; } ?>

运行结果：

myclass
myfunc1
myfunc2

参见 get_class_vars() 和 get_object_vars()。

get_class_vars

(PHP 4, PHP 5)

get_class_vars -- 返回由类的默认属性组成的数组

描述

array get_class_vars ( string class_name )

返回由类的默认属性组成的关联数组，此数组的元素以 varname => value 的形式存在。

注: 在 PHP 4.2.0 之前，get_class_vars() 不会包含未初始化的类变量。

例子 1. get_class_vars() 示例
<?php class myclass { var $var1; // 此变量没有默认值…… var $var2 = "xyz"; var $var3 = 100; // constructor function myclass() { return(TRUE); } } $my_class = new myclass(); $class_vars = get_class_vars(get_class($my_class)); foreach ($class_vars as $name => $value) { echo "$name : $value\n"; } ?>

运行结果：

// 在 PHP 4.2.0 之前
var2 : xyz
var3 : 100

// 从 PHP 4.2.0 开始
var1 :
var2 : xyz
var3 : 100

参见 get_class_methods()、 get_object_vars()

get_class

(PHP 4, PHP 5)

get_class -- 返回对象的类名

描述

string get_class ( object obj )

返回对象实例 obj 所属类的名字。如果 obj 不是一个对象则返回 FALSE。

注: get_class() 返回用户定义的类名的小写形式。在 PHP 扩展中定义的类则返回其原有的名字。

参见 get_parent_class()、 gettype() 和 is_subclass_of()。

get_declared_classes

(PHP 4, PHP 5)

get_declared_classes -- 返回由已定义类的名字所组成的数组

描述

array get_declared_classes ( void )

返回由当前脚本中已定义类的名字组成的数组。

注: 在 PHP 4.0.1pl2 中，有三个额外的类存在于返回的数组中：stdClass（在 Zend/zend.c 中定义）、OverloadedTestClass（在 ext/standard/basic_functions.c 中定义）和 Directory（在 ext/standard/dir.c 中定义）。
还需要注意的是额外类的出现依赖于你已编译到 PHP 中的库。这意味着你不能使用这些类名定义自己的类。在附录的预定义类部分有预定义类的列表。

参见 class_exists()。

get_declared_interfaces

(PHP 5)

get_declared_interfaces -- Returns an array of all declared interfaces

Description

array get_declared_interfaces ( void )

This function returns an array of the names of the declared interfaces in the current script.

例子 1. get_declared_interfaces() example
<?php print_r(get_declared_interfaces()); ?>
上例的输出类似于：
Array ( [0] => Traversable [1] => IteratorAggregate [2] => Iterator [3] => ArrayAccess [4] => reflector [5] => RecursiveIterator [6] => SeekableIterator )

get_object_vars

(PHP 4, PHP 5)

get_object_vars -- 返回由对象属性组成的关联数组

描述

array get_object_vars ( object obj )

返回由 obj 指定的对象中定义的属性组成的关联数组。

注: 在 PHP 4.2.0 之前的版本中，如果在 obj 对象实例中声明的变量没有被赋值，则它们将不会在返回的数组中。而在 PHP 4.2.0 之后，这些变量作为键名将被赋予 NULL 值。

例子 1. 使用 get_object_vars()
<?php class Point2D { var $x, $y; var $label; function Point2D($x, $y) { $this->x = $x; $this->y = $y; } function setLabel($label) { $this->label = $label; } function getPoint() { return array("x" => $this->x, "y" => $this->y, "label" => $this->label); } } // "$label" is declared but not defined $p1 = new Point2D(1.233, 3.445); print_r(get_object_vars($p1)); $p1->setLabel("point #1"); print_r(get_object_vars($p1)); ?>
上边的程序将输出：
Array ( [x] => 1.233 [y] => 3.445 [label] => ) Array ( [x] => 1.233 [y] => 3.445 [label] => point #1 )

参见 get_class_methods() 和 get_class_vars()！

get_parent_class

(PHP 4, PHP 5)

get_parent_class -- 返回对象或类的父类名

描述

string get_parent_class ( mixed obj )

如果 obj 是对象，则返回对象实例 obj 所属类的父类名。

如果 obj 是字符串，则返回以此字符串为名的类的父类名。此功能是在 PHP 4.0.5 中增加的。

参见 get_class() 和 is_subclass_of()

interface_exists

(PHP 5 >= 5.0.2)

interface_exists -- Checks if the interface has been defined

Description

bool interface_exists ( string interface_name [, bool autoload] )

bool method_exists ( object object, string method_name )

如果 method_name 所指的方法在 object 所指的对象类中已定义，则返回 TRUE，否则返回 FALSE。

property_exists

(PHP 5 >= 5.1.0RC1)

property_exists -- Checks if the object or class has a property

说明

bool property_exists ( mixed class, string property )

This function checks if the given property exists in the specified class (and if it was declared as public).

注: As opposed with isset(), property_exists() returns TRUE even if the property has the value NULL.

参数

class: A string with the class name or an object of the class to test for
property: The name of the property

返回值

Returns TRUE if the property exists or FALSE otherwise.

范例

例子 1. A property_exists() example
<?php class myClass { public $mine; private $xpto; } var_dump(property_exists('myClass', 'mine')); //true var_dump(property_exists(new myClass, 'mine')); //true var_dump(property_exists('myClass', 'xpto')); //false, isn't public ?>

参见

method_exists()

XIII. Classkit Functions

简介

These functions allow the dynamic manipulation of PHP classes, at runtime.

注: This extension has been replaced by runkit, which is not limited to class manipulation but has function manipulation, as well.

安装

本 PECL 扩展未绑定于 PHP 中。

进一步信息例如新版本，下载，源程序，维护者信息以及更新日志可以在此找到： http://pecl.php.net/package/classkit.

可以从 PHP 下载页面或者 http://snaps.php.net/ 下载此 PECL 扩展的 DLL 文件。

运行时配置

本扩展模块在 php.ini 中未定义任何配置选项。

资源类型

本扩展模块未定义任何资源类型。

预定义常量

以下常量由本扩展模块定义，因此只有在本扩展模块被编译到 PHP 中，或者在运行时被动态加载后才有效。

CLASSKIT_ACC_PRIVATE (int): Marks the method private
CLASSKIT_ACC_PROTECTED (int): Marks the method protected
CLASSKIT_ACC_PUBLIC (int): Marks the method public

目录
classkit_import -- Import new class method definitions from a file
classkit_method_add -- Dynamically adds a new method to a given class
classkit_method_copy -- Copies a method from class to another
classkit_method_redefine -- Dynamically changes the code of the given method
classkit_method_remove -- Dynamically removes the given method
classkit_method_rename -- Dynamically changes the name of the given method

classkit_import

(PECL)

classkit_import -- Import new class method definitions from a file

说明

array classkit_import ( string filename )

注: 本函数不能用于操作当前正在运行（或运行链上）的方法。

警告

参数

filename: The filename of the class method definitions to import

返回值

Associative array of imported methods

范例

例子 1. classkit_import() example
<?php // file: newclass.php class Example { function foo() { return "bar!\n"; } } ?>
<?php // requires newclass.php (see above) class Example { function foo() { return "foo!\n"; } } $e = new Example(); // output original echo $e->foo(); // import replacement method classkit_import('newclass.php'); // output imported echo $e->foo(); ?>
上例将输出：
foo! bar!

参见

classkit_method_add

(PECL)

classkit_method_add -- Dynamically adds a new method to a given class

说明

bool classkit_method_add ( string classname, string methodname, string args, string code [, int flags] )

警告

参数

classname: The class to which this method will be added
methodname: The name of the method to add
args: Comma-delimited list of arguments for the newly-created method
code: The code to be evaluated when methodname is called
flags: The type of method to create, can be CLASSKIT_ACC_PUBLIC, CLASSKIT_ACC_PROTECTED or CLASSKIT_ACC_PRIVATE
注: This parameter is only used as of PHP 5, because, prior to this, all methods were public.

返回值

如果成功则返回 TRUE，失败则返回 FALSE。

范例

例子 1. classkit_method_add() example
<?php class Example { function foo() { echo "foo!\n"; } } // create an Example object $e = new Example(); // Add a new public method classkit_method_add( 'Example', 'add', '$num1, $num2', 'return $num1 + $num2;', CLASSKIT_ACC_PUBLIC ); // add 12 + 4 echo $e->add(12, 4); ?>
上例将输出：
16

参见

create_function()

classkit_method_copy

(PECL)

classkit_method_copy -- Copies a method from class to another

说明

bool classkit_method_copy ( string dClass, string dMethod, string sClass [, string sMethod] )

警告

参数

dClass: Destination class for copied method
dMethod: Destination method name
sClass: Source class of the method to copy
sMethod: Name of the method to copy from the source class. If this parameter is omitted, the value of dMethod is assumed.

返回值

如果成功则返回 TRUE，失败则返回 FALSE。

范例

例子 1. classkit_method_copy() example
<?php class Foo { function example() { return "foo!\n"; } } class Bar { // initially, no methods } // copy the example() method from the Foo class to the Bar class, as baz() classkit_method_copy('Bar', 'baz', 'Foo', 'example'); // output copied function echo Bar::baz(); ?>
上例将输出：
foo!

参见

classkit_method_redefine

(PECL)

classkit_method_redefine -- Dynamically changes the code of the given method

说明

bool classkit_method_redefine ( string classname, string methodname, string args, string code [, int flags] )

注: 本函数不能用于操作当前正在运行（或运行链上）的方法。

警告

参数

classname: The class in which to redefine the method
methodname: The name of the method to redefine
args: Comma-delimited list of arguments for the redefined method
code: The new code to be evaluated when methodname is called
flags: The redefined method can be CLASSKIT_ACC_PUBLIC, CLASSKIT_ACC_PROTECTED or CLASSKIT_ACC_PRIVATE
注: This parameter is only used as of PHP 5, because, prior to this, all methods were public.

返回值

如果成功则返回 TRUE，失败则返回 FALSE。

范例

例子 1. classkit_method_redefine() example
<?php class Example { function foo() { return "foo!\n"; } } // create an Example object $e = new Example(); // output Example::foo() (before redefine) echo "Before: " . $e->foo(); // Redefine the 'foo' method classkit_method_redefine( 'Example', 'foo', '', 'return "bar!\n";', CLASSKIT_ACC_PUBLIC ); // output Example::foo() (after redefine) echo "After: " . $e->foo(); ?>
上例将输出：
Before: foo! After: bar!

参见

classkit_method_remove

(PECL)

classkit_method_remove -- Dynamically removes the given method

说明

bool classkit_method_remove ( string classname, string methodname )

注: 本函数不能用于操作当前正在运行（或运行链上）的方法。

警告

参数

classname: The class in which to remove the method
methodname: The name of the method to remove

返回值

如果成功则返回 TRUE，失败则返回 FALSE。

范例

例子 1. classkit_method_remove() example
<?php class Example { function foo() { return "foo!\n"; } function bar() { return "bar!\n"; } } // Remove the 'foo' method classkit_method_remove( 'Example', 'foo' ); echo implode(' ', get_class_methods('Example')); ?>
上例将输出：
bar

参见

classkit_method_rename

(PECL)

classkit_method_rename -- Dynamically changes the name of the given method

说明

bool classkit_method_rename ( string classname, string methodname, string newname )

注: 本函数不能用于操作当前正在运行（或运行链上）的方法。

警告

参数

classname: The class in which to rename the method
methodname: The name of the method to rename
newname: The new name to give to the renamed method

返回值

如果成功则返回 TRUE，失败则返回 FALSE。

范例

例子 1. classkit_method_rename() example
<?php class Example { function foo() { return "foo!\n"; } } // Rename the 'foo' method to 'bar' classkit_method_rename( 'Example', 'foo', 'bar' ); // output renamed function echo Example::bar(); ?>
上例将输出：
foo!

参见

XIV. ClibPDF Functions

简介

ClibPDF lets you create PDF documents with PHP. ClibPDF functionality and API are similar to PDFlib. This documentation should be read alongside the ClibPDF manual since it explains the library in much greater detail.

Many functions in the native ClibPDF and the PHP module, as well as in PDFlib, have the same name. All functions except for cpdf_open() take the handle for the document as their first parameter.

Currently this handle is not used internally since ClibPDF does not support the creation of several PDF documents at the same time. Actually, you should not even try it, the results are unpredictable. I can't oversee what the consequences in a multi threaded environment are. According to the author of ClibPDF this will change in one of the next releases (current version when this was written is 1.10). If you need this functionality use the pdflib module.

A nice feature of ClibPDF (and PDFlib) is the ability to create the pdf document completely in memory without using temporary files. It also provides the ability to pass coordinates in a predefined unit length. (This feature can also be simulated by pdf_translate() when using the PDFlib functions.)

Another nice feature of ClibPDF is the fact that any page can be modified at any time even if a new page has been already opened. The function cpdf_set_current_page() allows to leave the current page and presume modifying an other page.

Most of the functions are fairly easy to use. The most difficult part is probably creating a very simple PDF document at all. The following example should help you to get started. It creates a document with one page. The page contains the text "Times-Roman" in an outlined 30pt font. The text is underlined.

注: 本扩展已被移动到 PECL 库中且自以下版本起不再被绑定到 PHP 中：5.1.0.

注: If you're interested in alternative free PDF generators that do not utilize external PDF libraries, see this related FAQ.

需求

In order to use the ClibPDF functions you need to install the ClibPDF package. It is available for download from FastIO, but requires that you purchase a license for commercial use. PHP requires that you use cpdflib >= 2.

安装

To get these functions to work, you have to compile PHP with --with-cpdflib[=DIR]. DIR is the cpdflib install directory, defaults to /usr. In addition you can specify the jpeg library and the tiff library for ClibPDF to use. To do so add to your configure line the options --with-jpeg-dir[=DIR] --with-tiff-dir[=DIR].

运行时配置

本扩展模块在 php.ini 中未定义任何配置选项。

预定义常量

以下常量由本扩展模块定义，因此只有在本扩展模块被编译到 PHP 中，或者在运行时被动态加载后才有效。

CPDF_PM_NONE (integer)
CPDF_PM_OUTLINES (integer)
CPDF_PM_THUMBS (integer)
CPDF_PM_FULLSCREEN (integer)
CPDF_PL_SINGLE (integer)
CPDF_PL_1COLUMN (integer)
CPDF_PL_2LCOLUMN (integer)
CPDF_PL_2RCOLUMN (integer)

范例

例子 1. Simple ClibPDF Example

<?php
$cpdf = cpdf_open(0);
cpdf_page_init($cpdf, 1, 0, 595, 842, 1.0);
cpdf_add_outline($cpdf, 0, 0, 0, 1, "Page 1");
cpdf_begin_text($cpdf);
cpdf_set_font($cpdf, "Times-Roman", 30, "WinAnsiEncoding");
cpdf_set_text_rendering($cpdf, 1);
cpdf_text($cpdf, "Times Roman outlined", 50, 50);
cpdf_end_text($cpdf);
cpdf_moveto($cpdf, 50, 50);
cpdf_lineto($cpdf, 740, 330);
cpdf_stroke($cpdf);
cpdf_finalize_page($cpdf, 1);
cpdf_finalize($cpdf);
Header("Content-type: application/pdf");
cpdf_output_buffer($cpdf);
cpdf_close($cpdf);
?>

The pdflib distribution contains a more complex example which creates a series of pages with an analog clock. Here is that example converted into PHP using the ClibPDF extension:

例子 2. pdfclock example from pdflib 2.0 distribution

<?php
$radius = 200;
$margin = 20;
$pagecount = 40;

$pdf = cpdf_open(0);
cpdf_set_creator($pdf, "pdf_clock.php");
cpdf_set_title($pdf, "Analog Clock");
  
while ($pagecount-- > 0) {
  cpdf_page_init($pdf, $pagecount+1, 0, 2 * ($radius + $margin), 2 * ($radius + $margin), 1.0);
  
  cpdf_set_page_animation($pdf, 4, 0.5, 0, 0, 0);  /* wipe */
  
  cpdf_translate($pdf, $radius + $margin, $radius + $margin);
  cpdf_save($pdf);
  cpdf_setrgbcolor($pdf, 0.0, 0.0, 1.0);
  
  /* minute strokes */
  cpdf_setlinewidth($pdf, 2.0);
  for ($alpha = 0; $alpha < 360; $alpha += 6) {
    cpdf_rotate($pdf, 6.0);
    cpdf_moveto($pdf, $radius, 0.0);
    cpdf_lineto($pdf, $radius-$margin/3, 0.0);
    cpdf_stroke($pdf);
  }
  
  cpdf_restore($pdf);
  cpdf_save($pdf);
 
  /* 5 minute strokes */
  cpdf_setlinewidth($pdf, 3.0);
  for ($alpha = 0; $alpha < 360; $alpha += 30) {
    cpdf_rotate($pdf, 30.0);
    cpdf_moveto($pdf, $radius, 0.0);
    cpdf_lineto($pdf, $radius-$margin, 0.0);
    cpdf_stroke($pdf);
  }

  $ltime = getdate();

  /* draw hour hand */
  cpdf_save($pdf);
  cpdf_rotate($pdf, -(($ltime['minutes']/60.0) + $ltime['hours'] - 3.0) * 30.0);
  cpdf_moveto($pdf, -$radius/10, -$radius/20);
  cpdf_lineto($pdf, $radius/2, 0.0);
  cpdf_lineto($pdf, -$radius/10, $radius/20);
  cpdf_closepath($pdf);
  cpdf_fill($pdf);
  cpdf_restore($pdf);

  /* draw minute hand */
  cpdf_save($pdf);
  cpdf_rotate($pdf, -(($ltime['seconds']/60.0) + $ltime['minutes'] - 15.0) * 6.0);
  cpdf_moveto($pdf, -$radius/10, -$radius/20);
  cpdf_lineto($pdf, $radius * 0.8, 0.0);
  cpdf_lineto($pdf, -$radius/10, $radius/20);
  cpdf_closepath($pdf);
  cpdf_fill($pdf);
  cpdf_restore($pdf);

  /* draw second hand */
  cpdf_setrgbcolor($pdf, 1.0, 0.0, 0.0);
  cpdf_setlinewidth($pdf, 2);
  cpdf_save($pdf);
  cpdf_rotate($pdf, -(($ltime['seconds'] - 15.0) * 6.0));
  cpdf_moveto($pdf, -$radius/5, 0.0);
  cpdf_lineto($pdf, $radius, 0.0);
  cpdf_stroke($pdf);
  cpdf_restore($pdf);

  /* draw little circle at center */
  cpdf_circle($pdf, 0, 0, $radius/30);
  cpdf_fill($pdf);

  cpdf_restore($pdf);

  cpdf_finalize_page($pdf, $pagecount+1);
}

cpdf_finalize($pdf);
Header("Content-type: application/pdf");
cpdf_output_buffer($pdf);
cpdf_close($pdf);
?>

参见

See also the PDFlib extension documentation.

目录
cpdf_add_annotation -- Adds annotation
cpdf_add_outline -- Adds bookmark for current page
cpdf_arc -- Draws an arc
cpdf_begin_text -- Starts text section
cpdf_circle -- Draw a circle
cpdf_clip -- Clips to current path
cpdf_close -- Closes the pdf document
cpdf_closepath_fill_stroke -- Close, fill and stroke current path
cpdf_closepath_stroke -- Close path and draw line along path
cpdf_closepath -- Close path
cpdf_continue_text -- Output text in next line
cpdf_curveto -- Draws a curve
cpdf_end_text -- Ends text section
cpdf_fill_stroke -- Fill and stroke current path
cpdf_fill -- Fill current path
cpdf_finalize_page -- Ends page
cpdf_finalize -- Ends document
cpdf_global_set_document_limits -- Sets document limits for any pdf document
cpdf_import_jpeg -- Opens a JPEG image
cpdf_lineto -- Draws a line
cpdf_moveto -- Sets current point
cpdf_newpath -- Starts a new path
cpdf_open -- Opens a new pdf document
cpdf_output_buffer -- Outputs the pdf document in memory buffer
cpdf_page_init -- Starts new page
cpdf_place_inline_image -- Places an image on the page
cpdf_rect -- Draw a rectangle
cpdf_restore -- Restores formerly saved environment
cpdf_rlineto -- Draws a line
cpdf_rmoveto -- Sets current point
cpdf_rotate_text -- Sets text rotation angle
cpdf_rotate -- Sets rotation
cpdf_save_to_file -- Writes the pdf document into a file
cpdf_save -- Saves current environment
cpdf_scale -- Sets scaling
cpdf_set_action_url -- Sets hyperlink
cpdf_set_char_spacing -- Sets character spacing
cpdf_set_creator -- Sets the creator field in the pdf document
cpdf_set_current_page -- Sets current page
cpdf_set_font_directories -- Sets directories to search when using external fonts
cpdf_set_font_map_file -- Sets fontname to filename translation map when using external fonts
cpdf_set_font -- Select the current font face and size
cpdf_set_horiz_scaling -- Sets horizontal scaling of text
cpdf_set_keywords -- Sets the keywords field of the pdf document
cpdf_set_leading -- Sets distance between text lines
cpdf_set_page_animation -- Sets duration between pages
cpdf_set_subject -- Sets the subject field of the pdf document
cpdf_set_text_matrix -- Sets the text matrix
cpdf_set_text_pos -- Sets text position
cpdf_set_text_rendering -- Determines how text is rendered
cpdf_set_text_rise -- Sets the text rise
cpdf_set_title -- Sets the title field of the pdf document
cpdf_set_viewer_preferences -- How to show the document in the viewer
cpdf_set_word_spacing -- Sets spacing between words
cpdf_setdash -- Sets dash pattern
cpdf_setflat -- Sets flatness
cpdf_setgray_fill -- Sets filling color to gray value
cpdf_setgray_stroke -- Sets drawing color to gray value
cpdf_setgray -- Sets drawing and filling color to gray value
cpdf_setlinecap -- Sets linecap parameter
cpdf_setlinejoin -- Sets linejoin parameter
cpdf_setlinewidth -- Sets line width
cpdf_setmiterlimit -- Sets miter limit
cpdf_setrgbcolor_fill -- Sets filling color to rgb color value
cpdf_setrgbcolor_stroke -- Sets drawing color to rgb color value
cpdf_setrgbcolor -- Sets drawing and filling color to rgb color value
cpdf_show_xy -- Output text at position
cpdf_show -- Output text at current position
cpdf_stringwidth -- Returns width of text in current font
cpdf_stroke -- Draw line along path
cpdf_text -- Output text with parameters
cpdf_translate -- Sets origin of coordinate system

bool cpdf_curveto ( int pdf_document, float x1, float y1, float x2, float y2, float x3, float y3 [, int mode] )

The cpdf_curveto() function draws a Bezier curve from the current point to the point (x3, y3) using (x1, y1) and (x2, y2) as control points. 如果成功则返回 TRUE，失败则返回 FALSE。

可选参数 mode 决定单元的长度。如果为 0 或被省略则使用该页指定的默认单元。否则坐标忽略当前单元而使用 postscript 的点来度量。

cpdf_end_text

(PHP 3 >= 3.0.8, PHP 4, PHP 5 <= 5.0.4)

cpdf_end_text -- Ends text section

Description

bool cpdf_end_text ( int pdf_document )

bool cpdf_finalize_page ( int pdf_document, int page_number )

bool cpdf_newpath ( int pdf_document )

The cpdf_newpath() starts a new path on the document given by the pdf_document parameter. 如果成功则返回 TRUE，失败则返回 FALSE。

cpdf_open

(PHP 3 >= 3.0.8, PHP 4, PHP 5 <= 5.0.4)

cpdf_open -- Opens a new pdf document

Description

int cpdf_open ( int compression [, string filename [, array doc_limits]] )

The cpdf_open() function opens a new pdf document. The first parameter turns document compression on if it is unequal to 0. The second optional parameter sets the file in which the document is written. If it is omitted the document is created in memory and can either be written into a file with the cpdf_save_to_file() or written to standard output with cpdf_output_buffer().

注: The return value will be needed in further versions of ClibPDF as the first parameter in all other functions which are writing to the pdf document.
The ClibPDF library takes the filename "-" as a synonym for stdout. If PHP is compiled as an apache module this will not work because the way ClibPDF outputs to stdout does not work with apache. You can solve this problem by skipping the filename and using cpdf_output_buffer() to output the pdf document.

可选参数 mode 决定单元的长度。如果为 0 或被省略则使用该页指定的默认单元。否则坐标忽略当前单元而使用 postscript 的点来度量。

注: This function is only available if PHP was compiled with the GD Graphics Library 1.3. See the GD extension installation instructions for further information.

cpdf_rect

(PHP 3 >= 3.0.8, PHP 4, PHP 5 <= 5.0.4)

cpdf_rect -- Draw a rectangle

Description

bool cpdf_rect ( int pdf_document, float x_coor, float y_coor, float width, float height [, int mode] )

bool cpdf_rotate ( int pdf_document, float angle )

The cpdf_rotate() function set the rotation in degrees to angle. 如果成功则返回 TRUE，失败则返回 FALSE。

cpdf_save_to_file

(PHP 3 >= 3.0.8, PHP 4, PHP 5 <= 5.0.4)

cpdf_save_to_file -- Writes the pdf document into a file

Description

bool cpdf_save_to_file ( int pdf_document, string filename )

bool cpdf_set_action_url ( int pdfdoc, float xll, float yll, float xur, float xur, string url [, int mode] )

bool cpdf_set_font_directories ( int pdfdoc, string pfmdir, string pfbdir )

警告

本函数暂无文档，仅有参数列表。

cpdf_set_font_map_file

(PHP 4 >= 4.0.6, PHP 5 <= 5.0.4)

cpdf_set_font_map_file -- Sets fontname to filename translation map when using external fonts

Description

bool cpdf_set_font_map_file ( int pdfdoc, string filename )

警告

本函数暂无文档，仅有参数列表。

cpdf_set_font

(PHP 3 >= 3.0.8, PHP 4, PHP 5 <= 5.0.4)

cpdf_set_font -- Select the current font face and size

Description

bool cpdf_set_font ( int pdf_document, string font_name, float size, string encoding )

The cpdf_set_font() function sets the current font face, font size and encoding. Currently only the standard postscript fonts are supported. 如果成功则返回 TRUE，失败则返回 FALSE。

bool cpdf_set_page_animation ( int pdf_document, int transition, float duration, float direction, int orientation, int inout )

The cpdf_set_page_animation() function set the transition between following pages. 如果成功则返回 TRUE，失败则返回 FALSE。

The value of transition can be

0 for none,

1 for two lines sweeping across the screen reveal the page,

2 for multiple lines sweeping across the screen reveal the page,

3 for a box reveals the page,

4 for a single line sweeping across the screen reveals the page,

5 for the old page dissolves to reveal the page,

6 for the dissolve effect moves from one screen edge to another,

bool cpdf_set_text_pos ( int pdf_document, float x_coor, float y_coor [, int mode] )

The cpdf_set_text_pos() function sets the position of text for the next cpdf_show() function call. 如果成功则返回 TRUE，失败则返回 FALSE。

可选参数 mode 决定单元的长度。如果为 0 或被省略则使用该页指定的默认单元。否则坐标忽略当前单元而使用 postscript 的点来度量。

See also cpdf_show() and cpdf_text().

cpdf_set_text_rendering

(PHP 3 >= 3.0.8, PHP 4, PHP 5 <= 5.0.4)

cpdf_set_text_rendering -- Determines how text is rendered

Description

bool cpdf_set_text_rendering ( int pdf_document, int rendermode )

bool cpdf_set_viewer_preferences ( int pdfdoc, array preferences )

bool cpdf_setrgbcolor_fill ( int pdf_document, float red_value, float green_value, float blue_value )

The cpdf_setrgbcolor_fill() function sets the current rgb color value to fill a path. 如果成功则返回 TRUE，失败则返回 FALSE。

注: The values are expected to be floating point values between 0.0 and 1.0. (i.e black is (0.0, 0.0, 0.0) and white is (1.0, 1.0, 1.0)).

cpdf_setrgbcolor_stroke

(PHP 3 >= 3.0.8, PHP 4, PHP 5 <= 5.0.4)

cpdf_setrgbcolor_stroke -- Sets drawing color to rgb color value

Description

bool cpdf_setrgbcolor_stroke ( int pdf_document, float red_value, float green_value, float blue_value )

The cpdf_setrgbcolor_stroke() function sets the current drawing color to the given rgb color value. 如果成功则返回 TRUE，失败则返回 FALSE。

注: The values are expected to be floating point values between 0.0 and 1.0. (i.e black is (0.0, 0.0, 0.0) and white is (1.0, 1.0, 1.0)).

cpdf_setrgbcolor

(PHP 3 >= 3.0.8, PHP 4, PHP 5 <= 5.0.4)

cpdf_setrgbcolor -- Sets drawing and filling color to rgb color value

Description

bool cpdf_setrgbcolor ( int pdf_document, float red_value, float green_value, float blue_value )

The cpdf_setrgbcolor() function sets the current drawing and filling color to the given rgb color value. 如果成功则返回 TRUE，失败则返回 FALSE。

注: The values are expected to be floating point values between 0.0 and 1.0. (i.e black is (0.0, 0.0, 0.0) and white is (1.0, 1.0, 1.0)).

cpdf_show_xy

(PHP 3 >= 3.0.8, PHP 4, PHP 5 <= 5.0.4)

cpdf_show_xy -- Output text at position

Description

bool cpdf_show_xy ( int pdf_document, string text, float x_coor, float y_coor [, int mode] )

The cpdf_show_xy() function outputs the string text at position with coordinates (x_coor, y_coor). 如果成功则返回 TRUE，失败则返回 FALSE。

可选参数 mode 决定单元的长度。如果为 0 或被省略则使用该页指定的默认单元。否则坐标忽略当前单元而使用 postscript 的点来度量。

注: The function cpdf_show_xy() is identical to cpdf_text() without the optional parameters.

可选参数 mode 决定单元的长度。如果为 0 或被省略则使用该页指定的默认单元。否则坐标忽略当前单元而使用 postscript 的点来度量。

The optional parameter orientation is the rotation of the text in degree.

The optional parameter alignmode determines how the text is aligned.

See the ClibPDF documentation for possible values.

cpdf_translate

(PHP 3 >= 3.0.8, PHP 4, PHP 5 <= 5.0.4)

cpdf_translate -- Sets origin of coordinate system

Description

bool cpdf_translate ( int pdf_document, float x_coor, float y_coor )

The cpdf_translate() function set the origin of coordinate system to the point (x_coor, y_coor). 如果成功则返回 TRUE，失败则返回 FALSE。

可选参数 mode 决定单元的长度。如果为 0 或被省略则使用该页指定的默认单元。否则坐标忽略当前单元而使用 postscript 的点来度量。

XV. COM 和 .Net（Windows）函数

简介

COM is an acronym for Component Object Model; it is an object orientated layer (and associated services) on top of DCE RPC (an open standard) and defines a common calling convention that enables code written in any language to call and interoperate with code written in any other language (provided those languages are COM aware). Not only can the code be written in any language, but it need not even be part of the same executable; the code can be loaded from a DLL, be found in another process running on the same machine, or, with DCOM (Distributed COM), be found in another process on a remote machine, all without your code even needing to know where a component resides.

There is a subset of COM known as OLE Automation which comprises a set of COM interfaces that allow loose binding to COM objects, so that they can be introspected and called at run-time without compile-time knowledge of how the object works. The PHP COM extension utilizes the OLE Automation interfaces to allow you to create and call compatible objects from your scripts. Technically speaking, this should really be called the "OLE Automation Extension for PHP", since not all COM objects are OLE compatible.

Now, why would or should you use COM? COM is one of the main ways to glue applications and components together on the Windows platform; using COM you can launch Microsoft Word, fill in a document template and save the result as a Word document and send it to a visitor of your web site. You can also use COM to perform administrative tasks for your network and to configure your IIS; these are just the most common uses; you can do much more with COM.

Starting with PHP 5, this extension (and this documentation) was rewritten from scratch and much of the old confusing and bogus cruft has be removed. Additionally, we support the instantiation and creation of .Net assemblies using the COM interoperability layer provided by Microsoft.

Please read this article for an overview of the changes in this extension in PHP 5.

需求

COM functions are only available for the Windows version of PHP.

.Net support requires PHP 5 and the .Net runtime.

安装

本函数库作为 PHP 内核的一部分，不用安装就能使用。

PHP 的 Windows 版本已经内置该扩展模块的支持。无需加载任何附加扩展库即可使用这些函数。

You are responsible for installing support for the various COM objects that you intend to use (such as MS Word); we don't and can't bundle all of those with PHP.

For Each

Starting with PHP 5, you may use PHP's own the 节 called foreach 在 µÚ 16 章 statement to iterate over the contents of a standard COM/OLE IEnumVariant. In laymans terms, this means that you can use foreach in places where you would have used For Each in VB/ASP code.

例子 1. For Each in ASP
<% Set domainObject = GetObject("WinNT://Domain") For Each obj in domainObject Response.Write obj.Name & "<br />" Next %>

例子 2. while() ... Next() in PHP 4
<?php $domainObject = new COM("WinNT://Domain"); while ($obj = $domainObject->Next()) { echo $obj->Name . "<br />"; } ?>

例子 3. foreach in PHP 5
<?php $domainObject = new COM("WinNT://Domain"); foreach ($domainObject as $obj) { echo $obj->Name . "<br />"; } ?>

Arrays and Array-style COM properties

Many COM objects expose their properties as arrays, or using array-style access. In PHP 4, you may use PHP array syntax to read/write such a property, but only a single dimension is allowed. If you want to read a multi-dimensional property, you could instead make the property access into a function call, with each parameter representing each dimension of the array access, but there is no way to write to such a property.

PHP 5 introduces the following new features to make your life easier:

Access multi-dimensional arrays, or COM properties that require multiple parameters using PHP array syntax. You can also write or set properties using this technique.
Iterate SafeArrays ("true" arrays) using the the 节 called foreach 在 µÚ 16 章 control structure. This works because SafeArrays include information about their size. If an array-style property implements IEnumVariant then you can also use foreach for that property too; take a look at the 节 called For Each for more information on this topic.

Exceptions (PHP 5)

This extension will throw instances of the class com_exception whenever there is a potentially fatal error reported by COM. All COM exceptions have a well-defined code property that corresponds to the HRESULT return value from the various COM operations. You may use this code to make programmatic decisions on how to handle the exception.

运行时配置

这些函数的行为受 php.ini 的影响。

表格 1. COM 配置选项

名称	默认值	可修改范围	更新记录
com.allow_dcom	"0"	PHP_INI_SYSTEM	自 PHP 4.0.5 起可用
com.autoregister_typelib	"0"	PHP_INI_ALL	在 PHP 4 中是 PHP_INI_SYSTEM。自 PHP 4.1.0 起可用
com.autoregister_verbose	"0"	PHP_INI_ALL	在 PHP 4 中是 PHP_INI_SYSTEM。自 PHP 4.1.0 起可用
com.autoregister_casesensitive	"1"	PHP_INI_ALL	在 PHP 4 中是 PHP_INI_SYSTEM。自 PHP 4.1.0 起可用
com.code_page	""	PHP_INI_ALL	自 PHP 5.0.0 起可用
com.typelib_file	""	PHP_INI_SYSTEM	自 PHP 4.0.5 起可用

有关 PHP_INI_* 常量进一步的细节与定义参见附录 G。

以下是配置选项的简要解释。

com.allow_dcom

如果打开此选项，PHP 将被允许以一个 D-COM（Distributed COM）客户方式操作并允许 PHP 脚本在远程服务器上实例化 COM 对象。

com.autoregister_typelib

When this is turned on, PHP will attempt to register constants from the typelibrary of objects that it instantiates, if those objects implement the interfaces required to obtain that information. The case sensitivity of the constants it registers is controlled by the com.autoregister_casesensitive configuration directive.

com.autoregister_verbose

When this is turned on, any problems with loading a typelibrary during object instantiation will be reported using the PHP error mechanism. The default is off, which does not emit any indication if there was an error finding or loading the type library.

com.autoregister_casesensitive

When this is turned on (the default), constants found in auto-loaded type libraries will be registered case sensitively. See com_load_typelib() for more details.

com.code_page

It controls the default character set code-page to use when passing strings to and from COM objects. If set to an empty string, PHP will assume that you want CP_ACP, which is the default system ANSI code page.

If the text in your scripts is encoded using a different encoding/character set by default, setting this directive will save you from having to pass the code page as a parameter to the COM class constructor. Please note that by using this directive (as with any PHP configuration directive), your PHP script becomes less portable; you should use the COM constructor parameter whenever possible.

注: This configuration directive was introduced with PHP 5.

com.typelib_file

When set, this should hold the path to a file that contains a list of typelibraries that should be loaded on startup. Each line of the file will be treated as the type library name and loaded as though you had called com_load_typelib(). The constants will be registered persistently, so that the library only needs to be loaded once. If a type library name ends with the string #cis or #case_insensitive, then the constants from that library will be registered case insensitively.

预定义常量

以下常量由本扩展模块定义，因此只有在本扩展模块被编译到 PHP 中，或者在运行时被动态加载后才有效。

CLSCTX_INPROC_SERVER (integer)
CLSCTX_INPROC_HANDLER (integer)
CLSCTX_LOCAL_SERVER (integer)
CLSCTX_REMOTE_SERVER (integer)
CLSCTX_SERVER (integer)
CLSCTX_ALL (integer)
VT_NULL (integer)
VT_EMPTY (integer)
VT_UI1 (integer)
VT_I2 (integer)
VT_I4 (integer)
VT_R4 (integer)
VT_R8 (integer)
VT_BOOL (integer)
VT_ERROR (integer)
VT_CY (integer)
VT_DATE (integer)
VT_BSTR (integer)
VT_DECIMAL (integer)
VT_UNKNOWN (integer)
VT_DISPATCH (integer)
VT_VARIANT (integer)
VT_I1 (integer)
VT_UI2 (integer)
VT_UI4 (integer)
VT_INT (integer)
VT_UINT (integer)
VT_ARRAY (integer)
VT_BYREF (integer)
CP_ACP (integer)
CP_MACCP (integer)
CP_OEMCP (integer)
CP_UTF7 (integer)
CP_UTF8 (integer)
CP_SYMBOL (integer)
CP_THREAD_ACP (integer)
VARCMP_LT (integer)
VARCMP_EQ (integer)
VARCMP_GT (integer)
VARCMP_NULL (integer)
NORM_IGNORECASE (integer)
NORM_IGNORENONSPACE (integer)
NORM_IGNORESYMBOLS (integer)
NORM_IGNOREWIDTH (integer)
NORM_IGNOREKANATYPE (integer)
NORM_IGNOREKASHIDA (integer)
DISP_E_DIVBYZERO (integer)
DISP_E_OVERFLOW (integer)
MK_E_UNAVAILABLE (integer)

参见

For further information on COM read the COM specification or perhaps take a look at Don Box's Yet Another COM Library (YACL). You might find some additional useful information in our FAQ for µÚ 55 章. If you're thinking of using MS Office applications on the server side, you should read the information here: Considerations for Server-Side Automation of Office.

目录
COM -- COM 类
DOTNET -- DOTNET class
VARIANT -- VARIANT 类
com_addref -- 增加组件引用计数。[被废弃]
com_create_guid -- Generate a globally unique identifier (GUID)
com_event_sink -- Connect events from a COM object to a PHP object
com_get_active_object -- Returns a handle to an already running instance of a COM object
com_get -- 获取 COM 组件的属性值 [被废弃]
com_invoke -- 调用 COM 组件的方法。
com_isenum -- 获取一个 IEnumVariant
com_load_typelib -- 装载一个 Typelib
com_load -- 创建新的 COM 组件的引用
com_message_pump -- Process COM messages, sleeping for up to timeoutms milliseconds
com_print_typeinfo -- Print out a PHP class definition for a dispatchable interface
com_propget -- com_get() 的别名
com_propput -- com_set() 的别名
com_propset -- com_set() 的别名
com_release -- 减少组件引用计数。[被废弃]
com_set -- 给 COM 组件的属性赋值
variant_abs -- Returns the absolute value of a variant
variant_add -- "Adds" two variant values together and returns the result
variant_and -- performs a bitwise AND operation between two variants and returns the result
variant_cast -- Convert a variant into a new variant object of another type
variant_cat -- concatenates two variant values together and returns the result
variant_cmp -- Compares two variants
variant_date_from_timestamp -- Returns a variant date representation of a unix timestamp
variant_date_to_timestamp -- Converts a variant date/time value to unix timestamp
variant_div -- Returns the result from dividing two variants
variant_eqv -- Performs a bitwise equivalence on two variants
variant_fix -- Returns the integer portion ? of a variant
variant_get_type -- Returns the type of a variant object
variant_idiv -- Converts variants to integers and then returns the result from dividing them
variant_imp -- Performs a bitwise implication on two variants
variant_int -- Returns the integer portion of a variant
variant_mod -- Divides two variants and returns only the remainder
variant_mul -- multiplies the values of the two variants and returns the result
variant_neg -- Performs logical negation on a variant
variant_not -- Performs bitwise not negation on a variant
variant_or -- Performs a logical disjunction on two variants
variant_pow -- Returns the result of performing the power function with two variants
variant_round -- Rounds a variant to the specified number of decimal places
variant_set_type -- Convert a variant into another type "in-place"
variant_set -- Assigns a new value for a variant object
variant_sub -- subtracts the value of the right variant from the left variant value and returns the result
variant_xor -- Performs a logical exclusion on two variants

COM

(no version information, might be only in CVS)

COM -- COM 类

大纲

$obj = new COM("server.object")

描述

COM 类提供了一个将 (D)COM 组件整合到 PHP 脚本中的框架。

方法

string COM::COM ( string module_name [, string server_name [, int codepage]] )

COM 类构造函数。参数：

module_name: 被请求组件的名字或 class-id。
server_name: DCOM 服务器的名字，组件在此服务器上被取用。如果是 NULL，则假定是 localhost。想要允许 DCOM，必须将 php.ini 中的 com.allow_dcom 设为 TRUE。
codepage: 指定用于将 PHP 字符串（php-strings）转换成 UNICODE 字符串（unicode-strings）的代码页，反之亦然。可用的值为 CP_ACP、CP_MACCP、CP_OEMCP、CP_SYMBOL、CP_THREAD_ACP, CP_UTF7 和 CP_UTF8。

例子 1. COM 示例（1）
// 启动 word $word = new COM("word.application") or die("Unable to instanciate Word"); print "Loaded Word, version {$word->Version}\n"; //将其置前 $word->Visible = 1; //打开一个空文档 $word->Documents->Add(); //随便做些事情 $word->Selection->TypeText("This is a test..."); $word->Documents[1]->SaveAs("Useless test.doc"); //关闭 word $word->Quit(); //释放对象 $word->Release(); $word = null;

例子 2. COM 示例（2）
$conn = new COM("ADODB.Connection") or die("Cannot start ADO"); $conn->Open("Provider=SQLOLEDB; Data Source=localhost; Initial Catalog=database; User ID=user; Password=password"); $rs = $conn->Execute("SELECT * FROM sometable"); // 记录集 $num_columns = $rs->Fields->Count(); echo $num_columns . "\n"; for ($i=0; $i < $num_columns; $i++) { $fld[$i] = $rs->Fields($i); } $rowcount = 0; while (!$rs->EOF) { for ($i=0; $i < $num_columns; $i++) { echo $fld[$i]->value . "\t"; } echo "\n"; $rowcount++; // rowcount 自增 $rs->MoveNext(); } $rs->Close(); $conn->Close(); $rs->Release(); $conn->Release(); $rs = null; $conn = null;

DOTNET

(no version information, might be only in CVS)

DOTNET -- DOTNET class

大纲

$obj = new DOTNET("assembly", "classname")

Description

The DOTNET class allows you to instantiate a class from a .Net assembly and call its methods and access its properties.

Methods

string DOTNET::DOTNET ( string assembly_name, string class_name [, int codepage] )

DOTNET class constructor. assembly_name specifies which assembly should be loaded, and class_name specifices which class in that assembly to instantiate. You may optionally specify a codepage to use for unicode string transformations; see the COM class for more details on code pages.

The returned object is an overloaded object, which means that PHP does not see any fixed methods as it does with regular classes; instead, any property or method accesses are passed through to COM and from there to DOTNET. In other words, the .Net object is mapped through the COM interoperability layer provided by the .Net runtime.

Once you have created a DOTNET object, PHP treats it identically to any other COM object; all the same rules apply.

例子 1. DOTNET example
<?php $stack = new DOTNET("mscorlib", "System.Collections.Stack"); $stack->Push(".Net"); $stack->Push("Hello "); echo $stack->Pop() . $stack->Pop(); ?>

注: You need to install the .Net runtime on your web server to take advantage of this feature.

VARIANT

(no version information, might be only in CVS)

VARIANT -- VARIANT 类

大纲

$vVar = new VARIANT($var)

描述

用于将变量封装进 VARIANT 结构中的简单容器。

方法

string VARIANT::VARIANT ( [mixed value [, int type [, int codepage]]] )

VARIANT 类构造函数。参数：

value: 初始值。若省略则创建一个 VT_EMPTY 对象。
type: 指定 VARIANT 对象的内容类型。可用的值为 VT_UI1、VT_UI2、VT_UI4、VT_I1、VT_I2、VT_I4、VT_R4、VT_R8、VT_INT、VT_UINT、VT_BOOL、VT_ERROR、VT_CY、VT_DATE、VT_BSTR、VT_DECIMAL、VT_UNKNOWN、VT_DISPATCH 和 VT_VARIANT。这些值相互排斥，但是可以使用 VT_BYREF 将它们联合起来指定为一个值。若省略，则使用参数 value 的类型。额外信息请查阅 msdn 库。
codepage: 指定用于将 PHP 字符串（php-strings）转换成 UNICODE 字符串（unicode-strings）的代码页，反之亦然。可用的值为 CP_ACP、CP_MACCP、CP_OEMCP、CP_SYMBOL、CP_THREAD_ACP, CP_UTF7 和 CP_UTF8。

com_addref

(PHP 4 >= 4.1.0)

com_addref -- 增加组件引用计数。[被废弃]

描述

void com_addref ( void )

增加组件引用计数。

警告

你应当不再需要使用该函数。

注: 该函数已经在 PHP 5 取消。

com_create_guid

(PHP 5)

com_create_guid -- Generate a globally unique identifier (GUID)

Description

string com_create_guid ( void )

Generates a Globally Unique Identifier (GUID) and returns it as a string. A GUID is generated in the same way as DCE UUID's, except that the Microsoft convention is to enclose a GUID in curly braces.

See also uuid_create() in the PECL uuid extension.

com_event_sink

(PHP 4 >= 4.2.3, PHP 5)

com_event_sink -- Connect events from a COM object to a PHP object

Description

bool com_event_sink ( variant comobject, object sinkobject [, mixed sinkinterface] )

Instructs COM to sink events generated by comobject into the PHP object sinkobject. PHP will attempt to use the default dispinterface type specified by the typelibrary associated with comobject, but you may override this choice by setting sinkinterface to the name of the dispinterface that you want to use.

sinkobject should be an instance of a class with methods named after those of the desired dispinterface; you may use com_print_typeinfo() to help generate a template class for this purpose.

Be careful how you use this feature; if you are doing something similar to the example below, then it doesn't really make sense to run it in a web server context.

例子 1. COM event sink example

<?php
class IEEventSinker {
  var $terminated = false;

  function ProgressChange($progress, $progressmax) {
    echo "Download progress: $progress / $progressmax\n";
  }

  function DocumentComplete(&$dom, $url) {
    echo "Document $url complete\n";
  }

  function OnQuit() {
    echo "Quit!\n";
    $this->terminated = true;
  }
}
$ie = new COM("InternetExplorer.Application");
// note that you don't need the & for PHP 5!
$sink =& new IEEventSinker();
com_event_sink($ie, $sink, "DWebBrowserEvents2");
$ie->Visible = true;
$ie->Navigate("http://www.php.net");
while(!$sink->terminated) {
  com_message_pump(4000);
}
$ie = null;
?>

com_get_active_object

(PHP 5)

com_get_active_object -- Returns a handle to an already running instance of a COM object

Description

variant com_get_active_object ( string progid [, int code_page] )

com_get_active_object() is similar to creating a new instance of a COM object, except that it will only return an object to your script if the object is already running. OLE applications use something known as the Running Object Table to allow well-known applications to be launched only once; this function exposes the COM library function GetActiveObject() to get a handle on a running instance.

progid must be either the ProgID or CLSID for the object that you want to access (for example Word.Application). code_page acts in precisely the same way that it does for the COM class.

If the requested object is running, it will be returned to your script just like any other COM object. Otherwise a com_exception will be raised. There are a variety of reasons why this function might fail, the most common being that the object is not already running. In that situation, the exception error code will be MK_E_UNAVAILABLE; you can use the getCode method of the exception object to check the exception code.

警告

Using com_get_active_object() in a web server context is not always a smart idea. Most COM/OLE applications are not designed to handle more than one client concurrently, even (or especially!) Microsoft Office. You should read Considerations for Server-Side Automation of Office for more information on the general issues involved.

com_get

(PHP 3 >= 3.0.3, PHP 4)

com_get -- 获取 COM 组件的属性值 [被废弃]

描述

mixed com_get ( resource com_object, string property )

返回由 com_object 所引用的 COM 对象的 property 属性值，出错则返回 FALSE。

例子 1. 不要使用 com_get() ，使用 OO 语法代替
<?php // do this $var = $obj->property; // instead of this: $var = com_get($obj, 'property'); ?>

注: 本函数在 PHP 5 中不存在，应该使用常规的并更自然的面向对象语法来访问属性或调用方法。

com_invoke

(PHP 4)

com_invoke -- 调用 COM 组件的方法。

string com_load ( string module_name [, string server_name [, int codepage]] )

com_load() 创建新的 COM 组件同时返回此组件的引用。失败则返回 FALSE。codepage 可用的值为：CP_ACP、CP_MACCP、CP_OEMCP、CP_SYMBOL、CP_THREAD_ACP, CP_UTF7 和 CP_UTF8。

com_message_pump

(PHP 4 >= 4.2.3, PHP 5)

com_message_pump -- Process COM messages, sleeping for up to timeoutms milliseconds

Description

bool com_message_pump ( [int timeoutms] )

This function will sleep for up to timeoutms milliseconds, or until a message arrives in the queue. If a message or messages arrives before the timeout, they will be dispatched, and the function will return TRUE. If the timeout occurs and no messages were processed, the return value will be FALSE. If you do not specify a value for timeoutms, then 0 will be assumed. A 0 value means that no waiting will be performed; if there are messages pending they will be dispatched as before; if there are no messages pending, the function will return FALSE immediately without sleeping.

The purpose of this function is to route COM calls between apartments and handle various synchronization issues. This allows your script to wait efficiently for events to be triggered, while still handling other events or running other code in the background. You should use it in a loop, as demonstrated by the example in the com_event_sink() function, until you are finished using event bound COM objects.

com_print_typeinfo

(PHP 4 >= 4.2.3, PHP 5)

com_print_typeinfo -- Print out a PHP class definition for a dispatchable interface

Description

bool com_print_typeinfo ( object comobject [, string dispinterface [, bool wantsink]] )

The purpose of this function is to help generate a skeleton class for use as an event sink. You may also use it to generate a dump of any COM object, provided that it supports enough of the introspection interfaces, and that you know the name of the interface you want to display.

void com_release ( void )

减少组件引用计数。

警告

你应当不再需要使用该函数。

注: 该函数已经在 PHP 5 取消。

com_set

(PHP 3 >= 3.0.3, PHP 4)

com_set -- 给 COM 组件的属性赋值

描述

void com_set ( resource com_object, string property, mixed value )

设置由 com_object 所引用的对象的 property 属性值。成功则返回新设置的值，出错则返回 FALSE。

例子 1. 不要使用 com_set() ，使用 OO 语法代替
<?php // do this $obj->property = $value; // instead of this: com_set($obj, 'property', $value); ?>

注: 本函数在 PHP 5 中不存在，应该使用常规的并更自然的面向对象语法来访问属性或调用方法。

variant_abs

(PHP 5)

variant_abs -- Returns the absolute value of a variant

Description

This function wraps VariantChangeType() in the COM library; consult MSDN for more information.

variant_cat

(PHP 5)

variant_cat -- concatenates two variant values together and returns the result

Description

mixed variant_cat ( mixed left, mixed right )

Concatenates left with right and returns the result.

See also the 节 called 字符串运算符 在 µÚ 15 章 for the string concatenation operator; this function is notionally equivalent to $left . $right.

注: 对于所有的变量算法函数，此函数的参数可以要么是 PHP 自身的类型（整型，字符串，浮点型，布尔型或者 NULL），要么是一个 COM，VARIANT 或 DOTNET 类的实例。PHP 自身类型将被转换为变量，使用与 VARIANT 类的构造函数中相同的规则。COM 和 DOTNET 对象将具有其默认属性的值，取得并作为变量值使用。
变量算法函数是 COM 库中与其名称接近的函数的封装。此类函数的更多信息请参考 MSDN 库。PHP 函数命名有少许不同，例如 PHP 中的 variant_add() 对应于 MSDN 文档中的 VarAdd()。

variant_cmp

(PHP 5)

variant_cmp -- Compares two variants

Description

int variant_cmp ( mixed left, mixed right [, int lcid [, int flags]] )

Compares left with right and returns one of the following values:

表格 1. Variant Comparision Results

value	meaning
`VARCMP_LT`	`left` is less than `right`
`VARCMP_EQ`	`left` is equal to `right`
`VARCMP_GT`	`left` is greater than `right`
`VARCMP_NULL`	Either `left`, `right` or both are `NULL`

This function will only compare scalar values, not arrays or variant records.

lcid is a valid Locale Identifier to use when comparing strings (this affects string collation). flags can be one or more of the following values OR'd together, and affects string comparisons:

表格 2. Variant Comparision Flags

value	meaning
`NORM_IGNORECASE`	Compare case insensitively
`NORM_IGNORENONSPACE`	Ignore nonspacing characters
`NORM_IGNORESYMBOLS`	Ignore symbols
`NORM_IGNOREWIDTH`	Ignore string width
`NORM_IGNOREKANATYPE`	Ignore Kana type
`NORM_IGNOREKASHIDA`	Ignore Arabic kashida characters

注: 对于所有的变量算法函数，此函数的参数可以要么是 PHP 自身的类型（整型，字符串，浮点型，布尔型或者 NULL），要么是一个 COM，VARIANT 或 DOTNET 类的实例。PHP 自身类型将被转换为变量，使用与 VARIANT 类的构造函数中相同的规则。COM 和 DOTNET 对象将具有其默认属性的值，取得并作为变量值使用。
变量算法函数是 COM 库中与其名称接近的函数的封装。此类函数的更多信息请参考 MSDN 库。PHP 函数命名有少许不同，例如 PHP 中的 variant_add() 对应于 MSDN 文档中的 VarAdd()。

If	Then
Both expressions are of the string, date, character, boolean type	Double is returned
One expression is a string type and the other a character	Division and a double is returned
One expression is numeric and the other is a string	Division and a double is returned.
Both expressions are numeric	Division and a double is returned
Either expression is NULL	NULL is returned
`right` is empty and `left` is anything but empty	A com_exception with code `DISP_E_DIVBYZERO` is thrown
`left` is empty and `right` is anything but empty.	0 as type double is returned
Both expressions are empty	A com_exception with code `DISP_E_OVERFLOW` is thrown

注: 对于所有的变量算法函数，此函数的参数可以要么是 PHP 自身的类型（整型，字符串，浮点型，布尔型或者 NULL），要么是一个 COM，VARIANT 或 DOTNET 类的实例。PHP 自身类型将被转换为变量，使用与 VARIANT 类的构造函数中相同的规则。COM 和 DOTNET 对象将具有其默认属性的值，取得并作为变量值使用。
变量算法函数是 COM 库中与其名称接近的函数的封装。此类函数的更多信息请参考 MSDN 库。PHP 函数命名有少许不同，例如 PHP 中的 variant_add() 对应于 MSDN 文档中的 VarAdd()。

variant_eqv

(PHP 5)

variant_eqv -- Performs a bitwise equivalence on two variants

Description

mixed variant_eqv ( mixed left, mixed right )

If each bit in left is equal to the corresponding bit in right then TRUE is returned, otherwise FALSE is returned.

注: 对于所有的变量算法函数，此函数的参数可以要么是 PHP 自身的类型（整型，字符串，浮点型，布尔型或者 NULL），要么是一个 COM，VARIANT 或 DOTNET 类的实例。PHP 自身类型将被转换为变量，使用与 VARIANT 类的构造函数中相同的规则。COM 和 DOTNET 对象将具有其默认属性的值，取得并作为变量值使用。
变量算法函数是 COM 库中与其名称接近的函数的封装。此类函数的更多信息请参考 MSDN 库。PHP 函数命名有少许不同，例如 PHP 中的 variant_add() 对应于 MSDN 文档中的 VarAdd()。

variant_fix

(PHP 5)

variant_fix -- Returns the integer portion ? of a variant

Description

mixed variant_fix ( mixed variant )

If variant is negative, then the first negative integer greater than or equal to the variant is returned, otherwise returns the integer portion of the value of variant.

警告

This documentation is based on the MSDN documentation; it appears that this function is either the same as variant_int(), or that there is an error in the MSDN documentation.

注: 对于所有的变量算法函数，此函数的参数可以要么是 PHP 自身的类型（整型，字符串，浮点型，布尔型或者 NULL），要么是一个 COM，VARIANT 或 DOTNET 类的实例。PHP 自身类型将被转换为变量，使用与 VARIANT 类的构造函数中相同的规则。COM 和 DOTNET 对象将具有其默认属性的值，取得并作为变量值使用。
变量算法函数是 COM 库中与其名称接近的函数的封装。此类函数的更多信息请参考 MSDN 库。PHP 函数命名有少许不同，例如 PHP 中的 variant_add() 对应于 MSDN 文档中的 VarAdd()。

注: 对于所有的变量算法函数，此函数的参数可以要么是 PHP 自身的类型（整型，字符串，浮点型，布尔型或者 NULL），要么是一个 COM，VARIANT 或 DOTNET 类的实例。PHP 自身类型将被转换为变量，使用与 VARIANT 类的构造函数中相同的规则。COM 和 DOTNET 对象将具有其默认属性的值，取得并作为变量值使用。
变量算法函数是 COM 库中与其名称接近的函数的封装。此类函数的更多信息请参考 MSDN 库。PHP 函数命名有少许不同，例如 PHP 中的 variant_add() 对应于 MSDN 文档中的 VarAdd()。

variant_int

(PHP 5)

variant_int -- Returns the integer portion of a variant

Description

mixed variant_int ( mixed variant )

If variant is negative, then the first negative integer greater than or equal to the variant is returned, otherwise returns the integer portion of the value of variant.

注: 对于所有的变量算法函数，此函数的参数可以要么是 PHP 自身的类型（整型，字符串，浮点型，布尔型或者 NULL），要么是一个 COM，VARIANT 或 DOTNET 类的实例。PHP 自身类型将被转换为变量，使用与 VARIANT 类的构造函数中相同的规则。COM 和 DOTNET 对象将具有其默认属性的值，取得并作为变量值使用。
变量算法函数是 COM 库中与其名称接近的函数的封装。此类函数的更多信息请参考 MSDN 库。PHP 函数命名有少许不同，例如 PHP 中的 variant_add() 对应于 MSDN 文档中的 VarAdd()。

variant_mod

(PHP 5)

variant_mod -- Divides two variants and returns only the remainder

Description

mixed variant_mod ( mixed left, mixed right )

Divides left by right and returns the remainder.

注: 对于所有的变量算法函数，此函数的参数可以要么是 PHP 自身的类型（整型，字符串，浮点型，布尔型或者 NULL），要么是一个 COM，VARIANT 或 DOTNET 类的实例。PHP 自身类型将被转换为变量，使用与 VARIANT 类的构造函数中相同的规则。COM 和 DOTNET 对象将具有其默认属性的值，取得并作为变量值使用。
变量算法函数是 COM 库中与其名称接近的函数的封装。此类函数的更多信息请参考 MSDN 库。PHP 函数命名有少许不同，例如 PHP 中的 variant_add() 对应于 MSDN 文档中的 VarAdd()。

variant_mul

(PHP 5)

variant_mul -- multiplies the values of the two variants and returns the result

Description

mixed variant_mul ( mixed left, mixed right )

Multiplies left by right and returns the result, subject to the following rules:

表格 1. Variant Multiplication Rules

If	Then
Both expressions are of the string, date, character, boolean type	Multiplication
One expression is a string type and the other a character	Multiplication
One expression is numeric and the other is a string	Multiplication
Both expressions are numeric	Multiplication
Either expression is NULL	NULL is returned
Both expressions are empty	Empty string is returned

Boolean values are converted to -1 for FALSE and 0 for TRUE.

注: 对于所有的变量算法函数，此函数的参数可以要么是 PHP 自身的类型（整型，字符串，浮点型，布尔型或者 NULL），要么是一个 COM，VARIANT 或 DOTNET 类的实例。PHP 自身类型将被转换为变量，使用与 VARIANT 类的构造函数中相同的规则。COM 和 DOTNET 对象将具有其默认属性的值，取得并作为变量值使用。
变量算法函数是 COM 库中与其名称接近的函数的封装。此类函数的更多信息请参考 MSDN 库。PHP 函数命名有少许不同，例如 PHP 中的 variant_add() 对应于 MSDN 文档中的 VarAdd()。

variant_neg

(PHP 5)

variant_neg -- Performs logical negation on a variant

Description

mixed variant_neg ( mixed variant )

Performs logical negation of variant and returns the result.

注: 对于所有的变量算法函数，此函数的参数可以要么是 PHP 自身的类型（整型，字符串，浮点型，布尔型或者 NULL），要么是一个 COM，VARIANT 或 DOTNET 类的实例。PHP 自身类型将被转换为变量，使用与 VARIANT 类的构造函数中相同的规则。COM 和 DOTNET 对象将具有其默认属性的值，取得并作为变量值使用。
变量算法函数是 COM 库中与其名称接近的函数的封装。此类函数的更多信息请参考 MSDN 库。PHP 函数命名有少许不同，例如 PHP 中的 variant_add() 对应于 MSDN 文档中的 VarAdd()。

variant_not

(PHP 5)

variant_not -- Performs bitwise not negation on a variant

Description

mixed variant_not ( mixed variant )

Performs bitwise not negation on variant and returns the result. If variant is NULL, the result will also be NULL.

注: 对于所有的变量算法函数，此函数的参数可以要么是 PHP 自身的类型（整型，字符串，浮点型，布尔型或者 NULL），要么是一个 COM，VARIANT 或 DOTNET 类的实例。PHP 自身类型将被转换为变量，使用与 VARIANT 类的构造函数中相同的规则。COM 和 DOTNET 对象将具有其默认属性的值，取得并作为变量值使用。
变量算法函数是 COM 库中与其名称接近的函数的封装。此类函数的更多信息请参考 MSDN 库。PHP 函数命名有少许不同，例如 PHP 中的 variant_add() 对应于 MSDN 文档中的 VarAdd()。

variant_or

(PHP 5)

variant_or -- Performs a logical disjunction on two variants

Description

mixed variant_or ( mixed left, mixed right )

Performs a bitwise OR operation, according to the following truth table; note that this is slightly different from a regular OR operation.

表格 1. Variant OR Rules

If `left` is	If `right` is	then the result is
`TRUE`	`TRUE`	`TRUE`
`TRUE`	`FALSE`	`TRUE`
`TRUE`	`NULL`	`TRUE`
`FALSE`	`TRUE`	`TRUE`
`FALSE`	`FALSE`	`FALSE`
`FALSE`	`NULL`	`NULL`
`NULL`	`TRUE`	`TRUE`
`NULL`	`FALSE`	`NULL`
`NULL`	`NULL`	`NULL`

注: 对于所有的变量算法函数，此函数的参数可以要么是 PHP 自身的类型（整型，字符串，浮点型，布尔型或者 NULL），要么是一个 COM，VARIANT 或 DOTNET 类的实例。PHP 自身类型将被转换为变量，使用与 VARIANT 类的构造函数中相同的规则。COM 和 DOTNET 对象将具有其默认属性的值，取得并作为变量值使用。
变量算法函数是 COM 库中与其名称接近的函数的封装。此类函数的更多信息请参考 MSDN 库。PHP 函数命名有少许不同，例如 PHP 中的 variant_add() 对应于 MSDN 文档中的 VarAdd()。

表格 1. Variant Subtraction Rules

If	Then
Both expressions are of the string type	Subtraction
One expression is a string type and the other a character	Subtraction
One expression is numeric and the other is a string	Subtraction.
Both expressions are numeric	Subtraction
Either expression is NULL	NULL is returned
Both expressions are empty	Empty string is returned

variant_xor

(PHP 5)

variant_xor -- Performs a logical exclusion on two variants

Description

mixed variant_xor ( mixed left, mixed right )

Performs a logical exclusion, according to the following truth table:

表格 1. Variant XOR Rules

If `left` is	If `right` is	then the result is
`TRUE`	`TRUE`	`FALSE`
`TRUE`	`FALSE`	`TRUE`
`FALSE`	`TRUE`	`TRUE`
`FALSE`	`FALSE`	`FALSE`
`NULL`	`NULL`	`NULL`

注: 对于所有的变量算法函数，此函数的参数可以要么是 PHP 自身的类型（整型，字符串，浮点型，布尔型或者 NULL），要么是一个 COM，VARIANT 或 DOTNET 类的实例。PHP 自身类型将被转换为变量，使用与 VARIANT 类的构造函数中相同的规则。COM 和 DOTNET 对象将具有其默认属性的值，取得并作为变量值使用。
变量算法函数是 COM 库中与其名称接近的函数的封装。此类函数的更多信息请参考 MSDN 库。PHP 函数命名有少许不同，例如 PHP 中的 variant_add() 对应于 MSDN 文档中的 VarAdd()。

XVI. Crack Functions

简介

These functions allow you to use the CrackLib library to test the 'strength' of a password. The 'strength' of a password is tested by that checks length, use of upper and lower case and checked against the specified CrackLib dictionary. CrackLib will also give helpful diagnostic messages that will help 'strengthen' the password.

注: 本扩展已被移动到 PECL 库中且自以下版本起不再被绑定到 PHP 中：5.0.0.

需求

More information regarding CrackLib along with the library can be found at http://www.crypticide.com/users/alecm/.

安装

本 PECL 扩展未绑定于 PHP 中。进一步信息例如新版本，下载，源程序，维护者信息以及更新日志可以在此找到： http://pecl.php.net/package/crack.

在 PHP 4 中本 PECL 扩展的源程序位于 PHP 源程序中的 ext/ 目录下或者在上面的 PECL 连接中。 In order to use these functions you must compile PHP with Crack support by using the --with-crack[=DIR] configuration option.

Windows users will enable php_crack.dll inside of php.ini in order to use these functions. 在 PHP 4 中本 DLL 位于 PHP Windows 执行包中的 extensions/ 目录下。可以从 PHP 下载页面或者 http://snaps.php.net/ 下载此 PECL 扩展的 DLL 文件。

运行时配置

这些函数的行为受 php.ini 的影响。

表格 1. Crack configuration options

Name	Default	Changeable	Changelog
crack.default_dictionary	NULL	PHP_INI_SYSTEM	Available since PHP 4.0.5.

有关 PHP_INI_* 常量进一步的细节与定义参见附录 G。

资源类型

本扩展模块未定义任何资源类型。

预定义常量

本扩展模块未定义任何常量。

范例

This example shows how to open a CrackLib dictionary, test a given password, retrieve any diagnostic messages, and close the dictionary.
例子 1. CrackLib example
<?php // Open CrackLib Dictionary $dictionary = crack_opendict('/usr/local/lib/pw_dict') or die('Unable to open CrackLib dictionary'); // Perform password check $check = crack_check($dictionary, 'gx9A2s0x'); // Retrieve messages $diag = crack_getlastmessage(); echo $diag; // 'strong password' // Close dictionary crack_closedict($dictionary); ?>

注: If crack_check() returns TRUE, crack_getlastmessage() will return 'strong password'.

目录
crack_check -- Performs an obscure check with the given password
crack_closedict -- Closes an open CrackLib dictionary
crack_getlastmessage -- Returns the message from the last obscure check
crack_opendict -- Opens a new CrackLib dictionary

crack_check

(PHP 4 >= 4.0.5, PECL)

crack_check -- Performs an obscure check with the given password

说明

bool crack_check ( resource dictionary, string password )

bool crack_check ( string password )

Performs an obscure check with the given password on the specified dictionary.

警告

参数

dictionary: The crack lib dictionary. If not specified, the last opened dictionary is used.
password: The tested password.

返回值

Returns TRUE if password is strong, or FALSE otherwise.

crack_closedict

(PHP 4 >= 4.0.5, PECL)

crack_closedict -- Closes an open CrackLib dictionary

说明

bool crack_closedict ( [resource dictionary] )

crack_closedict() closes the specified dictionary identifier.

警告

参数

dictionary: The dictionary to close. If not specified, the current directory is closed.

返回值

如果成功则返回 TRUE，失败则返回 FALSE。

参见

crack_opendict()

crack_getlastmessage

(PHP 4 >= 4.0.5, PECL)

crack_getlastmessage -- Returns the message from the last obscure check

说明

string crack_getlastmessage ( void )

crack_getlastmessage() returns the message from the last obscure check.

警告

返回值

The message from the last obscure check.

参见

crack_check()

crack_opendict

(PHP 4 >= 4.0.5, PECL)

crack_opendict -- Opens a new CrackLib dictionary

说明

resource crack_opendict ( string dictionary )

crack_opendict() opens the specified CrackLib dictionary for use with crack_check().

警告

注: Only one dictionary may be open at a time.

参数

dictionary: The path to the Cracklib dictionary.

返回值

Returns a dictionary resource identifier on success, or FALSE on failure.

参见

crack_check()

crack_closedict()

XVII. Credit Mutuel CyberMUT functions

简介

This extension allows you to process credit cards transactions using Credit Mutuel CyberMUT system.

CyberMUT is a popular Web Payment Service in France, provided by the Credit Mutuel bank. If you are foreign in France, these functions will not be useful for you.

The use of these functions is almost identical to the original functions, except for the parameters of return for CreerFormulaireCM and CreerReponseCM, which are returned directly by functions PHP, whereas they had passed in reference in the original functions.

注: 本扩展模块在 Windows 平台下不可用。

注: 本扩展已被移动到 PECL 库中且自以下版本起不再被绑定到 PHP 中：4.3.0

需求

You will require the appropriate SDK for your platform, which may be sent to you after your CyberMUT's subscription (contact them via Web, or go to the nearest Credit Mutuel).

注: These functions only provide a link to CyberMUT SDK. Be sure to read the CyberMUT Developers Guide for full details of the required parameters.

目录
cybermut_creerformulairecm -- Generate HTML form of request for payment
cybermut_creerreponsecm -- Generate the delivery's acknowledgement of the payment's confirmation
cybermut_testmac -- Make sure that there was no data diddling contained in the received message of confirmation

cybermut_creerformulairecm

(4.0.5 - 4.2.3 only, PECL)

cybermut_creerformulairecm -- Generate HTML form of request for payment

说明

string cybermut_creerformulairecm ( string url_cm, string version, string tpe, string price, string ref_command, string text_free, string url_return, string url_return_ok, string url_return_err, string language, string code_company, string text_button )

cybermut_creerformulairecm() is used to generate the HTML form of request for payment.

参见

cybermut_testmac()

cybermut_creerreponsecm()

cybermut_creerreponsecm

(4.0.5 - 4.2.3 only, PECL)

cybermut_creerreponsecm -- Generate the delivery's acknowledgement of the payment's confirmation

说明

string cybermut_creerreponsecm ( string sentence )

The parameter is "OK" if the message of confirmation of the payment were correctly authenticated by cybermut_testmac(). Any other chain is regarded as an error message.

返回值

Returns a string containing the message of acknowledgement of delivery.

参见

cybermut_creerformulairecm()

cybermut_testmac()

cybermut_testmac

(4.0.5 - 4.2.3 only, PECL)

cybermut_testmac -- Make sure that there was no data diddling contained in the received message of confirmation

说明

bool cybermut_testmac ( string code_mac, string version, string tpe, string cdate, string price, string ref_command, string text_free, string code_return )

cybermut_testmac() is used to make sure that there was no data diddling contained in the received message of confirmation. Pay attention to parameters code_return and text_free, which cannot be evaluated as is, because of the dash.

参见

cybermut_creerformulairecm()

cybermut_creerreponsecm()

XVIII. CURL, Client URL Library Functions

简介

PHP supports libcurl, a library created by Daniel Stenberg, that allows you to connect and communicate to many different types of servers with many different types of protocols. libcurl currently supports the http, https, ftp, gopher, telnet, dict, file, and ldap protocols. libcurl also supports HTTPS certificates, HTTP POST, HTTP PUT, FTP uploading (this can also be done with PHP's ftp extension), HTTP form based upload, proxies, cookies, and user+password authentication.

These functions have been added in PHP 4.0.2.

需求

In order to use the CURL functions you need to install the CURL package. PHP requires that you use CURL 7.0.2-beta or higher. In PHP 4.2.3, you will need CURL version 7.9.0 or higher. From PHP 4.3.0, you will need a CURL version that's 7.9.8 or higher. PHP 5.0.0 requires a CURL version 7.10.5 or greater.

安装

To use PHP's CURL support you must also compile PHP --with-curl[=DIR] where DIR is the location of the directory containing the lib and include directories. In the "include" directory there should be a folder named "curl" which should contain the easy.h and curl.h files. There should be a file named libcurl.a located in the "lib" directory. Beginning with PHP 4.3.0 you can configure PHP to use CURL for URL streams --with-curlwrappers.

Note to Win32 Users: In order to enable this module on a Windows environment, you must copy libeay32.dll and ssleay32.dll from the DLL folder of the PHP/Win32 binary package to the SYSTEM folder of your Windows machine. (Ex: C:\WINNT\SYSTEM32 or C:\WINDOWS\SYSTEM)

预定义常量

以下常量由本扩展模块定义，因此只有在本扩展模块被编译到 PHP 中，或者在运行时被动态加载后才有效。

CURLOPT_AUTOREFERER (integer): Available since PHP 5.1.0
CURLOPT_COOKIESESSION (integer): Available since PHP 5.1.0
CURLOPT_DNS_USE_GLOBAL_CACHE (integer)

CURLOPT_DNS_CACHE_TIMEOUT (integer)

CURLOPT_FTPSSLAUTH (integer): Available since PHP 5.1.0

CURLOPT_PORT (integer)

CURLOPT_FILE (integer)

CURLOPT_INFILE (integer)

CURLOPT_INFILESIZE (integer)

CURLOPT_URL (integer)

CURLOPT_PROXY (integer)

CURLOPT_VERBOSE (integer)

CURLOPT_HEADER (integer)

CURLOPT_HTTPHEADER (integer)

CURLOPT_NOPROGRESS (integer)

CURLOPT_NOBODY (integer)

CURLOPT_FAILONERROR (integer)

CURLOPT_UPLOAD (integer)

CURLOPT_POST (integer)

CURLOPT_FTPLISTONLY (integer)

CURLOPT_FTPAPPEND (integer)

CURLOPT_NETRC (integer)

CURLOPT_FOLLOWLOCATION (integer)

CURLOPT_FTPASCII (integer)

CURLOPT_PUT (integer)

CURLOPT_MUTE (integer)

CURLOPT_USERPWD (integer)

CURLOPT_PROXYUSERPWD (integer)

CURLOPT_RANGE (integer)

CURLOPT_TIMEOUT (integer)

CURLOPT_POSTFIELDS (integer)

CURLOPT_REFERER (integer)

CURLOPT_USERAGENT (integer)

CURLOPT_FTPPORT (integer)

CURLOPT_FTP_USE_EPSV (integer)

CURLOPT_LOW_SPEED_LIMIT (integer)

CURLOPT_LOW_SPEED_TIME (integer)

CURLOPT_RESUME_FROM (integer)

CURLOPT_COOKIE (integer)

CURLOPT_SSLCERT (integer)

CURLOPT_SSLCERTPASSWD (integer)

CURLOPT_WRITEHEADER (integer)

CURLOPT_SSL_VERIFYHOST (integer)

CURLOPT_COOKIEFILE (integer)

CURLOPT_SSLVERSION (integer)

CURLOPT_TIMECONDITION (integer)

CURLOPT_TIMEVALUE (integer)

CURLOPT_CUSTOMREQUEST (integer)

CURLOPT_STDERR (integer)

CURLOPT_TRANSFERTEXT (integer)

CURLOPT_RETURNTRANSFER (integer)

CURLOPT_QUOTE (integer)

CURLOPT_POSTQUOTE (integer)

CURLOPT_INTERFACE (integer)

CURLOPT_KRB4LEVEL (integer)

CURLOPT_HTTPPROXYTUNNEL (integer)

CURLOPT_FILETIME (integer)

CURLOPT_WRITEFUNCTION (integer)

CURLOPT_READFUNCTION (integer)

CURLOPT_PASSWDFUNCTION (integer)

CURLOPT_HEADERFUNCTION (integer)

CURLOPT_MAXREDIRS (integer)

CURLOPT_MAXCONNECTS (integer)

CURLOPT_CLOSEPOLICY (integer)

CURLOPT_FRESH_CONNECT (integer)

CURLOPT_FORBID_REUSE (integer)

CURLOPT_RANDOM_FILE (integer)

CURLOPT_EGDSOCKET (integer)

CURLOPT_CONNECTTIMEOUT (integer)

CURLOPT_SSL_VERIFYPEER (integer)

CURLOPT_CAINFO (integer)

CURLOPT_CAPATH (integer)

CURLOPT_COOKIEJAR (integer)

CURLOPT_SSL_CIPHER_LIST (integer)

CURLOPT_BINARYTRANSFER (integer)

CURLOPT_NOSIGNAL (integer)

CURLOPT_PROXYTYPE (integer)

CURLOPT_BUFFERSIZE (integer)

CURLOPT_HTTPGET (integer)

CURLOPT_HTTP_VERSION (integer)

CURLOPT_SSLKEY (integer)

CURLOPT_SSLKEYTYPE (integer)

CURLOPT_SSLKEYPASSWD (integer)

CURLOPT_SSLENGINE (integer)

CURLOPT_SSLENGINE_DEFAULT (integer)

CURLOPT_SSLCERTTYPE (integer)

CURLOPT_CRLF (integer)

CURLOPT_ENCODING (integer)

CURLOPT_PROXYPORT (integer)

CURLOPT_UNRESTRICTED_AUTH (integer)

CURLOPT_FTP_USE_EPRT (integer)

CURLOPT_HTTP200ALIASES (integer)

CURLOPT_HTTPAUTH (integer)

CURLAUTH_BASIC (integer)

CURLAUTH_DIGEST (integer)

CURLAUTH_GSSNEGOTIATE (integer)

CURLAUTH_NTLM (integer)

CURLAUTH_ANY (integer)

CURLAUTH_ANYSAFE (integer)

CURLOPT_PROXYAUTH (integer)

CURLCLOSEPOLICY_LEAST_RECENTLY_USED (integer)

CURLCLOSEPOLICY_LEAST_TRAFFIC (integer)

CURLCLOSEPOLICY_SLOWEST (integer)

CURLCLOSEPOLICY_CALLBACK (integer)

CURLCLOSEPOLICY_OLDEST (integer)

CURLINFO_EFFECTIVE_URL (integer)

CURLINFO_HTTP_CODE (integer)

CURLINFO_HEADER_SIZE (integer)

CURLINFO_REQUEST_SIZE (integer)

CURLINFO_TOTAL_TIME (integer)

CURLINFO_NAMELOOKUP_TIME (integer)

CURLINFO_CONNECT_TIME (integer)

CURLINFO_PRETRANSFER_TIME (integer)

CURLINFO_SIZE_UPLOAD (integer)

CURLINFO_SIZE_DOWNLOAD (integer)

CURLINFO_SPEED_DOWNLOAD (integer)

CURLINFO_SPEED_UPLOAD (integer)

CURLINFO_FILETIME (integer)

CURLINFO_SSL_VERIFYRESULT (integer)

CURLINFO_CONTENT_LENGTH_DOWNLOAD (integer)

CURLINFO_CONTENT_LENGTH_UPLOAD (integer)

CURLINFO_STARTTRANSFER_TIME (integer)

CURLINFO_CONTENT_TYPE (integer)

CURLINFO_REDIRECT_TIME (integer)

CURLINFO_REDIRECT_COUNT (integer)

CURL_VERSION_IPV6 (integer)

CURL_VERSION_KERBEROS4 (integer)

CURL_VERSION_SSL (integer)

CURL_VERSION_LIBZ (integer)

CURLVERSION_NOW (integer)

CURLE_OK (integer)

CURLE_UNSUPPORTED_PROTOCOL (integer)

CURLE_FAILED_INIT (integer)

CURLE_URL_MALFORMAT (integer)

CURLE_URL_MALFORMAT_USER (integer)

CURLE_COULDNT_RESOLVE_PROXY (integer)

CURLE_COULDNT_RESOLVE_HOST (integer)

CURLE_COULDNT_CONNECT (integer)

CURLE_FTP_WEIRD_SERVER_REPLY (integer)

CURLE_FTP_ACCESS_DENIED (integer)

CURLE_FTP_USER_PASSWORD_INCORRECT (integer)

CURLE_FTP_WEIRD_PASS_REPLY (integer)

CURLE_FTP_WEIRD_USER_REPLY (integer)

CURLE_FTP_WEIRD_PASV_REPLY (integer)

CURLE_FTP_WEIRD_227_FORMAT (integer)

CURLE_FTP_CANT_GET_HOST (integer)

CURLE_FTP_CANT_RECONNECT (integer)

CURLE_FTP_COULDNT_SET_BINARY (integer)

CURLE_PARTIAL_FILE (integer)

CURLE_FTP_COULDNT_RETR_FILE (integer)

CURLE_FTP_WRITE_ERROR (integer)

CURLE_FTP_QUOTE_ERROR (integer)

CURLE_HTTP_NOT_FOUND (integer)

CURLE_WRITE_ERROR (integer)

CURLE_MALFORMAT_USER (integer)

CURLE_FTP_COULDNT_STOR_FILE (integer)

CURLE_READ_ERROR (integer)

CURLE_OUT_OF_MEMORY (integer)

CURLE_OPERATION_TIMEOUTED (integer)

CURLE_FTP_COULDNT_SET_ASCII (integer)

CURLE_FTP_PORT_FAILED (integer)

CURLE_FTP_COULDNT_USE_REST (integer)

CURLE_FTP_COULDNT_GET_SIZE (integer)

CURLE_HTTP_RANGE_ERROR (integer)

CURLE_HTTP_POST_ERROR (integer)

CURLE_SSL_CONNECT_ERROR (integer)

CURLE_FTP_BAD_DOWNLOAD_RESUME (integer)

CURLE_FILE_COULDNT_READ_FILE (integer)

CURLE_LDAP_CANNOT_BIND (integer)

CURLE_LDAP_SEARCH_FAILED (integer)

CURLE_LIBRARY_NOT_FOUND (integer)

CURLE_FUNCTION_NOT_FOUND (integer)

CURLE_ABORTED_BY_CALLBACK (integer)

CURLE_BAD_FUNCTION_ARGUMENT (integer)

CURLE_BAD_CALLING_ORDER (integer)

CURLE_HTTP_PORT_FAILED (integer)

CURLE_BAD_PASSWORD_ENTERED (integer)

CURLE_TOO_MANY_REDIRECTS (integer)

CURLE_UNKNOWN_TELNET_OPTION (integer)

CURLE_TELNET_OPTION_SYNTAX (integer)

CURLE_OBSOLETE (integer)

CURLE_SSL_PEER_CERTIFICATE (integer)

CURLE_GOT_NOTHING (integer)

CURLE_SSL_ENGINE_NOTFOUND (integer)

CURLE_SSL_ENGINE_SETFAILED (integer)

CURLE_SEND_ERROR (integer)

CURLE_RECV_ERROR (integer)

CURLE_SHARE_IN_USE (integer)

CURLE_SSL_CERTPROBLEM (integer)

CURLE_SSL_CIPHER (integer)

CURLE_SSL_CACERT (integer)

CURLE_BAD_CONTENT_ENCODING (integer)

CURLE_LDAP_INVALID_URL (integer)

CURLE_FILESIZE_EXCEEDED (integer)

CURLE_FTP_SSL_FAILED (integer)

CURLFTPAUTH_DEFAULT (integer): Available since PHP 5.1.0

CURLFTPAUTH_SSL (integer): Available since PHP 5.1.0

CURLFTPAUTH_TLS (integer): Available since PHP 5.1.0

CURLPROXY_HTTP (integer)

CURLPROXY_SOCKS5 (integer)

CURL_NETRC_OPTIONAL (integer)

CURL_NETRC_IGNORED (integer)

CURL_NETRC_REQUIRED (integer)

CURL_HTTP_VERSION_NONE (integer)

CURL_HTTP_VERSION_1_0 (integer)

CURL_HTTP_VERSION_1_1 (integer)

CURLM_CALL_MULTI_PERFORM (integer)

CURLM_OK (integer)

CURLM_BAD_HANDLE (integer)

CURLM_BAD_EASY_HANDLE (integer)

CURLM_OUT_OF_MEMORY (integer)

CURLM_INTERNAL_ERROR (integer)

CURLMSG_DONE (integer)

范例

Once you've compiled PHP with CURL support, you can begin using the CURL functions. The basic idea behind the CURL functions is that you initialize a CURL session using the curl_init(), then you can set all your options for the transfer via the curl_setopt(), then you can execute the session with the curl_exec() and then you finish off your session using the curl_close(). Here is an example that uses the CURL functions to fetch the example.com homepage into a file:
例子 1. Using PHP's CURL module to fetch the example.com homepage
<?php $ch = curl_init("http://www.example.com/"); $fp = fopen("example_homepage.txt", "w"); curl_setopt($ch, CURLOPT_FILE, $fp); curl_setopt($ch, CURLOPT_HEADER, 0); curl_exec($ch); curl_close($ch); fclose($fp); ?>

目录
curl_close -- Close a CURL session
curl_copy_handle -- Copy a cURL handle along with all of its preferences
curl_errno -- Return the last error number
curl_error -- Return a string containing the last error for the current session
curl_exec -- Perform a CURL session
curl_getinfo -- Get information regarding a specific transfer
curl_init -- Initialize a CURL session
curl_multi_add_handle -- Add a normal cURL handle to a cURL multi handle
curl_multi_close -- Close a set of cURL handles
curl_multi_exec -- Run the sub-connections of the current cURL handle
curl_multi_getcontent -- Return the content of a cURL handle if CURLOPT_RETURNTRANSFER is set
curl_multi_info_read -- Get information about the current transfers
curl_multi_init -- Returns a new cURL multi handle
curl_multi_remove_handle -- Remove a multi handle from a set of cURL handles
curl_multi_select -- Get all the sockets associated with the cURL extension, which can then be "selected"
curl_setopt -- Set an option for a CURL transfer
curl_version -- Return the current CURL version

If called without the optional parameter opt an associative array is returned with the following array elements which correspond to opt options:

"url"
"content_type"
"http_code"
"header_size"
"request_size"
"filetime"
"ssl_verify_result"
"redirect_count"
"total_time"
"namelookup_time"
"connect_time"
"pretransfer_time"
"size_upload"
"size_download"
"speed_download"
"speed_upload"
"download_content_length"
"upload_content_length"
"starttransfer_time"
"redirect_time"

curl_init

(PHP 4 >= 4.0.2, PHP 5)

curl_init -- Initialize a CURL session

bool curl_setopt ( resource ch, int option, mixed value )

Set an option for a CURL session identified by the ch parameter. option specifies which option to set, and value specifies the value for the option given.

value should be a bool for the following values of the option parameter:

Option	Set `value` to	Notes
`CURLOPT_AUTOREFERER`	`TRUE` to automatically set the `Referer:` field in requests where it follows a `Location:` redirect.	Available since PHP 5.1.0.
`CURLOPT_BINARYTRANSFER`	`TRUE` to return the raw output when `CURLOPT_RETURNTRANSFER` is used.
`CURLOPT_COOKIESESSION`	`TRUE` to mark this as a new cookie "session". It will force libcurl to ignore all cookies it is about to load that are "session cookies" from the previous session. By default, libcurl always stores and loads all cookies, independent if they are session cookies are not. Session cookies are cookies without expiry date and they are meant to be alive and existing for this "session" only.	Available since PHP 5.1.0.
`CURLOPT_CRLF`	`TRUE` to convert Unix newlines to CRLF newlines on transfers.
`CURLOPT_DNS_USE_GLOBAL_CACHE`	`TRUE` to use a global DNS cache. This option is not thread-safe and is enabled by default.
`CURLOPT_FAILONERROR`	`TRUE` to fail silently if the HTTP code returned is greater than 300. The default behavior is to return the page normally, ignoring the code.
`CURLOPT_FILETIME`	`TRUE` to attempt to retrieve the modification date of the remote document. You can then retrieve this value using the `CURLINFO_FILETIME` option with curl_getinfo().
`CURLOPT_FOLLOWLOCATION`	`TRUE` to follow any `"Location: "` header that the server sends as part of the HTTP header (note this is recursive, PHP will follow as many `"Location: "` headers that it is sent, unless `CURLOPT_MAXREDIRS` is set).
`CURLOPT_FORBID_REUSE`	`TRUE` to force the connection to explicitly close when it has finished processing, and not be pooled for reuse.
`CURLOPT_FRESH_CONNECT`	`TRUE` to force the use of a new connection instead of a cached one.
`CURLOPT_FTP_USE_EPRT`	`TRUE` to use EPRT (and LPRT) when doing active FTP downloads. Use `FALSE` to disable EPRT and LPRT and use PORT only.	Added in PHP 5.0.0.
`CURLOPT_FTP_USE_EPSV`	`TRUE` to first try an EPSV command for FTP transfers before reverting back to PASV. Set to `FALSE` to disable EPSV.
`CURLOPT_FTPAPPEND`	`TRUE` to append to the remote file instead of overwriting it.
`CURLOPT_FTPASCII`	An alias of `CURLOPT_TRANSFERTEXT`. Use that instead.
`CURLOPT_FTPLISTONLY`	`TRUE` to only list the names of an FTP directory.
`CURLOPT_HEADER`	`TRUE` to include the header in the output.
`CURLOPT_HTTPGET`	`TRUE` to reset the HTTP request method to GET. Since GET is the default, this is only necessary if the request method has been changed.
`CURLOPT_HTTPPROXYTUNNEL`	`TRUE` to tunnel through a given HTTP proxy.
`CURLOPT_MUTE`	`TRUE` to be completely silent with regards to the CURL functions.
`CURLOPT_NETRC`	`TRUE` to scan your `~/.netrc` file to find your username and password for the remote site that you're establishing a connection with.
`CURLOPT_NOBODY`	`TRUE` to exclude the body from the output.
`CURLOPT_NOPROGRESS`	`TRUE` to disable the progress meter for CURL transfers. 注: PHP automatically sets this option to `TRUE`, this should only be changed for debugging purposes.
`CURLOPT_NOSIGNAL`	`TRUE` to ignore any CURL function that causes a signal to be sent to the PHP process. This is turned on by default in multi-threaded SAPIs so timeout options can still be used.	Added in CURL 7.10 and PHP 5.0.0.
`CURLOPT_POST`	`TRUE` to do a regular HTTP POST. This POST is the normal `application/x-www-form-urlencoded` kind, most commonly used by HTML forms.
`CURLOPT_PUT`	`TRUE` to HTTP PUT a file. The file to PUT must be set with `CURLOPT_INFILE` and `CURLOPT_INFILESIZE`.
`CURLOPT_RETURNTRANSFER`	`TRUE` to return the transfer as a string of the return value of curl_exec() instead of outputting it out directly.
`CURLOPT_SSL_VERIFYPEER`	`FALSE` to stop CURL from verifying the peer's certificate. Alternate certificates to verify against can be specified with the `CURLOPT_CAINFO` option or a certificate directory can be specified with the `CURLOPT_CAPATH` option. `CURLOPT_SSL_VERIFYHOST` may also need to be `TRUE` or `FALSE` if `CURLOPT_SSL_VERIFYPEER` is disabled (it defaults to 2).	`TRUE` by default as of CURL 7.10. Default bundle installed as of CURL 7.10.
`CURLOPT_TRANSFERTEXT`	`TRUE` to use ASCII mode for FTP transfers. For LDAP, it retrieves data in plain text instead of HTML. On Windows systems, it will not set `STDOUT` to binary mode.
`CURLOPT_UNRESTRICTED_AUTH`	`TRUE` to keep sending the username and password when following locations (using `CURLOPT_FOLLOWLOCATION`), even when the hostname has changed.	Added in PHP 5.0.0.
`CURLOPT_UPLOAD`	`TRUE` to prepare for an upload.
`CURLOPT_VERBOSE`	`TRUE` to output verbose information. Writes output to `STDERR`, or the file specified using `CURLOPT_STDERR`.

value should be an integer for the following values of the option parameter:

Option	Set `value` to	Notes
`CURLOPT_BUFFERSIZE`	The size of the buffer to use for each read. There is no guarantee this request will be fulfilled, however.	Added in CURL 7.10 and PHP 5.0.0.
`CURLOPT_CLOSEPOLICY`	Either `CURLCLOSEPOLICY_LEAST_RECENTLY_USED` or `CURLCLOSEPOLICY_OLDEST`. There are three other `CURLCLOSEPOLICY_` constants, but CURL does not support them yet.
`CURLOPT_CONNECTTIMEOUT`	The number of seconds to wait whilst trying to connect. Use 0 to wait indefinitely.
`CURLOPT_DNS_CACHE_TIMEOUT`	The number of seconds to keep DNS entries in memory. This option is set to 120 (2 minutes) by default.
`CURLOPT_FTPSSLAUTH`	The FTP authentication method (when is activated): `CURLFTPAUTH_SSL` (try SSL first), `CURLFTPAUTH_TLS` (try TLS first), or `CURLFTPAUTH_DEFAULT` (let CURL decide).	Added in CURL 7.12.2 and PHP 5.1.0.
`CURLOPT_HTTP_VERSION`	`CURL_HTTP_VERSION_NONE` (default, lets CURL decide which version to use), `CURL_HTTP_VERSION_1_0` (forces HTTP/1.0), or `CURL_HTTP_VERSION_1_1` (forces HTTP/1.1).
`CURLOPT_HTTPAUTH`	The HTTP authentication method(s) to use. The options are: `CURLAUTH_BASIC`, `CURLAUTH_DIGEST`, `CURLAUTH_GSSNEGOTIATE`, `CURLAUTH_NTLM`, `CURLAUTH_ANY`, and `CURLAUTH_ANYSAFE`. You can use the bitwise `\|` (or) operator to combine more than one method. If you do this, CURL will poll the server to see what methods it supports and pick the best one. `CURLAUTH_ANY` is an alias for `CURLAUTH_BASIC \| CURLAUTH_DIGEST \| CURLAUTH_GSSNEGOTIATE \| CURLAUTH_NTLM`. `CURLAUTH_ANYSAFE` is an alias for `CURLAUTH_DIGEST \| CURLAUTH_GSSNEGOTIATE \| CURLAUTH_NTLM`.	Added in PHP 5.0.0.
`CURLOPT_INFILESIZE`	The expected size, in bytes, of the file when uploading a file to a remote site.
`CURLOPT_LOW_SPEED_LIMIT`	The transfer speed, in bytes per second, that the transfer should be below during `CURLOPT_LOW_SPEED_TIME` seconds for PHP to consider the transfer too slow and abort.
`CURLOPT_LOW_SPEED_TIME`	The number of seconds the transfer should be below `CURLOPT_LOW_SPEED_LIMIT` for PHP to consider the transfer too slow and abort.
`CURLOPT_MAXCONNECTS`	The maximum amount of persistent connections that are allowed. When the limit is reached, `CURLOPT_CLOSEPOLICY` is used to determine which connection to close.
`CURLOPT_MAXREDIRS`	The maximum amount of HTTP redirections to follow. Use this option alongside `CURLOPT_FOLLOWLOCATION`.
`CURLOPT_PORT`	An alternative port number to connect to.
`CURLOPT_PROXYAUTH`	The HTTP authentication method(s) to use for the proxy connection. Use the same bitmasks as described in `CURLOPT_HTTPAUTH`. For proxy authentication, only `CURLAUTH_BASIC` and `CURLAUTH_NTLM` are currently supported.	Added in CURL 7.10.7 and PHP 5.1.0.
`CURLOPT_PROXYPORT`	The port number of the proxy to connect to. This port number can also be set in `CURLOPT_PROXY`.	Added in PHP 5.0.0.
`CURLOPT_PROXYTYPE`	Either `CURLPROXY_HTTP` (default) or `CURLPROXY_SOCKS5`.	Added in CURL 7.10 and PHP 5.0.0.
`CURLOPT_RESUME_FROM`	The offset, in bytes, to resume a transfer from.
`CURLOPT_SSL_VERIFYHOST`	1 to check the existence of a common name in the SSL peer certificate. 2 to check the existence of a common name and also verify that it matches the hostname provided.
`CURLOPT_SSLVERSION`	The SSL version (2 or 3) to use. By default PHP will try to determine this itself, although in some cases you must set this manually.
`CURLOPT_TIMECONDITION`	How `CURLOPT_TIMEVALUE` is treated. Use `CURL_TIMECOND_IFMODSINCE` to return the page only if it has been modified since the time specified in `CURLOPT_TIMEVALUE`. If it hasn't been modified, a `"304 Not Modified"` header will be returned assuming `CURLOPT_HEADER` is `TRUE`. Use `CURL_TIMECOND_ISUNMODSINCE` for the reverse effect. `CURL_TIMECOND_IFMODSINCE` is the default.	Added in PHP 5.1.0.
`CURLOPT_TIMEOUT`	The maximum number of seconds to allow CURL functions to execute.
`CURLOPT_TIMEVALUE`	The time in seconds since January 1st, 1970. The time will be used by `CURLOPT_TIMECONDITION`. By default, `CURL_TIMECOND_IFMODSINCE` is used.

value should be a string for the following values of the option parameter:

Option	Set `value` to	Notes
`CURLOPT_CAINFO`	The name of a file holding one or more certificates to verify the peer with. This only makes sense when used in combination with `CURLOPT_SSL_VERIFYPEER`.
`CURLOPT_CAPATH`	A directory that holds multiple CA certificates. Use this option alongside `CURLOPT_SSL_VERIFYPEER`.
`CURLOPT_COOKIE`	The contents of the `"Set-Cookie: "` header to be used in the HTTP request.
`CURLOPT_COOKIEFILE`	The name of the file containing the cookie data. The cookie file can be in Netscape format, or just plain HTTP-style headers dumped into a file.
`CURLOPT_COOKIEJAR`	The name of a file to save all internal cookies to when the connection closes.
`CURLOPT_CUSTOMREQUEST`	A custom request method to use instead of `"GET"` or `"HEAD"` when doing a HTTP request. This is useful for doing `"DELETE"` or other, more obscure HTTP requests. Valid values are things like `"GET"`, `"POST"`, `"CONNECT"` and so on; i.e. Do not enter a whole HTTP request line here. For instance, entering `"GET /index.html HTTP/1.0\r\n\r\n"` would be incorrect. 注: Don't do this without making sure your server supports the custom request method first.
`CURLOPT_EGBSOCKET`	Like `CURLOPT_RANDOM_FILE`, except a filename to an Entropy Gathering Daemon socket.
`CURLOPT_ENCODING`	The contents of the `"Accept-Encoding: "` header. This enables decoding of the response. Supported encodings are `"identity"`, `"deflate"`, and `"gzip"`. If an empty string, `""`, is set, a header containing all supported encoding types is sent.	Added in CURL 7.10.
`CURLOPT_FTPPORT`	The value which will be used to get the IP address to use for the FTP "POST" instruction. The "POST" instruction tells the remote server to connect to our specified IP address. The string may be a plain IP address, a hostname, a network interface name (under Unix), or just a plain '-' to use the systems default IP address.
`CURLOPT_INTERFACE`	The name of the outgoing network interface to use. This can be an interface name, an IP address or a host name.
`CURLOPT_KRB4LEVEL`	The KRB4 (Kerberos 4) security level. Any of the following values (in order from least to most powerful) are valid: `"clear"`, `"safe"`, `"confidential"`, `"private".`. If the string does not match one of these, `"private"` is used. Setting this option to `NULL` will disable KRB4 security. Currently KRB4 security only works with FTP transactions.
`CURLOPT_POSTFIELDS`	The full data to post in a HTTP "POST" operation.
`CURLOPT_PROXY`	The HTTP proxy to tunnel requests through.
`CURLOPT_PROXYUSERPWD`	A username and password formatted as `"[username]:[password]"` to use for the connection to the proxy.
`CURLOPT_RANDOM_FILE`	A filename to be used to seed the random number generator for SSL.
`CURLOPT_RANGE`	Range(s) of data to retrieve in the format `"X-Y"` where X or Y are optional. HTTP transfers also support several intervals, separated with commas in the format `"X-Y,N-M"`.
`CURLOPT_REFERER`	The contents of the `"Referer: "` header to be used in a HTTP request.
`CURLOPT_SSL_CIPHER_LIST`	A list of ciphers to use for SSL. For example, `RC4-SHA` and `TLSv1` are valid cipher lists.
`CURLOPT_SSLCERT`	The name of a file containing a PEM formatted certificate.
`CURLOPT_SSLCERTPASSWD`	The password required to use the `CURLOPT_SSLCERT` certificate.
`CURLOPT_SSLCERTTYPE`	The format of the certificate. Supported formats are `"PEM"` (default), `"DER"`, and `"ENG"`.	Added in CURL 7.9.3 and PHP 5.0.0.
`CURLOPT_SSLENGINE`	The identifier for the crypto engine of the private SSL key specified in `CURLOPT_SSLKEY`.
`CURLOPT_SSLENGINE_DEFAULT`	The identifier for the crypto engine used for asymmetric crypto operations.
`CURLOPT_SSLKEY`	The name of a file containing a private SSL key.
`CURLOPT_SSLKEYPASSWD`	The secret password needed to use the private SSL key specified in `CURLOPT_SSLKEY`. 注: Since this option contains a sensitive password, remember to keep the PHP script it is contained within safe.
`CURLOPT_SSLKEYTYPE`	The key type of the private SSL key specified in `CURLOPT_SSLKEY`. Supported key types are `"PEM"` (default), `"DER"`, and `"ENG"`.
`CURLOPT_URL`	The URL to fetch. You can also set this when initializing a session with curl_init().
`CURLOPT_USERAGENT`	The contents of the `"User-Agent: "` header to be used in a HTTP request.
`CURLOPT_USERPWD`	A username and password formatted as `"[username]:[password]"` to use for the connection.

value should be an array for the following values of the option parameter:

Option	Set `value` to	Notes
`CURLOPT_HTTP200ALIASES`	An array of HTTP 200 responses that will be treated as valid responses and not as errors.	Added in CURL 7.10.3 and PHP 5.0.0.
`CURLOPT_HTTPHEADER`	An array of HTTP header fields to set.
`CURLOPT_POSTQUOTE`	An array of FTP commands to execute on the server after the FTP request has been performed.
`CURLOPT_QUOTE`	An array of FTP commands to execute on the server prior to the FTP request.

value should be a stream resource (using fopen(), for example) for the following values of the option parameter:

Option	Set `value` to	Notes
`CURLOPT_FILE`	The file that the transfer should be written to. The default is `STDOUT` (the browser window).
`CURLOPT_INFILE`	The file that the transfer should be read from when uploading.
`CURLOPT_STDERR`	An alternative location to output errors to instead of `STDERR`.
`CURLOPT_WRITEHEADER`	The file that the header part of the transfer is written to.

value should be a string that is the name of a valid callback function for the following values of the option parameter:

Option	Set `value` to	Notes
`CURLOPT_HEADERFUNCTION`	The name of a callback function where the callback function takes two parameters. The first is the CURL resource, the second is a string with the header data to be written. Using this callback function, it becomes your responsibility to write the header data. Return the number of bytes written.
`CURLOPT_PASSWDFUNCTION`	The name of a callback function where the callback function takes three parameters. The first is the CURL resource, the second is a string containing a password prompt, and the third is the maximum password length. Return the string containing the password.
`CURLOPT_READFUNCTION`	The name of a callback function where the callback function takes two parameters. The first is the CURL resource, and the second is a string with the data to be read. Using this callback function, it becomes your responsibility to read the data. Return the number of bytes read. Return 0 to signal `EOF`.
`CURLOPT_WRITEFUNCTION`	The name of a callback function where the callback function takes two parameters. The first is the CURL resource, and the second is a string with the data to be written. Using this callback function, it becomes your responsibility to write the data. Must return the exact number of bytes written or this will fail.

例子 1. Initializing a new CURL session and fetching a webpage
<?php // create a new CURL resource $ch = curl_init(); // set URL and other appropriate options curl_setopt($ch, CURLOPT_URL, "http://www.example.com/"); curl_setopt($ch, CURLOPT_HEADER, false); // grab URL and pass it to the browser curl_exec($ch); // close CURL resource, and free up system resources curl_close($ch); ?>

curl_version

(PHP 4 >= 4.0.2, PHP 5)

curl_version -- Return the current CURL version

Description

array curl_version ( [int version] )

The curl_version() function returns a string containing the current CURL version.

XIX. Cybercash Payment Functions

安装

These functions are only available if the interpreter has been compiled with the --with-cybercash=[DIR].

This extension has been moved from PHP as of PHP 4.3.0 and now CyberCash lives in PECL.

If you have questions as to the latest status of CyberCash then the following CyberCash Faq will be helpful. In short, CyberCash was bought out by VeriSign and although the CyberCash service continues to exist, VeriSign encourages users to switch. See the above faq and PECL link for details.

目录
cybercash_base64_decode -- base64 decode data for Cybercash
cybercash_base64_encode -- base64 encode data for Cybercash
cybercash_decr -- Cybercash decrypt
cybercash_encr -- Cybercash encrypt

The function returns an associative array with the elements "errcode" and, if "errcode" is FALSE, "outbuff" (string), "outLth" (long) and "macbuff" (string).

cybercash_encr

(PHP 4 <= 4.2.3, PECL)

cybercash_encr -- Cybercash encrypt

Description

array cybercash_encr ( string wmk, string sk, string inbuff )

The function returns an associative array with the elements "errcode" and, if "errcode" is FALSE, "outbuff" (string), "outLth" (long) and "macbuff" (string).

XX. Cyrus IMAP administration Functions

简介

警告

本函数暂无文档，仅有参数列表。

注: 本扩展模块在 Windows 平台下不可用。

安装

To enable Cyrus IMAP support and to use these functions you have to compile PHP with the --with-cyrus option.

警告

IMAP 扩展模块不能和 recode 扩展模块，YAZ 扩展模块以及 Cyrus 扩展模块同时使用。因为它们使用了相同的内部符号。

预定义常量

以下常量由本扩展模块定义，因此只有在本扩展模块被编译到 PHP 中，或者在运行时被动态加载后才有效。

CYRUS_CONN_NONSYNCLITERAL (integer)
CYRUS_CONN_INITIALRESPONSE (integer)
CYRUS_CALLBACK_NUMBERED (integer)
CYRUS_CALLBACK_NOLITERAL (integer)

目录
cyrus_authenticate -- Authenticate against a Cyrus IMAP server
cyrus_bind -- Bind callbacks to a Cyrus IMAP connection
cyrus_close -- Close connection to a Cyrus IMAP server
cyrus_connect -- Connect to a Cyrus IMAP server
cyrus_query -- Send a query to a Cyrus IMAP server
cyrus_unbind -- Unbind ...

XXI. Database (dbm-style) Abstraction Layer Functions

简介

These functions build the foundation for accessing Berkeley DB style databases.

This is a general abstraction layer for several file-based databases. As such, functionality is limited to a common subset of features supported by modern databases such as Sleepycat Software's DB2. (This is not to be confused with IBM's DB2 software, which is supported through the ODBC functions.)

需求

The behaviour of various aspects depends on the implementation of the underlying database. Functions such as dba_optimize() and dba_sync() will do what they promise for one database and will do nothing for others. You have to download and install supported dba-Handlers.

表格 1. List of DBA handlers

Handler	Notes
`dbm`	Dbm is the oldest (original) type of Berkeley DB style databases. You should avoid it, if possible. We do not support the compatibility functions built into DB2 and gdbm, because they are only compatible on the source code level, but cannot handle the original dbm format.
`ndbm`	Ndbm is a newer type and more flexible than dbm. It still has most of the arbitrary limits of dbm (therefore it is deprecated).
`gdbm`	Gdbm is the GNU database manager.
`db2`	DB2 is Sleepycat Software's DB2. It is described as "a programmatic toolkit that provides high-performance built-in database support for both standalone and client/server applications.
`db3`	DB3 is Sleepycat Software's DB3.
`db4`	DB4 is Sleepycat Software's DB4. This is available since PHP 4.3.2.
`cdb`	Cdb is "a fast, reliable, lightweight package for creating and reading constant databases." It is from the author of qmail and can be found at http://cr.yp.to/cdb.html. Since it is constant, we support only reading operations. And since PHP 4.3.0 we support writing (not updating) through the internal cdb library.
`cdb_make`	Since PHP 4.3.0 we support creation (not updating) of cdb files when the bundled cdb library is used.
`flatfile`	This is available since PHP 4.3.0 for compatibility with the deprecated dbm extension only and should be avoided. However you may use this where files were created in this format. That happens when configure could not find any external library.
`inifile`	This is available since PHP 4.3.3 to be able to modify php.ini files from within PHP scripts. When working with ini files you can pass arrays of the form array(0=>group,1=>value_name) or strings of the form "[group]value_name" where group is optional. As the functions dba_firstkey() and dba_nextkey() return string representations of the key there is a new function dba_key_split() available since PHP 5 which allows to convert the string keys into array keys without loosing `FALSE`.
`qdbm`	This is available since PHP 5.0.0. The qdbm library can be loaded from http://qdbm.sourceforge.net.

When invoking the dba_open() or dba_popen() functions, one of the handler names must be supplied as an argument. The actually available list of handlers is displayed by invoking phpinfo() or dba_handlers().

安装

By using the --enable-dba=shared configuration option you can build a dynamic loadable module to enable PHP for basic support of dbm-style databases. You also have to add support for at least one of the following handlers by specifying the --with-XXXX configure switch to your PHP configure line.

警告

After configuring and compiling PHP you must execute the following test from commandline: php run-tests.php ext/dba. This shows whether your combination of handlers works. Most problematic are dbm and ndbm which conflict with many installations. The reason for this is that on several systems these libraries are part of more than one other library. The configuration test only prevents you from configuring malfaunctioning single handlers but not combinations.

表格 2. Supported DBA handlers

Handler	Configure Switch
`dbm`	To enable support for dbm add `--with-dbm[=DIR]`. 注: dbm normally is a wrapper which often results in failures. This means you should only use dbm if you are sure it works and if you really need this format.
`ndbm`	To enable support for ndbm add `--with-ndbm[=DIR]`. 注: ndbm normally is a wrapper which often results in failures. This means you should only use ndbm if you are sure it works and if you really need this format.
`gdbm`	To enable support for gdbm add `--with-gdbm[=DIR]`.
`db2`	To enable support for db2 add `--with-db2[=DIR]`. 注: db2 conflicts with db3 and db4.
`db3`	To enable support for db3 add `--with-db3[=DIR]`. 注: db3 conflicts with db2 and db4.
`db4`	To enable support for db4 add `--with-db4[=DIR]`. 注: db4 conflicts with db2 and db3. 注: This was added in PHP 4.3.2. In earlier versions of PHP you need to use `--with-db3=DIR` with DIR being the path to db4 library. It is not possible to use db versions starting from 4.1 with PHP prior to version 4.3.0. Also, the db libraries with versions 4.1 through 4.1.24 cannot be used in any PHP version.
`cdb`	To enable support for cdb add `--with-cdb[=DIR]`. 注: Since PHP 4.3.0 you can omit DIR to use the bundled cdb library that adds the cdb_make handler which allows creation of cdb files and allows to access cdb files on the network using PHP's streams.
`flatfile`	To enable support for flatfile add `--with-flatfile`. 注: This was added in PHP 4.3.0 to add compatibility with deprecated dbm extension. Use this handler only when you cannot install one of the libraries required by the other handlers and when you cannot use bundled cdb handler.
`inifile`	To enable support for inifile add `--with-inifile`. 注: This was added in PHP 5.0.0 and allows to read and set microsoft style `.ini` files (like the `php.ini` file).
`qdbm`	To enable support for qdbm add `--with-qdbm[=DIR]`. 注: qdbm conflicts with dbm and gdbm. 注: This was added in PHP 5.0.0. The qdbm library can be loaded from http://qdbm.sourceforge.net.

注: Up to PHP 4.3.0 you are able to add both db2 and db3 handler but only one of them can be used internally. That means that you cannot have both file formats. Starting with PHP 5.0.0 there is a configuration check avoid such misconfigurations.

运行时配置

本扩展模块在 php.ini 中未定义任何配置选项。

资源类型

The functions dba_open() and dba_popen() return a handle to the specified database file to access which is used by all other dba-function calls.

预定义常量

本扩展模块未定义任何常量。

范例

例子 1. DBA example
<?php $id = dba_open("/tmp/test.db", "n", "db2"); if (!$id) { echo "dba_open failed\n"; exit; } dba_replace("key", "This is an example!", $id); if (dba_exists("key", $id)) { echo dba_fetch("key", $id); dba_delete("key", $id); } dba_close($id); ?>

DBA is binary safe and does not have any arbitrary limits. However, it inherits all limits set by the underlying database implementation.

All file-based databases must provide a way of setting the file mode of a new created database, if that is possible at all. The file mode is commonly passed as the fourth argument to dba_open() or dba_popen().

You can access all entries of a database in a linear way by using the dba_firstkey() and dba_nextkey() functions. You may not change the database while traversing it.

例子 2. Traversing a database
<?php // ...open database... $key = dba_firstkey($id); while ($key != false) { if (true) { // remember the key to perform some action later $handle_later[] = $key; } $key = dba_nextkey($id); } foreach ($handle_later as $val) { dba_delete($val, $id); } ?>

目录
dba_close -- Close a DBA database
dba_delete -- Delete DBA entry specified by key
dba_exists -- Check whether key exists
dba_fetch -- Fetch data specified by key
dba_firstkey -- Fetch first key
dba_handlers -- List all the handlers available
dba_insert -- Insert entry
dba_key_split -- Splits a key in string representation into array representation
dba_list -- List all open database files
dba_nextkey -- Fetch next key
dba_open -- Open database
dba_optimize -- Optimize database
dba_popen -- Open database persistently
dba_replace -- Replace or insert entry
dba_sync -- Synchronize database

dba_close

(PHP 3 >= 3.0.8, PHP 4, PHP 5)

dba_close -- Close a DBA database

说明

void dba_close ( resource handle )

dba_close() closes the established database and frees all resources of the specified database handle.

参数

handle: The database handler, returned by dba_open() or dba_popen().

返回值

无返回值。

参见

dba_open()

dba_popen()

dba_delete

(PHP 3 >= 3.0.8, PHP 4, PHP 5)

dba_delete -- Delete DBA entry specified by key

说明

bool dba_delete ( string key, resource handle )

dba_delete() deletes the specified entry from the database.

参数

key: The key of the entry which is deleted.
handle: The database handler, returned by dba_open() or dba_popen().

返回值

如果成功则返回 TRUE，失败则返回 FALSE。

参见

dba_exists

(PHP 3 >= 3.0.8, PHP 4, PHP 5)

dba_exists -- Check whether key exists

说明

bool dba_exists ( string key, resource handle )

dba_exists() checks whether the specified key exists in the database.

参数

key: The key the check is performed for.
handle: The database handler, returned by dba_open() or dba_popen().

返回值

Returns TRUE if the key exists, FALSE otherwise.

参见

dba_fetch

(PHP 3 >= 3.0.8, PHP 4, PHP 5)

dba_fetch -- Fetch data specified by key

说明

string dba_fetch ( string key, resource handle )

string dba_fetch ( string key, int skip, resource handle )

dba_fetch() fetches the data specified by key from the database specified with handle.

参数

key: The key the data is specified by.
注: When working with inifiles this function accepts arrays as keys where index 0 is the group and index 1 is the value name. See: dba_key_split().
skip: The number of key-value pairs to ignore when using cdb databases. This value is ignored for all other databases which do not support multiple keys with the same name.
handle: The database handler, returned by dba_open() or dba_popen().

返回值

Returns the associated string if the key/data pair is found, FALSE otherwise.

更新日志

版本	说明
4.3	The `skip` parameter is available to support cdb's capability of multiple keys having the same name.

参见

dba_key_split()

dba_firstkey

(PHP 3 >= 3.0.8, PHP 4, PHP 5)

dba_firstkey -- Fetch first key

说明

string dba_firstkey ( resource handle )

dba_firstkey() returns the first key of the database and resets the internal key pointer. This permits a linear search through the whole database.

参数

handle: The database handler, returned by dba_open() or dba_popen().

返回值

Returns the key on success, or FALSE on failure.

参见

dba_nextkey()

dba_key_split()

Example 2 in the DBA examples

dba_handlers

(PHP 4 >= 4.3.0, PHP 5)

dba_handlers -- List all the handlers available

说明

array dba_handlers ( [bool full_info] )

dba_handlers() list all the handlers supported by this extension.

参数

full_info: Turns on/off full information display in the result. The default is FALSE.

返回值

Returns an array of database handlers. If full_info is set to TRUE, the array will be associative with the handlers names as keys, and their version information as value. Otherwise, the result will be an indexed array of handlers names.

注: When the internal cdb library is used you will see cdb and cdb_make.

范例

例子 1. dba_handlers() Example
<?php echo "Available DBA handlers:\n"; foreach (dba_handlers(true) as $handler_name => $handler_version) { // clean the versions $handler_version = str_replace('$', '', $handler_version); echo " - $handler_name: $handler_version\n"; } ?>
上例的输出类似于：
Available DBA handlers: - cdb: 0.75, Revision: 1.3.2.3 - cdb_make: 0.75, Revision: 1.2.2.4 - db2: Sleepycat Software: Berkeley DB 2.7.7: (08/20/99) - inifile: 1.0, Revision: 1.6.2.3 - flatfile: 1.0, Revision: 1.5.2.4

dba_insert

(PHP 3 >= 3.0.8, PHP 4, PHP 5)

dba_insert -- Insert entry

说明

bool dba_insert ( string key, string value, resource handle )

dba_insert() inserts the entry described with key and value into the database.

参数

key: The key of the entry to be inserted. If this key already exist in the database, this function will fail. Use dba_replace() if you need to replace an existent key.
value: The value to be inserted.
handle: The database handler, returned by dba_open() or dba_popen().

返回值

如果成功则返回 TRUE，失败则返回 FALSE。

参见

dba_key_split

(PHP 5)

dba_key_split -- Splits a key in string representation into array representation

说明

mixed dba_key_split ( mixed key )

dba_key_split() splits a key (string representation) into an array representation.

参数

key: The key in string representation.

返回值

Returns an array of the form array(0 => group, 1 => value_name). This function will return FALSE if key is NULL or FALSE.

参见

dba_firstkey()

dba_nextkey()

dba_list

(PHP 4 >= 4.3.0, PHP 5)

dba_list -- List all open database files

说明

array dba_list ( void )

dba_list() list all open database files.

返回值

An associative array, in the form resourceid => filename.

dba_nextkey

(PHP 3 >= 3.0.8, PHP 4, PHP 5)

dba_nextkey -- Fetch next key

说明

string dba_nextkey ( resource handle )

dba_nextkey() returns the next key of the database and advances the internal key pointer.

参数

handle: The database handler, returned by dba_open() or dba_popen().

返回值

Returns the key on success, or FALSE on failure.

参见

dba_firstkey()

dba_key_split()

Example 2 in the DBA examples

dba_open

(PHP 3 >= 3.0.8, PHP 4, PHP 5)

dba_open -- Open database

说明

resource dba_open ( string path, string mode [, string handler [, mixed ...]] )

dba_open() establishes a database instance for path with mode using handler.

参数

path

Commonly a regular path in your filesystem.

mode

It is r for read access, w for read/write access to an already existing database, c for read/write access and database creation if it doesn't currently exist, and n for create, truncate and read/write access.

Additionally you can set the database lock method with the next char. Use l to lock the database with a .lck file or d to lock the databasefile itself. It is important that all of your applications do this consistently.

If you want to test the access and do not want to wait for the lock you can add t as third character. When you are absolutely sure that you do not require database locking you can do so by using - instead of l or d. When none of d, l or - is used, dba will lock on the database file as it would with d.

注: There can only be one writer for one database file. When you use dba on a webserver and more than one request requires write operations they can only be done one after another. Also read during write is not allowed. The dba extension uses locks to prevent this. See the following table:
表格 1. DBA locking
already open mode = "rl" mode = "rlt" mode = "wl" mode = "wlt" mode = "rd" mode = "rdt" mode = "wd" mode = "wdt"
not open ok ok ok ok ok ok ok ok
mode = "rl" ok ok wait false illegal illegal illegal illegal
mode = "wl" wait false wait false illegal illegal illegal illegal
mode = "rd" illegal illegal illegal illegal ok ok wait false
mode = "wd" illegal illegal illegal illegal wait false wait false

ok: the second call will be successfull.
wait: the second call waits until dba_close() is called for the first.
false: the second call returns false.
illegal: you must not mix "l" and "d" modifiers for mode parameter.

handler

The name of the handler which shall be used for accessing path. It is passed all optional parameters given to dba_open() and can act on behalf of them.

返回值

Returns a positive handle on success, or FALSE on failure.

更新日志

版本	说明
4.3.0	It's possible to open database files over network connection. However in cases a socket connection will be used (as with http or ftp) the connection will be locked instead of the resource itself. This is important to know since in such cases locking is simply ignored on the resource and other solutions have to be found.
4.3.0	Locking and the `mode` modifiers "l", "d", "-" and "t" were added. In previous PHP versions, you must use semaphores to guard against simultaneous database access for any database handler with the exception of GDBM. See System V semaphore support.
before 4.3.5	open mode 'c' is broken for several internal handlers and truncates the database instead of appending data to an existent database. Also dbm and ndbm fail on mode 'c' in typical configurations (this cannot be fixed).

参见

dba_popen()

dba_close()

dba_optimize

(PHP 3 >= 3.0.8, PHP 4, PHP 5)

dba_optimize -- Optimize database

说明

bool dba_optimize ( resource handle )

dba_optimize() optimizes the underlying database.

参数

handle: The database handler, returned by dba_open() or dba_popen().

返回值

如果成功则返回 TRUE，失败则返回 FALSE。

参见

dba_sync()

dba_popen

(PHP 3 >= 3.0.8, PHP 4, PHP 5)

dba_popen -- Open database persistently

说明

resource dba_popen ( string path, string mode [, string handler [, mixed ...]] )

dba_popen() establishes a persistent database instance for path with mode using handler.

参数

path: Commonly a regular path in your filesystem.
mode: It is r for read access, w for read/write access to an already existing database, c for read/write access and database creation if it doesn't currently exist, and n for create, truncate and read/write access.
handler: The name of the handler which shall be used for accessing path. It is passed all optional parameters given to dba_popen() and can act on behalf of them.

返回值

Returns a positive handle on success, or FALSE on failure.

参见

dba_open()

dba_close()

dba_replace

(PHP 3 >= 3.0.8, PHP 4, PHP 5)

dba_replace -- Replace or insert entry

说明

bool dba_replace ( string key, string value, resource handle )

dba_replace() replaces or inserts the entry described with key and value into the database specified by handle.

参数

key: The key of the entry to be replaced.
value: The value to be replaced.
handle: The database handler, returned by dba_open() or dba_popen().

返回值

如果成功则返回 TRUE，失败则返回 FALSE。

参见

dba_sync

(PHP 3 >= 3.0.8, PHP 4, PHP 5)

dba_sync -- Synchronize database

说明

bool dba_sync ( resource handle )

dba_sync() synchronizes the database. This will probably trigger a physical write to the disk, if supported.

参数

handle: The database handler, returned by dba_open() or dba_popen().

返回值

如果成功则返回 TRUE，失败则返回 FALSE。

参见

dba_optimize()

XXII. Date/Time 日期／时间函数

简介

可以用这些函数得到 PHP 所运行的服务器的日期和时间。可以用这些函数将日期和时间以很多不同方式格式化输出。

注: 请留意这些函数依赖于服务器的地区设置。确认在使用这些函数时考虑到了夏令时的设置（例如使用 $date = strtotime('+7 days', $date) 而不是 $date += 7*24*60*60）和闰年。

需求

要编译本扩展模块不需要外部库文件。

安装

本函数库作为 PHP 内核的一部分，不用安装就能使用。

运行时配置

本扩展模块在 php.ini 中未定义任何配置选项。

运行时配置

这些函数的行为受 php.ini 的影响。

表格 1. 日期／时间配置选项

名称	默认值	可修改范围	更新记录
date.default_latitude	"31.7667"	PHP_INI_ALL	自 PHP 5.0.0 起可用
date.default_longitude	"35.2333"	PHP_INI_ALL	自 PHP 5.0.0 起可用
date.sunrise_zenith	"90.83"	PHP_INI_ALL	自 PHP 5.0.0 起可用
date.sunset_zenith	"90.83"	PHP_INI_ALL	自 PHP 5.0.0 起可用
date.timezone	""	PHP_INI_ALL	自 PHP 5.0.0 起可用

有关 PHP_INI_* 常量进一步的细节与定义参见附录 G。

以下是配置选项的简要解释。

date.default_latitude float: 默认纬度。
date.default_longitude float: 默认经度。
date.sunrise_zenith float: 默认日出天顶。
date.sunset_zenith float: 默认日落天顶。
date.timezone string: 在未设定 TZ 环境变量时用于所有日期／时间函数的默认时区。优先顺序在 date_default_timezone_get() 页面中有说明。

注: 前四个配置选项目前仅用于 date_sunrise() 和 date_sunset()。

资源类型

本扩展模块未定义任何资源类型。

预定义常量

自 PHP 5.1.0 起定义有以下常量来提供标准日期表达方法，可以用于日期格式函数（例如 date()）。

DATE_ATOM（string）: 原子钟格式（如：2005-08-15T15:52:01+0000）
DATE_COOKIE（string）: HTTP Cookies 格式（如：Mon, 15 Aug 2005 15:52:01 UTC）
DATE_ISO8601（string）: ISO-8601（如：2005-08-15T15:52:01+0000）
DATE_RFC822（string）: RFC 822（如：Mon, 15 Aug 2005 15:52:01 UTC）
DATE_RFC850（string）: RFC 850（如：Monday, 15-Aug-05 15:52:01 UTC）
DATE_RFC1036（string）: RFC 1036（如：Monday, 15-Aug-05 15:52:01 UTC）
DATE_RFC1123（string）: RFC 1123（如：Mon, 15 Aug 2005 15:52:01 UTC）
DATE_RFC2822（string）: RFC 2822（如：Mon, 15 Aug 2005 15:52:01 +0000）
DATE_RSS（string）: RSS（如：Mon, 15 Aug 2005 15:52:01 UTC）
DATE_W3C（string）: World Wide Web Consortium（如：2005-08-15T15:52:01+0000）

目录
checkdate -- 验证一个格里高里日期
date_default_timezone_get -- 取得一个脚本中所有日期时间函数所使用的默认时区
date_default_timezone_set -- 设定用于一个脚本中所有日期时间函数的默认时区
date_sunrise -- 返回给定的日期与地点的日出时间
date_sunset -- 返回给定的日期与地点的日落时间
date -- 格式化一个本地时间／日期
getdate -- 取得日期／时间信息
gettimeofday -- 取得当前时间
gmdate -- 格式化一个 GMT/UTC 日期／时间
gmmktime -- 取得 GMT 日期的 UNIX 时间戳
gmstrftime -- 根据区域设置格式化 GMT/UTC 时间／日期
idate -- 将本地时间日期格式化为整数
localtime -- 取得本地时间
microtime -- 返回当前 Unix 时间戳和微秒数
mktime -- 取得一个日期的 Unix 时间戳
strftime -- 根据区域设置格式化本地时间／日期
strptime -- 解析由 strftime() 生成的日期／时间
strtotime -- 将任何英文文本的日期时间描述解析为 Unix 时间戳
time -- 返回当前的 Unix 时间戳

checkdate

(PHP 3, PHP 4, PHP 5)

checkdate -- 验证一个格里高里日期

说明

bool checkdate ( int month, int day, int year )

如果给出的日期有效则返回 TRUE，否则返回 FALSE。检查由参数构成的日期的合法性。日期在以下情况下被认为有效：

year 的值是从 1 到 32767
month 的值是从 1 到 12
Day 的值在给定的 month 所应该具有的天数范围之内，闰年已经考虑进去了。

例子 1. checkdate() 例子
<?php var_dump(checkdate(12, 31, 2000)); var_dump(checkdate(2, 29, 2001)); ?>
上例将输出：
bool(true) bool(false)

参见 mktime() 和 strtotime()。

date_default_timezone_get

(PHP 5 >= 5.1.0RC1)

date_default_timezone_get -- 取得一个脚本中所有日期时间函数所使用的默认时区

说明

string date_default_timezone_get ( void )

本函数返回默认时区，使用如下“假定”的顺序：

用 date_default_timezone_set() 函数设定的时区（如果设定了的话）
TZ 环境变量（如果非空）
date.timezone 配置选项（如果设定了的话）
自己推测（如果操作系统支持）
如果以上选择都不成功，则返回 UTC

返回值

返回一个 string。

参见

date_default_timezone_set()

date_default_timezone_set

(PHP 5 >= 5.1.0RC1)

date_default_timezone_set -- 设定用于一个脚本中所有日期时间函数的默认时区

说明

bool date_default_timezone_set ( string timezone_identifier )

date_default_timezone_set() 设定用于所有日期时间函数的默认时区。

注: 自 PHP 5.1.0 起（此版本日期时间函数被重写了），如果时区不合法则每个对日期时间函数的调用都会产生一条 E_NOTICE 级别的错误信息。

参数

timezone_identifier: 时区标识符，例如 UTC 或 Europe/Lisbon

返回值

本函数永远返回 TRUE（即使 timezone_identifier 参数不合法）。

参见

date_default_timezone_get()

date_sunrise

(PHP 5)

date_sunrise -- 返回给定的日期与地点的日出时间

说明

mixed date_sunrise ( int timestamp [, int format [, float latitude [, float longitude [, float zenith [, float gmt_offset]]]]] )

date_sunrise() 返回给定的日期（以 timestamp 指定）与地点的日出时间。latitude，longitude 和 zenith 参数默认值分别为配置选项中的 date.default_latitude，date.default_longitude 和 date.sunrise_zenith。

latitude 默认是指北纬。因此如果要指定南纬，必须传递一个负值。同样规则也适用于 longitude，其默认是指东经。

gmt_offset 参数的单位是小时。

表格 1. format 常量

常量	说明	取值举例
SUNFUNCS_RET_STRING	以 string 格式返回结果	16:46
SUNFUNCS_RET_DOUBLE	以 float 格式返回结果	16.78243132
SUNFUNCS_RET_TIMESTAMP	以 integer 格式（时间戳）返回结果	1095034606

例子 1. date_sunrise() 例子
<?php /* 计算葡萄牙里斯本的日出时间 Latitude: 北纬 38.4 度 Longitude: 西经 9 度 Zenith ~= 90 offset: +1 GMT */ echo date("D M d Y"). ', sunrise time : ' .date_sunrise(time(), SUNFUNCS_RET_STRING, 38.4, -9, 90, 1); ?>
上例的输出类似于：
Mon Dec 20 2004, sunrise time : 08:54

参见 date_sunset()。

date_sunset

(PHP 5)

date_sunset -- 返回给定的日期与地点的日落时间

说明

mixed date_sunset ( int timestamp [, int format [, float latitude [, float longitude [, float zenith [, float gmt_offset]]]]] )

date_sunset() 返回给定的日期（以 timestamp 指定）与地点的日落时间。latitude，longitude 和 zenith 参数默认值分别为配置选项中的 date.default_latitude，date.default_longitude 和 date.sunrise_zenith。

latitude 默认是指北纬。因此如果要指定南纬，必须传递一个负值。同样规则也适用于 longitude，其默认是指东经。

gmt_offset 参数的单位是小时。

表格 1. format 常量

常量	说明	取值举例
SUNFUNCS_RET_STRING	以 string 格式返回结果	16:46
SUNFUNCS_RET_DOUBLE	以 float 格式返回结果	16.78243132
SUNFUNCS_RET_TIMESTAMP	以 integer 格式（时间戳）返回结果	1095034606

例子 1. date_sunset() 例子
<?php /* 计算葡萄牙里斯本的日落时间 Latitude: 北纬 38.4 度 Longitude: 西经 9 度 Zenith ~= 90 offset: +1 GMT */ echo date("D M d Y"). ', sunset time : ' .date_sunset(time(), SUNFUNCS_RET_STRING, 38.4, -9, 90, 1); ?>
上例的输出类似于：
Mon Dec 20 2004, sunset time : 18:13

参见 date_sunrise()。

date

(PHP 3, PHP 4, PHP 5)

date -- 格式化一个本地时间／日期

说明

string date ( string format [, int timestamp] )

返回将整数 timestamp 按照给定的格式字串而产生的字符串。如果没有给出时间戳则使用本地当前时间。换句话说，timestamp 是可选的，默认值为 time()。

提示: 自 PHP 5.1.0 起有几个有用的常量可用作标准的日期／时间格式来指定 format 参数。

注: 有效的时间戳典型范围是格林威治时间 1901 年 12 月 13 日 20:45:54 到 2038 年 1 月 19 日 03:14:07。（此范围符合 32 位有符号整数的最小值和最大值）。不过在 PHP 5.1 之前此范围在某些系统（如 Windows）中限制为从 1970 年 1 月 1 日到 2038 年 1 月 19 日。

注: 要将字符串表达的时间转换成时间戳，应该使用 strtotime()。此外一些数据库有一些函数将其时间格式转换成时间戳（例如 MySQL 的 UNIX_TIMESTAMP 函数）。

表格 1. 格式字串可以识别以下 format 参数的字符串

`format` 字符	说明	返回值例子
日	---	---
`d`	月份中的第几天，有前导零的 2 位数字	`01` 到 `31`
`D`	星期中的第几天，文本表示，3 个字母	`Mon` 到 `Sun`
`j`	月份中的第几天，没有前导零	`1` 到 `31`
`l`（“L”的小写字母）	星期几，完整的文本格式	`Sunday` 到 `Saturday`
`N`	ISO-8601 格式数字表示的星期中的第几天（PHP 5.1.0 新加）	`1`（表示星期一）到 `7`（表示星期天）
`S`	每月天数后面的英文后缀，2 个字符	`st`，`nd`，`rd` 或者 `th`。可以和 `j` 一起用
`w`	星期中的第几天，数字表示	`0`（表示星期天）到 `6`（表示星期六）
`z`	年份中的第几天	`0` 到 `366`
星期	---	---
`W`	ISO-8601 格式年份中的第几周，每周从星期一开始（PHP 4.1.0 新加的）	例如：`42`（当年的第 42 周）
月	---	---
`F`	月份，完整的文本格式，例如 January 或者 March	`January` 到 `December`
`m`	数字表示的月份，有前导零	`01` 到 `12`
`M`	三个字母缩写表示的月份	`Jan` 到 `Dec`
`n`	数字表示的月份，没有前导零	`1` 到 `12`
`t`	给定月份所应有的天数	`28` 到 `31`
年	---	---
`L`	是否为闰年	如果是闰年为 `1`，否则为 `0`
`o`	ISO-8601 格式年份数字。这和 `Y` 的值相同，只除了如果 ISO 的星期数（`W`）属于前一年或下一年，则用那一年。（PHP 5.1.0 新加）	Examples: `1999` or `2003`
`Y`	4 位数字完整表示的年份	例如：`1999` 或 `2003`
`y`	2 位数字表示的年份	例如：`99` 或 `03`
时间	---	---
`a`	小写的上午和下午值	`am` 或 `pm`
`A`	大写的上午和下午值	`AM` 或 `PM`
`B`	Swatch Internet 标准时	`000` 到 `999`
`g`	小时，12 小时格式，没有前导零	`1` 到 `12`
`G`	小时，24 小时格式，没有前导零	`0` 到 `23`
`h`	小时，12 小时格式，有前导零	`01` 到 `12`
`H`	小时，24 小时格式，有前导零	`00` 到 `23`
`i`	有前导零的分钟数	`00` 到 `59`>
`s`	秒数，有前导零	`00` 到 `59`>
时区	---	---
`e`	时区标识（PHP 5.1.0 新加）	例如：`UTC`，`GMT`，`Atlantic/Azores`
`I`	是否为夏令时	如果是夏令时为 `1`，否则为 `0`
`O`	与格林威治时间相差的小时数	例如：`+0200`
`T`	本机所在的时区	例如：`EST`，`MDT`（【译者注】在 Windows 下为完整文本格式，例如“Eastern Standard Time”，中文版会显示“中国标准时间”）。
`Z`	时差偏移量的秒数。UTC 西边的时区偏移量总是负的，UTC 东边的时区偏移量总是正的。	`-43200` 到 `43200`
完整的日期／时间	---	---
`c`	ISO 8601 格式的日期（PHP 5 新加）	2004-02-12T15:19:21+00:00
`r`	RFC 822 格式的日期	例如：`Thu, 21 Dec 2000 16:01:07 +0200`
`U`	从 Unix 纪元（January 1 1970 00:00:00 GMT）开始至今的秒数	参见 time()

格式字串中不能被识别的字符将原样显示。Z 格式在使用 gmdate() 时总是返回 0。

例子 1. date() 例子
<?php // 设定要用的默认时区。自 PHP 5.1 可用 date_default_timezone_set('UTC'); // 输出类似：Monday echo date("l"); // 输出类似：Monday 15th of August 2005 03:12:46 PM echo date('l dS \of F Y h:i:s A'); // 输出：July 1, 2000 is on a Saturday echo "July 1, 2000 is on a " . date("l", mktime(0, 0, 0, 7, 1, 2000)); /* 在格式参数中使用常量 */ // 输出类似：Mon, 15 Aug 2005 15:12:46 UTC echo date(DATE_RFC822); // 输出类似：2000-07-01T00:00:00+0000 echo date(DATE_ATOM, mktime(0, 0, 0, 7, 1, 2000)); ?>

在格式字串中的字符前加上反斜线来转义可以避免它被按照上表解释。如果加上反斜线后的字符本身就是一个特殊序列，那还要转义反斜线。
例子 2. 在 date() 中转义字符
<?php // prints something like: Wednesday the 15th echo date("l \\t\h\e jS"); ?>

可以把 date() 和 mktime() 结合使用来得到未来或过去的日期。
例子 3. date() 和 mktime() 例子
<?php $tomorrow = mktime(0, 0, 0, date("m") , date("d")+1, date("Y")); $lastmonth = mktime(0, 0, 0, date("m")-1, date("d"), date("Y")); $nextyear = mktime(0, 0, 0, date("m"), date("d"), date("Y")+1); ?>

注: 由于夏令时的缘故，这种方法比简单地在时间戳上加减一天或者一个月的秒数更可靠。

一些使用 date() 格式化日期的例子。注意要转义所有其它的字符，因为目前有特殊含义的字符会产生不需要的结果，而其余字符在 PHP 将来的版本中可能会被用上。当转义时，注意用单引号以避免类似 \n 的字符变成了换行符。
例子 4. date() 格式举例
<?php // 假定今天是：March 10th, 2001, 5:16:18 pm $today = date("F j, Y, g:i a"); // March 10, 2001, 5:16 pm $today = date("m.d.y"); // 03.10.01 $today = date("j, n, Y"); // 10, 3, 2001 $today = date("Ymd"); // 20010310 $today = date('h-i-s, j-m-y, it is w Day z '); // 05-16-17, 10-03-01, 1631 1618 6 Fripm01 $today = date('\i\t \i\s \t\h\e jS \d\a\y.'); // It is the 10th day. $today = date("D M j G:i:s T Y"); // Sat Mar 10 15:16:08 MST 2001 $today = date('H:m:s \m \i\s\ \m\o\n\t\h'); // 17:03:17 m is month $today = date("H:i:s"); // 17:16:17 ?>

要格式化其它语种的日期，应该用 setlocale() 和 strftime() 函数。

参见 getlastmod()，gmdate()，mktime()，strftime() 和 time()。

getdate

(PHP 3, PHP 4, PHP 5)

getdate -- 取得日期／时间信息

说明

array getdate ( [int timestamp] )

返回一个根据 timestamp 得出的包含有日期信息的结合数组。如果没有给出时间戳则认为是当前本地时间。数组中的单元如下：

表格 1. 返回的关联数组中的键名单元

键名	说明	返回值例子
`"seconds"`	秒的数字表示	`0` 到 `59`
`"minutes"`	分钟的数字表示	`0` 到 `59`
`"hours"`	小时的数字表示	`0` 到 `23`
`"mday"`	月份中第几天的数字表示	`1` 到 `31`
`"wday"`	星期中第几天的数字表示	`0`（表示星期天）到 `6`（表示星期六）
`"mon"`	月份的数字表示	`1` 到 `12`
`"year"`	4 位数字表示的完整年份	例如：`1999` 或 `2003`
`"yday"`	一年中第几天的数字表示	`0` 到 `365`
`"weekday"`	星期几的完整文本表示	`Sunday` 到 `Saturday`
`"month"`	月份的完整文本表示	`January>` 到 `December`
`0`	自从 Unix 纪元开始至今的秒数，和 time() 的返回值以及用于 date() 的值类似。	系统相关，典型值为从 `-2147483648` 到 `2147483647`。

例子 1. getdate() 例子
<?php $today = getdate(); print_r($today); ?>
上例的输出类似于：
Array ( [seconds] => 40 [minutes] => 58 [hours] => 21 [mday] => 17 [wday] => 2 [mon] => 6 [year] => 2003 [yday] => 167 [weekday] => Tuesday [month] => June [0] => 1055901520 )

参见 date()，time() 和 setlocale()。

gettimeofday

(PHP 3 >= 3.0.7, PHP 4, PHP 5)

gettimeofday -- 取得当前时间

说明

mixed gettimeofday ( [bool return_float] )

本函数是 gettimeofday(2) 的接口。返回一个关联数组，包含有系统调用返回的数据。

自 PHP 5.1.0 起有个可选参数 return_float，当其设为 TRUE 时，gettimeofday() 会返回一个浮点数。

数组中的键为：

"sec" - 自 Unix 纪元起的秒数
"usec" - 微秒数
"minuteswest" - 格林威治向西的分钟数
"dsttime" - 夏令时修正的类型

例子 1. gettimeofday() example
<?php print_r(gettimeofday()); echo gettimeofday(true); ?>
上例的输出类似于：
Array ( [sec] => 1073504408 [usec] => 238215 [minuteswest] => 0 [dsttime] => 1 ) 1073504408.23910

gmdate

(PHP 3, PHP 4, PHP 5)

gmdate -- 格式化一个 GMT/UTC 日期／时间

说明

string gmdate ( string format [, int timestamp] )

同 date() 函数完全一样，只除了返回的时间是格林威治标准时（GMT）。例如当在中国（GMT +0800）运行以下程序时，第一行显示“Jan 01 2000 00:00:00”而第二行显示“Dec 31 1999 16:00:00”。
例子 1. gmdate() 例子
<?php echo date("M d Y H:i:s", mktime (0,0,0,1,1,2000)); echo gmdate("M d Y H:i:s", mktime (0,0,0,1,1,2000)); ?>

注: 在 PHP 5.1.0 之前，负的时间戳（1970 年之前的日期）在某些系统下（例如 Windows）不能工作。

参见 date()，mktime()，gmmktime() 和 strftime()。

gmmktime

(PHP 3, PHP 4, PHP 5)

gmmktime -- 取得 GMT 日期的 UNIX 时间戳

说明

int gmmktime ( [int hour [, int minute [, int second [, int month [, int day [, int year [, int is_dst]]]]]]] )

和 mktime() 完全一样，只除了返回值是格林威治标准时的时间戳。

参数总是表示 GMT 日期，因此 is_dst 对结果没有影响。

和 mktime() 一样，参数可以从右到左依次空着，空着的参数会被设为相应的当前 GMT 值。

注: 自 5.1.0 起，is_dst 参数被废弃。因此应该用新的时区处理特性。

注: gmmktime() 内部使用了 mktime()，因此只有转换成本地时间也合法的时间才能用在其中。 so only times valid in derived local time can be used.

例子 1. gmmktime() 在 Windows 中的边界

<?php
gmmktime(0, 0, 0, 1, 1, 1970); // 在 GMT 和西方合法，在东方不合法
?>

参见 mktime()，date() 和 time()。

gmstrftime

(PHP 3 >= 3.0.12, PHP 4, PHP 5)

gmstrftime -- 根据区域设置格式化 GMT/UTC 时间／日期

说明

string gmstrftime ( string format [, int timestamp] )

和 strftime() 的行为相同，只除了返回时间是格林威治标准时（GMT）。例如，当在东部标准时（EST，GMT -500）运行时，下面第一行显示“Dec 31 1998 20:00:00”，而第二行显示“Jan 01 1999 01:00:00”。
例子 1. gmstrftime() 例子
<?php setlocale(LC_TIME, 'en_US'); echo strftime("%b %d %Y %H:%M:%S", mktime (20,0,0,12,31,98))."\n"; echo gmstrftime("%b %d %Y %H:%M:%S", mktime (20,0,0,12,31,98))."\n"; ?>

参见 strftime()。

idate

(PHP 5)

idate -- 将本地时间日期格式化为整数

说明

int idate ( string format [, int timestamp] )

根据给定的格式字符对 timestamp 格式化并返回数字结果。timestamp 为可选项，默认值为本地当前时间，即 time() 的值。

和 date() 不同，idate() 只接受一个字符作为 format 参数。

表格 1. format 参数可识别以下字符

`format` 字符	说明
`B`	Swatch Beat/Internet Time
`d`	月份中的第几天
`h`	小时（12 小时格式）
`H`	小时（24 小时格式）
`i`	分钟
`I`	如果启用夏时制则返回 `1`，否则返回 `0`
`L`	如果是闰年则返回 `1`，否则返回 `0`
`m`	月份的数字
`s`	秒数
`t`	本月的总天数
`U`	自 Unix 纪元（January 1 1970 00:00:00 GMT）起的秒数――这和 time() 作用相同
`w`	星期中的第几天（星期天是 `0`）
`W`	ISO-8601 格式年份中的第几个星期，每星期从星期一开始
`y`	年份（1 或 2 位数字――见下面说明）
`Y`	年份（4 位数字）
`z`	年份中的第几天
`Z`	以秒为单位的时区偏移量

注: 因为 idate() 总是返回 integer，不能以“0”开头，因此 idate() 可能会返回比用户期望中要少的数字。见下面例子：

<?php
$timestamp = strtotime('1st January 2004'); //1072915200

// 下面以两位数字格式显示年份，但是因为
// 以“0”打头，因此只会显示“4”
echo idate('y', $timestamp);
?>

参见 date() 和 time()。

localtime

(PHP 4, PHP 5)

localtime -- 取得本地时间

说明

array localtime ( [int timestamp [, bool is_associative]] )

localtime() 函数返回一个数组，其结构和 C 函数调用返回的完全一样。localtime() 的第一个参数是时间戳，如果没有给出则使用从 time() 返回的当前时间。第二个参数是 is_associative，如果设为 FALSE 或未提供则返回的是普通的数字索引数组。如果该参数设为 TRUE 则 localtime() 函数返回包含有所有从 C 的 localtime 函数调用所返回的不同单元的关联数组。关联数组中不同的键名为：

"tm_sec" - 秒数
"tm_min" - 分钟数
"tm_hour" - 小时
"tm_mday" - 月份中的第几日
"tm_mon" - 年份中的第几个月，从 0 开始表示一月
"tm_year" - 年份，从 1900 开始
"tm_wday" - 星期中的第几天
"tm_yday" - 一年中的第几天
"tm_isdst" - 夏令时当前是否生效

注: 月份从 0（一月）到 11（十二月），星期数从 0（星期天）到 6（星期六）。

例子 1. time() 例子
<?php $localtime = localtime(); $localtime_assoc = localtime(time(), true); print_r($localtime); print_r($localtime_assoc); ?>
上例的输出类似于：
Array ( [0] => 24 [1] => 3 [2] => 19 [3] => 3 [4] => 3 [5] => 105 [6] => 0 [7] => 92 [9] => 1 ) Array ( [tm_sec] => 24 [tm_min] => 3 [tm_hour] => 19 [tm_mday] => 3 [tm_mon] => 3 [tm_year] => 105 [tm_wday] => 0 [tm_yday] => 92 [tm_isdst] => 1 )

microtime

(PHP 3, PHP 4, PHP 5)

microtime -- 返回当前 Unix 时间戳和微秒数

说明

mixed microtime ( [bool get_as_float] )

microtime() 当前 Unix 时间戳以及微秒数。本函数仅在支持 gettimeofday() 系统调用的操作系统下可用。

如果调用时不带可选参数，本函数以 "msec sec" 的格式返回一个字符串，其中 sec 是自 Unix 纪元（0:00:00 January 1, 1970 GMT）起到现在的秒数，msec 是微秒部分。字符串的两部分都是以秒为单位返回的。

如果给出了 get_as_float 参数并且其值等价于 TRUE，microtime() 将返回一个浮点数。

注: get_as_float 参数是 PHP 5.0.0 新加的。

例子 1. 用 microtime() 对脚本的运行计时
<?php /** * Simple function to replicate PHP 5 behaviour */ function microtime_float() { list($usec, $sec) = explode(" ", microtime()); return ((float)$usec + (float)$sec); } $time_start = microtime_float(); // Sleep for a while usleep(100); $time_end = microtime_float(); $time = $time_end - $time_start; echo "Did nothing in $time seconds\n"; ?>

参见 time()。

mktime

(PHP 3, PHP 4, PHP 5)

mktime -- 取得一个日期的 Unix 时间戳

说明

int mktime ( [int hour [, int minute [, int second [, int month [, int day [, int year [, int is_dst]]]]]]] )

根据给出的参数返回 Unix 时间戳。时间戳是一个长整数，包含了从 Unix 纪元（January 1 1970 00:00:00 GMT）到给定时间的秒数。

参数可以从右向左省略，任何省略的参数会被设置成本地日期和时间的当前值。

参数

hour: 小时数。
minute: 分钟数。
second: 秒数（一分钟之内）。
month: 月份数。
day: 天数。
year: 年份数，可以是两位或四位数字，0-69 对应于 2000-2069，70-100 对应于 1970-2000。在如今系统中普遍把 time_t 作为一个 32 位有符号整数的情况下，year 的合法范围是 1901 到 2038 之间，不过此限制自 PHP 5.1.0 起已被克服了。
is_dst: 本参数可以设为 1，表示正处于夏时制时间（DST），0 表示不是夏时制，或者 -1（默认值）表示不知道是否是夏时制。如果未知，PHP 会尝试自己搞明白。这可能产生不可预知（但并非不正确）的结果。如果 PHP 运行的系统中启用了 DST 或者 is_dst 设为 1，某些时间是无效的。例如 DST 自 2:00 生效，则所有处于 2:00 到 3:00 之间的时间都无效，mktime() 会返回一个未定义（通常为负）的值。某些系统（例如 Solaris 8）的 DST 在午夜生效，则 DST 生效当天的 0:30 会被计算为前一天的 23:30。
注: 自 PHP 5.1.0 起，本参数已被废弃。应该使用新的时区处理特性来替代。

返回值

mktime() 根据给出的参数返回 Unix 时间戳。如果参数非法（例如年，月，日都是零），本函数返回 FALSE（在 PHP 5.1 之前返回 -1）。

更新日志

版本	说明
3.0.10	加入了 `is_dst` 参数
5.1.0	`is_dst` 参数被废弃。出错时函数返回 `FALSE` 而不再是 `-1`

范例

例子 1. mktime() 例子
mktime() 在做日期计算和验证方面很有用，它会自动计算超出范围的输入的正确值。例如下面例子中每一行都会产生字符串 "Jan-01-1998"。
<?php echo date("M-d-Y", mktime(0, 0, 0, 12, 32, 1997)); echo date("M-d-Y", mktime(0, 0, 0, 13, 1, 1997)); echo date("M-d-Y", mktime(0, 0, 0, 1, 1, 1998)); echo date("M-d-Y", mktime(0, 0, 0, 1, 1, 98)); ?>

例子 2. 下个月的最后一天
任何给定月份的最后一天都可以被表示为下个月的第 "0" 天，而不是 -1 天。下面两个例子都会产生字符串 "The last day in Feb 2000 is: 29"。
<?php $lastday = mktime(0, 0, 0, 3, 0, 2000); echo strftime("Last day in Feb 2000 is: %d", $lastday); $lastday = mktime(0, 0, 0, 4, -31, 2000); echo strftime("Last day in Feb 2000 is: %d", $lastday); ?>

注释

注意

在 PHP 5.1.0 之前，在任何已知 Windows 版本以及一些其它系统下不支持负的时间戳。因此年份的有效范围限制为 1970 到 2038。

参见

gmmktime()

date()

time()

strftime

(PHP 3, PHP 4, PHP 5)

strftime -- 根据区域设置格式化本地时间／日期

说明

string strftime ( string format [, int timestamp] )

返回用给定的格式字串对给出的 timestamp 进行格式输出后的字符串。如果没有给出时间戳则用当前的本地时间。月份和星期几以及其它和语言有关的字符串写法和用 setlocale() 设定的当前的区域有关。

格式字串能识别下列转换标记：

%a - 当前区域星期几的简写
%A - 当前区域星期几的全称
%b - 当前区域月份的简写
%B - 当前区域月份的全称
%c - 当前区域首选的日期时间表达
%C - 世纪值（年份除以 100 后取整，范围从 00 到 99）
%d - 月份中的第几天，十进制数字（范围从 01 到 31）
%D - 和 %m/%d/%y 一样
%e - 月份中的第几天，十进制数字，一位的数字前会加上一个空格（范围从 ' 1' 到 '31'）
%g - 和 %G 一样，但是没有世纪
%G - 4 位数的年份，符合 ISO 星期数（参见 %V）。和 %V 的格式和值一样，只除了如果 ISO 星期数属于前一年或者后一年，则使用那一年。
%h - 和 %b 一样
%H - 24 小时制的十进制小时数（范围从 00 到 23）
%I - 12 小时制的十进制小时数（范围从 00 到 12）
%j - 年份中的第几天，十进制数（范围从 001 到 366）
%m - 十进制月份（范围从 01 到 12）
%M - 十进制分钟数
%n - 换行符
%p - 根据给定的时间值为 `am' 或 `pm'，或者当前区域设置中的相应字符串
%r - 用 a.m. 和 p.m. 符号的时间
%R - 24 小时符号的时间
%S - 十进制秒数
%t - 制表符
%T - 当前时间，和 %H:%M:%S 一样
%u - 星期几的十进制数表达 [1,7]，1 表示星期一
警告
尽管 ISO 9889:1999（当前的 C 标准）明确指出一周从星期一开始，但是 Sun Solaris 的一周似乎从星期天开始并作为 1。
%U - 本年的第几周，从第一周的第一个星期天作为第一天开始
%V - 本年第几周的 ISO 8601:1988 格式，范围从 01 到 53，第 1 周是本年第一个至少还有 4 天的星期，星期一作为每周的第一天。（用 %G 或者 %g 作为指定时间戳相应周数的年份组成。）
%W - 本年的第几周数，从第一周的第一个星期一作为第一天开始
%w - 星期中的第几天，星期天为 0
%x - 当前区域首选的时间表示法，不包括时间
%X - 当前区域首选的时间表示法，不包括日期
%y - 没有世纪数的十进制年份（范围从 00 到 99）
%Y - 包括世纪数的十进制年份
%Z 或 %z - 时区名或缩写
%% - 文字上的 `%' 字符

注: 可能不是所有的转换标记都被 C 库文件支持，这种情况下 PHP 的 strftime() 也不支持。此外，不是所有的平台都支持负的时间戳，因此日期的范围可能限定在不早于 Unix 纪元。这意味着例如 %e, %T，%R 和 %D（可能更多）以及早于 Jan 1, 1970 的时间在 Windows，一些 Linux 发行版本，以及其它几个操作系统中无效。对于 Windows 系统，所支持的转换标记可在 MSDN 网站找到。

例子 1. strftime() 区域的例子

<?php
setlocale(LC_TIME, "C");
echo strftime("%A");
setlocale(LC_TIME, "fi_FI");
echo strftime(" in Finnish is %A,");
setlocale(LC_TIME, "fr_FR");
echo strftime(" in French %A and");
setlocale(LC_TIME, "de_DE");
echo strftime(" in German %A.\n");
?>

本例在你的系统中安装有各自的区域设置后才能工作。

注: %G 和 %V，如果数字编号系统未能充分理解，基于 ISO 8601:1988 的星期数可能得出未预期的结果。见上面的 %V 和以下的例子。

例子 2. ISO 8601:1988 week number example

<?php
/*     December 2002 / January 2003
ISOWk  M   Tu  W   Thu F   Sa  Su
----- ----------------------------
51     16  17  18  19  20  21  22
52     23  24  25  26  27  28  29
1      30  31   1   2   3   4   5
2       6   7   8   9  10  11  12
3      13  14  15  16  17  18  19   */

// Outputs: 12/28/2002 - %V,%G,%Y = 52,2002,2002
echo "12/28/2002 - %V,%G,%Y = " . strftime("%V,%G,%Y", strtotime("12/28/2002")) . "\n";

// Outputs: 12/30/2002 - %V,%G,%Y = 1,2003,2002
echo "12/30/2002 - %V,%G,%Y = " . strftime("%V,%G,%Y", strtotime("12/30/2002")) . "\n";

// Outputs: 1/3/2003 - %V,%G,%Y = 1,2003,2003
echo "1/3/2003 - %V,%G,%Y = " . strftime("%V,%G,%Y",strtotime("1/3/2003")) . "\n";

// Outputs: 1/10/2003 - %V,%G,%Y = 2,2003,2003
echo "1/10/2003 - %V,%G,%Y = " . strftime("%V,%G,%Y",strtotime("1/10/2003")) . "\n";



/*     December 2004 / January 2005
ISOWk  M   Tu  W   Thu F   Sa  Su
----- ----------------------------
51     13  14  15  16  17  18  19
52     20  21  22  23  24  25  26
53     27  28  29  30  31   1   2
1       3   4   5   6   7   8   9
2      10  11  12  13  14  15  16   */

// Outputs: 12/23/2004 - %V,%G,%Y = 52,2004,2004
echo "12/23/2004 - %V,%G,%Y = " . strftime("%V,%G,%Y",strtotime("12/23/2004")) . "\n";

// Outputs: 12/31/2004 - %V,%G,%Y = 53,2004,2004
echo "12/31/2004 - %V,%G,%Y = " . strftime("%V,%G,%Y",strtotime("12/31/2004")) . "\n";

// Outputs: 1/2/2005 - %V,%G,%Y = 53,2004,2005
echo "1/2/2005 - %V,%G,%Y = " . strftime("%V,%G,%Y",strtotime("1/2/2005")) . "\n";

// Outputs: 1/3/2005 - %V,%G,%Y = 1,2005,2005
echo "1/3/2005 - %V,%G,%Y = " . strftime("%V,%G,%Y",strtotime("1/3/2005")) . "\n";

?>

参见 setlocale()，mktime()，strptime() 以及 Open Group specification of strftime()。

strptime

(PHP 5 >= 5.1.0RC1)

strptime -- 解析由 strftime() 生成的日期／时间

说明

array strptime ( string date, string format )

strptime() 返回一个将 date 解析后的数组，如果出错返回 FALSE。

月份和星期几的名字以及其它与语种有关的字符串对应于 setlocale()设定的当前区域（LC_TIME）。

参数

date（string）

被解析的字符串（例如从 strftime() 返回的）

format（string）

date 所使用的格式（例如同 strftime() 中所使用的相同）。

更多有关格式选项的信息见 strftime() 页面。

返回值

返回一个数组，失败则返回 FALSE。

表格 1. 数组中包含以下单元

键名	说明
tm_sec	当前分钟内的秒数（0-61）
tm_min	当前小时内的分钟数（0-59）
tm_hour	午夜起的小时数（0-23）
tm_mday	月份中的第几天（1-31）
tm_mon	自一月起过了几个月（0-11）
tm_year	自 1900 年起过了几年
tm_wday	自星期天起过了几天（0-6）
tm_yday	本年自一月一日起过了多少天（0-365）
unparsed	`date` 中未能通过指定的 `format` 识别的部分

范例

例子 1. strptime() 例子
<?php $format = '%d/%m/%Y %H:%M:%S'; $strf = strftime($format); echo "$strf\n"; print_r(strptime($strf, $format)); ?>
上例的输出类似于：
03/10/2004 15:54:19 Array ( [tm_sec] => 19 [tm_min] => 54 [tm_hour] => 15 [tm_mday] => 3 [tm_mon] => 9 [tm_year] => 104 [tm_wday] => 0 [tm_yday] => 276 [unparsed] => )

参见

strftime()

strtotime

(PHP 3 >= 3.0.12, PHP 4, PHP 5)

strtotime -- 将任何英文文本的日期时间描述解析为 Unix 时间戳

说明

int strtotime ( string time [, int now] )

本函数预期接受一个包含美国英语日期格式的字符串并尝试将其解析为 Unix 时间戳（自 January 1 1970 00:00:00 GMT 起的秒数），其值相对于 now 参数给出的时间，如果没有提供此参数则用系统当前时间。

本函数将使用 TZ 环境变量（如果有的话）来计算时间戳。自 PHP 5.1.0 起有更容易的方法来定义时区用于所有的日期／时间函数。此过程在 date_default_timezone_get() 函数页面中有说明。

注: 如果给定的年份是两位数字的格式，则其值 0-69 表示 2000-2069，70-100 表示 1970-2000。

参数

time: 被解析的字符串，格式根据 GNU Date Input Formats 语法
now: 用来计算返回值的时间戳

返回值

成功则返回时间戳，否则返回 FALSE。在 PHP 5.1.0 之前本函数在失败时返回 -1。

更新日志

版本	说明
5.1.0	失败时返回 `FALSE`，不再是 `-1`。

范例

例子 1. strtotime() 例子
<?php echo strtotime("now"), "\n"; echo strtotime("10 September 2000"), "\n"; echo strtotime("+1 day"), "\n"; echo strtotime("+1 week"), "\n"; echo strtotime("+1 week 2 days 4 hours 2 seconds"), "\n"; echo strtotime("next Thursday"), "\n"; echo strtotime("last Monday"), "\n"; ?>

例子 2. 失败检查
<?php $str = 'Not Good'; // previous to PHP 5.1.0 you would compare with -1, instead of false if (($timestamp = strtotime($str)) === false) { echo "The string ($str) is bogus"; } else { echo "$str == " . date('l dS of F Y h:i:s A', $timestamp); } ?>

注释

警告

在 PHP 5 中到 5.0.2 之前，"now" 和其它相对时间从今天午夜起错误计算了。这和正确从当前时间起计算的其它版本不同。

注: 有效的时间戳通常从 Fri, 13 Dec 1901 20:45:54 GMT 到 Tue, 19 Jan 2038 03:14:07 GMT（对应于 32 位有符号整数的最小值和最大值）。不是所有的平台都支持负的时间戳，那么日记范围就被限制为不能早于 Unix 纪元。这意味着在 1970 年 1 月 1 日之前的日期将不能用在 Windows，一些 Linux 版本，以及几个其它的操作系统中。不过 PHP 5.1.0 及更新的版本克服了此限制。

参见

strptime()

time

(PHP 3, PHP 4, PHP 5)

time -- 返回当前的 Unix 时间戳

说明

int time ( void )

返回自从 Unix 纪元（格林威治时间 1970 年 1 月 1 日 00:00:00）到当前时间的秒数。

例子 1. time() 例子
<?php $nextWeek = time() + (7 * 24 * 60 * 60); // 7 days; 24 hours; 60 mins; 60secs echo 'Now: '. date('Y-m-d') ."\n"; echo 'Next Week: '. date('Y-m-d', $nextWeek) ."\n"; ?>
上例的输出类似于：
Now: 2005-03-30 Next Week: 2005-04-07

参见 date() 和 microtime()。

XXIII. DB++ Functions

警告

简介

db++, made by the German company Concept asa, is a relational database system with high performance and low memory and disk usage in mind. While providing SQL as an additional language interface, it is not really a SQL database in the first place but provides its own AQL query language which is much more influenced by the relational algebra then SQL is.

Concept asa always had an interest in supporting open source languages, db++ has had Perl and Tcl call interfaces for years now and uses Tcl as its internal stored procedure language.

需求

This extension relies on external client libraries so you have to have a db++ client installed on the system you want to use this extension on.

Concept asa provides db++ Demo versions and documentation for Linux, some other Unix versions. There is also a Windows version of db++, but this extension doesn't support it (yet).

安装

In order to build this extension yourself you need the db++ client libraries and header files to be installed on your system (these are included in the db++ installation archives by default). You have to run configure with option --with-dbplus to build this extension.

configure looks for the client libraries and header files under the default paths /usr/dbplus, /usr/local/dbplus and /opt/dblus. If you have installed db++ in a different place you have add the installation path to the configure option like this: --with-dbplus=/your/installation/path.

运行时配置

本扩展模块在 php.ini 中未定义任何配置选项。

资源类型

dbplus_relation

Most db++ functions operate on or return dbplus_relation resources. A dbplus_relation is a handle to a stored relation or a relation generated as the result of a query.

预定义常量

以下常量由本扩展模块定义，因此只有在本扩展模块被编译到 PHP 中，或者在运行时被动态加载后才有效。

db++ error codes

表格 1. DB++ Error Codes

PHP Constant	db++ constant	meaning
`DBPLUS_ERR_NOERR` (integer)	ERR_NOERR	Null error condition
`DBPLUS_ERR_DUPLICATE` (integer)	ERR_DUPLICATE	Tried to insert a duplicate tuple
`DBPLUS_ERR_EOSCAN` (integer)	ERR_EOSCAN	End of scan from rget()
`DBPLUS_ERR_EMPTY` (integer)	ERR_EMPTY	Relation is empty (server)
`DBPLUS_ERR_CLOSE` (integer)	ERR_CLOSE	The server can't close
`DBPLUS_ERR_WLOCKED` (integer)	ERR_WLOCKED	The record is write locked
`DBPLUS_ERR_LOCKED` (integer)	ERR_LOCKED	Relation was already locked
`DBPLUS_ERR_NOLOCK` (integer)	ERR_NOLOCK	Relation cannot be locked
`DBPLUS_ERR_READ` (integer)	ERR_READ	Read error on relation
`DBPLUS_ERR_WRITE` (integer)	ERR_WRITE	Write error on relation
`DBPLUS_ERR_CREATE` (integer)	ERR_CREATE	Create() system call failed
`DBPLUS_ERR_LSEEK` (integer)	ERR_LSEEK	Lseek() system call failed
`DBPLUS_ERR_LENGTH` (integer)	ERR_LENGTH	Tuple exceeds maximum length
`DBPLUS_ERR_OPEN` (integer)	ERR_OPEN	Open() system call failed
`DBPLUS_ERR_WOPEN` (integer)	ERR_WOPEN	Relation already opened for writing
`DBPLUS_ERR_MAGIC` (integer)	ERR_MAGIC	File is not a relation
`DBPLUS_ERR_VERSION` (integer)	ERR_VERSION	File is a very old relation
`DBPLUS_ERR_PGSIZE` (integer)	ERR_PGSIZE	Relation uses a different page size
`DBPLUS_ERR_CRC` (integer)	ERR_CRC	Invalid crc in the superpage
`DBPLUS_ERR_PIPE` (integer)	ERR_PIPE	Piped relation requires lseek()
`DBPLUS_ERR_NIDX` (integer)	ERR_NIDX	Too many secondary indices
`DBPLUS_ERR_MALLOC` (integer)	ERR_MALLOC	Malloc() call failed
`DBPLUS_ERR_NUSERS` (integer)	ERR_NUSERS	Error use of max users
`DBPLUS_ERR_PREEXIT` (integer)	ERR_PREEXIT	Caused by invalid usage
`DBPLUS_ERR_ONTRAP` (integer)	ERR_ONTRAP	Caused by a signal
`DBPLUS_ERR_PREPROC` (integer)	ERR_PREPROC	Error in the preprocessor
`DBPLUS_ERR_DBPARSE` (integer)	ERR_DBPARSE	Error in the parser
`DBPLUS_ERR_DBRUNERR` (integer)	ERR_DBRUNERR	Run error in db
`DBPLUS_ERR_DBPREEXIT` (integer)	ERR_DBPREEXIT	Exit condition caused by prexit() * procedure
`DBPLUS_ERR_WAIT` (integer)	ERR_WAIT	Wait a little (Simple only)
`DBPLUS_ERR_CORRUPT_TUPLE` (integer)	ERR_CORRUPT_TUPLE	A client sent a corrupt tuple
`DBPLUS_ERR_WARNING0` (integer)	ERR_WARNING0	The Simple routines encountered a non fatal error which was corrected
`DBPLUS_ERR_PANIC` (integer)	ERR_PANIC	The server should not really die but after a disaster send ERR_PANIC to all its clients
`DBPLUS_ERR_FIFO` (integer)	ERR_FIFO	Can't create a fifo
`DBPLUS_ERR_PERM` (integer)	ERR_PERM	Permission denied
`DBPLUS_ERR_TCL` (integer)	ERR_TCL	TCL_error
`DBPLUS_ERR_RESTRICTED` (integer)	ERR_RESTRICTED	Only two users
`DBPLUS_ERR_USER` (integer)	ERR_USER	An error in the use of the library by an application programmer
`DBPLUS_ERR_UNKNOWN` (integer)	ERR_UNKNOWN

目录
dbplus_add -- Add a tuple to a relation
dbplus_aql -- Perform AQL query
dbplus_chdir -- Get/Set database virtual current directory
dbplus_close -- Close a relation
dbplus_curr -- Get current tuple from relation
dbplus_errcode -- Get error string for given errorcode or last error
dbplus_errno -- Get error code for last operation
dbplus_find -- Set a constraint on a relation
dbplus_first -- Get first tuple from relation
dbplus_flush -- Flush all changes made on a relation
dbplus_freealllocks -- Free all locks held by this client
dbplus_freelock -- Release write lock on tuple
dbplus_freerlocks -- Free all tuple locks on given relation
dbplus_getlock -- Get a write lock on a tuple
dbplus_getunique -- Get an id number unique to a relation
dbplus_info -- Get information about a relation
dbplus_last -- Get last tuple from relation
dbplus_lockrel -- Request write lock on relation
dbplus_next -- Get next tuple from relation
dbplus_open -- Open relation file
dbplus_prev -- Get previous tuple from relation
dbplus_rchperm -- Change relation permissions
dbplus_rcreate -- Creates a new DB++ relation
dbplus_rcrtexact -- Creates an exact but empty copy of a relation including indices
dbplus_rcrtlike -- Creates an empty copy of a relation with default indices
dbplus_resolve -- Resolve host information for relation
dbplus_restorepos -- Restore position
dbplus_rkeys -- Specify new primary key for a relation
dbplus_ropen -- Open relation file local
dbplus_rquery -- Perform local (raw) AQL query
dbplus_rrename -- Rename a relation
dbplus_rsecindex -- Create a new secondary index for a relation
dbplus_runlink -- Remove relation from filesystem
dbplus_rzap -- Remove all tuples from relation
dbplus_savepos -- Save position
dbplus_setindex -- Set index
dbplus_setindexbynumber -- Set index by number
dbplus_sql -- Perform SQL query
dbplus_tcl -- Execute TCL code on server side
dbplus_tremove -- Remove tuple and return new current tuple
dbplus_undo -- Undo
dbplus_undoprepare -- Prepare undo
dbplus_unlockrel -- Give up write lock on relation
dbplus_unselect -- Remove a constraint from relation
dbplus_update -- Update specified tuple in relation
dbplus_xlockrel -- Request exclusive lock on relation
dbplus_xunlockrel -- Free exclusive lock on relation

dbplus_add

(4.1.0 - 4.2.3 only, PECL)

dbplus_add -- Add a tuple to a relation

Description

int dbplus_add ( resource relation, array tuple )

警告

This function will add a tuple to a relation. The tuple data is an array of attribute/value pairs to be inserted into the given relation. After successful execution the tuple array will contain the complete data of the newly created tuple, including all implicitly set domain fields like sequences.

The function will return zero (aka. DBPLUS_ERR_NOERR) on success or a db++ error code on failure. See dbplus_errcode() or the introduction to this chapter for more information on db++ error codes.

dbplus_aql

(4.1.0 - 4.2.3 only, PECL)

dbplus_aql -- Perform AQL query

Description

resource dbplus_aql ( string query [, string server [, string dbpath]] )

警告

dbplus_aql() will execute an AQL query on the given server and dbpath.

On success it will return a relation handle. The result data may be fetched from this relation by calling dbplus_next() and dbplus_current(). Other relation access functions will not work on a result relation.

Further information on the AQL A... Query Language is provided in the original db++ manual.

dbplus_chdir

(4.1.0 - 4.2.3 only, PECL)

dbplus_chdir -- Get/Set database virtual current directory

Description

string dbplus_chdir ( [string newdir] )

警告

dbplus_chdir() will change the virtual current directory where relation files will be looked for by dbplus_open(). dbplus_chdir() will return the absolute path of the current directory. Calling dbplus_chdir() without giving any newdir may be used to query the current working directory.

dbplus_close

(4.1.0 - 4.2.3 only, PECL)

dbplus_close -- Close a relation

Description

mixed dbplus_close ( resource relation )

resource dbplus_open ( string name )

string dbplus_tcl ( int sid, string script )

int dbplus_xunlockrel ( resource relation )

警告

dbplus_xunlockrel() will release an exclusive lock on relation previously obtained by dbplus_xlockrel().

XXIV. dBase Functions

简介

These functions allow you to access records stored in dBase-format (dbf) databases.

dBase files are simple sequential files of fixed length records. Records are appended to the end of the file and delete records are kept until you call dbase_pack().

The types of dBase fields available are:

表格 1. Available types of fields

Field	dBase Type	Format	Additional informations
`M`	Memo	n/a	This type is not supported by PHP, such field will be ignored
`D`	Date	`YYYYMMDD`	The field length is limited to 8
`N`	Number	A number	You must declare a length and a precision (the number of digits after the decimal point)
`C`	String	A string	You must declare a length. When retrieving data, the string will be right-padded with spaces to fit the declared length.
`L`	Boolean	`T` or `Y` for `TRUE`, `F` or `N` for `FALSE`	Stored and returned as an integer (1 or 0)

警告

There is no support for indexes or memo fields. There is no support for locking, too. Two concurrent webserver processes modifying the same dBase file will very likely ruin your database.

We recommend that you do not use dBase files as your production database. Choose any real SQL server instead; MySQL or Postgres are common choices with PHP. dBase support is here to allow you to import and export data to and from your web database, because the file format is commonly understood by Windows spreadsheets and organizers.

安装

In order to enable the bundled dbase library and to use these functions, you must compile PHP with the --enable-dbase option.

运行时配置

本扩展模块在 php.ini 中未定义任何配置选项。

资源类型

本扩展模块未定义任何资源类型。

范例

Many examples in this reference require a dBase database. We will use /tmp/test.dbf that will be created in the example of dbase_create().

预定义常量

本扩展模块未定义任何常量。

目录
dbase_add_record -- Adds a record to a database
dbase_close -- Closes a database
dbase_create -- Creates a database
dbase_delete_record -- Deletes a record from a database
dbase_get_header_info -- Gets the header info of a database
dbase_get_record_with_names -- Gets a record from a database as an associative array
dbase_get_record -- Gets a record from a database as an indexed array
dbase_numfields -- Gets the number of fields of a database
dbase_numrecords -- Gets the number of records in a database
dbase_open -- Opens a database
dbase_pack -- Packs a database
dbase_replace_record -- Replaces a record in a database

dbase_add_record

(PHP 3, PHP 4, PHP 5)

dbase_add_record -- Adds a record to a database

说明

bool dbase_add_record ( int dbase_identifier, array record )

Adds the given data to the database.

参数

dbase_identifier: The database link identifier, returned by dbase_open() or dbase_create().
record: An indexed array of data. The number of items must be equal to the number of fields in the database, otherwise dbase_add_record() will fail.
注: If you're using dbase_get_record() return value for this parameter, remember to reset the key named deleted.

返回值

如果成功则返回 TRUE，失败则返回 FALSE。

范例

例子 1. Inserting a record in a dBase database
<?php // open in read-write mode $db = dbase_open('/tmp/test.dbf', 2); if ($db) { dbase_add_record($db, array( date('Ymd'), 'Maxim Topolov', '23', 'max@example.com', 'T')); dbase_close($db); } ?>

参见

dbase_delete_record()

dbase_replace_record()

dbase_close

(PHP 3, PHP 4, PHP 5)

dbase_close -- Closes a database

说明

bool dbase_close ( int dbase_identifier )

Closes the given database link identifier.

参数

dbase_identifier: The database link identifier, returned by dbase_open() or dbase_create().

返回值

如果成功则返回 TRUE，失败则返回 FALSE。

范例

例子 1. Closing a dBase database file
<?php // open in read-only mode $db = dbase_open('/tmp/test.dbf', 0); if ($db) { // read some data .. dbase_close($db); } ?>

参见

dbase_open()

dbase_create()

dbase_create

(PHP 3, PHP 4, PHP 5)

dbase_create -- Creates a database

说明

int dbase_create ( string filename, array fields )

dbase_create() creates a dBase database with the given definition.

注: 当安全模式被激活时，PHP 将检查被操作的文件或者目录是否与正在执行的脚本有相同的 UID（所有者）。

注: 本函数受 open_basedir 的影响。

参数

filename: The name of the database. It can be a relative or absolute path to the file where dBase will store your data.
fields: An array of arrays, each array describing the format of one field of the database. Each field consists of a name, a character indicating the field type, and optionally, a length, and a precision.
注: The fieldnames are limited in length and must not exceed 10 chars.

返回值

Returns a database link identifier if the database is successfully created, or FALSE if an error occurred.

范例

例子 1. Creating a dBase database file
<?php // database "definition" $def = array( array("date", "D"), array("name", "C", 50), array("age", "N", 3, 0), array("email", "C", 128), array("ismember", "L") ); // creation if (!dbase_create('/tmp/test.dbf', $def)) { echo "Error, can't create the database\n"; } ?>

参见

dbase_open()

dbase_close()

dbase_delete_record

(PHP 3, PHP 4, PHP 5)

dbase_delete_record -- Deletes a record from a database

说明

bool dbase_delete_record ( int dbase_identifier, int record_number )

Marks the given record to be deleted from the database.

注: To actually remove the record from the database, you must also call dbase_pack().

参数

dbase_identifier: The database link identifier, returned by dbase_open() or dbase_create().
record_number: An integer which spans from 1 to the number of records in the database (as returned by dbase_numrecords()).

返回值

如果成功则返回 TRUE，失败则返回 FALSE。

参见

dbase_add_record()

dbase_replace_record()

dbase_get_header_info

(PHP 5)

dbase_get_header_info -- Gets the header info of a database

说明

array dbase_get_header_info ( int dbase_identifier )

Returns information on the column structure of the given database link identifier.

参数

dbase_identifier: The database link identifier, returned by dbase_open() or dbase_create().

返回值

An indexed array with an entry for each column in the database. The array index starts at 0.

Each array element contains an associative array of column information, as described here:

name: The name of the column
type: The human-readable name for the dbase type of the column (i.e. date, boolean, etc.)
length: The number of bytes this column can hold
precision: The number of digits of decimal precision for the column
format: A suggested printf() format specifier for the column
offset: The byte offset of the column from the start of the row

If the database header information cannot be read, FALSE is returned.

范例

例子 1. Showing header information for a dBase database file
<?php // Path to dbase file $db_path = "/tmp/test.dbf"; // Open dbase file $dbh = dbase_open($db_path, 0) or die("Error! Could not open dbase database file '$db_path'."); // Get column information $column_info = dbase_get_header_info($dbh); // Display information print_r($column_info); ?>

dbase_get_record_with_names

(PHP 3 >= 3.0.4, PHP 4, PHP 5)

dbase_get_record_with_names -- Gets a record from a database as an associative array

说明

array dbase_get_record_with_names ( int dbase_identifier, int record_number )

Gets a record from a dBase database as an associative array.

参数

dbase_identifier: The database link identifier, returned by dbase_open() or dbase_create().
record_number: The index of the record.

返回值

An associative array with the record. This will also include a key named deleted which is set to 1 if the record has been marked for deletion (see dbase_delete_record()).

Each field is converted to the appropriate PHP type, except:

Dates are left as strings.
Integers that would have caused an overflow (> 32 bits) are returned as strings.

On error, dbase_get_record_with_names() will return FALSE.

范例

例子 1. Listing all the registered members in the database
<?php // open in read-only mode $db = dbase_open('/tmp/test.dbf', 0); if ($db) { $record_numbers = dbase_numrecords($db); for ($i = 1; $i <= $record_numbers; $i++) { $row = dbase_get_record_with_names($db, $i); if ($row['ismember'] == 1) { echo "Member #$i: " . trim($row['name']) . "\n"; } } } ?>

参见

dbase_get_record()

dbase_get_record

(PHP 3, PHP 4, PHP 5)

dbase_get_record -- Gets a record from a database as an indexed array

说明

array dbase_get_record ( int dbase_identifier, int record_number )

Gets a record from a database as an indexed array.

参数

dbase_identifier: The database link identifier, returned by dbase_open() or dbase_create().
record_number: The index of the record.

返回值

An indexed array with the record. This array will also include an associative key named deleted which is set to 1 if the record has been marked for deletion (see dbase_delete_record()).

Each field is converted to the appropriate PHP type, except:

Dates are left as strings.
Integers that would have caused an overflow (> 32 bits) are returned as strings.

On error, dbase_get_record() will return FALSE.

参见

dbase_get_record_with_names()

dbase_numfields

(PHP 3, PHP 4, PHP 5)

dbase_numfields -- Gets the number of fields of a database

说明

int dbase_numfields ( int dbase_identifier )

Gets the number of fields (columns) in the specified database.

注: Field numbers are between 0 and dbase_numfields($db)-1, while record numbers are between 1 and dbase_numrecords($db).

参数

dbase_identifier: The database link identifier, returned by dbase_open() or dbase_create().

返回值

The number of fields in the database, or FALSE if an error occurs.

范例

例子 1. dbase_numfields() Example
<?php $rec = dbase_get_record($db, $recno); $nf = dbase_numfields($db); for ($i = 0; $i < $nf; $i++) { echo $rec[$i], "\n"; } ?>

参见

dbase_numrecords()

dbase_numrecords

(PHP 3, PHP 4, PHP 5)

dbase_numrecords -- Gets the number of records in a database

说明

int dbase_numrecords ( int dbase_identifier )

Gets the number of records (rows) in the specified database.

注: Record numbers are between 1 and dbase_numrecords($db), while field numbers are between 0 and dbase_numfields($db)-1.

参数

dbase_identifier: The database link identifier, returned by dbase_open() or dbase_create().

返回值

The number of records in the database, or FALSE if an error occurs.

范例

例子 1. Looping over all the records of the database
<?php // open in read-only mode $db = dbase_open('/tmp/test.dbf', 0); if ($db) { $record_numbers = dbase_numrecords($db); for ($i = 1; $i <= $record_numbers; $i++) { // do something here, for each record } } ?>

参见

dbase_num_fields()

dbase_open

(PHP 3, PHP 4, PHP 5)

dbase_open -- Opens a database

说明

int dbase_open ( string filename, int mode )

dbase_open() opens a dBase database with the given access mode.

注: 当安全模式被激活时，PHP 将检查被操作的文件或者目录是否与正在执行的脚本有相同的 UID（所有者）。

注: 本函数受 open_basedir 的影响。

参数

filename: The name of the database. It can be a relative or absolute path to the file where dBase will store your data.
mode: An integer which correspond to those for the open() system call (Typically 0 means read-only, 1 means write-only, and 2 means read and write).
注: You can't open a dBase file in write-only mode as the function will fail to read the headers information and thus you can't use 1 as mode.

范例

例子 1. Opening a dBase database file
<?php // open in read-only mode $db = dbase_open('/tmp/test.dbf', 0); if ($db) { // read some data .. dbase_close($db); } ?>

返回值

Returns a database link identifier if the database is successfully opened, or FALSE if an error occurred.

参见

dbase_create()

dbase_close()

dbase_pack

(PHP 3, PHP 4, PHP 5)

dbase_pack -- Packs a database

说明

bool dbase_pack ( int dbase_identifier )

Packs the specified database by permanently deleting all records marked for deletion using dbase_delete_record().

参数

dbase_identifier: The database link identifier, returned by dbase_open() or dbase_create().

返回值

如果成功则返回 TRUE，失败则返回 FALSE。

范例

例子 1. Emptying a dBase database
<?php // open in read-write mode $db = dbase_open('/tmp/test.dbf', 2); if ($db) { $record_numbers = dbase_numrecords($db); for ($i = 1; $i <= $record_numbers; $i++) { dbase_delete_record($db, $i); } // expunge the database dbase_pack($db); } ?>

参见

dbase_delete_record()

dbase_replace_record

(PHP 3 >= 3.0.11, PHP 4, PHP 5)

dbase_replace_record -- Replaces a record in a database

说明

bool dbase_replace_record ( int dbase_identifier, array record, int record_number )

Replaces the given record in the database with the given data.

参数

dbase_identifier: The database link identifier, returned by dbase_open() or dbase_create().
record: An indexed array of data. The number of items must be equal to the number of fields in the database, otherwise dbase_add_record() will fail.
注: If you're using dbase_get_record() return value for this parameter, remember to reset the key named deleted.
record_number: An integer which spans from 1 to the number of records in the database (as returned by dbase_numrecords()).

返回值

如果成功则返回 TRUE，失败则返回 FALSE。

范例

例子 1. Updating a record in the database
<?php // open in read-write mode $db = dbase_open('/tmp/test.dbf', 2); if ($db) { // gets the old row $row = dbase_get_record_with_names($db, 1); // remove the 'deleted' entry unset($row['deleted']); // Update the date field with the current timestamp $row['date'] = date('Ymd'); // Replace the record dbase_replace_record($db, $row, 1); dbase_close($db); } ?>

参见

dbase_add_record()

dbase_delete_record()

XXV. DBM Functions [deprecated]

简介

These functions allow you to store records stored in a dbm-style database. This type of database (supported by the Berkeley DB, GDBM, and some system libraries, as well as a built-in flatfile library) stores key/value pairs (as opposed to the full-blown records supported by relational databases).

注: However, dbm support is deprecated and you are encouraged to use the Database (dbm-style) abstraction layer functions instead.

需求

To use this functions you have to compile PHP with support for an underlying database. See the list of supported Databases.

安装

In order to use these functions, you must compile PHP with dbm support by using the --with-db option. In addition you must ensure support for an underlying database or you can use some system libraries.

运行时配置

本扩展模块在 php.ini 中未定义任何配置选项。

资源类型

The function dbmopen() returns an database identifier which is used by the other dbm-functions.

预定义常量

本扩展模块未定义任何常量。

范例

例子 1. DBM example
<?php $dbm = dbmopen("lastseen", "w"); if (dbmexists($dbm, $userid)) { $last_seen = dbmfetch($dbm, $userid); } else { dbminsert($dbm, $userid, time()); } do_stuff(); dbmreplace($dbm, $userid, time()); dbmclose($dbm); ?>

目录
dblist -- Describes the DBM-compatible library being used
dbmclose -- Closes a dbm database
dbmdelete -- Deletes the value for a key from a DBM database
dbmexists -- Tells if a value exists for a key in a DBM database
dbmfetch -- Fetches a value for a key from a DBM database
dbmfirstkey -- Retrieves the first key from a DBM database
dbminsert -- Inserts a value for a key in a DBM database
dbmnextkey -- Retrieves the next key from a DBM database
dbmopen -- Opens a DBM database
dbmreplace -- Replaces the value for a key in a DBM database

Adds the value to the database with the specified key.

Returns -1 if the database was opened read-only, 0 if the insert was successful, and 1 if the specified key already exists. (To replace the value, use dbmreplace().)

dbmnextkey

int dbmreplace ( resource dbm_identifier, string key, string value )

Replaces the value for the specified key in the database.

This will also add the key to the database if it didn't already exist.

XXVI. dbx Functions

简介

The dbx module is a database abstraction layer (db 'X', where 'X' is a supported database). The dbx functions allow you to access all supported databases using a single calling convention. The dbx-functions themselves do not interface directly to the databases, but interface to the modules that are used to support these databases.

注: 本扩展已被移动到 PECL 库中且自以下版本起不再被绑定到 PHP 中：5.1.0.

需求

To be able to use a database with the dbx-module, the module must be either linked or loaded into PHP, and the database module must be supported by the dbx-module. Currently, the following databases are supported, but others will follow:

FrontBase (available from PHP 4.1.0).
Microsoft SQL Server
MySQL
ODBC
PostgreSQL
Sybase-CT (available from PHP 4.2.0).
Oracle (oci8) (available from PHP 4.3.0).
SQLite (PHP 5).

Documentation for adding additional database support to dbx can be found at http://www.guidance.nl/php/dbx/doc/.

安装

In order to have these functions available, you must compile PHP with dbx support by using the --enable-dbx option and all options for the databases that will be used, e.g. for MySQL you must also specify --with-mysql=[DIR]. To get other supported databases to work with the dbx-module refer to their specific documentation.

运行时配置

这些函数的行为受 php.ini 的影响。

表格 1. DBX Configuration Options

Name	Default	Changeable	Changelog
dbx.colnames_case	"unchanged"	PHP_INI_SYSTEM	Available since PHP 4.3.0.

有关 PHP_INI_* 常量进一步的细节与定义参见附录 G。

以下是配置选项的简要解释。

dbx.colnames_case string: Columns names can be returned "unchanged" or converted to "uppercase" or "lowercase". This directive can be overridden with a flag to dbx_query().

资源类型

There are two resource types used in the dbx module. The first one is the link-object for a database connection, the second a result-object which holds the result of a query.

预定义常量

以下常量由本扩展模块定义，因此只有在本扩展模块被编译到 PHP 中，或者在运行时被动态加载后才有效。

DBX_MYSQL (integer)
DBX_ODBC (integer)
DBX_PGSQL (integer)
DBX_MSSQL (integer)
DBX_FBSQL (integer)
DBX_OCI8 (integer) (available from PHP 4.3.0)
DBX_SYBASECT (integer)
DBX_SQLITE (integer) (PHP 5)
DBX_PERSISTENT (integer)
DBX_RESULT_INFO (integer)
DBX_RESULT_INDEX (integer)
DBX_RESULT_ASSOC (integer)
DBX_RESULT_UNBUFFERED (integer) (PHP 5)
DBX_COLNAMES_UNCHANGED (integer) (available from PHP 4.3.0)
DBX_COLNAMES_UPPERCASE (integer) (available from PHP 4.3.0)
DBX_COLNAMES_LOWERCASE (integer) (available from PHP 4.3.0)
DBX_CMP_NATIVE (integer)
DBX_CMP_TEXT (integer)
DBX_CMP_NUMBER (integer)
DBX_CMP_ASC (integer)
DBX_CMP_DESC (integer)

目录
dbx_close -- Close an open connection/database
dbx_compare -- Compare two rows for sorting purposes
dbx_connect -- Open a connection/database
dbx_error -- Report the error message of the latest function call in the module (not just in the connection)
dbx_escape_string -- Escape a string so it can safely be used in an sql-statement
dbx_fetch_row -- Fetches rows from a query-result that had the DBX_RESULT_UNBUFFERED flag set
dbx_query -- Send a query and fetch all results (if any)
dbx_sort -- Sort a result from a dbx_query by a custom sort function

dbx_close

(PHP 4 >= 4.0.6, PHP 5 <= 5.0.4)

dbx_close -- Close an open connection/database

Description

bool dbx_close ( object link_identifier )

如果成功则返回 TRUE，失败则返回 FALSE。

例子 1. dbx_close() example

<?php
$link = dbx_connect(DBX_MYSQL, "localhost", "db", "username", "password")
    or die("Could not connect");

echo "Connected successfully";
dbx_close($link);
?>

注: Always refer to the module-specific documentation as well.

dbx_compare

(PHP 4 >= 4.1.0, PHP 5 <= 5.0.4)

dbx_compare -- Compare two rows for sorting purposes

Description

int dbx_compare ( array row_a, array row_b, string column_key [, int flags] )

dbx_compare() returns 0 if the row_a[$column_key] is equal to row_b[$column_key], and 1 or -1 if the former is greater or is smaller than the latter one, respectively, or vice versa if the flag is set to DBX_CMP_DESC. dbx_compare() is a helper function for dbx_sort() to ease the make and use of the custom sorting function.

The flags can be set to specify comparison direction:

DBX_CMP_ASC - ascending order
DBX_CMP_DESC - descending order

and the preferred comparison type:

DBX_CMP_NATIVE - no type conversion
DBX_CMP_TEXT - compare items as strings
DBX_CMP_NUMBER - compare items numerically

One of the direction and one of the type constant can be combined with bitwise OR operator (|). The default value for the flags parameter is DBX_CMP_ASC | DBX_CMP_NATIVE.

例子 1. dbx_compare() example

<?php
function user_re_order($a, $b) 
{
    $rv = dbx_compare($a, $b, "parentid", DBX_CMP_DESC);
    if (!$rv) {
        $rv = dbx_compare($a, $b, "id", DBX_CMP_NUMBER);
    }
    return $rv;
}

$link   = dbx_connect(DBX_ODBC, "", "db", "username", "password")
    or die("Could not connect");

$result = dbx_query($link, "SELECT id, parentid, description FROM table ORDER BY id");
    // data in $result is now ordered by id

dbx_sort($result, "user_re_order");
    // date in $result is now ordered by parentid (descending), then by id

dbx_close($link);
?>

dbx_connect

(PHP 4 >= 4.0.6, PHP 5 <= 5.0.4)

dbx_connect -- Open a connection/database

Description

object dbx_connect ( mixed module, string host, string database, string username, string password [, int persistent] )

dbx_connect() returns an object on success, FALSE on error. If a connection has been made but the database could not be selected, the connection is closed and FALSE is returned. The persistent parameter can be set to DBX_PERSISTENT, if so, a persistent connection will be created.

The module parameter can be either a string or a constant, though the latter form is preferred. The possible values are given below, but keep in mind that they only work if the module is actually loaded.

DBX_MYSQL or "mysql"
DBX_ODBC or "odbc"
DBX_PGSQL or "pgsql"
DBX_MSSQL or "mssql"
DBX_FBSQL or "fbsql" (available from PHP 4.1.0)
DBX_SYBASECT or "sybase_ct" (available from PHP 4.2.0)
DBX_OCI8 or "oci8" (available from PHP 4.3.0)
DBX_SQLITE or "sqlite" (PHP 5)

The host, database, username and password parameters are expected, but not always used depending on the connect functions for the abstracted module.

The returned object has three properties:

database

It is the name of the currently selected database.

handle

It is a valid handle for the connected database, and as such it can be used in module-specific functions (if required).

<?php
$link = dbx_connect(DBX_MYSQL, "localhost", "db", "username", "password");
mysql_close($link->handle); // dbx_close($link) would be better here
?>

module

It is used internally by dbx only, and is actually the module number mentioned above.

例子 1. dbx_connect() example
<?php $link = dbx_connect(DBX_ODBC, "", "db", "username", "password", DBX_PERSISTENT) or die("Could not connect"); echo "Connected successfully"; dbx_close($link); ?>

注: Always refer to the module-specific documentation as well.

dbx_error

(PHP 4 >= 4.0.6, PHP 5 <= 5.0.4)

dbx_error -- Report the error message of the latest function call in the module (not just in the connection)

Description

string dbx_error ( object link_identifier )

dbx_error() returns a string containing the error message from the last function call of the abstracted module (e.g. mysql module). If there are multiple connections in the same module, just the last error is given. If there are connections on different modules, the latest error is returned for the module specified by the link_identifier parameter.

例子 1. dbx_error() example

<?php
$link   = dbx_connect(DBX_MYSQL, "localhost", "db", "username", "password")
    or die("Could not connect");

$result = dbx_query($link, "select id from non_existing_table");
if ($result == 0) {
    echo dbx_error($link);
}
dbx_close($link);
?>

注: Always refer to the module-specific documentation as well.
The error message for Microsoft SQL Server is actually the result of the mssql_get_last_message() function.
The error message for Oracle (oci8) is not implemented (yet).

dbx_escape_string

(PHP 4 >= 4.3.0, PHP 5 <= 5.0.4)

dbx_escape_string -- Escape a string so it can safely be used in an sql-statement

Description

string dbx_escape_string ( object link_identifier, string text )

dbx_escape_string() returns the text, escaped where necessary (such as quotes, backslashes etc). It returns NULL on error.

例子 1. dbx_escape_string() example

<?php
$link   = dbx_connect(DBX_MYSQL, "localhost", "db", "username", "password")
    or die("Could not connect");

$text = dbx_escape_string($link, "It\'s quoted and backslashed (\\).");
$result = dbx_query($link, "insert into tbl (txt) values ('" . $text . "')");
if ($result == 0) {
    echo dbx_error($link);
}
dbx_close($link);
?>

dbx_fetch_row

(PHP 5 <= 5.0.4)

dbx_fetch_row -- Fetches rows from a query-result that had the DBX_RESULT_UNBUFFERED flag set

Description

mixed dbx_fetch_row ( object result_identifier )

dbx_fetch_row() returns a row on success, and 0 on failure (e.g. when no more rows are available). When the DBX_RESULT_UNBUFFERED is not set in the query, dbx_fetch_row() will fail as all rows have already been fetched into the results data property.

As a side effect, the rows property of the query-result object is incremented for each successful call to dbx_fetch_row().

例子 1. How to handle the returned value

<?php
$result = dbx_query($link, 'SELECT id, parentid, description FROM table', DBX_RESULT_UNBUFFERED);

echo "<table>\n";
while ($row = dbx_fetch_row($result)) {
    echo "<tr>\n";
    foreach ($row as $field) {
        echo "<td>$field</td>";
    }
    echo "</tr>\n";
}
echo "</table>\n";
?>

The result_identifier parameter is the result object returned by a call to dbx_query().

The returned object contains the same information as any row would have in the dbx_query result data property, including columns accessible by index or fieldname when the flags for dbx_guery were set that way.

dbx_query

(PHP 4 >= 4.0.6, PHP 5 <= 5.0.4)

dbx_query -- Send a query and fetch all results (if any)

Description

mixed dbx_query ( object link_identifier, string sql_statement [, int flags] )

dbx_query() returns an object or 1 on success, and 0 on failure. The result object is returned only if the query given in sql_statement produces a result set (i.e. a SELECT query, even if the result set is empty).

例子 1. How to handle the returned value

<?php
$link   = dbx_connect(DBX_ODBC, "", "db", "username", "password")
    or die("Could not connect");

$result = dbx_query($link, 'SELECT id, parentid, description FROM table');

if (is_object($result) ) {
    // ... do some stuff here, see detailed examples below ...
    // first, print out field names and types 
    // then, draw a table filled with the returned field values
} else {
    exit("Query failed");
}

dbx_close($link);
?>

The flags parameter is used to control the amount of information that is returned. It may be any combination of the following constants with the bitwise OR operator (|). The DBX_COLNAMES_* flags override the dbx.colnames_case setting from php.ini.

DBX_RESULT_INDEX

It is always set, that is, the returned object has a data property which is a 2 dimensional array indexed numerically. For example, in the expression data[2][3] 2 stands for the row (or record) number and 3 stands for the column (or field) number. The first row and column are indexed at 0.

If DBX_RESULT_ASSOC is also specified, the returning object contains the information related to DBX_RESULT_INFO too, even if it was not specified.

DBX_RESULT_INFO

It provides info about columns, such as field names and field types.

DBX_RESULT_ASSOC

It effects that the field values can be accessed with the respective column names used as keys to the returned object's data property.

Associated results are actually references to the numerically indexed data, so modifying data[0][0] causes that data[0]['field_name_for_first_column'] is modified as well.

DBX_RESULT_UNBUFFERED (PHP 5)

This flag will not create the data property, and the rows property will initially be 0. Use this flag for large datasets, and use dbx_fetch_row() to retrieve the results row by row.

The dbx_fetch_row() function will return rows that are conformant to the flags set with this query. Incidentally, it will also update the rows each time it is called.

DBX_COLNAMES_UNCHANGED (available from PHP 4.3.0)

The case of the returned column names will not be changed.

DBX_COLNAMES_UPPERCASE (available from PHP 4.3.0)

The case of the returned column names will be changed to uppercase.

DBX_COLNAMES_LOWERCASE (available from PHP 4.3.0)

The case of the returned column names will be changed to lowercase.

Note that DBX_RESULT_INDEX is always used, regardless of the actual value of flags parameter. This means that only the following combinations are effective:

DBX_RESULT_INDEX
DBX_RESULT_INDEX | DBX_RESULT_INFO
DBX_RESULT_INDEX | DBX_RESULT_INFO | DBX_RESULT_ASSOC - this is the default, if flags is not specified.

The returned object has four or five properties depending on flags:

handle

It is a valid handle for the connected database, and as such it can be used in module specific functions (if required).

<?php
$result = dbx_query($link, "SELECT id FROM table");
mysql_field_len($result->handle, 0);
?>

cols and rows

These contain the number of columns (or fields) and rows (or records) respectively.

<?php
$result = dbx_query($link, 'SELECT id FROM table');
echo $result->rows; // number of records
echo $result->cols; // number of fields 
?>

info (optional)

It is returned only if either DBX_RESULT_INFO or DBX_RESULT_ASSOC is specified in the flags parameter. It is a 2 dimensional array, that has two named rows (name and type) to retrieve column information.

例子 2. lists each field's name and type

<?php
$result = dbx_query($link, 'SELECT id FROM table',
                     DBX_RESULT_INDEX | DBX_RESULT_INFO);

for ($i = 0; $i < $result->cols; $i++ ) {
    echo $result->info['name'][$i] . "\n";
    echo $result->info['type'][$i] . "\n";  
}
?>

data

This property contains the actual resulting data, possibly associated with column names as well depending on flags. If DBX_RESULT_ASSOC is set, it is possible to use $result->data[2]["field_name"].

例子 3. outputs the content of data property into HTML table

<?php
$result = dbx_query($link, 'SELECT id, parentid, description FROM table');

echo "<table>\n";
foreach ($result->data as $row) {
    echo "<tr>\n";
    foreach ($row as $field) {
        echo "<td>$field</td>";
    }
    echo "</tr>\n";
}
echo "</table>\n";
?>

例子 4. How to handle UNBUFFERED queries

<?php

$result = dbx_query ($link, 'SELECT id, parentid, description FROM table', DBX_RESULT_UNBUFFERED);

echo "<table>\n";
while ($row = dbx_fetch_row($result)) {
    echo "<tr>\n";
    foreach ($row as $field) {
        echo "<td>$field</td>";
    }
    echo "</tr>\n";
}
echo "</table>\n";

?>

注: Always refer to the module-specific documentation as well.
Column names for queries on an Oracle database are returned in lowercase.

dbx_sort

(PHP 4 >= 4.0.6, PHP 5 <= 5.0.4)

dbx_sort -- Sort a result from a dbx_query by a custom sort function

Description

bool dbx_sort ( object result, string user_compare_function )

如果成功则返回 TRUE，失败则返回 FALSE。

注: It is always better to use ORDER BY SQL clause instead of dbx_sort(), if possible.

例子 1. dbx_sort() example

<?php
function user_re_order($a, $b) 
{
    $rv = dbx_compare($a, $b, "parentid", DBX_CMP_DESC);
    if (!$rv) {
        $rv = dbx_compare($a, $b, "id", DBX_CMP_NUMBER);
    }
    return $rv;
}

$link   = dbx_connect(DBX_ODBC, "", "db", "username", "password")
    or die("Could not connect");

$result = dbx_query($link, "SELECT id, parentid, description FROM tbl ORDER BY id");
    // data in $result is now ordered by id

dbx_sort($result, "user_re_order");
    // data in $result is now ordered by parentid (descending), then by id

dbx_close($link);
?>

XXVII. Direct IO Functions

简介

PHP supports the direct io functions as described in the Posix Standard (Section 6) for performing I/O functions at a lower level than the C-Language stream I/O functions (fopen(), fread(),..). The use of the DIO functions should be considered only when direct control of a device is needed. In all other cases, the standard filesystem functions are more than adequate.

注: 本扩展已被移动到 PECL 库中且自以下版本起不再被绑定到 PHP 中：5.1.0.

This extension is only available on Windows Platforms as of PHP 5.0.0

需求

要编译本扩展模块不需要外部库文件。

安装

To get these functions to work, you have to configure PHP with --enable-dio.

预定义常量

以下常量由本扩展模块定义，因此只有在本扩展模块被编译到 PHP 中，或者在运行时被动态加载后才有效。

c (integer)
F_DUPFD (integer)
F_GETFD (integer)
F_GETFL (integer)
F_GETLK (integer)
F_GETOWN (integer)
F_RDLCK (integer)
F_SETFL (integer)
F_SETLK (integer)
F_SETLKW (integer)
F_SETOWN (integer)
F_UNLCK (integer)
F_WRLCK (integer)
O_APPEND (integer)
O_ASYNC (integer)
O_CREAT (integer)
O_EXCL (integer)
O_NDELAY (integer)
O_NOCTTY (integer)
O_NONBLOCK (integer)
O_RDONLY (integer)
O_RDWR (integer)
O_SYNC (integer)
O_TRUNC (integer)
O_WRONLY (integer)
S_IRGRP (integer)
S_IROTH (integer)
S_IRUSR (integer)
S_IRWXG (integer)
S_IRWXO (integer)
S_IRWXU (integer)
S_IWGRP (integer)
S_IWOTH (integer)
S_IWUSR (integer)
S_IXGRP (integer)
S_IXOTH (integer)
S_IXUSR (integer)

运行时配置

本扩展模块在 php.ini 中未定义任何配置选项。

资源类型

One resource type is defined by this extension: a file descriptor returned by dio_open().

目录
dio_close -- Closes the file descriptor given by fd
dio_fcntl -- Performs a c library fcntl on fd
dio_open -- Opens a new filename with specified permissions of flags and creation permissions of mode
dio_read -- Reads bytes from a file descriptor
dio_seek -- Seeks to pos on fd from whence
dio_stat -- Gets stat information about the file descriptor fd
dio_tcsetattr -- Sets terminal attributes and baud rate for a serial port
dio_truncate -- Truncates file descriptor fd to offset bytes
dio_write -- Writes data to fd with optional truncation at length

dio_close

(PHP 4 >= 4.2.0, PHP 5 <= 5.0.4)

dio_close -- Closes the file descriptor given by fd

说明

void dio_close ( resource fd )

The function dio_close() closes the file descriptor fd.

参数

fd: The file descriptor returned by dio_open().

返回值

无返回值。

范例

例子 1. Closing an open file descriptor
<?php $fd = dio_open('/dev/ttyS0', O_RDWR); dio_close($fd); ?>

参见

dio_open()

dio_fcntl

(PHP 4 >= 4.2.0, PHP 5 <= 5.0.4)

dio_fcntl -- Performs a c library fcntl on fd

说明

mixed dio_fcntl ( resource fd, int cmd [, mixed args] )

The dio_fcntl() function performs the operation specified by cmd on the file descriptor fd. Some commands require additional arguments args to be supplied.

注: 本函数未在 Windows 平台下实现。

参数

fd

The file descriptor returned by dio_open().

cmd

Can be one of the following operations:

F_SETLK - Lock is set or cleared. If the lock is held by someone else dio_fcntl() returns -1.
F_SETLKW - like F_SETLK, but in case the lock is held by someone else, dio_fcntl() waits until the lock is released.
F_GETLK - dio_fcntl() returns an associative array (as described above) if someone else prevents lock. If there is no obstruction key "type" will set to F_UNLCK.
F_DUPFD - finds the lowest numbered available file descriptor greater than or equal to args and returns them.
F_SETFL - Sets the file descriptors flags to the value specified by args, which can be O_APPEND, O_NONBLOCK or O_ASYNC. To use O_ASYNC you will need to use the PCNTL extension.

args

args is an associative array, when cmd is F_SETLK or F_SETLLW, with the following keys:

"start" - offset where lock begins
"length" - size of locked area. zero means to end of file
"wenth" - Where l_start is relative to: can be SEEK_SET, SEEK_END and SEEK_CUR
"type" - type of lock: can be F_RDLCK (read lock), F_WRLCK (write lock) or F_UNLCK (unlock)

返回值

Returns the result of the C call.

范例

例子 1. Setting and clearing a lock
<?php $fd = dio_open('/dev/ttyS0', O_RDWR); if (dio_fcntl($fd, F_SETLK, Array("type"=>F_WRLCK)) == -1) { // the file descriptor appears locked echo "The lock can not be cleared. It is held by someone else."; } else { echo "Lock succesfully set/cleared"; } dio_close($fd); ?>

dio_open

(PHP 4 >= 4.2.0, PHP 5 <= 5.0.4)

dio_open -- Opens a new filename with specified permissions of flags and creation permissions of mode

说明

resource dio_open ( string filename, int flags [, int mode] )

dio_open() opens a file and returns a new file descriptor for it.

参数

filename

The opened file.

flags

The flags parameter can also include any combination of the following flags:

O_CREAT - creates the file, if it doesn't already exist.
O_EXCL - if both, O_CREAT and O_EXCL are set, dio_open() fails, if the file already exists.
O_TRUNC - if the file exists, and its opened for write access, the file will be truncated to zero length.
O_APPEND - write operations write data at the end of the file.
O_NONBLOCK - sets non blocking mode.

mode

If flags is O_CREAT, mode will set the mode of the file (creation permissions).

O_RDONLY - opens the file for read access.
O_WRONLY - opens the file for write access.
O_RDWR - opens the file for both reading and writing.

返回值

A file descriptor or FALSE on error.

范例

例子 1. Opening a file descriptor

<?php

$fd = dio_open('/dev/ttyS0', O_RDWR | O_NOCTTY | O_NONBLOCK);

dio_close($fd);
?>

参见

dio_close()

dio_read

(PHP 4 >= 4.2.0, PHP 5 <= 5.0.4)

dio_read -- Reads bytes from a file descriptor

说明

string dio_read ( resource fd [, int len] )

The function dio_read() reads and returns len bytes from file with descriptor fd.

参数

fd: The file descriptor returned by dio_open().
len: The number of bytes to read. If not specified, dio_read() reads 1K sized block.

返回值

The bytes read from fd.

参见

dio_write()

dio_seek

(PHP 4 >= 4.2.0, PHP 5 <= 5.0.4)

dio_seek -- Seeks to pos on fd from whence

说明

int dio_seek ( resource fd, int pos [, int whence] )

The function dio_seek() is used to change the file position of the given file descriptor.

参数

fd

The file descriptor returned by dio_open().

pos

The new position.

whence

Specifies how the position pos should be interpreted:

SEEK_SET (default) - specifies that pos is specified from the beginning of the file.
SEEK_CUR - Specifies that pos is a count of characters from the current file position. This count may be positive or negative.
SEEK_END - Specifies that pos is a count of characters from the end of the file. A negative count specifies a position within the current extent of the file; a positive count specifies a position past the current end. If you set the position past the current end, and actually write data, you will extend the file with zeros up to that position.

返回值

范例

例子 1. Positioning in a file
<?php $fd = dio_open('/dev/ttyS0', O_RDWR); dio_seek($fd, 10, SEEK_SET); // position is now at 10 characters from the start of the file dio_seek($fd, -2, SEEK_CUR); // position is now at 8 characters from the start of the file dio_seek($fd, -5, SEEK_END); // position is now at 5 characters from the end of the file dio_seek($fd, 10, SEEK_END); // position is now at 10 characters past the end of the file. // The 10 characters between the end of the file and the current // position are filled with zeros. dio_close($fd); ?>

dio_stat

(PHP 4 >= 4.2.0, PHP 5 <= 5.0.4)

dio_stat -- Gets stat information about the file descriptor fd

说明

array dio_stat ( resource fd )

dio_stat() returns information about the given file descriptor.

参数

fd: The file descriptor returned by dio_open().

返回值

Returns an associative array with the following keys:

"device" - device
"inode" - inode
"mode" - mode
"nlink" - number of hard links
"uid" - user id
"gid" - group id
"device_type" - device type (if inode device)
"size" - total size in bytes
"blocksize" - blocksize
"blocks" - number of blocks allocated
"atime" - time of last access
"mtime" - time of last modification
"ctime" - time of last change

On error dio_stat() returns NULL.

dio_tcsetattr

(PHP 4 >= 4.3.0, PHP 5 <= 5.0.4)

dio_tcsetattr -- Sets terminal attributes and baud rate for a serial port

说明

bool dio_tcsetattr ( resource fd, array options )

dio_tcsetattr() sets the terminal attributes and baud rate of the open fd.

注: 本函数未在 Windows 平台下实现。

参数

fd

The file descriptor returned by dio_open().

options

The currently available options are:

'baud' - baud rate of the port - can be 38400,19200,9600,4800,2400,1800, 1200,600,300,200,150,134,110,75 or 50, default value is 9600.
'bits' - data bits - can be 8,7,6 or 5. Default value is 8.
'stop' - stop bits - can be 1 or 2. Default value is 1.
'parity' - can be 0,1 or 2. Default value is 0.

返回值

无返回值。

范例

例子 1. Setting the baud rate on a serial port
<?php $fd = dio_open('/dev/ttyS0', O_RDWR | O_NOCTTY | O_NONBLOCK); dio_fcntl($fd, F_SETFL, O_SYNC); dio_tcsetattr($fd, array( 'baud' => 9600, 'bits' => 8, 'stop' => 1, 'parity' => 0 )); while (1) { $data = dio_read($fd, 256); if ($data) { echo $data; } } ?>

dio_truncate

(PHP 4 >= 4.2.0, PHP 5 <= 5.0.4)

dio_truncate -- Truncates file descriptor fd to offset bytes

说明

bool dio_truncate ( resource fd, int offset )

dio_truncate() truncates a file to at most offset bytes in size.

If the file previously was larger than this size, the extra data is lost. If the file previously was shorter, it is unspecified whether the file is left unchanged or is extended. In the latter case the extended part reads as zero bytes.

注: 本函数未在 Windows 平台下实现。

参数

fd: The file descriptor returned by dio_open().
offset: The offset in bytes.

返回值

如果成功则返回 TRUE，失败则返回 FALSE。

dio_write

(PHP 4 >= 4.2.0, PHP 5 <= 5.0.4)

dio_write -- Writes data to fd with optional truncation at length

说明

int dio_write ( resource fd, string data [, int len] )

dio_write() writes up to len bytes from data to file fd.

参数

fd: The file descriptor returned by dio_open().
data: The written data.
len: The length of data to write in bytes. If not specified, the function writes all the data to the specified file.

返回值

Returns the number of bytes written to fd.

参见

dio_read()

XXVIII. Directory 目录函数

简介

需求

要编译本扩展模块不需要外部库文件。

安装

本函数库作为 PHP 内核的一部分，不用安装就能使用。

运行时配置

本扩展模块在 php.ini 中未定义任何配置选项。

资源类型

预定义常量

以下常量由本扩展模块定义，因此只有在本扩展模块被编译到 PHP 中，或者在运行时被动态加载后才有效。

DIRECTORY_SEPARATOR (string)
PATH_SEPARATOR (string)

注: PATH_SEPARATOR 是在 PHP 4.3.0-RC2 中引入。

参见

相关函数例如 dirname()，is_dir()，mkdir() 和 rmdir()，见文件系统函数一章。

目录
chdir -- 改变目录
chroot -- 改变根目录
dir -- directory 类
closedir -- 关闭目录句柄
getcwd -- 取得当前工作目录
opendir -- 打开目录句柄
readdir -- 从目录句柄中读取条目
rewinddir -- 倒回目录句柄
scandir -- 列出指定路径中的文件和目录

chdir

(PHP 3, PHP 4, PHP 5)

chdir -- 改变目录

说明

bool chdir ( string directory )

将 PHP 的当前目录改为 directory。

参数

directory: 新的当前目录

返回值

如果成功则返回 TRUE，失败则返回 FALSE。

范例

例子 1. chdir() 例子
<?php // current directory echo getcwd() . "\n"; chdir('public_html'); // current directory echo getcwd() . "\n"; ?>
上例的输出类似于：
/home/vincent /home/vincent/public_html

注释

注: 当安全模式被激活时，PHP 将检查被操作的目录是否和正在执行的脚本有相同的 UID（所有者）。

参见

getcwd()

chroot

(PHP 4 >= 4.0.5, PHP 5)

chroot -- 改变根目录

说明

bool chroot ( string directory )

将当前进程的根目录改变为 directory。

本函数仅在系统支持且运行于 CLI，CGI 或嵌入 SAPI 版本时才能正确工作。此外本函数还需要 root 权限。

参数

返回值

如果成功则返回 TRUE，失败则返回 FALSE。

注释

注: 本函数未在 Windows 平台下实现。

dir

(PHP 3, PHP 4, PHP 5)

dir -- directory 类

说明

class dir {

dir ( string directory )

string path

resource handle

string read ( void )

void rewind ( void )

void close ( void )

}

这是个仿冒面向对象的机制来读取一个目录。给定的 directory 被打开。一旦目录被打开，有两个属性可用。handle 属性可以用在其它目录函数例如 readdir()，rewinddir() 和 closedir() 中。path 属性被设为被打开的目录路径。有三个方法可用：read，rewind 和 close。

范例

例子 1. dir() 例子
请留意下面例子中检查 dir() 返回值的风格。我们明确地测试返回值是否全等于（值和类型都相同－更多信息参见比较运算符）FALSE，否则任何目录项的名称求值为 FALSE 的都会导致循环停止。
<?php $d = dir("/etc/php5"); echo "Handle: " . $d->handle . "\n"; echo "Path: " . $d->path . "\n"; while (false !== ($entry = $d->read())) { echo $entry."\n"; } $d->close(); ?>
上例的输出类似于：
Handle: Resource id #2 Path: /etc/php5 . .. apache cgi cli

注释

注: read 方法返回的目录项的顺序依赖于系统。

注: 本函数定义了内部类 Directory，意味着不能再用同样的名字定义用户自己的类。PHP 预定义类的完整列表见预定义类一节。

closedir

(PHP 3, PHP 4, PHP 5)

closedir -- 关闭目录句柄

说明

void closedir ( resource dir_handle )

关闭由 dir_handle 指定的目录流。流必须之前被 opendir() 所打开。

参数

dir_handle: 目录句柄的 resource，之前由 opendir() 所打开的。

范例

例子 1. closedir() 例子
<?php $dir = "/etc/php5/"; // Open a known directory, read directory into variable and then close if (is_dir($dir)) { if ($dh = opendir($dir)) { $directory = readdir($dh); closedir($dh); } } ?>

getcwd

(PHP 4, PHP 5)

getcwd -- 取得当前工作目录

说明

string getcwd ( void )

取得当前工作目录。

返回值

成功则返回当前工作目录，失败返回 FALSE。

在某些 Unix 的变种下，如果任何父目录没有设定可读或搜索模式，即使当前目录设定了，getcwd() 还是会返回 FALSE。有关模式与权限的更多信息见 chmod()。

范例

例子 1. getcwd() 例子
<?php // current directory echo getcwd() . "\n"; chdir('cvs'); // current directory echo getcwd() . "\n"; ?>
上例的输出类似于：
/home/didou /home/didou/cvs

参见

chdir()

chmod()

opendir

(PHP 3, PHP 4, PHP 5)

opendir -- 打开目录句柄

说明

resource opendir ( string path [, resource context] )

打开一个目录句柄，可用于之后的 closedir()，readdir() 和 rewinddir() 调用中。

参数

path: 要打开的目录路径
context: context 参数的说明见手册中的 Streams API 一章。

返回值

如果成功则返回目录句柄的 resource，失败则返回 FALSE。

如果 path 不是一个合法的目录或者因为权限限制或文件系统错误而不能打开目录，opendir() 返回 FALSE 并产生一个 E_WARNING 级别的 PHP 错误信息。可以在 opendir() 前面加上“@”符号来抑制错误信息的输出。

更新日志

版本	说明
5.0.0	`path` 支持 `ftp://` URL wrapper
4.3.0	`path` 可以是任何支持目录列表的 URL，不过在 PHP 4 中只有 `file://` URL wrapper 支持此功能

范例

例子 1. opendir() 例子
<?php $dir = "/etc/php5/"; // Open a known directory, and proceed to read its contents if (is_dir($dir)) { if ($dh = opendir($dir)) { while (($file = readdir($dh)) !== false) { echo "filename: $file : filetype: " . filetype($dir . $file) . "\n"; } closedir($dh); } } ?>
上例的输出类似于：
filename: . : filetype: dir filename: .. : filetype: dir filename: apache : filetype: dir filename: cgi : filetype: dir filename: cli : filetype: dir

参见

is_dir()

readdir()

Dir

readdir

(PHP 3, PHP 4, PHP 5)

readdir -- 从目录句柄中读取条目

说明

string readdir ( resource dir_handle )

返回目录中下一个文件的文件名。文件名以在文件系统中的排序返回。

参数

dir_handle: 目录句柄的 resource，之前由 opendir() 打开

返回值

成功则返回文件名，失败返回 FALSE。

范例

例子 1. 列出目录中的所有文件
请留意下面例子中检查 readdir() 返回值的风格。这里明确地测试返回值是否全等于（值和类型都相同――更多信息参见比较运算符）FALSE，否则任何目录项的名称求值为 FALSE 的都会导致循环停止（例如一个目录名为“0”）。
<?php // 注意在 4.0.0-RC2 之前不存在 !== 运算符 if ($handle = opendir('/path/to/files')) { echo "Directory handle: $handle\n"; echo "Files:\n"; /* 这是正确地遍历目录方法 */ while (false !== ($file = readdir($handle))) { echo "$file\n"; } /* 这是错误地遍历目录的方法 */ while ($file = readdir($handle)) { echo "$file\n"; } closedir($handle); } ?>

例子 2. 列出当前目录的所有文件并去掉 . 和 ..
<?php if ($handle = opendir('.')) { while (false !== ($file = readdir($handle))) { if ($file != "." && $file != "..") { echo "$file\n"; } } closedir($handle); } ?>

参见

is_dir()

glob()

rewinddir

(PHP 3, PHP 4, PHP 5)

rewinddir -- 倒回目录句柄

说明

void rewinddir ( resource dir_handle )

将 dir_handle 指定的目录流重置到目录的开头。

参数

dir_handle: 目录句柄的 resource，之前由 opendir() 打开

scandir

(PHP 5)

scandir -- 列出指定路径中的文件和目录

说明

array scandir ( string directory [, int sorting_order [, resource context]] )

返回一个 array，包含有 directory 中的文件和目录。

参数

directory: 要被浏览的目录
sorting_order: 默认的排序顺序是按字母升序排列。如果使用了可选参数 sorting_order（设为 1），则排序顺序是按字母降序排列。
context: context 参数的说明见手册中的 Streams API 一章。

返回值

成功则返回包含有文件名的 array，如果失败则返回 FALSE。如果 directory 不是个目录，则返回布尔值 FALSE 并生成一条 E_WARNING 级的错误。

范例

例子 1. 一个简单的 scandir() 例子
<?php $dir = '/tmp'; $files1 = scandir($dir); $files2 = scandir($dir, 1); print_r($files1); print_r($files2); ?>
上例的输出类似于：
Array ( [0] => . [1] => .. [2] => bar.php [3] => foo.txt [4] => somedir ) Array ( [0] => somedir [1] => foo.txt [2] => bar.php [3] => .. [4] => . )

例子 2. scandir() 在 PHP 4 中的实现
<?php $dir = "/tmp"; $dh = opendir($dir); while (false !== ($filename = readdir($dh))) { $files[] = $filename; } sort($files); print_r($files); rsort($files); print_r($files); ?>
上例的输出类似于：
Array ( [0] => . [1] => .. [2] => bar.php [3] => foo.txt [4] => somedir ) Array ( [0] => somedir [1] => foo.txt [2] => bar.php [3] => .. [4] => . )

注释

提示: 如果“fopen wrappers”已经被激活，则在本函数中可以把 URL 作为文件名来使用。请参阅 fopen() 函数来获取怎样指定文件名的详细信息以及支持 URL 封装协议的列表：附录 L。

参见

opendir()

readdir()

glob()

is_dir()

sort()

XXIX. DOM Functions

简介

The DOM extension is the replacement for the DOM XML extension from PHP 4. The extension still contains many old functions, but they should no longer be used. In particular, functions that are not object-oriented should be avoided.

The extension allows you to operate on an XML document with the DOM API.

安装

本函数库作为 PHP 内核的一部分，不用安装就能使用。

预定义类

This module defines a number of classes, which are explained in the following tables. Classes with an equivalent in the DOM standard are named DOMxxx.

DOMAttr

Extends DOMNode. The DOMAttr interface represents an attribute in an DOMElement object.

构造函数

DOMAttr->__construct() - construct a new DOMAttr object

方法

DOMAttr->isId() - Checks if attribute is a defined ID

属性

表格 1.

Name	Type	Read-only	Description
name	string	yes	The name of the attribute
ownerElement	DOMElement	yes	The element which contains the attribute
schemaTypeInfo	bool	yes	Not implemented yet, always return `NULL`
specified	bool	yes	Not implemented yet, always return `NULL`
value	string	no	The value of the attribute

DOMCharacterData

Extends DOMNode.

方法

DOMCharacterData->appendData() - Append a string to the end of the character data of the node
DOMCharacterData->deleteData() - Remove a range of characters from the node
DOMCharacterData->insertData() - Insert a string at the specified 16-bit unit offset
DOMCharacterData->replaceData() - Replace a substring within the DOMCharacterData node
DOMCharacterData->substringData() - Extracts a range of data from the node

属性

表格 2.

Name	Type	Read-only	Description
data	string	no	The contents of the node
length	int	yes	The length of the contents

DOMComment

Extends DOMCharacterData.

构造函数

DOMComment->__construct() - construct a new DOMComment object

DOMDocument

Extends DOMNode.

构造函数

DOMDocument->__construct() - construct a new DOMDocument object

方法

DOMDocument->createAttribute() - Create new attribute
DOMDocument->createAttributeNS() - Create new attribute node with an associated namespace
DOMDocument->createCDATASection() - Create new cdata node
DOMDocument->createComment() - Create new comment node
DOMDocument->createDocumentFragment() - Create new document fragment
DOMDocument->createElement() - Create new element node
DOMDocument->createElementNS() - Create new element node with an associated namespace
DOMDocument->createEntityReference() - Create new entity reference node
DOMDocument->createProcessingInstruction() - Creates new PI node
DOMDocument->createTextNode() - Create new text node
DOMDocument->getElementById() - Searches for an element with a certain id
DOMDocument->getElementsByTagName() - Searches for all elements with given tag name
DOMDocument->getElementsByTagNameNS() - Searches for all elements with given tag name in specified namespace
DOMDocument->importNode() - Import node into current document
DOMDocument->load() - Load XML from a file
DOMDocument->loadHTML() - Load HTML from a string
DOMDocument->loadHTMLFile() - Load HTML from a file
DOMDocument->loadXML() - Load XML from a string
DOMDocument->normalize() - Normalizes document
DOMDocument->relaxNGValidate() - Performs relaxNG validation on the document
DOMDocument->relaxNGValidateSource() - Performs relaxNG validation on the document
DOMDocument->save() - Dumps the internal XML tree back into a file
DOMDocument->saveHTML() - Dumps the internal document into a string using HTML formatting
DOMDocument->saveHTMLFile() - Dumps the internal document back into a file using HTML formatting
DOMDocument->saveXML() - Dumps the internal XML tree back into a string
DOMDocument->schemaValidate() - Validates a document based on a schema
DOMDocument->schemaValidateSource() - Validates a document based on a schema
DOMDocument->validate() - Validates the document based on its DTD
DOMDocument->xinclude() - Substitutes XIncludes in a DOMDocument Object

属性

表格 3.

Name	Type	Read-only	Description
actualEncoding	string	yes
config	DOMConfiguration	yes
doctype	DOMDocumentType	yes	The Document Type Declaration associated with this document.
documentElement	DOMElement	yes	This is a convenience attribute that allows direct access to the child node that is the document element of the document.
documentURI	string	no	The location of the document or `NULL` if undefined.
encoding	string	no
formatOutput	bool	no
implementation	DOMImplementation	yes	The DOMImplementation object that handles this document.
preserveWhiteSpace	bool	no	Do not remove redundant white space. Default to `TRUE`.
recover	bool	no
resolveExternals	bool	no	Set it to `TRUE` to load external entities from a doctype declaration. This is useful for including character entities in your XML document.
standalone	bool	no
strictErrorChecking	bool	no	Throws DOMException on errors. Default to `TRUE`.
substituteEntities	bool	no
validateOnParse	bool	no	Loads and validates against the DTD. Default to `FALSE`.
version	string	no
xmlEncoding	string	yes	An attribute specifying, as part of the XML declaration, the encoding of this document. This is `NULL` when unspecified or when it is not known, such as when the Document was created in memory.
xmlStandalone	bool	no	An attribute specifying, as part of the XML declaration, whether this document is standalone. This is `FALSE` when unspecified.
xmlVersion	string	no	An attribute specifying, as part of the XML declaration, the version number of this document. If there is no declaration and if this document supports the "XML" feature, the value is "1.0".

DOMDocumentType

Extends DOMNode

Each DOMDocument has a doctype attribute whose value is either NULL or a DOMDocumentType object.

属性

表格 4.

Name	Type	Read-only	Description
publicId	string	yes	The public identifier of the external subset.
systemId	string	yes	The system identifier of the external subset. This may be an absolute URI or not.
name	string	yes	The name of DTD; i.e., the name immediately following the `DOCTYPE` keyword.
entities	DOMNamedNodeMap	yes	A DOMNamedNodeMap containing the general entities, both external and internal, declared in the DTD.
notations	DOMNamedNodeMap	yes	A DOMNamedNodeMap containing the notations declared in the DTD.
internalSubset	string	yes	The internal subset as a string, or null if there is none. This is does not contain the delimiting square brackets.

DOMElement

Extends DOMNode.

构造函数

DOMElement->__construct() - construct a new DOMElement object

方法

DOMElement->getAttribute() - Returns value of attribute
DOMElement->getAttributeNode() - Returns attribute node
DOMElement->getAttributeNodeNS() - Returns attribute node
DOMElement->getAttributeNS() - Returns value of attribute
DOMElement->getElementsByTagName() - Gets elements by tagname
DOMElement->getElementsByTagNameNS() - Get elements by namespaceURI and localName
DOMElement->hasAttribute() - Checks to see if attribute exists
DOMElement->hasAttributeNS() - Checks to see if attribute exists
DOMElement->removeAttribute() - Removes attribute
DOMElement->removeAttributeNode() - Removes attribute
DOMElement->removeAttributeNS() - Removes attribute
DOMElement->setAttribute() - Adds new attribute
DOMElement->setAttributeNode() - Adds new attribute node to element
DOMElement->setAttributeNodeNS() - Adds new attribute node to element
DOMElement->setAttributeNS() - Adds new attribute

属性

表格 5.

Name	Type	Read-only	Description
schemaTypeInfo	bool	yes	Not implemented yet, always return `NULL`
tagName	string	yes	The element name

DOMEntity

Extends DOMNode

This interface represents a known entity, either parsed or unparsed, in an XML document.

属性

表格 6.

Name	Type	Read-only	Description
publicId	string	yes	The public identifier associated with the entity if specified, and `NULL` otherwise.
systemId	string	yes	The system identifier associated with the entity if specified, and `NULL` otherwise. This may be an absolute URI or not.
notationName	string	yes	For unparsed entities, the name of the notation for the entity. For parsed entities, this is `NULL`.
actualEncoding	string	no	An attribute specifying the encoding used for this entity at the time of parsing, when it is an external parsed entity. This is `NULL` if it an entity from the internal subset or if it is not known.
encoding	string	yes	An attribute specifying, as part of the text declaration, the encoding of this entity, when it is an external parsed entity. This is `NULL` otherwise.
version	string	yes	An attribute specifying, as part of the text declaration, the version number of this entity, when it is an external parsed entity. This is `NULL` otherwise.

DOMEntityReference

Extends DOMNode.

构造函数

DOMAttr->__construct() - construct a new DOMEntityReference object

DOMException

DOM operations raise exceptions under particular circumstances, i.e., when an operation is impossible to perform for logical reasons.

属性

表格 7.

Name	Type	Read-only	Description
code	int	yes	An integer indicating the type of error generated

DOMImplementation

The DOMImplementation interface provides a number of methods for performing operations that are independent of any particular instance of the document object model.

构造函数

DOMImplementation->__construct() - construct a new DOMImplementation object

方法

DOMImplementation->createDocument() - Creates a DOM Document object of the specified type with its document element
DOMImplementation->createDocumentType() - Creates an empty DOMDocumentType object
DOMImplementation->hasFeature() - Test if the DOM implementation implements a specific feature

DOMNode

方法

DOMNode->appendChild() - Adds new child at the end of the children
DOMNode->cloneNode() - Clones a node
DOMNode->hasAttributes() - Checks if node has attributes
DOMNode->hasChildNodes() - Checks if node has children
DOMNode->insertBefore() - Adds a new child before a reference node
DOMNode->isSameNode() - Indicates if two nodes are the same node
DOMNode->isSupported() - Checks if feature is supported for specified version
DOMNode->lookupNamespaceURI() - Returns namespace URI of the node based on the prefix
DOMNode->lookupPrefix() - Returns name space prefix of the node based on namespaceURI
DOMNode->normalize() - Normalizes the node
DOMNode->removeChild() - Removes child from list of children
DOMNode->replaceChild() - Replaces a child

属性

表格 8.

Name	Type	Read-only	Description
nodeName	string	yes	Returns the more accurate name for the current node type
nodeValue	string	no	The value of this node, depending on its type.
nodeType	int	yes	Gets the type of the node. One of the predefined XML_xxx_NODE constants
parentNode	DOMNode	yes	The parent of this node.
childNodes	DOMNodeList	yes	A DOMNodeList that contains all children of this node. If there are no children, this is an empty DOMNodeList.
firstChild	DOMNode	yes	The first child of this node. If there is no such node, this returns `NULL`.
lastChild	DOMNode	yes	The last child of this node. If there is no such node, this returns `NULL`.
previousSibling	DOMNode	yes	The node immediately preceding this node. If there is no such node, this returns `NULL`.
nextSibling	DOMNode	yes	The node immediately following this node. If there is no such node, this returns `NULL`.
attributes	DOMNamedNodeMap	yes	A DOMNamedNodeMap containing the attributes of this node (if it is a DOMElement) or `NULL` otherwise.
ownerDocument	DOMDocument	yes	The DOMDocument object associated with this node.
namespaceURI	string	yes	The namespace URI of this node, or `NULL` if it is unspecified.
prefix	string	no	The namespace prefix of this node, or `NULL` if it is unspecified.
localName	string	yes	Returns the local part of the qualified name of this node.
baseURI	string	yes	The absolute base URI of this node or `NULL` if the implementation wasn't able to obtain an absolute URI.
textContent	string	no	This attribute returns the text content of this node and its descendants.

DOMNodeList

方法

DOMNodelist->item() - Retrieves a node specified by index

属性

表格 9.

Name	Type	Read-only	Description
length	int	yes	The number of nodes in the list. The range of valid child node indices is 0 to `length - 1` inclusive.

DOMNotation

Extends DOMNode

属性

表格 10.

Name	Type	Read-only	Description
publicId	string	yes
systemId	string	yes

DOMProcessingInstruction

Extends DOMNode.

构造函数

DOMProcessingInstruction->__construct() - construct a new DOMProcessingInstruction object

属性

表格 11.

Name	Type	Read-only	Description
target	string	yes
data	string	no

DOMText

Extends DOMCharacterData.

构造函数

DOMText->__construct() - construct a new DOMText object

方法

DOMText->isWhitespaceInElementContent() - Indicates whether this text node contains whitespace
DOMText->splitText() - Breaks the node into two nodes at the specified offset

属性

表格 12.

Name	Type	Read-only	Description
wholeText	string	yes

DOMXPath

构造函数

DOMXPath->__construct() - construct a new DOMXPath object

方法

DOMXPath->registerNamespace() - Registers the namespace with the DOMXpath object
DOMXPath->evaluate() - Evaluates the given XPath expression and returns a typed result if possible
DOMXPath->query() - Evaluates the given XPath expression

属性

表格 13.

Name	Type	Read-only	Description
document	DOMDocument

范例

Many examples in this reference require an XML file. We will use book.xml that contains the following:

例子 1. chapter.xml
<?xml version="1.0" encoding="iso-8859-1"?> <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [ ]> <book id="listing"> <title>My lists</title> <chapter id="books"> <title>My books</title> <para> <informaltable> <tgroup cols="4"> <thead> <row> <entry>Title</entry> <entry>Author</entry> <entry>Language</entry> <entry>ISBN</entry> </row> </thead> <tbody> <row> <entry>The Grapes of Wrath</entry> <entry>John Steinbeck</entry> <entry>en</entry> <entry>0140186409</entry> </row> <row> <entry>The Pearl</entry> <entry>John Steinbeck</entry> <entry>en</entry> <entry>014017737X</entry> </row> <row> <entry>Samarcande</entry> <entry>Amine Maalouf</entry> <entry>fr</entry> <entry>2253051209</entry> </row>  </tbody> </tgroup> </informaltable> </para> </chapter> </book>

预定义常量

以下常量由本扩展模块定义，因此只有在本扩展模块被编译到 PHP 中，或者在运行时被动态加载后才有效。

表格 14. XML constants

Constant	Value	Description
`XML_ELEMENT_NODE` (integer)	1	Node is a DOMElement
`XML_ATTRIBUTE_NODE` (integer)	2	Node is a DOMAttr
`XML_TEXT_NODE` (integer)	3	Node is a DOMText
`XML_CDATA_SECTION_NODE` (integer)	4	Node is a DOMCharacterData
`XML_ENTITY_REF_NODE` (integer)	5	Node is a DOMEntityReference
`XML_ENTITY_NODE` (integer)	6	Node is a DOMEntity
`XML_PI_NODE` (integer)	7	Node is a DOMProcessingInstruction
`XML_COMMENT_NODE` (integer)	8	Node is a DOMComment
`XML_DOCUMENT_NODE` (integer)	9	Node is a DOMDocument
`XML_DOCUMENT_TYPE_NODE` (integer)	10	Node is a DOMDocumentType
`XML_DOCUMENT_FRAG_NODE` (integer)	11	Node is a DOMDocumentFragment
`XML_NOTATION_NODE` (integer)	12	Node is a DOMNotation
`XML_HTML_DOCUMENT_NODE` (integer)	13
`XML_DTD_NODE` (integer)	14
`XML_ELEMENT_DECL_NODE` (integer)	15
`XML_ATTRIBUTE_DECL_NODE` (integer)	16
`XML_ENTITY_DECL_NODE` (integer)	17
`XML_NAMESPACE_DECL_NODE` (integer)	18
`XML_ATTRIBUTE_CDATA` (integer)	1
`XML_ATTRIBUTE_ID` (integer)	2
`XML_ATTRIBUTE_IDREF` (integer)	3
`XML_ATTRIBUTE_IDREFS` (integer)	4
`XML_ATTRIBUTE_ENTITY` (integer)	5
`XML_ATTRIBUTE_NMTOKEN` (integer)	7
`XML_ATTRIBUTE_NMTOKENS` (integer)	8
`XML_ATTRIBUTE_ENUMERATION` (integer)	9
`XML_ATTRIBUTE_NOTATION` (integer)	10

表格 15. DOMException constants

Constant	Value	Description
`DOM_INDEX_SIZE_ERR` (integer)	1	If index or size is negative, or greater than the allowed value.
`DOMSTRING_SIZE_ERR` (integer)	2	If the specified range of text does not fit into a DOMString.
`DOM_HIERARCHY_REQUEST_ERR` (integer)	3	If any node is inserted somewhere it doesn't belong
`DOM_WRONG_DOCUMENT_ERR` (integer)	4	If a node is used in a different document than the one that created it.
`DOM_INVALID_CHARACTER_ERR` (integer)	5	If an invalid or illegal character is specified, such as in a name.
`DOM_NO_DATA_ALLOWED_ERR` (integer)	6	If data is specified for a node which does not support data.
`DOM_NO_MODIFICATION_ALLOWED_ERR` (integer)	7	If an attempt is made to modify an object where modifications are not allowed.
`DOM_NOT_FOUND_ERR` (integer)	8	If an attempt is made to reference a node in a context where it does not exist.
`DOM_NOT_SUPPORTED_ERR` (integer)	9	If the implementation does not support the requested type of object or operation.
`DOM_INUSE_ATTRIBUTE_ERR` (integer)	10	If an attempt is made to add an attribute that is already in use elsewhere.
`DOM_INVALID_STATE_ERR` (integer)	11	If an attempt is made to use an object that is not, or is no longer, usable.
`DOM_SYNTAX_ERR` (integer)	12	If an invalid or illegal string is specified.
`DOM_INVALID_MODIFICATION_ERR` (integer)	13	If an attempt is made to modify the type of the underlying object.
`DOM_NAMESPACE_ERR` (integer)	14	If an attempt is made to create or change an object in a way which is incorrect with regard to namespaces.
`DOM_INVALID_ACCESS_ERR` (integer)	15	If a parameter or an operation is not supported by the underlying object.
`DOM_VALIDATION_ERR` (integer)	16	If a call to a method such as insertBefore or removeChild would make the Node invalid with respect to "partial validity", this exception would be raised and the operation would not be done.

目录
DOMAttr->__construct() -- Creates a new DOMAttr object
DOMAttr->isId() -- Checks if attribute is a defined ID
DOMCharacterData->appendData() -- Append the string to the end of the character data of the node
DOMCharacterData->deleteData() -- Remove a range of characters from the node
DOMCharacterData->insertData() -- Insert a string at the specified 16-bit unit offset
DOMCharacterData->replaceData() -- Replace a substring within the DOMCharacterData node
DOMCharacterData->substringData() -- Extracts a range of data from the node
DOMComment->__construct() -- Creates a new DOMComment object
DOMDocument->__construct() -- Creates a new DOMDocument object
DOMDocument->createAttribute() -- Create new attribute
DOMDocument->createAttributeNS() -- Create new attribute node with an associated namespace
DOMDocument->createCDATASection() -- Create new cdata node
DOMDocument->createComment() -- Create new comment node
DOMDocument->createDocumentFragment() -- Create new document fragment
DOMDocument->createElement() -- Create new element node
DOMDocument->createElementNS() -- Create new element node with an associated namespace
DOMDocument->createEntityReference() -- Create new entity reference node
DOMDocument->createProcessingInstruction() -- Creates new PI node
DOMDocument->createTextNode() -- Create new text node
DOMDocument->getElementById() -- Searches for an element with a certain id
DOMDocument->getElementsByTagName() -- Searches for all elements with given tag name
DOMDocument->getElementsByTagNameNS() -- Searches for all elements with given tag name in specified namespace
DOMDocument->importNode() -- Import node into current document
DOMDocument->load() -- Load XML from a file
DOMDocument->loadHTML() -- Load HTML from a string
DOMDocument->loadHTMLFile() -- Load HTML from a file
DOMDocument->loadXML() -- Load XML from a string
DOMDocument->normalize() -- Normalizes the document
DOMDocument->relaxNGValidate() -- Performs relaxNG validation on the document
DOMDocument->relaxNGValidateSource() -- Performs relaxNG validation on the document
DOMDocument->save() -- Dumps the internal XML tree back into a file
DOMDocument->saveHTML() -- Dumps the internal document into a string using HTML formatting
DOMDocument->saveHTMLFile() -- Dumps the internal document into a file using HTML formatting
DOMDocument->saveXML() -- Dumps the internal XML tree back into a string
DOMDocument->schemaValidate() -- Validates a document based on a schema
DOMDocument->schemaValidateSource() -- Validates a document based on a schema
DOMDocument->validate() -- Validates the document based on its DTD
DOMDocument->xinclude() -- Substitutes XIncludes in a DOMDocument Object
DOMElement->__construct() -- Creates a new DOMElement object
DOMElement->getAttribute() -- Returns value of attribute
DOMElement->getAttributeNode() -- Returns attribute node
DOMElement->getAttributeNodeNS() -- Returns attribute node
DOMElement->getAttributeNS() -- Returns value of attribute
DOMElement->getElementsByTagName() -- Gets elements by tagname
DOMElement->getElementsByTagNameNS() -- Get elements by namespaceURI and localName
DOMElement->hasAttribute() -- Checks to see if attribute exists
DOMElement->hasAttributeNS() -- Checks to see if attribute exists
DOMElement->removeAttribute() -- Removes attribute
DOMElement->removeAttributeNode() -- Removes attribute
DOMElement->removeAttributeNS() -- Removes attribute
DOMElement->setAttribute() -- Adds new attribute
DOMElement->setAttributeNode() -- Adds new attribute node to element
DOMElement->setAttributeNodeNS() -- Adds new attribute node to element
DOMElement->setAttributeNS() -- Adds new attribute
DOMAttr->__construct() -- Creates a new DOMEntityReference object
DOMImplementation->__construct() -- Creates a new DOMImplementation object
DOMImplementation->createDocument() -- Creates a DOMDocument object of the specified type with its document element
DOMImplementation->createDocumentType() -- Creates an empty DOMDocumentType object
DOMImplementation->hasFeature() -- Test if the DOM implementation implements a specific feature
DOMNamedNodeMap->getNamedItem() -- Retrieves a node specified by name
DOMNamedNodeMap->getNamedItemNS() -- Retrieves a node specified by local name and namespace URI
DOMNamedNodeMap->item() -- Retrieves a node specified by index
DOMNode->appendChild() -- Adds new child at the end of the children
DOMNode->cloneNode() -- Clones a node
DOMNode->hasAttributes() -- Checks if node has attributes
DOMNode->hasChildNodes() -- Checks if node has children
DOMNode->insertBefore() -- Adds a new child before a reference node
DOMNode->isSameNode() -- Indicates if two nodes are the same node
DOMNode->isSupported() -- Checks if feature is supported for specified version
DOMNode->lookupNamespaceURI() -- Gets the namespace URI of the node based on the prefix
DOMNode->lookupPrefix() -- Gets the namespace prefix of the node based on the namespace URI
DOMNode->normalize() -- Normalizes the node
DOMNode->removeChild() -- Removes child from list of children
DOMNode->replaceChild() -- Replaces a child
DOMNodelist->item() -- Retrieves a node specified by index
DOMProcessingInstruction->__construct() -- Creates a new DOMProcessingInstruction object
DOMText->__construct() -- Creates a new DOMText object
DOMText->isWhitespaceInElementContent() -- Indicates whether this text node contains whitespace
DOMText->splitText() -- Breaks this node into two nodes at the specified offset
DOMXPath->__construct() -- Creates a new DOMXPath object
DOMXPath->evaluate() -- Evaluates the given XPath expression and returns a typed result if possible.
DOMXPath->query() -- Evaluates the given XPath expression
DOMXPath->registerNamespace() -- Registers the namespace with the DOMXPath object
dom_import_simplexml -- Gets a DOMElement object from a SimpleXMLElement object

DOMAttr->__construct()

(no version information, might be only in CVS)

DOMAttr->__construct() -- Creates a new DOMAttr object

说明

class DOMAttr {

__construct ( string name [, string value] )

}

Creates a new DOMAttr object. This object is read only. It may be appended to a document, but additional nodes may not be appended to this node until the node is associated with a document. To create a writeable node, use DOMDocument->createAttribute().

参数

name: The tag name of the attribute.
value: The value of the attribute.

范例

例子 1. Creating a new DOMAttr
<?php $dom = new DOMDocument('1.0', 'iso-8859-1'); $element = $dom->appendChild(new DOMElement('root')); $attr = $element->setAttributeNode(new DOMAttr('attr', 'attrvalue')); echo $dom->saveXML(); /* <?xml version="1.0" encoding="iso-8859-1"?><root attr="attrvalue" /> */ ?>

参见

DOMAttr->isId()

(no version information, might be only in CVS)

DOMAttr->isId() -- Checks if attribute is a defined ID

说明

class DOMAttr {

bool isId ( void )

}

This function checks if the attribute is a defined ID.

According to the DOM standard this requires a DTD which defines the attribute ID to be of type ID. You need to validate your document with DOMDocument->validate() or DOMDocument::validateOnParse before using this function.

返回值

如果成功则返回 TRUE，失败则返回 FALSE。

范例

例子 1. DOMAttr->isId() Example
<?php $doc = new DomDocument; // We need to validate our document before refering to the id $doc->validateOnParse = true; $doc->Load('book.xml'); // We retrieve the attribute named id of the chapter element $attr = $doc->getElementsByTagName('chapter')->item(0)->getAttributeNode('id'); var_dump($attr->isId()); // bool(true) ?>

DOMCharacterData->appendData()

(no version information, might be only in CVS)

DOMCharacterData->appendData() -- Append the string to the end of the character data of the node

说明

class DOMCharacterData {

void appendData ( string data )

}

Append the string data to the end of the character data of the node.

参数

data: The string to append.

返回值

无返回值。

参见

DOMCharacterData->deleteData()

(no version information, might be only in CVS)

DOMCharacterData->deleteData() -- Remove a range of characters from the node

说明

class DOMCharacterData {

void deleteData ( int offset, int count )

}

Deletes count characters starting from position offset.

参数

offset: The offset from which to start removing.
count: The number of characters to delete. If the sum of offset and count exceeds the length, then all characters to the end of the data are deleted.

返回值

无返回值。

异常

DOM_INDEX_SIZE_ERR: Raised if offset is negative or greater than the number of 16-bit units in data, or if count is negative.

参见

DOMCharacterData->insertData()

(no version information, might be only in CVS)

DOMCharacterData->insertData() -- Insert a string at the specified 16-bit unit offset

说明

class DOMCharacterData {

void insertData ( int offset, string data )

}

Inserts string data at position offset.

参数

offset: The character offset at which to insert.
data: The string to insert.

返回值

无返回值。

异常

DOM_INDEX_SIZE_ERR: Raised if offset is negative or greater than the number of 16-bit units in data.

参见

DOMCharacterData->replaceData()

(no version information, might be only in CVS)

DOMCharacterData->replaceData() -- Replace a substring within the DOMCharacterData node

说明

class DOMCharacterData {

void replaceData ( int offset, int count, string data )

}

Replace count characters starting from position offset with data.

参数

offset: The offset from which to start replacing.
count: The number of characters to replace. If the sum of offset and count exceeds the length, then all characters to the end of the data are replaced.
data: The string with which the range must be replaced.

返回值

无返回值。

异常

DOM_INDEX_SIZE_ERR: Raised if offset is negative or greater than the number of 16-bit units in data, or if count is negative.

参见

(no version information, might be only in CVS)

DOMCharacterData->substringData() -- Extracts a range of data from the node

说明

class DOMCharacterData {

string substringData ( int offset, int count )

}

Returns the specified substring.

参数

offset: Start offset of substring to extract.
count: The number of characters to extract.

返回值

The specified substring. If the sum of offset and count exceeds the length, then all 16-bit units to the end of the data are returned.

异常

DOM_INDEX_SIZE_ERR: Raised if offset is negative or greater than the number of 16-bit units in data, or if count is negative.

参见

DOMComment->__construct()

(no version information, might be only in CVS)

DOMComment->__construct() -- Creates a new DOMComment object

说明

class DOMComment {

__construct ( [string value] )

}

Creates a new DOMComment object. This object is read only. It may be appended to a document, but additional nodes may not be appended to this node until the node is associated with a document. To create a writeable node, use DOMDocument->createComment().

参数

value: The value of the comment.

范例

例子 1. Creating a new DOMComment
<?php $dom = new DOMDocument('1.0', 'iso-8859-1'); $element = $dom->appendChild(new DOMElement('root')); $comment = $element->appendChild(new DOMComment('root comment')); echo $dom->saveXML(); /* <?xml version="1.0" encoding="iso-8859-1"?><root></root> */ ?>

参见

DOMImplementation->createDocument()

DOMDocument->__construct()

(no version information, might be only in CVS)

DOMDocument->__construct() -- Creates a new DOMDocument object

说明

class DOMDocument {

__construct ( [string version [, string encoding]] )

}

Creates a new DOMDocument object.

参数

version: The version number of the document as part of the XML declaration.
encoding: The encoding of the document as part of the XML declaration.

范例

例子 1. Creating a new DOMDocument
<?php $dom = new DOMDocument('1.0', 'iso-8859-1'); echo $dom->saveXML(); /* <?xml version="1.0" encoding="iso-8859-1"?> */ ?>

参见

DOMDocument->createAttribute()

(no version information, might be only in CVS)

DOMDocument->createAttribute() -- Create new attribute

说明

class DOMDocument {

DOMAttr createAttribute ( string name )

}

This function creates a new instance of class DOMAttr. 本节点不会出现在文档中，除非是用例如 DOMNode->appendChild() 函数来将其插入。

参数

name: The name of the attribute.

返回值

The new DOMAttr or FALSE if an error occured.

异常

DOM_INVALID_CHARACTER_ERR: Raised if name contains an invalid character.

参见

DOMDocument->createAttributeNS()

(no version information, might be only in CVS)

DOMDocument->createAttributeNS() -- Create new attribute node with an associated namespace

说明

class DOMDocument {

DOMAttr createAttributeNS ( string namespaceURI, string qualifiedName )

}

This function creates a new instance of class DOMAttr. 本节点不会出现在文档中，除非是用例如 DOMNode->appendChild() 函数来将其插入。

参数

namespaceURI: The URI of the namespace.
qualifiedName: The tag name and prefix of the attribute, as prefix:tagname.

返回值

The new DOMAttr or FALSE if an error occured.

异常

DOM_INVALID_CHARACTER_ERR: Raised if qualifiedName contains an invalid character.
DOM_NAMESPACE_ERR: Raised if qualifiedName is a malformed qualified name, or if qualifiedName has a prefix and namespaceURI is NULL.

参见

DOMDocument->createCDATASection()

(no version information, might be only in CVS)

DOMDocument->createCDATASection() -- Create new cdata node

说明

class DOMDocument {

DOMCDATASection createCDATASection ( string data )

}

This function creates a new instance of class DOMCDATASection. 本节点不会出现在文档中，除非是用例如 DOMNode->appendChild() 函数来将其插入。

参数

data: The content of the cdata.

返回值

The new DOMCDATASection or FALSE if an error occured.

参见

DOMDocument->createComment()

(no version information, might be only in CVS)

DOMDocument->createComment() -- Create new comment node

说明

class DOMDocument {

DOMComment createComment ( string data )

}

This function creates a new instance of class DOMComment. 本节点不会出现在文档中，除非是用例如 DOMNode->appendChild() 函数来将其插入。

参数

data: The content of the comment.

返回值

The new DOMComment or FALSE if an error occured.

参见

DOMDocument->createDocumentFragment()

(no version information, might be only in CVS)

DOMDocument->createDocumentFragment() -- Create new document fragment

说明

class DOMDocument {

DOMDocumentFragment createDocumentFragment ( void )

}

This function creates a new instance of class DOMDocumentFragment. 本节点不会出现在文档中，除非是用例如 DOMNode->appendChild() 函数来将其插入。

返回值

The new DOMDocumentFragment or FALSE if an error occured.

参见

DOMDocument->createElement()

(no version information, might be only in CVS)

DOMDocument->createElement() -- Create new element node

说明

class DOMDocument {

DOMElement createElement ( string name [, string value] )

}

This function creates a new instance of class DOMElement. 本节点不会出现在文档中，除非是用例如 DOMNode->appendChild() 函数来将其插入。

参数

name: The tag name of the element.
value: The value of the element. By default, an empty element will be created. You can also set the value later with DOMElement->nodeValue.

返回值

Returns a new instance of class DOMElement or FALSE if an error occured.

异常

DOM_INVALID_CHARACTER_ERR: Raised if name contains an invalid character.

范例

例子 1. Creating a new element and inserting it as root
<?php $dom = new DOMDocument('1.0', 'iso-8859-1'); $element = $dom->createElement('test', 'This is the root element!'); // We insert the new element as root (child of the document) $dom->appendChild($element); echo $dom->saveXML(); ?>
上例将输出：
<?xml version="1.0" encoding="iso-8859-1"?> <test>This is the root element!</test>

参见

DOMDocument->createElementNS()

(no version information, might be only in CVS)

DOMDocument->createElementNS() -- Create new element node with an associated namespace

说明

class DOMDocument {

DOMElement createElementNS ( string namespaceURI, string qualifiedName [, string value] )

}

This function creates a new element node with an associated namespace. 本节点不会出现在文档中，除非是用例如 DOMNode->appendChild() 函数来将其插入。

参数

namespaceURI: The URI of the namespace.
qualifiedName: The qualified name of the element, as prefix:tagname.
value: The value of the element. By default, an empty element will be created. You can also set the value later with DOMElement->nodeValue.

返回值

The new DOMElement or FALSE if an error occured.

异常

DOM_INVALID_CHARACTER_ERR: Raised if qualifiedName contains an invalid character.
DOM_NAMESPACE_ERR: Raised if qualifiedName is a maformed qualified name.

范例

例子 1. Creating a new element and inserting it as root
<?php $dom = new DOMDocument('1.0', 'iso-8859-1'); $element = $dom->createElementNS('http://www.example.com/XFoo', 'xfoo:test', 'This is the root element!'); // We insert the new element as root (child of the document) $dom->appendChild($element); echo $dom->saveXML(); ?>
上例将输出：
<?xml version="1.0" encoding="iso-8859-1"?> <xfoo:test xmlns:xfoo="http://www.example.com/XFoo">This is the root element!</xfoo:test>

参见

DOMDocument->createEntityReference()

(no version information, might be only in CVS)

DOMDocument->createEntityReference() -- Create new entity reference node

说明

class DOMDocument {

DOMEntityReference createEntityReference ( string name )

}

This function creates a new instance of class DOMEntityReference. 本节点不会出现在文档中，除非是用例如 DOMNode->appendChild() 函数来将其插入。

参数

name: The content of the entity reference, e.g. the entity reference minus the leading & and the trailing ; characters.

返回值

The new DOMEntityReference or FALSE if an error occured.

异常

DOM_INVALID_CHARACTER_ERR: Raised if name contains an invalid character.

参见

DOMDocument->createProcessingInstruction()

(no version information, might be only in CVS)

DOMDocument->createProcessingInstruction() -- Creates new PI node

说明

class DOMDocument {

DOMProcessingInstruction createProcessingInstruction ( string target [, string data] )

}

This function creates a new instance of class DOMProcessingInstruction. 本节点不会出现在文档中，除非是用例如 DOMNode->appendChild() 函数来将其插入。

参数

target: The target of the processing instruction.
data: The content of the processing instruction.

返回值

The new DOMProcessingInstruction or FALSE if an error occured.

异常

DOM_INVALID_CHARACTER_ERR: Raised if target contains an invalid character.

参见

(no version information, might be only in CVS)

DOMDocument->createTextNode() -- Create new text node

说明

class DOMDocument {

DOMText createTextNode ( string content )

}

This function creates a new instance of class DOMText. 本节点不会出现在文档中，除非是用例如 DOMNode->appendChild() 函数来将其插入。

参数

content: The content of the text.

返回值

The new DOMText or FALSE if an error occured.

参见

DOMDocument->getElementsByTagName()

DOMDocument->getElementById()

(no version information, might be only in CVS)

DOMDocument->getElementById() -- Searches for an element with a certain id

说明

class DOMDocument {

DOMElement getElementById ( string elementId )

}

This function is similar to DOMDocument->getElementsByTagName() but searches for an element with a given id.

参数

elementId: The unique id value for an element.

返回值

Returns the DOMElement or NULL if the element is not found.

范例

例子 1. DOMDocument->getElementById() Example

<?php

$doc = new DomDocument;

// We need to validate our document before refering to the id
$doc->validateOnParse = true;
$doc->Load('book.xml');

echo "The element whose id is books is: " . $doc->getElementById('books')->tagName . "\n";

?>

上例将输出：

The element whose id is books is: chapter

参见

(no version information, might be only in CVS)

DOMDocument->getElementsByTagName() -- Searches for all elements with given tag name

说明

class DOMDocument {

DOMNodeList getElementsByTagName ( string name )

}

This function returns a new instance of class DOMNodeList containing the elements with a given tag name.

参数

name: The name of the tag to match on. The special value * matches all tags.

返回值

A new DOMNodeList object containing all the matched elements.

参见

DOMDocument->getElementsByTagNameNS()

(no version information, might be only in CVS)

DOMDocument->getElementsByTagNameNS() -- Searches for all elements with given tag name in specified namespace

说明

class DOMDocument {

DOMNodeList getElementsByTagNameNS ( string namespaceURI, string localName )

}

Returns a DOMNodeList of all elements with a given local name and a namespace URI.

参数

namespaceURI: The namespace URI of the elements to match on. The special value * matches all namespaces.
localName: The local name of the elements to match on. The special value * matches all local names.

返回值

A new DOMNodeList object containing all the matched elements.

范例

例子 1. Get all the XInclude elements
<?php $xml = <<<EOD <?xml version="1.0" ?> <chapter xmlns:xi="http://www.w3.org/2001/XInclude"> <title>Books of the other guy..</title> <para> <xi:include href="book.xml"> <xi:fallback> <error>xinclude: book.xml not found</error> </xi:fallback> </xi:include> <include> This is another namespace </include> </para> </chapter> EOD; $dom = new DOMDocument; // load the XML string defined above $dom->loadXML($xml); foreach ($dom->getElementsByTagNameNS('http://www.w3.org/2001/XInclude', '*') as $element) { echo 'local name: ', $element->localName, ', prefix: ', $element->prefix, "\n"; } ?>
上例将输出：
local name: include, prefix: xi local name: fallback, prefix: xi

参见

DOMDocument->getElementsByTagName()

DOMDocument->importNode()

(no version information, might be only in CVS)

DOMDocument->importNode() -- Import node into current document

说明

class DOMDocument {

DOMNode importNode ( DOMNode importedNode [, bool deep] )

}

This function returns a copy of the node to import and associates it with the current document.

参数

importedNode: The node to import.
deep: If set to TRUE, this method will recursively import the subtree under the importedNode.

返回值

The copied node.

异常

DOMException is thrown if node cannot be imported.

DOMDocument->load()

(no version information, might be only in CVS)

DOMDocument->load() -- Load XML from a file

说明

class DOMDocument {

bool load ( string filename [, int options] )

}

Loads an XML document from a file.

This method may also be called statically to load and create a DOMDocument object. The static invocation may be used when no DOMDocument properties need to be set prior to loading.

参数

filename: The path to the XML document.

返回值

如果成功则返回 TRUE，失败则返回 FALSE。

范例

例子 1. Creating a Document
<?php $doc = DOMDocument::load('book.xml'); echo $doc->saveXML(); $doc = new DOMDocument(); $doc->load('book.xml'); echo $doc->saveXML(); ?>

参见

DOMDocument->loadXML()

DOMDocument->save()

DOMDocument->saveXML()

DOMDocument->loadHTML()

(no version information, might be only in CVS)

DOMDocument->loadHTML() -- Load HTML from a string

说明

class DOMDocument {

bool loadHTML ( string source )

}

The function parses the HTML contained in the string source. Unlike loading XML, HTML does not have to be well-formed to load. This function may also be called statically to load and create a DOMDocument object. The static invocation may be used when no DOMDocument properties need to be set prior to loading.

参数

source: The HTML string.

返回值

如果成功则返回 TRUE，失败则返回 FALSE。

范例

例子 1. Creating a Document
<?php $doc = DOMDocument::loadHTML("<html><body>Test<br></body></html>"); echo $doc->saveHTML(); $doc = new DOMDocument(); $doc->loadHTML("<html><body>Test<br></body></html>"); echo $doc->saveHTML(); ?>

参见

DOMDocument->loadHTMLFile()

DOMDocument->saveHTML()

DOMDocument->saveHTMLFile()

DOMDocument->loadHTMLFile()

(no version information, might be only in CVS)

DOMDocument->loadHTMLFile() -- Load HTML from a file

说明

class DOMDocument {

bool loadHTMLFile ( string filename )

}

The function parses the HTML document in the file named filename. Unlike loading XML, HTML does not have to be well-formed to load.

This function may also be called statically to load and create a DOMDocument object. The static invocation may be used when no DOMDocument properties need to be set prior to loading.

参数

filename: The path to the HTML file.

返回值

如果成功则返回 TRUE，失败则返回 FALSE。

范例

例子 1. Creating a Document
<?php $doc = DOMDocument::loadHTMLFile("filename.html"); print $doc->saveHTML(); $doc = new DOMDocument(); $doc->loadHTMLFile("filename.html"); print $doc->saveHTML(); ?>

参见

DOMDocument->loadHTML()

DOMDocument->saveHTML()

DOMDocument->saveHTMLFile()

DOMDocument->loadXML()

(no version information, might be only in CVS)

DOMDocument->loadXML() -- Load XML from a string

说明

class DOMDocument {

bool loadXML ( string source [, int options] )

}

Loads an XML document from a string.

This method may also be called statically to load and create a DOMDocument object. The static invocation may be used when no DOMDocument properties need to be set prior to loading.

参数

source: The string containing the XML.

返回值

如果成功则返回 TRUE，失败则返回 FALSE。

范例

例子 1. Creating a Document
<?php $doc = DOMDocument::loadXML('<root><node/></root>'); echo $doc->saveXML(); $doc = new DOMDocument(); $doc->loadXML('<root><node/></root>'); echo $doc->saveXML(); ?>

参见

DOMDocument->load()

DOMDocument->save()

DOMDocument->saveXML()

DOMDocument->normalize()

(no version information, might be only in CVS)

DOMDocument->normalize() -- Normalizes the document

说明

class DOMDocument {

void normalize ( void )

}

Normalizes the document.

返回值

无返回值。

参见

DOMNode->normalize()

DOMDocument->relaxNGValidate()

(no version information, might be only in CVS)

DOMDocument->relaxNGValidate() -- Performs relaxNG validation on the document

说明

class DOMDocument {

bool relaxNGValidate ( string filename )

}

Performs relaxNG validation on the document based on the given RNG schema.

参数

filename: The RNG file.

返回值

如果成功则返回 TRUE，失败则返回 FALSE。

参见

DOMDocument->relaxNGValidateSource()

(no version information, might be only in CVS)

DOMDocument->relaxNGValidateSource() -- Performs relaxNG validation on the document

说明

class DOMDocument {

bool relaxNGValidateSource ( string source )

}

Performs relaxNG validation on the document based on the given RNG source.

参数

source: A string containing the RNG schema.

返回值

如果成功则返回 TRUE，失败则返回 FALSE。

参见

DOMDocument->saveHTMLFile()

DOMDocument->save()

(no version information, might be only in CVS)

DOMDocument->save() -- Dumps the internal XML tree back into a file

说明

class DOMDocument {

mixed save ( string filename [, integer options] )

}

Creates an XML document from the DOM representation. This function is usually called after building a new dom document from scratch as in the example below.

参数

filename: The path to the saved XML document.
options: Additional Options. Currently only LIBXML_NOEMPTYTAG is supported.

返回值

Returns the number of bytes written or FALSE if an error occurred.

更新日志

版本	说明
5.1.0	Added the `options` parameter

范例

例子 1. Saving a DOM tree into a file
<?php $doc = new DOMDocument('1.0'); // we want a nice output $doc->formatOutput = true; $root = $doc->createElement('book'); $root = $doc->appendChild($root); $title = $doc->createElement('title'); $title = $root->appendChild($title); $text = $doc->createTextNode('This is the title'); $text = $title->appendChild($text); echo 'Wrote: ' . $doc->save("/tmp/test.xml") . ' bytes'; // Wrote: 72 bytes ?>

参见

DOMDocument->saveXML()

DOMDocument->load()

DOMDocument->loadXML()

DOMDocument->saveHTML()

(no version information, might be only in CVS)

DOMDocument->saveHTML() -- Dumps the internal document into a string using HTML formatting

说明

class DOMDocument {

string saveHTML ( void )

}

Creates an HTML document from the DOM representation. This function is usually called after building a new dom document from scratch as in the example below.

返回值

Returns the HTML, or FALSE if an error occurred.

范例

例子 1. Saving a HTML tree into a string
<?php $doc = new DOMDocument('1.0'); // we want a nice output $doc->formatOutput = true; $root = $doc->createElement('html'); $root = $doc->appendChild($root); $head = $doc->createElement('head'); $head = $root->appendChild($head); $title = $doc->createElement('title'); $title = $head->appendChild($title); $text = $doc->createTextNode('This is the title'); $text = $title->appendChild($text); echo $doc->saveHTML(); ?>

参见

DOMDocument->loadHTML()

DOMDocument->loadHTMLFile()

DOMDocument->saveHTMLFile()

(no version information, might be only in CVS)

DOMDocument->saveHTMLFile() -- Dumps the internal document into a file using HTML formatting

说明

class DOMDocument {

int saveHTMLFile ( string filename )

}

Creates an HTML document from the DOM representation. This function is usually called after building a new dom document from scratch as in the example below.

参数

filename: The path to the saved HTML document.

返回值

Returns the number of bytes written or FALSE if an error occurred.

范例

例子 1. Saving a HTML tree into a file
<?php $doc = new DOMDocument('1.0'); // we want a nice output $doc->formatOutput = true; $root = $doc->createElement('html'); $root = $doc->appendChild($root); $head = $doc->createElement('head'); $head = $root->appendChild($head); $title = $doc->createElement('title'); $title = $head->appendChild($title); $text = $doc->createTextNode('This is the title'); $text = $title->appendChild($text); echo 'Wrote: ' . $doc->saveHTMLFile("/tmp/test.html") . ' bytes'; // Wrote: 129 bytes ?>

参见

DOMDocument->saveHTML()

DOMDocument->loadHTML()

DOMDocument->loadHTMLFile()

DOMDocument->saveXML()

(no version information, might be only in CVS)

DOMDocument->saveXML() -- Dumps the internal XML tree back into a string

说明

class DOMDocument {

string saveXML ( [DOMNode node [, integer options]] )

}

Creates an XML document from the DOM representation. This function is usually called after building a new dom document from scratch as in the example below.

参数

node: Use this parameter to output only a specific node without XML declaration rather than the entire document.
options: Additional Options. Currently only LIBXML_NOEMPTYTAG is supported.

返回值

Returns the XML, or FALSE if an error occurred.

异常

DOM_WRONG_DOCUMENT_ERR: Raised if node is from another document.

更新日志

版本	说明
5.1.0	Added the `options` parameter

范例

例子 1. Saving a DOM tree into a string
<?php $doc = new DOMDocument('1.0'); // we want a nice output $doc->formatOutput = true; $root = $doc->createElement('book'); $root = $doc->appendChild($root); $title = $doc->createElement('title'); $title = $root->appendChild($title); $text = $doc->createTextNode('This is the title'); $text = $title->appendChild($text); echo "Retrieving all the document:\n"; echo $doc->saveXML() . "\n"; echo "Retrieving only the title part:\n"; echo $doc->saveXML($title); ?>
上例将输出：
Retrieving all the document: <?xml version="1.0"?> <book> <title>This is the title</title> </book> Retrieving only the title part: <title>This is the title</title>

参见

DOMDocument->save()

DOMDocument->load()

DOMDocument->loadXML()

DOMDocument->schemaValidate()

(no version information, might be only in CVS)

DOMDocument->schemaValidate() -- Validates a document based on a schema

说明

class DOMDocument {

bool schemaValidate ( string filename )

}

Validates a document based on the given schema file.

参数

filename: The path to the schema.

返回值

如果成功则返回 TRUE，失败则返回 FALSE。

参见

DOMDocument->schemaValidateSource()

(no version information, might be only in CVS)

DOMDocument->schemaValidateSource() -- Validates a document based on a schema

说明

class DOMDocument {

bool schemaValidateSource ( string source )

}

Validates a document based on a schema defined in the given string.

参数

source: A string containing the schema.

返回值

如果成功则返回 TRUE，失败则返回 FALSE。

参见

(no version information, might be only in CVS)

DOMDocument->validate() -- Validates the document based on its DTD

说明

class DOMDocument {

bool validate ( void )

}

Validates the document based on its DTD.

You can also use the validateOnParse property of DOMDocument to make a DTD validation.

返回值

如果成功则返回 TRUE，失败则返回 FALSE。 If the document have no DTD attached, this method will return FALSE.

范例

例子 1. Example of DTD validation
<?php $dom = new DOMDocument; $dom->Load('book.xml'); if ($dom->validate()) { echo "This document is valid!\n"; } ?>
You can also validate your XML file while loading it:
<?php $dom = new DOMDocument; $dom->validateOnParse = true; $dom->Load('book.xml'); ?>

参见

DOMDocument->xinclude()

(no version information, might be only in CVS)

DOMDocument->xinclude() -- Substitutes XIncludes in a DOMDocument Object

说明

class DOMDocument {

int xinclude ( [int options] )

}

This method substitutes XIncludes in a DOMDocument object.

注: Due to libxml2 automatically resolving entities, this method will produce unexpected results if the included XML file have an attached DTD.

参数

options: libxml parameters. Available since PHP 5.1.0 and Libxml 2.6.7.

返回值

Returns the number of XIncludes in the document.

范例

例子 1. DOMDocument->xinclude() example
<?php $xml = <<<EOD <?xml version="1.0" ?> <chapter xmlns:xi="http://www.w3.org/2001/XInclude"> <title>Books of the other guy..</title> <para> <xi:include href="book.xml"> <xi:fallback> <error>xinclude: book.xml not found</error> </xi:fallback> </xi:include> </para> </chapter> EOD; $dom = new DOMDocument; // let's have a nice output $dom->preserveWhiteSpace = false; $dom->formatOutput = true; // load the XML string defined above $dom->loadXML($xml); // substitute xincludes $dom->xinclude(); echo $dom->saveXML(); ?>
上例的输出类似于：
<?xml version="1.0"?> <chapter xmlns:xi="http://www.w3.org/2001/XInclude"> <title>Books of the other guy..</title> <para> <row xml:base="/home/didou/book.xml"> <entry>The Grapes of Wrath</entry> <entry>John Steinbeck</entry> <entry>en</entry> <entry>0140186409</entry> </row> <row xml:base="/home/didou/book.xml"> <entry>The Pearl</entry> <entry>John Steinbeck</entry> <entry>en</entry> <entry>014017737X</entry> </row> <row xml:base="/home/didou/book.xml"> <entry>Samarcande</entry> <entry>Amine Maalouf</entry> <entry>fr</entry> <entry>2253051209</entry> </row> </para> </chapter>

DOMElement->__construct()

(no version information, might be only in CVS)

DOMElement->__construct() -- Creates a new DOMElement object

说明

class DOMElement {

__construct ( string name [, string value [, string namespaceURI]] )

}

Creates a new DOMElement object. This object is read only. It may be appended to a document, but additional nodes may not be appended to this node until the node is associated with a document. To create a writeable node, use DOMDocument->createElement() or DOMDocument->createElementNS().

参数

name: The tag name of the element. When also passing in namespaceURI, the element name may take a prefix to be associated with the URI.
value: The value of the element.
namespaceURI: A namespace URI to create the element within a specific namespace.

范例

例子 1. Creating a new DOMElement
<?php $dom = new DOMDocument('1.0', 'iso-8859-1'); $element = $dom->appendChild(new DOMElement('root')); $element_ns = new DOMElement('pr:node1', 'thisvalue', 'http://xyz'); $element->appendChild($element_ns); echo $dom->saveXML(); /* <?xml version="1.0" encoding="iso-8859-1"?> <root><pr:node1 xmlns:pr="http://xyz">thisvalue</pr:node1></root> */ ?>

参见

DOMElement->getAttribute()

(no version information, might be only in CVS)

DOMElement->getAttribute() -- Returns value of attribute

说明

class DOMElement {

string getAttribute ( string name )

}

Gets the value of the attribute with name name for the current node.

参数

name: The name of the attribute.

返回值

The value of the attribute, or an empty string if no attribute with the given name is found.

参见

DOMElement->setAttribute()

DOMElement->removeAttribute()

DOMElement->getAttributeNode()

(no version information, might be only in CVS)

DOMElement->getAttributeNode() -- Returns attribute node

说明

class DOMElement {

DOMAttr getAttributeNode ( string name )

}

Returns the attribute node with name name for the current element.

参数

name: The name of the attribute.

返回值

The attribute node.

参见

DOMElement->setAttributeNode()

DOMElement->getAttributeNodeNS()

(no version information, might be only in CVS)

DOMElement->getAttributeNodeNS() -- Returns attribute node

说明

class DOMElement {

DOMAttr getAttributeNodeNS ( string namespaceURI, string localName )

}

Returns the attribute node in namespace namespaceURI with local name localName for the current node.

参数

namespaceURI: The namespace URI.
localName: The local name.

返回值

The attribute node.

参见

DOMElement->setAttributeNodeNS()

DOMElement->getAttributeNS()

(no version information, might be only in CVS)

DOMElement->getAttributeNS() -- Returns value of attribute

说明

class DOMElement {

string getAttributeNS ( string namespaceURI, string localName )

}

Gets the value of the attribute in namespace namespaceURI with local name localName for the current node.

参数

namespaceURI: The namespace URI.
localName: The local name.

返回值

The value of the attribute, or an empty string if no attribute with the given localName and namespaceURI is found.

参见

DOMElement->setAttributeNS()

DOMElement->removeAttributeNS()

DOMElement->getElementsByTagName()

(no version information, might be only in CVS)

DOMElement->getElementsByTagName() -- Gets elements by tagname

说明

class DOMElement {

DOMNodeList getElementsByTagName ( string name )

}

This function returns a new instance of the class DOMNodeList of all descendant elements with a given tag name, in the order in which they are encountered in a preorder traversal of this element tree.

参数

name: The tag name. Use * to return all elements within the element tree.

返回值

This function returns a new instance of the class DOMNodeList of all matched elements.

参见

DOMElement->getElementsByTagNameNS()

(no version information, might be only in CVS)

DOMElement->getElementsByTagNameNS() -- Get elements by namespaceURI and localName

说明

class DOMElement {

DOMNodeList getElementsByTagNameNS ( string namespaceURI, string localName )

}

This function fetch all the descendant elements with a given localName and namespaceURI.

参数

namespaceURI: The namespace URI.
localName: The local name. Use * to return all elements within the element tree.

返回值

This function returns a new instance of the class DOMNodeList of all matched elements in the order in which they are encountered in a preorder traversal of this element tree.

参见

DOMElement->getElementsByTagName()

DOMElement->hasAttribute()

(no version information, might be only in CVS)

DOMElement->hasAttribute() -- Checks to see if attribute exists

说明

class DOMElement {

bool hasAttribute ( string name )

}

Indicates whether attribute named name exists as a member of the element.

参数

name: The attribute name.

返回值

如果成功则返回 TRUE，失败则返回 FALSE。

参见

DOMElement->getAttribute()

DOMElement->setAttribute()

DOMElement->removeAttribute()

DOMElement->hasAttributeNS()

(no version information, might be only in CVS)

DOMElement->hasAttributeNS() -- Checks to see if attribute exists

说明

class DOMElement {

bool hasAttributeNS ( string namespaceURI, string localName )

}

Indicates whether attribute in namespace namespaceURI named localName exists as a member of the element.

参数

namespaceURI: The namespace URI.
localName: The local name.

返回值

如果成功则返回 TRUE，失败则返回 FALSE。

参见

DOMElement->getAttributeNS()

DOMElement->setAttributeNS()

DOMElement->removeAttributeNS()

DOMElement->removeAttribute()

(no version information, might be only in CVS)

DOMElement->removeAttribute() -- Removes attribute

说明

class DOMElement {

bool removeAttribute ( string name )

}

Removes attribute named name from the element.

参数

name: The name of the attribute.

返回值

如果成功则返回 TRUE，失败则返回 FALSE。

异常

DOM_NO_MODIFICATION_ALLOWED_ERR: Raised if the node is readonly.

参见

DOMElement->getAttribute()

DOMElement->setAttribute()

DOMElement->removeAttributeNode()

(no version information, might be only in CVS)

DOMElement->removeAttributeNode() -- Removes attribute

说明

class DOMElement {

bool removeAttributeNode ( DOMAttr oldnode )

}

Removes attribute oldnode from the element.

参数

oldnode: The attribute node.

返回值

如果成功则返回 TRUE，失败则返回 FALSE。

异常

DOM_NO_MODIFICATION_ALLOWED_ERR: Raised if the node is readonly.
DOM_NOT_FOUND_ERROR: Raised if oldnode is not an attribute of the element.

参见

DOMElement->getAttributeNode()

DOMElement->setAttributeNode()

DOMElement->removeAttributeNS()

(no version information, might be only in CVS)

DOMElement->removeAttributeNS() -- Removes attribute

说明

class DOMElement {

bool removeAttributeNS ( string namespaceURI, string localName )

}

Removes attribute is namespace namespaceURI named localName from the element.

参数

namespaceURI: The namespace URI.
localName: The local name.

返回值

如果成功则返回 TRUE，失败则返回 FALSE。

异常

DOM_NO_MODIFICATION_ALLOWED_ERR: Raised if the node is readonly.

参见

DOMElement->getAttributeNS()

DOMElement->setAttributeNS()

DOMElement->setAttribute()

(no version information, might be only in CVS)

DOMElement->setAttribute() -- Adds new attribute

说明

class DOMElement {

bool setAttribute ( string name, string value )

}

Sets an attribute with name name to the given value. If the attribute does not exist, it will be created.

参数

name: The name of the attribute.
value: The value of the attribute.

返回值

如果成功则返回 TRUE，失败则返回 FALSE。

异常

DOM_NO_MODIFICATION_ALLOWED_ERR: Raised if the node is readonly.

范例

例子 1. Setting an attribute
<?php $doc = new DOMDocument("1.0"); $node = $doc->createElement("para"); $newnode = $doc->appendChild($node); $newnode->setAttribute("align", "left"); ?>

参见

DOMElement->getAttribute()

DOMElement->removeAttribute()

DOMElement->setAttributeNode()

(no version information, might be only in CVS)

DOMElement->setAttributeNode() -- Adds new attribute node to element

说明

class DOMElement {

DOMAttr setAttributeNode ( DOMAttr attr )

}

Adds new attribute node attr to element.

参数

attr: The attribute node.

返回值

Returns old node if the attribute has been replaced or NULL.

异常

DOM_NO_MODIFICATION_ALLOWED_ERR: Raised if the node is readonly.

参见

DOMElement->getAttributeNode()

DOMElement->setAttributeNodeNS()

(no version information, might be only in CVS)

DOMElement->setAttributeNodeNS() -- Adds new attribute node to element

说明

class DOMElement {

DOMAttr setAttributeNodeNS ( DOMAttr attr )

}

Adds new attribute node attr to element.

参数

name: The attribute node.

返回值

Returns the old node if the attribute has been replaced.

异常

DOM_NO_MODIFICATION_ALLOWED_ERR: Raised if the node is readonly.

参见

DOMElement->getAttributeNodeNS()

DOMElement->setAttributeNS()

(no version information, might be only in CVS)

DOMElement->setAttributeNS() -- Adds new attribute

说明

class DOMElement {

void setAttributeNS ( string namespaceURI, string qualifiedName, string value )

}

Sets an attribute with namespace namespaceURI and name name to the given value. If the attribute does not exist, it will be created.

参数

namespaceURI: The namespace URI.
qualifiedName: The qualified name of the attribute, as prefix:tagname.
value: The value of the attribute.

返回值

无返回值。

异常

DOM_NO_MODIFICATION_ALLOWED_ERR: Raised if the node is readonly.
DOM_NAMESPACE_ERR: Raised if qualifiedName is a malformed qualified name, or if qualifiedName has a prefix and namespaceURI is NULL.

参见

DOMElement->getAttributeNS()

DOMElement->removeAttributeNS()

DOMAttr->__construct()

(no version information, might be only in CVS)

DOMAttr->__construct() -- Creates a new DOMEntityReference object

说明

class DOMEntityReference {

__construct ( string name )

}

Creates a new DOMEntityReference object.

参数

name: The name of the entity reference.

范例

例子 1. Creating a new DOMEntityReference
<?php $dom = new DOMDocument('1.0', 'iso-8859-1'); $element = $dom->appendChild(new DOMElement('root')); $entity = $element->appendChild(new DOMEntityReference('nbsp')); echo $dom->saveXML(); /* <?xml version="1.0" encoding="iso-8859-1"?><root> </root> */ ?>

参见

DOMDocument->__construct()

DOMImplementation->__construct()

(no version information, might be only in CVS)

DOMImplementation->__construct() -- Creates a new DOMImplementation object

说明

class DOMImplementation {

__construct ( (void); )

}

Creates a new DOMImplementation object.

DOMImplementation->createDocument()

(no version information, might be only in CVS)

DOMImplementation->createDocument() -- Creates a DOMDocument object of the specified type with its document element

说明

class DOMImplementation {

DOMDocument createDocument ( [string namespaceURI [, string qualifiedName [, DOMDocumentType doctype]]] )

}

Creates a DOMDocument object of the specified type with its document element.

参数

namespaceURI: The namespace URI of the document element to create.
qualifiedName: The qualified name of the document element to create.
doctype: The type of document to create or NULL.

返回值

A new DOMDocument object. If namespaceURI, qualifiedName, and doctype are null, the returned DOMDocument is empty with no document element

异常

DOM_WRONG_DOCUMENT_ERR: Raised if doctype has already been used with a different document or was created from a different implementation.
DOM_NAMESPACE_ERR: Raised if there is an error with the namespace, as determined by namespaceURI and qualifiedName.

参见

DOMImplementation->createDocumentType()

(no version information, might be only in CVS)

DOMImplementation->createDocumentType() -- Creates an empty DOMDocumentType object

说明

class DOMImplementation {

DOMDocumentType createDocumentType ( [string qualifiedName [, string publicId [, string systemId]]] )

}

Creates an empty DOMDocumentType object. Entity declarations and notations are not made available. Entity reference expansions and default attribute additions do not occur.

参数

qualifiedName: The qualified name of the document type to create.
publicId: The external subset public identifier.
systemId: The external subset system identifier.

返回值

A new DOMDocumentType node with its ownerDocument set to NULL.

范例

例子 1. Creating a document with an attached DTD
<?php // Creates an instance of the DOMImplementation class $imp = new DOMImplementation; // Creates a DOMDocumentType instance $dtd = $imp->createDocumentType('graph', '', 'graph.dtd'); // Creates a DOMDocument instance $dom = $imp->createDocument("", "", $dtd); // Set other properties $dom->encoding = 'UTF-8'; $dom->standalone = false; // Create an empty element $element = $dom->createElement('graph'); // Append the element $dom->appendChild($element); // Retrieve and print the document echo $dom->saveXML(); ?>
上例将输出：
<?xml version="1.0" encoding="UTF-8" standalone="no"?> <!DOCTYPE graph SYSTEM "graph.dtd"> <graph/>

异常

DOM_NAMESPACE_ERR: Raised if there is an error with the namespace, as determined by qualifiedName.

参见

DOMImplementation->createDocument()

DOMImplementation->hasFeature()

(no version information, might be only in CVS)

DOMImplementation->hasFeature() -- Test if the DOM implementation implements a specific feature

说明

class DOMImplementation {

bool hasFeature ( string feature, string version )

}

Test if the DOM implementation implements a specific feature.

You can find a list of all features in the Conformance section of the DOM specification.

参数

feature: The feature to test.
version: The version number of the feature to test. In level 2, this can be either 2.0 or 1.0.

返回值

如果成功则返回 TRUE，失败则返回 FALSE。

范例

例子 1. Testing your DOM Implementation

<?php

$features = array(
  'Core'           => 'Core module',
  'XML'            => 'XML module',
  'HTML'           => 'HTML module',
  'Views'          => 'Views module',
  'Stylesheets'    => 'Style Sheets module',
  'CSS'            => 'CSS module',
  'CSS2'           => 'CSS2 module',
  'Events'         => 'Events module',
  'UIEvents'       => 'User interface Events module',
  'MouseEvents'    => 'Mouse Events module',
  'MutationEvents' => 'Mutation Events module',
  'HTMLEvents'     => 'HTML Events module',
  'Range'          => 'Range module',
  'Traversal'      => 'Traversal module'
);
               
foreach ($features as $key => $name) {
  if (DOMImplementation::hasFeature($key, '2.0')) {
    echo "Has feature $name\n";
  } else {
    echo "Missing feature $name\n";
  }
}

?>

参见

DOMNode->isSupported()

DOMNamedNodeMap->getNamedItem()

(no version information, might be only in CVS)

DOMNamedNodeMap->getNamedItem() -- Retrieves a node specified by name

说明

class DOMNamedNodeMap {

DOMNode getNamedItem ( string name )

}

Retrieves a node specified by its nodeName.

参数

name: The nodeName of the node to retrieve.

返回值

A node (of any type) with the specified nodeName, or NULL if no node is found.

参见

DOMNamedNodeMap->getNamedItemNS()

(no version information, might be only in CVS)

DOMNamedNodeMap->getNamedItemNS() -- Retrieves a node specified by local name and namespace URI

说明

class DOMNamedNodeMap {

DOMNode getNamedItemNS ( string namespaceURI, string localName )

}

Retrieves a node specified by localName and namespaceURI.

参数

namespaceURI: The namespace URI of the node to retrieve.
localName: The local name of the node to retrieve.

返回值

A node (of any type) with the specified local name and namespace URI, or NULL if no node is found.

参见

DOMNamedNodeMap->getNamedItem()

DOMNamedNodeMap->item()

(no version information, might be only in CVS)

DOMNamedNodeMap->item() -- Retrieves a node specified by index

说明

class DOMNamedNodeMap {

DOMNode item ( int index )

}

Retrieves a node specified by index within the DOMNamedNodeMap object.

参数

index: Index into this map.

返回值

The node at the indexth position in the map, or NULL if that is not a valid index (greater than or equal to the number of nodes in this map).

DOMNode->appendChild()

(no version information, might be only in CVS)

DOMNode->appendChild() -- Adds new child at the end of the children

说明

class DOMNode {

DOMNode appendChild ( DOMNode newnode )

}

This functions appends a child to an existing list of children or creates a new list of children. The child can be created with e.g. DOMDocument->createElement(), DOMDocument->createTextNode() etc. or simply by using any other node.

参数

newnode: The appended child.

返回值

The node added.

异常

DOM_NO_MODIFICATION_ALLOWED_ERR: Raised if this node is readonly or if the previous parent of the node being inserted is readonly.
DOM_HIERARCHY_REQUEST_ERR: Raised if this node is of a type that does not allow children of the type of the newnode node, or if the node to append is one of this node's ancestors or this node itself.
DOM_WRONG_DOCUMENT_ERR: Raised if newnode was created from a different document than the one that created this node.

范例

The following example will add a new element node to a fresh document.
例子 1. Adding a child
<?php $doc = new DOMDocument; $node = $doc->createElement("para"); $newnode = $doc->appendChild($node); echo $doc->saveXML(); ?>

参见

DOMNode->removeChild()

DOMNode->replaceChild()

DOMNode->cloneNode()

(no version information, might be only in CVS)

DOMNode->cloneNode() -- Clones a node

说明

class DOMNode {

DOMNode cloneNode ( [bool deep] )

}

Creates a copy of the node.

参数

deep: Indicates whether to copy all descendant nodes. This parameter is defaulted to FALSE.

返回值

The cloned node.

DOMNode->hasAttributes()

(no version information, might be only in CVS)

DOMNode->hasAttributes() -- Checks if node has attributes

说明

class DOMNode {

bool hasAttributes ( void )

}

This method checks if the node has attributes. The tested node have to be an XML_ELEMENT_NODE.

返回值

如果成功则返回 TRUE，失败则返回 FALSE。

参见

DOMNode->hasChildNodes()

(no version information, might be only in CVS)

DOMNode->hasChildNodes() -- Checks if node has children

说明

class DOMNode {

bool hasChildNodes ( void )

}

This function checks if the node has children.

返回值

如果成功则返回 TRUE，失败则返回 FALSE。

参见

DOMNode->hasAttributes()

DOMNode->insertBefore()

(no version information, might be only in CVS)

DOMNode->insertBefore() -- Adds a new child before a reference node

说明

class DOMNode {

DOMNode insertBefore ( DOMNode newnode [, DOMNode refnode] )

}

This function inserts a new node right before the reference node. If you plan to do further modifications on the appended child you must use the returned node.

参数

newnode: The new node.
refnode: The reference node. If not supplied, newnode is appended to the children.

返回值

The inserted node.

异常

DOM_NO_MODIFICATION_ALLOWED_ERR: Raised if this node is readonly or if the previous parent of the node being inserted is readonly.
DOM_HIERARCHY_REQUEST_ERR: Raised if this node is of a type that does not allow children of the type of the newnode node, or if the node to append is one of this node's ancestors or this node itself.
DOM_WRONG_DOCUMENT_ERR: Raised if newnode was created from a different document than the one that created this node.
DOM_NOT_FOUND: Raised if refnode is not a child of this node.

DOMNode->isSameNode()

(no version information, might be only in CVS)

DOMNode->isSameNode() -- Indicates if two nodes are the same node

说明

class DOMNode {

bool isSameNode ( DOMNode node )

}

This function indicates if two nodes are the same node. The comparison is not based on content

参数

node: The compared node.

返回值

如果成功则返回 TRUE，失败则返回 FALSE。

DOMNode->isSupported()

(no version information, might be only in CVS)

DOMNode->isSupported() -- Checks if feature is supported for specified version

说明

class DOMNode {

bool isSupported ( string feature, string version )

}

Checks if the asked feature is supported for the specified version.

参数

feature: The feature to test. See the example of DOMImplementation->hasFeature() for a list of features.
version: The version number of the feature to test.

返回值

如果成功则返回 TRUE，失败则返回 FALSE。

参见

DOMImplementation->hasFeature()

DOMNode->lookupNamespaceURI()

(no version information, might be only in CVS)

DOMNode->lookupNamespaceURI() -- Gets the namespace URI of the node based on the prefix

说明

class DOMNode {

string lookupNamespaceURI ( string prefix )

}

Gets the namespace URI of the node based on the prefix.

参数

prefix: The prefix of the namespace.

返回值

The namespace URI of the node.

参见

DOMNode->lookupPrefix()

(no version information, might be only in CVS)

DOMNode->lookupPrefix() -- Gets the namespace prefix of the node based on the namespace URI

说明

class DOMNode {

string lookupPrefix ( string namespaceURI )

}

Gets the namespace prefix of the node based on the namespace URI.

参数

namespaceURI: The namespace URI.

返回值

The prefix of the namespace.

参见

DOMNode->lookupNamespaceURI()

DOMNode->normalize()

(no version information, might be only in CVS)

DOMNode->normalize() -- Normalizes the node

说明

class DOMNode {

void normalize ( void )

}

Normalizes the node.

返回值

无返回值。

参见

DOMDocument->normalize()

DOMNode->removeChild()

(no version information, might be only in CVS)

DOMNode->removeChild() -- Removes child from list of children

说明

class DOMNode {

DOMNode removeChild ( DOMNode oldnode )

}

This functions removes a child from a list of children.

参数

oldnode: The removed child.

返回值

If the child could be removed the functions returns the old child.

异常

DOM_NO_MODIFICATION_ALLOWED_ERR: Raised if this node is readonly.
DOM_NOT_FOUND: Raised if oldnode is not a child of this node.

范例

The following example will delete the chapter element of our XML document.
例子 1. Removing a child
<?php $doc = new DOMDocument; $doc->load('book.xml'); $book = $doc->documentElement; // we retrieve the chapter and remove it from the book $chapter = $book->getElementsByTagName('chapter')->item(0); $oldchapter = $book->removeChild($chapter); echo $doc->saveXML(); ?>
上例将输出：
<?xml version="1.0" encoding="iso-8859-1"?> <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd"> <book id="listing"> <title>My lists</title> </book>

参见

DOMNode->replaceChild()

(no version information, might be only in CVS)

DOMNode->replaceChild() -- Replaces a child

说明

class DOMNode {

DOMNode replaceChild ( DOMNode newnode, DOMNode oldnode )

}

This function replaces the child oldnode with the passed new node. If the new node is already a child it will not be added a second time. If the replacement succeeds the old node is returned.

参数

newnode: The new node. It must be a member of the target document, i.e. created by one of the DOMDocument->createXXX() methods or imported in the document by DOMDocument->importNode().
oldnode: The old node.

返回值

The old node or FALSE if an error occur.

异常

DOM_NO_MODIFICATION_ALLOWED_ERR: Raised if this node is readonly or if the previous parent of the node being inserted is readonly.
DOM_HIERARCHY_REQUEST_ERR: Raised if this node is of a type that does not allow children of the type of the newnode node, or if the node to put in is one of this node's ancestors or this node itself.
DOM_WRONG_DOCUMENT_ERR: Raised if newnode was created from a different document than the one that created this node.
DOM_NOT_FOUND: Raised if oldnode is not a child of this node.

参见

DOMNode->removeChild()

DOMNodelist->item()

(no version information, might be only in CVS)

DOMNodelist->item() -- Retrieves a node specified by index

说明

class DOMNodeList {

DOMNode item ( int index )

}

Retrieves a node specified by index within the DOMNodeList object.

提示: If you need to know the number of nodes in the collection, use the length property of the DOMNodeList object.

参数

index: Index of the node into the collection.

返回值

The node at the indexth position in the DOMNodeList, or NULL if that is not a valid index.

范例

例子 1. Traversing all the entries of the table
<?php $doc = new DOMDocument; $doc->load('book.xml'); $items = $doc->getElementsByTagName('entry'); for ($i = 0; $i < $items->length; $i++) { echo $items->item($i)->nodeValue . "\n"; } ?>
Alternatively, you can use foreach, which is a much more convenient way:
<?php foreach ($items as $item) { echo $item->nodeValue . "\n"; } ?>
上例将输出：
Title Author Language ISBN The Grapes of Wrath John Steinbeck en 0140186409 The Pearl John Steinbeck en 014017737X Samarcande Amine Maalouf fr 2253051209

DOMProcessingInstruction->__construct()

(no version information, might be only in CVS)

DOMProcessingInstruction->__construct() -- Creates a new DOMProcessingInstruction object

说明

class DOMProcessingInstruction {

__construct ( string name [, string value] )

}

Creates a new DOMProcessingInstruction object. This object is read only. It may be appended to a document, but additional nodes may not be appended to this node until the node is associated with a document. To create a writeable node, use DOMDocument->createProcessingInstruction().

参数

name: The tag name of the processing instruction.
value: The value of the processing instruction.

范例

例子 1. Creating a new DOMProcessingInstruction
<?php $dom = new DOMDocument('1.0', 'UTF-8'); $html = $dom->appendChild(new DOMElement('html')); $body = $html->appendChild(new DOMElement('body')); $pinode = new DOMProcessingInstruction('php', 'echo "Hello World"; '); $body->appendChild($pinode); echo $dom->saveXML(); ?>
上例将输出：
<?xml version="1.0" encoding="UTF-8"?> <html><body><?php echo "Hello World"; ?></body></html>

参见

DOMText->__construct()

(no version information, might be only in CVS)

DOMText->__construct() -- Creates a new DOMText object

说明

class DOMText {

__construct ( [string value] )

}

Creates a new DOMText object.

参数

value: The value of the text node. If not supplied an empty text node is created.

范例

例子 1. Creating a new DOMText
<?php $dom = new DOMDocument('1.0', 'iso-8859-1'); $element = $dom->appendChild(new DOMElement('root')); $text = $element->appendChild(new DOMText('root value')); echo $dom->saveXML(); /* <?xml version="1.0" encoding="iso-8859-1"?><root>root value</root> */ ?>

参见

DomElement->get_attribute()

DOMText->isWhitespaceInElementContent()

(no version information, might be only in CVS)

DOMText->isWhitespaceInElementContent() -- Indicates whether this text node contains whitespace

说明

class DOMText {

bool isWhitespaceInElementContent ( void )

}

Indicates whether this text node contains whitespace. The text node is determined to contain whitespace in element content during the load of the document.

返回值

如果成功则返回 TRUE，失败则返回 FALSE。

DOMText->splitText()

(no version information, might be only in CVS)

DOMText->splitText() -- Breaks this node into two nodes at the specified offset

说明

class DOMText {

DOMText splitText ( int offset )

}

Breaks this node into two nodes at the specified offset, keeping both in the tree as siblings.

After being split, this node will contain all the content up to the offset. If the original node had a parent node, the new node is inserted as the next sibling of the original node. When the offset is equal to the length of this node, the new node has no data.

参数

offset: The offset at which to split, starting from 0.

返回值

The new node of the same type, which contains all the content at and after the offset.

DOMXPath->__construct()

(no version information, might be only in CVS)

DOMXPath->__construct() -- Creates a new DOMXPath object

说明

class DOMXPath {

__construct ( DOMDocument doc )

}

Creates a new DOMXPath object.

参数

doc: The DOMDocument associated with the DOMXPath.

DOMXPath->evaluate()

(no version information, might be only in CVS)

DOMXPath->evaluate() -- Evaluates the given XPath expression and returns a typed result if possible.

说明

class DOMXPath {

mixed evaluate ( string expression [, DOMNode contextnode] )

}

Executes the given XPath expression and returns a typed result if possible.

参数

expression: The XPath expression to execute.
contextnode: The optional contextnode can be specified for doing relative XPath queries. By default, the queries are relative to the root element.

返回值

Returns a typed result if possible or a DOMNodeList containing all nodes matching the given XPath expression.

范例

例子 1. Getting the count of all the english books
<?php $doc = new DOMDocument; $doc->load('book.xml'); $xpath = new DOMXPath($doc); $tbody = $doc->getElementsByTagName('tbody')->item(0); // our query is relative to the tbody node $query = 'count(row/entry[. = "en"])'; $entries = $xpath->evaluate($query, $tbody); echo "There are $entries english books\n"; ?>
上例将输出：
There are 2 english books

参见

DOMXPath->query()

(no version information, might be only in CVS)

DOMXPath->query() -- Evaluates the given XPath expression

说明

class DOMXPath {

DOMNodeList query ( string expression [, DOMNode contextnode] )

}

Executes the given XPath expression.

参数

expression: The XPath expression to execute.
contextnode: The optional contextnode can be specified for doing relative XPath queries. By default, the queries are relative to the root element.

返回值

Returns a DOMNodeList containing all nodes matching the given XPath expression. Any expression which do not return nodes will return an empty DOMNodeList.

范例

例子 1. Getting all the english books
<?php $doc = new DOMDocument; // We don't want to bother with white spaces $doc->preserveWhiteSpace = false; $doc->Load('book.xml'); $xpath = new DOMXPath($doc); // We starts from the root element $query = '//book/chapter/para/informaltable/tgroup/tbody/row/entry[. = "en"]'; $entries = $xpath->query($query); foreach ($entries as $entry) { echo "Found {$entry->previousSibling->previousSibling->nodeValue}," . " by {$entry->previousSibling->nodeValue}\n"; } ?>
上例将输出：
Found The Grapes of Wrath, by John Steinbeck Found The Pearl, by John Steinbeck
We can also use the contextnode parameter to shorten our expression:
<?php $doc = new DOMDocument; $doc->preserveWhiteSpace = false; $doc->load('book.xml'); $xpath = new DOMXPath($doc); $tbody = $doc->getElementsByTagName('tbody')->item(0); // our query is relative to the tbody node $query = 'row/entry[. = "en"]'; $entries = $xpath->query($query, $tbody); foreach ($entries as $entry) { echo "Found {$entry->previousSibling->previousSibling->nodeValue}," . " by {$entry->previousSibling->nodeValue}\n"; } ?>

参见

DOMXPath->evaluate()

DOMXPath->registerNamespace()

(no version information, might be only in CVS)

DOMXPath->registerNamespace() -- Registers the namespace with the DOMXPath object

说明

class DOMXPath {

bool registerNamespace ( string prefix, string namespaceURI )

}

Registers the namespaceURI and prefix with the DOMXPath object.

参数

prefix: The prefix.
namespaceURI: The URI of the namespace.

返回值

如果成功则返回 TRUE，失败则返回 FALSE。

dom_import_simplexml

(PHP 5)

dom_import_simplexml -- Gets a DOMElement object from a SimpleXMLElement object

说明

DOMElement dom_import_simplexml ( SimpleXMLElement node )

This function takes the node node of class SimpleXML and makes it into a DOMElement node. This new object can then be used as a native DOMElement node.

参数

node: The SimpleXMLElement node.

返回值

The DOMElement node added or FALSE if any errors occur.

范例

例子 1. Import SimpleXML into DOM with dom_import_simplexml()

<?php

$sxe = simplexml_load_string('<books><book><title>blah</title></book></books>');

if ($sxe === false) {
    echo 'Error while parsing the document';
    exit;
}

$dom_sxe = dom_import_simplexml($sxe);
if (!$dom_sxe) {
    echo 'Error while converting XML';
    exit;
}

$dom = new DOMDocument('1.0');
$dom_sxe = $dom->importNode($dom_sxe, true);
$dom_sxe = $dom->appendChild($dom_sxe);

echo $dom->saveXML();

?>

参见

simplexml_import_dom()

XXX. DOM XML Functions

简介

The DOM XML extension has been overhauled in PHP 4.3.0 to better comply with the DOM standard. The extension still contains many old functions, but they should no longer be used. In particular, functions that are not object-oriented should be avoided.

The extension allows you to operate on an XML document with the DOM API. It also provides a function domxml_xmltree() to turn the complete XML document into a tree of PHP objects. Currently, this tree should be considered read-only - you can modify it, but this would not make any sense since DomDocument_dump_mem() cannot be applied to it. Therefore, if you want to read an XML file and write a modified version, use DomDocument_create_element(), DomDocument_create_text_node(), set_attribute(), etc. and finally the DomDocument_dump_mem() function.

注: 本扩展已被移动到 PECL 库中且自以下版本起不再被绑定到 PHP 中：5.0.0.

注: This extension is no longer marked experimental. It will, however, never be released with PHP 5, and will only be distributed with PHP 4. If you need DOM XML support with PHP 5 you can use the DOM extension. This domxml extension is not compatible with the DOM extension.

需求

This extension makes use of the GNOME XML library. Download and install this library. You will need at least libxml-2.4.14. To use DOM XSLT features you can use the libxslt library and EXSLT enhancements from http://www.exslt.org/. Download and install these libraries if you plan to use (enhanced) XSLT features. You will need at least libxslt-1.0.18.

安装

本 PECL 扩展未绑定于 PHP 中。进一步信息例如新版本，下载，源程序，维护者信息以及更新日志可以在此找到： http://pecl.php.net/package/domxml.

在 PHP 4 中本 PECL 扩展的源程序位于 PHP 源程序中的 ext/ 目录下或者在上面的 PECL 连接中。 This extension is only available if PHP was configured with --with-dom[=DIR]. Add --with-dom-xslt[=DIR] to include DOM XSLT support. DIR is the libxslt install directory. Add --with-dom-exslt[=DIR] to include DOM EXSLT support, where DIR is the libexslt install directory.

Windows users will enable php_domxml.dll inside of php.ini in order to use these functions. 在 PHP 4 中本 DLL 位于 PHP Windows 执行包中的 extensions/ 目录下。可以从 PHP 下载页面或者 http://snaps.php.net/ 下载此 PECL 扩展的 DLL 文件。 Also, there is one additional DLL that must be made available to your system's PATH in order for this extension to work. In PHP 4 this is in the dlls/ directory. It's name: For PHP <= 4.2.0, it's libxml2.dll. For PHP >= 4.3.0, it's iconv.dll. And as of PHP 5.0.0, iconv is compiled into your Windows PHP binaries by default so no extra DLL is needed.

Deprecated functions

There are quite a few functions that do not fit into the DOM standard and should no longer be used. These functions are listed in the following table. The function DomNode_append_child() has changed its behaviour. It now adds a child and not a sibling. If this breaks your application, use the non-DOM function DomNode_append_sibling().

表格 1. Deprecated functions and their replacements

Old function	New function
xmldoc	domxml_open_mem()
xmldocfile	domxml_open_file()
domxml_new_xmldoc	domxml_new_doc()
domxml_dump_mem	DomDocument_dump_mem()
domxml_dump_mem_file	DomDocument_dump_file()
DomDocument_dump_mem_file	DomDocument_dump_file()
DomDocument_add_root	DomDocument_create_element() followed by DomNode_append_child()
DomDocument_dtd	DomDocument_doctype()
DomDocument_root	DomDocument_document_element()
DomDocument_children	DomNode_child_nodes()
DomDocument_imported_node	No replacement.
DomNode_add_child	Create a new node with e.g. DomDocument_create_element() and add it with DomNode_append_child().
DomNode_children	DomNode_child_nodes()
DomNode_parent	DomNode_parent_node()
DomNode_new_child	Create a new node with e.g. DomDocument_create_element() and add it with DomNode_append_child().
DomNode_set_content	Create a new node with e.g. DomDocument_create_text_node() and add it with DomNode_append_child().
DomNode_get_content	Content is just a text node and can be accessed with DomNode_child_nodes().
DomNode_set_content	Content is just a text node and can be added with DomNode_append_child().

预定义常量

以下常量由本扩展模块定义，因此只有在本扩展模块被编译到 PHP 中，或者在运行时被动态加载后才有效。

表格 2. XML constants

Constant	Value	Description
`XML_ELEMENT_NODE` (integer)	1	Node is an element
`XML_ATTRIBUTE_NODE` (integer)	2	Node is an attribute
`XML_TEXT_NODE` (integer)	3	Node is a piece of text
`XML_CDATA_SECTION_NODE` (integer)	4
`XML_ENTITY_REF_NODE` (integer)	5
`XML_ENTITY_NODE` (integer)	6	Node is an entity like
`XML_PI_NODE` (integer)	7	Node is a processing instruction
`XML_COMMENT_NODE` (integer)	8	Node is a comment
`XML_DOCUMENT_NODE` (integer)	9	Node is a document
`XML_DOCUMENT_TYPE_NODE` (integer)	10
`XML_DOCUMENT_FRAG_NODE` (integer)	11
`XML_NOTATION_NODE` (integer)	12
`XML_GLOBAL_NAMESPACE` (integer)	1
`XML_LOCAL_NAMESPACE` (integer)	2
`XML_HTML_DOCUMENT_NODE` (integer)
`XML_DTD_NODE` (integer)
`XML_ELEMENT_DECL_NODE` (integer)
`XML_ATTRIBUTE_DECL_NODE` (integer)
`XML_ENTITY_DECL_NODE` (integer)
`XML_NAMESPACE_DECL_NODE` (integer)
`XML_ATTRIBUTE_CDATA` (integer)
`XML_ATTRIBUTE_ID` (integer)
`XML_ATTRIBUTE_IDREF` (integer)
`XML_ATTRIBUTE_IDREFS` (integer)
`XML_ATTRIBUTE_ENTITY` (integer)
`XML_ATTRIBUTE_NMTOKEN` (integer)
`XML_ATTRIBUTE_NMTOKENS` (integer)
`XML_ATTRIBUTE_ENUMERATION` (integer)
`XML_ATTRIBUTE_NOTATION` (integer)
`XPATH_UNDEFINED` (integer)
`XPATH_NODESET` (integer)
`XPATH_BOOLEAN` (integer)
`XPATH_NUMBER` (integer)
`XPATH_STRING` (integer)
`XPATH_POINT` (integer)
`XPATH_RANGE` (integer)
`XPATH_LOCATIONSET` (integer)
`XPATH_USERS` (integer)
`XPATH_NUMBER` (integer)

Classes

The API of the module follows the DOM Level 2 standard as closely as possible. Consequently, the API is fully object-oriented. It is a good idea to have the DOM standard available when using this module. Though the API is object-oriented, there are many functions which can be called in a non-object-oriented way by passing the object to operate on as the first argument. These functions are mainly to retain compatibility to older versions of the extension, and should not be used when creating new scripts.

This API differs from the official DOM API in two ways. First, all class attributes are implemented as functions with the same name. Secondly, the function names follow the PHP naming convention. This means that a DOM function lastChild() will be written as last_child().

This module defines a number of classes, which are listed - including their method - in the following tables. Classes with an equivalent in the DOM standard are named DOMxxx.

表格 3. List of classes

Class name	Parent classes
DomAttribute	DomNode
DomCData	DomNode
DomComment	DomCData : DomNode
DomDocument	DomNode
DomDocumentType	DomNode
DomElement	DomNode
DomEntity	DomNode
DomEntityReference	DomNode
DomProcessingInstruction	DomNode
DomText	DomCData : DomNode
Parser	Currently still called DomParser
XPathContext

表格 4. DomDocument class (DomDocument : DomNode)

Method name	Function name	Remark
doctype	DomDocument_doctype()
document_element	DomDocument_document_element()
create_element	DomDocument_create_element()
create_text_node	DomDocument_create_text_node()
create_comment	DomDocument_create_comment()
create_cdata_section	DomDocument_create_cdata_section()
create_processing_instruction	DomDocument_create_processing_instruction()
create_attribute	DomDocument_create_attribute()
create_entity_reference	DomDocument_create_entity_reference()
get_elements_by_tagname	DomDocument_get_elements_by_tagname()
get_element_by_id	DomDocument_get_element_by_id()
dump_mem	DomDocument_dump_mem()	not DOM standard
dump_file	DomDocument_dump_file()	not DOM standard
html_dump_mem	DomDocument_html_dump_mem()	not DOM standard
xpath_init	xpath_init	not DOM standard
xpath_new_context	xpath_new_context	not DOM standard
xptr_new_context	xptr_new_context	not DOM standard

表格 5. DomElement class (DomElement : DomNode)

Method name	Function name	Remark
tagname	DomElement_tagname()
get_attribute	DomElement_get_attribute()
set_attribute	DomElement_set_attribute()
remove_attribute	DomElement_remove_attribute()
get_attribute_node	DomElement_get_attribute_node()
get_elements_by_tagname	DomElement_get_elements_by_tagname()
has_attribute	DomElement_has_attribute()

表格 6. DomNode class

Method name	Remark
DomNode_node_name()
DomNode_node_value()
DomNode_node_type()
DomNode_last_child()
DomNode_first_child()
DomNode_child_nodes()
DomNode_previous_sibling()
DomNode_next_sibling()
DomNode_parent_node()
DomNode_owner_document()
DomNode_insert_before()
DomNode_append_child()
DomNode_append_sibling()	Not in DOM standard. This function emulates the former behaviour of DomNode_append_child().
DomNode_remove_child()
DomNode_has_child_nodes()
DomNode_has_attributes()
DomNode_clone_node()
DomNode_attributes()
DomNode_unlink_node()	Not in DOM standard
DomNode_replace_node()	Not in DOM standard
DomNode_set_content()	Not in DOM standard, deprecated
DomNode_get_content()	Not in DOM standard, deprecated
DomNode_dump_node()	Not in DOM standard
DomNode_is_blank_node()	Not in DOM standard

表格 7. DomAttribute class (DomAttribute : DomNode)

Method name		Remark
name	DomAttribute_name()
value	DomAttribute_value()
specified	DomAttribute_specified()

表格 8. DomProcessingInstruction class (DomProcessingInstruction : DomNode)

Method name	Function name	Remark
target	DomProcessingInstruction_target()
data	DomProcessingInstruction_data()

表格 9. Parser class

Method name	Function name	Remark
add_chunk	Parser_add_chunk()
end	Parser_end()

表格 10. XPathContext class

Method name	Function name	Remark
eval	XPathContext_eval()
eval_expression	XPathContext_eval_expression()
register_ns	XPathContext_register_ns()

表格 11. DomDocumentType class (DomDocumentType : DomNode)

Method name	Function name	Remark
name	DomDocumentType_name()
entities	DomDocumentType_entities()
notations	DomDocumentType_notations()
public_id	DomDocumentType_public_id()
system_id	DomDocumentType_system_id()
internal_subset	DomDocumentType_internal_subset()

The classes DomDtd is derived from DomNode. DomComment is derived from DomCData.

范例

Many examples in this reference require an XML string. Instead of repeating this string in every example, it will be put into a file which will be included by each example. This include file is shown in the following example section. Alternatively, you could create an XML document and read it with DomDocument_open_file().

例子 1. Include file example.inc with XML string
<?php $xmlstr = "<?xml version='1.0' standalone='yes'?> <!DOCTYPE chapter SYSTEM '/share/sgml/Norman_Walsh/db3xml10/db3xml10.dtd' [ <!ENTITY sp \"spanish\"> ]>  <chapter language='en'><title language='en'>Title</title> <para language='ge'> &sp;  <informaltable ID='findme' language='&sp;'> <tgroup cols='3'> <tbody> <row><entry>a1</entry><entry morerows='1'>b1</entry><entry>c1</entry></row> <row><entry>a2</entry><entry>c2</entry></row> <row><entry>a3</entry><entry>b3</entry><entry>c3</entry></row> </tbody> </tgroup> </informaltable> </para> </chapter>"; ?>

目录
DomAttribute->name -- Returns the name of attribute
DomAttribute->set_value -- Sets the value of an attribute
DomAttribute->specified -- Checks if attribute is specified
DomAttribute->value -- Returns value of attribute
DomDocument->add_root -- Adds a root node [deprecated]
DomDocument->create_attribute -- Create new attribute
DomDocument->create_cdata_section -- Create new cdata node
DomDocument->create_comment -- Create new comment node
DomDocument->create_element_ns -- Create new element node with an associated namespace
DomDocument->create_element -- Create new element node
DomDocument->create_entity_reference -- Create an entity reference
DomDocument->create_processing_instruction -- Creates new PI node
DomDocument->create_text_node -- Create new text node
DomDocument->doctype -- Returns the document type
DomDocument->document_element -- Returns root element node
DomDocument->dump_file -- Dumps the internal XML tree back into a file
DomDocument->dump_mem -- Dumps the internal XML tree back into a string
DomDocument->get_element_by_id -- Searches for an element with a certain id
DomDocument->get_elements_by_tagname -- Returns array with nodes with given tagname in document or empty array, if not found
DomDocument->html_dump_mem -- Dumps the internal XML tree back into a string as HTML
DomDocument->xinclude -- Substitutes XIncludes in a DomDocument Object
DomDocumentType->entities() -- Returns list of entities
DomDocumentType->internal_subset() -- Returns internal subset
DomDocumentType->name() -- Returns name of document type
DomDocumentType->notations() -- Returns list of notations
DomDocumentType->public_id() -- Returns public id of document type
DomDocumentType->system_id() -- Returns the system id of document type
DomElement->get_attribute_node() -- Returns the node of the given attribute
DomElement->get_attribute() -- Returns the value of the given attribute
DomElement->get_elements_by_tagname() -- Gets elements by tagname
DomElement->has_attribute() -- Checks to see if an attribute exists in the current node
DomElement->remove_attribute() -- Removes attribute
DomElement->set_attribute() -- Sets the value of an attribute
DomElement->tagname() -- Returns the name of the current element
DomNode->add_namespace -- Adds a namespace declaration to a node
DomNode->append_child -- Adds a new child at the end of the children
DomNode->append_sibling -- Adds new sibling to a node
DomNode->attributes -- Returns list of attributes
DomNode->child_nodes -- Returns children of node
DomNode->clone_node -- Clones a node
DomNode->dump_node -- Dumps a single node
DomNode->first_child -- Returns first child of node
DomNode->get_content -- Gets content of node
DomNode->has_attributes -- Checks if node has attributes
DomNode->has_child_nodes -- Checks if node has children
DomNode->insert_before -- Inserts new node as child
DomNode->is_blank_node -- Checks if node is blank
DomNode->last_child -- Returns last child of node
DomNode->next_sibling -- Returns the next sibling of node
DomNode->node_name -- Returns name of node
DomNode->node_type -- Returns type of node
DomNode->node_value -- Returns value of a node
DomNode->owner_document -- Returns the document this node belongs to
DomNode->parent_node -- Returns the parent of the node
DomNode->prefix -- Returns name space prefix of node
DomNode->previous_sibling -- Returns the previous sibling of node
DomNode->remove_child -- Removes child from list of children
DomNode->replace_child -- Replaces a child
DomNode->replace_node -- Replaces node
DomNode->set_content -- Sets content of node
DomNode->set_name -- Sets name of node
DomNode->set_namespace -- Sets namespace of a node
DomNode->unlink_node -- Deletes node
DomProcessingInstruction->data -- Returns the data of ProcessingInstruction node
DomProcessingInstruction->target -- Returns the target of a ProcessingInstruction node
DomXsltStylesheet->process() -- Applies the XSLT-Transformation on a DomDocument Object
DomXsltStylesheet->result_dump_file() -- Dumps the result from a XSLT-Transformation into a file
DomXsltStylesheet->result_dump_mem() -- Dumps the result from a XSLT-Transformation back into a string
domxml_new_doc -- Creates new empty XML document
domxml_open_file -- Creates a DOM object from an XML file
domxml_open_mem -- Creates a DOM object of an XML document
domxml_version -- Gets the XML library version
domxml_xmltree -- Creates a tree of PHP objects from an XML document
domxml_xslt_stylesheet_doc -- Creates a DomXsltStylesheet Object from a DomDocument Object
domxml_xslt_stylesheet_file -- Creates a DomXsltStylesheet Object from an XSL document in a file
domxml_xslt_stylesheet -- Creates a DomXsltStylesheet object from an XSL document in a string
domxml_xslt_version -- Gets the XSLT library version
xpath_eval_expression -- Evaluates the XPath Location Path in the given string
xpath_eval -- Evaluates the XPath Location Path in the given string
xpath_new_context -- Creates new xpath context
xpath_register_ns_auto -- Register the given namespace in the passed XPath context
xpath_register_ns -- Register the given namespace in the passed XPath context
xptr_eval -- Evaluate the XPtr Location Path in the given string
xptr_new_context -- Create new XPath Context

DomAttribute->name

(no version information, might be only in CVS)

DomAttribute->name -- Returns the name of attribute

说明

class DomAttribute {

string name ( void )

}

Gets the name of the attribute.

返回值

Returns the name of the attribute.

Migrating to PHP 5

Use the name property of DOMAttr.

参见

DomAttribute->value for an example

DomAttribute->set_value

(no version information, might be only in CVS)

DomAttribute->set_value -- Sets the value of an attribute

说明

class DomAttribute {

bool set_value ( string content )

}

This function sets the value of an attribute.

参数

content: The new value.

返回值

如果成功则返回 TRUE，失败则返回 FALSE。

Migrating to PHP 5

Set the value property of DOMAttr.

参见

DomAttribute->value

DomAttribute->specified

(no version information, might be only in CVS)

DomAttribute->specified -- Checks if attribute is specified

说明

class DomAttribute {

bool specified ( void )

}

Checks if the attribute was explicitly given a value in the original document.

注: This method is not implemented yet.

返回值

如果成功则返回 TRUE，失败则返回 FALSE。

参见

The definition of specified in the DOM Recommendations

DomAttribute->value

(no version information, might be only in CVS)

DomAttribute->value -- Returns value of attribute

说明

class DomAttribute {

string value ( void )

}

This function returns the value of the attribute.

范例

例子 1. Getting all the attributes of a node
<?php include("example.inc"); if (!$dom = domxml_open_mem($xmlstr)) { echo "Error while parsing the document\n"; exit; } $root = $dom->document_element(); $attrs = $root->attributes(); echo 'Attributes of ' . $root->node_name() . "\n"; foreach ($attrs as $attribute) { echo ' - ' . $attribute->name . ' : ' . $attribute->value . "\n"; } ?>
上例将输出：
Attributes of chapter - language : en

返回值

Returns the value of the attribute.

Migrating to PHP 5

Use the value property of DOMAttr.

本函数暂无文档，仅有参数列表。

Migrating to PHP 5

Use the entities property of the DOMDocumentType object.

DomDocumentType->internal_subset()

(no version information, might be only in CVS)

DomDocumentType->internal_subset() -- Returns internal subset

说明

class DomDocumentType {

bool internal_subset ( void )

}

警告

本函数暂无文档，仅有参数列表。

Migrating to PHP 5

Use the internalSubset property of the DOMDocumentType object.

DomDocumentType->name()

(no version information, might be only in CVS)

DomDocumentType->name() -- Returns name of document type

说明

class DomDocumentType {

string name ( void )

}

This function returns the name of the document type.

返回值

Returns the name of the DomDocumentType, as a string.

范例

例子 1. Getting the document type's name
<?php include("example.inc"); if (!$dom = domxml_open_mem($xmlstr)) { echo "Error while parsing the document\n"; exit; } $doctype = $dom->doctype(); echo $doctype->name(); // chapter ?>

Migrating to PHP 5

DomElement->get_attribute_node() -- Returns the node of the given attribute

说明

class DomElement {

DomAttribute get_attribute_node ( string name )

}

Returns the node of the given attribute in the current element.

参数

name: The name of the seeked attribute. This parameter is case sensitive.

返回值

Returns the node of the attribute as a DomAttribute or FALSE if no attribute with the given name is found.

范例

例子 1. Getting an attribute node
<?php include("example.inc"); if (!$dom = domxml_open_mem($xmlstr)) { echo "Error while parsing the document\n"; exit; } $root = $dom->document_element(); if ($attribute = $root->get_attribute_node('language')) { echo 'Language is: ' . $attribute->value() . "\n"; } ?>

Migrating to PHP 5

Use DOMElement->getAttributeNode().

参见

DomElement->set_attribute()

DomElement->get_attribute()

(no version information, might be only in CVS)

DomElement->get_attribute() -- Returns the value of the given attribute

说明

class DomElement {

string get_attribute ( string name )

}

Returns the value of the given attribute in the current element.

Since PHP 4.3, if no attribute with given name is found, an empty string is returned.

参数

name: The name of the seeked attribute. This parameter is case sensitive.

返回值

Returns the name of the attribute as a string or an empty string if no attribute with the given name is found.

范例

例子 1. Getting the value of an attribute
<?php include("example.inc"); if (!$dom = domxml_open_mem($xmlstr)) { echo "Error while parsing the document\n"; exit; } // get chapter $root = $dom->document_element(); echo $root->get_attribute('language'); // en ?>

Migrating to PHP 5

Use DOMElement->getAttribute().

参见

DomElement->get_attribute_node()

DomElement->set_attribute()

DomElement->get_elements_by_tagname()

(no version information, might be only in CVS)

DomElement->get_elements_by_tagname() -- Gets elements by tagname

说明

class DomElement {

array get_elements_by_tagname ( string name )

}

Gets all the sub elements with the specific name within the current element.

参数

name: The name of the seeked element.

返回值

Returns an array of DomElement objects.

范例

例子 1. Getting a content
<?php if (!$dom = domxml_open_mem($xmlstr)) { echo "Error while parsing the document\n"; exit; } $root = $dom->document_element(); $node_array = $root->get_elements_by_tagname('element'); foreach ($node_array as $node) { echo ' - ' . $node->get_content() . "\n"; } ?>

Migrating to PHP 5

Use DOMElement->getElementsByTagName().

DomElement->has_attribute()

(no version information, might be only in CVS)

DomElement->has_attribute() -- Checks to see if an attribute exists in the current node

说明

class DomElement {

bool has_attribute ( string name )

}

This functions checks to see if an attribute named name exists in the current node.

参数

name: The name of the tested attribute.

返回值

Returns TRUE if the asked attribute exists, FALSE otherwise.

范例

例子 1. Testing the existence of an attribute
<?php include("example.inc"); if (!$dom = domxml_open_mem($xmlstr)) { echo "Error while parsing the document\n"; exit; } $root = $dom->document_element(); $buffer = '<html'; if ($root->has_attribute('language')) { $buffer .= 'lang="' . $root->get_attribute('language') . '"'; } $buffer .= '>'; ?>

Migrating to PHP 5

Use DOMElement->hasAttribute().

DomElement->remove_attribute()

(no version information, might be only in CVS)

DomElement->remove_attribute() -- Removes attribute

说明

class DomElement {

bool remove_attribute ( string name )

}

Removes an attribute from the current DomElement node.

参数

name: The name of the attribute to remove.

返回值

如果成功则返回 TRUE，失败则返回 FALSE。

Migrating to PHP 5

Use DOMElement->removeAttribute().

DomElement->set_attribute()

(no version information, might be only in CVS)

DomElement->set_attribute() -- Sets the value of an attribute

说明

class DomElement {

DomAttribute set_attribute ( string name, string value )

}

Sets an attribute with name name to the given value.

参数

name: The name of the attribute. If this attribute doesn't exist, it will be created.
value: The value of the attribute.

返回值

Returns the old DomAttribute node, or the new one if you are creating the attribute for the first time.

范例

例子 1. Setting an attribute
<?php $doc = domxml_new_doc("1.0"); $node = $doc->create_element("para"); $newnode = $doc->append_child($node); $newnode->set_attribute("align", "left"); ?>

Migrating to PHP 5

Use DOMElement->setAttribute().

参见

DomElement->get_attribute_node()

DomElement->get_attribute()

DomElement->tagname()

(no version information, might be only in CVS)

DomElement->tagname() -- Returns the name of the current element

说明

class DomElement {

string tagname ( void )

}

Returns the name of the current node. Calling this function is the same as accessing the tagname property, or calling DomNode->node_name on the current node.

返回值

Returns the name of the current DomElement node.

范例

例子 1. Getting the node name
<?php include("example.inc"); if (!$dom = domxml_open_mem($xmlstr)) { echo "Error while parsing the document\n"; exit; } $root = $dom->document_element(); echo $root->tagname(); // chapter echo $root->tagname; // chapter echo $root->node_name(); // chapter ?>

Migrating to PHP 5

Use the tagName property of the DOMElement object.

DomNode->add_namespace

(no version information, might be only in CVS)

DomNode->add_namespace -- Adds a namespace declaration to a node

说明

class DOMNode {

bool add_namespace ( string uri, string prefix )

}

This method adds a namespace declaration to a node.

注: This method is not part of the DOM specification.

参数

uri: The namespace URI of the node.
prefix: The namespace prefix of the node.

返回值

如果成功则返回 TRUE，失败则返回 FALSE。

Migrating to PHP 5

You can set the namespace URI and prefix of a DOMElement or a DOMAttr at creation time by using DOMDocument->createElementNS() or DOMDocument->createAttributeNS().

注: Remember the an attribute does not inherit its namespace from the element it is attached to.

参见

DomDocument->create_element_ns

DomNode->set_namespace

DomNode->append_child

(no version information, might be only in CVS)

DomNode->append_child -- Adds a new child at the end of the children

说明

class DOMNode {

DOMNode append_child ( DOMNode newnode )

}

This functions appends a child to an existing list of children or creates a new list of children.

参数

newnode: The node being appended. It can be created with e.g. DomDocument->create_element, DomDocument->create_text_node etc. or simply by using any other node.
注: You can not append a DOMAttribute using this method. Use DomElement->set_attribute() instead.

返回值

Returns the appended node on success or FALSE on failure.

更新日志

版本	说明
4.3.0	You are not allowed anymore to insert a node from another document.
4.3.0	Prior to PHP 4.3.0, the new child is duplicated before being appended. Therefore the new child is a completely new copy which can be modified without changing the node which was passed to this function. If the node passed has children itself, they will be duplicated as well, which makes it quite easy to duplicate large parts of an XML document. The return value is the appended child. If you plan to do further modifications on the appended child you must use the returned node.
4.3.0 and 4.3.1	The new child `newnode` is first unlinked from its existing context, if it's already a child of DomNode. Therefore the `newnode` is moved and not copies anymore. This is the behaviour according to the W3C specifications. If you need the old behaviour, use DomNode->clone_node before appending.
4.3.2	The new child `newnode` is first unlinked from its existing context, if it's already in the tree. Same rules apply.

范例

The following example adds a new element node to a fresh document and sets the attribute align to left.

例子 1. Adding a child
<?php $doc = domxml_new_doc("1.0"); $node = $doc->create_element("para"); $newnode = $doc->append_child($node); $newnode->set_attribute("align", "left"); ?>

The above example could also be written as the following:

例子 2. Adding a child
<?php $doc = domxml_new_doc("1.0"); $node = $doc->create_element("para"); $node->set_attribute("align", "left"); $newnode = $doc->append_child($node); ?>

A more complex example is the one below. It first searches for a certain element, duplicates it including its children and adds it as a sibling. Finally a new attribute is added to one of the children of the new sibling and the whole document is dumped.

例子 3. Adding a child
<?php include("example.inc"); if (!$dom = domxml_open_mem($xmlstr)) { echo "Error while parsing the document\n"; exit; } $elements = $dom->get_elements_by_tagname("informaltable"); print_r($elements); $element = $elements[0]; $parent = $element->parent_node(); $newnode = $parent->append_child($element); $children = $newnode->children(); $attr = $children[1]->set_attribute("align", "left"); $xmlfile = $dom->dump_mem(); echo htmlentities($xmlfile); ?>

The above example could also be done with DomNode->insert_before instead of DomNode->append_child.

Migrating to PHP 5

You should use DOMNode->appendChild().

参见

DomNode->insert_before

DomNode->clone_node

DomNode->append_sibling

(no version information, might be only in CVS)

DomNode->append_sibling -- Adds new sibling to a node

说明

domelement DomNode->append_sibling ( domelement newnode )

This functions appends a sibling to an existing node. The child can be created with e.g. domdocument_create_element(), domdocument_create_text() etc. or simply by using any other node.

Before a new sibling is added it is first duplicated. Therefore the new child is a completely new copy which can be modified without changing the node which was passed to this function. If the node passed has children itself, they will be duplicated as well, which makes it quite easy to duplicate large parts of an XML document. The return value is the added sibling. If you plan to do further modifications on the added sibling you must use the returned node.

This function has been added to provide the behaviour of domnode_append_child() as it works till PHP 4.2.

DomNode->attributes

(no version information, might be only in CVS)

DomNode->attributes -- Returns list of attributes

说明

array DomNode->attributes ( void )

This function only returns an array of attributes if the node is of type XML_ELEMENT_NODE.

(PHP >= 4.3 only) If no attributes are found, NULL is returned.

DomNode->child_nodes

(no version information, might be only in CVS)

DomNode->child_nodes -- Returns children of node

bool DomNode->has_attributes ( void )

This function checks if the node has attributes.

DomNode->has_child_nodes

(no version information, might be only in CVS)

DomNode->has_child_nodes -- Checks if node has children

说明

bool DomNode->has_child_nodes ( void )

This function checks if the node has children.

DomNode->insert_before

(no version information, might be only in CVS)

DomNode->insert_before -- Inserts new node as child

说明

domelement DomNode->insert_before ( domelement newnode, domelement refnode )

This function inserts the new node newnode right before the node refnode. The return value is the inserted node. If you plan to do further modifications on the appended child you must use the returned node.

string DomNode->node_name ( void )

Returns name of the node. The name has different meanings for the different types of nodes as illustrated in the following table.

表格 1. Meaning of value

Type	Meaning
DomAttribute	value of attribute
DomAttribute
DomCDataSection	#cdata-section
DomComment	#comment
DomDocument	#document
DomDocumentType	document type name
DomElement	tag name
DomEntity	name of entity
DomEntityReference	name of entity reference
DomNotation	notation name
DomProcessingInstruction	target
DomText	#text

DomNode->node_type

(no version information, might be only in CVS)

DomNode->node_type -- Returns type of node

说明

int DomNode->node_type ( void )

Returns the type of the node. All possible types are listed in the table in the introduction.

例子 1.

<?php

include 'example.inc';

$dom = domxml_open_mem($xmlstr);

$chapter = $dom->document_element();

// Let's see the elements contained in chapter
foreach($chapter->child_nodes() as $node) {
  if ($node->node_type() == XML_ELEMENT_NODE) {
    echo $node->node_name() . "\n";
  }
}

?>

上例将输出：

title
para

DomNode->node_value

(no version information, might be only in CVS)

DomNode->node_value -- Returns value of a node

说明

string DomNode->node_value ( void )

Returns value of the node. The value has different meanings for the different types of nodes as illustrated in the following table.

表格 1. Meaning of value

Type	Meaning
DomAttribute	value of attribute
DomAttribute
DomCDataSection	content
DomComment	content of comment
DomDocument	null
DomDocumentType	null
DomElement	null
DomEntity	null
DomEntityReference	null
DomNotation	null
DomProcessingInstruction	entire content without target
DomText	content of text

DomNode->owner_document

(no version information, might be only in CVS)

DomNode->owner_document -- Returns the document this node belongs to

说明

domdocument DomNode->owner_document ( void )

This function returns the document the current node belongs to.

The following example will create two identical lists of children.
例子 1. Finding the document of a node
<?php $doc = domxml_new_doc("1.0"); $node = $doc->create_element("para"); $node = $doc->append_child($node); $children = $doc->children(); print_r($children); $doc2 = $node->owner_document(); $children = $doc2->children(); print_r($children); ?>

DomNode->parent_node

(no version information, might be only in CVS)

DomNode->parent_node -- Returns the parent of the node

说明

domnode DomNode->parent_node ( void )

This function returns the parent node.

xml_doc: The XML document being transformed, as a DomDocument object.
xslt_params: An associative array that takes pairs of parameter names and values.
is_xpath_param: If set to FALSE the values of the xslt_params will be quoted. This is the default behavior. It allows you to pass the values as PHP strings.
注: If your strings contains both single and double quotes, you must take care of quoting all the values by yourself and set this parameter to TRUE.
profile_filename: Set this to the path of a filename, if you want profiling information.

返回值

Returns the result of the processing, as a DomDocument object.

Migrating to PHP 5

Use XSLTProcessor->setParameter() and XSLTProcessor->transformToDoc().

更新日志

版本	说明
4.3.0	The `profile_filename` parameter was added.

参见

domxml_xslt_stylesheet()

domxml_xslt_stylesheet_file()

domxml_xslt_stylesheet_doc()

DomXsltStylesheet->result_dump_file()

(no version information, might be only in CVS)

DomXsltStylesheet->result_dump_file() -- Dumps the result from a XSLT-Transformation into a file

说明

class DomXsltStylesheet {

string result_dump_file ( DomDocument xmldoc, string filename )

}

Since DomXsltStylesheet->process() always returns a well-formed XML DomDocument, no matter what output method was declared in <xsl:output> and similar attributes/elements, it's of not much use, if you want to output HTML 4 or text data.

This function on the contrary honors <xsl:output method="html|text"> and other output control directives. See the example for instruction on how to use it.

范例

例子 1. Saving the result of a XSLT transformation in a file
<?php $filename = "stylesheet.xsl"; $xmldoc = domxml_open_file("data.xml"); $xsldoc = domxml_xslt_stylesheet_file($filename); $result = $xsldoc->process($xmldoc); echo $xsldoc->result_dump_file($result, "filename"); ?>

参见

DomXsltStylesheet->result_dump_mem()

DomXsltStylesheet->result_dump_file()

DomXsltStylesheet->result_dump_mem()

(no version information, might be only in CVS)

DomXsltStylesheet->result_dump_mem() -- Dumps the result from a XSLT-Transformation back into a string

说明

class DomXsltStylesheet {

string result_dump_mem ( DomDocument xmldoc )

}

This function on the contrary honors <xsl:output method="html|text"> and other output control directives. See the example for instruction on how to use it.

范例

例子 1. Outputting the result of a XSLT transformation
<?php $filename = "stylesheet.xsl"; $xmldoc = domxml_open_file("data.xml"); $xsldoc = domxml_xslt_stylesheet_file($filename); $result = $xsldoc->process($xmldoc); echo $xsldoc->result_dump_mem($result); ?>

参见

domxml_new_doc

(PHP 4 >= 4.2.1, PECL)

domxml_new_doc -- Creates new empty XML document

说明

DomDocument domxml_new_doc ( string version )

Creates a new Dom document from scratch and returns it.

参数

version: The XML version number of the document.

返回值

Returns a new DomDocument instance.

domxml_open_file

(PHP 4 >= 4.2.1, PECL)

domxml_open_file -- Creates a DOM object from an XML file

说明

DomDocument domxml_open_file ( string filename [, int mode [, array &error]] )

The function parses the XML document in the given file.

参数

filename

The path to the XML file. The file is accessed in read-only mode.

mode

This optional parameter can be used to change the behavior of this function.

You can use one of the following constants for it: DOMXML_LOAD_PARSING (default), DOMXML_LOAD_VALIDATING or DOMXML_LOAD_RECOVERING. You can add to it also DOMXML_LOAD_DONT_KEEP_BLANKS, DOMXML_LOAD_SUBSTITUTE_ENTITIES and DOMXML_LOAD_COMPLETE_ATTRS by bitwise or.

error

If used, it will contain the error messages. error must be passed in by reference.

返回值

Returns a DomDocument instance of the given file.

范例

例子 1. Opening an XML document from a file
<?php if (!$dom = domxml_open_file("example.xml")) { echo "Error while parsing the document\n"; exit; } $root = $dom->document_element(); ?>

更新日志

版本	说明
4.3.0	The parameters `mode` and `error` were added.

参见

domxml_open_mem()

domxml_new_doc()

domxml_open_mem

(PHP 4 >= 4.2.1, PECL)

domxml_open_mem -- Creates a DOM object of an XML document

说明

DomDocument domxml_open_mem ( string str [, int mode [, array &error]] )

The function parses the XML document in the given string.

参数

str

The contents of the XML file.

mode

This optional parameter can be used to change the behavior of this function.

error

If used, it will contain the error messages. error must be passed in by reference.

返回值

Returns a DomDocument instance of the given XML contents.

范例

例子 1. Opening an XML document in a string
<?php include("example.inc"); if (!$dom = domxml_open_mem($xmlstr)) { echo "Error while parsing the document\n"; exit; } $root = $dom->document_element(); ?>

参见

domxml_open_file()

domxml_new_doc()

domxml_version

(PHP 4 >= 4.1.0, PECL)

domxml_version -- Gets the XML library version

说明

string domxml_version ( void )

Gets the version of the XML library currently used.

返回值

The version of the XML library, as a string.

范例

例子 1. domxml_version() Example
<?php echo domxml_version(); ?>
上例的输出类似于：
20607

domxml_xmltree

(PHP 4 >= 4.2.1, PECL)

domxml_xmltree -- Creates a tree of PHP objects from an XML document

说明

DomDocument domxml_xmltree ( string str )

The function parses the XML document in str and returns a tree PHP objects as the parsed document.

This function is isolated from the other functions, which means you cannot access the tree with any of the other functions. Modifying it, for example by adding nodes, makes no sense since there is currently no way to dump it as an XML file.

However this function may be valuable if you want to read a file and investigate the content.

参数

str: The contents of the XML file.

返回值

Returns a tree of Dom objects starting by a DomDocument.

domxml_xslt_stylesheet_doc

(PHP 4 >= 4.2.0, PECL)

domxml_xslt_stylesheet_doc -- Creates a DomXsltStylesheet Object from a DomDocument Object

说明

DomXsltStylesheet domxml_xslt_stylesheet_doc ( DomDocument xsl_doc )

Creates a DomXsltStylesheet object from the given XSL document.

参数

xsl_doc: The XSL document, as a DomDocument object.

返回值

Returns a new instance of DomXsltStylesheet.

Migrating to PHP 5

Call XSLTProcessor->importStylesheet() with the xsl_doc parameter.

参见

domxml_xslt_stylesheet()

domxml_xslt_stylesheet_file()

domxml_xslt_stylesheet_file

(PHP 4 >= 4.2.0, PECL)

domxml_xslt_stylesheet_file -- Creates a DomXsltStylesheet Object from an XSL document in a file

说明

DomXsltStylesheet domxml_xslt_stylesheet_file ( string xsl_file )

Creates a DomXsltStylesheet object from the given XSL file.

参数

xsl_file: The path to the XSL document, as a string.

返回值

Returns a new instance of DomXsltStylesheet.

Migrating to PHP 5

Call XSLTProcessor->importStylesheet() with DOMDocument::load($xsl_file) as parameter.

参见

domxml_xslt_stylesheet()

domxml_xslt_stylesheet_doc()

domxml_xslt_stylesheet

(PHP 4 >= 4.2.0, PECL)

domxml_xslt_stylesheet -- Creates a DomXsltStylesheet object from an XSL document in a string

说明

DomXsltStylesheet domxml_xslt_stylesheet ( string xsl_buf )

Creates a DomXsltStylesheet object from the given XSL buffer.

参数

xsl_buf: The XSL document, as a string.

返回值

Returns a new instance of DomXsltStylesheet.

Migrating to PHP 5

Call XSLTProcessor->importStylesheet() with DOMDocument::loadXML($xsl_buf) as parameter.

参见

domxml_xslt_stylesheet_file()

domxml_xslt_stylesheet_doc()

domxml_xslt_version

(PHP 4 >= 4.2.0, PECL)

domxml_xslt_version -- Gets the XSLT library version

说明

int domxml_xslt_version ( void )

Gets the XSLT library version.

返回值

Returns the version number of the XSLT library, as an integer.

范例

例子 1. domxml_xslt_version() Example
<?php echo domxml_xslt_version(); ?>
上例的输出类似于：
10112

XPathContext xpath_new_context ( domdocument dom_document )

xpath_register_ns_auto

(PECL)

xpath_register_ns_auto -- Register the given namespace in the passed XPath context

说明

bool xpath_register_ns_auto ( XPathContext xpath_context [, object context_node] )

警告

本函数暂无文档，仅有参数列表。

返回值

如果成功则返回 TRUE，失败则返回 FALSE。

参见

xpath_register_ns()

xpath_register_ns

(PHP 4 >= 4.2.0, PECL)

xpath_register_ns -- Register the given namespace in the passed XPath context

说明

bool xpath_register_ns ( XPathContext xpath_context, string prefix, string uri )

简介

These are functions dealing with error handling and logging. They allow you to define your own error handling rules, as well as modify the way the errors can be logged. This allows you to change and enhance error reporting to suit your needs.

With the logging functions, you can send messages directly to other machines, to an email (or email to pager gateway!), to system logs, etc., so you can selectively log and monitor the most important parts of your applications and websites.

The error reporting functions allow you to customize what level and kind of error feedback is given, ranging from simple notices to customized functions returned during errors.

需求

要编译本扩展模块不需要外部库文件。

安装

本函数库作为 PHP 内核的一部分，不用安装就能使用。

运行时配置

这些函数的行为受 php.ini 的影响。

表格 1. Errors and Logging Configuration Options

Name	Default	Changeable	Changelog
error_reporting	NULL	PHP_INI_ALL
display_errors	"1"	PHP_INI_ALL
display_startup_errors	"0"	PHP_INI_ALL	Available since PHP 4.0.3.
log_errors	"0"	PHP_INI_ALL
log_errors_max_len	"1024"	PHP_INI_ALL	Available since PHP 4.3.0.
ignore_repeated_errors	"0"	PHP_INI_ALL	Available since PHP 4.3.0.
ignore_repeated_source	"0"	PHP_INI_ALL	Available since PHP 4.3.0.
report_memleaks	"1"	PHP_INI_ALL	Available since PHP 4.3.0.
track_errors	"0"	PHP_INI_ALL
html_errors	"1"	PHP_INI_ALL	PHP_INI_SYSTEM in PHP <= 4.2.3. Available since PHP 4.0.2.
docref_root	""	PHP_INI_ALL	Available since PHP 4.3.0.
docref_ext	""	PHP_INI_ALL	Available since PHP 4.3.2.
error_prepend_string	NULL	PHP_INI_ALL
error_append_string	NULL	PHP_INI_ALL
error_log	NULL	PHP_INI_ALL
warn_plus_overloading	NULL	PHP_INI??

有关 PHP_INI_* 常量进一步的细节与定义参见附录 G。

以下是配置选项的简要解释。

error_reporting integer

Set the error reporting level. The parameter is either an integer representing a bit field, or named constants. The error_reporting levels and constants are described in Predefined Constants, and in php.ini. To set at runtime, use the error_reporting() function. See also the display_errors directive.

In PHP 4 and PHP 5 the default value is E_ALL & ~E_NOTICE. This setting does not show E_NOTICE level errors. You may want to show them during development.

注: Enabling E_NOTICE during development has some benefits. For debugging purposes: NOTICE messages will warn you about possible bugs in your code. For example, use of unassigned values is warned. It is extremely useful to find typos and to save time for debugging. NOTICE messages will warn you about bad style. For example, $arr[item] is better to be written as $arr['item'] since PHP tries to treat "item" as constant. If it is not a constant, PHP assumes it is a string index for the array.

注: In PHP 5 a new error level E_STRICT is available. As E_STRICT is not included within E_ALL you have to explicitly enable this kind of error level. Enabling E_STRICT during development has some benefits. STRICT messages will help you to use the latest and greatest suggested method of coding, for example warn you about using deprecated functions.

In PHP 3, the default setting is (E_ERROR | E_WARNING | E_PARSE), meaning the same thing. Note, however, that since constants are not supported in PHP 3's php3.ini, the error_reporting setting there must be numeric; hence, it is 7.

display_errors boolean

This determines whether errors should be printed to the screen as part of the output or if they should be hidden from the user.

注: This is a feature to support your development and should never be used on production systems (e.g. systems connected to the internet).

注: Although display_errors may be set at runtime (with ini_set ()), it won't have any affect if the script has fatal errors. This is because the desired runtime action does not get executed.

display_startup_errors boolean

Even when display_errors is on, errors that occur during PHP's startup sequence are not displayed. It's strongly recommended to keep display_startup_errors off, except for debugging.

log_errors boolean

Tells whether script error messages should be logged to the server's error log or error_log. This option is thus server-specific.

注: You're strongly advised to use error logging in place of error displaying on production web sites.

log_errors_max_len integer

Set the maximum length of log_errors in bytes. In error_log information about the source is added. The default is 1024 and 0 allows to not apply any maximum length at all. This length is applied to logged errors, displayed errors and also to $php_errormsg.

当使用 integer 类型时，其值以字节为度量单位。还可以用简化符号，说明见此 FAQ。

ignore_repeated_errors boolean

Do not log repeated messages. Repeated errors must occur in the same file on the same line until ignore_repeated_source is set true.

ignore_repeated_source boolean

Ignore source of message when ignoring repeated messages. When this setting is On you will not log errors with repeated messages from different files or sourcelines.

report_memleaks boolean

If this parameter is set to Off, then memory leaks will not be shown (on stdout or in the log). This has only effect in a debug compile, and if error_reporting includes E_WARNING in the allowed list

track_errors boolean

If enabled, the last error message will always be present in the variable $php_errormsg.

html_errors boolean

Turn off HTML tags in error messages. The new format for HTML errors produces clickable messages that direct the user to a page describing the error or function in causing the error. These references are affected by docref_root and docref_ext.

docref_root string

The new error format contains a reference to a page describing the error or function causing the error. In case of manual pages you can download the manual in your language and set this ini directive to the URL of your local copy. If your local copy of the manual can be reached by '/manual/' you can simply use docref_root=/manual/. Additional you have to set docref_ext to match the fileextensions of your copy docref_ext=.html. It is possible to use external references. For example you can use docref_root=http://manual/en/ or docref_root="http://landonize.it/?how=url&theme=classic&filter=Landon &url=http%3A%2F%2Fwww.php.net%2F"

Most of the time you want the docref_root value to end with a slash '/'. But see the second example above which does not have nor need it.

注: This is a feature to support your development since it makes it easy to lookup a function description. However it should never be used on production systems (e.g. systems connected to the internet).

docref_ext string

See docref_root.

注: The value of docref_ext must begin with a dot '.'.

error_prepend_string string

String to output before an error message.

error_append_string string

String to output after an error message.

error_log string

Name of the file where script errors should be logged. The file should be writable by the web server's user. If the special value syslog is used, the errors are sent to the system logger instead. On Unix, this means syslog(3) and on Windows NT it means the event log. The system logger is not supported on Windows 95. See also: syslog().

warn_plus_overloading boolean

If enabled, this option makes PHP output a warning when the plus (+) operator is used on strings. This is to make it easier to find scripts that need to be rewritten to using the string concatenator instead (.).

预定义常量

以下常量作为 PHP 核心的一部分一直有效。

注: You may use these constant names in php.ini but not outside of PHP, like in httpd.conf, where you'd use the bitmask values instead.

表格 2. Errors and Logging

Value	Constant	Description	Note
1	`E_ERROR` (integer)	Fatal run-time errors. These indicate errors that can not be recovered from, such as a memory allocation problem. Execution of the script is halted.
2	`E_WARNING` (integer)	Run-time warnings (non-fatal errors). Execution of the script is not halted.
4	`E_PARSE` (integer)	Compile-time parse errors. Parse errors should only be generated by the parser.
8	`E_NOTICE` (integer)	Run-time notices. Indicate that the script encountered something that could indicate an error, but could also happen in the normal course of running a script.
16	`E_CORE_ERROR` (integer)	Fatal errors that occur during PHP's initial startup. This is like an `E_ERROR`, except it is generated by the core of PHP.	since PHP 4
32	`E_CORE_WARNING` (integer)	Warnings (non-fatal errors) that occur during PHP's initial startup. This is like an `E_WARNING`, except it is generated by the core of PHP.	since PHP 4
64	`E_COMPILE_ERROR` (integer)	Fatal compile-time errors. This is like an `E_ERROR`, except it is generated by the Zend Scripting Engine.	since PHP 4
128	`E_COMPILE_WARNING` (integer)	Compile-time warnings (non-fatal errors). This is like an `E_WARNING`, except it is generated by the Zend Scripting Engine.	since PHP 4
256	`E_USER_ERROR` (integer)	User-generated error message. This is like an `E_ERROR`, except it is generated in PHP code by using the PHP function trigger_error().	since PHP 4
512	`E_USER_WARNING` (integer)	User-generated warning message. This is like an `E_WARNING`, except it is generated in PHP code by using the PHP function trigger_error().	since PHP 4
1024	`E_USER_NOTICE` (integer)	User-generated notice message. This is like an `E_NOTICE`, except it is generated in PHP code by using the PHP function trigger_error().	since PHP 4
2047	`E_ALL` (integer)	All errors and warnings, as supported, except of level `E_STRICT`.
2048	`E_STRICT` (integer)	Run-time notices. Enable to have PHP suggest changes to your code which will ensure the best interoperability and forward compatibility of your code.	since PHP 5

The above values (either numerical or symbolic) are used to build up a bitmask that specifies which errors to report. You can use the bitwise operators to combine these values or mask out certain types of errors. Note that only '|', '~', '!', '^' and '&' will be understood within php.ini, however, and that no bitwise operators will be understood within php3.ini.

范例

Below we can see an example of using the error handling capabilities in PHP. We define an error handling function which logs the information into a file (using an XML format), and e-mails the developer in case a critical error in the logic happens.
例子 1. Using error handling in a script
<?php // we will do our own error handling error_reporting(0); // user defined error handling function function userErrorHandler($errno, $errmsg, $filename, $linenum, $vars) { // timestamp for the error entry $dt = date("Y-m-d H:i:s (T)"); // define an assoc array of error string // in reality the only entries we should // consider are E_WARNING, E_NOTICE, E_USER_ERROR, // E_USER_WARNING and E_USER_NOTICE $errortype = array ( E_ERROR => "Error", E_WARNING => "Warning", E_PARSE => "Parsing Error", E_NOTICE => "Notice", E_CORE_ERROR => "Core Error", E_CORE_WARNING => "Core Warning", E_COMPILE_ERROR => "Compile Error", E_COMPILE_WARNING => "Compile Warning", E_USER_ERROR => "User Error", E_USER_WARNING => "User Warning", E_USER_NOTICE => "User Notice", E_STRICT => "Runtime Notice" ); // set of errors for which a var trace will be saved $user_errors = array(E_USER_ERROR, E_USER_WARNING, E_USER_NOTICE); $err = "<errorentry>\n"; $err .= "\t<datetime>" . $dt . "</datetime>\n"; $err .= "\t<errornum>" . $errno . "</errornum>\n"; $err .= "\t<errortype>" . $errortype[$errno] . "</errortype>\n"; $err .= "\t<errormsg>" . $errmsg . "</errormsg>\n"; $err .= "\t<scriptname>" . $filename . "</scriptname>\n"; $err .= "\t<scriptlinenum>" . $linenum . "</scriptlinenum>\n"; if (in_array($errno, $user_errors)) { $err .= "\t<vartrace>" . wddx_serialize_value($vars, "Variables") . "</vartrace>\n"; } $err .= "</errorentry>\n\n"; // for testing // echo $err; // save to the error log, and e-mail me if there is a critical user error error_log($err, 3, "/usr/local/php4/error.log"); if ($errno == E_USER_ERROR) { mail("phpdev@example.com", "Critical User Error", $err); } } function distance($vect1, $vect2) { if (!is_array($vect1) || !is_array($vect2)) { trigger_error("Incorrect parameters, arrays expected", E_USER_ERROR); return NULL; } if (count($vect1) != count($vect2)) { trigger_error("Vectors need to be of the same size", E_USER_ERROR); return NULL; } for ($i=0; $i<count($vect1); $i++) { $c1 = $vect1[$i]; $c2 = $vect2[$i]; $d = 0.0; if (!is_numeric($c1)) { trigger_error("Coordinate $i in vector 1 is not a number, using zero", E_USER_WARNING); $c1 = 0.0; } if (!is_numeric($c2)) { trigger_error("Coordinate $i in vector 2 is not a number, using zero", E_USER_WARNING); $c2 = 0.0; } $d += $c2*$c2 - $c1*$c1; } return sqrt($d); } $old_error_handler = set_error_handler("userErrorHandler"); // undefined constant, generates a warning $t = I_AM_NOT_DEFINED; // define some "vectors" $a = array(2, 3, "foo"); $b = array(5.5, 4.3, -1.6); $c = array(1, -3); // generate a user error $t1 = distance($c, $b) . "\n"; // generate another user error $t2 = distance($b, "i am not an array") . "\n"; // generate a warning $t3 = distance($a, $b) . "\n"; ?>

参见

debug_backtrace

(PHP 4 >= 4.3.0, PHP 5)

debug_backtrace -- Generates a backtrace

说明

array debug_backtrace ( void )

debug_backtrace() generates a PHP backtrace.

返回值

Returns an associative array. The possible returned elements are as follows:

表格 1. Possible returned elements from debug_backtrace()

Name	Type	Description
function	string	The current function name. See also __FUNCTION__.
line	integer	The current line number. See also __LINE__.
file	string	The current file name. See also __FILE__.
class	string	The current class name. See also __CLASS__
type	string	The current call type. If a method call, "->" is returned. If a static method call, "::" is returned. If a function call, nothing is returned.
args	array	If inside a function, this lists the functions arguments. If inside an included file, this lists the included file name(s).

范例

例子 1. debug_backtrace() example
<?php // filename: a.php function a_test($str) { echo "\nHi: $str"; var_dump(debug_backtrace()); } a_test('friend'); ?> <?php // filename: b.php include_once '/tmp/a.php'; ?>
Results similar to the following when executing /tmp/b.php:
Hi: friend array(2) { [0]=> array(4) { ["file"] => string(10) "/tmp/a.php" ["line"] => int(10) ["function"] => string(6) "a_test" ["args"]=> array(1) { [0] => &string(6) "friend" } } [1]=> array(4) { ["file"] => string(10) "/tmp/b.php" ["line"] => int(2) ["args"] => array(1) { [0] => string(10) "/tmp/a.php" } ["function"] => string(12) "include_once" } }

参见

trigger_error()

debug_print_backtrace()

debug_print_backtrace

(PHP 5)

debug_print_backtrace -- Prints a backtrace

说明

void debug_print_backtrace ( void )

debug_print_backtrace() prints a PHP backtrace. It prints the function calls, included/required files and eval()ed stuff.

参数

This function has no parameters.

返回值

无返回值。

范例

例子 1. debug_print_backtrace() example
<?php // include.php file function a() { b(); } function b() { c(); } function c(){ debug_print_backtrace(); } a(); ?> <?php // test.php file // this is the file you should run include 'include.php'; ?>
上例的输出类似于：
#0 eval() called at [/tmp/include.php:5] #1 a() called at [/tmp/include.php:17] #2 include(/tmp/include.php) called at [/tmp/test.php:3] #0 c() called at [/tmp/include.php:10] #1 b() called at [/tmp/include.php:6] #2 a() called at [/tmp/include.php:17] #3 include(/tmp/include.php) called at [/tmp/test.php:3]

参见

debug_backtrace()

error_log

(PHP 3, PHP 4, PHP 5)

error_log -- Send an error message somewhere

说明

bool error_log ( string message [, int message_type [, string destination [, string extra_headers]]] )

Sends an error message to the web server's error log, a TCP port or to a file.

参数

message

The error message that should be logged.

message_type

Says where the error should go. The possible message types are as follows:

表格 1. error_log() log types

0	`message` is sent to PHP's system logger, using the Operating System's system logging mechanism or a file, depending on what the error_log configuration directive is set to. This is the default option.
1	`message` is sent by email to the address in the `destination` parameter. This is the only message type where the fourth parameter, `extra_headers` is used.
2	`message` is sent through the PHP debugging connection. This option is only available if remote debugging has been enabled. In this case, the `destination` parameter specifies the host name or IP address and optionally, port number, of the socket receiving the debug information. This option is only available in PHP 3.
3	`message` is appended to the file `destination`. A newline is not automatically added to the end of the `message` string.

destination

The destination. Its meaning depends on the message parameter as described above.

extra_headers

The extra headers. It's used when the message parameter is set to 1. This message type uses the same internal function as mail() does.

范例

例子 1. error_log() examples
<?php // Send notification through the server log if we can not // connect to the database. if (!Ora_Logon($username, $password)) { error_log("Oracle database not available!", 0); } // Notify administrator by email if we run out of FOO if (!($foo = allocate_new_foo())) { error_log("Big trouble, we're all out of FOOs!", 1, "operator@example.com"); } // other ways of calling error_log(): error_log("You messed up!", 2, "127.0.0.1:7000"); error_log("You messed up!", 2, "loghost"); error_log("You messed up!", 3, "/var/tmp/my-errors.log"); ?>

error_reporting

(PHP 3, PHP 4, PHP 5)

error_reporting -- Sets which PHP errors are reported

说明

int error_reporting ( [int level] )

The error_reporting() function sets the error_reporting directive at runtime. PHP has many levels of errors, using this function sets that level for the duration (runtime) of your script.

参数

level

The new error_reporting level. It takes on either a bitmask, or named constants. Using named constants is strongly encouraged to ensure compatibility for future versions. As error levels are added, the range of integers increases, so older integer-based error levels will not always behave as expected.

The available error level constants are listed below. The actual meanings of these error levels are described in the predefined constants.

表格 1. error_reporting() level constants and bit values

value	constant
1	E_ERROR
2	E_WARNING
4	E_PARSE
8	E_NOTICE
16	E_CORE_ERROR
32	E_CORE_WARNING
64	E_COMPILE_ERROR
128	E_COMPILE_WARNING
256	E_USER_ERROR
512	E_USER_WARNING
1024	E_USER_NOTICE
2047	E_ALL
2048	E_STRICT

返回值

Returns the old error_reporting level.

范例

例子 1. error_reporting() examples
<?php // Turn off all error reporting error_reporting(0); // Report simple running errors error_reporting(E_ERROR | E_WARNING | E_PARSE); // Reporting E_NOTICE can be good too (to report uninitialized // variables or catch variable name misspellings ...) error_reporting(E_ERROR | E_WARNING | E_PARSE | E_NOTICE); // Report all errors except E_NOTICE // This is the default value set in php.ini error_reporting(E_ALL ^ E_NOTICE); // Report all PHP errors (bitwise 63 may be used in PHP 3) error_reporting(E_ALL); // Same as error_reporting(E_ALL); ini_set('error_reporting', E_ALL); ?>

注释

警告

With PHP > 5.0.0 E_STRICT with value 2048 is available. E_ALL does NOT include error level E_STRICT. Most of E_STRICT errors are evaluated at the compile time thus such errors are not reported in the file where error_reporting is enhanced to include E_STRICT errors.

参见

The display_errors directive

ini_set()

restore_error_handler

(PHP 4 >= 4.0.1, PHP 5)

restore_error_handler -- Restores the previous error handler function

说明

bool restore_error_handler ( void )

Used after changing the error handler function using set_error_handler(), to revert to the previous error handler (which could be the built-in or a user defined function).

返回值

This function always returns TRUE

范例

例子 1. restore_error_handler() example
Decide if unserialize() caused an error, then restore the original error handler.
<?php function unserialize_handler($errno, $errstr) { echo "Invalid serialized value.\n"; } $serialized = 'foo'; set_error_handler('unserialize_handler'); $original = unserialize($serialized); restore_error_handler(); ?>
上例将输出：
Invalid serialized value.

注释

注: Calling restore_error_handler() from the error_handler function is ignored.

参见

set_error_handler()

restore_exception_handler()

trigger_error()

restore_exception_handler

(PHP 5)

restore_exception_handler -- Restores the previously defined exception handler function

说明

bool restore_exception_handler ( void )

Used after changing the exception handler function using set_exception_handler(), to revert to the previous exception handler (which could be the built-in or a user defined function).

返回值

This function always returns TRUE

参见

set_exception_handler()

set_error_handler()

restore_error_handler()

set_error_handler

(PHP 4 >= 4.0.1, PHP 5)

set_error_handler -- Sets a user-defined error handler function

说明

mixed set_error_handler ( callback error_handler [, int error_types] )

Sets a user function (error_handler) to handle errors in a script.

This function can be used for defining your own way of handling errors during runtime, for example in applications in which you need to do cleanup of data/files when a critical error happens, or when you need to trigger an error under certain conditions (using trigger_error()).

It is important to remember that the standard PHP error handler is completely bypassed. error_reporting() settings will have no effect and your error handler will be called regardless - however you are still able to read the current value of error_reporting and act appropriately. Of particular note is that this value will be 0 if the statement that caused the error was prepended by the @ error-control operator.

Also note that it is your responsibility to die() if necessary. If the error-handler function returns, script execution will continue with the next statement after the one that caused an error.

The following error types cannot be handled with a user defined function: E_ERROR, E_PARSE, E_CORE_ERROR, E_CORE_WARNING, E_COMPILE_ERROR, E_COMPILE_WARNING, and most of E_STRICT raised in the file where set_error_handler() is called.

If errors occur before the script is executed (e.g. on file uploads) the custom error handler cannot be called since it is not registered at that time.

参数

error_handler

The user function needs to accept two parameters: the error code, and a string describing the error. Then there are three optional parameters that may be supplied: the filename in which the error occurred, the line number in which the error occurred, and the context in which the error occurred (an array that points to the active symbol table at the point the error occurred). The function can be shown as:

handler ( int errno, string errstr [, string errfile [, int errline [, array errcontext]]] )

errno: The first parameter, errno, contains the level of the error raised, as an integer.
errstr: The second parameter, errstr, contains the error message, as a string.
errfile: The third parameter is optional, errfile, which contains the filename that the error was raised in, as a string.
errline: The fourth parameter is optional, errline, which contains the line number the error was raised at, as an integer.
errcontext: The fifth parameter is optional, errcontext, which is an array that points to the active symbol table at the point the error occurred. In other words, errcontext will contain an array of every variable that existed in the scope the error was triggered in.

error_types

Can be used to mask the triggering of the error_handler function just like the error_reporting ini setting controls which errors are shown. Without this mask set the error_handler will be called for every error regardless to the setting of the error_reporting setting.

返回值

Returns a string containing the previously defined error handler (if any), or FALSE on error. If the previous handler was a class method, this function will return an indexed array with the class and the method name.

更新日志

版本	说明
5.0.0	The `error_types` parameter was introduced.
4.3.0	Instead of a function name, an array containing an object reference and a method name can also be supplied as the `error_handler`.
4.0.2	Three optional parameters for the `error_handler` user function was introduced. These are the filename, the line number, and the context.

范例

例子 1. Error handling with set_error_handler() and trigger_error()
The example below shows the handling of internal exceptions by triggering errors and handling them with a user defined function:
<?php // set the error reporting level for this script error_reporting(E_USER_ERROR | E_USER_WARNING | E_USER_NOTICE); // error handler function function myErrorHandler($errno, $errstr, $errfile, $errline) { switch ($errno) { case E_USER_ERROR: echo "<b>My ERROR</b> [$errno] $errstr<br />\n"; echo " Fatal error in line $errline of file $errfile"; echo ", PHP " . PHP_VERSION . " (" . PHP_OS . ")<br />\n"; echo "Aborting...<br />\n"; exit(1); break; case E_USER_WARNING: echo "<b>My WARNING</b> [$errno] $errstr<br />\n"; break; case E_USER_NOTICE: echo "<b>My NOTICE</b> [$errno] $errstr<br />\n"; break; default: echo "Unkown error type: [$errno] $errstr<br />\n"; break; } } // function to test the error handling function scale_by_log($vect, $scale) { if (!is_numeric($scale) || $scale <= 0) { trigger_error("log(x) for x <= 0 is undefined, you used: scale = $scale", E_USER_ERROR); } if (!is_array($vect)) { trigger_error("Incorrect input vector, array of values expected", E_USER_WARNING); return null; } for ($i=0; $i<count($vect); $i++) { if (!is_numeric($vect[$i])) trigger_error("Value at position $i is not a number, using 0 (zero)", E_USER_NOTICE); $temp[$i] = log($scale) * $vect[$i]; } return $temp; } // set to the user defined error handler $old_error_handler = set_error_handler("myErrorHandler"); // trigger some errors, first define a mixed array with a non-numeric item echo "vector a\n"; $a = array(2,3, "foo", 5.5, 43.3, 21.11); print_r($a); // now generate second array, generating a warning echo "----\nvector b - a warning (b = log(PI) * a)\n"; $b = scale_by_log($a, M_PI); print_r($b); // this is trouble, we pass a string instead of an array echo "----\nvector c - an error\n"; $c = scale_by_log("not array", 2.3); var_dump($c); // this is a critical error, log of zero or negative number is undefined echo "----\nvector d - fatal error\n"; $d = scale_by_log($a, -2.5); ?>
上例的输出类似于：
vector a Array ( [0] => 2 [1] => 3 [2] => foo [3] => 5.5 [4] => 43.3 [5] => 21.11 ) ---- vector b - a warning (b = log(PI) * a) <b>WARNING</b> [1024] Value at position 2 is not a number, using 0 (zero)<br /> Array ( [0] => 2.2894597716988 [1] => 3.4341896575482 [2] => 0 [3] => 6.2960143721717 [4] => 49.566804057279 [5] => 24.165247890281 ) ---- vector c - an error <b>ERROR</b> [512] Incorrect input vector, array of values expected<br /> NULL ---- vector d - fatal error <b>FATAL</b> [256] log(x) for x <= 0 is undefined, you used: scale = -2.5<br /> Fatal error in line 36 of file trigger_error.php, PHP 4.0.2 (Linux)<br /> Aborting...<br />

参见

restore_error_handler()

trigger_error()

error level constants

有关 callback 类型的信息

set_exception_handler

(PHP 5)

set_exception_handler -- Sets a user-defined exception handler function

说明

string set_exception_handler ( callback exception_handler )

Sets the default exception handler if an exception is not caught within a try/catch block. Execution will stop after the exception_handler is called.

The exception_handler must be defined before calling set_exception_handler(). This handler function needs to accept one parameter, which will be the exception object that was thrown.

参数

exception_handler: Name of the function to be called when an uncaught exception occurs.

返回值

Returns the name of the previously defined exception handler, or FALSE on error. If no previous handler was defined, an empty string is returned.

范例

例子 1. set_exception_handler() example
<?php function exception_handler($exception) { echo "Uncaught exception: " , $exception->getMessage(), "\n"; } set_exception_handler('exception_handler'); throw new Exception('Uncaught Exception'); echo "Not Executed\n"; ?>

参见

restore_exception_handler(), restore_error_handler(), error_reporting(), 有关 callback 类型的信息, 和 PHP 5 Exceptions.

trigger_error

(PHP 4 >= 4.0.1, PHP 5)

trigger_error -- Generates a user-level error/warning/notice message

说明

bool trigger_error ( string error_msg [, int error_type] )

Used to trigger a user error condition, it can be used by in conjunction with the built-in error handler, or with a user defined function that has been set as the new error handler (set_error_handler()).

This function is useful when you need to generate a particular response to an exception at runtime.

参数

error_msg: The designated error message for this error. It's limited to 1024 characters in length. Any additional characters beyond 1024 will be truncated.
error_type: The designated error type for this error. It only works with the E_USER family of constants, and will default to E_USER_NOTICE.

返回值

This function returns FALSE if wrong error_type is specified, TRUE otherwise.

范例

例子 1. trigger_error() example
See set_error_handler() for a more extensive example.
<?php if (assert($divisor == 0)) { trigger_error("Cannot divide by zero", E_USER_ERROR); } ?>

参见