Php Manual

Official.%20php_manual_en

User Manual: manual pdf -FilePursuit

Open the PDF directly: View PDF .
Page Count: 4081 [warning: Documents this large are best viewed by clicking the View PDF Link!]

PHP Manual
Preface
Part I. Getting Started
Part II. Language Reference
Part III. Features
Part IV. Function Reference
Part V. Extending PHP 4.0
Part VI. PHP API: Interfaces for extension writers
- Chapter 43. Streams API for PHP Extension Authors
Part VII. FAQ: Frequently Asked Questions
Part VIII. Appendixes

PHP Manual

Stig Sæther Bakken, Alexander Aulbach, Egon Schmid, Jim Winstead, Lars Torben Wilson, Rasmus

Lerdorf, Andrei Zmievski, and Jouni Ahto

Edited by

Stig Sæther Bakken and Egon Schmid

PHP Manual

Published 03-06-2003

Publication License, v1.0 or later (the latest version is presently available at http://www.opencontent.org/openpub/).

Distribution of substantively modified versions of this document is prohibited without the explicit permission of the copyright holder.

Distribution of the work or derivative of the work in any standard (paper) book form is prohibited unless prior permission is obtained from the copyright

holder.

The members of the PHP Documentation Group are listed on the front page of this manual. In case you would like to contact the group, please write to

phpdoc@lists.php.net [mailto:phpdoc@lists.php.net].

and conditions set forth in the Open Publication License, v1.0 or later (the latest version is presently available at http://www.opencontent.org/openpub/).

Table of Contents

Preface ............................................................................................................................................. viii

I. Getting Started ................................................................................................................................... 1

1. Introduction .............................................................................................................................. 2

2. A simple tutorial ........................................................................................................................ 5

3. Installation ............................................................................................................................. 10

4. Configuration .......................................................................................................................... 45

5. Security ................................................................................................................................. 54

II. Language Reference ........................................................................................................................ 68

6. Basic syntax ........................................................................................................................... 69

7. Types .................................................................................................................................... 72

8. Variables ................................................................................................................................ 95

9. Constants ..............................................................................................................................105

10. Expressions ..........................................................................................................................107

11. Operators .............................................................................................................................109

12. Control Structures .................................................................................................................116

13. Functions .............................................................................................................................131

14. Classes and Objects ...............................................................................................................138

15. References Explained .............................................................................................................151

III. Features ......................................................................................................................................155

16. HTTP authentication with PHP ................................................................................................156

17. Cookies ...............................................................................................................................158

18. Handling file uploads .............................................................................................................159

19. Using remote files .................................................................................................................164

20. Connection handling ..............................................................................................................166

21. Persistent Database Connections ..............................................................................................167

22. Safe Mode ...........................................................................................................................169

23. Using PHP from the command line ...........................................................................................175

IV. Function Reference .......................................................................................................................184

I. Apache-specific Functions ........................................................................................................187

II. Array Functions .....................................................................................................................199

III. Aspell functions [deprecated] ..................................................................................................276

IV. BCMath Arbitrary Precision Mathematics Functions ...................................................................282

V. Bzip2 Compression Functions ..................................................................................................294

VI. Calendar functions ................................................................................................................307

VII. CCVS API Functions ...........................................................................................................328

VIII. COM support functions for Windows .....................................................................................346

IX. Class/Object Functions ..........................................................................................................364

X. ClibPDF functions .................................................................................................................381

XI. Crack functions ....................................................................................................................458

XII. CURL, Client URL Library Functions .....................................................................................465

XIII. Cybercash payment functions ................................................................................................491

XIV. Cyrus IMAP administration functions .....................................................................................497

XV. Character type functions .......................................................................................................505

XVI. Database (dbm-style) abstraction layer functions ......................................................................518

XVII. Date and Time functions .....................................................................................................538

XVIII. dBase functions ...............................................................................................................558

XIX. DBM Functions [deprecated] ................................................................................................571

XX. dbx functions ......................................................................................................................583

XXI. DB++ Functions .................................................................................................................596

XXII. Direct IO functions ............................................................................................................647

XXIII. Directory functions ...........................................................................................................658

XXIV. DOM XML functions .......................................................................................................670

XXV. .NET functions .................................................................................................................760

XXVI. Error Handling and Logging Functions .................................................................................763

XXVII. FrontBase Functions ........................................................................................................781

XXVIII. filePro functions ............................................................................................................839

XXIX. Filesystem functions .........................................................................................................848

XXX. Forms Data Format functions ..............................................................................................930

XXXI. FriBiDi functions .............................................................................................................968

XXXII. FTP functions .................................................................................................................971

XXXIII. Function Handling functions .......................................................................................... 1008

XXXIV. Gettext ...................................................................................................................... 1022

XXXV. GMP functions ............................................................................................................. 1033

XXXVI. HTTP functions ........................................................................................................... 1075

XXXVII. Hyperwave functions ................................................................................................... 1084

XXXVIII. Hyperwave API functions ........................................................................................... 1153

XXXIX. iconv functions ............................................................................................................ 1210

XL. Image functions ................................................................................................................. 1217

XLI. IMAP, POP3 and NNTP functions ....................................................................................... 1328

XLII. Informix functions ........................................................................................................... 1405

XLIII. InterBase functions ......................................................................................................... 1448

XLIV. Ingres II functions .......................................................................................................... 1481

XLV. IRC Gateway Functions .................................................................................................... 1503

XLVI. PHP / Java Integration ..................................................................................................... 1530

XLVII. LDAP functions ............................................................................................................ 1536

XLVIII. Mail functions ............................................................................................................. 1585

XLIX. mailparse functions ......................................................................................................... 1592

L. Mathematical Functions ......................................................................................................... 1607

LI. Multi-Byte String Functions .................................................................................................. 1658

LII. MCAL functions ................................................................................................................ 1712

LIII. Mcrypt Encryption Functions .............................................................................................. 1757

LIV. MCVE Payment Functions ................................................................................................. 1800

LV. Mhash Functions ................................................................................................................ 1878

LVI. Mimetype Functions .......................................................................................................... 1886

LVII. Microsoft SQL Server functions ......................................................................................... 1889

LVIII. Ming functions for Flash .................................................................................................. 1922

LIX. Miscellaneous functions ..................................................................................................... 2040

LX. mnoGoSearch Functions ...................................................................................................... 2065

LXI. mSQL functions ............................................................................................................... 2095

LXII. MySQL Functions ........................................................................................................... 2137

LXIII. Improved MySQL Extension ............................................................................................ 2194

LXIV. Mohawk Software session handler functions ........................................................................ 2279

LXV. muscat functions ............................................................................................................. 2302

LXVI. Network Functions ......................................................................................................... 2309

LXVII. Ncurses terminal screen control functions .......................................................................... 2345

LXVIII. Lotus Notes functions ................................................................................................... 2472

LXIX. Unified ODBC functions .................................................................................................. 2488

LXX. Object Aggregation/Composition Functions .......................................................................... 2539

LXXI. Oracle 8 functions .......................................................................................................... 2556

LXXII. OpenSSL functions ........................................................................................................ 2613

LXXIII. Oracle functions ........................................................................................................... 2651

LXXIV. Ovrimos SQL functions ................................................................................................. 2676

LXXV. Output Control Functions ............................................................................................... 2699

LXXVI. Object property and method call overloading ..................................................................... 2716

LXXVII. PDF functions ............................................................................................................ 2720

LXXVIII. Verisign Payflow Pro functions .................................................................................... 2843

LXXIX. PHP Options&Information ............................................................................................. 2852

LXXX. POSIX functions ........................................................................................................... 2908

LXXXI. PostgreSQL functions ................................................................................................... 2942

LXXXII. Process Control Functions ............................................................................................ 3017

LXXXIII. Program Execution functions ....................................................................................... 3033

PHP Manual

LXXXIV. Printer functions ........................................................................................................ 3046

LXXXV. Pspell Functions ......................................................................................................... 3080

LXXXVI. GNU Readline .......................................................................................................... 3100

LXXXVII. GNU Recode functions .............................................................................................. 3110

LXXXVIII. Regular Expression Functions (Perl-Compatible) ........................................................... 3115

LXXXIX. qtdom functions ........................................................................................................ 3155

XC. Regular Expression Functions (POSIX Extended) .................................................................... 3159

XCI. Semaphore, Shared Memory and IPC Functions ..................................................................... 3170

XCII. SESAM database functions ............................................................................................... 3190

XCIII. Session handling functions ............................................................................................... 3219

XCIV. Shared Memory Functions ............................................................................................... 3247

XCV. Shockwave Flash functions ............................................................................................... 3256

XCVI. SNMP functions ............................................................................................................. 3329

XCVII. Socket functions ........................................................................................................... 3338

XCVIII. Stream functions .......................................................................................................... 3381

XCIX. String functions ............................................................................................................. 3415

C. Sybase functions .................................................................................................................. 3523

CI. Tokenizer functions ............................................................................................................. 3552

CII. URL Functions .................................................................................................................. 3560

CIII. Variable Functions ............................................................................................................ 3570

CIV. vpopmail functions ........................................................................................................... 3608

CV. W32api functions ............................................................................................................... 3627

CVI. WDDX Functions ............................................................................................................. 3635

CVII. XML parser functions ....................................................................................................... 3644

CVIII. XML-RPC functions ....................................................................................................... 3679

CIX. XSLT functions ................................................................................................................ 3694

CX. YAZ functions .................................................................................................................. 3712

CXI. YP/NIS Functions ............................................................................................................. 3741

CXII. Zip File Functions (Read Only Access) ................................................................................ 3754

CXIII. Zlib Compression Functions ............................................................................................. 3767

V. Extending PHP 4.0 ..............................................................................................................................

24. Overview ........................................................................................................................... 3794

25. Extension Possibilities ......................................................................................................... 3796

26. Source Layout .................................................................................................................... 3798

27. PHP's Automatic Build System .............................................................................................. 3801

28. Creating Extensions ............................................................................................................. 3803

29. Using Extensions ................................................................................................................ 3806

30. Troubleshooting .................................................................................................................. 3807

31. Source Discussion ............................................................................................................... 3808

32. Accepting Arguments .......................................................................................................... 3815

33. Creating Variables ............................................................................................................... 3828

34. Duplicating Variable Contents: The Copy Constructor ............................................................... 3840

35. Returning Values ................................................................................................................ 3841

36. Printing Information ............................................................................................................ 3843

37. Startup and Shutdown Functions ............................................................................................ 3847

38. Calling User Functions ......................................................................................................... 3848

39. Initialization File Support ..................................................................................................... 3850

40. Where to Go from Here ........................................................................................................ 3852

41. Reference: Some Configuration Macros .................................................................................. 3853

42. API Macros ....................................................................................................................... 3854

VI. PHP API: Interfaces for extension writers ........................................................................................ 3855

43. Streams API for PHP Extension Authors ................................................................................. 3856

VII. FAQ: Frequently Asked Questions ................................................................................................ 3906

44. General Information ............................................................................................................ 3907

45. Mailing lists ....................................................................................................................... 3909

46. Obtaining PHP ................................................................................................................... 3911

47. Database issues ................................................................................................................... 3913

48. Installation ......................................................................................................................... 3916

PHP Manual

49. Build Problems ................................................................................................................... 3921

50. Using PHP ......................................................................................................................... 3926

51. PHP and HTML .................................................................................................................. 3930

52. PHP and COM ................................................................................................................... 3933

53. PHP and other languages ...................................................................................................... 3936

54. Migrating from PHP 2 to PHP 3 ............................................................................................. 3937

55. Migrating from PHP 3 to PHP 4 ............................................................................................. 3938

56. Miscellaneous Questions ...................................................................................................... 3939

VIII. Appendixes ............................................................................................................................. 3940

A. History of PHP and related projects ......................................................................................... 3941

B. Migrating from PHP 3 to PHP 4 .............................................................................................. 3944

C. Migrating from PHP/FI 2 to PHP 3 .......................................................................................... 3949

D. Debugging PHP ................................................................................................................... 3953

E. Extending PHP 3 .................................................................................................................. 3956

F. List of Function Aliases ......................................................................................................... 3967

G. List of Reserved Words ......................................................................................................... 3975

H. List of Resource Types .......................................................................................................... 3991

I. List of Supported Protocols/Wrappers ....................................................................................... 4008

J. List of Supported Socket Transports ......................................................................................... 4013

K. PHP type comparison tables ................................................................................................... 4016

L. List of Parser Tokens ............................................................................................................ 4018

M. About the manual ................................................................................................................ 4021

N. Function Index .................................................................................................................... 4025

PHP Manual

vii

Preface

Abstract

PHP, which stands for "PHP: Hypertext Preprocessor" is a widely-used Open Source general-purpose scripting language

that is especially suited for Web development and can be embedded into HTML. Its syntax draws upon C, Java, and Perl,

and is easy to learn. The main goal of the language is to allow web developers to write dynamically generated webpages

quickly, but you can do much more with PHP.

This manual consists primarily of a function reference, but also contains a language reference, explanations of some of

PHP's major features, and other supplemental information.

You can download this manual in several formats at http://www.php.net/docs.php. The downloads [http://www.php.net/

downloads.php] are updated as the content changes. More information about how this manual is developed can be found in

the 'About the manual' appendix.

See Also

See also is_array(),explode(),implode(),split(),preg_split(), and join().

Array Functions

202

array_change_key_case

(PHP 4 >= 4.2.0)

array_change_key_case - Returns an array with all string keys lowercased or uppercased

Description

array array_change_key_case (array input [, int case])

array_change_key_case() changes the keys in the input array to be all lowercase or uppercase. The change depends on the

last optional case parameter. You can pass two constants there, CASE_UPPER and CASE_LOWER. The default is

CASE_LOWER. The function will leave number indices as is.

Example 102. array_change_key_case() example

<?php

$input_array = array("FirSt" => 1, "SecOnd" => 4);

print_r(array_change_key_case($input_array, CASE_UPPER));

The printout of the above program will be:

Array

([FIRST] => 1

[SECOND] => 2

)

If an array has indices that will be the same once run through this function (e.g. "keY" and "kEY"), the value that is later in

the array will override other indices.

203

array_chunk

(PHP 4 >= 4.2.0)

array_chunk - Split an array into chunks

Description

array array_chunk (array input, int size [, bool preserve_keys])

array_chunk() splits the array into several arrays with size values in them. You may also have an array with less values at

the end. You get the arrays as members of a multidimensional array indexed with numbers starting from zero.

By setting the optional preserve_keys parameter to TRUE, you can force PHP to preserve the original keys from the input ar-

ray. If you specify FALSE new number indices will be used in each resulting array with indices starting from zero. The de-

fault is FALSE.

Example 103. array_chunk() example

<?php

$input_array = array('a', 'b', 'c', 'd', 'e');

print_r(array_chunk($input_array, 2));

print_r(array_chunk($input_array, 2, TRUE));

The printout of the above program will be:

Array

([0] => Array

([0] => a

[1] => b

)

[1] => Array

([0] => c

[1] => d

)

[2] => Array

([0] => e

)

Array

([0] => Array

([0] => a

[1] => b

)

[1] => Array

([2] => c

[3] => d

)

[2] => Array

(

204

[4] => e

)

array_chunk

205

array_combine

(PHP 5 CVS only)

array_combine - Creates an array by using one array for keys and another for its values

Description

array array_combine (array keys, array values)

Returns an array by using the values from the keys array as keys and the values from the values array as the corresponding

values.

Returns FALSE if the number of elements for each array isn't equal or if the arrays are empty.

Example 104. A simple array_combine() example

<?php

$a = array('green','red','yellow');

$b = array('avocado','apple','banana');

$c = array_combine($a, $b);

print_r($c);

/* Outputs:

Array

([green] => avocado

[red] => apple

[yellow] => banana

)

See also array_merge(),array_walk(), and array_values().

206

array_count_values

(PHP 4 )

array_count_values - Counts all the values of an array

Description

array array_count_values (array input)

array_count_values() returns an array using the values of the input array as keys and their frequency in input as values.

Example 105. array_count_values() example

<?php

$array = array (1, "hello", 1, "world", "hello");

print_r(array_count_values ($array));

The printout of the above program will be:

Array

([1] => 2

[hello] => 2

[world] => 1

)

207

array_diff_assoc

(PHP 4 >= 4.3.0)

array_diff_assoc - Computes the difference of arrays with additional index check

Description

array array_diff_assoc (array array1, array array2 [, array ...])

array_diff_assoc() returns an array containing all the values from array1 that are not present in any of the other arguments.

Note that the keys are used in the comparison unlike array_diff().

Example 106. array_diff_assoc() example

<?php

$array1 = array ("a" => "green", "b" => "brown", "c" => "blue", "red");

$array2 = array ("a" => "green", "yellow", "red");

$result = array_diff_assoc ($array1, $array2);

/* The result is:

Array

([b] => brown

[c] => blue

[0] => red

)

In our example above you see the "a" => "green" pair is present in both arrays and thus it is not in the ouput from the

function. Unlike this, the pair 0 => "red" is in the ouput because in the second argument "red" has key which is 1.

Two values from key => value pairs are considered equal only if (string) $elem1 === (string) $elem2 . In other

words a strict check takes place so the string representations must be the same.

Note: Please note that this function only checks one dimension of a n-dimensional array. Of course you can check

deeper dimensions by using, for example, array_diff_assoc($array1[0], $array2[0]);.

See also array_diff(),array_intersect(), and array_intersect_assoc().

208

array_diff

(PHP 4 >= 4.0.1)

array_diff - Computes the difference of arrays

Description

array array_diff (array array1, array array2 [, array ...])

array_diff() returns an array containing all the values of array1 that are not present in any of the other arguments. Note that

keys are preserved.

Example 107. array_diff() example

$array1 = array ("a" => "green", "red", "blue", "red");

$array2 = array ("b" => "green", "yellow", "red");

$result = array_diff ($array1, $array2);

This makes $result have array ("blue");. Multiple occurrences in $array1 are all treated the same way.

Note: Two elements are considered equal if and only if (string) $elem1 === (string) $elem2. In words:

when the string representation is the same.

Note: Please note that this function only checks one dimension of a n-dimensional array. Of course you can check

deeper dimensions by using array_diff($array1[0], $array2[0]);.

Warning

This was broken in PHP 4.0.4!

See also array_diff_assoc(),array_intersect(), and array_intersect_assoc().

209

array_fill

(PHP 4 >= 4.2.0)

array_fill - Fill an array with values

Description

array array_fill (int start_index, int num, mixed value)

array_fill() fills an array with num entries of the value of the value parameter, keys starting at the start_index parameter.

Note that num must be a number greater than zero, or PHP will throw a warning.

Example 108. array_fill() example

<?php

$a = array_fill(5, 6, 'banana');

print_r($a);

$a now is :

Array

([5] => banana

[6] => banana

[7] => banana

[8] => banana

[9] => banana

[10] => banana

)

210

array_filter

(PHP 4 >= 4.0.6)

array_filter - Filters elements of an array using a callback function

Description

array array_filter (array input [, callback function])

array_filter() iterates over each value in the input array passing them to the callback function. If the callback function re-

turns true, the current value from input is returned into the result array. Array keys are preserved.

Example 109. array_filter() example

<?php

function odd($var) {

return ($var % 2 == 1);

}

function even($var) {

return ($var % 2 == 0);

}

$array1 = array ("a"=>1, "b"=>2, "c"=>3, "d"=>4, "e"=>5);

$array2 = array (6, 7, 8, 9, 10, 11, 12);

echo "Odd :\n";

print_r(array_filter($array1, "odd"));

echo "Even:\n";

print_r(array_filter($array2, "even"));

The printout of the program above will be:

Odd :

Array

([a] => 1

[c] => 3

[e] => 5

)

Even:

Array

([0] => 6

[2] => 8

[4] => 10

[6] => 12

)

Users may not change the array itself from the callback function. e.g. Add/delete an element, unset the array that ar-

ray_filter() is applied to. If the array is changed, the behavior of this function is undefined.

See also array_map(),array_reduce(), and array_walk().

211

array_flip

(PHP 4 )

array_flip - Exchanges all keys with their associated values in an array

Description

array array_flip (array trans)

array_flip() returns an array in flip order, i.e. keys from trans become values and values from trans become keys.

Note that the values of trans need to be valid keys, i.e. they need to be either integer or string. A warning will be emitted if a

value has the wrong type, and the key/value pair in question will not be flipped.

If a value has several occurrences, the latest key will be used as its values, and all others will be lost.

array_flip() returns FALSE if it fails.

Example 110. array_flip() example

<?php

$trans = array_flip ($trans);

$original = strtr ($str, $trans);

Example 111. array_flip() example : collision

<?php

$trans = array ("a" => 1, "b" => 1, "c" => 2);

$trans = array_flip ($trans);

print_r($trans);

now $trans is :

Array

([1] => b

[2] => c

)

212

array_intersect_assoc

(PHP 4 >= 4.3.0)

array_intersect_assoc - Computes the intersection of arrays with additional index check

Description

array array_intersect_assoc (array array1, array array2 [, array ...])

array_intersect_assoc() returns an array containing all the values of array1 that are present in all the arguments. Note that

the keys are used in the comparison unlike in array_intersect().

Example 112. array_intersect_assoc() example

<?php

$array1 = array ("a" => "green", "b" => "brown", "c" => "blue", "red");

$array2 = array ("a" => "green", "yellow", "red");

$result_array = array_intersect_assoc ($array1, $array2);

/* $result_array will look like:

Array

([a] => green

)

In our example you see that only the pair "a" => "green" is present in both arrays and thus is returned. The value "red"

is not returned because in $array1 it's key is 2while the key of "red" in $array2 it is 1.

The two values from the key => value pairs are considered equal only if (string) $elem1 === (string) $elem2

. In otherwords a strict type check is executed so the string representation must be the same.

See also array_intersect(),array_diff() and array_diff_assoc().

213

array_intersect

(PHP 4 >= 4.0.1)

array_intersect - Computes the intersection of arrays

Description

array array_intersect (array array1, array array2 [, array ...])

array_intersect() returns an array containing all the values of array1 that are present in all the arguments. Note that keys

are preserved.

Example 113. array_intersect() example

<?php

$array1 = array ("a" => "green", "red", "blue");

$array2 = array ("b" => "green", "yellow", "red");

$result = array_intersect ($array1, $array2);

This makes $result have

Array

([a] => green

[0] => red

)

Note: Two elements are considered equal if and only if (string) $elem1 === (string) $elem2. In words:

when the string representation is the same.

Warning

This was broken in PHP 4.0.4!

See also array_intersect_assoc(),array_diff(), and array_diff_assoc().

214

array_key_exists

(PHP 4 >= 4.1.0)

array_key_exists - Checks if the given key or index exists in the array

Description

bool array_key_exists (mixed key, array search)

array_key_exists() returns TRUE if the given key is set in the array. key can be any value possible for an array index.

Example 114. array_key_exists() example

<?php

$search_array = array("first" => 1, "second" => 4);

if (array_key_exists("first", $search_array)) {

echo "The 'first' element is in the array";

}

Note: The name of this function is key_exists() in PHP version 4.0.6.

See Also

RedHat has discontinued support for CCVS; however, a slightly outdated manual is still available at http://redhat.com/docs/

manuals/ccvs/.

329

ccvs_add

(4.0.2 - 4.2.3 only)

ccvs_add - Add data to a transaction

Description

string ccvs_add (string session, string invoice, string argtype, string argval)

Warning

This function is currently not documented; only the argument list is available.

330

ccvs_auth

(4.0.2 - 4.2.3 only)

ccvs_auth - Perform credit authorization test on a transaction

Description

string ccvs_auth (string session, string invoice)

Warning

This function is currently not documented; only the argument list is available.

331

ccvs_command

(4.0.2 - 4.2.3 only)

ccvs_command - Performs a command which is peculiar to a single protocol, and thus is not available

in the general CCVS API

Description

string ccvs_command (string session, string type, string argval)

Warning

This function is currently not documented; only the argument list is available.

332

ccvs_count

(4.0.2 - 4.2.3 only)

ccvs_count - Find out how many transactions of a given type are stored in the system

Description

int ccvs_count (string session, string type)

Warning

This function is currently not documented; only the argument list is available.

333

ccvs_delete

(4.0.2 - 4.2.3 only)

ccvs_delete - Delete a transaction

Description

string ccvs_delete (string session, string invoice)

Warning

This function is currently not documented; only the argument list is available.

334

ccvs_done

(4.0.2 - 4.2.3 only)

ccvs_done - Terminate CCVS engine and do cleanup work

Description

string ccvs_done (string sess)

Warning

This function is currently not documented; only the argument list is available.

335

ccvs_init

(4.0.2 - 4.2.3 only)

ccvs_init - Initialize CCVS for use

Description

string ccvs_init (string name)

Warning

This function is currently not documented; only the argument list is available.

336

ccvs_lookup

(4.0.2 - 4.2.3 only)

ccvs_lookup - Look up an item of a particular type in the database #

Description

string ccvs_lookup (string session, string invoice, int inum)

Warning

This function is currently not documented; only the argument list is available.

337

ccvs_new

(4.0.2 - 4.2.3 only)

ccvs_new - Create a new, blank transaction

Description

string ccvs_new (string session, string invoice)

Warning

This function is currently not documented; only the argument list is available.

338

ccvs_report

(4.0.2 - 4.2.3 only)

ccvs_report - Return the status of the background communication process

Description

string ccvs_report (string session, string type)

Warning

This function is currently not documented; only the argument list is available.

339

ccvs_return

(4.0.2 - 4.2.3 only)

ccvs_return - Transfer funds from the merchant to the credit card holder

Description

string ccvs_return (string session, string invoice)

Warning

This function is currently not documented; only the argument list is available.

340

ccvs_reverse

(4.0.2 - 4.2.3 only)

ccvs_reverse - Perform a full reversal on an already-processed authorization

Description

string ccvs_reverse (string session, string invoice)

Warning

This function is currently not documented; only the argument list is available.

341

ccvs_sale

(4.0.2 - 4.2.3 only)

ccvs_sale - Transfer funds from the credit card holder to the merchant

Description

string ccvs_sale (string session, string invoice)

Warning

This function is currently not documented; only the argument list is available.

342

ccvs_status

(4.0.2 - 4.2.3 only)

ccvs_status - Check the status of an invoice

Description

string ccvs_status (string session, string invoice)

Warning

This function is currently not documented; only the argument list is available.

343

ccvs_textvalue

(4.0.2 - 4.2.3 only)

ccvs_textvalue - Get text return value for previous function call

Description

string ccvs_textvalue (string session)

Warning

This function is currently not documented; only the argument list is available.

344

ccvs_void

(4.0.2 - 4.2.3 only)

ccvs_void - Perform a full reversal on a completed transaction

Description

string ccvs_void (string session, string invoice)

Warning

This function is currently not documented; only the argument list is available.

345

COM support functions for Windows

Table of Contents

COM ...............................................................................................................................................350

VARIANT ........................................................................................................................................352

com_addref .......................................................................................................................................353

com_get ...........................................................................................................................................354

com_invoke ......................................................................................................................................355

com_isenum ......................................................................................................................................356

com_load_typelib ...............................................................................................................................357

com_load ..........................................................................................................................................358

com_propget .....................................................................................................................................359

com_propput .....................................................................................................................................360

com_propset .....................................................................................................................................361

com_release ......................................................................................................................................362

com_set ............................................................................................................................................363

346

Introduction

COM is a technology which allows the reuse of code written in any language (by any language) using a standard calling

convention and hiding behind APIs the implementation details such as what machine the Component is stored on and the

executable which houses it. It can be thought of as a super Remote Procedure Call (RPC) mechanism with some basic object

roots. It separates implementation from interface.

COM encourages versioning, separation of implementation from interface and hiding the implementation details such as ex-

ecutable location and the language it was written in.

Requirements

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

Installation

There is no installation needed to use these functions; they are part of the PHP core.

The windows version of PHP has built in support for this extension. You do not need to load any additional extension in or-

der to use these functions.

Runtime Configuration

The behaviour of these functions is affected by settings in php.ini.

Table 28. Com configuration options

Name Default Changeable

com.allow_dcom "0" PHP_INI_SYSTEM

com.autoregister_typelib "0" PHP_INI_SYSTEM

com.autoregister_verbose "0" PHP_INI_SYSTEM

com.autoregister_casesensitive "1" PHP_INI_SYSTEM

com.typelib_file "" PHP_INI_SYSTEM

For further details and definition of the PHP_INI_* constants see ini_set().

Predefined Constants

The constants below are defined by this extension, and will only be available when the extension has either been compiled

into PHP or dynamically loaded at runtime.

CLSCTX_INPROC_SERVER (integer)

CLSCTX_INPROC_HANDLER (integer)

CLSCTX_LOCAL_SERVER (integer)

CLSCTX_REMOTE_SERVER (integer)

CLSCTX_SERVER (integer)

347

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)

COM support functions for Windows

348

CP_THREAD_ACP (integer)

See Also

For further information on COM read the COM specification [http://www.microsoft.com/Com/resources/comdocs.asp] or

perhaps take a look at Don Box's Yet Another COM Library (YACL) [http:/ / www.develop.com/ essentialcom/ sources/

YACL.htm]

COM support functions for Windows

349

COM

()

COM - COM class

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

Description

The COM class provides a framework to integrate (D)COM components into your php scripts.

Methods

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

COM class constructor. Parameters:

module_name

name or class-id of the requested component.

server_name

name of the DCOM server from which the component should be fetched. If NULL,localhost is assumed. To allow

DCOM com.allow_dcom has to be set to TRUE in php.ini.

codepage

specifies the codepage that is used to convert php-strings to unicode-strings and vice versa. Possible values are CP_ACP,

CP_MACCP,CP_OEMCP,CP_SYMBOL,CP_THREAD_ACP,CP_UTF7 and CP_UTF8.

Example 182. COM example (1)

// starting word

$word = new COM("word.application") or die("Unable to instanciate Word");

print "Loaded Word, version {$word->Version}\n";

//bring it to front

$word->Visible = 1;

//open an empty document

$word->Documents->Add();

//do some weird stuff

$word->Selection->TypeText("This is a test...");

$word->Documents[1]->SaveAs("Useless test.doc");

//closing word

$word->Quit();

//free the object

$word->Release();

$word = null;

350

Example 183. COM example (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"); // Recordset

$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++; // increments rowcount

$rs->MoveNext();

}

$rs->Close();

$conn->Close();

$rs->Release();

$conn->Release();

$rs = null;

$conn = null;

COM

351

VARIANT

()

VARIANT - VARIANT class

$vVar = new VARIANT($var)

Description

A simple container to wrap variables into VARIANT structures.

Methods

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

VARIANT class constructor. Parameters:

value

initial value. if omitted an VT_EMPTY object is created.

typespecifies the content type of the VARIANT object. Possible values are 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 and VT_VARIANT. These values are mutual exclusive, but they can be combined with

VT_BYREF to specify being a value. If omitted, the type of value is used. Consult the msdn library for additional in-

formation.

codepage

specifies the codepage that is used to convert php-strings to unicode-strings and vice versa. Possible values are CP_ACP,

CP_MACCP,CP_OEMCP,CP_SYMBOL,CP_THREAD_ACP,CP_UTF7 and CP_UTF8.

352

com_addref

(4.1.0 - 4.3.2 only)

com_addref - Increases the components reference counter.

Description

void com_addref (void)

Increases the components reference counter.

353

com_get

(PHP 3>= 3.0.3, 4.0.5 - 4.3.2 only)

com_get - Gets the value of a COM Component's property

Description

mixed com_get (resource com_object, string property)

Returns the value of the property of the COM component referenced by com_object. Returns FALSE on error.

354

com_invoke

(PHP 3>= 3.0.3)

com_invoke - Calls a COM component's method.

Description

mixed com_invoke (resource com_object, string function_name [, mixed function parameters, ... ])

com_invoke() invokes a method of the COM component referenced by com_object. Returns FALSE on error, returns the

function_name's return value on success.

355

com_isenum

(4.1.0 - 4.3.2 only)

com_isenum - Grabs an IEnumVariant

Description

void com_isenum (object com_module)

Warning

This function is currently not documented; only the argument list is available.

356

com_load_typelib

(4.1.0 - 4.3.2 only)

com_load_typelib - Loads a Typelib

Description

void com_load_typelib (string typelib_name [, int case_insensitive])

Warning

This function is currently not documented; only the argument list is available.

357

com_load

(PHP 3>= 3.0.3)

com_load - Creates a new reference to a COM component

Description

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

com_load() creates a new COM component and returns a reference to it. Returns FALSE on failure. Possible values for

codepage are: CP_ACP,CP_MACCP,CP_OEMCP,CP_SYMBOL,CP_THREAD_ACP,CP_UTF7, and CP_UTF8.

358

com_propget

(PHP 3>= 3.0.3, 4.0.5 - 4.3.2 only)

com_propget - Alias of com_get()

Description

This function is an alias for com_get().

359

com_propput

(PHP 3>= 3.0.3, 4.0.5 - 4.3.2 only)

com_propput - Alias of com_set()

Description

This function is an alias for com_set().

360

com_propset

(PHP 3>= 3.0.3, 4.0.5 - 4.3.2 only)

com_propset - Alias of com_set()

Description

This function is an alias for com_set().

361

com_release

(4.1.0 - 4.3.2 only)

com_release - Decreases the components reference counter.

Description

void com_release (void)

Decreases the components reference counter.

362

com_set

(PHP 3>= 3.0.3, 4.0.5 - 4.3.2 only)

com_set - Assigns a value to a COM component's property

Description

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

Sets the value of the property of the COM component referenced by com_object. Returns the newly set value if succeeded,

FALSE on error.

363

Class/Object Functions

Table of Contents

call_user_method_array ......................................................................................................................368

call_user_method ...............................................................................................................................369

class_exists .......................................................................................................................................370

get_class_methods .............................................................................................................................371

get_class_vars ...................................................................................................................................372

get_class ..........................................................................................................................................373

get_declared_classes ...........................................................................................................................374

get_object_vars ..................................................................................................................................375

get_parent_class ................................................................................................................................377

is_a .................................................................................................................................................378

is_subclass_of ...................................................................................................................................379

method_exists ...................................................................................................................................380

364

Introduction

These functions allow you to obtain information about classes and instance objects. You can obtain the name of the class to

which a object belongs, as well as its member properties and methods. Using these functions, you can find out not only the

class membership of an object, but also its parentage (i.e. what class is the object class extending).

Requirements

No external libraries are needed to build this extension.

Installation

There is no installation needed to use these functions; they are part of the PHP core.

Runtime Configuration

This extension has no configuration directives defined in php.ini.

Resource Types

This extension has no resource types defined.

Predefined Constants

This extension has no constants defined.

Examples

In this example, we first define a base class and an extension of the class. The base class describes a general vegetable,

whether it is edible or not and what is its color. The subclass Spinach adds a method to cook it and another to find out if it

is cooked.

Example 184. classes.inc

<?php

// base class with member properties and methods

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;

}

365

} // end of class Vegetable

// extends the base class

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;

}

} // end of class Spinach

We then instantiate 2 objects from these classes and print out information about them, including their class parentage. We

also define some utility functions, mainly to have a nice printout of the variables.

Example 185. test_script.php

<pre>

<?php

include "classes.inc";

// utility functions

function print_vars($obj) {

$arr = get_object_vars($obj);

while (list($prop, $val) = each($arr))

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) {

global $$obj;

if (is_subclass_of($$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);

Class/Object Functions

366

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>

One important thing to note in the example above is that the object $leafy is an instance of the class Spinach which is a

subclass of Vegetable, therefore the last part of the script above will output:

[...]

Parentage:

Object leafy does not belong to a subclass of Spinach

Object leafy belongs to class spinach a subclass of Vegetable

Class/Object Functions

367

call_user_method_array

(PHP 4 >= 4.0.5)

call_user_method_array - Call a user method given with an array of parameters [deprecated]

Description

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

Warning

The call_user_method_array() function is deprecated as of PHP 4.1.0, use the call_user_func_array() variety

with the array(&$obj, "method_name") syntax instead.

Calls the method referred by method_name from the user defined obj object, using the parameters in paramarr.

See also: call_user_func_array(),call_user_func(),call_user_method().

Note: This function was added to the CVS code after release of PHP 4.0.4pl1

368

call_user_method

(PHP 3>= 3.0.3, PHP 4 )

call_user_method - Call a user method on an specific object [deprecated]

Description

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

Warning

The call_user_method() function is deprecated as of PHP 4.1.0, use the call_user_func() variety with the ar-

ray(&$obj, "method_name") syntax instead.

Calls the method referred by method_name from the user defined obj object. An example of usage is below, where we

define a class, instantiate an object and use call_user_method() to call indirectly its print_info method.

<?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");

See also call_user_func_array(),call_user_func(), and call_user_method_array().

369

class_exists

(PHP 4 )

class_exists - Checks if the class has been defined

Description

bool class_exists (string class_name)

This function returns TRUE if the class given by class_name has been defined, FALSE otherwise.

See Also

See also the PDFlib extension documentation.

ClibPDF functions

385

cpdf_add_annotation

(PHP 3>= 3.0.12, PHP 4 )

cpdf_add_annotation - Adds annotation

Description

void cpdf_add_annotation (int pdf_document, float llx, float lly, float urx, float ury, string title, string content [,

int mode])

The cpdf_add_annotation() adds a note with the lower left corner at (llx,lly) and the upper right corner at (urx,ury).

The optional parameter mode determines the unit length. If it's 0 or omitted the default unit as specified for the page is used.

Otherwise the coordinates are measured in postscript points disregarding the current unit.

386

cpdf_add_outline

(PHP 3>= 3.0.9, PHP 4 )

cpdf_add_outline - Adds bookmark for current page

Description

void cpdf_add_outline (int pdf_document, string text)

The cpdf_add_outline() function adds a bookmark with text text that points to the current page.

Example 191. Adding a page outline

<?php

$cpdf = cpdf_open(0);

cpdf_page_init($cpdf, 1, 0, 595, 842);

cpdf_add_outline($cpdf, 0, 0, 0, 1, "Page 1");

// ...

// some drawing

// ...

cpdf_finalize($cpdf);

Header("Content-type: application/pdf");

cpdf_output_buffer($cpdf);

cpdf_close($cpdf);

387

cpdf_arc

(PHP 3>= 3.0.8, PHP 4 )

cpdf_arc - Draws an arc

Description

void cpdf_arc (int pdf_document, float x-coor, float y-coor, float radius, float start, float end [, int mode])

The cpdf_arc() function draws an arc with center at point (x-coor,y-coor) and radius radius, starting at angle start and end-

ing at angle end.

The optional parameter mode determines the unit length. If it's 0 or omitted the default unit as specified for the page is used.

Otherwise the coordinates are measured in postscript points disregarding the current unit.

See Also

For related functions such as dirname(),is_dir(),mkdir(), and rmdir(), see the Filesystem section.

659

chdir

(PHP 3, PHP 4 )

chdir - Change directory

Description

bool chdir (string directory)

Changes PHP's current directory to directory. Returns TRUE on success or FALSE on failure..

See Also

For related functions, see also the Directory and Program Execution sections.

For a list and explanation of the various URL wrappers that can be used as remote files, see also Appendix I, List of Suppor-

ted Protocols/Wrappers.

Filesystem functions

851

basename

(PHP 3, PHP 4 )

basename - Returns filename component of path

Description

string basename (string path [, string suffix])

Given a string containing a path to a file, this function will return the base name of the file. If the filename ends in suffix this

will also be cut off.

On Windows, both slash (/) and backslash (\) are used as path separator character. In other environments, it is the forward

slash (/).

Example 285. basename() example

<?php

$path = "/home/httpd/html/index.php";

$file = basename ($path); // $file is set to "index.php"

$file = basename ($path,".php"); // $file is set to "index"

Note: The suffix parameter was added in PHP 4.1.0.

See Also

More mathmatical functions can be found in the sections BCMath Arbitrary Precision Mathematics Functions and Mathem-

atical Functions.

GMP functions

1035

gmp_abs

(PHP 4 >= 4.0.4)

gmp_abs - Absolute value

Description

resource gmp_abs (resource a)

Returns absolute value of a.

1036

gmp_add

(PHP 4 >= 4.0.4)

gmp_add - Add numbers

Description

resource gmp_add (resource a, resource b)

Add two GMP numbers. The result will be a GMP number representing the sum of the arguments.

1037

gmp_and

(PHP 4 >= 4.0.4)

gmp_and - Logical AND

Description

resource gmp_and (resource a, resource b)

Calculates logical AND of two GMP numbers.

1038

gmp_clrbit

(PHP 4 >= 4.0.4)

gmp_clrbit - Clear bit

Description

resource gmp_clrbit (resource &a, int index)

Clears (sets to 0) bit index in a.

1039

gmp_cmp

(PHP 4 >= 4.0.4)

gmp_cmp - Compare numbers

Description

int gmp_cmp (resource a, resource b)

Returns a positive value if a>b, zero if a=band negative value if a<b.

1040

gmp_com

(PHP 4 >= 4.0.4)

gmp_com - Calculates one's complement of a

Description

resource gmp_com (resource a)

Warning

This function is currently not documented; only the argument list is available.

1041

gmp_div_q

(PHP 4 >= 4.0.4)

gmp_div_q - Divide numbers

Description

resource gmp_div_q (resource a, resource b [, int round])

Divides aby band returns the integer result. The result rounding is defined by the round, which can have the following val-

ues:

•GMP_ROUND_ZERO: The result is truncated towards 0.

•GMP_ROUND_PLUSINF: The result is rounded towards +infinity.

•GMP_ROUND_MINUSINF: The result is rounded towards -infinity.

This function can also be called as gmp_div().

See Also

See also imageloadfont().

1238

imagecharup

(PHP 3, PHP 4 )

imagecharup - Draw a character vertically

Description

int imagecharup (resource image, int font, int x, int y, string c, int color)

imagecharup() draws the character cvertically in the image identified by image at coordinates x,y(top left is 0, 0) with the

color color.Iffont is 1, 2, 3, 4 or 5, a built-in font is used.

See also imageloadfont().

1239

imagecolorallocate

(PHP 3, PHP 4 )

imagecolorallocate - Allocate a color for an image

Description

int imagecolorallocate (resource image, int red, int green, int blue)

imagecolorallocate() returns a color identifier representing the color composed of the given RGB components. The im ar-

gument is the return from the imagecreate() function. red,green and blue are the values of the red, green and blue compon-

ent of the requested color respectively. These parameters are integers between 0 and 255. imagecolorallocate() must be

called to create each color that is to be used in the image represented by image.

$white = imagecolorallocate ($im, 255, 255, 255);

$black = imagecolorallocate ($im, 0, 0, 0);

Returns -1 if the allocation failed.

1240

imagecolorallocatealpha

(PHP 4 >= 4.3.2)

imagecolorallocatealpha - Allocate a color for an image

Description

int imagecolorallocatealpha (resource image, int red, int green, int blue, int alpha)

imagecolorallocatealpha() behaves identically to imagecolorallocate() with the addition of the transparency parameter al-

pha which may have a value between 0and 127.0indicates completely opaque while 127 indicates completely transparent.

Returns FALSE if the allocation failed.

1241

imagecolorat

(PHP 3, PHP 4 )

imagecolorat - Get the index of the color of a pixel

Description

int imagecolorat (resource image, int x, int y)

Returns the index of the color of the pixel at the specified location in the image specified by image.

If PHP is compiled against GD library 2.0 or higher and the image is a truecolor image, this function returns the RGB value

of that pixel as integer. Use bitshifting and masking to access the distinct red, green and blue component values:

Example 367. Access distinct RGB values

<?php

$im = ImageCreateFromPng("rockym.png");

$rgb = ImageColorAt($im, 100, 100);

$r = ($rgb >> 16) & 0xFF;

$g = ($rgb >> 8) & 0xFF;

$b = $rgb & 0xFF;

See also imagecolorset() and imagecolorsforindex().

1242

imagecolorclosest

(PHP 3, PHP 4 )

imagecolorclosest - Get the index of the closest color to the specified color

Description

int imagecolorclosest (resource image, int red, int green, int blue)

Returns the index of the color in the palette of the image which is "closest" to the specified RGB value.

The "distance" between the desired color and each color in the palette is calculated as if the RGB values represented points

in three-dimensional space.

See also imageloadfont().

1314

imagestringup

(PHP 3, PHP 4 )

imagestringup - Draw a string vertically

Description

int imagestringup (resource image, int font, int x, int y, string s, int col)

imagestringup() draws the string svertically in the image identified by image at coordinates x,y(top left is 0, 0) in color

col. If font is 1, 2, 3, 4 or 5, a built-in font is used.

See also imageloadfont().

1315

imagesx

(PHP 3, PHP 4 )

imagesx - Get image width

Description

int imagesx (resource image)

imagesx() returns the width of the image identified by image.

Example 374. Using imagesx()

<?php

// create a 300*200 image

$img = imagecreate(300, 200);

echo imagesx($img); // 300

See also imagecreate(),getimagesize() and imagesy().

1316

imagesy

(PHP 3, PHP 4 )

imagesy - Get image height

Description

int imagesy (resource image)

imagesy() returns the height of the image identified by image.

Example 375. Using imagesy()

<?php

// create a 300*200 image

$img = imagecreate(300, 200);

echo imagesy($img); // 200

See also imagecreate(),getimagesize() and imagesx().

1317

imagetruecolortopalette

(PHP 4 >= 4.0.6)

imagetruecolortopalette - Convert a true color image to a palette image

Description

void imagetruecolortopalette (resource image, bool dither, int ncolors)

imagetruecolortopalette() converts a truecolor image to a palette image. The code for this function was originally drawn

from the Independent JPEG Group library code, which is excellent. The code has been modified to preserve as much alpha

channel information as possible in the resulting palette, in addition to preserving colors as well as possible. This does not

work as well as might be hoped. It is usually best to simply produce a truecolor output image instead, which guarantees the

highest output quality.

dither indicates if the image should be dithered - if it is TRUE then dithering will be used which will result in a more

speckled image but with better color approximation.

ncolors sets the maximum number of colors that should be retained in the palette.

Note: This function was added in PHP 4.0.6 and requires GD 2.0.1 or later

1318

imagettfbbox

(PHP 3>= 3.0.1, PHP 4 )

imagettfbbox - Give the bounding box of a text using TrueType fonts

Description

array imagettfbbox (int size, int angle, string fontfile, string text)

This function calculates and returns the bounding box in pixels for a TrueType text.

text The string to be measured.

size The font size in pixels.

fontfile

The name of the TrueType font file. (Can also be an URL.) Depending on which version of the GD library that PHP is

using, it may attempt to search for files that do not begin with a leading '/' by appending '.ttf' to the filename and search-

ing along a library-defined font path.

angle

Angle in degrees in which text will be measured.

imagettfbbox() returns an array with 8 elements representing four points making the bounding box of the text:

0 lower left corner, X position

1 lower left corner, Y position

2 lower right corner, X position

3 lower right corner, Y position

4 upper right corner, X position

5 upper right corner, Y position

6 upper left corner, X position

7 upper left corner, Y position

The points are relative to the text regardless of the angle, so "upper left" means in the top left-hand corner seeing the text ho-

rizontallty.

This function requires both the GD library and the FreeType library.

See Also

This document can't go into detail on all the topics touched by the provided functions. Further information is provided by

the documentation of the c-client library source (docs/internal.txt). and the following RFC documents:

• RFC2821 [http://www.faqs.org/rfcs/rfc2821]: Simple Mail Transfer Protocol (SMTP).

• RFC2822 [http://www.faqs.org/rfcs/rfc2822]: Standard for ARPA internet text messages.

IMAP, POP3 and NNTP functions

1332

• RFC2060 [http://www.faqs.org/rfcs/rfc2060]: Internet Message Access Protocol (IMAP) Version 4rev1.

• RFC1939 [http://www.faqs.org/rfcs/rfc1939]: Post Office Protocol Version 3 (POP3).

• RFC977 [http://www.faqs.org/rfcs/rfc977]: Network News Transfer Protocol (NNTP).

• RFC2076 [http://www.faqs.org/rfcs/rfc2076]: Common Internet Message Headers.

• RFC2045 [http:/ / www.faqs.org/ rfcs/ rfc2045] , RFC2046 [http:/ / www.faqs.org/ rfcs/ rfc2046] , RFC2047 [http:/ /

www.faqs.org/ rfcs/ rfc2047] , RFC2048 [http:/ / www.faqs.org/ rfcs/ rfc2048] & RFC2049 [http:/ / www.faqs.org/ rfcs/

rfc2049]: Multipurpose Internet Mail Extensions (MIME).

A detailed overview is also available in the books Programming Internet Email [http://www.oreilly.com/catalog/progintem-

ail/noframes.html] by David Wood and Managing IMAP [http://www.oreilly.com/catalog/mimap/noframes.html] by Dianna

Mullet & Kevin Mullet.

IMAP, POP3 and NNTP functions

1333

imap_8bit

(PHP 3, PHP 4 )

imap_8bit - Convert an 8bit string to a quoted-printable string

Description

string imap_8bit (string string)

Convert an 8bit string to a quoted-printable string (according to RFC2045 [http://www.faqs.org/rfcs/rfc2045], section 6.7).

Returns a quoted-printable string.

See Also

Additional documentation about MCVE's PHP API can be found at http://www.mcve.com/docs/phpapi.pdf. Main Street's

documentation is complete and should be the primary reference for functions.

1802

mcve_adduser

(PHP 4 >= 4.2.0)

mcve_adduser - Add an MCVE user using usersetup structure

Description

int mcve_adduser (resource conn, string admin_password, int usersetup)

Warning

This function is currently not documented; only the argument list is available.

1803

mcve_adduserarg

(PHP 4 >= 4.2.0)

mcve_adduserarg - Add a value to user configuration structure

Description

int mcve_adduserarg (resource usersetup, int argtype, string argval)

Warning

This function is currently not documented; only the argument list is available.

1804

mcve_bt

(PHP 4 >= 4.2.0)

mcve_bt - Get unsettled batch totals

Description

int mcve_bt (resource conn, string username, string password)

Warning

This function is currently not documented; only the argument list is available.

1805

mcve_checkstatus

(PHP 4 >= 4.2.0)

mcve_checkstatus - Check to see if a transaction has completed

Description

int mcve_checkstatus (resource conn, int identifier)

Warning

This function is currently not documented; only the argument list is available.

1806

mcve_chkpwd

(PHP 4 >= 4.2.0)

mcve_chkpwd - Verify Password

Description

int mcve_chkpwd (resource conn, string username, string password)

Warning

This function is currently not documented; only the argument list is available.

1807

mcve_chngpwd

(PHP 4 >= 4.2.0)

mcve_chngpwd - Change the system administrator's password

Description

int mcve_chngpwd (resource conn, string admin_password, string new_password)

Warning

This function is currently not documented; only the argument list is available.

1808

mcve_completeauthorizations

(PHP 4 >= 4.2.0)

mcve_completeauthorizations - Number of complete authorizations in queue, returning an array of their

identifiers

Description

int mcve_completeauthorizations (resource conn, int &array)

Warning

This function is currently not documented; only the argument list is available.

1809

mcve_connect

(PHP 4 >= 4.2.0)

mcve_connect - Establish the connection to MCVE

Description

int mcve_connect (resource conn)

Warning

This function is currently not documented; only the argument list is available.

1810

mcve_connectionerror

(PHP 4 >= 4.3.0)

mcve_connectionerror - Get a textual representation of why a connection failed

Description

string mcve_connectionerror (resource conn)

Warning

This function is currently not documented; only the argument list is available.

1811

mcve_deleteresponse

(PHP 4 >= 4.2.0)

mcve_deleteresponse - Delete specified transaction from MCVE_CONN structure

Description

bool mcve_deleteresponse (resource conn, int identifier)

Warning

This function is currently not documented; only the argument list is available.

1812

mcve_deletetrans

(PHP 4 >= 4.3.0)

mcve_deletetrans - Delete specified transaction from MCVE_CONN structure

Description

bool mcve_deletetrans (resource conn, int identifier)

Warning

This function is currently not documented; only the argument list is available.

1813

mcve_deleteusersetup

(PHP 4 >= 4.2.0)

mcve_deleteusersetup - Deallocate data associated with usersetup structure

Description

void mcve_deleteusersetup (resource usersetup)

Warning

This function is currently not documented; only the argument list is available.

1814

mcve_deluser

(PHP 4 >= 4.2.0)

mcve_deluser - Delete an MCVE user account

Description

int mcve_deluser (resource conn, string admin_password, string username)

Warning

This function is currently not documented; only the argument list is available.

1815

mcve_destroyconn

(PHP 4 >= 4.2.0)

mcve_destroyconn - Destroy the connection and MCVE_CONN structure

Description

void mcve_destroyconn (resource conn)

Warning

This function is currently not documented; only the argument list is available.

1816

mcve_destroyengine

(PHP 4 >= 4.2.0)

mcve_destroyengine - Free memory associated with IP/SSL connectivity

Description

void mcve_destroyengine (void)

Warning

This function is currently not documented; only the argument list is available.

1817

mcve_disableuser

(PHP 4 >= 4.2.0)

mcve_disableuser - Disable an active MCVE user account

Description

int mcve_disableuser (resource conn, string admin_password, string username)

Warning

This function is currently not documented; only the argument list is available.

1818

mcve_edituser

(PHP 4 >= 4.2.0)

mcve_edituser - Edit MCVE user using usersetup structure

Description

int mcve_edituser (resource conn, string admin_password, int usersetup)

Warning

This function is currently not documented; only the argument list is available.

1819

mcve_enableuser

(PHP 4 >= 4.2.0)

mcve_enableuser - Enable an inactive MCVE user account

Description

int mcve_enableuser (resource conn, string admin_password, string username)

Warning

This function is currently not documented; only the argument list is available.

1820

mcve_force

(PHP 4 >= 4.2.0)

mcve_force - Send a FORCE to MCVE. (typically, a phone-authorization)

Description

int mcve_force (resiurce conn, string username, string password, string trackdata, string account, string expdate,

float amount, string authcode, string comments, string clerkid, string stationid, int ptrannum)

Warning

This function is currently not documented; only the argument list is available.

1821

mcve_getcell

(PHP 4 >= 4.2.0)

mcve_getcell - Get a specific cell from a comma delimited response by column name

Description

string mcve_getcell (resource conn, int identifier, string column, int row)

Warning

This function is currently not documented; only the argument list is available.

1822

mcve_getcellbynum

(PHP 4 >= 4.2.0)

mcve_getcellbynum - Get a specific cell from a comma delimited response by column number

Description

string mcve_getcellbynum (resource conn, int identifier, int column, int row)

Warning

This function is currently not documented; only the argument list is available.

1823

mcve_getcommadelimited

(PHP 4 >= 4.2.0)

mcve_getcommadelimited - Get the RAW comma delimited data returned from MCVE

Description

string mcve_getcommadelimited (resource conn, int identifier)

Warning

This function is currently not documented; only the argument list is available.

1824

mcve_getheader

(PHP 4 >= 4.2.0)

mcve_getheader - Get the name of the column in a comma-delimited response

Description

string mcve_getheader (resource conn, int identifier, int column_num)

Warning

This function is currently not documented; only the argument list is available.

1825

mcve_getuserarg

(PHP 4 >= 4.2.0)

mcve_getuserarg - Grab a value from usersetup structure

Description

string mcve_getuserarg (resource usersetup, int argtype)

Warning

This function is currently not documented; only the argument list is available.

1826

mcve_getuserparam

(PHP 4 >= 4.3.0)

mcve_getuserparam - Get a user response parameter

Description

string mcve_getuserparam (resource conn, long identifier, int key)

Warning

This function is currently not documented; only the argument list is available.

1827

mcve_gft

(PHP 4 >= 4.2.0)

mcve_gft - Audit MCVE for Failed transactions

Description

int mcve_gft (resource conn, string username, string password, int type, string account, string clerkid, string sta-

tionid, string comments, int ptrannum, string startdate, string enddate)

Warning

This function is currently not documented; only the argument list is available.

1828

mcve_gl

(PHP 4 >= 4.2.0)

mcve_gl - Audit MCVE for settled transactions

Description

int mcve_gl (int conn, string username, string password, int type, string account, string batch, string clerkid,

string stationid, string comments, int ptrannum, string startdate, string enddate)

Warning

This function is currently not documented; only the argument list is available.

1829

mcve_gut

(PHP 4 >= 4.2.0)

mcve_gut - Audit MCVE for Unsettled Transactions

Description

int mcve_gut (resource conn, string username, string password, int type, string account, string clerkid, string sta-

tionid, string comments, int ptrannum, string startdate, string enddate)

Warning

This function is currently not documented; only the argument list is available.

1830

mcve_initconn

(PHP 4 >= 4.2.0)

mcve_initconn - Create and initialize an MCVE_CONN structure

Description

resource mcve_initconn (void)

Warning

This function is currently not documented; only the argument list is available.

1831

mcve_initengine

(PHP 4 >= 4.2.0)

mcve_initengine - Ready the client for IP/SSL Communication

Description

int mcve_initengine (string location)

Warning

This function is currently not documented; only the argument list is available.

1832

mcve_initusersetup

(PHP 4 >= 4.2.0)

mcve_initusersetup - Initialize structure to store user data

Description

resource mcve_initusersetup (void)

Warning

This function is currently not documented; only the argument list is available.

1833

mcve_iscommadelimited

(PHP 4 >= 4.2.0)

mcve_iscommadelimited - Checks to see if response is comma delimited

Description

int mcve_iscommadelimited (resource conn, int identifier)

Warning

This function is currently not documented; only the argument list is available.

1834

mcve_liststats

(PHP 4 >= 4.2.0)

mcve_liststats - List statistics for all users on MCVE system

Description

int mcve_liststats (resource conn, string admin_password)

Warning

This function is currently not documented; only the argument list is available.

1835

mcve_listusers

(PHP 4 >= 4.2.0)

mcve_listusers - List all users on MCVE system

Description

int mcve_listusers (resource conn, string admin_password)

Warning

This function is currently not documented; only the argument list is available.

1836

mcve_maxconntimeout

(PHP 4 >= 4.3.0)

mcve_maxconntimeout - The maximum amount of time the API will attempt a connection to MCVE

Description

bool mcve_maxconntimeout (resource conn, int secs)

Warning

This function is currently not documented; only the argument list is available.

1837

mcve_monitor

(PHP 4 >= 4.2.0)

mcve_monitor - Perform communication with MCVE (send/receive data) Non-blocking

Description

int mcve_monitor (resource conn)

Warning

This function is currently not documented; only the argument list is available.

1838

mcve_numcolumns

(PHP 4 >= 4.2.0)

mcve_numcolumns - Number of columns returned in a comma delimited response

Description

int mcve_numcolumns (resource conn, int identifier)

Warning

This function is currently not documented; only the argument list is available.

1839

mcve_numrows

(PHP 4 >= 4.2.0)

mcve_numrows - Number of rows returned in a comma delimited response

Description

int mcve_numrows (resource conn, int identifier)

Warning

This function is currently not documented; only the argument list is available.

1840

mcve_override

(PHP 4 >= 4.2.0)

mcve_override - Send an OVERRIDE to MCVE

Description

int mcve_override (resource conn, string username, string password, string trackdata, string account, string exp-

date, float amount, string street, string zip, string cv, string comments, string clerkid, string stationid, int ptran-

num)

Warning

This function is currently not documented; only the argument list is available.

1841

mcve_parsecommadelimited

(PHP 4 >= 4.2.0)

mcve_parsecommadelimited - Parse the comma delimited response so mcve_getcell, etc will work

Description

int mcve_parsecommadelimited (resource conn, int identifier)

Warning

This function is currently not documented; only the argument list is available.

1842

mcve_ping

(PHP 4 >= 4.3.0)

mcve_ping - Send a ping request to MCVE

Description

int mcve_ping (resource conn)

Warning

This function is currently not documented; only the argument list is available.

1843

mcve_preauth

(PHP 4 >= 4.2.0)

mcve_preauth - Send a PREAUTHORIZATION to MCVE

Description

int mcve_preauth (resource conn, string username, string password, string trackdata, string account, string exp-

date, float amount, string street, string zip, string cv, string comments, string clerkid, string stationid, int ptran-

num)

Warning

This function is currently not documented; only the argument list is available.

1844

mcve_preauthcompletion

(PHP 4 >= 4.2.0)

mcve_preauthcompletion - Complete a PREAUTHORIZATION... Ready it for settlement

Description

int mcve_preauthcompletion (resource conn, string username, string password, float finalamount, int sid, int

ptrannum)

Warning

This function is currently not documented; only the argument list is available.

1845

mcve_qc

(PHP 4 >= 4.2.0)

mcve_qc - Audit MCVE for a list of transactions in the outgoing queue

Description

int mcve_qc (resource conn, string username, string password, string clerkid, string stationid, string comments,

int ptrannum)

Warning

This function is currently not documented; only the argument list is available.

1846

mcve_responseparam

(PHP 4 >= 4.3.0)

mcve_responseparam - Get a custom response parameter

Description

string mcve_responseparam (resource conn, long identifier, string key)

Warning

This function is currently not documented; only the argument list is available.

1847

mcve_return

(PHP 4 >= 4.2.0)

mcve_return - Issue a RETURN or CREDIT to MCVE

Description

int mcve_return (int conn, string username, string password, string trackdata, string account, string expdate,

float amount, string comments, string clerkid, string stationid, int ptrannum)

Warning

This function is currently not documented; only the argument list is available.

1848

mcve_returncode

(PHP 4 >= 4.2.0)

mcve_returncode - Grab the exact return code from the transaction

Description

int mcve_returncode (resource conn, int identifier)

Warning

This function is currently not documented; only the argument list is available.

1849

mcve_returnstatus

(PHP 4 >= 4.2.0)

mcve_returnstatus - Check to see if the transaction was successful

Description

int mcve_returnstatus (resource conn, int identifier)

Warning

This function is currently not documented; only the argument list is available.

1850

mcve_sale

(PHP 4 >= 4.2.0)

mcve_sale - Send a SALE to MCVE

Description

int mcve_sale (resource conn, string username, string password, string trackdata, string account, string expdate,

float amount, string street, string zip, string cv, string comments, string clerkid, string stationid, int ptrannum)

Warning

This function is currently not documented; only the argument list is available.

1851

mcve_setblocking

(PHP 4 >= 4.3.0)

mcve_setblocking - Set blocking/non-blocking mode for connection

Description

int mcve_setblocking (resource conn, int tf)

Warning

This function is currently not documented; only the argument list is available.

1852

mcve_setdropfile

(PHP 4 >= 4.2.0)

mcve_setdropfile - Set the connection method to Drop-File

Description

int mcve_setdropfile (resource conn, string directory)

Warning

This function is currently not documented; only the argument list is available.

1853

mcve_setip

(PHP 4 >= 4.2.0)

mcve_setip - Set the connection method to IP

Description

int mcve_setip (resource conn, string host, int port)

Warning

This function is currently not documented; only the argument list is available.

1854

mcve_setssl

(PHP 4 >= 4.2.0)

mcve_setssl - Set the connection method to SSL

Description

int mcve_setssl (resource conn, string host, int port)

Warning

This function is currently not documented; only the argument list is available.

1855

mcve_settimeout

(PHP 4 >= 4.2.0)

mcve_settimeout - Set maximum transaction time (per trans)

Description

int mcve_settimeout (resource conn, int seconds)

Warning

This function is currently not documented; only the argument list is available.

1856

mcve_settle

(PHP 4 >= 4.2.0)

mcve_settle - Issue a settlement command to do a batch deposit

Description

int mcve_settle (resource conn, string username, string password, string batch)

Warning

This function is currently not documented; only the argument list is available.

1857

mcve_text_avs

(PHP 4 >= 4.3.0)

mcve_text_avs - Get a textual representation of the return_avs

Description

string mcve_text_avs (string code)

Warning

This function is currently not documented; only the argument list is available.

1858

mcve_text_code

(PHP 4 >= 4.3.0)

mcve_text_code - Get a textual representation of the return_code

Description

string mcve_text_code (string code)

Warning

This function is currently not documented; only the argument list is available.

1859

mcve_text_cv

(PHP 4 >= 4.3.0)

mcve_text_cv - Get a textual representation of the return_cv

Description

string mcve_text_cv (int code)

Warning

This function is currently not documented; only the argument list is available.

1860

mcve_transactionauth

(PHP 4 >= 4.2.0)

mcve_transactionauth - Get the authorization number returned for the transaction (alpha-numeric)

Description

string mcve_transactionauth (resource conn, int identifier)

Warning

This function is currently not documented; only the argument list is available.

1861

mcve_transactionavs

(PHP 4 >= 4.2.0)

mcve_transactionavs - Get the Address Verification return status

Description

int mcve_transactionavs (resource conn, int identifier)

Warning

This function is currently not documented; only the argument list is available.

1862

mcve_transactionbatch

(PHP 4 >= 4.2.0)

mcve_transactionbatch - Get the batch number associated with the transaction

Description

int mcve_transactionbatch (resource conn, int identifier)

Warning

This function is currently not documented; only the argument list is available.

1863

mcve_transactioncv

(PHP 4 >= 4.2.0)

mcve_transactioncv - Get the CVC2/CVV2/CID return status

Description

int mcve_transactioncv (resource conn, int identifier)

Warning

This function is currently not documented; only the argument list is available.

1864

mcve_transactionid

(PHP 4 >= 4.2.0)

mcve_transactionid - Get the unique system id for the transaction

Description

int mcve_transactionid (resource conn, int identifier)

Warning

This function is currently not documented; only the argument list is available.

1865

mcve_transactionitem

(PHP 4 >= 4.2.0)

mcve_transactionitem - Get the ITEM number in the associated batch for this transaction

Description

int mcve_transactionitem (resource conn, int identifier)

Warning

This function is currently not documented; only the argument list is available.

1866

mcve_transactionssent

(PHP 4 >= 4.2.0)

mcve_transactionssent - Check to see if outgoing buffer is clear

Description

int mcve_transactionssent (resource conn)

Warning

This function is currently not documented; only the argument list is available.

1867

mcve_transactiontext

(PHP 4 >= 4.2.0)

mcve_transactiontext - Get verbiage (text) return from MCVE or processing institution

Description

string mcve_transactiontext (resource conn, int identifier)

Warning

This function is currently not documented; only the argument list is available.

1868

mcve_transinqueue

(PHP 4 >= 4.2.0)

mcve_transinqueue - Number of transactions in client-queue

Description

int mcve_transinqueue (resource conn)

Warning

This function is currently not documented; only the argument list is available.

1869

mcve_transnew

(PHP 4 >= 4.3.0)

mcve_transnew - Start a new transaction

Description

int mcve_transnew (resource conn)

Warning

This function is currently not documented; only the argument list is available.

1870

mcve_transparam

(PHP 4 >= 4.3.0)

mcve_transparam - Add a parameter to a transaction

Description

int mcve_transparam (resource conn, long identifier, int key)

Warning

This function is currently not documented; only the argument list is available.

1871

mcve_transsend

(PHP 4 >= 4.3.0)

mcve_transsend - Finalize and send the transaction

Description

int mcve_transsend (resource conn, long identifier)

Warning

This function is currently not documented; only the argument list is available.

1872

mcve_ub

(PHP 4 >= 4.2.0)

mcve_ub - Get a list of all Unsettled batches

Description

int mcve_ub (resource conn, string username, string password)

Warning

This function is currently not documented; only the argument list is available.

1873

mcve_uwait

(PHP 4 >= 4.3.0)

mcve_uwait - Wait x microsecs

Description

int mcve_uwait (long microsecs)

Warning

This function is currently not documented; only the argument list is available.

1874

mcve_verifyconnection

(PHP 4 >= 4.3.0)

mcve_verifyconnection - Set whether or not to PING upon connect to verify connection

Description

bool mcve_verifyconnection (resource conn, int tf)

Warning

This function is currently not documented; only the argument list is available.

1875

mcve_verifysslcert

(PHP 4 >= 4.3.0)

mcve_verifysslcert - Set whether or not to verify the server ssl certificate

Description

bool mcve_verifysslcert (resource conn, int tf)

Warning

This function is currently not documented; only the argument list is available.

1876

mcve_void

(PHP 4 >= 4.2.0)

mcve_void - VOID a transaction in the settlement queue

Description

int mcve_void (resource conn, string username, string password, int sid, int ptrannum)

Warning

This function is currently not documented; only the argument list is available.

1877

Mhash Functions

Table of Contents

mhash_count ................................................................................................................................... 1881

mhash_get_block_size ...................................................................................................................... 1882

mhash_get_hash_name ...................................................................................................................... 1883

mhash_keygen_s2k .......................................................................................................................... 1884

mhash ............................................................................................................................................ 1885

1878

Introduction

These functions are intended to work with mhash [http://mhash.sourceforge.net/]. Mhash can be used to create checksums,

message digests, message authentication codes, and more.

This is an interface to the mhash library. mhash supports a wide variety of hash algorithms such as MD5, SHA1, GOST, and

many others. For a complete list of supported hashes, refer to the documentation of mhash. The general rule is that you can

access the hash algorithm from PHP with MHASH_HASHNAME. For example, to access TIGER you use the PHP constant

MHASH_TIGER.

Requirements

To use it, download the mhash distribution from its web site [http://mhash.sourceforge.net/] and follow the included install-

ation instructions.

Installation

You need to compile PHP with the --with-mhash[=DIR] parameter to enable this extension. DIR is the mhash install dir-

ectory.

Runtime Configuration

This extension has no configuration directives defined in php.ini.

Resource Types

This extension has no resource types defined.

Predefined Constants

The constants below are defined by this extension, and will only be available when the extension has either been compiled

into PHP or dynamically loaded at runtime.

Here is a list of hashes which are currently supported by mhash. If a hash is not listed here, but is listed by mhash as suppor-

ted, you can safely assume that this documentation is outdated.

•MHASH_MD5

•MHASH_SHA1

•MHASH_HAVAL256

•MHASH_HAVAL192

•MHASH_HAVAL160

•MHASH_HAVAL128

•MHASH_RIPEMD160

•MHASH_GOST

1879

•MHASH_TIGER

•MHASH_CRC32

•MHASH_CRC32B

Examples

Example 486. Compute the MD5 digest and hmac and print it out as hex

<?php

$input = "what do ya want for nothing?";

$hash = mhash (MHASH_MD5, $input);

print "The hash is ".bin2hex ($hash)."<br />\n";

$hash = mhash (MHASH_MD5, $input, "Jefe");

print "The hmac is ".bin2hex ($hash)."<br />\n";

This will produce:

The hash is d03cb659cbf9192dcd066272249f8412

The hmac is 750c783e6ab0b503eaa86e310a5db738

Mhash Functions

1880

mhash_count

(PHP 3>= 3.0.9, PHP 4 )

mhash_count - Get the highest available hash id

Description

int mhash_count (void)

mhash_count() returns the highest available hash id. Hashes are numbered from 0 to this hash id.

Example 487. Traversing all hashes

<?php

$nr = mhash_count();

for ($i = 0; $i <= $nr; $i++) {

echo sprintf ("The blocksize of %s is %d\n",

mhash_get_hash_name ($i),

mhash_get_block_size ($i));

}

1881

mhash_get_block_size

(PHP 3>= 3.0.9, PHP 4 )

mhash_get_block_size - Get the block size of the specified hash

Description

int mhash_get_block_size (int hash)

mhash_get_block_size() is used to get the size of a block of the specified hash.

mhash_get_block_size() takes one argument, the hash and returns the size in bytes or FALSE, if the hash does not exist.

1882

mhash_get_hash_name

(PHP 3>= 3.0.9, PHP 4 )

mhash_get_hash_name - Get the name of the specified hash

Description

string mhash_get_hash_name (int hash)

mhash_get_hash_name() is used to get the name of the specified hash.

mhash_get_hash_name() takes the hash id as an argument and returns the name of the hash or FALSE, if the hash does not

exist.

Example 488. mhash_get_hash_name() example

<?php

$hash = MHASH_MD5;

print mhash_get_hash_name ($hash);

The above example will print out:

MD5

1883

mhash_keygen_s2k

(PHP 4 >= 4.0.4)

mhash_keygen_s2k - Generates a key

Description

string mhash_keygen_s2k (int hash, string password, string salt, int bytes)

mhash_keygen_s2k() generates a key that is bytes long, from a user given password. This is the Salted S2K algorithm as

specified in the OpenPGP document (RFC 2440). That algorithm will use the specified hash algorithm to create the key.

The salt must be different and random enough for every key you generate in order to create different keys. That salt must be

known when you check the keys, thus it is a good idea to append the key to it. Salt has a fixed length of 8 bytes and will be

padded with zeros if you supply less bytes.

Keep in mind that user supplied passwords are not really suitable to be used as keys in cryptographic algorithms, since users

normally choose keys they can write on keyboard. These passwords use only 6 to 7 bits per character (or less). It is highly

recommended to use some kind of tranformation (like this function) to the user supplied key.

1884

mhash

(PHP 3>= 3.0.9, PHP 4 )

mhash - Compute hash

Description

string mhash (int hash, string data [, string key])

mhash() applies a hash function specified by hash to the data and returns the resulting hash (also called digest). If the key is

specified it will return the resulting HMAC. HMAC is keyed hashing for message authentication, or simply a message di-

gest that depends on the specified key. Not all algorithms supported in mhash can be used in HMAC mode. In case of an er-

ror returns FALSE.

1885

Mimetype Functions

Table of Contents

mime_content_type .......................................................................................................................... 1888

1886

Introduction

The functions in this module try to guess the content type and encoding of a file by looking for certain magic byte sequences

at specific positions within the file. While this is not a bullet proof approach the heuristics used do a very good job.

This extension is derivated from Apache mod_mime_magic, which is itself based on the file command maintaind by Ian

F. Darwin. See the source code for further historic and copyright information.

Requirements

No external libraries are needed to build this extension.

Installation

You must compile PHP with the configure switch --with-mime-magic to get support for mime-type functions. The exten-

sion needs a copy of the simplified magic file that is distributed with the Apache httpd.

Note: The configure option has been changed from --enable-mime-magic to --with-mime-magic since PHP

4.3.2

Note: This extension is not capable of handling the fully decorated magic file that generally comes with standard

Linux distro's and is supposed to be used with recent versions of file command.

Runtime Configuration

The behaviour of these functions is affected by settings in php.ini.

Table 88. Mimetype configuration options

Name Default Changeable

mime_magic.magicfile "/usr/share/misc/magic.mime" PHP_INI_SYSTEM

For further details and definition of the PHP_INI_* constants see ini_set().

Resource Types

This extension has no resource types defined.

Predefined Constants

This extension has no constants defined.

1887

mime_content_type

(PHP 4 >= 4.3.0)

mime_content_type - Detect MIME Content-type for a file

Description

string mime_content_type (string filename)

Returns the MIME content type for a file as determined by using information from the magic.mime file. Content types are

returned in MIME format, like text/plain or application/octet-stream.

1888

Microsoft SQL Server functions

Table of Contents

mssql_bind ..................................................................................................................................... 1892

mssql_close .................................................................................................................................... 1893

mssql_connect ................................................................................................................................. 1894

mssql_data_seek .............................................................................................................................. 1895

mssql_execute ................................................................................................................................. 1896

mssql_fetch_array ............................................................................................................................ 1897

mssql_fetch_assoc ............................................................................................................................ 1898

mssql_fetch_batch ............................................................................................................................ 1899

mssql_fetch_field ............................................................................................................................. 1900

mssql_fetch_object ........................................................................................................................... 1901

mssql_fetch_row .............................................................................................................................. 1902

mssql_field_length ........................................................................................................................... 1903

mssql_field_name ............................................................................................................................ 1904

mssql_field_seek .............................................................................................................................. 1905

mssql_field_type .............................................................................................................................. 1906

mssql_free_result ............................................................................................................................. 1907

mssql_free_statement ........................................................................................................................ 1908

mssql_get_last_message .................................................................................................................... 1909

mssql_guid_string ............................................................................................................................ 1910

mssql_init ....................................................................................................................................... 1911

mssql_min_error_severity .................................................................................................................. 1912

mssql_min_message_severity ............................................................................................................. 1913

mssql_next_result ............................................................................................................................ 1914

mssql_num_fields ............................................................................................................................ 1915

mssql_num_rows ............................................................................................................................. 1916

mssql_pconnect ............................................................................................................................... 1917

mssql_query .................................................................................................................................... 1918

mssql_result .................................................................................................................................... 1919

mssql_rows_affected ........................................................................................................................ 1920

mssql_select_db ............................................................................................................................... 1921

1889

Introduction

These functions allow you to access MS SQL Server database.

Requirements

Requirements for WIn32 platforms.

The extension requires the MS SQL Client Tools to be installed on the system where PHP is installed. The Client Tools can

be installed from the MS SQL Server CD or by copying ntwdblib.dll from \winnt\system32 on the server to

\winnt\system32 on the PHP box. Copying ntwdblib.dll will only provide access. Configuration of the client will re-

quire installation of all the tools.

Requirements for Unix/Linux platforms.

To use the MSSQL extension on Unix/Linux, you first need to build and install the FreeTDS library. Source code and in-

stallation instructions are available at the FreeTDS home page: http://www.freetds.org/

Installation

The MSSQL extension is enabled by adding extension=php_mssql.dll to php.ini.

To get these functions to work, you have to compile PHP with --with-mssql[=DIR], where DIR is the FreeTDS install

prefix. And FreeTDS should be compiled using --enable-msdblib.

Runtime Configuration

The behaviour of these functions is affected by settings in php.ini.

Table 89. MS SQL Server configuration options

Name Default Changeable

mssql.allow_persistent "1" PHP_INI_SYSTEM

mssql.max_persistent "-1" PHP_INI_SYSTEM

mssql.max_links "-1" PHP_INI_SYSTEM

mssql.min_error_severity "10" PHP_INI_ALL

mssql.min_message_severity "10" PHP_INI_ALL

mssql.compatability_mode "0" PHP_INI_ALL

mssql.connect_timeout "5" PHP_INI_ALL

mssql.timeout "60" PHP_INI_ALL

mssql.textsize "-1" PHP_INI_ALL

mssql.textlimit "-1" PHP_INI_ALL

mssql.batchsize "0" PHP_INI_ALL

mssql.datetimeconvert "1" PHP_INI_ALL

mssql.secure_connection "0" PHP_INI_SYSTEM

mssql.max_procs "25" PHP_INI_ALL

For further details and definition of the PHP_INI_* constants see ini_set().

1890

Resource Types

Predefined Constants

The constants below are defined by this extension, and will only be available when the extension has either been compiled

into PHP or dynamically loaded at runtime.

MSSQL_ASSOC (integer)

MSSQL_NUM (integer)

MSSQL_BOTH (integer)

SQLTEXT (integer)

SQLVARCHAR (integer)

SQLCHAR (integer)

SQLINT1 (integer)

SQLINT2 (integer)

SQLINT4 (integer)

SQLBIT (integer)

SQLFLT8 (integer)

Microsoft SQL Server functions

1891

mssql_bind

(PHP 4 >= 4.1.0)

mssql_bind - Adds a parameter to a stored procedure or a remote stored procedure

Description

int mssql_bind (int stmt, string param_name, mixed var, int type [, int is_output [, int is_null [, int maxlen]]])

Warning

This function is currently not documented; only the argument list is available.

See also mssql_execute(),mssql_free_statement(), and mssql_init()

1892

mssql_close

(PHP 3, PHP 4 )

mssql_close - Close MS SQL Server connection

Description

int mssql_close ([int link_identifier])

mssql_close() closes the link to a MS SQL Server database that's associated with the specified link identifier. If the link

identifier isn't specified, the last opened link is assumed.

Returns TRUE on success or FALSE on failure.

Note that this isn't usually necessary, as non-persistent open links are automatically closed at the end of the script's execu-

tion.

mssql_close() will not close persistent links generated by mssql_pconnect().

See also mssql_connect(), and mssql_pconnect().

1893

mssql_connect

(PHP 3, PHP 4 )

mssql_connect - Open MS SQL server connection

Description

int mssql_connect ([string servername [, string username [, string password]]])

Returns: A positive MS SQL link identifier on success, or FALSE on error.

mssql_connect() establishes a connection to a MS SQL server. The servername argument has to be a valid servername that

is defined in the 'interfaces' file.

In case a second call is made to mssql_connect() with the same arguments, no new link will be established, but instead, the

link identifier of the already opened link will be returned.

The link to the server will be closed as soon as the execution of the script ends, unless it's closed earlier by explicitly calling

mssql_close().

See also mssql_pconnect(),mssql_close().

1894

mssql_data_seek

(PHP 3, PHP 4 )

mssql_data_seek - Move internal row pointer

Description

int mssql_data_seek (int result_identifier, int row_number)

Returns: TRUE on success, FALSE on failure.

mssql_data_seek() moves the internal row pointer of the MS SQL result associated with the specified result identifier to

point to the specified row number. The next call to mssql_fetch_row() would return that row.

See Also

Note: An alternative PHP module for PDF document creation based on FastIO's [http://www.fastio.com/] ClibPDF

is available. Please see the ClibPDF section for details. Note that ClibPDF has a slightly different API than PDFlib.

PDF functions

2727

pdf_add_annotation

(PHP 3>= 3.0.12, PHP 4 )

pdf_add_annotation - Deprecated: Adds annotation

Description

pdf_add_outline() is replaced by pdf_add_note()

See Also

The section about Process Control Functions maybe of interest for you.

2909

posix_ctermid

(PHP 3>= 3.0.13, PHP 4 )

posix_ctermid - Get path name of controlling terminal

Description

string posix_ctermid (void)

Warning

This function is currently not documented; only the argument list is available.

2910

posix_get_last_error

(PHP 4 >= 4.2.0)

posix_get_last_error - Retrieve the error number set by the last posix function that failed.

Description

int posix_get_last_error (void)

Returns the errno (error number) set by the last posix function that failed. If no errors exist, 0 is returned. If you're wanting

the system error message associated with the errno, use posix_strerror().

See also pg_convert()

2960

pg_end_copy

(PHP 4 >= 4.0.3)

pg_end_copy - Sync with PostgreSQL backend

Description

bool pg_end_copy ([resource connection])

pg_end_copy() syncs the PostgreSQL frontend (usually a web server process) with the PostgreSQL server after doing a

copy operation performed by pg_put_line().pg_end_copy() must be issued, otherwise the PostgreSQL server may get out

of sync with the frontend and will report an error. Returns TRUE on success or FALSE on failure.

For further details and an example, see also pg_put_line().

2961

pg_escape_bytea

(PHP 4 >= 4.2.0)

pg_escape_bytea - Escape binary for bytea type

Description

string pg_escape_bytea (string data)

pg_escape_bytea() escapes string for bytea datatype. It returns escaped string.

Note: When you SELECT bytea type, PostgreSQL returns octal byte value prefixed by \ (e.g. \032). Users are sup-

posed to convert back to binary format by yourself.

This function requires PostgreSQL 7.2 or later. With PostgreSQL 7.2.0 and 7.2.1, bytea type must be casted when

you enable multi-byte support. i.e. INSERT INTO test_table (image) VALUES

('$image_escaped'::bytea); PostgreSQL 7.2.2 or later does not need cast. Exception is when client and

backend character encoding does not match, there may be multi-byte stream error. User must cast to bytea to avoid

this error.

Newer PostgreSQL will support unescape function. Support for built-in unescape function will be added when it's

available.

See also pg_convert()

2982

pg_last_error

(PHP 4 >= 4.2.0)

pg_last_error - Get the last error message string of a connection

Description

string pg_last_error ([resource connection])

pg_last_error() returns the last error message for given connection.

Error messages may be overwritten by internal PostgreSQL(libpq) function calls. It may not return appropriate error mes-

sage, if multiple errors are occured inside a PostgreSQL module function.

Use pg_result_error(),pg_result_status() and pg_connection_status() for better error handling.

Note: This function used to be called pg_errormessage().

See also pg_convert()

2997

pg_num_fields

(PHP 4 >= 4.2.0)

pg_num_fields - Returns the number of fields

Description

int pg_num_fields (resource result)

pg_num_fields() returns the number of fields (columns) in a PostgreSQL result. The argument is a result resource returned

by pg_query(). This function will return -1 on error.

Note: This function used to be called pg_numfields().

See also pg_num_rows() and pg_affected_rows().

2998

pg_num_rows

(PHP 4 >= 4.2.0)

pg_num_rows - Returns the number of rows

Description

int pg_num_rows (resource result)

pg_num_rows() will return the number of rows in a PostgreSQL result resource. result is a query result resource returned

by pg_query(). This function will return -1 on error.

Note: Use pg_affected_rows() to get number of rows affected by INSERT, UPDATE and DELETE query.

Note: This function used to be called pg_numrows().

See also pg_num_fields() and pg_affected_rows().

2999

pg_options

(PHP 3, PHP 4 )

pg_options - Get the options associated with the connection

Description

string pg_options (resource connection)

pg_options() will return a string containing the options specified on the given PostgreSQL connection resource.

3000

pg_pconnect

(PHP 3, PHP 4 )

pg_pconnect - Open a persistent PostgreSQL connection

Description

resource pg_pconnect (string connection_string)

pg_pconnect() opens a connection to a PostgreSQL database. It returns a connection resource that is needed by other Post-

greSQL functions.

For a description of the connection_string parameter, see pg_connect().

To enable persistent connection, the pgsql.allow_persistent php.ini directive must be set to "On" (which is the default).

The maximum number of persistent connection can be defined with the pgsql.max_persistent php.ini directive (defaults to

-1 for no limit). The total number of connections can be set with the pgsql.max_links php.ini directive.

pg_close() will not close persistent links generated by pg_pconnect().

See also pg_connect(), and the section Persistent Database Connections for more information.

3001

pg_ping

(PHP 4 >= 4.3.0)

pg_ping - Ping database connection

Description

bool pg_ping (resource connection)

pg_ping() ping database connection, try to reconnect if it is broken. It returns TRUE if connection is alive, otherwise FALSE.

See also pg_connection_status() and pg_connection_reset().

Example 680. PostgreSQL ping

<?php

$conn = pg_pconnect ("dbname=publisher");

if (!$conn) {

echo "An error occured.\n";

exit;

}

if (!pg_ping($conn))

die("Connection is broken\n");

3002

pg_port

(PHP 3, PHP 4 )

pg_port - Return the port number associated with the connection

Description

int pg_port (resource connection)

pg_port() returns the port number that the given PostgreSQL connection resource is connected to.

3003

pg_put_line

(PHP 4 >= 4.0.3)

pg_put_line - Send a NULL-terminated string to PostgreSQL backend

Description

bool pg_put_line ([resource connection, string data])

pg_put_line() sends a NULL-terminated string to the PostgreSQL backend server. This is useful for example for very high-

speed inserting of data into a table, initiated by starting a PostgreSQL copy-operation. That final NULL-character is added

automatically. Returns TRUE on success or FALSE on failure.

Note: The application must explicitly send the two characters "\." on the last line to indicate to the backend that it

has finished sending its data.

See also pg_convert()

3009

pg_send_query

(PHP 4 >= 4.2.0)

pg_send_query - Send asynchronous query

Description

bool pg_send_query (resource connection, string query)

bool pg_send_query (string query)

pg_send_query() send asynchronous query to the connection. Unlike pg_query(), it can send multiple query to Postgr-

eSQL and get the result one by one using pg_get_result(). Script execution is not blocked while query is executing. Use

pg_connection_busy() to check connection is busy (i.e. query is executing). Query may be canceled by calling

pg_cancel_query().

Although user can send multiple query at once, user cannot send multiple query over busy connection. If query is sent while

connection is busy, it waits until last query is finished and discards all result.

See also pg_query(),pg_cancel_query(),pg_get_result() and pg_connection_busy()

3010

pg_set_client_encoding

(PHP 3 CVS only, PHP 4 >= 4.0.3)

pg_set_client_encoding - Set the client encoding

Description

int pg_set_client_encoding ([resource connection, string encoding])

pg_set_client_encoding() sets the client encoding and returns 0 if success or -1 if error.

encoding is the client encoding and can be either : SQL_ASCII, EUC_JP, EUC_CN, EUC_KR, EUC_TW, UNICODE,

MULE_INTERNAL, LATINX (X=1...9), KOI8, WIN, ALT, SJIS, BIG5, WIN1250. Available encoding depends on your

PostgreSQL and libpq version. Refer to PostgreSQL manual for supported encodings for your PostgreSQL.

Note: This function requires PHP-4.0.3 or higher and PostgreSQL-7.0 or higher. Supported encoding depends on

PostgreSQL version. Refer to PostgreSQL manual for details.

The function used to be called pg_setclientencoding().

See also pg_convert()

3016

Process Control Functions

Table of Contents

pcntl_exec ...................................................................................................................................... 3022

pcntl_fork ....................................................................................................................................... 3023

pcntl_signal .................................................................................................................................... 3024

pcntl_waitpid .................................................................................................................................. 3026

pcntl_wexitstatus ............................................................................................................................. 3027

pcntl_wifexited ................................................................................................................................ 3028

pcntl_wifsignaled ............................................................................................................................. 3029

pcntl_wifstopped .............................................................................................................................. 3030

pcntl_wstopsig ................................................................................................................................ 3031

pcntl_wtermsig ................................................................................................................................ 3032

3017

Introduction

Process Control support in PHP implements the Unix style of process creation, program execution, signal handling and pro-

cess termination. Process Control should not be enabled within a webserver environment and unexpected results may hap-

pen if any Process Control functions are used within a webserver environment.

This documentation is intended to explain the general usage of each of the Process Control functions. For detailed informa-

tion about Unix process control you are encouraged to consult your systems documentation including fork(2), waitpid(2)

and signal(2) or a comprehensive reference such as Advanced Programming in the UNIX Environment by W. Richard

Stevens (Addison-Wesley).

PCNTL now uses ticks as the signal handle callback mechanism, which is much faster than the previous mechanism. This

change follows the same semantics as using "user ticks". You use the declare() statement to specify the locations in your

program where callbacks are allowed to occur. This allows you to minimize the overhead of handling asynchronous events.

In the past, compiling PHP with pcntl enabled would always incur this overhead, whether or not your script actually used

pcntl.

There is one adjustment that all pcntl scripts prior to PHP 4.3.0 must make for them to work which is to either to use de-

clare() on a section where you wish to allow callbacks or to just enable it across the entire script using the new global syn-

tax of declare().

Note: This extension is not available on Windows platforms.

Requirements

No external libraries are needed to build this extension.

Installation

Process Control support in PHP is not enabled by default. You have to compile the CGI or CLI version of PHP with -

-enable-pcntl configuration option when compiling PHP to enable Process Control support.

Note: Currently, this module will not function on non-Unix platforms (Windows).

Runtime Configuration

This extension has no configuration directives defined in php.ini.

Resource Types

This extension has no resource types defined.

Predefined Constants

The following list of signals are supported by the Process Control functions. Please see your systems signal(7) man page for

details of the default behavior of these signals.

WNOHANG (integer)

WUNTRACED (integer)

SIG_IGN (integer)

3018

SIG_DFL (integer)

SIG_ERR (integer)

SIGHUP (integer)

SIGINT (integer)

SIGQUIT (integer)

SIGILL (integer)

SIGTRAP (integer)

SIGABRT (integer)

SIGIOT (integer)

SIGBUS (integer)

SIGFPE (integer)

SIGKILL (integer)

SIGUSR1 (integer)

SIGSEGV (integer)

SIGUSR2 (integer)

SIGPIPE (integer)

SIGALRM (integer)

SIGTERM (integer)

SIGSTKFLT (integer)

SIGCLD (integer)

SIGCHLD (integer)

SIGCONT (integer)

SIGSTOP (integer)

SIGTSTP (integer)

SIGTTIN (integer)

SIGTTOU (integer)

SIGURG (integer)

SIGXCPU (integer)

SIGXFSZ (integer)

SIGVTALRM (integer)

Process Control Functions

3019

SIGPROF (integer)

SIGWINCH (integer)

SIGPOLL (integer)

SIGIO (integer)

SIGPWR (integer)

SIGSYS (integer)

SIGBABY (integer)

Examples

This example forks off a daemon process with a signal handler.

Example 684. Process Control Example

<?php

declare(ticks=1);

$pid = pcntl_fork();

if ($pid == -1) {

die("could not fork");

} else if ($pid) {

exit(); // we are the parent

} else {

// we are the child

}

// detatch from the controlling terminal

if (!posix_setsid()) {

die("could not detach from terminal");

}

// setup signal handlers

pcntl_signal(SIGTERM, "sig_handler");

pcntl_signal(SIGHUP, "sig_handler");

// loop forever performing tasks

while(1) {

// do something interesting here

}

function sig_handler($signo) {

switch($signo) {

case SIGTERM:

// handle shutdown tasks

exit;

break;

case SIGHUP:

// handle restart tasks

break;

default:

// handle all other signals

}

Process Control Functions

3020

See Also

A look at the section about POSIX functions may be useful.

Process Control Functions

3021

pcntl_exec

(PHP 4 >= 4.2.0)

pcntl_exec - Executes specified program in current process space

Description

bool pcntl_exec (string path [, array args [, array envs]])

Warning

This function is currently not documented; only the argument list is available.

3022

pcntl_fork

(PHP 4 >= 4.1.0)

pcntl_fork - Forks the currently running process

Description

int pcntl_fork (void)

The pcntl_fork() function creates a child process that differs from the parent process only in it's PID and PPID. Please see

your system's fork(2) man page for specific details as to how fork works on your system.

On success, the PID of the child process is returned in the parent's thread of execution, and a 0 is returned in the child's

thread of execution. On failure, a -1 will be returned in the parent's context, no child process will be created, and a PHP er-

ror is raised.

Example 685. pcntl_fork() Example

<?php

$pid = pcntl_fork();

if ($pid == -1) {

die("could not fork");

} else if ($pid) {

// we are the parent

} else {

// we are the child

}

See also pcntl_waitpid() and pcntl_signal().

3023

pcntl_signal

(PHP 4 >= 4.1.0)

pcntl_signal - Installs a signal handler

Description

bool pcntl_signal (int signo, mixed handle [, bool restart_syscalls])

The pcntl_signal() function installs a new signal handler for the signal indicated by signo. The signal handler is set to hand-

ler which may be the name of a user created function, or either of the two global constants SIG_IGN or SIG_DFL. The op-

tional restart_syscalls specifies whether system call restarting should be used when this signal arrives and defaults to TRUE.

Returns TRUE on success or FALSE on failure.

Note: The optional restart_syscalls parameter became available in PHP 4.3.0.

Note: The ability to use an object method as a callback became available in PHP 4.3.0. Note that when you set a

handler to an object method, that object's reference count is increased which makes it persist until you either

change the handler to something else, or your script ends.

Example 686. pcntl_signal() Example

<?php

// tick use required as of PHP 4.3.0

declare (ticks = 1);

// signal handler function

function sig_handler($signo) {

switch($signo) {

case SIGTERM:

// handle shutdown tasks

exit;

break;

case SIGHUP:

// handle restart tasks

break;

case SIGUSR1:

print "Caught SIGUSR1...\n";

break;

default:

// handle all other signals

}

print "Installing signal handler...\n";

// setup signal handlers

pcntl_signal(SIGTERM, "sig_handler");

pcntl_signal(SIGHUP, "sig_handler");

pcntl_signal(SIGUSR1, "sig_handler");

// or use an object, available as of PHP 4.3.0

// pcntl_signal(SIGUSR1, array($obj, "do_something");

print "Generating signal SIGTERM to self...\n";

// send SIGUSR1 to current process id

posix_kill(posix_getpid(), SIGUSR1);

print "Done\n"

3024

See also pcntl_fork() and pcntl_waitpid().

pcntl_signal

3025

pcntl_waitpid

(PHP 4 >= 4.1.0)

pcntl_waitpid - Waits on or returns the status of a forked child

Description

int pcntl_waitpid (int pid, int &status, int options)

The pcntl_waitpid() function suspends execution of the current process until a child as specified by the pid argument has

exited, or until a signal is delivered whose action is to terminate the current process or to call a signal handling function. If a

child as requested by pid has already exited by the time of the call (a so-called "zombie" process), the function returns im-

mediately. Any system resources used by the child are freed. Please see your system's waitpid(2) man page for specific de-

tails as to how waitpid works on your system.

pcntl_waitpid() returns the process ID of the child which exited, -1 on error or zero if WNOHANG was used and no child

was available

The value of pid can be one of the following:

Table 136. possible values for pid

< -1 wait for any child process whose process group ID is equal

to the absolute value of pid.

-1 wait for any child process; this is the same behaviour that the

wait function exhibits.

0wait for any child process whose process group ID is equal

to that of the calling process.

> 0 wait for the child whose process ID is equal to the value of

pid.

pcntl_waitpid() will store status information in the status parameter which can be evaluated using the following functions:

pcntl_wifexited(),pcntl_wifstopped(),pcntl_wifsignaled(),pcntl_wexitstatus(),pcntl_wtermsig() and

pcntl_wstopsig().

The value of options is the value of zero or more of the following two global constants OR'ed together:

Table 137. possible values for options

WNOHANG return immediately if no child has exited.

WUNTRACED return for children which are stopped, and whose status has

not been reported.

See also pcntl_fork(),pcntl_signal(),pcntl_wifexited(),pcntl_wifstopped(),pcntl_wifsignaled(),pcntl_wexitstatus(),

pcntl_wtermsig() and pcntl_wstopsig().

3026

pcntl_wexitstatus

(PHP 4 >= 4.1.0)

pcntl_wexitstatus - Returns the return code of a terminated child

Description

int pcntl_wexitstatus (int status)

Returns the return code of a terminated child. This function is only useful if pcntl_wifexited() returned TRUE.

The parameter status is the status parameter supplied to a successfull call to pcntl_waitpid().

See also pcntl_waitpid() and pcntl_wifexited().

3027

pcntl_wifexited

(PHP 4 >= 4.1.0)

pcntl_wifexited - Returns TRUE if status code represents a successful exit

Description

int pcntl_wifexited (int status)

Returns TRUE if the child status code represents a successful exit.

The parameter status is the status parameter supplied to a successfull call to pcntl_waitpid().

See also pcntl_waitpid() and pcntl_wexitstatus().

3028

pcntl_wifsignaled

(PHP 4 >= 4.1.0)

pcntl_wifsignaled - Returns TRUE if status code represents a termination due to a signal

Description

int pcntl_wifsignaled (int status)

Returns TRUE if the child process exited because of a signal which was not caught.

The parameter status is the status parameter supplied to a successfull call to pcntl_waitpid().

See also pcntl_waitpid() and pcntl_signal().

3029

pcntl_wifstopped

(PHP 4 >= 4.1.0)

pcntl_wifstopped - Returns TRUE if child process is currently stopped

Description

int pcntl_wifstopped (int status)

Returns TRUE if the child process which caused the return is currently stopped; this is only possible if the call to

pcntl_waitpid() was done using the option WUNTRACED.

The parameter status is the status parameter supplied to a successfull call to pcntl_waitpid().

See Also

These functions are also closely related to the backtick operator. Also, while in safe mode you must consider the

safe_mode_exec_dir directive.

3034

escapeshellarg

(PHP 4 >= 4.0.3)

escapeshellarg - escape a string to be used as a shell argument

Description

string escapeshellarg (string arg)

escapeshellarg() adds single quotes around a string and quotes/escapes any existing single quotes allowing you to pass a

string directly to a shell function and having it be treated as a single safe argument. This function should be used to escape

individual arguments to shell functions coming from user input. The shell functions include exec(),system() and the back-

tick operator. A standard use would be:

system("ls ".escapeshellarg($dir));

See also escshellcmd(),exec(),popen(),system(), and the backtick operator.

3035

escapeshellcmd

(PHP 3, PHP 4 )

escapeshellcmd - escape shell metacharacters

Description

string escapeshellcmd (string command)

escapeshellcmd() escapes any characters in a string that might be used to trick a shell command into executing arbitrary

commands. This function should be used to make sure that any data coming from user input is escaped before this data is

passed to the exec() or system() functions, or to the backtick operator. A standard use would be:

$e = escapeshellcmd($userinput);

system("echo $e"); // here we don't care if $e has spaces

$f = escapeshellcmd($filename);

system("touch \"/tmp/$f\"; ls -l \"/tmp/$f\""); // and here we do, so we use quotes

See also escapeshellarg(),exec(),popen(),system(), and the backtick operator.

3036

exec

(PHP 3, PHP 4 )

exec - Execute an external program

Description

string exec (string command [, array output [, int return_var]])

exec() executes the given command, however it does not output anything. It simply returns the last line from the result of the

command. If you need to execute a command and have all the data from the command passed directly back without any in-

terference, use the passthru() function.

If the output argument is present, then the specified array will be filled with every line of output from the command. Line

endings, such as \n, are not included in this array. Note that if the array already contains some elements, exec() will append

to the end of the array. If you do not want the function to append elements, call unset() on the array before passing it to ex-

ec().

If the return_var argument is present along with the array argument, then the return status of the executed command will be

written to this variable.

Warning

If you are going to allow data coming from user input to be passed to this function, then you should be using es-

capeshellarg() or escapeshellcmd() to make sure that users cannot trick the system into executing arbitrary com-

mands.

Note: If you start a program using this function and want to leave it running in the background, you have to make

sure that the output of that program is redirected to a file or some other output stream or else PHP will hang until

the execution of the program ends.

See also system(),passthru(),popen(),escapeshellcmd(), and the backtick operator.

3037

passthru

(PHP 3, PHP 4 )

passthru - Execute an external program and display raw output

Description

void passthru (string command [, int return_var])

The passthru() function is similar to the exec() function in that it executes a command. If the return_var argument is

present, the return status of the Unix command will be placed here. This function should be used in place of exec() or sys-

tem() when the output from the Unix command is binary data which needs to be passed directly back to the browser. A

common use for this is to execute something like the pbmplus utilities that can output an image stream directly. By setting

the Content-type to image/gif and then calling a pbmplus program to output a gif, you can create PHP scripts that output im-

ages directly.

Warning

If you are going to allow data coming from user input to be passed to this function, then you should be using es-

capeshellarg() or escapeshellcmd() to make sure that users cannot trick the system into executing arbitrary com-

mands.

Note: If you start a program using this function and want to leave it running in the background, you have to make

sure that the output of that program is redirected to a file or some other output stream or else PHP will hang until

the execution of the program ends.

See also exec(),system(),popen(),escapeshellcmd(), and the backtick operator.

3038

proc_close

(PHP 4 >= 4.3.0)

proc_close - Close a process opened by proc_open() and return the exit code of that process.

Description

int proc_close (resource process)

proc_close() is similar to pclose() except that it only works on processes opened by proc_open().proc_close() waits for the

process to terminate, and returns it's exit code. If you have open pipes to that process, you should fclose() them prior to call-

ing this function in order to avoid a deadlock - the child process may not be able to exit while the pipes are open.

3039

proc_get_status

(PHP 5 CVS only)

proc_get_status - Get information about a process opened by proc_open()

Description

int proc_get_status (resource process)

proc_get_status() fetches data about a process opened using proc_open(). The collected information is returned in an array

containing the following elements:

element type description

command string

pid int process id

running bool TRUE if the process is still running,

FALSE if it has terminated

signaled bool TRUE if the child process has been ter-

minated by an uncaught signal. Always

set to FALSE on Windows.

stopped bool TRUE if the child process has been

stopped by a signal. Always set to

FALSE on Windows.

exitcode int the exit code returned by the process

(which is only meaningful if running

is FALSE)

termsig int the number of the signal that caused the

child process to terminate its execution

(only meaningful if signaled is TRUE)

stopsig int the number of the signal that caused the

child process to stop its execution (only

meaningful if stopped is TRUE)

3040

proc_nice

(PHP 5 CVS only)

proc_nice - Change the priority of the current process

Description

bool proc_nice (int priority)

proc_nice() changes the priority of the current process. If an errno occurs, like the user lacks permission to change the pri-

ority, an error of level E_WARNING is generated and FALSE is returned. Otherwise, TRUE is returned.

Note: proc_nice() will only exist if your system has NICE capabilities. NICE conforms to: SVr4, SVID EXT,

AT&T, X/OPEN, BSD 4.3. So, for example, proc_nice() is not available in Windows.

See also proc_open() and proc_terminate().

3041

proc_open

(PHP 4 >= 4.3.0)

proc_open - Execute a command and open file pointers for input/output

Description

resource proc_open (string cmd, array descriptorspec, array pipes)

proc_open() is similar to popen() but provides a much greater degree of control over the program execution. cmd is the

command to be executed by the shell. descriptorspec is an indexed array where the key represents the descriptor number

and the value represents how PHP will pass that descriptor to the child process. pipes will be set to an indexed array of file

pointers that correspond to PHP's end of any pipes that are created. The return value is a resource representing the process;

you should free it using proc_close() when you are finished with it.

<?php

$descriptorspec = array(

0 => array("pipe", "r"), // stdin is a pipe that the child will read from

1 => array("pipe", "w"), // stdout is a pipe that the child will write to

2 => array("file", "/tmp/error-output.txt", "a") // stderr is a file to write to

);

$process = proc_open("php", $descriptorspec, $pipes);

if (is_resource($process)) {

// $pipes now looks like this:

// 0 => writeable handle connected to child stdin

// 1 => readable handle connected to child stdout

// Any error output will be appended to /tmp/error-output.txt

fwrite($pipes[0], "<?php echo \"Hello World!\"; ?>");

fclose($pipes[0]);

while(!feof($pipes[1])) {

echo fgets($pipes[1], 1024);

}

fclose($pipes[1]);

// It is important that you close any pipes before calling

// proc_close in order to avoid a deadlock

$return_value = proc_close($process);

echo "command returned $return_value\n";

}

The file descriptor numbers in descriptorspec are not limited to 0, 1 and 2 - you may specify any valid file descriptor num-

ber and it will be passed to the child process. This allows your script to interoperate with other scripts that run as "co-

processes". In particular, this is useful for passing passphrases to programs like PGP, GPG and openssl in a more secure

manner. It is also useful for reading status information provided by those programs on auxillary file descriptors.

Note: Windows compatibility: Descriptors beyond 2 (stderr) are made available to the child process as inheritable

handles, but since the Windows architecture does not associate file descriptor numbers with low-level handles, the

child process does not (yet) have a means of accessing those handles. Stdin, stdout and stderr work as expected.

Note: This function was introduced in PHP 4.3.0.

Note: If you only need a uni-directional (one-way) process pipe, use popen() instead, as it is much easier to use.

See also stream_select(),exec(),system(),passthru(),popen(),escapeshellcmd(), and the backtick operator.

3042

proc_terminate

(PHP 5 CVS only)

proc_terminate - kills a process opened by proc_open

Description

int proc_terminate (resource process [, int signal])

Warning

This function is currently not documented; only the argument list is available.

See also proc_open(),proc_close(), and proc_nice().

3043

shell_exec

(PHP 4 )

shell_exec - Execute command via shell and return complete output as string

Description

string shell_exec (string cmd)

This function is identical to the backtick operator.

3044

system

(PHP 3, PHP 4 )

system - Execute an external program and display output

Description

string system (string command [, int return_var])

system() is just like the C version of the function in that it executes the given command and outputs the result. If a variable

is provided as the second argument, then the return status code of the executed command will be written to this variable.

Warning

If you are going to allow data coming from user input to be passed to this function, then you should be using es-

capeshellarg() or escapeshellcmd() to make sure that users cannot trick the system into executing arbitrary com-

mands.

Note: If you start a program using this function and want to leave it running in the background, you have to make

sure that the output of that program is redirected to a file or some other output stream or else PHP will hang until

the execution of the program ends.

The system() call also tries to automatically flush the web server's output buffer after each line of output if PHP is running

as a server module.

Returns the last line of the command output on success, and FALSE on failure.

If you need to execute a command and have all the data from the command passed directly back without any interference,

use the passthru() function.

See also exec(),passthru(),popen(),escapeshellcmd(), and the backtick operator.

3045

Printer functions

Table of Contents

printer_abort ................................................................................................................................... 3048

printer_close ................................................................................................................................... 3049

printer_create_brush ......................................................................................................................... 3050

printer_create_dc ............................................................................................................................. 3051

printer_create_font ........................................................................................................................... 3052

printer_create_pen ............................................................................................................................ 3053

printer_delete_brush ......................................................................................................................... 3054

printer_delete_dc ............................................................................................................................. 3055

printer_delete_font ........................................................................................................................... 3056

printer_delete_pen ............................................................................................................................ 3057

printer_draw_bmp ............................................................................................................................ 3058

printer_draw_chord .......................................................................................................................... 3059

printer_draw_elipse .......................................................................................................................... 3060

printer_draw_line ............................................................................................................................. 3061

printer_draw_pie .............................................................................................................................. 3062

printer_draw_rectangle ...................................................................................................................... 3063

printer_draw_roundrect ..................................................................................................................... 3064

printer_draw_text ............................................................................................................................. 3065

printer_end_doc ............................................................................................................................... 3066

printer_end_page ............................................................................................................................. 3067

printer_get_option ............................................................................................................................ 3068

printer_list ...................................................................................................................................... 3069

printer_logical_fontheight .................................................................................................................. 3070

printer_open .................................................................................................................................... 3071

printer_select_brush ......................................................................................................................... 3072

printer_select_font ........................................................................................................................... 3073

printer_select_pen ............................................................................................................................ 3074

printer_set_option ............................................................................................................................ 3075

printer_start_doc .............................................................................................................................. 3077

printer_start_page ............................................................................................................................ 3078

printer_write ................................................................................................................................... 3079

3046

Introduction

These functions are only available under Windows 9.x, ME, NT4 and 2000. They have been added in PHP 4.0.4.

Installation

Add the line extension=php_printer.dll to your php.ini file.

Runtime Configuration

The behaviour of these functions is affected by settings in php.ini.

Table 138. Printer configuration options

Name Default Changeable

printer.default_printer "" PHP_INI_ALL

For further details and definition of the PHP_INI_* constants see ini_set().

3047

printer_abort

()

printer_abort - Deletes the printer's spool file

Description

void printer_abort (resource handle)

This function deletes the printers spool file.

handle must be a valid handle to a printer.

Example 687. printer_abort() example

$handle = printer_open();

printer_abort($handle);

printer_close($handle);

3048

printer_close

()

printer_close - Close an open printer connection

Description

void printer_close (resource handle)

This function closes the printer connection. printer_close() also closes the active device context.

handle must be a valid handle to a printer.

Example 688. printer_close() example

$handle = printer_open();

printer_close($handle);

3049

printer_create_brush

()

printer_create_brush - Create a new brush

Description

mixed printer_create_brush (int style, string color)

The function creates a new brush and returns a handle to it. A brush is used to fill shapes. For an example see print-

er_select_brush().color must be a color in RGB hex format, i.e. "000000" for black, style must be one of the following

constants:

•PRINTER_BRUSH_SOLID: creates a brush with a solid color.

•PRINTER_BRUSH_DIAGONAL: creates a brush with a 45-degree upward left-to-right hatch ( / ).

•PRINTER_BRUSH_CROSS: creates a brush with a cross hatch ( + ).

•PRINTER_BRUSH_DIAGCROSS: creates a brush with a 45 cross hatch ( x ).

•PRINTER_BRUSH_FDIAGONAL: creates a brush with a 45-degree downward left-to-right hatch ( \ ).

•PRINTER_BRUSH_HORIZONTAL: creates a brush with a horizontal hatch ( - ).

•PRINTER_BRUSH_VERTICAL: creates a brush with a vertical hatch ( | ).

•PRINTER_BRUSH_CUSTOM: creates a custom brush from an BMP file. The second parameter is used to specify the

BMP instead of the RGB color code.

3050

printer_create_dc

()

printer_create_dc - Create a new device context

Description

void printer_create_dc (resource handle)

The function creates a new device context. A device context is used to customize the graphic objects of the document.

handle must be a valid handle to a printer.

Example 689. printer_create_dc() example

$handle = printer_open();

printer_start_doc($handle);

printer_start_page($handle);

printer_create_dc($handle);

/* do some stuff with the dc */

printer_set_option($handle, PRINTER_TEXT_COLOR, "333333");

printer_draw_text($handle, 1, 1, "text");

printer_delete_dc($handle);

/* create another dc */

printer_create_dc($handle);

printer_set_option($handle, PRINTER_TEXT_COLOR, "000000");

printer_draw_text($handle, 1, 1, "text");

/* do some stuff with the dc */

printer_delete_dc($handle);

printer_endpage($handle);

printer_end_doc($handle);

printer_close($handle);

3051

printer_create_font

()

printer_create_font - Create a new font

Description

mixed printer_create_font (string face, int height, int width, int font_weight, bool italic, bool underline, bool

strikeout, int orientaton)

The function creates a new font and returns a handle to it. A font is used to draw text. For an example see print-

er_select_font().face must be a string specifying the font face. height specifies the font height, and width the font width.

The font_weight specifies the font weight (400 is normal), and can be one of the following predefined constants.

•PRINTER_FW_THIN: sets the font weight to thin (100).

•PRINTER_FW_ULTRALIGHT: sets the font weight to ultra light (200).

•PRINTER_FW_LIGHT: sets the font weight to light (300).

•PRINTER_FW_NORMAL: sets the font weight to normal (400).

•PRINTER_FW_MEDIUM: sets the font weight to medium (500).

•PRINTER_FW_BOLD: sets the font weight to bold (700).

•PRINTER_FW_ULTRABOLD: sets the font weight to ultra bold (800).

•PRINTER_FW_HEAVY: sets the font weight to heavy (900).

italic can be TRUE or FALSE, and sets whether the font should be italic.

underline can be TRUE or FALSE, and sets whether the font should be underlined.

strikeout can be TRUE or FALSE, and sets whether the font should be striked out.

orientation specifies a rotation. For an example see printer_select_font().

3052

printer_create_pen

()

printer_create_pen - Create a new pen

Description

mixed printer_create_pen (int style, int width, string color)

The function creates a new pen and returns a handle to it. A pen is used to draw lines and curves. For an example see print-

er_select_pen().color must be a color in RGB hex format, i.e. "000000" for black, width specifies the width of the pen

whereas style must be one of the following constants:

•PRINTER_PEN_SOLID: creates a solid pen.

•PRINTER_PEN_DASH: creates a dashed pen.

•PRINTER_PEN_DOT: creates a dotted pen.

•PRINTER_PEN_DASHDOT: creates a pen with dashes and dots.

•PRINTER_PEN_DASHDOTDOT: creates a pen with dashes and double dots.

•PRINTER_PEN_INVISIBLE: creates an invisible pen.

3053

printer_delete_brush

()

printer_delete_brush - Delete a brush

Description

bool printer_delete_brush (resource handle)

The function deletes the selected brush. For an example see printer_select_brush(). Returns TRUE on success or FALSE on

failure. handle must be a valid handle to a brush.

3054

printer_delete_dc

()

printer_delete_dc - Delete a device context

Description

bool printer_delete_dc (resource handle)

The function deletes the device context. Returns TRUE on success or FALSE on failure. For an example see print-

er_create_dc().handle must be a valid handle to a printer.

3055

printer_delete_font

()

printer_delete_font - Delete a font

Description

bool printer_delete_font (resource handle)

The function deletes the selected font. For an example see printer_select_font(). Returns TRUE on success or FALSE on

failure. handle must be a valid handle to a font.

3056

printer_delete_pen

()

printer_delete_pen - Delete a pen

Description

bool printer_delete_pen (resource handle)

The function deletes the selected pen. For an example see printer_select_pen(). Returns TRUE on success or FALSE on fail-

ure. handle must be a valid handle to a pen.

3057

printer_draw_bmp

()

printer_draw_bmp - Draw a bmp

Description

void printer_draw_bmp (resource handle, string filename, int x, int y)

The function simply draws an bmp the bitmap filename at position x,y.handle must be a valid handle to a printer.

Returns TRUE on success or FALSE on failure.

Example 690. printer_draw_bmp() example

$handle = printer_open();

printer_start_doc($handle, "My Document");

printer_start_page($handle);

printer_draw_bmp($handle, "c:\\image.bmp", 1, 1);

printer_end_page($handle);

printer_end_doc($handle);

printer_close($handle);

3058

printer_draw_chord

()

printer_draw_chord - Draw a chord

Description

void printer_draw_chord (resource handle, int rec_x, int rec_y, int rec_x1, int rec_y1, int rad_x, int rad_y, int

rad_x1, int rad_y1)

The function simply draws an chord. handle must be a valid handle to a printer.

rec_x is the upper left x coordinate of the bounding rectangle.

rec_y is the upper left y coordinate of the bounding rectangle.

rec_x1 is the lower right x coordinate of the bounding rectangle.

rec_y1 is the lower right y coordinate of the bounding rectangle.

rad_x is x coordinate of the radial defining the beginning of the chord.

rad_y is y coordinate of the radial defining the beginning of the chord.

rad_x1 is x coordinate of the radial defining the end of the chord.

rad_y1 is y coordinate of the radial defining the end of the chord.

Example 691. printer_draw_chord() example

$handle = printer_open();

printer_start_doc($handle, "My Document");

printer_start_page($handle);

$pen = printer_create_pen(PRINTER_PEN_SOLID, 2, "000000");

printer_select_pen($handle, $pen);

$brush = printer_create_brush(PRINTER_BRUSH_SOLID, "2222FF");

printer_select_brush($handle, $brush);

printer_draw_chord($handle, 1, 1, 500, 500, 1, 1, 500, 1);

printer_delete_brush($brush);

printer_delete_pen($pen);

printer_end_page($handle);

printer_end_doc($handle);

printer_close($handle);

3059

printer_draw_elipse

()

printer_draw_elipse - Draw an ellipse

Description

void printer_draw_elipse (resource handle, int ul_x, int ul_y, int lr_x, int lr_y)

The function simply draws an ellipse. handle must be a valid handle to a printer.

ul_x is the upper left x coordinate of the ellipse.

ul_y is the upper left y coordinate of the ellipse.

lr_x is the lower right x coordinate of the ellipse.

lr_y is the lower right y coordinate of the ellipse.

Example 692. printer_draw_elipse() example

$handle = printer_open();

printer_start_doc($handle, "My Document");

printer_start_page($handle);

$pen = printer_create_pen(PRINTER_PEN_SOLID, 2, "000000");

printer_select_pen($handle, $pen);

$brush = printer_create_brush(PRINTER_BRUSH_SOLID, "2222FF");

printer_select_brush($handle, $brush);

printer_draw_elipse($handle, 1, 1, 500, 500);

printer_delete_brush($brush);

printer_delete_pen($pen);

printer_end_page($handle);

printer_end_doc($handle);

printer_close($handle);

3060

printer_draw_line

()

printer_draw_line - Draw a line

Description

void printer_draw_line (resource printer_handle, int from_x, int from_y, int to_x, int to_y)

The function simply draws a line from position from_x,from_y to position to_x,to_y using the selected pen. printer_handle

must be a valid handle to a printer.

Example 693. printer_draw_line() example

$handle = printer_open();

printer_start_doc($handle, "My Document");

printer_start_page($handle);

$pen = printer_create_pen(PRINTER_PEN_SOLID, 30, "000000");

printer_select_pen($handle, $pen);

printer_draw_line($handle, 1, 10, 1000, 10);

printer_draw_line($handle, 1, 60, 500, 60);

printer_delete_pen($pen);

printer_end_page($handle);

printer_end_doc($handle);

printer_close($handle);

3061

printer_draw_pie

()

printer_draw_pie - Draw a pie

Description

void printer_draw_pie (resource handle, int rec_x, int rec_y, int rec_x1, int rec_y1, int rad1_x, int rad1_y, int

rad2_x, int rad2_y)

The function simply draws an pie. handle must be a valid handle to a printer.

rec_x is the upper left x coordinate of the bounding rectangle.

rec_y is the upper left y coordinate of the bounding rectangle.

rec_x1 is the lower right x coordinate of the bounding rectangle.

rec_y1 is the lower right y coordinate of the bounding rectangle.

rad1_x is x coordinate of the first radial's ending.

rad1_y is y coordinate of the first radial's ending.

rad2_x is x coordinate of the second radial's ending.

rad2_y is y coordinate of the second radial's ending.

Example 694. printer_draw_pie() example

$handle = printer_open();

printer_start_doc($handle, "My Document");

printer_start_page($handle);

$pen = printer_create_pen(PRINTER_PEN_SOLID, 2, "000000");

printer_select_pen($handle, $pen);

$brush = printer_create_brush(PRINTER_BRUSH_SOLID, "2222FF");

printer_select_brush($handle, $brush);

printer_draw_pie($handle, 1, 1, 500, 500, 1, 1, 500, 1);

printer_delete_brush($brush);

printer_delete_pen($pen);

printer_end_page($handle);

printer_end_doc($handle);

printer_close($handle);

3062

printer_draw_rectangle

()

printer_draw_rectangle - Draw a rectangle

Description

void printer_draw_rectangle (resource handle, int ul_x, int ul_y, int lr_x, int lr_y)

The function simply draws a rectangle.

handle must be a valid handle to a printer.

ul_x is the upper left x coordinate of the rectangle.

ul_y is the upper left y coordinate of the rectangle.

lr_x is the lower right x coordinate of the rectangle.

lr_y is the lower right y coordinate of the rectangle.

Example 695. printer_draw_rectangle() example

$handle = printer_open();

printer_start_doc($handle, "My Document");

printer_start_page($handle);

$pen = printer_create_pen(PRINTER_PEN_SOLID, 2, "000000");

printer_select_pen($handle, $pen);

$brush = printer_create_brush(PRINTER_BRUSH_SOLID, "2222FF");

printer_select_brush($handle, $brush);

printer_draw_rectangle($handle, 1, 1, 500, 500);

printer_delete_brush($brush);

printer_delete_pen($pen);

printer_end_page($handle);

printer_end_doc($handle);

printer_close($handle);

3063

printer_draw_roundrect

()

printer_draw_roundrect - Draw a rectangle with rounded corners

Description

void printer_draw_roundrect (resource handle, int ul_x, int ul_y, int lr_x, int lr_y, int width, int height)

The function simply draws a rectangle with rounded corners.

handle must be a valid handle to a printer.

ul_x is the upper left x coordinate of the rectangle.

ul_y is the upper left y coordinate of the rectangle.

lr_x is the lower right x coordinate of the rectangle.

lr_y is the lower right y coordinate of the rectangle.

width is the width of the ellipse.

height is the height of the ellipse.

Example 696. printer_draw_roundrect() example

$handle = printer_open();

printer_start_doc($handle, "My Document");

printer_start_page($handle);

$pen = printer_create_pen(PRINTER_PEN_SOLID, 2, "000000");

printer_select_pen($handle, $pen);

$brush = printer_create_brush(PRINTER_BRUSH_SOLID, "2222FF");

printer_select_brush($handle, $brush);

printer_draw_roundrect($handle, 1, 1, 500, 500, 200, 200);

printer_delete_brush($brush);

printer_delete_pen($pen);

printer_end_page($handle);

printer_end_doc($handle);

printer_close($handle);

3064

printer_draw_text

()

printer_draw_text - Draw text

Description

void printer_draw_text (resource printer_handle, string text, int x, int y)

The function simply draws text at position x,yusing the selected font. printer_handle must be a valid handle to a printer.

Example 697. printer_draw_text() example

$handle = printer_open();

printer_start_doc($handle, "My Document");

printer_start_page($handle);

$font = printer_create_font("Arial",72,48,400,false,false,false,0);

printer_select_font($handle, $font);

printer_draw_text($handle, "test", 10, 10);

printer_delete_font($font);

printer_end_page($handle);

printer_end_doc($handle);

printer_close($handle);

3065

printer_end_doc

()

printer_end_doc - Close document

Description

bool printer_end_doc (resource handle)

Closes a new document in the printer spooler. The document is now ready for printing. For an example see print-

er_start_doc().handle must be a valid handle to a printer.

3066

printer_end_page

()

printer_end_page - Close active page

Description

bool printer_end_page (resource handle)

The function closes the active page in the active document. For an example see printer_start_doc().handle must be a valid

handle to a printer.

3067

printer_get_option

()

printer_get_option - Retrieve printer configuration data

Description

mixed printer_get_option (resource handle, string option)

The function retrieves the configuration setting of option.handle must be a valid handle to a printer. Take a look at print-

er_set_option() for the settings that can be retrieved, additionally the following settings can be retrieved:

•PRINTER_DEVICENAME returns the devicename of the printer.

•PRINTER_DRIVERVERSION returns the printer driver version.

Example 698. printer_get_option() example

$handle = printer_open();

print printer_get_option($handle, PRINTER_DRIVERVERSION);

printer_close($handle);

3068

printer_list

()

printer_list - Return an array of printers attached to the server

Description

array printer_list (int enumtype [, string name [, int level]])

The function enumerates available printers and their capabilities. level sets the level of information request. Can be 1,2,4 or

5. enumtype must be one of the following predefined constants:

•PRINTER_ENUM_LOCAL: enumerates the locally installed printers.

•PRINTER_ENUM_NAME: enumerates the printer of name, can be a server, domain or print provider.

•PRINTER_ENUM_SHARED: this parameter can't be used alone, it has to be OR'ed with other parameters, i.e. PRINT-

ER_ENUM_LOCAL to detect the locally shared printers.

•PRINTER_ENUM_DEFAULT: (Win9.x only) enumerates the default printer.

•PRINTER_ENUM_CONNECTIONS: (WinNT/2000 only) enumerates the printers to which the user has made connec-

tions.

•PRINTER_ENUM_NETWORK: (WinNT/2000 only) enumerates network printers in the computer's domain. Only valid

if level is 1.

•PRINTER_ENUM_REMOTE: (WinNT/2000 only) enumerates network printers and print servers in the computer's do-

main. Only valid if level is 1.

Example 699. printer_list() example

/* detect locally shared printer */

var_dump( printer_list(PRINTER_ENUM_LOCAL | PRINTER_ENUM_SHARED) );

3069

printer_logical_fontheight

()

printer_logical_fontheight - Get logical font height

Description

int printer_logical_fontheight (resource handle, int height)

The function calculates the logical font height of height.handle must be a valid handle to a printer.

Example 700. printer_logical_fontheight() example

$handle = printer_open();

print printer_logical_fontheight($handle, 72);

printer_close($handle);

3070

printer_open

()

printer_open - Open connection to a printer

Description

mixed printer_open ([string devicename])

This function tries to open a connection to the printer devicename, and returns a handle on success or FALSE on failure.

If no parameter was given it tries to open a connection to the default printer (if not specified in php.ini as print-

er.default_printer, php tries to detect it).

printer_open() also starts a device context.

Example 701. printer_open() example

$handle = printer_open("HP Deskjet 930c");

$handle = printer_open();

3071

printer_select_brush

()

printer_select_brush - Select a brush

Description

void printer_select_brush (resource printer_handle, resource brush_handle)

The function selects a brush as the active drawing object of the actual device context. A brush is used to fill shapes. If you

draw an rectangle the brush is used to draw the shapes, while the pen is used to draw the border. If you haven't selected a

brush before drawing shapes, the shape won't be filled. printer_handle must be a valid handle to a printer. brush_handle

must be a valid handle to a brush.

Example 702. printer_select_brush() example

$handle = printer_open();

printer_start_doc($handle, "My Document");

printer_start_page($handle);

$pen = printer_create_pen(PRINTER_PEN_SOLID, 2, "000000");

printer_select_pen($handle, $pen);

$brush = printer_create_brush(PRINTER_BRUSH_CUSTOM, "c:\\brush.bmp");

printer_select_brush($handle, $brush);

printer_draw_rectangle($handle, 1,1,500,500);

printer_delete_brush($brush);

$brush = printer_create_brush(PRINTER_BRUSH_SOLID, "000000");

printer_select_brush($handle, $brush);

printer_draw_rectangle($handle, 1,501,500,1001);

printer_delete_brush($brush);

printer_delete_pen($pen);

printer_end_page($handle);

printer_end_doc($handle);

printer_close($handle);

3072

printer_select_font

()

printer_select_font - Select a font

Description

void printer_select_font (resource printer_handle, resource font_handle)

The function selects a font to draw text. printer_handle must be a valid handle to a printer. font_handle must be a valid

handle to a font.

Example 703. printer_select_font() example

$handle = printer_open();

printer_start_doc($handle, "My Document");

printer_start_page($handle);

$font = printer_create_font("Arial", 148, 76, PRINTER_FW_MEDIUM, false, false, false, -50);

printer_select_font($handle, $font);

printer_draw_text($handle, "PHP is simply cool", 40, 40);

printer_delete_font($font);

printer_end_page($handle);

printer_end_doc($handle);

printer_close($handle);

3073

printer_select_pen

()

printer_select_pen - Select a pen

Description

void printer_select_pen (resource printer_handle, resource pen_handle)

The function selects a pen as the active drawing object of the actual device context. A pen is used to draw lines and curves.

I.e. if you draw a single line the pen is used. If you draw an rectangle the pen is used to draw the borders, while the brush is

used to fill the shape. If you haven't selected a pen before drawing shapes, the shape won't be outlined. printer_handle must

be a valid handle to a printer. pen_handle must be a valid handle to a pen.

Example 704. printer_select_pen() example

$handle = printer_open();

printer_start_doc($handle, "My Document");

printer_start_page($handle);

$pen = printer_create_pen(PRINTER_PEN_SOLID, 30, "2222FF");

printer_select_pen($handle, $pen);

printer_draw_line($handle, 1, 60, 500, 60);

printer_delete_pen($pen);

printer_end_page($handle);

printer_end_doc($handle);

printer_close($handle);

3074

printer_set_option

()

printer_set_option - Configure the printer connection

Description

bool printer_set_option (resource handle, int option, mixed value)

The function sets the following options for the current connection. handle must be a valid handle to a printer. For option can

be one of the following constants:

•PRINTER_COPIES: sets how many copies should be printed, value must be an integer.

•PRINTER_MODE: specifies the type of data (text, raw or emf), value must be a string.

•PRINTER_TITLE: specifies the name of the document, value must be a string.

•PRINTER_ORIENTATION: specifies the orientation of the paper, value can be either PRINT-

ER_ORIENTATION_PORTRAIT or PRINTER_ORIENTATION_LANDSCAPE

•PRINTER_RESOLUTION_Y: specifies the y-resolution in DPI, value must be an integer.

•PRINTER_RESOLUTION_X: specifies the x-resolution in DPI, value must be an integer.

•PRINTER_PAPER_FORMAT: specifies the a predefined paper format, set value to PRINTER_FORMAT_CUSTOM if

you want to specify a custom format with PRINTER_PAPER_WIDTH and PRINTER_PAPER_LENGTH. value can be

one of the following constants.

•PRINTER_FORMAT_CUSTOM: let's you specify a custom paper format.

•PRINTER_FORMAT_LETTER: specifies standard letter format (8 1/2- by 11-inches).

•PRINTER_FORMAT_LETTER: specifies standard legal format (8 1/2- by 14-inches).

•PRINTER_FORMAT_A3: specifies standard A3 format (297- by 420-millimeters).

•PRINTER_FORMAT_A4: specifies standard A4 format (210- by 297-millimeters).

•PRINTER_FORMAT_A5: specifies standard A5 format (148- by 210-millimeters).

•PRINTER_FORMAT_B4: specifies standard B4 format (250- by 354-millimeters).

•PRINTER_FORMAT_B5: specifies standard B5 format (182- by 257-millimeter).

•PRINTER_FORMAT_FOLIO: specifies standard FOLIO format (8 1/2- by 13-inch).

•PRINTER_PAPER_LENGTH: if PRINTER_PAPER_FORMAT is set to PRINTER_FORMAT_CUSTOM, PRINT-

ER_PAPER_LENGTH specifies a custom paper length in mm, value must be an integer.

•PRINTER_PAPER_WIDTH: if PRINTER_PAPER_FORMAT is set to PRINTER_FORMAT_CUSTOM, PRINT-

ER_PAPER_WIDTH specifies a custom paper width in mm, value must be an integer.

•PRINTER_SCALE: specifies the factor by which the printed output is to be scaled. the page size is scaled from the phys-

3075

ical page size by a factor of scale/100. for example if you set the scale to 50, the output would be half of it's original

size. value must be an integer.

•PRINTER_BACKGROUND_COLOR: specifies the background color for the actual device context, value must be a

string containing the rgb information in hex format i.e. "005533".

•PRINTER_TEXT_COLOR: specifies the text color for the actual device context, value must be a string containing the

rgb information in hex format i.e. "005533".

•PRINTER_TEXT_ALIGN: specifies the text alignment for the actual device context, value can be combined through

OR'ing the following constants:

•PRINTER_TA_BASELINE: text will be aligned at the base line.

•PRINTER_TA_BOTTOM: text will be aligned at the bottom.

•PRINTER_TA_TOP: text will be aligned at the top.

•PRINTER_TA_CENTER: text will be aligned at the center.

•PRINTER_TA_LEFT: text will be aligned at the left.

•PRINTER_TA_RIGHT: text will be aligned at the right.

Example 705. printer_set_option() example

$handle = printer_open();

printer_set_option($handle, PRINTER_SCALE, 75);

printer_set_option($handle, PRINTER_TEXT_ALIGN, PRINTER_TA_LEFT);

printer_close($handle);

printer_set_option

3076

printer_start_doc

()

printer_start_doc - Start a new document

Description

bool printer_start_doc (resource handle [, string document])

The function creates a new document in the printer spooler. A document can contain multiple pages, it's used to schedule

the print job in the spooler. handle must be a valid handle to a printer. The optional parameter document can be used to set

an alternative document name.

Example 706. printer_start_doc() example

$handle = printer_open();

printer_start_doc($handle, "My Document");

printer_start_page($handle);

printer_end_page($handle);

printer_end_doc($handle);

printer_close($handle);

3077

printer_start_page

()

printer_start_page - Start a new page

Description

bool printer_start_page (resource handle)

The function creates a new page in the active document. For an example see printer_start_doc().handle must be a valid

handle to a printer.

3078

printer_write

()

printer_write - Write data to the printer

Description

bool printer_write (resource handle, string content)

Writes content directly to the printer. Returns TRUE on success or FALSE on failure.

handle must be a valid handle to a printer.

Example 707. printer_write() example

$handle = printer_open();

printer_write($handle, "Text to print");

printer_close($handle);

3079

Pspell Functions

Table of Contents

pspell_add_to_personal ..................................................................................................................... 3082

pspell_add_to_session ....................................................................................................................... 3083

pspell_check ................................................................................................................................... 3084

pspell_clear_session ......................................................................................................................... 3085

pspell_config_create ......................................................................................................................... 3086

pspell_config_ignore ........................................................................................................................ 3087

pspell_config_mode ......................................................................................................................... 3088

pspell_config_personal ...................................................................................................................... 3089

pspell_config_repl ............................................................................................................................ 3090

pspell_config_runtogether ................................................................................................................. 3091

pspell_config_save_repl .................................................................................................................... 3092

pspell_new_config ........................................................................................................................... 3093

pspell_new_personal ......................................................................................................................... 3094

pspell_new ..................................................................................................................................... 3096

pspell_save_wordlist ......................................................................................................................... 3097

pspell_store_replacement ................................................................................................................... 3098

pspell_suggest ................................................................................................................................. 3099

3080

Introduction

These functions allow you to check the spelling of a word and offer suggestions.

Note: This extension is not available on Windows platforms.

Requirements

To compile PHP with pspell support, you need the aspell and pspell libraries, available from http://aspell.sourceforge.net/

and http://aspell.net/respectively.

Installation

If you have the libraries needed add the --with-pspell[=dir] option when compiling PHP.

Runtime Configuration

This extension has no configuration directives defined in php.ini.

Resource Types

This extension has no resource types defined.

Predefined Constants

The constants below are defined by this extension, and will only be available when the extension has either been compiled

into PHP or dynamically loaded at runtime.

PSPELL_FAST (integer)

PSPELL_NORMAL (integer)

PSPELL_BAD_SPELLERS (integer)

PSPELL_RUN_TOGETHER (integer)

3081

pspell_add_to_personal

(PHP 4 >= 4.0.2)

pspell_add_to_personal - Add the word to a personal wordlist

Description

int pspell_add_to_personal (int dictionary_link, string word)

pspell_add_to_personal() adds a word to the personal wordlist. If you used pspell_new_config() with

pspell_config_personal() to open the dictionary, you can save the wordlist later with pspell_save_wordlist(). Please, note

that this function will not work unless you have pspell .11.2 and aspell .32.5 or later.

Example 708. pspell_add_to_personal()

$pspell_config = pspell_config_create ("en");

pspell_config_personal ($pspell_config, "/var/dictionaries/custom.pws");

$pspell_link = pspell_new_config ($pspell_config);

pspell_add_to_personal ($pspell_link, "Vlad");

pspell_save_wordlist ($pspell_link);

3082

pspell_add_to_session

(PHP 4 >= 4.0.2)

pspell_add_to_session - Add the word to the wordlist in the current session

Description

int pspell_add_to_session (int dictionary_link, string word)

pspell_add_to_session() adds a word to the wordlist associated with the current session. It is very similar to

pspell_add_to_personal()

3083

pspell_check

(PHP 4 >= 4.0.2)

pspell_check - Check a word

Description

bool pspell_check (int dictionary_link, string word)

pspell_check() checks the spelling of a word and returns TRUE if the spelling is correct, FALSE if not.

Example 709. pspell_check()

$pspell_link = pspell_new ("en");

if (pspell_check ($pspell_link, "testt")) {

echo "This is a valid spelling";

} else {

echo "Sorry, wrong spelling";

}

3084

pspell_clear_session

(PHP 4 >= 4.0.2)

pspell_clear_session - Clear the current session

Description

int pspell_clear_session (int dictionary_link)

pspell_clear_session() clears the current session. The current wordlist becomes blank, and, for example, if you try to save it

with pspell_save_wordlist(), nothing happens.

Example 710. pspell_add_to_personal()

$pspell_config = pspell_config_create ("en");

pspell_config_personal ($pspell_config, "/var/dictionaries/custom.pws");

$pspell_link = pspell_new_config ($pspell_config);

pspell_add_to_personal ($pspell_link, "Vlad");

pspell_clear_session ($pspell_link);

pspell_save_wordlist ($pspell_link); //"Vlad" will not be saved

3085

pspell_config_create

(PHP 4 >= 4.0.2)

pspell_config_create - Create a config used to open a dictionary

Description

int pspell_config_create (string language [, string spelling [, string jargon [, string encoding ]]])

pspell_config_create() has a very similar syntax to pspell_new(). In fact, using pspell_config_create() immediatelly fol-

lowed by pspell_new_config() will produce the exact same result. However, after creating a new config, you can also use

pspell_config_*() functions before calling pspell_new_config() to take advantage of some advanced functionality.

The language parameter is the language code which consists of the two letter ISO 639 language code and an optional two

letter ISO 3166 country code after a dash or underscore.

The spelling parameter is the requested spelling for languages with more than one spelling such as English. Known values

are 'american', 'british', and 'canadian'.

The jargon parameter contains extra information to distinguish two different words lists that have the same language and

spelling parameters.

The encoding parameter is the encoding that words are expected to be in. Valid values are 'utf-8', 'iso8859-*', 'koi8-r', 'vis-

cii', 'cp1252', 'machine unsigned 16', 'machine unsigned 32'. This parameter is largely untested, so be careful when using.

The mode parameter is the mode in which spellchecker will work. There are several modes available:

•PSPELL_FAST - Fast mode (least number of suggestions)

•PSPELL_NORMAL - Normal mode (more suggestions)

•PSPELL_BAD_SPELLERS - Slow mode (a lot of suggestions)

For more information and examples, check out inline manual pspell website:http://aspell.net/.

Example 711. pspell_config_create()

$pspell_config = pspell_config_create ("en");

pspell_config_personal ($pspell_config, "/var/dictionaries/custom.pws");

pspell_config_repl ($pspell_config, "/var/dictionaries/custom.repl");

$pspell_link = pspell_new_personal ($pspell_config, "en");

3086

pspell_config_ignore

(PHP 4 >= 4.0.2)

pspell_config_ignore - Ignore words less than N characters long

Description

int pspell_config_ignore (int dictionary_link, int n)

pspell_config_ignore() should be used on a config before calling pspell_new_config(). This function allows short words to

be skipped by the spellchecker. Words less then n characters will be skipped.

Example 712. pspell_config_ignore()

$pspell_config = pspell_config_create ("en");

pspell_config_ignore($pspell_config, 5);

$pspell_link = pspell_new_config($pspell_config);

pspell_check($pspell_link, "abcd"); //will not result in an error

3087

pspell_config_mode

(PHP 4 >= 4.0.2)

pspell_config_mode - Change the mode number of suggestions returned

Description

int pspell_config_mode (int dictionary_link, int mode)

pspell_config_mode() should be used on a config before calling pspell_new_config(). This function determines how many

suggestions will be returned by pspell_suggest().

The mode parameter is the mode in which spellchecker will work. There are several modes available:

•PSPELL_FAST - Fast mode (least number of suggestions)

•PSPELL_NORMAL - Normal mode (more suggestions)

•PSPELL_BAD_SPELLERS - Slow mode (a lot of suggestions)

Example 713. pspell_config_mode()

$pspell_config = pspell_config_create ("en");

pspell_config_mode($pspell_config, PSPELL_FAST);

$pspell_link = pspell_new_config($pspell_config);

pspell_check($pspell_link, "thecat");

3088

pspell_config_personal

(PHP 4 >= 4.0.2)

pspell_config_personal - Set a file that contains personal wordlist

Description

int pspell_config_personal (int dictionary_link, string file)

pspell_config_personal() should be used on a config before calling pspell_new_config(). The personal wordlist will be

loaded and used in addition to the standard one after you call pspell_new_config(). If the file does not exist, it will be cre-

ated. The file is also the file where pspell_save_wordlist() will save personal wordlist to. The file should be writable by

whoever php runs as (e.g. nobody). Please, note that this function will not work unless you have pspell .11.2 and aspell .32.5

or later.

Example 714. pspell_config_personal()

$pspell_config = pspell_config_create ("en");

pspell_config_personal ($pspell_config, "/var/dictionaries/custom.pws");

$pspell_link = pspell_new_config ($pspell_config);

pspell_check ($pspell_link, "thecat");

3089

pspell_config_repl

(PHP 4 >= 4.0.2)

pspell_config_repl - Set a file that contains replacement pairs

Description

int pspell_config_repl (int dictionary_link, string file)

pspell_config_repl() should be used on a config before calling pspell_new_config(). The replacement pairs improve the

quality of the spellchecker. When a word is misspelled, and a proper suggestion was not found in the list,

pspell_store_replacement() can be used to store a replacement pair and then pspell_save_wordlist() to save the wordlist

along with the replacement pairs. The file should be writable by whoever php runs as (e.g. nobody). Please, note that this

function will not work unless you have pspell .11.2 and aspell .32.5 or later.

Example 715. pspell_config_repl()

$pspell_config = pspell_config_create ("en");

pspell_config_personal ($pspell_config, "/var/dictionaries/custom.pws");

pspell_config_repl ($pspell_config, "/var/dictionaries/custom.repl");

$pspell_link = pspell_new_config ($pspell_config);

pspell_check ($pspell_link, "thecat");

3090

pspell_config_runtogether

(PHP 4 >= 4.0.2)

pspell_config_runtogether - Consider run-together words as valid compounds

Description

int pspell_config_runtogether (int dictionary_link, bool flag)

pspell_config_runtogether() should be used on a config before calling pspell_new_config(). This function determines

whether run-together words will be treated as legal compounds. That is, "thecat" will be a legal compound, athough there

should be a space between the two words. Changing this setting only affects the results returned by pspell_check();

pspell_suggest() will still return suggestions.

Example 716. pspell_config_runtogether()

$pspell_config = pspell_config_create ("en");

pspell_config_runtogether ($pspell_config, true);

$pspell_link = pspell_new_config ($pspell_config);

pspell_check ($pspell_link, "thecat");

3091

pspell_config_save_repl

(PHP 4 >= 4.0.2)

pspell_config_save_repl - Determine whether to save a replacement pairs list along with the wordlist

Description

int pspell_config_save_repl (int dictionary_link, bool flag)

pspell_config_save_repl() should be used on a config before calling pspell_new_config(). It determines whether

pspell_save_wordlist() will save the replacement pairs along with the wordlist. Usually there is no need to use this function

because if pspell_config_repl() is used, the replacement pairs will be saved by pspell_save_wordlist() anyway, and if it is

not, the replacement pairs will not be saved. Please, note that this function will not work unless you have pspell .11.2 and

aspell .32.5 or later.

3092

pspell_new_config

(PHP 4 >= 4.0.2)

pspell_new_config - Load a new dictionary with settings based on a given config

Description

int pspell_new_config (int config)

pspell_new_config() opens up a new dictionary with settings specified in a config, created with with

pspell_config_create() and modified with pspell_config_*() functions. This method provides you with the most flexibility

and has all the functionality provided by pspell_new() and pspell_new_personal().

The config parameter is the one returned by pspell_config_create() when the config was created.

Example 717. pspell_new_config()

$pspell_config = pspell_config_create ("en");

pspell_config_personal ($pspell_config, "/var/dictionaries/custom.pws");

pspell_config_repl ($pspell_config, "/var/dictionaries/custom.repl");

$pspell_link = pspell_new_config ($pspell_config);

3093

pspell_new_personal

(PHP 4 >= 4.0.2)

pspell_new_personal - Load a new dictionary with personal wordlist

Description

int pspell_new_personal (string personal, string language [, string spelling [, string jargon [, string encoding [,

int mode ]]]])

pspell_new_personal() opens up a new dictionary with a personal wordlist and returns the dictionary link identifier for use

in other pspell functions. The wordlist can be modified and saved with pspell_save_wordlist(), if desired. However, the re-

placement pairs are not saved. In order to save replacement pairs, you should create a config using pspell_config_create(),

set the personal wordlist file with pspell_config_personal(), set the file for replacement pairs with pspell_config_repl(),

and open a new dictionary with pspell_new_config().

The personal parameter specifies the file where words added to the personal list will be stored. It should be an absolute file-

name beginning with '/' because otherwise it will be relative to $HOME, which is "/root" for most systems, and is probably

not what you want.

The language parameter is the language code which consists of the two letter ISO 639 language code and an optional two

letter ISO 3166 country code after a dash or underscore.

The spelling parameter is the requested spelling for languages with more than one spelling such as English. Known values

are 'american', 'british', and 'canadian'.

The jargon parameter contains extra information to distinguish two different words lists that have the same language and

spelling parameters.

The encoding parameter is the encoding that words are expected to be in. Valid values are 'utf-8', 'iso8859-*', 'koi8-r', 'vis-

cii', 'cp1252', 'machine unsigned 16', 'machine unsigned 32'. This parameter is largely untested, so be careful when using.

The mode parameter is the mode in which spellchecker will work. There are several modes available:

•PSPELL_FAST - Fast mode (least number of suggestions)

•PSPELL_NORMAL - Normal mode (more suggestions)

•PSPELL_BAD_SPELLERS - Slow mode (a lot of suggestions)

•PSPELL_RUN_TOGETHER - Consider run-together words as legal compounds. That is, "thecat" will be a legal compound,

athough there should be a space between the two words. Changing this setting only affects the results returned by

pspell_check();pspell_suggest() will still return suggestions.

Mode is a bitmask constructed from different constants listed above. However, PSPELL_FAST,PSPELL_NORMAL and

PSPELL_BAD_SPELLERS are mutually exclusive, so you should select only one of them.

For more information and examples, check out inline manual pspell website:http://aspell.net/.

Example 718. pspell_new_personal()

$pspell_link = pspell_new_personal ("/var/dictionaries/custom.pws",

"en", "", "", "", PSPELL_FAST|PSPELL_RUN_TOGETHER));

3094

pspell_new_personal

3095

pspell_new

(PHP 4 >= 4.0.2)

pspell_new - Load a new dictionary

Description

int pspell_new (string language [, string spelling [, string jargon [, string encoding [, int mode ]]]])

pspell_new() opens up a new dictionary and returns the dictionary link identifier for use in other pspell functions.

The language parameter is the language code which consists of the two letter ISO 639 language code and an optional two

letter ISO 3166 country code after a dash or underscore.

The spelling parameter is the requested spelling for languages with more than one spelling such as English. Known values

are 'american', 'british', and 'canadian'.

The jargon parameter contains extra information to distinguish two different words lists that have the same language and

spelling parameters.

The encoding parameter is the encoding that words are expected to be in. Valid values are 'utf-8', 'iso8859-*', 'koi8-r', 'vis-

cii', 'cp1252', 'machine unsigned 16', 'machine unsigned 32'. This parameter is largely untested, so be careful when using.

The mode parameter is the mode in which spellchecker will work. There are several modes available:

•PSPELL_FAST - Fast mode (least number of suggestions)

•PSPELL_NORMAL - Normal mode (more suggestions)

•PSPELL_BAD_SPELLERS - Slow mode (a lot of suggestions)

•PSPELL_RUN_TOGETHER - Consider run-together words as legal compounds. That is, "thecat" will be a legal compound,

athough there should be a space between the two words. Changing this setting only affects the results returned by

pspell_check();pspell_suggest() will still return suggestions.

Mode is a bitmask constructed from different constants listed above. However, PSPELL_FAST,PSPELL_NORMAL and

PSPELL_BAD_SPELLERS are mutually exclusive, so you should select only one of them.

For more information and examples, check out inline manual pspell website:http://aspell.net/.

Example 719. pspell_new()

$pspell_link = pspell_new ("en", "", "", "",

(PSPELL_FAST|PSPELL_RUN_TOGETHER));

3096

pspell_save_wordlist

(PHP 4 >= 4.0.2)

pspell_save_wordlist - Save the personal wordlist to a file

Description

int pspell_save_wordlist (int dictionary_link)

pspell_save_wordlist() saves the personal wordlist from the current session. The dictionary has to be open with

pspell_new_personal(), and the location of files to be saved specified with pspell_config_personal() and (optionally)

pspell_config_repl(). Please, note that this function will not work unless you have pspell .11.2 and aspell .32.5 or later.

Example 720. pspell_add_to_personal()

$pspell_config = pspell_config_create ("en");

pspell_config_personal ($pspell_config, "/tmp/dicts/newdict");

$pspell_link = pspell_new_config ($pspell_config);

pspell_add_to_personal ($pspell_link, "Vlad");

pspell_save_wordlist ($pspell_link);

3097

pspell_store_replacement

(PHP 4 >= 4.0.2)

pspell_store_replacement - Store a replacement pair for a word

Description

int pspell_store_replacement (int dictionary_link, string misspelled, string correct)

pspell_store_replacement() stores a replacement pair for a word, so that replacement can be returned by pspell_suggest()

later. In order to be able to take advantage of this function, you have to use pspell_new_personal() to open the dictionary.

In order to permanently save the replacement pair, you have to use pspell_config_personal() and pspell_config_repl() to

set the path where to save your custom wordlists, and then use pspell_save_wordlist() for the changes to be written to disk.

Please, note that this function will not work unless you have pspell .11.2 and aspell .32.5 or later.

Example 721. pspell_store_replacement()

$pspell_config = pspell_config_create ("en");

pspell_config_personal ($pspell_config, "/var/dictionaries/custom.pws");

pspell_config_repl ($pspell_config, "/var/dictionaries/custom.repl");

$pspell_link = pspell_new_config ($pspell_config);

pspell_store_replacement ($pspell_link, $misspelled, $correct);

pspell_save_wordlist ($pspell_link);

3098

pspell_suggest

(PHP 4 >= 4.0.2)

pspell_suggest - Suggest spellings of a word

Description

array pspell_suggest (int dictionary_link, string word)

pspell_suggest() returns an array of possible spellings for the given word.

Example 722. pspell_suggest()

$pspell_link = pspell_new ("en");

if (!pspell_check ($pspell_link, "testt")) {

$suggestions = pspell_suggest ($pspell_link, "testt");

foreach ($suggestions as $suggestion) {

echo "Possible spelling: $suggestion<br>";

}

3099

GNU Readline

Table of Contents

readline_add_history ......................................................................................................................... 3102

readline_clear_history ....................................................................................................................... 3103

readline_completion_function ............................................................................................................ 3104

readline_info ................................................................................................................................... 3105

readline_list_history ......................................................................................................................... 3106

readline_read_history ........................................................................................................................ 3107

readline_write_history ...................................................................................................................... 3108

readline .......................................................................................................................................... 3109

3100

Introduction

The readline() functions implement an interface to the GNU Readline library. These are functions that provide editable

command lines. An example being the way Bash allows you to use the arrow keys to insert characters or scroll through

command history. Because of the interactive nature of this library, it will be of little use for writing Web applications, but

may be useful when writing scripts meant using PHP from the command line.

Note: This extension is not available on Windows platforms.

Requirements

To use the readline functions, you need to install libreadline. You can find libreadline on the home page of the GNU Read-

line project, at http://cnswww.cns.cwru.edu/~chet/readline/rltop.html. It's maintained by Chet Ramey, who's also the author

of Bash.

You can also use this functions with the libedit library, a non-GPL replacement for the readline library. The libedit library is

BSD licensend and available for download from http://sourceforge.net/projects/libedit/ [http://cnswww.cns.cwru.edu/~chet/

readline/rltop.html].

Installation

To use this functions you must compile the CGI or CLI version of PHP with readline support. You need to configure PHP -

-with-readline[=DIR]. In order you want to use the libedit readline replacement, configure PHP -

-with-libedit[=DIR].

Runtime Configuration

This extension has no configuration directives defined in php.ini.

Resource Types

This extension has no resource types defined.

Predefined Constants

This extension has no constants defined.

3101

readline_add_history

(PHP 4 )

readline_add_history - Adds a line to the history

Description

void readline_add_history (string line)

This function adds a line to the command line history.

3102

readline_clear_history

(PHP 4 )

readline_clear_history - Clears the history

Description

bool readline_clear_history (void)

This function clears the entire command line history.

3103

readline_completion_function

(PHP 4 )

readline_completion_function - Registers a completion function

Description

bool readline_completion_function (string line)

This function registers a completion function. You must supply the name of an existing function which accepts a partial

command line and returns an array of possible matches. This is the same kind of functionality you'd get if you hit your tab

key while using Bash.

3104

readline_info

(PHP 4 )

readline_info - Gets/sets various internal readline variables

Description

mixed readline_info ([string varname [, string newvalue]])

If called with no parameters, this function returns an array of values for all the setting readline uses. The elements will be in-

dexed by the following values: done, end, erase_empty_line, library_version, line_buffer, mark, pending_input, point,

prompt, readline_name, and terminal_name.

If called with one parameter, the value of that setting is returned. If called with two parameters, the setting will be changed

to the given value.

3105

readline_list_history

(PHP 4 )

readline_list_history - Lists the history

Description

array readline_list_history (void)

This function returns an array of the entire command line history. The elements are indexed by integers starting at zero.

3106

readline_read_history

(PHP 4 )

readline_read_history - Reads the history

Description

bool readline_read_history (string filename)

This function reads a command history from a file.

3107

readline_write_history

(PHP 4 )

readline_write_history - Writes the history

Description

bool readline_write_history (string filename)

This function writes the command history to a file.

3108

readline

(PHP 4 )

readline - Reads a line

Description

string readline ([string prompt])

This function returns a single string from the user. You may specify a string with which to prompt the user. The line re-

turned has the ending newline removed. You must add this line to the history yourself using readline_add_history().

Example 723. readline()

//get 3 commands from user

for ($i=0; $i < 3; $i++) {

$line = readline ("Command: ");

readline_add_history ($line);

}

//dump history

print_r (readline_list_history());

//dump variables

print_r (readline_info());

3109

GNU Recode functions

Table of Contents

recode_file ...................................................................................................................................... 3112

recode_string ................................................................................................................................... 3113

recode ............................................................................................................................................ 3114

3110

Introduction

This module contains an interface to the GNU Recode library, version 3.5. The GNU Recode library converts files between

various coded character sets and surface encodings. When this cannot be achieved exactly, it may get rid of the offending

characters or fall back on approximations. The library recognises or produces nearly 150 different character sets and is able

to convert files between almost any pair. Most RFC 1345 [http://www.faqs.org/rfcs/rfc1345] character sets are supported.

Note: This extension is not available on Windows platforms.

Requirements

You must have GNU Recode 3.5 or higher installed on your system. You can download the package from here [http://

www.gnu.org/directory/All_GNU_Packages/recode.html].

Installation

To be able to use the functions defined in this module you must compile your PHP interpreter using the -

-with-recode[=DIR] option.

Warning

Crashes and startup problems of PHP may be encountered when loading the recode as extension after loading any

extension of mysql or imap. Loading the recode before those extension has proven to fix the problem. This is due a

technical problem that both the c-client library used by imap and recode have their own hash_lookup() function

and both mysql and recode have their own hash_insert function.

Warning

The IMAP extension cannot be used in conjuction with the recode or YAZ extensions. This is due to the fact that

they both share the same internal symbol.

Runtime Configuration

This extension has no configuration directives defined in php.ini.

Resource Types

This extension has no resource types defined.

Predefined Constants

This extension has no constants defined.

3111

recode_file

(PHP 3>= 3.0.13, PHP 4 )

recode_file - Recode from file to file according to recode request

Description

bool recode_file (string request, resource input, resource output)

Recode the file referenced by file handle input into the file referenced by file handle output according to the recode request.

Returns FALSE, if unable to comply, TRUE otherwise.

This function does not currently process filehandles referencing remote files (URLs). Both filehandles must refer to local

files.

Example 724. Basic recode_file() example

$input = fopen ('input.txt', 'r');

$output = fopen ('output.txt', 'w');

recode_file ("us..flat", $input, $output);

3112

recode_string

(PHP 3>= 3.0.13, PHP 4 )

recode_string - Recode a string according to a recode request

Description

string recode_string (string request, string string)

Recode the string string according to the recode request request. Returns the recoded string or FALSE, if unable to perform

the recode request.

A simple recode request may be "lat1..iso646-de". See also the GNU Recode documentation of your installation for detailed

instructions about recode requests.

Example 725. Basic recode_string() example:

print recode_string ("us..flat", "The following character has a diacritical mark: á");

3113

recode

(PHP 4 )

recode - Alias for recode_string()

Description

This function is an alias of recode_string().

3114

Regular Expression Functions

(Perl-Compatible)

Table of Contents

Pattern Modifiers ............................................................................................................................. 3118

Pattern Syntax ................................................................................................................................. 3120

preg_grep ....................................................................................................................................... 3142

preg_match_all ................................................................................................................................ 3143

preg_match ..................................................................................................................................... 3145

preg_quote ...................................................................................................................................... 3147

preg_replace_callback ....................................................................................................................... 3148

preg_replace ................................................................................................................................... 3150

preg_split ....................................................................................................................................... 3153

3115

Introduction

The syntax for patterns used in these functions closely resembles Perl. The expression should be enclosed in the delimiters,

a forward slash (/), for example. Any character can be used for delimiter as long as it's not alphanumeric or backslash (\). If

the delimiter character has to be used in the expression itself, it needs to be escaped by backslash. Since PHP 4.0.4, you can

also use Perl-style (), {}, [], and <> matching delimiters.

The ending delimiter may be followed by various modifiers that affect the matching. See Pattern Modifiers.

PHP also supports regular expressions using a POSIX-extended syntax using the POSIX-extended regex functions..

Requirements

Regular expression support is provided by the PCRE library package, which is open source software, written by Philip

Hazel, and copyright by the University of Cambridge, England. It is available at ftp://ftp.csx.cam.ac.uk/pub/software/pro-

gramming/pcre/.

Installation

Beginning with PHP 4.2.0 these functions are enabled by default. You can disable the pcre functions with -

-without-pcre-regex. Use --with-pcre-regex=DIR to specify DIR where PCRE's include and library files are loc-

ated, if not using bundled library. For older versions you have to configure and compile PHP with -

-with-pcre-regex[=DIR] in order to use these functions.

The windows version of PHP has built in support for this extension. You do not need to load any additional extension in or-

der to use these functions.

Runtime Configuration

This extension has no configuration directives defined in php.ini.

Resource Types

This extension has no resource types defined.

Predefined Constants

The constants below are defined by this extension, and will only be available when the extension has either been compiled

into PHP or dynamically loaded at runtime.

Table 139. PREG constants

constant description

PREG_PATTERN_ORDER Orders results so that $matches[0] is an array of full pattern

matches, $matches[1] is an array of strings matched by the

first parenthesized subpattern, and so on. This flag is only

used with preg_match_all().

PREG_SET_ORDER Orders results so that $matches[0] is an array of first set of

matches, $matches[1] is an array of second set of matches,

and so on. This flag is only used with preg_match_all().

PREG_OFFSET_CAPTURE See the description of PREG_SPLIT_OFFSET_CAPTURE.

This flag is available since PHP 4.3.0 .

3116

constant description

PREG_SPLIT_NO_EMPTY This flag tells preg_split() to only return only non-empty

pieces.

PREG_SPLIT_DELIM_CAPTURE This flag tells preg_split() to capture parenthesized expres-

sion in the delimiter pattern as well. This flag is available

since PHP 4.0.5 .

PREG_SPLIT_OFFSET_CAPTURE If this flag is set, for every occuring match the appendant

string offset will also be returned. Note that this changes the

return value in an array where very element is an array con-

sisting of the matched string at offset 0 and it's string offset

into subject at offset 1. This flag is available since PHP 4.3.0

and is only used for preg_split().

Examples

Example 726. Examples of valid patterns

•/<\/\w+>/

•|(\d{3})-\d+|Sm

•/^(?i)php[34]/

•{^\s+(\s+)?$}

Example 727. Examples of invalid patterns

•/href='(.*)' - missing ending delimiter

•/\w+\s*\w+/J - unknown modifier 'J'

•1-\d3-\d3-\d4| - missing starting delimiter

Regular Expression Functions

(Perl-Compatible)

3117

Pattern Modifiers

()

Pattern Modifiers - Describes possible modifiers in regex patterns

Description

The current possible PCRE modifiers are listed below. The names in parentheses refer to internal PCRE names for these

modifiers.

i(PCRE_CASELESS)

If this modifier is set, letters in the pattern match both upper and lower case letters.

m(PCRE_MULTILINE)

By default, PCRE treats the subject string as consisting of a single "line" of characters (even if it actually con-

tains several newlines). The "start of line" metacharacter (^) matches only at the start of the string, while the

"end of line" metacharacter ($) matches only at the end of the string, or before a terminating newline (unless D

modifier is set). This is the same as Perl.

When this modifier is set, the "start of line" and "end of line" constructs match immediately following or im-

mediately before any newline in the subject string, respectively, as well as at the very start and end. This is

equivalent to Perl's /m modifier. If there are no "\n" characters in a subject string, or no occurrences of ^ or $

in a pattern, setting this modifier has no effect.

s(PCRE_DOTALL)

If this modifier is set, a dot metacharacter in the pattern matches all characters, including newlines. Without it,

newlines are excluded. This modifier is equivalent to Perl's /s modifier. A negative class such as [^a] always

matches a newline character, independent of the setting of this modifier.

x(PCRE_EXTENDED)

If this modifier is set, whitespace data characters in the pattern are totally ignored except when escaped or in-

side a character class, and characters between an unescaped # outside a character class and the next newline

character, inclusive, are also ignored. This is equivalent to Perl's /x modifier, and makes it possible to include

comments inside complicated patterns. Note, however, that this applies only to data characters. Whitespace

characters may never appear within special character sequences in a pattern, for example within the sequence

(?( which introduces a conditional subpattern.

If this modifier is set, preg_replace() does normal substitution of backreferences in the replacement string,

evaluates it as PHP code, and uses the result for replacing the search string.

Only preg_replace() uses this modifier; it is ignored by other PCRE functions.

Note: This modifier was not available in PHP3.

A(PCRE_ANCHORED)

If this modifier is set, the pattern is forced to be "anchored", that is, it is constrained to match only at the start

of the string which is being searched (the "subject string"). This effect can also be achieved by appropriate

constructs in the pattern itself, which is the only way to do it in Perl.

D(PCRE_DOLLAR_ENDONLY)

If this modifier is set, a dollar metacharacter in the pattern matches only at the end of the subject string.

Without this modifier, a dollar also matches immediately before the final character if it is a newline (but not

3118

before any other newlines). This modifier is ignored if mmodifier is set. There is no equivalent to this modifi-

er in Perl.

When a pattern is going to be used several times, it is worth spending more time analyzing it in order to speed

up the time taken for matching. If this modifier is set, then this extra analysis is performed. At present, study-

ing a pattern is useful only for non-anchored patterns that do not have a single fixed starting character.

U(PCRE_UNGREEDY)

This modifier inverts the "greediness" of the quantifiers so that they are not greedy by default, but become

greedy if followed by "?". It is not compatible with Perl. It can also be set by a (?U) modifier setting within the

pattern.

X(PCRE_EXTRA)

This modifier turns on additional functionality of PCRE that is incompatible with Perl. Any backslash in a pat-

tern that is followed by a letter that has no special meaning causes an error, thus reserving these combinations

for future expansion. By default, as in Perl, a backslash followed by a letter with no special meaning is treated

as a literal. There are at present no other features controlled by this modifier.

u(PCRE_UTF8)

This modifier turns on additional functionality of PCRE that is incompatible with Perl. Pattern strings are

treated as UTF-8. This modifier is available from PHP 4.1.0 or greater on Unix and from PHP 4.2.3 on win32.

Pattern Modifiers

3119

Pattern Syntax

()

Pattern Syntax - Describes PCRE regex syntax

Description

The PCRE library is a set of functions that implement regular expression pattern matching using the same syntax and se-

mantics as Perl 5, with just a few differences (see below). The current implementation corresponds to Perl 5.005.

Differences From Perl

The differences described here are with respect to Perl 5.005.

1. By default, a whitespace character is any character that the C library function isspace() recognizes, though it is possible

to compile PCRE with alternative character type tables. Normally isspace() matches space, formfeed, newline, carriage

return, horizontal tab, and vertical tab. Perl 5 no longer includes vertical tab in its set of whitespace characters. The \v

escape that was in the Perl documentation for a long time was never in fact recognized. However, the character itself

was treated as whitespace at least up to 5.002. In 5.004 and 5.005 it does not match \s.

2. PCRE does not allow repeat quantifiers on lookahead assertions. Perl permits them, but they do not mean what you

might think. For example, (?!a){3} does not assert that the next three characters are not "a". It just asserts that the next

character is not "a" three times.

3. Capturing subpatterns that occur inside negative looka- head assertions are counted, but their entries in the offsets vec-

tor are never set. Perl sets its numerical vari- ables from any such patterns that are matched before the assertion fails to

match something (thereby succeeding), but only if the negative lookahead assertion contains just one branch.

4. Though binary zero characters are supported in the subject string, they are not allowed in a pattern string because it is

passed as a normal C string, terminated by zero. The escape sequence "\\x00" can be used in the pattern to represent a

binary zero.

5. The following Perl escape sequences are not supported: \l, \u, \L, \U, \E, \Q. In fact these are implemented by Perl's

general string-handling and are not part of its pat- tern matching engine.

6. The Perl \G assertion is not supported as it is not relevant to single pattern matches.

7. Fairly obviously, PCRE does not support the (?{code}) construction.

8. There are at the time of writing some oddities in Perl 5.005_02 concerned with the settings of captured strings when

part of a pattern is repeated. For example, matching "aba" against the pattern /^(a(b)?)+$/ sets $2 to the value "b", but

matching "aabbaa" against /^(aa(bb)?)+$/ leaves $2 unset. However, if the pattern is changed to /^(aa(b(b))?)+$/ then

$2 (and $3) get set. In Perl 5.004 $2 is set in both cases, and that is also TRUE of PCRE. If in the future Perl changes to

a consistent state that is different, PCRE may change to follow.

9. Another as yet unresolved discrepancy is that in Perl 5.005_02 the pattern /^(a)?(?(1)a|b)+$/ matches the string "a",

whereas in PCRE it does not. However, in both Perl and PCRE /^(a)?a/ matched against "a" leaves $1 unset.

10. PCRE provides some extensions to the Perl regular expression facilities:

3120

a. Although lookbehind assertions must match fixed length strings, each alternative branch of a lookbehind assertion

can match a different length of string. Perl 5.005 requires them all to have the same length.

b. If PCRE_DOLLAR_ENDONLY is set and PCRE_MULTILINE is not set, the $ meta- character matches only at

the very end of the string.

c. If PCRE_EXTRA is set, a backslash followed by a letter with no special meaning is faulted.

d. If PCRE_UNGREEDY is set, the greediness of the repeti- tion quantifiers is inverted, that is, by default they are

not greedy, but if followed by a question mark they are.

Regular Expression Details

Introduction

The syntax and semantics of the regular expressions sup- ported by PCRE are described below. Regular expressions are also

described in the Perl documentation and in a number of other books, some of which have copious examples. Jeffrey Friedl's

"Mastering Regular Expressions", published by O'Reilly (ISBN 1-56592-257-3), covers them in great detail. The descrip-

tion here is intended as reference documentation. A regular expression is a pattern that is matched against a subject string

from left to right. Most characters stand for themselves in a pattern, and match the corresponding charac- ters in the subject.

As a trivial example, the pattern The quick brown fox matches a portion of a subject string that is identical to itself.

Meta-characters

The power of regular expressions comes from the ability to include alternatives and repetitions in the pat- tern. These are

encoded in the pattern by the use of meta-characters, which do not stand for themselves but instead are interpreted in some

special way.

There are two different sets of meta-characters: those that are recognized anywhere in the pattern except within square

brackets, and those that are recognized in square brackets. Outside square brackets, the meta-characters are as follows:

\general escape character with several uses

^assert start of subject (or line, in multiline mode)

$assert end of subject (or line, in multiline mode)

.match any character except newline (by default)

[start character class definition

]end character class definition

|start of alternative branch

Pattern Syntax

3121

(start subpattern

)end subpattern

?extends the meaning of (, also 0 or 1 quantifier, also quantifier minimizer

*0 or more quantifier

+1 or more quantifier

{start min/max quantifier

}end min/max quantifier

Part of a pattern that is in square brackets is called a "character class". In a character class the only meta- characters are:

\general escape character

^negate the class, but only if the first character

-indicates character range

]terminates the character class

The following sections describe the use of each of the meta-characters.

backslash

The backslash character has several uses. Firstly, if it is followed by a non-alphanumeric character, it takes away any special

meaning that character may have. This use of backslash as an escape character applies both inside and outside character

classes.

For example, if you want to match a "*" character, you write "\*" in the pattern. This applies whether or not the follow- ing

character would otherwise be interpreted as a meta- character, so it is always safe to precede a non-alphanumeric with "\" to

specify that it stands for itself. In particu- lar, if you want to match a backslash, you write "\\".

If a pattern is compiled with the PCRE_EXTENDED option, whi- tespace in the pattern (other than in a character class) and

characters between a "#" outside a character class and the next newline character are ignored. An escaping backslash can be

used to include a whitespace or "#" character as part of the pattern.

A second use of backslash provides a way of encoding non- printing characters in patterns in a visible manner. There is no

restriction on the appearance of non-printing characters, apart from the binary zero that terminates a pattern, but when a pat-

tern is being prepared by text editing, it is usually easier to use one of the following escape sequences than the binary char-

acter it represents:

Pattern Syntax

3122

\a alarm, that is, the BEL character (hex 07)

\cx "control-x", where x is any character

\e escape (hex 1B)

\f formfeed (hex 0C)

\n newline (hex 0A)

\r carriage return (hex 0D)

\t tab (hex 09)

\xhhcharacter with hex code hh

\dddcharacter with octal code ddd, or backreference

The precise effect of "\cx" is as follows: if "x" is a lower case letter, it is converted to upper case. Then bit 6 of the charac-

ter (hex 40) is inverted. Thus "\cz" becomes hex 1A, but "\c{" becomes hex 3B, while "\c;" becomes hex 7B.

After "\x", up to two hexadecimal digits are read (letters can be in upper or lower case).

After "\0" up to two further octal digits are read. In both cases, if there are fewer than two digits, just those that are present

are used. Thus the sequence "\0\x\07" specifies two binary zeros followed by a BEL character. Make sure you supply two

digits after the initial zero if the character that follows is itself an octal digit.

The handling of a backslash followed by a digit other than 0 is complicated. Outside a character class, PCRE reads it and

any following digits as a decimal number. If the number is less than 10, or if there have been at least that many previous

capturing left parentheses in the expression, the entire sequence is taken as a back reference. A description of how this

works is given later, following the discussion of parenthesized subpatterns.

Inside a character class, or if the decimal number is greater than 9 and there have not been that many capturing subpatterns,

PCRE re-reads up to three octal digits following the backslash, and generates a single byte from the least significant 8 bits

of the value. Any subsequent digits stand for themselves. For example:

\040is another way of writing a space

\40 is the same, provided there are fewer than 40 previous capturing subpatterns

\7 is always a back reference

\11

Pattern Syntax

3123

might be a back reference, or another way of writing a tab

\011is always a tab

\0113

is a tab followed by the character "3"

\113is the character with octal code 113 (since there can be no more than 99 back references)

\377is a byte consisting entirely of 1 bits

\81 is either a back reference, or a binary zero followed by the two characters "8" and "1"

Note that octal values of 100 or greater must not be intro- duced by a leading zero, because no more than three octal digits

are ever read.

All the sequences that define a single byte value can be used both inside and outside character classes. In addition, inside a

character class, the sequence "\b" is interpreted as the backspace character (hex 08). Outside a character class it has a differ-

ent meaning (see below).

The third use of backslash is for specifying generic charac- ter types:

\d any decimal digit

\D any character that is not a decimal digit

\s any whitespace character

\S any character that is not a whitespace character

\w any "word" character

\W any "non-word" character

Each pair of escape sequences partitions the complete set of characters into two disjoint sets. Any given character matches

one, and only one, of each pair.

A "word" character is any letter or digit or the underscore character, that is, any character which can be part of a Perl

"word". The definition of letters and digits is controlled by PCRE's character tables, and may vary if locale-specific match-

ing is taking place (see "Locale support" above). For example, in the "fr" (French) locale, some char- acter codes greater

than 128 are used for accented letters, and these are matched by \w.

These character type sequences can appear both inside and outside character classes. They each match one character of the

appropriate type. If the current matching point is at the end of the subject string, all of them fail, since there is no character

to match.

Pattern Syntax

3124

The fourth use of backslash is for certain simple asser- tions. An assertion specifies a condition that has to be met at a partic-

ular point in a match, without consuming any characters from the subject string. The use of subpatterns for more complic-

ated assertions is described below. The backslashed assertions are

\b word boundary

\B not a word boundary

\A start of subject (independent of multiline mode)

\Z end of subject or newline at end (independent of multiline mode)

\z end of subject(independent of multiline mode)

These assertions may not appear in character classes (but note that "\b" has a different meaning, namely the backspace

character, inside a character class).

A word boundary is a position in the subject string where the current character and the previous character do not both match

\w or \W (i.e. one matches \w and the other matches \W), or the start or end of the string if the first or last character matches

\w, respectively.

The \A,\Z, and \z assertions differ from the traditional circumflex and dollar (described below) in that they only ever

match at the very start and end of the subject string, whatever options are set. They are not affected by the PCRE_NOTBOL

or PCRE_NOTEOL options. The difference between \Z and \z is that \Z matches before a newline that is the last character

of the string as well as at the end of the string, whereas \z matches only at the end.

Circumflex and dollar

Outside a character class, in the default matching mode, the

circumflex character is an assertion which is true only if

the current matching point is at the start of the subject

string. Inside a character class, circumflex has an entirely

different meaning (see below).

Circumflex need not be the first character of the pattern if

a number of alternatives are involved, but it should be the

first thing in each alternative in which it appears if the

pattern is ever to match that branch. If all possible alter-

natives start with a circumflex, that is, if the pattern is

constrained to match only at the start of the subject, it is

said to be an "anchored" pattern. (There are also other con-

structs that can cause a pattern to be anchored.)

A dollar character is an assertion which is TRUE only if the

current matching point is at the end of the subject string,

or immediately before a newline character that is the last

character in the string (by default). Dollar need not be the

last character of the pattern if a number of alternatives

are involved, but it should be the last item in any branch

Pattern Syntax

3125

in which it appears. Dollar has no special meaning in a

character class.

The meaning of dollar can be changed so that it matches only

at the very end of the string, by setting the

PCRE_DOLLAR_ENDONLY

option at compile or matching time. This

does not affect the \Z assertion.

The meanings of the circumflex and dollar characters are

changed if the PCRE_MULTILINE option is set. When this is

the case, they match immediately after and immediately

before an internal "\n" character, respectively, in addition

to matching at the start and end of the subject string. For

example, the pattern /^abc$/ matches the subject string

"def\nabc" in multiline mode, but not otherwise. Conse-

quently, patterns that are anchored in single line mode

because all branches start with "^" are not anchored in mul-

tiline mode. The PCRE_DOLLAR_ENDONLY option is ignored if

PCRE_MULTILINE is set.

Note that the sequences \A, \Z, and \z can be used to match

the start and end of the subject in both modes, and if all

branches of a pattern start with \A is it always anchored,

whether PCRE_MULTILINE is set or not.

FULL STOP

Outside a character class, a dot in the pattern matches any

one character in the subject, including a non-printing

character, but not (by default) newline. If the PCRE_DOTALL

option is set, then dots match newlines as well. The han-

dling of dot is entirely independent of the handling of cir-

cumflex and dollar, the only relationship being that they

both involve newline characters. Dot has no special meaning

in a character class.

Square brackets

An opening square bracket introduces a character class, ter-

minated by a closing square bracket. A closing square

bracket on its own is not special. If a closing square

bracket is required as a member of the class, it should be

the first data character in the class (after an initial cir-

cumflex, if present) or escaped with a backslash.

A character class matches a single character in the subject;

the character must be in the set of characters defined by

the class, unless the first character in the class is a cir-

cumflex, in which case the subject character must not be in

the set defined by the class. If a circumflex is actually

Pattern Syntax

3126

required as a member of the class, ensure it is not the

first character, or escape it with a backslash.

For example, the character class [aeiou] matches any lower

case vowel, while [^aeiou] matches any character that is not

a lower case vowel. Note that a circumflex is just a con-

venient notation for specifying the characters which are in

the class by enumerating those that are not. It is not an

assertion: it still consumes a character from the subject

string, and fails if the current pointer is at the end of

the string.

When caseless matching is set, any letters in a class

represent both their upper case and lower case versions, so

for example, a caseless [aeiou] matches "A" as well as "a",

and a caseless [^aeiou] does not match "A", whereas a case-

ful version would.

The newline character is never treated in any special way in

character classes, whatever the setting of the PCRE_DOTALL

or PCRE_MULTILINE options is. A class such as [^a] will

always match a newline.

The minus (hyphen) character can be used to specify a range

of characters in a character class. For example, [d-m]

matches any letter between d and m, inclusive. If a minus

character is required in a class, it must be escaped with a

backslash or appear in a position where it cannot be inter-

preted as indicating a range, typically as the first or last

character in the class.

It is not possible to have the literal character "]" as the

end character of a range. A pattern such as [W-]46] is

interpreted as a class of two characters ("W" and "-") fol-

lowed by a literal string "46]", so it would match "W46]" or

"-46]". However, if the "]" is escaped with a backslash it

is interpreted as the end of range, so [W-\]46] is inter-

preted as a single class containing a range followed by two

separate characters. The octal or hexadecimal representation

of "]" can also be used to end a range.

Ranges operate in ASCII collating sequence. They can also be

used for characters specified numerically, for example

[\000-\037]. If a range that includes letters is used when

caseless matching is set, it matches the letters in either

case. For example, [W-c] is equivalent to [][\^_`wxyzabc],

matched caselessly, and if character tables for the "fr"

locale are in use, [\xc8-\xcb] matches accented E characters

in both cases.

The character types \d, \D, \s, \S, \w, and \W may also

appear in a character class, and add the characters that

they match to the class. For example, [\dABCDEF] matches any

hexadecimal digit. A circumflex can conveniently be used

with the upper case character types to specify a more res-

tricted set of characters than the matching lower case type.

For example, the class [^\W_] matches any letter or digit,

Pattern Syntax

3127

but not underscore.

All non-alphanumeric characters other than \, -, ^ (at the

start) and the terminating ] are non-special in character

classes, but it does no harm if they are escaped.

Vertical bar

Vertical bar characters are used to separate alternative

patterns. For example, the pattern

gilbert|sullivan

matches either "gilbert" or "sullivan". Any number of alternatives

may appear, and an empty alternative is permitted

(matching the empty string). The matching process tries

each alternative in turn, from left to right, and the first

one that succeeds is used. If the alternatives are within a

subpattern (defined below), "succeeds" means matching the

rest of the main pattern as well as the alternative in the

subpattern.

Internal option setting

The settings of PCRE_CASELESS ,

PCRE_MULTILINE ,

PCRE_DOTALL ,

and PCRE_EXTENDED can be changed from within the pattern by

a sequence of Perl option letters enclosed between "(?" and

")". The option letters are

i for PCRE_CASELESS

m for PCRE_MULTILINE

s for PCRE_DOTALL

x for PCRE_EXTENDED

For example, (?im) sets caseless, multiline matching. It is

also possible to unset these options by preceding the letter

with a hyphen, and a combined setting and unsetting such as

(?im-sx), which sets PCRE_CASELESS and PCRE_MULTILINE while

unsetting PCRE_DOTALL and PCRE_EXTENDED , is also permitted.

If a letter appears both before and after the hyphen, the

option is unset.

The scope of these option changes depends on where in the

pattern the setting occurs. For settings that are outside

any subpattern (defined below), the effect is the same as if

the options were set or unset at the start of matching. The

following patterns all behave in exactly the same way:

(?i)abc

Pattern Syntax

3128

a(?i)bc

ab(?i)c

abc(?i)

which in turn is the same as compiling the pattern abc with

PCRE_CASELESS set.

In other words, such "top level" settings apply to the whole

pattern (unless there are other changes inside subpatterns).

If there is more than one setting of the same option at top level,

the rightmost setting is used.

If an option change occurs inside a subpattern, the effect

is different. This is a change of behaviour in Perl 5.005.

An option change inside a subpattern affects only that part

of the subpattern that follows it, so

(a(?i)b)c

matches abc and aBc and no other strings (assuming

PCRE_CASELESS is not used). By this means, options can be

made to have different settings in different parts of the

pattern. Any changes made in one alternative do carry on

into subsequent branches within the same subpattern. For

example,

(a(?i)b|c)

matches "ab", "aB", "c", and "C", even though when matching

"C" the first branch is abandoned before the option setting.

This is because the effects of option settings happen at

compile time. There would be some very weird behaviour otherwise.

The PCRE-specific options PCRE_UNGREEDY and

PCRE_EXTRA can

be changed in the same way as the Perl-compatible options by

using the characters U and X respectively. The (?X) flag

setting is special in that it must always occur earlier in

the pattern than any of the additional features it turns on,

even when it is at top level. It is best put at the start.

subpatterns

Subpatterns are delimited by parentheses (round brackets),

which can be nested. Marking part of a pattern as a subpattern

does two things:

1. It localizes a set of alternatives. For example, the pat-

tern

cat(aract|erpillar|)

matches one of the words "cat", "cataract", or "caterpillar".

Without the parentheses, it would match "cataract",

"erpillar" or the empty string.

Pattern Syntax

3129

2. It sets up the subpattern as a capturing subpattern (as

defined above). When the whole pattern matches, that portion

of the subject string that matched the subpattern is

passed back to the caller via the ovector

argument of

pcre_exec(). Opening parentheses are counted

from left to right (starting from 1) to obtain the numbers of the

capturing subpatterns.

For example, if the string "the red king" is matched against

the pattern

the ((red|white) (king|queen))

the captured substrings are "red king", "red", and "king",

and are numbered 1, 2, and 3.

The fact that plain parentheses fulfil two functions is not

always helpful. There are often times when a grouping subpattern

is required without a capturing requirement. If an

opening parenthesis is followed by "?:", the subpattern does

not do any capturing, and is not counted when computing the

number of any subsequent capturing subpatterns. For example,

if the string "the white queen" is matched against the

pattern

the ((?:red|white) (king|queen))

the captured substrings are "white queen" and "queen", and

are numbered 1 and 2. The maximum number of captured substrings

is 99, and the maximum number of all subpatterns,

both capturing and non-capturing, is 200.

As a convenient shorthand, if any option settings are

required at the start of a non-capturing subpattern, the

option letters may appear between the "?" and the ":". Thus

the two patterns

(?i:saturday|sunday)

(?:(?i)saturday|sunday)

match exactly the same set of strings. Because alternative

branches are tried from left to right, and options are not

reset until the end of the subpattern is reached, an option

setting in one branch does affect subsequent branches, so

the above patterns match "SUNDAY" as well as "Saturday".

Repetition

Repetition is specified by quantifiers, which can follow any

of the following items:

a single character, possibly escaped

the . metacharacter

Pattern Syntax

3130

a character class

a back reference (see next section)

a parenthesized subpattern (unless it is an assertion -

see below)

The general repetition quantifier specifies a minimum and

maximum number of permitted matches, by giving the two

numbers in curly brackets (braces), separated by a comma.

The numbers must be less than 65536, and the first must be

less than or equal to the second. For example:

z{2,4}

matches "zz", "zzz", or "zzzz". A closing brace on its own

is not a special character. If the second number is omitted,

but the comma is present, there is no upper limit; if the

second number and the comma are both omitted, the quantifier

specifies an exact number of required matches. Thus

[aeiou]{3,}

matches at least 3 successive vowels, but may match many

more, while

\d{8}

matches exactly 8 digits. An opening curly bracket that

appears in a position where a quantifier is not allowed, or

one that does not match the syntax of a quantifier, is taken

as a literal character. For example, {,6} is not a quantifier,

but a literal string of four characters.

The quantifier {0} is permitted, causing the expression to

behave as if the previous item and the quantifier were not

present.

For convenience (and historical compatibility) the three

most common quantifiers have single-character abbreviations:

* is equivalent to {0,}

+ is equivalent to {1,}

? is equivalent to {0,1}

It is possible to construct infinite loops by following a

subpattern that can match no characters with a quantifier

that has no upper limit, for example:

(a?)*

Earlier versions of Perl and PCRE used to give an error at

compile time for such patterns. However, because there are

cases where this can be useful, such patterns are now

accepted, but if any repetition of the subpattern does in

fact match no characters, the loop is forcibly broken.

By default, the quantifiers are "greedy", that is, they

match as much as possible (up to the maximum number of permitted

Pattern Syntax

3131

times), without causing the rest of the pattern to

fail. The classic example of where this gives problems is in

trying to match comments in C programs. These appear between

the sequences /* and */ and within the sequence, individual

* and / characters may appear. An attempt to match C comments

by applying the pattern

/\*.*\*/

to the string

/* first command */ not comment /* second comment */

fails, because it matches the entire string due to the

greediness of the .* item.

However, if a quantifier is followed by a question mark,

then it ceases to be greedy, and instead matches the minimum

number of times possible, so the pattern

/\*.*?\*/

does the right thing with the C comments. The meaning of the

various quantifiers is not otherwise changed, just the preferred

number of matches. Do not confuse this use of ques-

tion mark with its use as a quantifier in its own right.

Because it has two uses, it can sometimes appear doubled, as

\d??\d

which matches one digit by preference, but can match two if

that is the only way the rest of the pattern matches.

If the PCRE_UNGREEDY option is set (an option which is not

available in Perl) then the quantifiers are not greedy by

default, but individual ones can be made greedy by following

them with a question mark. In other words, it inverts the

default behaviour.

When a parenthesized subpattern is quantified with a minimum

repeat count that is greater than 1 or with a limited maximum,

more store is required for the compiled pattern, in

proportion to the size of the minimum or maximum.

If a pattern starts with .* or .{0,} and the PCRE_DOTALL

option (equivalent to Perl's /s) is set, thus allowing the .

to match newlines, then the pattern is implicitly anchored,

because whatever follows will be tried against every character

position in the subject string, so there is no point in

retrying the overall match at any position after the first.

PCRE treats such a pattern as though it were preceded by \A.

In cases where it is known that the subject string contains

no newlines, it is worth setting PCRE_DOTALL when the pattern begins with .* in order to

obtain this optimization, or

alternatively using ^ to indicate anchoring explicitly.

Pattern Syntax

3132

When a capturing subpattern is repeated, the value captured

is the substring that matched the final iteration. For example, after

(tweedle[dume]{3}\s*)+

has matched "tweedledum tweedledee" the value of the captured

substring is "tweedledee". However, if there are

nested capturing subpatterns, the corresponding captured

values may have been set in previous iterations. For example,

after

/(a|(b))+/

matches "aba" the value of the second captured substring is

"b".

BACK REFERENCES

Outside a character class, a backslash followed by a digit

greater than 0 (and possibly further digits) is a back

reference to a capturing subpattern earlier (i.e. to its

left) in the pattern, provided there have been that many

previous capturing left parentheses.

However, if the decimal number following the backslash is

less than 10, it is always taken as a back reference, and

causes an error only if there are not that many capturing

left parentheses in the entire pattern. In other words, the

parentheses that are referenced need not be to the left of

the reference for numbers less than 10. See the section

entitled "Backslash" above for further details of the handling

of digits following a backslash.

A back reference matches whatever actually matched the capturing

subpattern in the current subject string, rather than

anything matching the subpattern itself. So the pattern

(sens|respons)e and \1ibility

matches "sense and sensibility" and "response and responsibility",

but not "sense and responsibility". If caseful

matching is in force at the time of the back reference, then

the case of letters is relevant. For example,

((?i)rah)\s+\1

matches "rah rah" and "RAH RAH", but not "RAH rah", even

though the original capturing subpattern is matched caselessly.

There may be more than one back reference to the same subpattern.

If a subpattern has not actually been used in a

particular match, then any back references to it always

fail. For example, the pattern

(a|(bc))\2

Pattern Syntax

3133

always fails if it starts to match "a" rather than "bc".

Because there may be up to 99 back references, all digits

following the backslash are taken as part of a potential

back reference number. If the pattern continues with a digit

character, then some delimiter must be used to terminate the

back reference. If the PCRE_EXTENDED option is set, this can

be whitespace. Otherwise an empty comment can be used.

A back reference that occurs inside the parentheses to which

it refers fails when the subpattern is first used, so, for

example, (a\1) never matches. However, such references can

be useful inside repeated subpatterns. For example, the pattern

(a|b\1)+

matches any number of "a"s and also "aba", "ababaa" etc. At

each iteration of the subpattern, the back reference matches

the character string corresponding to the previous iteration.

In order for this to work, the pattern must be such

that the first iteration does not need to match the back

reference. This can be done using alternation, as in the

example above, or by a quantifier with a minimum of zero.

Assertions

An assertion is a test on the characters following or

preceding the current matching point that does not actually

consume any characters. The simple assertions coded as \b,

\B, \A, \Z, \z, ^ and $ are described above. More complicated

assertions are coded as subpatterns. There are two

kinds: those that look ahead of the current position in the

subject string, and those that look behind it.

An assertion subpattern is matched in the normal way, except

that it does not cause the current matching position to be

changed. Lookahead assertions start with (?= for positive

assertions and (?! for negative assertions. For example,

\w+(?=;)

matches a word followed by a semicolon, but does not include

the semicolon in the match, and

foo(?!bar)

matches any occurrence of "foo" that is not followed by

"bar". Note that the apparently similar pattern

(?!foo)bar

does not find an occurrence of "bar" that is preceded by

something other than "foo"; it finds any occurrence of "bar"

whatsoever, because the assertion (?!foo) is always TRUE

Pattern Syntax

3134

when the next three characters are "bar". A lookbehind

assertion is needed to achieve this effect.

Lookbehind assertions start with (?<= for positive assertions

and (?<! for negative assertions. For example,

(?<!foo)bar

does find an occurrence of "bar" that is not preceded by

"foo". The contents of a lookbehind assertion are restricted

such that all the strings it matches must have a fixed

length. However, if there are several alternatives, they do

not all have to have the same fixed length. Thus

(?<=bullock|donkey)

is permitted, but

(?<!dogs?|cats?)

causes an error at compile time. Branches that match different

length strings are permitted only at the top level of

a lookbehind assertion. This is an extension compared with

Perl 5.005, which requires all branches to match the same

length of string. An assertion such as

(?<=ab(c|de))

is not permitted, because its single top-level branch can

match two different lengths, but it is acceptable if rewritten

to use two top-level branches:

(?<=abc|abde)

The implementation of lookbehind assertions is, for each

alternative, to temporarily move the current position back

by the fixed width and then try to match. If there are

insufficient characters before the current position, the

match is deemed to fail. Lookbehinds in conjunction with

once-only subpatterns can be particularly useful for matching

at the ends of strings; an example is given at the end

of the section on once-only subpatterns.

Several assertions (of any sort) may occur in succession.

For example,

(?<=\d{3})(?<!999)foo

matches "foo" preceded by three digits that are not "999".

Notice that each of the assertions is applied independently

at the same point in the subject string. First there is a

check that the previous three characters are all digits,

then there is a check that the same three characters are not

"999". This pattern does not match "foo" preceded by six

characters, the first of which are digits and the last three

of which are not "999". For example, it doesn't match

"123abcfoo". A pattern to do that is

Pattern Syntax

3135

(?<=\d{3}...)(?<!999)foo

This time the first assertion looks at the preceding six

characters, checking that the first three are digits, and

then the second assertion checks that the preceding three

characters are not "999".

Assertions can be nested in any combination. For example,

(?<=(?<!foo)bar)baz

matches an occurrence of "baz" that is preceded by "bar"

which in turn is not preceded by "foo", while

(?<=\d{3}(?!999)...)foo

is another pattern which matches "foo" preceded by three

digits and any three characters that are not "999".

Assertion subpatterns are not capturing subpatterns, and may

not be repeated, because it makes no sense to assert the

same thing several times. If any kind of assertion contains

capturing subpatterns within it, these are counted for the

purposes of numbering the capturing subpatterns in the whole

pattern. However, substring capturing is carried out only

for positive assertions, because it does not make sense for

negative assertions.

Assertions count towards the maximum of 200 parenthesized

subpatterns.

Once-only subpatterns

With both maximizing and minimizing repetition, failure of

what follows normally causes the repeated item to be re-

evaluated to see if a different number of repeats allows the

rest of the pattern to match. Sometimes it is useful to

prevent this, either to change the nature of the match, or

to cause it fail earlier than it otherwise might, when the

author of the pattern knows there is no point in carrying

on.

Consider, for example, the pattern \d+foo when applied to

the subject line

123456bar

After matching all 6 digits and then failing to match "foo",

the normal action of the matcher is to try again with only 5

digits matching the \d+ item, and then with 4, and so on,

before ultimately failing. Once-only subpatterns provide the

means for specifying that once a portion of the pattern has

matched, it is not to be re-evaluated in this way, so the

matcher would give up immediately on failing to match "foo"

the first time. The notation is another kind of special

Pattern Syntax

3136

parenthesis, starting with (?> as in this example:

(?>\d+)bar

This kind of parenthesis "locks up" the part of the pattern

it contains once it has matched, and a failure further into

the pattern is prevented from backtracking into it. Back-

tracking past it to previous items, however, works as normal.

An alternative description is that a subpattern of this type

matches the string of characters that an identical standalone

pattern would match, if anchored at the current point

in the subject string.

Once-only subpatterns are not capturing subpatterns. Simple

cases such as the above example can be thought of as a maximizing

repeat that must swallow everything it can. So,

while both \d+ and \d+? are prepared to adjust the number of

digits they match in order to make the rest of the pattern

match, (?>\d+) can only match an entire sequence of digits.

This construction can of course contain arbitrarily complicated

subpatterns, and it can be nested.

Once-only subpatterns can be used in conjunction with look-

behind assertions to specify efficient matching at the end

of the subject string. Consider a simple pattern such as

abcd$

when applied to a long string which does not match. Because

matching proceeds from left to right, PCRE will look for

each "a" in the subject and then see if what follows matches

the rest of the pattern. If the pattern is specified as

^.*abcd$

then the initial .* matches the entire string at first, but

when this fails (because there is no following "a"), it

backtracks to match all but the last character, then all but

the last two characters, and so on. Once again the search

for "a" covers the entire string, from right to left, so we

are no better off. However, if the pattern is written as

^(?>.*)(?<=abcd)

then there can be no backtracking for the .* item; it can

match only the entire string. The subsequent lookbehind

assertion does a single test on the last four characters. If

it fails, the match fails immediately. For long strings,

this approach makes a significant difference to the processing time.

When a pattern contains an unlimited repeat inside a subpattern

that can itself be repeated an unlimited number of

times, the use of a once-only subpattern is the only way to

avoid some failing matches taking a very long time indeed.

The pattern

Pattern Syntax

3137

(\D+|<\d+>)*[!?]

matches an unlimited number of substrings that either consist

of non-digits, or digits enclosed in <>, followed by

either ! or ?. When it matches, it runs quickly. However, if

it is applied to

aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa

it takes a long time before reporting failure. This is

because the string can be divided between the two repeats in

a large number of ways, and all have to be tried. (The example

used [!?] rather than a single character at the end,

because both PCRE and Perl have an optimization that allows

for fast failure when a single character is used. They

remember the last single character that is required for a

match, and fail early if it is not present in the string.)

If the pattern is changed to

((?>\D+)|<\d+>)*[!?]

sequences of non-digits cannot be broken, and failure happens quickly.

Conditional subpatterns

It is possible to cause the matching process to obey a subpattern

conditionally or to choose between two alternative

subpatterns, depending on the result of an assertion, or

whether a previous capturing subpattern matched or not. The

two possible forms of conditional subpattern are

(?(condition)yes-pattern)

(?(condition)yes-pattern|no-pattern)

If the condition is satisfied, the yes-pattern is used; otherwise

the no-pattern (if present) is used. If there are

more than two alternatives in the subpattern, a compile-time

error occurs.

There are two kinds of condition. If the text between the

parentheses consists of a sequence of digits, then the

condition is satisfied if the capturing subpattern of that

number has previously matched. Consider the following pattern,

which contains non-significant white space to make it

more readable (assume the PCRE_EXTENDED option) and to

divide it into three parts for ease of discussion:

( $ )? [^()]+ (?(1) $ )

The first part matches an optional opening parenthesis, and

if that character is present, sets it as the first captured

substring. The second part matches one or more characters

that are not parentheses. The third part is a conditional

Pattern Syntax

3138

subpattern that tests whether the first set of parentheses

matched or not. If they did, that is, if subject started

with an opening parenthesis, the condition is TRUE, and so

the yes-pattern is executed and a closing parenthesis is

required. Otherwise, since no-pattern is not present, the

subpattern matches nothing. In other words, this pattern

matches a sequence of non-parentheses, optionally enclosed

in parentheses.

If the condition is not a sequence of digits, it must be an

assertion. This may be a positive or negative lookahead or

lookbehind assertion. Consider this pattern, again containing

non-significant white space, and with the two alternatives on

the second line:

(?(?=[^a-z]*[a-z])

\d{2}-[a-z]{3}-\d{2} | \d{2}-\d{2}-\d{2} )

The condition is a positive lookahead assertion that matches

an optional sequence of non-letters followed by a letter. In

other words, it tests for the presence of at least one

letter in the subject. If a letter is found, the subject is

matched against the first alternative; otherwise it is

matched against the second. This pattern matches strings in

one of the two forms dd-aaa-dd or dd-dd-dd, where aaa are

letters and dd are digits.

Comments

The sequence (?# marks the start of a comment which

continues up to the next closing parenthesis. Nested

parentheses are not permitted. The characters that make up a

comment play no part in the pattern matching at all.

If the PCRE_EXTENDED option is set, an unescaped # character

outside a character class introduces a comment that contin-

ues up to the next newline character in the pattern.

Recursive patterns

Consider the problem of matching a string in parentheses,

allowing for unlimited nested parentheses. Without the use

of recursion, the best that can be done is to use a pattern

that matches up to some fixed depth of nesting. It is not

possible to handle an arbitrary nesting depth. Perl 5.6 has

provided an experimental facility that allows regular

expressions to recurse (amongst other things). The special

item (?R) is provided for the specific case of recursion.

This PCRE pattern solves the parentheses problem (assume

the PCRE_EXTENDED

option is set so that white space is

Pattern Syntax

3139

ignored):

$ ( (?>[^()]+) | (?R) )* $

First it matches an opening parenthesis. Then it matches any

number of substrings which can either be a sequence of non-

parentheses, or a recursive match of the pattern itself

(i.e. a correctly parenthesized substring). Finally there is

a closing parenthesis.

This particular example pattern contains nested unlimited

repeats, and so the use of a once-only subpattern for matching

strings of non-parentheses is important when applying

the pattern to strings that do not match. For example, when

it is applied to

(aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa()

it yields "no match" quickly. However, if a once-only subpattern

is not used, the match runs for a very long time

indeed because there are so many different ways the + and *

repeats can carve up the subject, and all have to be tested

before failure can be reported.

The values set for any capturing subpatterns are those from

the outermost level of the recursion at which the subpattern

value is set. If the pattern above is matched against

(ab(cd)ef)

the value for the capturing parentheses is "ef", which is

the last value taken on at the top level. If additional

parentheses are added, giving

$ ( ( (?>[^()]+) | (?R) )* ) $

^ ^

^ ^ then the string they capture

is "ab(cd)ef", the contents of the top level parentheses. If

there are more than 15 capturing parentheses in a pattern,

PCRE has to obtain extra memory to store data during a

recursion, which it does by using pcre_malloc, freeing it

via pcre_free afterwards. If no memory can be obtained, it

saves data for the first 15 capturing parentheses only, as

there is no way to give an out-of-memory error from within a

recursion.

Performances

Certain items that may appear in patterns are more efficient

than others. It is more efficient to use a character class

like [aeiou] than a set of alternatives such as (a|e|i|o|u).

In general, the simplest construction that provides the

required behaviour is usually the most efficient. Jeffrey

Friedl's book contains a lot of discussion about optimizing

regular expressions for efficient performance.

Pattern Syntax

3140

When a pattern begins with .* and the PCRE_DOTALL option is

set, the pattern is implicitly anchored by PCRE, since it

can match only at the start of a subject string. However, if

PCRE_DOTALL is not set, PCRE cannot make this optimization,

because the . metacharacter does not then match a newline,

and if the subject string contains newlines, the pattern may

match from the character immediately following one of them

instead of from the very start. For example, the pattern

(.*) second

matches the subject "first\nand second" (where \n stands for

a newline character) with the first captured substring being

"and". In order to do this, PCRE has to retry the match

starting after every newline in the subject.

If you are using such a pattern with subject strings that do

not contain newlines, the best performance is obtained by

setting PCRE_DOTALL , or starting the pattern with ^.* to

indicate explicit anchoring. That saves PCRE from having to

scan along the subject looking for a newline to restart at.

Beware of patterns that contain nested indefinite repeats.

These can take a long time to run when applied to a string

that does not match. Consider the pattern fragment

(a+)*

This can match "aaaa" in 33 different ways, and this number

increases very rapidly as the string gets longer. (The *

repeat can match 0, 1, 2, 3, or 4 times, and for each of

those cases other than 0, the + repeats can match different

numbers of times.) When the remainder of the pattern is such

that the entire match is going to fail, PCRE has in principle

to try every possible variation, and this can take an

extremely long time.

An optimization catches some of the more simple cases such

(a+)*b

where a literal character follows. Before embarking on the

standard matching procedure, PCRE checks that there is a "b"

later in the subject string, and if there is not, it fails

the match immediately. However, when there is no following

literal this optimization cannot be used. You can see the

difference by comparing the behaviour of

(a+)*\d

with the pattern above. The former gives a failure almost

instantly when applied to a whole line of "a" characters,

whereas the latter takes an appreciable time with strings

longer than about 20 characters.

Pattern Syntax

3141

preg_grep

(PHP 4 )

preg_grep - Return array entries that match the pattern

Description

array preg_grep (string pattern, array input)

preg_grep() returns the array consisting of the elements of the input array that match the given pattern.

Since PHP 4.0.4, the results returned by preg_grep() are indexed using the keys from the input array. If this behavior is un-

desirable, use array_values() on the array returned by preg_grep() to reindex the values.

Example 728. preg_grep() example

// return all array elements

// containing floating point numbers

$fl_array = preg_grep ("/^(\d+)?\.\d+$/", $array);

3142

preg_match_all

(PHP 3>= 3.0.9, PHP 4 )

preg_match_all - Perform a global regular expression match

Description

int preg_match_all (string pattern, string subject, array matches [, int flags])

Searches subject for all matches to the regular expression given in pattern and puts them in matches in the order specified

by flags.

After the first match is found, the subsequent searches are continued on from end of the last match.

flags can be a combination of the following flags (note that it doesn't make sense to use PREG_PATTERN_ORDER together

with PREG_SET_ORDER):

PREG_PATTERN_ORDER

Orders results so that $matches[0] is an array of full pattern matches, $matches[1] is an array of strings matched by the

first parenthesized subpattern, and so on.

<?php

preg_match_all ("|<[^>]+>(.*)</[^>]+>|U",

"<b>example: </b><div align=left>this is a test</div>",

$out, PREG_PATTERN_ORDER);

print $out[0][0].", ".$out[0][1]."\n";

print $out[1][0].", ".$out[1][1]."\n";

This example will produce:

<b>example: </b>, <div align=left>this is a test</div>

example: , this is a test

So, $out[0] contains array of strings that matched full pattern, and $out[1] contains array of strings enclosed by tags.

PREG_SET_ORDER

Orders results so that $matches[0] is an array of first set of matches, $matches[1] is an array of second set of matches,

and so on.

<?php

preg_match_all ("|<[^>]+>(.*)</[^>]+>|U",

"<b>example: </b><div align=left>this is a test</div>",

$out, PREG_SET_ORDER);

print $out[0][0].", ".$out[0][1]."\n";

print $out[1][0].", ".$out[1][1]."\n";

This example will produce:

<b>example: </b>, example:

<div align=left>this is a test</div>, this is a test

In this case, $matches[0] is the first set of matches, and $matches[0][0] has text matched by full pattern, $matches[0][1]

has text matched by first subpattern and so on. Similarly, $matches[1] is the second set of matches, etc.

PREG_OFFSET_CAPTURE

If this flag is set, for every occuring match the appendant string offset will also be returned. Note that this changes the

3143

return value in an array where every element is an array consisting of the matched string at offset 0and it's string offset

into subject at offset 1. This flag is available since PHP 4.3.0 .

If no order flag is given, PREG_PATTERN_ORDER is assumed.

Returns the number of full pattern matches (which might be zero), or FALSE if an error occurred.

Example 729. Getting all phone numbers out of some text.

<?php

preg_match_all ("/$? (\d{3})? $? (?(1) [\-\s] ) \d{3}-\d{4}/x",

"Call 555-1212 or 1-800-555-1212", $phones);

Example 730. Find matching HTML tags (greedy)

<?php

// The \\2 is an example of backreferencing. This tells pcre that

// it must match the second set of parentheses in the regular expression

// itself, which would be the ([\w]+) in this case. The extra backslash is

// required because the string is in double quotes.

$html = "<b>bold text</b><a href=howdy.html>click me</a>";

preg_match_all ("/(<([\w]+)[^>]*>)(.*)(<\/\\2>)/", $html, $matches);

for ($i=0; $i< count($matches[0]); $i++) {

echo "matched: ".$matches[0][$i]."\n";

echo "part 1: ".$matches[1][$i]."\n";

echo "part 2: ".$matches[3][$i]."\n";

echo "part 3: ".$matches[4][$i]."\n\n";

}

This example will produce:

matched: <b>bold text</b>

part 1: <b>

part 2: bold text

part 3: </b>

matched: <a href=howdy.html>click me</a>

part 1: <a href=howdy.html>

part 2: click me

part 3: </a>

See also preg_match(),preg_replace(), and preg_split().

preg_match_all

3144

preg_match

(PHP 3>= 3.0.9, PHP 4 )

preg_match - Perform a regular expression match

Description

int preg_match (string pattern, string subject [, array matches [, int flags]])

Searches subject for a match to the regular expression given in pattern.

If matches is provided, then it is filled with the results of search. $matches[0] will contain the text that matched the full pat-

tern, $matches[1] will have the text that matched the first captured parenthesized subpattern, and so on.

flags can be the following flag:

PREG_OFFSET_CAPTURE

If this flag is set, for every occuring match the appendant string offset will also be returned. Note that this changes the

return value in an array where every element is an array consisting of the matched string at offset 0and it's string offset

into subject at offset 1. This flag is available since PHP 4.3.0 .

The flags parameter is available since PHP 4.3.0 .

preg_match() returns the number of times pattern matches. That will be either 0 times (no match) or 1 time because

preg_match() will stop searching after the first match. preg_match_all() on the contrary will continue until it reaches the

end of subject.preg_match() returns FALSE if an error occured.

Example 731. Find the string of text "php"

// the "i" after the pattern delimiter indicates a case-insensitive search

if (preg_match ("/php/i", "PHP is the web scripting language of choice.")) {

print "A match was found.";

} else {

print "A match was not found.";

}

Example 732. find the word "web"

// the \b in the pattern indicates a word boundary, so only the distinct

// word "web" is matched, and not a word partial like "webbing" or "cobweb"

if (preg_match ("/\bweb\b/i", "PHP is the web scripting language of choice.")) {

print "A match was found.";

} else {

print "A match was not found.";

}

if (preg_match ("/\bweb\b/i", "PHP is the website scripting language of choice.")) {

print "A match was found.";

} else {

print "A match was not found.";

}

Example 733. Getting the domain name out of a URL

3145

// get host name from URL

preg_match("/^(http:\/\/)?([^\/]+)/i",

"http://www.php.net/index.html", $matches);

$host = $matches[2];

// get last two segments of host name

preg_match("/[^\.\/]+\.[^\.\/]+$/",$host,$matches);

echo "domain name is: ".$matches[0]."\n";

This example will produce:

domain name is: php.net

See also preg_match_all(),preg_replace(), and preg_split().

preg_match

3146

preg_quote

(PHP 3>= 3.0.9, PHP 4 )

preg_quote - Quote regular expression characters

Description

string preg_quote (string str [, string delimiter])

preg_quote() takes str and puts a backslash in front of every character that is part of the regular expression syntax. This is

useful if you have a run-time string that you need to match in some text and the string may contain special regex characters.

If the optional delimiter is specified, it will also be escaped. This is useful for escaping the delimiter that is required by the

PCRE functions. The / is the most commonly used delimiter.

The special regular expression characters are:

.\\+*?[^]$(){}=!<>|:

Example 734.

$keywords = "$40 for a g3/400";

$keywords = preg_quote ($keywords, "/");

echo $keywords; // returns \$40 for a g3\/400

Example 735. Italicizing a word within some text

// In this example, preg_quote($word) is used to keep the

// asterisks from having special meaning to the regular

// expression.

$textbody = "This book is *very* difficult to find.";

$word = "*very*";

$textbody = preg_replace ("/".preg_quote($word)."/",

"<i>".$word."</i>",

$textbody);

3147

preg_replace_callback

(PHP 4 >= 4.0.5)

preg_replace_callback - Perform a regular expression search and replace using a callback

Description

mixed preg_replace_callback (mixed pattern, callback callback, mixed subject [, int limit])

The behavior of this function is almost identical to preg_replace(), except for the fact that instead of replacement paramet-

er, one should specify a callback that will be called and passed an array of matched elements in the subject string. The call-

back should return the replacement string.

Example 736. preg_replace_callback() example

<?php

// this text was used in 2002

// we want to get this up to date for 2003

$text = "April fools day is 04/01/2002\n";

$text.= "Last christmas was 12/24/2001\n";

// the callback function

function next_year($matches) {

// as usual: $matches[0] is the complete match

// $matches[1] the match for the first subpattern

// enclosed in '(...)' and so on

return $matches[1].($matches[2]+1);

}

echo preg_replace_callback(

"|(\d{2}/\d{2}/)(\d{4})|",

"next_year",

$text);

// result is:

// April fools day is 04/01/2003

// Last christmas was 12/24/2002

You'll often need the callback function for a preg_replace_callback() in just one place. In this case you can use cre-

ate_function() to declare an anonymous function as callback within the call to preg_replace_callback(). By doing it this

way you have all information for the call in one place and do not clutter the function namespace with a callback functions

name not used anywhere else.

Example 737. preg_replace_callback() and create_function()

<?php

// a unix-style command line filter to convert uppercase

// letters at the beginning of paragraphs to lowercase

$fp = fopen("php://stdin", "r") or die("can't read stdin");

while (!feof($fp)) {

$line = fgets($fp);

$line = preg_replace_callback(

'|<p>\s*\w|',

create_function(

// single quotes are essential here,

// or alternative escape all $ as \$

'$matches',

'return strtolower($matches[0]);'

3148

$line

); echo $line;

}

fclose($fp);

See also preg_replace(),create_function().

preg_replace_callback

3149

preg_replace

(PHP 3>= 3.0.9, PHP 4 )

preg_replace - Perform a regular expression search and replace

Description

mixed preg_replace (mixed pattern, mixed replacement, mixed subject [, int limit])

Searches subject for matches to pattern and replaces them with replacement. If limit is specified, then only limit matches

will be replaced; if limit is omitted or is -1, then all matches are replaced.

Replacement may contain references of the form \\nor (since PHP 4.0.4) $n, with the latter form being the preferred one.

Every such reference will be replaced by the text captured by the n'th parenthesized pattern. ncan be from 0 to 99, and \\0

or $0 refers to the text matched by the whole pattern. Opening parentheses are counted from left to right (starting from 1) to

obtain the number of the capturing subpattern.

Note: When working with a replacement pattern where a backreference is immediately followed by another num-

ber (i.e.: placing a literal number immediately after a matched pattern), you cannot use the familiar \\1 notation

for your backreference. \\11, for example, would confuse preg_replace() since it does not know whether you

want the \\1 backreference followed by a literal 1, or the \\11 backreference followed by nothing. In this case the

solution is to use \${1}1. This creates an isolated $1 backreference, leaving the 1as a literal.

Example 738. Using backreferences followed by numeric literals.

<?php

$string = "April 15, 2003";

$pattern = "/(\w+) (\d+), (\d+)/i";

$replacement = "\${1}1,\$3";

print preg_replace($pattern, $replacement, $string);

/* Output

======

April1,2003

If matches are found, the new subject will be returned, otherwise subject will be returned unchanged.

Every parameter to preg_replace() (except limit) can be an array.

Note: When using arrays with pattern and replacement, the keys are processed in the order they appear in the ar-

ray. This is not necessarily the same as the numerical index order. If you use indexes to identify which pattern

should be replaced by which replacement, you should perform a ksort() on each array prior to calling

preg_replace().

Example 739. Using indexed arrays with preg_replace()

<?php

$string = "The quick brown fox jumped over the lazy dog.";

$patterns[0] = "/quick/";

$patterns[1] = "/brown/";

$patterns[2] = "/fox/";

3150

$replacements[2] = "bear";

$replacements[1] = "black";

$replacements[0] = "slow";

print preg_replace($patterns, $replacements, $string);

/* Output

======

The bear black slow jumped over the lazy dog.

/* By ksorting patterns and replacements,

we should get what we wanted. */

ksort($patterns);

ksort($replacements);

print preg_replace($patterns, $replacements, $string);

/* Output

======

The slow black bear jumped over the lazy dog.

If subject is an array, then the search and replace is performed on every entry of subject, and the return value is an array as

well.

If pattern and replacement are arrays, then preg_replace() takes a value from each array and uses them to do search and re-

place on subject.Ifreplacement has fewer values than pattern, then empty string is used for the rest of replacement values.

If pattern is an array and replacement is a string, then this replacement string is used for every value of pattern. The con-

verse would not make sense, though.

/e modifier makes preg_replace() treat the replacement parameter as PHP code after the appropriate references substitu-

tion is done. Tip: make sure that replacement constitutes a valid PHP code string, otherwise PHP will complain about a

parse error at the line containing preg_replace().

Example 740. Replacing several values

$patterns = array ("/(19|20)(\d{2})-(\d{1,2})-(\d{1,2})/",

"/^\s*{(\w+)}\s*=/");

$replace = array ("\\3/\\4/\\1\\2", "$\\1 =");

print preg_replace ($patterns, $replace, "{startDate} = 1999-5-27");

This example will produce:

$startDate = 5/27/1999

Example 741. Using /e modifier

preg_replace ("/(<\/?)(\w+)([^>]*>)/e",

"'\\1'.strtoupper('\\2').'\\3'",

$html_body);

preg_replace

3151

This would capitalize all HTML tags in the input text.

Example 742. Convert HTML to text

// $document should contain an HTML document.

// This will remove HTML tags, javascript sections

// and white space. It will also convert some

// common HTML entities to their text equivalent.

$search = array ("'<script[^>]*?>.*?</script>'si", // Strip out javascript

"'<[\/\!]*?[^<>]*?>'si", // Strip out html tags

"'([\r\n])[\s]+'", // Strip out white space

"'&(quot|#34);'i", // Replace html entities

"'&(amp|#38);'i",

"'&(lt|#60);'i",

"'&(gt|#62);'i",

"'&(nbsp|#160);'i",

"'&(iexcl|#161);'i",

"'&(cent|#162);'i",

"'&(pound|#163);'i",

"'&(copy|#169);'i",

"'&#(\d+);'e"); // evaluate as php

$replace = array ("",

"",

"\\1",

"\"",

"&",

"<",

">",

" ",

chr(161),

chr(162),

chr(163),

chr(169),

"chr(\\1)");

$text = preg_replace ($search, $replace, $document);

Note: Parameter limit was added after PHP 4.0.1pl2.

See also preg_match(),preg_match_all(), and preg_split().

preg_replace

3152

preg_split

(PHP 3>= 3.0.9, PHP 4 )

preg_split - Split string by a regular expression

Description

array preg_split (string pattern, string subject [, int limit [, int flags]])

Returns an array containing substrings of subject split along boundaries matched by pattern.

If limit is specified, then only substrings up to limit are returned, and if limit is -1, it actually means "no limit", which is use-

ful for specifying the flags.

flags can be any combination of the following flags (combined with bitwise | operator):

PREG_SPLIT_NO_EMPTY

If this flag is set, only non-empty pieces will be returned by preg_split().

PREG_SPLIT_DELIM_CAPTURE

If this flag is set, parenthesized expression in the delimiter pattern will be captured and returned as well. This flag was

added for 4.0.5.

PREG_SPLIT_OFFSET_CAPTURE

If this flag is set, for every occuring match the appendant string offset will also be returned. Note that this changes the

return value in an array where every element is an array consisting of the matched string at offset 0and it's string offset

into subject at offset 1. This flag is available since PHP 4.3.0 .

Example 743. preg_split() example : Get the parts of a search string

// split the phrase by any number of commas or space characters,

// which include " ", \r, \t, \n and \f

$keywords = preg_split ("/[\s,]+/", "hypertext language, programming");

Example 744. Splitting a string into component characters

$str = 'string';

$chars = preg_split('//', $str, -1, PREG_SPLIT_NO_EMPTY);

print_r($chars);

Example 745. Splitting a string into matches and their offsets

$str = 'hypertext language programming';

$chars = preg_split('/ /', $str, -1, PREG_SPLIT_OFFSET_CAPTURE);

print_r($chars);

will yield

3153

Array

([0] => Array

([0] => hypertext

[1] => 0

)

[1] => Array

([0] => language

[1] => 10

)

[2] => Array

([0] => programming

[1] => 19

)

Note: Parameter flags was added in PHP 4 Beta 3.

See also spliti(),split(),implode(),preg_match(),preg_match_all(), and preg_replace().

preg_split

3154

qtdom functions

Table of Contents

qdom_error ..................................................................................................................................... 3157

qdom_tree ...................................................................................................................................... 3158

3155

Warning

This extension is EXPERIMENTAL. The behaviour of this extension -- including the names of its functions and

anything else documented about this extension -- may change without notice in a future release of PHP. Use this

extension at your own risk.

Note: This extension is not available on Windows platforms.

Requirements

You need the Qt-library >=2.2.0

Installation

Configure PHP --with-qtdom to use these functions.

3156

qdom_error

(PHP 4 >= 4.0.5)

qdom_error - Returns the error string from the last QDOM operation or FALSE if no errors occured

Description

string qdom_error (void)

Warning

This function is EXPERIMENTAL. The behaviour of this function, the name of this function, and anything else

documented about this function may change without notice in a future release of PHP. Use this function at your

own risk.

Warning

This function is currently not documented; only the argument list is available.

3157

qdom_tree

(PHP 4 >= 4.0.4)

qdom_tree - creates a tree of an xml string

Description

object qdom_tree (string )

Warning

This function is EXPERIMENTAL. The behaviour of this function, the name of this function, and anything else

documented about this function may change without notice in a future release of PHP. Use this function at your

own risk.

Warning

This function is currently not documented; only the argument list is available.

3158

Regular Expression Functions (POSIX

Extended)

Table of Contents

ereg_replace .................................................................................................................................... 3162

ereg ............................................................................................................................................... 3164

eregi_replace ................................................................................................................................... 3165

eregi .............................................................................................................................................. 3166

split ............................................................................................................................................... 3167

spliti .............................................................................................................................................. 3168

sql_regcase ..................................................................................................................................... 3169

3159

Introduction

Note: PHP also supports regular expressions using a Perl-compatible syntax using the PCRE functions. Those

functions support non-greedy matching, assertions, conditional subpatterns, and a number of other features not sup-

ported by the POSIX-extended regular expression syntax.

Warning

These regular expression functions are not binary-safe. The PCRE functions are.

Regular expressions are used for complex string manipulation in PHP. The functions that support regular expressions are:

•ereg()

•ereg_replace()

•eregi()

•eregi_replace()

•split()

•spliti()

These functions all take a regular expression string as their first argument. PHP uses the POSIX extended regular expres-

sions as defined by POSIX 1003.2. For a full description of POSIX regular expressions see the regex man pages included in

the regex directory in the PHP distribution. It's in manpage format, so you'll want to do something along the lines of man /

usr/local/src/regex/regex.7 in order to read it.

Requirements

No external libraries are needed to build this extension.

Installation

To enable regexp support configure PHP --with-regex[=TYPE]. TYPE can be one of system, apache, php. The default is

to use php.

Note: Do not change the TYPE unless you know what you are doing.

The windows version of PHP has built in support for this extension. You do not need to load any additional extension in or-

der to use these functions.

Runtime Configuration

This extension has no configuration directives defined in php.ini.

Resource Types

This extension has no resource types defined.

Predefined Constants

3160

This extension has no constants defined.

Examples

Example 746. Regular Expression Examples

ereg ("abc", $string);

/* Returns true if "abc"

is found anywhere in $string. */

ereg ("^abc", $string);

/* Returns true if "abc"

is found at the beginning of $string. */

ereg ("abc$", $string);

/* Returns true if "abc"

is found at the end of $string. */

eregi ("(ozilla.[23]|MSIE.3)", $HTTP_USER_AGENT);

/* Returns true if client browser

is Netscape 2, 3 or MSIE 3. */

ereg ("([[:alnum:]]+) ([[:alnum:]]+) ([[:alnum:]]+)", $string,$regs);

/* Places three space separated words

into $regs[1], $regs[2] and $regs[3]. */

$string = ereg_replace ("^", "<br />", $string);

/* Put a <br /> tag at the beginning of $string. */

$string = ereg_replace ("$", "<br />", $string);

/* Put a <br /> tag at the end of $string. */

$string = ereg_replace ("\n", "", $string);

/* Get rid of any newline

characters in $string. */

See Also

For regular expressions in Perl-compatible syntax have a look at the PCRE functions. The simpler shell style wildcard pat-

tern matching is provided by fnmatch().

Regular Expression Functions (POSIX

Extended)

3161

ereg_replace

(PHP 3, PHP 4 )

ereg_replace - Replace regular expression

Description

string ereg_replace (string pattern, string replacement, string string)

Note: preg_replace(), which uses a Perl-compatible regular expression syntax, is often a faster alternative to

ereg_replace().

This function scans string for matches to pattern, then replaces the matched text with replacement.

The modified string is returned. (Which may mean that the original string is returned if there are no matches to be replaced.)

If pattern contains parenthesized substrings, replacement may contain substrings of the form \\digit, which will be re-

placed by the text matching the digit'th parenthesized substring; \\0 will produce the entire contents of string. Up to nine

substrings may be used. Parentheses may be nested, in which case they are counted by the opening parenthesis.

If no matches are found in string, then string will be returned unchanged.

For example, the following code snippet prints "This was a test" three times:

Example 747. ereg_replace() Example

$string = "This is a test";

echo ereg_replace (" is", " was", $string);

echo ereg_replace ("( )is", "\\1was", $string);

echo ereg_replace ("(( )is)", "\\2was", $string);

One thing to take note of is that if you use an integer value as the replacement parameter, you may not get the results you

expect. This is because ereg_replace() will interpret the number as the ordinal value of a character, and apply that. For in-

stance:

Example 748. ereg_replace() Example

<?php

/* This will not work as expected. */

$num = 4;

$string = "This string has four words.";

$string = ereg_replace('four', $num, $string);

echo $string; /* Output: 'This string has words.' */

/* This will work. */

$num = '4';

$string = "This string has four words.";

$string = ereg_replace('four', $num, $string);

echo $string; /* Output: 'This string has 4 words.' */

Example 749. Replace URLs with links

$text = ereg_replace("[[:alpha:]]+://[^<>[:space:]]+[[:alnum:]/]",

3162

"<a href=\"\\0\">\\0</a>", $text);

See also ereg(),eregi(),eregi_replace(),str_replace(), and preg_match().

ereg_replace

3163

ereg

(PHP 3, PHP 4 )

ereg - Regular expression match

Description

bool ereg (string pattern, string string [, array regs])

Note: preg_match(), which uses a Perl-compatible regular expression syntax, is often a faster alternative to ereg().

Searches a string for matches to the regular expression given in pattern.

If matches are found for parenthesized substrings of pattern and the function is called with the third argument regs, the

matches will be stored in the elements of the array regs. $regs[1] will contain the substring which starts at the first left par-

enthesis; $regs[2] will contain the substring starting at the second, and so on. $regs[0] will contain a copy of the complete

string matched.

Note: Up to (and including) PHP 4.1.0 $regs will be filled with exactly ten elements, even though more or fewer

than ten parenthesized substrings may actually have matched. This has no effect on ereg()'s ability to match more

substrings. If no matches are found, $regs will not be altered by ereg().

Searching is case sensitive.

Returns TRUE if a match for pattern was found in string,orFALSE if no matches were found or an error occurred.

The following code snippet takes a date in ISO format (YYYY-MM-DD) and prints it in DD.MM.YYYY format:

Example 750. ereg() example

<?php

if (ereg ("([0-9]{4})-([0-9]{1,2})-([0-9]{1,2})", $date, $regs)) {

echo "$regs[3].$regs[2].$regs[1]";

} else {

echo "Invalid date format: $date";

}

See also eregi(),ereg_replace(),eregi_replace(),preg_match(),strpos(), and strstr().

3164

eregi_replace

(PHP 3, PHP 4 )

eregi_replace - replace regular expression case insensitive

Description

string eregi_replace (string pattern, string replacement, string string)

This function is identical to ereg_replace() except that this ignores case distinction when matching alphabetic characters.

See also ereg(),eregi(), and ereg_replace().

3165

eregi

(PHP 3, PHP 4 )

eregi - case insensitive regular expression match

Description

bool eregi (string pattern, string string [, array regs])

This function is identical to ereg() except that this ignores case distinction when matching alphabetic characters.

Example 751. eregi() example

<?php

if (eregi("z", $string)) {

echo "'$string' contains a 'z' or 'Z'!";

}

See also ereg(),ereg_replace(),eregi_replace(),stripos(), and stristr().

3166

split

(PHP 3, PHP 4 )

split - split string into array by regular expression

Description

array split (string pattern, string string [, int limit])

Note: preg_split(), which uses a Perl-compatible regular expression syntax, is often a faster alternative to split().

Returns an array of strings, each of which is a substring of string formed by splitting it on boundaries formed by the regular

expression pattern. If limit is set, the returned array will contain a maximum of limit elements with the last element contain-

ing the whole rest of string. If an error occurs, split() returns FALSE.

To split off the first four fields from a line from /etc/passwd:

Example 752. split() Example

list($user,$pass,$uid,$gid,$extra)= split (":", $passwd_line, 5);

Note: If there are noccurrences of pattern, the returned array will contain n+1 items. For example, if there is no

occurrence of pattern, an array with only one element will be returned. Of course, this is also true if string is

empty.

To parse a date which may be delimited with slashes, dots, or hyphens:

Example 753. split() Example

$date = "04/30/1973"; // Delimiters may be slash, dot, or hyphen

list ($month, $day, $year) = split ('[/.-]', $date);

echo "Month: $month; Day: $day; Year: $year<br>\n";

Note that pattern is case-sensitive.

Note that if you don't require the power of regular expressions, it is faster to use explode(), which doesn't incur the overhead

of the regular expression engine.

For users looking for a way to emulate Perl's @chars = split('', $str) behaviour, please see the examples for preg_split().

Please note that pattern is a regular expression. If you want to split on any of the characters which are considered special by

regular expressions, you'll need to escape them first. If you think split() (or any other regex function, for that matter) is do-

ing something weird, please read the file regex.7, included in the regex/ subdirectory of the PHP distribution. It's in

manpage format, so you'll want to do something along the lines of man /usr/local/src/regex/regex.7 in order to read it.

See also: preg_split(),spliti(),explode(),implode(),chunk_split(), and wordwrap().

3167

spliti

(PHP 4 >= 4.0.1)

spliti - Split string into array by regular expression case insensitive

Description

array spliti (string pattern, string string [, int limit])

This function is identical to split() except that this ignores case distinction when matching alphabetic characters.

See also preg_spliti(),split(),explode(), and implode().

3168

sql_regcase

(PHP 3, PHP 4 )

sql_regcase - Make regular expression for case insensitive match

Description

string sql_regcase (string string)

Returns a valid regular expression which will match string, ignoring case. This expression is string with each character con-

verted to a bracket expression; this bracket expression contains that character's uppercase and lowercase form if applicable,

otherwise it contains the original character twice.

Example 754. sql_regcase() Example

echo sql_regcase ("Foo bar");

prints

[Ff][Oo][Oo] [Bb][Aa][Rr]

This can be used to achieve case insensitive pattern matching in products which support only case sensitive regular expres-

sions.

3169

Semaphore, Shared Memory and IPC

Functions

Table of Contents

ftok ............................................................................................................................................... 3173

msg_get_queue ................................................................................................................................ 3174

msg_receive .................................................................................................................................... 3175

msg_remove_queue .......................................................................................................................... 3176

msg_send ....................................................................................................................................... 3177

msg_set_queue ................................................................................................................................ 3178

msg_stat_queue ............................................................................................................................... 3179

sem_acquire .................................................................................................................................... 3180

sem_get .......................................................................................................................................... 3181

sem_release .................................................................................................................................... 3182

sem_remove .................................................................................................................................... 3183

shm_attach ..................................................................................................................................... 3184

shm_detach ..................................................................................................................................... 3185

shm_get_var ................................................................................................................................... 3186

shm_put_var ................................................................................................................................... 3187

shm_remove_var .............................................................................................................................. 3188

shm_remove ................................................................................................................................... 3189

3170

Introduction

This module provides wrappers for the System V IPC family of functions. It includes semaphores, shared memory and inter-

process messaging (IPC).

Semaphores may be used to provide exclusive access to resources on the current machine, or to limit the number of pro-

cesses that may simultaneously use a resource.

This module provides also shared memory functions using System V shared memory. Shared memory may be used to

provide access to global variables. Different httpd-daemons and even other programs (such as Perl, C, ...) are able to access

this data to provide a global data-exchange. Remember, that shared memory is NOT safe against simultaneous access. Use

semaphores for synchronization.

Table 140. Limits of Shared Memory by the Unix OS

SHMMAX max size of shared memory, normally 131072 bytes

SHMMIN minimum size of shared memory, normally 1 byte

SHMMNI max amount of shared memory segments on a system, nor-

mally 100

SHMSEG max amount of shared memory segments per process, nor-

mally 6

The messaging functions may be used to send and receive messages to/from other processes. They provide a simple and ef-

fective means of exchanging data between processes, without the need for setting up an alternative using unix domain sock-

ets.

Note: This extension is not available on Windows platforms.

Requirements

No external libraries are needed to build this extension.

Installation

Support for this functions are not enabled by default. To enable System V semaphore support compile PHP with the option

--enable-sysvsem. To enable the System V shared memory support compile PHP with the option --enable-sysvshm.

To enable the System V messages support compile PHP with the option --enable-sysvmsg.

Runtime Configuration

The behaviour of these functions is affected by settings in php.ini.

Table 141. Semaphore Configuration Options

Name Default Changeable

sysvmsg.value "42" PHP_INI_ALL

sysvmsg.string "foobar" PHP_INI_ALL

For further details and definition of the PHP_INI_* constants see ini_set().

3171

Resource Types

Predefined Constants

This extension has no constants defined.

Semaphore, Shared Memory and IPC

Functions

3172

ftok

(PHP 4 >= 4.2.0)

ftok - Convert a pathname and a project identifier to a System V IPC key

Description

int ftok (string pathname, string proj)

The function converts the pathname of an existing accessible file and a project identifier (proj) into a interger for use

with for example shmop_open() and other System V IPC keys. The proj parameter should be a one character string.

On success the return value will be the created key value, otherwise -1 is returned.

See Also

For specific SESAM details, please refer to the SESAM/SQL-Server documentation (english) [http://its.siemens.de/lobs/its/

techinf/oltp/sesam/manuals/index_en.htm] or the SESAM/SQL-Server documentation (german) [http://its.siemens.de/lobs/

its/techinf/oltp/sesam/manuals/index_gr.htm], both available online, or use the respective manuals.

SESAM database functions

3195

sesam_affected_rows

(PHP 3 CVS only)

sesam_affected_rows - Get number of rows affected by an immediate query

Description

int sesam_affected_rows (string result_id)

result_id is a valid result id returned by sesam_query().

Returns the number of rows affected by a query associated with result_id.

The sesam_affected_rows() function can only return useful values when used in combination with "immediate" SQL state-

ments (updating operations like INSERT,UPDATE and DELETE) because SESAM does not deliver any "affected rows" in-

formation for "select type" queries. The number returned is the number of affected rows.

See also: sesam_query() and sesam_execimm()

$result = sesam_execimm ("DELETE FROM PHONE WHERE LASTNAME = '".strtoupper ($name)."'");

if (!$result) {

... error ...

}

print sesam_affected_rows ($result).

" entries with last name ".$name." deleted.\n"

3196

sesam_commit

(PHP 3 CVS only)

sesam_commit - Commit pending updates to the SESAM database

Description

bool sesam_commit (void)

Returns: TRUE on success, FALSE on errors

sesam_commit() commits any pending updates to the database.

Note that there is no "auto-commit" feature as in other databases, as it could lead to accidental data loss. Uncommitted data

at the end of the current script (or when calling sesam_disconnect()) will be discarded by an implied sesam_rollback()

call.

See Also

For even more powerful string handling and manipulating functions take a look at the POSIX regular expression functions

and the Perl compatible regular expression functions.

String functions

3418

addcslashes

(PHP 4 )

addcslashes - Quote string with slashes in a C style

Description

string addcslashes (string str, string charlist)

Returns a string with backslashes before characters that are listed in charlist parameter. It escapes \n,\r etc. in C-like style,

characters with ASCII code lower than 32 and higher than 126 are converted to octal representation.

Be careful if you choose to escape characters 0, a, b, f, n, r, t and v. They will be converted to \0, \a, \b, \f, \n, \r, \t and \v. In

PHP \0 (NULL), \r (carriage return), \n (newline) and \t (tab) are predefined escape sequences, while in C all of these are pre-

defined escape sequences.

charlist like "\0..\37", which would escape all characters with ASCII code between 0 and 31.

Example 808. addcslashes() example

<?php

$escaped = addcslashes($not_escaped, "\0..\37!@\177..\377");

When you define a sequence of characters in the charlist argument make sure that you know what characters come between

the characters that you set as the start and end of the range.

<?php

echo addcslashes('foo[ ]', 'A..z');

// output: \f\o\o\[ \]

// All upper and lower-case letters will be escaped

// ... but so will the [\]^_` and any tabs, line

// feeds, carriage returns, etc.

Also, if the first character in a range has a lower ASCII value than the second character in the range, no range will be con-

structed. Only the start, end and period characters will be escaped. Use the ord() function to find the ASCII value for a char-

acter.

<?php

echo addcslashes("zoo['.']", 'z..A');

// output: \zoo['\.']

See also stripcslashes(),stripslashes(),htmlspecialchars(), and quotemeta().

3419

addslashes

(PHP 3, PHP 4 )

addslashes - Quote string with slashes

Description

string addslashes (string str)

Returns a string with backslashes before characters that need to be quoted in database queries etc. These characters are

single quote ('), double quote ("), backslash (\) and NUL (the NULL byte).

Note: magic_quotes_gpc is ON by default.

See also stripslashes(),htmlspecialchars(), and quotemeta().

3420

bin2hex

(PHP 3>= 3.0.9, PHP 4 )

bin2hex - Convert binary data into hexadecimal representation

Description

string bin2hex (string str)

Returns an ASCII string containing the hexadecimal representation of str. The conversion is done byte-wise with the high-

nibble first.

See also zip_open() and zip_read().

3757

zip_entry_close

(4.1.0 - 4.3.2 only)

zip_entry_close - Close a Directory Entry

Description

void zip_entry_close (resource zip_entry)

Closes a directory entry specified by zip_entry. The parameter zip_entry must be a valid directory entry opened by

zip_entry_open().

This function has no return value.

See also zip_entry_open() and zip_entry_read().

3758

zip_entry_compressedsize

(4.1.0 - 4.3.2 only)

zip_entry_compressedsize - Retrieve the Compressed Size of a Directory Entry

Description

int zip_entry_compressedsize (resource zip_entry)

Returns the compressed size of the directory entry specified by zip_entry. The parameter zip_entry is a valid directory entry

returned by zip_read().

See also zip_open() and zip_read().

3759

zip_entry_compressionmethod

(4.1.0 - 4.3.2 only)

zip_entry_compressionmethod - Retrieve the Compression Method of a Directory Entry

Description

string zip_entry_compressionmethod (resource zip_entry)

Returns the compression method of the directory entry specified by zip_entry. The parameter zip_entry is a valid directory

entry returned by zip_read().

See also zip_open() and zip_read().

3760

zip_entry_filesize

(4.1.0 - 4.3.2 only)

zip_entry_filesize - Retrieve the Actual File Size of a Directory Entry

Description

int zip_entry_filesize (resource zip_entry)

Returns the actual size of the directory entry specified by zip_entry. The parameter zip_entry is a valid directory entry re-

turned by zip_read().

See also zip_open() and zip_read().

3761

zip_entry_name

(4.1.0 - 4.3.2 only)

zip_entry_name - Retrieve the Name of a Directory Entry

Description

string zip_entry_name (resource zip_entry)

Returns the name of the directory entry specified by zip_entry. The parameter zip_entry is a valid directory entry returned

by zip_read().

See also zip_open() and zip_read().

3762

zip_entry_open

(4.1.0 - 4.3.2 only)

zip_entry_open - Open a Directory Entry for Reading

Description

bool zip_entry_open (resource zip, resource zip_entry [, string mode])

Opens a directory entry in a zip file for reading. The parameter zip is a valid resource handle returned by zip_open(). The

parameter zip_entry is a directory entry resource returned by zip_read(). The optional parameter mode can be any of the

modes specified in the documentaion for fopen().

Note: Currently, mode is ignored and is always "rb". This is due to the fact that zip support in PHP is read only

access. Please see fopen() for an explanation of various modes, including "rb".

Returns TRUE on success or FALSE on failure.

Note: Unlike fopen() and other similar functions, the return value of zip_entry_open() only indicates the result of

the operation and is not needed for reading or closing the directory entry.

See also zip_entry_read() and zip_entry_close().

3763

zip_entry_read

(4.1.0 - 4.3.2 only)

zip_entry_read - Read From an Open Directory Entry

Description

string zip_entry_read (resource zip_entry [, int length])

Reads up to length bytes from an open directory entry. If length is not specified, then zip_entry_read() will attempt to read

1024 bytes. The parameter zip_entry is a valid directory entry returned by zip_read().

Note: The length parameter should be the uncompressed length you wish to read.

Returns the data read, or FALSE if the end of the file is reached.

See also zip_entry_open(),zip_entry_close() and zip_entry_filesize().

3764

zip_open

(4.1.0 - 4.3.2 only)

zip_open - Open a Zip File Archive

Description

resource zip_open (string filename)

Opens a new zip archive for reading. The filename parameter is the filename of the zip archive to open.

Returns a resource handle for later use with zip_read() and zip_close() or returns FALSE if filename does not exist.

Php Manual

Official.%20php_manual_en

Navigation menu

Versions of this User Manual:

Views

Navigation