\n"; } This example will display all the request headers for the current request. Note: getallheaders() is currently only supported when PHP runs as an Apache module. virtual virtual -- Perform an Apache sub-request Description int virtual(string filename); virtual() is an Apache-specific function which is equivalent to in mod_include. It performs an Apache sub-request. It is useful for including CGI scripts or .shtml files, or anything else that you would parse through Apache. Note that for a CGI script, the script must generate valid CGI headers. At the minimum that means it must generate a Content-type header. For PHP files, you should use include() or require(). III. Array functions Table of Contents array Ñ Create an array array_push Ñ Push one or more elements onto the end of array array_pop Ñ Pop the element off the end of array array_unshift Ñ Push one or more elements onto the beginning of array array_shift Ñ Pop an element of the beginning of array array_slice Ñ Extract a slice of the array array_splice Ñ Remove a portion of the array and replace it with something else array_merge Ñ Merge two or more arrays array_keys Ñ Return all the keys of an array array_values Ñ Return all the values of an array array_walk Ñ Apply a user function to every member of an array. arsort Ñ Sort an array in reverse order and maintain index association asort Ñ Sort an array and maintain index association compact Ñ Create array containing variables and their values count Ñ count elements in a variable current Ñ Return the current element in an array each Ñ Return the next key and value pair from an array end Ñ Set the internal pointer of an array to its last element extract Ñ Import variables into the symbol table from an array in_array Ñ Return true if a value exists in an array key Ñ Fetch a key from an associative array ksort Ñ Sort an array by key list Ñ Assign variables as if they were an array next Ñ Advance the internal array pointer of an array pos Ñ Get the current element from an array prev Ñ Rewind the internal array pointer range Ñ Create an array containing a range of integers reset Ñ Set the internal pointer of an array to its first element rsort Ñ Sort an array in reverse order shuffle Ñ Shuffle an array sizeof Ñ Get the number of elements in an array sort Ñ Sort an array uasort Ñ Sort an array with a user-defined comparison function and maintain index association uksort Ñ Sort an array by keys using a user-defined comparison function usort Ñ Sort an array by values using a user-defined comparison function array array -- Create an array Description array array(...); Returns an array of the parameters. The parameters can be given an index with the => operator. Note: array() is a language construct used to represent literal arrays, and not a regular function. The following example demonstrates how to create a two-dimensional array, how to specify keys for associative arrays, and how to skip-and-continue numeric indices in normal arrays. Example 1. array() example $fruits = array( "fruits" => array("a"=>"orange","b"=>"banana","c"=>"apple"), "numbers" => array(1, 2, 3, 4, 5, 6), "holes" => array("first", 5 => "second", "third") ); See also: list(). array_push array_push -- Push one or more elements onto the end of array Description int array_push(array array, mixed var, [...]); array_push() treats array as a stack, and pushes the passed variables onto the end of array. The length of array increases by the number of variables pushed. Has the same effect as: $array[] = $var; repeated for each var. Returns the new number of elements in the array. Example 1. array_push() example $stack = array(1, 2); array_push($stack, "+", 3); This example would result in $stack having 4 elements: 1, 2, "+", and 3. See also array_pop(), array_shift(), and array_unshift(). Note: This function was added in PHP 4.0. array_pop array_pop -- Pop the element off the end of array Description mixed array_pop(array array); array_pop() pops and returns the last value of the array, shortening the array by one element. Example 1. array_pop() example $stack = array("orange", "apple", "raspberry"); $fruit = array_pop($stack); After this, $stack has only 2 elements: "orange" and "apple", and $fruit has "raspberry". See also array_push(), array_shift(), and array_unshift(). Note: This function was added in PHP 4.0. array_unshift array_unshift -- Push one or more elements onto the beginning of array Description int array_unshift(array array, mixed var, [...]); array_unshift() prepends passed elements to the front of the array. Note that the list of elements is prepended as a whole, so that the prepended elements stay in the same order. Returns the new number of elements in the array. Example 1. array_unshift() example $queue = array("p1", "p3"); array_unshift($queue, "p4", "p5", "p6"); This would result in $queue having 5 elements: "p4", "p5", "p6", "p1", and "p3". See also array_shift(), array_push(), and array_pop(). Note: This function was added in PHP 4.0. array_shift array_shift -- Pop an element of the beginning of array Description mixed array_shift(array array); array_shift() shifts the first value of the array off and returns it, shortening the array by one element and moving everything down. Example 1. array_shift() example $args = array("-v", "-f"); $opt = array_shift($args); This would result in $args having one element "-f" left, and $opt being "-v". See also array_unshift(), array_push(), and array_pop(). Note: This function was added in PHP 4.0. array_slice array_slice -- Extract a slice of the array Description array array_slice(array array, int offset, int [length] ); array_slice() returns a sequence of elements from the array specified by the offset and length parameters. If offset is positive, the sequence will start at that offset in the array. If offset is negative, the sequence will start that far from the end of the array. If length is given and is positive, then the sequence will have that many elements in it. If length is given and is negative then the sequence will stop that many elements from the end of the array. If it is omitted, then the sequence will have everything from offset up until the end of the array. Example 1. array_slice() examples $input = array("a", "b", "c", "d", "e"); $output = array_slice($input, 2); // returns "c", "d", and "e" $output = array_slice($input, 2, -1); // returns "c", "d" $output = array_slice($input, -2, 1); // returns "d" $output = array_slice($input, 0, 3); // returns "a", "b", and "c" See also array_splice(). Note: This function was added in PHP 4.0. array_splice array_splice -- Remove a portion of the array and replace it with something else Description array array_splice(array input, int offset, int [length] , array [replacement]); array_splice() removed the elements designated by offset and length from the input array, and replaces them with the elements of the replacement array, if supplied. If offset is positive then the start of removed portion is at that offset from the beginning of the input array. If offset is negative then it starts that far from the end of the input array. If length is omitted, removes everything from offset to the end of the array. If length is specified and is positive, then that many elements will be removed. If length is specified and is negative then the end of the removed portion will be that many elements from the end of the array. Tip: to remove everything from offset to the end of the array when replacement is also specified, use count($input) for length. If replacement array is specified, then the removed elements are replaced with elements from this array. If offset and length are such that nothing is removed, then the elements from the replacement array are inserted in the place specified by the offset. Tip: if the replacement is just one element it is not necessary to put array() around it, unless the element is an array itself. The following equivalences hold: array_push($input, $x, $y) array_splice($input, count($input), 0, array($x, $y)) array_pop($input) array_splice($input, -1) array_shift($input) array_splice($input, 0, 1) array_unshift($input, $x, $y) array_splice($input, 0, 0, array($x, $y)) $a[$x] = $y array_splice($input, $x, 1, $y) Returns the array consisting of removed elements. Example 1. array_splice() examples $input = array("red", "green", "blue", "yellow"); array_splice($input, 2); // $input is now array("red", "green") array_splice($input, 1, -1); // $input is now array("red", "yellow") array_splice($input, 1, count($input), "orange"); // $input is now array("red", "orange") array_splice($input, -1, 1, array("black", "maroon")); // $input is now array("red", "green", "blue", "black", "maroon") See also array_slice(). Note: This function was added in PHP 4.0. array_merge array_merge -- Merge two or more arrays Description array array_merge(array array1, array array2, [ ...] ); array_merge() merges the elements of two or more arrays together so that the values of one are appended to the end of the previous one. It returns the resulting array. If the input arrays had the same string keys, then the later value for that key will overwrite previous one. If, however, the arrays have the same numeric key, this does not happen since the values are appended. Example 1. array_merge() example $array1 = array("color" => "red", 2, 4); $array2 = array("a", "b", "color" => "green", "shape" => "trapezoid"); array_merge($array1, $array2); Resulting array will be array("color" => "green", 2, 4, "a", "b", "shape" => "trapezoid"). Note: This function was added in PHP 4.0. array_keys array_keys -- Return all the keys of an array Description array array_keys(array input); array_keys() returns all the keys, numeric and string, from the input array. Example 1. array_keys() example $array = array(0 => 100, "color" => "red"); array_keys($array); // returns array(0, "color") See also array_values(). Note: This function was added in PHP 4.0. array_values array_values -- Return all the values of an array Description array array_values(array input); array_values() returns all the values from the input array. Example 1. array_values() example $array = array("size" => "XL", "color" => "gold"); array_values($array); // returns array("XL", "gold") Note: This function was added in PHP 4.0. array_walk array_walk -- Apply a user function to every member of an array. Description int array_walk(array arr, string func, mixed userdata); Applies the function named by func to each element of arr. func will be passed array value as the first parameter and array key as the second parameter. If userdata is supplied, it will be passed as the third parameter to the user function. If func requires more than two or three arguments, depending on userdata, a warning will be generated each time array_walk() calls func. These warnings may be suppressed by prepending the '@' sign to the array_walk() call, or by using error_reporting(). Note: If func needs to be working with the actual values of the array, specify that the first parameter of func should be passed by reference. Then any changes made to those elements will be made in the array itself. Example 1. array_walk() example $fruits = array("d"=>"lemon","a"=>"orange","b"=>"banana","c"=>"apple"); function test_alter( &$item1, $key, $prefix ) { $item1 = "$prefix: $item1"; } function test_print( $item2, $key ) { echo "$key. $item2
\n"; } array_walk( $fruits, 'test_print' ); array_walk( $fruits, 'test_alter', 'fruit' ); array_walk( $fruits, 'test_print' ); See also each() and list(). arsort arsort -- Sort an array in reverse order and maintain index association Description void arsort(array array); This function sorts an array such that array indices maintain their correlation with the array elements they are associated with. This is used mainly when sorting associative arrays where the actual element order is significant. Example 1. arsort() example $fruits = array("d"=>"lemon","a"=>"orange","b"=>"banana","c"=>"apple"); arsort($fruits); for(reset($fruits); $key = key($fruits); next($fruits)) { echo "fruits[$key] = ".$fruits[$key]."\n"; } This example would display: fruits[a] = orange fruits[d] = lemon fruits[b] = banana fruits[c] = apple The fruits have been sorted in reverse alphabetical order, and the index associated with each element has been maintained. See also: asort(), rsort(), ksort(), and sort(). asort asort -- Sort an array and maintain index association Description void asort(array array); This function sorts an array such that array indices maintain their correlation with the array elements they are associated with. This is used mainly when sorting associative arrays where the actual element order is significant. Example 1. asort() example $fruits = array("d"=>"lemon","a"=>"orange","b"=>"banana","c"=>"apple"); asort($fruits); for(reset($fruits); $key = key($fruits); next($fruits)) { echo "fruits[$key] = ".$fruits[$key]."\n"; } This example would display: fruits[c] = apple fruits[b] = banana fruits[d] = lemon fruits[a] = orange The fruits have been sorted in alphabetical order, and the index associated with each element has been maintained. See also arsort(), rsort(), ksort(), and sort(). compact compact -- Create array containing variables and their values Description array compact(string varname | array varnames, [...]); compact() takes a variable number of parameters. Each parameter can be either a string containing the name of the variable, or an array of variable names. The array can contain other arrays of variable names inside it; compact() handles it recursively. For each of these, compact() looks for a variable with that name in the current symbol table and adds it to the output array such that the variable name becomes the key and the contents of the variable become the value for that key. In short, it does the opposite of extract(). It returns the output array with all the variables added to it. Example 1. compact() example $city = "San Francisco"; $state = "CA"; $event = "SIGGRAPH"; $location_vars = array("city", "state"); $result = compact("event", $location_vars); After this, $result will be array("event" => "SIGGRAPH", "city" => "San Francisco", "state" => "CA"). See also extract(). Note: This function was added in PHP 4.0. count count -- count elements in a variable Description int count(mixed var); Returns the number of elements in var, which is typically an array (since anything else will have one element). Returns 1 if the variable is not an array. Returns 0 if the variable is not set. Warning count() may return 0 for a variable that isn't set, but it may also return 0 for a variable that has been initialized with an empty array. Use isset() to test if a variable is set. See also: sizeof(), isset(), and is_array(). current current -- Return the current element in an array Description mixed current(array array); Every array has an internal pointer to its "current" element, which is initialized to the first element inserted into the array. The current() function simply returns the array element that's currently being pointed by the internal pointer. It does not move the pointer in any way. If the internal pointer points beyond the end of the elements list, current() returns false. Warning If the array contains empty elements (0 or "", the empty string) then this function will return false for these elements as well. This makes it impossible to determine if you are really at the end of the list in such an array using current(). To properly traverse an array that may contain empty elements, use the each() function. See also: end(), next(), prev() and reset(). each each -- Return the next key and value pair from an array Description array each(array array); Returns the current key and value pair from the array array and advances the array cursor. This pair is returned in a four-element array, with the keys 0, 1, key, and value. Elements 0 and key contain the key name of the array element, and 1 and value contain the data. If the internal pointer for the array points past the end of the array contents, each() returns false. Example 1. each() examples $foo = array( "bob", "fred", "jussi", "jouni" ); $bar = each( $foo ); $bar now contains the following key/value pairs: * 0 => 0 * 1 => 'bob' * key => 0 * value => 'bob' $foo = array( "Robert" => "Bob", "Seppo" => "Sepi" ); $bar = each( $foo ); $bar now contains the following key/value pairs: * 0 => 'Robert' * 1 => 'Bob' * key => 'Robert' * value => 'Bob' each() is typically used in conjunction with list() to traverse an array; for instance, $HTTP_POST_VARS: Example 2. Traversing $HTTP_POST_VARS with each() echo "Values submitted via POST method:
"; while (list($key, $val) = each($HTTP_POST_VARS)) { echo "$key => $val
"; } After each() has executed, the array cursor will be left on the next element of the array, or on the last element if it hits the end of the array. See also key(), list(), current(), reset(), next(), and prev(). end end -- Set the internal pointer of an array to its last element Description end(array array); end() advances array's internal pointer to the last element. See also: current(), each(), end() next() and reset() extract extract -- Import variables into the symbol table from an array Description void extract(array var_array, int [extract_type], string [prefix]); This function is used to import variables from an array into the current symbol table. It takes associative array var_array and treats keys as variable names and values as variable values. For each key/value pair it will create a variable in the current symbol table, subject to extract_type and prefix parameters. extract() checks for colissions with existing variables. The way collisions are treated is determined by extract_type. It can be one of the following values: EXTR_OVERWRITE If there is a collision, overwrite the existing variable. EXTR_SKIP If there is a collision, don't overwrite the existing variable. EXTR_PREFIX_SAME If there is a collision, prefix the new variable with prefix. EXTR_PREFIX_ALL Prefix all variables with prefix. If extract_type is not specified, it is assumed to be EXTR_OVERWRITE. Note that prefix is only required if extract_type is EXTR_PREFIX_SAME or EXTR_PREFIX_ALL. extract() checks each key to see if it constitues a valid variable name, and if it does only then does it proceed to import it. A possible use for extract is to import into symbol table variables contained in an associative array returned by wddx_deserialize(). Example 1. extract example "blue", "size" => "medium", "shape" => "sphere"); extract($var_array, EXTR_PREFIX_SAME, "wddx"); print "$color, $size, $shape, $wddx_size\n"; ?> The above example will produce: blue, large, sphere, medium The $size wasn't overwritten, becaus we specified EXTR_PREFIX_SAME, which resulted in $wddx_size being created. If EXTR_SKIP was specified, then $wddx_size wouldn't even have been created. EXTR_OVERWRITE would have cause $size to have value "medium", and EXTR_PREFIX_ALL would result in new variables being named $wddx_color, $wddx_size, and $wddx_shape. in_array in_array -- Return true if a value exists in an array Description bool in_array(mixed needle, array haystack); Searches haystack for needle and returns true if it is found in the array, false otherwise. Example 1. in_array() example $os = array("Mac", "NT", "Irix", "Linux"); if (in_array("Irix", $os)) print "Got Irix"; Note: This function was added in PHP 4.0. key key -- Fetch a key from an associative array Description mixed key(array array); key() returns the index element of the current array position. See also: current(), next() ksort ksort -- Sort an array by key Description int ksort(array array); Sorts an array by key, maintaining key to data correlations. This is useful mainly for associative arrays. Example 1. ksort() example $fruits = array("d"=>"lemon","a"=>"orange","b"=>"banana","c"=>"apple"); ksort($fruits); for(reset($fruits); $key = key($fruits); next($fruits)) { echo "fruits[$key] = ".$fruits[$key]."\n"; } This example would display: fruits[a] = orange fruits[b] = banana fruits[c] = apple fruits[d] = lemon See also asort(), arsort(), sort(), and rsort(). list list -- Assign variables as if they were an array Description void list(...); Like array(), this is not really a function, but a language construct. list() is used to assign a list of variables in one operation. Example 1. list() example
| Employee name | Salary | $name | \n". "$salary | \n". " \n"); } ?>
|---|
"; } } V. Arbitrary precision mathematics functions These functions are only available if PHP was configured with --enable-bcmath. Table of Contents bcadd Ñ Add two arbitrary precision numbers. bccomp Ñ Compare two arbitrary precision numbers. bcdiv Ñ Divide two arbitrary precision numbers. bcmod Ñ Get modulus of an arbitrary precision number. bcmul Ñ Multiply two arbitrary precision number. bcpow Ñ Raise an arbitrary precision number to another. bcscale Ñ Set default scale parameter for all bc math functions. bcsqrt Ñ Get the square root of an arbitray precision number. bcsub Ñ Subtract one arbitrary precision number from another. bcadd bcadd -- Add two arbitrary precision numbers. Description string bcadd(string left operand, string right operand, int [scale]); Adds the left operand to the right operand and returns the sum in a string. The optional scale parameter is used to set the number of digits after the decimal place in the result. See also bcsub(). bccomp bccomp -- Compare two arbitrary precision numbers. Description int bccomp(string left operand, string right operand, int [scale]); Compares the left operand to the right operand and returns the result as an integer. The optional scale parameter is used to set the number of digits after the decimal place which will be used in the comparion. The return value is 0 if the two operands are equal. If the left operand is larger than the right operand the return value is +1 and if the left operand is less than the right operand the return value is -1. bcdiv bcdiv -- Divide two arbitrary precision numbers. Description string bcdiv(string left operand, string right operand, int [scale]); Divides the left operand by the right operand and returns the result. The optional scale sets the number of digits after the decimal place in the result. See also bcmul(). bcmod bcmod -- Get modulus of an arbitrary precision number. Description string bcmod(string left operand, string modulus); Get the modulus of the left operand using modulus. See also bcdiv(). bcmul bcmul -- Multiply two arbitrary precision number. Description string bcmul(string left operand, string right operand, int [scale]); Multiply the left operand by the right operand and returns the result. The optional scale sets the number of digits after the decimal place in the result. See also bcdiv(). bcpow bcpow -- Raise an arbitrary precision number to another. Description string bcpow(string x, string y, int [scale]); Raise x to the power y. The scale can be used to set the number of digits after the decimal place in the result. See also bcsqrt(). bcscale bcscale -- Set default scale parameter for all bc math functions. Description string bcscale(int scale); This function sets the default scale parameter for all subsequent bc math functions that do not explicitly specify a scale parameter. bcsqrt bcsqrt -- Get the square root of an arbitray precision number. Description string bcsqrt(string operand, int scale); Return the square root of the operand. The optional scale parameter sets the number of digits after the decimal place in the result. See also bcpow(). bcsub bcsub -- Subtract one arbitrary precision number from another. Description string bcsub(string left operand, string right operand, int [scale]); Subtracts the right operand from the left operand and returns the result in a string. The optional scale parameter is used to set the number of digits after the decimal place in the result. See also bcadd(). VI. Calendar functions The calendar functions are only available if you have compiled the calendar extension in dl/calendar. Read dl/README for instructions on using it. The calendar extension presents a series of functions to simplify converting between different calendar formats. The intermediary or standard it is based on is the Julian Day Count. The Julian Day Count is a count of days starting way earlier than any date most people would need to track (somewhere around 4000bc). To convert between calendar systems, you must first convert to Julian Day Count, then to the calendar system of your choice. Julian Day Count is very different from the Julian Calendar! For more information on calendar systems visit http://genealogy.org/~scottlee/cal-overview.html. Excerpts from this page are included in these instructions, and are in quotes. Table of Contents JDToGregorian Ñ Converts Julian Day Count to Gregorian date GregorianToJD Ñ Converts a Gregorian date to Julian Day Count JDToJulian Ñ Converts a Julian Calendar date to Julian Day Count JulianToJD Ñ Converts a Julian Calendar date to Julian Day Count JDToJewish Ñ Converts a Julian Day Count to the Jewish Calendar JewishToJD Ñ Converts a date in the Jewish Calendar to Julian Day Count JDToFrench Ñ Converts a Julian Day Count to the French Republican Calendar FrenchToJD Ñ Converts a date from the French Republican Calendar to a Julian Day Count JDMonthName Ñ Returns a month name JDDayOfWeek Ñ Returns the day of the week easter_date Ñ get UNIX timestamp for midnight on Easter of a given year easter_days Ñ get number of days after March 21 on which Easter falls for a given year JDToGregorian JDToGregorian -- Converts Julian Day Count to Gregorian date Description string jdtogregorian(int julianday); Converts Julian Day Count to a string containing the Gregorian date in the format of "month/day/year" GregorianToJD GregorianToJD -- Converts a Gregorian date to Julian Day Count Description int gregoriantojd(int month, int day, int year); Valid Range for Gregorian Calendar 4714 B.C. to 9999 A.D. Although this software can handle dates all the way back to 4714 B.C., such use may not be meaningful. The Gregorian calendar was not instituted until October 15, 1582 (or October 5, 1582 in the Julian calendar). Some countries did not accept it until much later. For example, Britain converted in 1752, The USSR in 1918 and Greece in 1923. Most European countries used the Julian calendar prior to the Gregorian. Example 1. Calendar functions JDToJulian JDToJulian -- Converts a Julian Calendar date to Julian Day Count Description string jdtojulian(int julianday); Converts Julian Day Count to a string containing the Julian Calendar Date in the format of "month/day/year". JulianToJD JulianToJD -- Converts a Julian Calendar date to Julian Day Count Description int juliantojd(int month, int day, int year); Valid Range for Julian Calendar 4713 B.C. to 9999 A.D. Although this software can handle dates all the way back to 4713 B.C., such use may not be meaningful. The calendar was created in 46 B.C., but the details did not stabilize until at least 8 A.D., and perhaps as late at the 4th century. Also, the beginning of a year varied from one culture to another - not all accepted January as the first month. JDToJewish JDToJewish -- Converts a Julian Day Count to the Jewish Calendar Description string jdtojewish(int julianday); Converts a Julian Day Count the the Jewish Calendar. JewishToJD JewishToJD -- Converts a date in the Jewish Calendar to Julian Day Count Description int jewishtojd(int month, int day, int year); Valid Range Although this software can handle dates all the way back to the year 1 (3761 B.C.), such use may not be meaningful. The Jewish calendar has been in use for several thousand years, but in the early days there was no formula to determine the start of a month. A new month was started when the new moon was first observed. JDToFrench JDToFrench -- Converts a Julian Day Count to the French Republican Calendar Description string jdtofrench(int month, int day, int year); Converts a Julian Day Count to the French Republican Calendar. FrenchToJD FrenchToJD -- Converts a date from the French Republican Calendar to a Julian Day Count Description int frenchtojd(int month, int day, int year); Converts a date from the French Republican Calendar to a Julian Day Count These routines only convert dates in years 1 through 14 (Gregorian dates 22 September 1792 through 22 September 1806). This more than covers the period when the calendar was in use. JDMonthName JDMonthName -- Returns a month name Description string jdmonthname(int julianday, int mode); Returns a string containing a month name. mode tells this function which calendar to convert the Julian Day Count to, and what type of month names are to be returned. Table 1. Calendar modes ModeMeaning 0 Gregorian - apreviated 1 Gregorian 2 Julian - apreviated 3 Julian 4 Jewish 5 French Republican JDDayOfWeek JDDayOfWeek -- Returns the day of the week Description mixed jddayofweek(int julianday, int mode); Returns the day of the week. Can return a string or an int depending on the mode. Table 1. Calendar week modes ModeMeaning 0 returns the day number as an int (0=sunday, 1=monday, etc) 1 returns string containing the day of week (english-gregorian) 2 returns a string containing the abreviated day of week (english-gregorian) easter_date easter_date -- get UNIX timestamp for midnight on Easter of a given year Description int easter_date(int year); Returns the UNIX timestamp corresponding to midnight on Easter of the given year. If no year is specified, the current year is assumed. Warning: This function will generate a warning if the year is outside of the range for UNIX timestamps (i.e. before 1970 or after 2037). Example 1. easter_date() example echo date( "M-d-Y", easter_date(1999) ); /* "Apr-04-1999" */ echo date( "M-d-Y", easter_date(2000) ); /* "Apr-23-2000" */ echo date( "M-d-Y", easter_date(2001) ); /* "Apr-15-2001" */ The date of Easter Day was defined by the Council of Nicaea in AD325 as the Sunday after the first full moon which falls on or after the Spring Equinox. The Equinox is assumed to always fall on 21st March, so the calculation reduces to determining the date of the full moon and the date of the following Sunday. The algorithm used here was introduced around the year 532 by Dionysius Exiguus. Under the Julian Calendar (for years before 1753) a simple 19-year cycle is used to track the phases of the Moon. Under the Gregorian Calendar (for years after 1753 - devised by Clavius and Lilius, and introduced by Pope Gregory XIII in October 1582, and into Britain and its then colonies in September 1752) two correction factors are added to make the cycle more accurate. (The code is based on a C program by Simon Kershaw,
\n"; } dbase_numrecords dbase_numrecords -- find out how many records are in a dBase database Description int dbase_numrecords(int dbase_identifier); Returns the number of records (rows) in the specified database. Record numbers are between 1 and dbase_numrecords($db), while field numbers are between 0 and dbase_numfields($db)-1. XI. dbm functions These functions allow you to store records stored in a dbm-style database. This type of database (supported by the Berkeley db, gdbm, and some system libraries, as well as a built-in flatfile library) stores key/value pairs (as opposed to the full-blown records supported by relational databases). Example 1. dbm example $dbm = dbmopen("lastseen", "w"); if (dbmexists($dbm, $userid)) { $last_seen = dbmfetch($dbm, $userid); } else { dbminsert($dbm, $userid, time()); } do_stuff(); dbmreplace($dbm, $userid, time()); dbmclose($dbm); Table of Contents dbmopen Ñ opens a dbm database dbmclose Ñ closes a dbm database dbmexists Ñ tells if a value exists for a key in a dbm database dbmfetch Ñ fetches a value for a key from a dbm database dbminsert Ñ inserts a value for a key in a dbm database dbmreplace Ñ replaces the value for a key in a dbm database dbmdelete Ñ deletes the value for a key from a dbm database dbmfirstkey Ñ retrieves the first key from a dbm database dbmnextkey Ñ retrieves the next key from a dbm database dblist Ñ describes the dbm-compatible library being used dbmopen dbmopen -- opens a dbm database Description int dbmopen(string filename, string flags); The first argument is the full-path filename of the dbm file to be opened and the second is the file open mode which is one of "r", "n", "c" or "w" for read-only, new (implies read-write, and most likely will truncate an already-existing database of the same name), create (implies read-write, and will not truncate an already-existing database of the same name) and read-write respectively. Returns an identifer to be passed to the other dbm functions on success, or false on failure. If ndbm support is used, ndbm will actually create filename.dir and filename.pag files. gdbm only uses one file, as does the internal flat-file support, and Berkeley db creates a filename.db file. Note that PHP does its own file locking in addition to any file locking that may be done by the dbm library itself. PHP does not delete the .lck files it creates. It uses these files simply as fixed inodes on which to do the file locking. For more information on dbm files, see your Unix man pages, or obtain GNU's gdbm from ftp://prep.ai.mit.edu/pub/gnu. dbmclose dbmclose -- closes a dbm database Description bool dbmclose(int dbm_identifier); Unlocks and closes the specified database. dbmexists dbmexists -- tells if a value exists for a key in a dbm database Description bool dbmexists(int dbm_identifier, string key); Returns true if there is a value associated with the key. dbmfetch dbmfetch -- fetches a value for a key from a dbm database Description string dbmfetch(int dbm_identifier, string key); Returns the value associated with key. dbminsert dbminsert -- inserts a value for a key in a dbm database Description int dbminsert(int dbm_identifier, string key, string value); Adds the value to the database with the specified key. Returns -1 if the database was opened read-only, 0 if the insert was successful, and 1 if the specified key already exists. (To replace the value, use dbmreplace().) dbmreplace dbmreplace -- replaces the value for a key in a dbm database Description bool dbmreplace(int dbm_identifier, string key, string value); Replaces the value for the specified key in the database. This will also add the key to the database if it didn't already exist. dbmdelete dbmdelete -- deletes the value for a key from a dbm database Description bool dbmdelete(int dbm_identifier, string key); Deletes the value for key in the database. Returns false if the key didn't exist in the database. dbmfirstkey dbmfirstkey -- retrieves the first key from a dbm database Description string dbmfirstkey(int dbm_identifier); Returns the first key in the database. Note that no particular order is guaranteed since the database may be built using a hash-table, which doesn't guarantee any ordering. dbmnextkey dbmnextkey -- retrieves the next key from a dbm database Description string dbmnextkey(int dbm_identifier, string key); Returns the next key after key. By calling dbmfirstkey() followed by successive calls to dbmnextkey() it is possible to visit every key/value pair in the dbm database. For example: Example 1. Visiting every key/value pair in a dbm database. $key = dbmfirstkey($dbm_id); while ($key) { echo "$key = " . dbmfetch($dbm_id, $key) . "\n"; $key = dbmnextkey($dbm_id, $key); } dblist dblist -- describes the dbm-compatible library being used Description string dblist(void); XII. Directory functions Table of Contents chdir Ñ change directory dir Ñ directory class closedir Ñ close directory handle opendir Ñ open directory handle readdir Ñ read entry from directory handle rewinddir Ñ rewind directory handle chdir chdir -- change directory Description int chdir(string directory); Changes PHP's current directory to directory. Returns FALSE if unable to change directory, TRUE otherwise. dir dir -- directory class Description new dir(string directory); A pseudo-object oriented mechanism for reading a directory. The given directory is opened. Two properties are available once directory has been opened. The handle property can be used with other directory functions such as readdir(), rewinddir() and closedir(). The path property is set to path the directory that was opened. Three methods are available: read, rewind and close. Example 1. Dir() Example $d = dir("/etc"); echo "Handle: ".$d->handle."
\n"; echo "Path: ".$d->path."
\n"; while($entry=$d->read()) { echo $entry."
\n"; } $d->close(); closedir closedir -- close directory handle Description void closedir(int dir_handle); Closes the directory stream indicated by dir_handle. The stream must have previously been opened by opendir(). opendir opendir -- open directory handle Description int opendir(string path); Returns a directory handle to be used in subsequent closedir(), readdir(), and rewinddir() calls. readdir readdir -- read entry from directory handle Description string readdir(int dir_handle); Returns the filename of the next file from the directory. The filenames are not returned in any particular order. Example 1. List all files in the current directory rewinddir rewinddir -- rewind directory handle Description void rewinddir(int dir_handle); Resets the directory stream indicated by dir_handle to the beginning of the directory. XIII. Dynamic Loading functions Table of Contents dl Ñ load a PHP extension at runtime dl dl -- load a PHP extension at runtime Description int dl(string library); Loads the PHP extension defined in library. See also the extension_dir configuration directive. XIV. Program Execution functions Table of Contents escapeshellcmd Ñ escape shell metacharacters exec Ñ Execute an external program system Ñ Execute an external program and display output passthru Ñ Execute an external program and display raw output escapeshellcmd 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. A standard use would be: system(EscapeShellCmd($cmd)) exec exec -- Execute an external program Description string exec(string command, string [array], 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 interference, use the PassThru() function. If the array argument is present, then the specified array will be filled with every line of output from the command. 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 exec(). 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. Note that if you are going to allow data coming from user input to be passed to this function, then you should be using EscapeShellCmd() to make sure that users cannot trick the system into executing arbitrary commands. See also system(), PassThru(), popen() and EscapeShellCmd(). system 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. Note, that if you are going to allow data coming from user input to be passed to this function, then you should be using the EscapeShellCmd() function to make sure that users cannot trick the system into executing arbitrary commands. 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. 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 the exec() and popen() functions. passthru passthru -- Execute an external program and display raw output Description string 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 System() 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 images directly. See also exec() and fpassthru(). XV. Forms Data Format functions Forms Data Format (FDF) is a format for handling forms within PDF documents. You should read the documentation at http://partners.adobe.com/asn/developer/acrosdk/main.html for more information on what FDF is and how it is used in general. Note: Currently Adobe only provides a libc5 compatible version for Linux. Tests with glibc2 resulted in a segmentation fault. If somebody is able to make it work, please comment on this page. The general idea of FDF is similar to HTML forms. The diffence is basically the format how filled in data is transmitted to the server when the submit button is pressed (this is actually the Form Data Format) and the format of the form itself (which is the Portable Document Format, PDF). Processing the FDF data is one of the features provided by the fdf functions. But there is more. One may as well take an existing PDF form and populated the input fields with data without modifying the form itself. In such a case one would create a FDF document (fdf_create()) set the values of each input field (fdf_set_value()) and associate it with a PDF form (fdf_set_file()). Finally it has to be sent to the browser with MimeType application/vnd.fdf. The Acrobat reader plugin of your browser recognizes the MimeType, reads the associated PDF form and fills in the data from the FDF document. The following examples shows just the evaluation of form data. Example 1. Evaluating a FDF document $volume'
"; $date = fdf_get_value($fdf, "date"); echo "The date field has the value '$date'
"; $comment = fdf_get_value($fdf, "comment"); echo "The comment field has the value '$comment'
"; if(fdf_get_value($fdf, "show_publisher") == "On") { $publisher = fdf_get_value($fdf, "publisher"); echo "The publisher field has the value '$publisher'
"; } else echo "Publisher shall not be shown.
"; if(fdf_get_value($fdf, "show_preparer") == "On") { $preparer = fdf_get_value($fdf, "preparer"); echo "The preparer field has the value '$preparer'
"; } else echo "Preparer shall not be shown.
"; fdf_close($fdf); ?> Table of Contents fdf_open Ñ Open a FDF document fdf_close Ñ Close an FDF document fdf_create Ñ Create a new FDF document fdf_save Ñ Save a FDF document fdf_get_value Ñ Get the value of a field fdf_set_value Ñ Set the value of a field fdf_next_field_name Ñ Get the next field name fdf_set_ap Ñ Set the appearance of a field fdf_set_status Ñ Set the value of the /STATUS key fdf_get_status Ñ Get the value of the /STATUS key fdf_set_file Ñ Set the value of the /F key fdf_get_file Ñ Get the value of the /F key fdf_open fdf_open -- Open a FDF document Description int fdf_open(string filename); The fdf_open() function opens a file with form data. This file must contain the data as returned from a PDF form. Currently, the file has to be created 'manually' by using fopen() and writing the content of HTTP_FDF_DATA with fwrite() into it. A mechanism like for HTML form data where for each input field a variable is created does not exist. Example 1. Accessing the form data See also fdf_close(). fdf_close fdf_close -- Close an FDF document Description void fdf_close(int fdf_document); The fdf_close() function closes the FDF document. See also fdf_open(). fdf_create fdf_create -- Create a new FDF document Description int fdf_create(void ); The fdf_create() creates a new FDF document. This function is needed if one would like to populate input fields in a PDF document with data. Example 1. Populating a PDF document See also fdf_close(), fdf_save(), fdf_open(). fdf_save fdf_save -- Save a FDF document Description int fdf_save(string filename); The fdf_save() function saves a FDF document. The FDF Toolkit provides a way to output the document to stdout if the parameter filename is '.'. This does not work if PHP is used as an apache module. In such a case one will have to write to a file and use e.g. fpassthru(). to output it. See also fdf_close() and example for fdf_create(). fdf_get_value fdf_get_value -- Get the value of a field Description string fdf_get_value(int fdf_document, string fieldname); The fdf_get_value() function returns the value of a field. See also fdf_set_value(). fdf_set_value fdf_set_value -- Set the value of a field Description void fdf_set_value(int fdf_document, string fieldname, string value, int isName); The fdf_set_value() function sets the value of a field. The last parameter determines if the field value is to be converted to a PDF Name (isName = 1) or set to a PDF String (isName = 0). See also fdf_get_value(). fdf_next_field_name fdf_next_field_name -- Get the next field name Description string fdf_next_field_name(int fdf_document, string fieldname); The fdf_next_field_name() function returns the name of the field after the field in fieldname or the field name of the first field if the second paramter is NULL. See also fdf_set_field(), fdf_get_field(). fdf_set_ap fdf_set_ap -- Set the appearance of a field Description void fdf_set_ap(int fdf_document, string field_name, int face, string filename, int page_number); The fdf_set_ap() function sets the appearance of a field (i.e. the value of the /AP key). The possible values of face are 1=FDFNormalAP, 2=FDFRolloverAP, 3=FDFDownAP. fdf_set_status fdf_set_status -- Set the value of the /STATUS key Description void fdf_set_status(int fdf_document, string status); The fdf_set_status() sets the value of the /STATUS key. See also fdf_get_status(). fdf_get_status fdf_get_status -- Get the value of the /STATUS key Description string fdf_get_status(int fdf_document); The fdf_get_status() returns the value of the /STATUS key. See also fdf_set_status(). fdf_set_file fdf_set_file -- Set the value of the /F key Description void fdf_set_file(int fdf_document, string filename); The fdf_set_file() sets the value of the /F key. The /F key is just a reference to a PDF form which is to be populated with data. In a web environment it is a URL (e.g. http:/testfdf/resultlabel.pdf). See also fdf_get_file() and example for fdf_create(). fdf_get_file fdf_get_file -- Get the value of the /F key Description string fdf_get_file(int fdf_document); The fdf_set_file() returns the value of the /F key. See also fdf_set_file(). XVI. filePro functions These functions allow read-only access to data stored in filePro databases. filePro is a registered trademark of Fiserv, Inc. You can find more information about filePro at http://www.fileproplus.com/. Table of Contents filepro Ñ read and verify the map file filepro_fieldname Ñ gets the name of a field filepro_fieldtype Ñ gets the type of a field filepro_fieldwidth Ñ gets the width of a field filepro_retrieve Ñ retrieves data from a filePro database filepro_fieldcount Ñ find out how many fields are in a filePro database filepro_rowcount Ñ find out how many rows are in a filePro database filepro filepro -- read and verify the map file Description bool filepro(string directory); This reads and verifies the map file, storing the field count and info. No locking is done, so you should avoid modifying your filePro database while it may be opened in PHP. filepro_fieldname filepro_fieldname -- gets the name of a field Description string filepro_fieldname(int field_number); Returns the name of the field corresponding to field_number. filepro_fieldtype filepro_fieldtype -- gets the type of a field Description string filepro_fieldtype(int field_number); Returns the edit type of the field corresponding to field_number. filepro_fieldwidth filepro_fieldwidth -- gets the width of a field Description int filepro_fieldwidth(int field_number); Returns the width of the field corresponding to field_number. filepro_retrieve filepro_retrieve -- retrieves data from a filePro database Description string filepro_retrieve(int row_number, int field_number); Returns the data from the specified location in the database. filepro_fieldcount filepro_fieldcount -- find out how many fields are in a filePro database Description int filepro_fieldcount(void); Returns the number of fields (columns) in the opened filePro database. See also filepro(). filepro_rowcount filepro_rowcount -- find out how many rows are in a filePro database Description int filepro_rowcount(void); Returns the number of rows in the opened filePro database. See also filepro(). XVII. Filesystem functions Table of Contents basename Ñ return filename component of path chgrp Ñ change file group chmod Ñ change file mode chown Ñ change file owner clearstatcache Ñ clear file stat cache copy Ñ copy file delete Ñ a dummy manual entry dirname Ñ return directory name component of path diskfreespace Ñ return available space in directory fclose Ñ close an open file pointer feof Ñ test for end-of-file on a file pointer fgetc Ñ get character from file pointer fgetcsv Ñ get line from file pointer and parse for CSV fields fgets Ñ get line from file pointer fgetss Ñ get line from file pointer and strip HTML tags file Ñ read entire file into an array file_exists Ñ Check whether a file exists. fileatime Ñ get last access time of file filectime Ñ get inode change time of file filegroup Ñ get file group fileinode Ñ get file inode filemtime Ñ get file modification time fileowner Ñ get file owner fileperms Ñ get file permissions filesize Ñ get file size filetype Ñ get file type flock Ñ portable advisory file locking fopen Ñ open file or URL fpassthru Ñ output all remaining data on a file pointer fputs Ñ write to a file pointer fread Ñ Binary-safe file read fseek Ñ seek on a file pointer ftell Ñ tell file pointer read/write position fwrite Ñ Binary-safe file write set_file_buffer Ñ Sets file buffering on the given file pointer is_dir Ñ tells whether the filename is a directory is_executable Ñ tells whether the filename is executable is_file Ñ tells whether the filename is a regular file is_link Ñ tells whether the filename is a symbolic link is_readable Ñ tells whether the filename is readable is_writeable Ñ tells whether the filename is writeable link Ñ Create a hard link linkinfo Ñ Get information about a link mkdir Ñ make directory pclose Ñ close process file pointer popen Ñ open process file pointer readfile Ñ output a file readlink Ñ Return the target of a symbolic link rename Ñ rename a file rewind Ñ rewind the position of a file pointer rmdir Ñ remove directory stat Ñ give information about a file lstat Ñ give information about a file or symbolic link symlink Ñ Create a symbolic link tempnam Ñ create unique file name touch Ñ set modification time of file umask Ñ changes the current umask unlink Ñ Delete a file basename basename -- return filename component of path Description string basename(string path); Given a string containing a path to a file, this function will return the base name of the file. On Windows, both slash (/) and backslash (\) are used as path separator character. In other environments, it is the forward slash (/). Example 1. basename() example $path = "/home/httpd/html/index.php3"; $file = basename($path); // $file is set to "index.php3" See also: dirname() chgrp chgrp -- change file group Description int chgrp(string filename, mixed group); Attempts to change the group of the file filename to group. Only the superuser may change the group of a file arbitrarily; other users may change the group of a file to any group of which that user is a member. Returns true on success; otherwise returns false. On Windows, does nothing and returns true. See also chown() and chmod(). chmod chmod -- change file mode Description int chmod(string filename, int mode); Attempts to change the mode of the file specified by filename to that given in mode. Note that mode is not automatically assumed to be an octal value. To ensure the expected operation, you need to prefix mode with a zero (0): chmod( "/somedir/somefile", 755 ); // decimal; probably incorrect chmod( "/somedir/somefile", 0755 ); // octal; correct value of mode Returns true on success and false otherwise. See also chown() and chgrp(). chown chown -- change file owner Description int chown(string filename, mixed user); Attempts to change the owner of the file filename to user user. Only the superuser may change the owner of a file. Returns true on success; otherwise returns false. Note: On Windows, does nothing and returns true. See also chown() and chmod(). clearstatcache clearstatcache -- clear file stat cache Description void clearstatcache(void); Invoking the stat or lstat system call on most systems is quite expensive. Therefore, the result of the last call to any of the status functions (listed below) is stored for use on the next such call using the same filename. If you wish to force a new status check, for instance if the file is being checked many times and may change or disappear, use this function to clear the results of the last call from memory. This value is only cached for the lifetime of a single request. Affected functions include stat(), lstat(), file_exists(), is_writeable(), is_readable(), is_executable(), is_file(), is_dir(), is_link(), filectime(), fileatime(), filemtime(), fileinode(), filegroup(), fileowner(), filesize(), filetype(), and fileperms(). copy copy -- copy file Description int copy(string source, string dest); Makes a copy of a file. Returns true if the copy succeeded, false otherwise. Example 1. copy() example if (!copy($file, $file.'.bak')) { print("failed to copy $file...
\n"); } See also: rename() delete delete -- a dummy manual entry Description void delete(string file); This is a dummy manual entry to satisfy those people who are looking for unlink() or unset() in the wrong place. See also: unlink() to delete files, unset() to delete variables. dirname dirname -- return directory name component of path Description string dirname(string path); Given a string containing a path to a file, this function will return the name of the directory. On Windows, both slash (/) and backslash (\) are used as path separator character. In other environments, it is the forward slash (/). Example 1. dirname() example $path = "/etc/passwd"; $file = dirname($path); // $file is set to "/etc" See also: basename() diskfreespace diskfreespace -- return available space in directory Description float diskfreespace(string directory); Given a string containing a directory, this function will return the number of bytes available on the corresponding disk. Example 1. diskfreespace() example $df = diskfreespace("/"); // $df contains the number of bytes available on "/" fclose fclose -- close an open file pointer Description int fclose(int fp); The file pointed to by fp is closed. Returns true on success and false on failure. The file pointer must be valid, and must point to a file successfully opened by fopen() or fsockopen(). feof feof -- test for end-of-file on a file pointer Description int feof(int fp); Returns true if the file pointer is at EOF or an error occurs; otherwise returns false. The file pointer must be valid, and must point to a file successfully opened by fopen(), popen(), or fsockopen(). fgetc fgetc -- get character from file pointer Description string fgetc(int fp); Returns a string containing a single character read from the file pointed to by fp. Returns FALSE on EOF (as does feof()). The file pointer must be valid, and must point to a file successfully opened by fopen(), popen(), or fsockopen(). See also fread(), fopen(), popen(), fsockopen(), and fgets(). fgetcsv fgetcsv -- get line from file pointer and parse for CSV fields Description array fgetcsv(int fp, int length, string [delimiter]); Similar to fgets() except that fgetcsv() parses the line it reads for fields in CSV format and returns an array containing the fields read. The field delimiter is a comma, unless you specifiy another delimiter with the optional third parameter. fp must be a valid file pointer to a file successfully opened by fopen(), popen(), or fsockopen() length must be greater than the longest line to be found in the CSV file (allowing for trailing line-end characters). fgetcsv() returns false on error, including end of file. NB A blank line in a CSV file will be returned as an array comprising just one single null field, and will not be treated as an error. Example 1. fgetcsv() example - Read and print entire contents of a CSV file $row=1; $fp = fopen("test.csv","r"); while ($data = fgetcsv($fp,1000, ",")) { $num = count($data); print "
$num fields in line $row:
";
$row++;
for ( $c=0; $c<$num; $c++ ) print $data[$c] . "
";
}
fclose($fp);
fgets
fgets -- get line from file pointer
Description
string fgets(int fp, int length);
Returns a string of up to length - 1 bytes read from the file pointed to by
fp. Reading ends when length - 1 bytes have been read, on a newline (which
is included in the return value), or on EOF (whichever comes first).
If an error occurs, returns false.
Common Pitfalls:
People used to the 'C' semantics of fgets should note the difference in how
EOF is returned.
The file pointer must be valid, and must point to a file successfully opened
by fopen(), popen(), or fsockopen().
A simple example follows:
Example 1. Reading a file line by line
$fd = fopen("/tmp/inputfile.txt", "r");
while ($buffer = fgets($fd, 4096)) {
echo $buffer;
}
fclose($fd);
See also fread(), fopen(), popen(), fgetc(), and fsockopen().
fgetss
fgetss -- get line from file pointer and strip HTML tags
Description
string fgetss(int fp, int length);
Identical to fgets(), except that fgetss attempts to strip any HTML and PHP
tags from the text it reads.
See also fgets(), fopen(), fsockopen(), popen(), and strip_tags().
file
file -- read entire file into an array
Description
array file(string filename);
Identical to readfile(), except that file() returns the file in an array.
Each element of the array corresponds to a line in the file, with the
newline still attached.
See also readfile(), fopen(), and popen().
file_exists
file_exists -- Check whether a file exists.
Description
int file_exists(string filename);
Returns true if the file specified by filename exists; false otherwise.
The results of this function are cached. See clearstatcache() for more
details.
fileatime
fileatime -- get last access time of file
Description
int fileatime(string filename);
Returns the time the file was last accessed, or false in case of an error.
The results of this function are cached. See clearstatcache() for more
details.
filectime
filectime -- get inode change time of file
Description
int filectime(string filename);
Returns the time the file was last changed, or false in case of an error.
The results of this function are cached. See clearstatcache() for more
details.
filegroup
filegroup -- get file group
Description
int filegroup(string filename);
Returns the group ID of the owner of the file, or false in case of an error.
The results of this function are cached. See clearstatcache() for more
details.
fileinode
fileinode -- get file inode
Description
int fileinode(string filename);
Returns the inode number of the file, or false in case of an error.
The results of this function are cached. See clearstatcache() for more
details.
filemtime
filemtime -- get file modification time
Description
int filemtime(string filename);
Returns the time the file was last modified, or false in case of an error.
The results of this function are cached. See clearstatcache() for more
details.
fileowner
fileowner -- get file owner
Description
int fileowner(string filename);
Returns the user ID of the owner of the file, or false in case of an
The results of this function are cached. See clearstatcache() for more
details. error.
fileperms
fileperms -- get file permissions
Description
int fileperms(string filename);
Returns the permissions on the file, or false in case of an error.
The results of this function are cached. See clearstatcache() for more
details.
filesize
filesize -- get file size
Description
int filesize(string filename);
Returns the size of the file, or false in case of an error.
The results of this function are cached. See clearstatcache() for more
details.
filetype
filetype -- get file type
Description
string filetype(string filename);
Returns the type of the file. Possible values are fifo, char, dir, block,
link, file, and unknown.
Returns false if an error occurs.
The results of this function are cached. See clearstatcache() for more
details.
flock
flock -- portable advisory file locking
Description
bool flock(int fp, int operation);
PHP supports a portable way of locking complete files in an advisory way
(which means all accessing programs have to use the same way of locking or
it will not work).
flock() operates on fp which must be an open file pointer. operation is one
of the following values:
* To acquire a shared lock (reader), set operation to 1.
* To acquire an exclusive lock (writer), set operation to 2.
* To release a lock (shared or exclusive), set operation to 3.
* If you don't want flock() to block while locking, add 4 to operation.
flock() allows you to perform a simple reader/writer model which can be used
on virtually every platform (including most Unices and even Windows).
flock() returns true on success and false on error (e.g. when a lock could
not be acquired).
fopen
fopen -- open file or URL
Description
int fopen(string filename, string mode);
If filename begins with "http://" (not case sensitive), an HTTP 1.0
connection is opened to the specified server and a file pointer is returned
to the beginning of the text of the response.
Does not handle HTTP redirects, so you must include trailing slashes on
directories.
If filename begins with "ftp://" (not case sensitive), an ftp connection to
the specified server is opened and a pointer to the requested file is
returned. If the server does not support passive mode ftp, this will fail.
You can open files for either reading and writing via ftp (but not both
simultaneously).
If filename begins with anything else, the file will be opened from the
filesystem, and a file pointer to the file opened is returned.
If the open fails, the function returns false.
mode may be any of the following:
* 'r' - Open for reading only; place the file pointer at the beginning of
the file.
* 'r+' - Open for reading and writing; place the file pointer at the
beginning of the file.
* 'w' - Open for writing only; place the file pointer at the beginning of
the file and truncate the file to zero length. If the file does not
exist, attempt to create it.
* 'w+' - Open for reading and writing; place the file pointer at the
beginning of the file and truncate the file to zero length. If the file
does not exist, attempt to create it.
* 'a' - Open for writing only; place the file pointer at the end of the
file. If the file does not exist, attempt to create it.
* 'a+' - Open for reading and writing; place the file pointer at the end
of the file. If the file does not exist, attempt to create it.
As well, mode may contain the letter 'b'. This is useful only on systems
which differentiate between binary and text files (i.e., it's useless on
Unix). If not needed, this will be ignored.
Example 1. fopen() example
$fp = fopen("/home/rasmus/file.txt", "r");
$fp = fopen("http://www.php.net/", "r");
$fp = fopen("ftp://user:password@example.com/", "w");
If you are experiencing problems with reading and writing to files and
you're using the server module version of PHP, remember to make sure that
the files and directories you're using are accessible to the server process.
On the Windows platform, be careful to escape any backslashes used in the
path to the file, or use forward slashes.
$fp = fopen("c:\\data\\info.txt", "r");
See also fclose(), fsockopen(), and popen().
fpassthru
fpassthru -- output all remaining data on a file pointer
Description
int fpassthru(int fp);
Reads to EOF on the given file pointer and writes the results to standard
output.
If an error occurs, fpassthru() returns false.
The file pointer must be valid, and must point to a file successfully opened
by fopen(), popen(), or fsockopen(). The file is closed when fpassthru() is
done reading it (leaving fp useless).
If you just want to dump the contents of a file to stdout you may want to
use the readfile(), which saves you the fopen() call.
See also readfile(), fopen(), popen(), and fsockopen()
fputs
fputs -- write to a file pointer
Description
int fputs(int fp, string str, int [length]);
fputs() is an alias to fwrite(), and is identical in every way. Note that
the length parameter is optional and if not specified the entire string will
be written.
fread
fread -- Binary-safe file read
Description
string fread(int fp, int length);
fread() reads up to length bytes from the file pointer referenced by fp.
Reading stops when length bytes have been read or EOF is reached, whichever
comes first.
// get contents of a file into a string
$filename = "/usr/local/something.txt";
$fd = fopen( $filename, "r" );
$contents = fread( $fd, filesize( $filename ) );
fclose( $fd );
See also fwrite(), fopen(), fsockopen(), popen(), fgets(), fgetss(), file(),
and fpassthru().
fseek
fseek -- seek on a file pointer
Description
int fseek(int fp, int offset);
Sets the file position indicator for the file referenced by fp to offset
bytes into the file stream. Equivalent to calling (in C) fseek( fp, offset,
SEEK_SET ).
Upon success, returns 0; otherwise, returns -1. Note that seeking past EOF
is not considered an error.
May not be used on file pointers returned by fopen() if they use the
"http://" or "ftp://" formats.
See also ftell() and rewind().
ftell
ftell -- tell file pointer read/write position
Description
int ftell(int fp);
Returns the position of the file pointer referenced by fp; i.e., its offset
into the file stream.
If an error occurs, returns false.
The file pointer must be valid, and must point to a file successfully opened
by fopen() or popen().
See also fopen(), popen(), fseek() and rewind().
fwrite
fwrite -- Binary-safe file write
Description
int fwrite(int fp, string string, int [length]);
fwrite() writes the contents of string to the file stream pointed to by fp.
If the length argument is given, writing will stop after length bytes have
been written or the end of string is reached, whichever comes first.
Note that if the length argument is given, then the magic_quotes_runtime
configuration option will be ignored and no slashes will be stripped from
string.
See also fread(), fopen(), fsockopen(), popen(), and fputs().
set_file_buffer
set_file_buffer -- Sets file buffering on the given file pointer
Description
int fwrite(int fp, int buffer);
set_file_buffer() sets the buffering for write operations on the given
filepointer fp to buffer bytes. If buffer is 0 then write operations are
unbuffered.
The function returns 0 on success, or EOF if the request cannot be honored.
Note that the default for any fopen with calling set_file_buffer is 8K.
See also fopen().
is_dir
is_dir -- tells whether the filename is a directory
Description
bool is_dir(string filename);
Returns true if the filename exists and is a directory.
The results of this function are cached. See clearstatcache() for more
details.
See also is_file() and is_link().
is_executable
is_executable -- tells whether the filename is executable
Description
bool is_executable(string filename);
Returns true if the filename exists and is executable.
The results of this function are cached. See clearstatcache() for more
details.
See also is_file() and is_link().
is_file
is_file -- tells whether the filename is a regular file
Description
bool is_file(string filename);
Returns true if the filename exists and is a regular file.
The results of this function are cached. See clearstatcache() for more
details.
See also is_dir() and is_link().
is_link
is_link -- tells whether the filename is a symbolic link
Description
bool is_link(string filename);
Returns true if the filename exists and is a symbolic link.
The results of this function are cached. See clearstatcache() for more
details.
See also is_dir() and is_file().
is_readable
is_readable -- tells whether the filename is readable
Description
bool is_readable(string filename);
Returns true if the filename exists and is readable.
Keep in mind that PHP may be accessing the file as the user id that the web
server runs as (often 'nobody'). Safe mode limitations are not taken into
account.
The results of this function are cached. See clearstatcache() for more
details.
See also is_writeable().
is_writeable
is_writeable -- tells whether the filename is writeable
Description
bool is_writeable(string filename);
Returns true if the filename exists and is writeable. The filename argument
may be a directory name allowing you to check if a directory is writeable.
Keep in mind that PHP may be accessing the file as the user id that the web
server runs as (often 'nobody'). Safe mode limitations are not taken into
account.
The results of this function are cached. See clearstatcache() for more
details.
See also is_readable().
link
link -- Create a hard link
Description
int link(string target, string link);
Link() creates a hard link.
See also the symlink() to create soft links, and readlink() along with
linkinfo().
linkinfo
linkinfo -- Get information about a link
Description
int linkinfo(string path);
Linkinfo() returns the st_dev field of the UNIX C stat structure returned by
the lstat system call. This function is used to verify if a link (pointed to
by path) really exists (using the same method as the S_ISLNK macro defined
in stat.h). Returns 0 or FALSE in case of error.
See also symlink(), link(), and readlink().
mkdir
mkdir -- make directory
Description
int mkdir(string pathname, int mode);
Attempts to create the directory specified by pathname.
Note that you probably want to specify the mode as an octal number, which
means it should have a leading zero.
mkdir("/path/to/my/dir", 0700);
Returns true on success and false on failure.
See also rmdir().
pclose
pclose -- close process file pointer
Description
int pclose(int fp);
Closes a file pointer to a pipe opened by popen().
The file pointer must be valid, and must have been returned by a successful
call to popen().
Returns the termination status of the process that was run.
See also popen().
popen
popen -- open process file pointer
Description
int popen(string command, string mode);
Opens a pipe to a process executed by forking the command given by command.
Returns a file pointer identical to that returned by fopen(), except that it
is unidirectional (may only be used for reading or writing) and must be
closed with pclose(). This pointer may be used with fgets(), fgetss(), and
fputs().
If an error occurs, returns false.
$fp = popen( "/bin/ls", "r" );
See also pclose().
readfile
readfile -- output a file
Description
int readfile(string filename);
Reads a file and writes it to standard output.
Returns the number of bytes read from the file. If an error occurs, false is
returned and unless the function was called as @readfile, an error message
is printed.
If filename begins with "http://" (not case sensitive), an HTTP 1.0
connection is opened to the specified server and the text of the response is
written to standard output.
Does not handle HTTP redirects, so you must include trailing slashes on
directories.
If filename begins with "ftp://" (not case sensitive), an ftp connection to
the specified server is opened and the requested file is written to standard
output. If the server does not support passive mode ftp, this will fail.
If filename begins with neither of these strings, the file will be opened
from the filesystem and its contents written to standard output.
See also fpassthru(), file(), fopen(), include(), require(), and virtual().
readlink
readlink -- Return the target of a symbolic link
Description
string readlink(string path);
Readlink() does the same as the readlink C function and returns the contents
of the symbolic link path or 0 in case of error.
See also symlink(), readlink() and linkinfo().
rename
rename -- rename a file
Description
int rename(string oldname, string newname);
Attempts to rename oldname to newname.
Returns true on success and false on failure.
rewind
rewind -- rewind the position of a file pointer
Description
int rewind(int fp);
Sets the file position indicator for fp to the beginning of the file stream.
If an error occurs, returns 0.
The file pointer must be valid, and must point to a file successfully opened
by fopen().
See also fseek() and ftell().
rmdir
rmdir -- remove directory
Description
int rmdir(string dirname);
Attempts to remove the directory named by pathname. The directory must be
empty, and the relevant permissions must permit this.
If an error occurs, returns 0.
See also mkdir().
stat
stat -- give information about a file
Description
array stat(string filename);
Gathers the statistics of the file named by filename.
Returns an array with the statistics of the file with the following
elements:
1. device
2. inode
3. inode protection mode
4. number of links
5. user id of owner
6. group id owner
7. device type if inode device *
8. size in bytes
9. time of last access
10. time of last modification
11. time of last change
12. blocksize for filesystem I/O *
13. number of blocks allocated
* - only valid on systems supporting the st_blksize type--other systems
(i.e. Windows) return -1
The results of this function are cached. See clearstatcache() for more
details.
lstat
lstat -- give information about a file or symbolic link
Description
array lstat(string filename);
Gathers the statistics of the file or symbolic link named by filename. This
function is identical to the stat() function except that if the filename
parameter is a symbolic link, the status of the symbolic link is returned,
not the status of the file pointed to by the symbolic link.
Returns an array with the statistics of the file with the following
elements:
1. device
2. inode
3. number of links
4. user id of owner
5. group id owner
6. device type if inode device *
7. size in bytes
8. time of last access
9. time of last modification
10. time of last change
11. blocksize for filesystem I/O *
12. number of blocks allocated
* - only valid on systems supporting the st_blksize type--other systems
(i.e. Windows) return -1
The results of this function are cached. See clearstatcache() for more
details.
symlink
symlink -- Create a symbolic link
Description
int symlink(string target, string link);
symlink() creates a symbolic link from the existing target with the
specified name link.
See also link() to create hard links, and readlink() along with linkinfo().
tempnam
tempnam -- create unique file name
Description
string tempnam(string dir, string prefix);
Creates a unique temporary filename in the specified directory. If the
directory does not exist, tempnam() may generate a filename in the system's
temporary directory.
The behaviour of the tempnam() function is system dependent. On Windows the
TMP environment variable will override the dir parameter, on Linux the
TMPDIR environment variable has precedence, while SVR4 will always use your
dir parameter if the directory it points to exists. Consult your system
documentation on the tempnam(3) function if in doubt.
Returns the new temporary filename, or the null string on failure.
Example 1. tempnam() example
$tmpfname = tempnam( "/tmp", "FOO" );
touch
touch -- set modification time of file
Description
int touch(string filename, int time);
Attempts to set the modification time of the file named by filename to the
value given by time. If the option time is not given, uses the present time.
If the file does not exist, it is created.
Returns true on success and false otherwise.
umask
umask -- changes the current umask
Description
int umask(int mask);
Umask() sets PHP's umask to mask & 0777 and returns the old umask. When PHP
is being used as a server module, the umask is restored when each request is
finished.
Umask() without arguments simply returns the current umask.
unlink
unlink -- Delete a file
Description
int unlink(string filename);
Deletes filename. Similar to the Unix C unlink() function.
Returns 0 or FALSE on an error.
See also rmdir() for removing directories.
XVIII. HTTP functions
These functions let you manipulate the output sent back to the remote
browser right down to the HTTP protocol level.
Table of Contents
header Ñ Send a raw HTTP header
setcookie Ñ Send a cookie
header
header -- Send a raw HTTP header
Description
int header(string string);
The Header() function is used at the top of an HTML file to send raw HTTP
header strings. See the HTTP 1.1 Specification for more information on raw
http headers. Note: Remember that the Header() function must be called
before any actual output is sent either by normal HTML tags or from PHP. It
is a very common error to read code with include() or with auto_prepend and
have spaces or empty lines in this code that force output before header() is
called.
header("Location: http://www.php.net"); /* Redirect browser to PHP web site */
exit; /* Make sure that code below does not get executed when we redirect. */
PHP scripts often generate dynamic HTML that must not be cached by the
client browser or any proxy caches between the server and the client
browser. Many proxies and clients can be forced to disable caching with
header("Expires: Mon, 26 Jul 1997 05:00:00 GMT"); // Date in the past
header("Last-Modified: " . gmdate("D, d M Y H:i:s") . " GMT"); // always modified
header("Cache-Control: no-cache, must-revalidate"); // HTTP/1.1
header("Pragma: no-cache"); // HTTP/1.0
setcookie
setcookie -- Send a cookie
Description
int setcookie(string name, string value, int expire, string path, string
domain, int secure);
setcookie() defines a cookie to be sent along with the rest of the header
information. Cookies must be sent before any other headers are sent (this is
a restriction of cookies, not PHP). This requires you to place calls to this
function before any or
>
The optional imageinfo parameter allows you to extract some extended
information from the image file. Currently this will return the diffrent JPG
APP markers in an associative Array. Some Programs use these APP markers to
embedd text information in images. A very common one in to embed IPTC
http://www.xe.net/iptc/ information in the APP13 marker. You can use the
iptcparse() function to parse the binary APP13 marker into something
readable.
Example 2. GetImageSize returning IPTC
Note: This function does not require the GD image library.
ImageArc
ImageArc -- draw a partial ellipse
Description
int imagearc(int im, int cx, int cy, int w, int h, int s, int e, int col);
ImageArc draws a partial ellipse centered at cx, cy (top left is 0,0) in the
image represented by im. w and h specifies the ellipse's width and height
respectively while the start and end points are specified in degrees
indicated by the s and e arguments.
ImageChar
ImageChar -- draw a character horizontally
Description
int imagechar(int im, int font, int x, int y, string c, int col);
ImageChar draws the first character of c in the image identified by id with
its upper-left at x,y (top left is 0,0) with the color col. If font is 1, 2,
3, 4 or 5, a built-in font is used (with higher numbers corresponding to
larger fonts).
See also imageloadfont().
ImageCharUp
ImageCharUp -- draw a character vertically
Description
int imagecharup(int im, int font, int x, int y, string c, int col);
ImageCharUp draws the character c vertically in the image identified by im
at coordinates x, y (top left is 0, 0) with the color col. If font is 1, 2,
3, 4 or 5, a built-in font is used.
See also imageloadfont().
ImageColorAllocate
ImageColorAllocate -- allocate a color for an image
Description
int imagecolorallocate(int im, int red, int green, int blue);
ImageColorAllocate returns a color identifier representing the color
composed of the given RGB components. The im argument is the return from the
imagecreate() function. ImageColorAllocate must be called to create each
color that is to be used in the image represented by im.
$white = ImageColorAllocate($im, 255,255,255);
$black = ImageColorAllocate($im, 0,0,0);
ImageColorTransparent
ImageColorTransparent -- define a color as transparent
Description
int imagecolortransparent(int im, int [col]);
ImageColorTransparent sets the transparent color in the im image to col. im
is the image identifier returned by imagecreate() and col is a color
identifier returned by imagecolorallocate().
The identifier of the new (or current, if none is specified) transparent
color is returned.
ImageCopyResized
ImageCopyResized -- copy and resize part of an image
Description
int imagecopyresized(int dst_im, int src_im, int dstX, int dstY, int srcX,
int srcY, int dstW, int dstH, int srcW, int srcH);
ImageCopyResized copies a rectangular portion of one image to another image.
dst_im is the destination image, src_im is the source image identifier. If
the source and destination coordinates and width and heights differ,
appropriate stretching or shrinking of the image fragment will be performed.
The coordinates refer to the upper left corner. This function can be used to
copy regions within the same image (if dst_im is the same as src_im) but if
the regions overlap the results will be unpredictable.
ImageCreate
ImageCreate -- create a new image
Description
int imagecreate(int x_size, int y_size);
ImageCreate returns an image identifier representing a blank image of size
x_size by y_size.
ImageCreateFromGif
ImageCreateFromGif -- create a new image from file or URL
Description
int imagecreatefromgif(string filename);
imagecreatefromgif() returns an image identifier representing the image
obtained from the given filename.
imagecreatefromgif() returns an empty string on failure. It also outputs an
error message, which unfortunately displays as a broken link in a browser.
To ease debugging the following example will produce an error GIF:
Example 1. Example to handle an error during creation (courtesy
vic@zymsys.com )
function LoadGif($imgname)
{
$im = @imagecreatefromgif($imgname); /* Attempt to open */
if ($im == "") { /* See if it failed */
$im = ImageCreate(150,30); /* Create a blank image */
$bgc = ImageColorAllocate($im,255,255,255);
$tc = ImageColorAllocate($im,0,0,0);
ImageFilledRectangle($im,0,0,150,30,$bgc);
ImageString($im,1,5,5,"Error loading $imgname",$tc); /* Output an errmsg */
}
return $im;
}
Note: Since all GIF support was removed from the GD library in
version 1.6, this function is not available if you are using that
version of the GD library.
ImageDashedLine
ImageDashedLine -- draw a dashed line
Description
int imagedashedline(int im, int x1, int y1, int x2, int y2, int col);
ImageLine draws a dashed line from x1,y1 to x2,y2 (top left is 0,0) in image
im of color col.
See also imageline().
ImageDestroy
ImageDestroy -- destroy an image
Description
int imagedestroy(int im);
ImageDestroy frees any memory associated with image im. im is the image
identifier returned by the imagecreate() function.
ImageFill
ImageFill -- flood fill
Description
int imagefill(int im, int x, int y, int col);
ImageFill performs a flood fill starting at coordinate x, y (top left is
0,0) with color col in the image im.
ImageFilledPolygon
ImageFilledPolygon -- draw a filled polygon
Description
int imagefilledpolygon(int im, array points, int num_points, int col);
ImageFilledPolygon creates a filled polygon in image im. points is a PHP
array containing the polygon's vertices, ie. points[0] = x0, points[1] = y0,
points[2] = x1, points[3] = y1, etc. num_points is the total number of
vertices.
ImageFilledRectangle
ImageFilledRectangle -- draw a filled rectangle
Description
int imagefilledrectangle(int im, int x1, int y1, int x2, int y2, int col);
ImageFilledRectangle creates a filled rectangle of color col in image im
starting at upper left coordinates x1, y1 and ending at bottom right
coordinates x2, y2. 0, 0 is the top left corner of the image.
ImageFillToBorder
ImageFillToBorder -- flood fill to specific color
Description
int imagefilltoborder(int im, int x, int y, int border, int col);
ImageFillToBorder performs a flood fill whose border color is defined by
border. The starting point for the fill is x,y (top left is 0,0) and the
region is filled with color col.
ImageFontHeight
ImageFontHeight -- get font height
Description
int imagefontheight(int font);
Returns the pixel height of a character in the specified font.
See also imagefontwidth() and imageloadfont().
ImageFontWidth
ImageFontWidth -- get font width
Description
int imagefontwidth(int font);
Returns the pixel width of a character in font.
See also imagefontheight() and imageloadfont().
ImageGif
ImageGif -- output image to browser or file
Description
int imagegif(int im, string filename);
imagegif() creates the GIF file in filename from the image im. The im
argument is the return from the imagecreate() function.
The image format will be GIF87a unless the image has been made transparent
with imagecolortransparent(), in which case the image format will be GIF89a.
The filename argument is optional, and if left off, the raw image stream
will be output directly. By sending an image/gif content-type using
header(), you can create a PHP script that outputs GIF images directly.
Note: Since all GIF support was removed from the GD library in
version 1.6, this function is not available if you are using that
version of the GD library.
ImageInterlace
ImageInterlace -- enable or disable interlace
Description
int imageinterlace(int im, int [interlace]);
ImageInterlace() turns the interlace bit on or off. If interlace is 1 the im
image will be interlaced, and if interlace is 0 the interlace bit is turned
off.
This functions returns whether the interlace bit is set for the image.
ImageLine
ImageLine -- draw a line
Description
int imageline(int im, int x1, int y1, int x2, int y2, int col);
ImageLine draws a line from x1,y1 to x2,y2 (top left is 0,0) in image im of
color col.
See also imagecreate() and imagecolorallocate().
ImageLoadFont
ImageLoadFont -- load a new font
Description
int imageloadfont(string file);
ImageLoadFont loads a user-defined bitmap font and returns an identifier for
the font (that is always greater than 5, so it will not conflict with the
built-in fonts).
The font file format is currently binary and architecture dependent. This
means you should generate the font files on the same type of CPU as the
machine you are running PHP on.
Table 1. Font file format
byte positionC data description
type
byte 0-3 int number of characters in the font
byte 4-7 int value of first character in the font (often 32 for
space)
byte 8-11 int pixel width of each character
byte 12-15 int pixel height of each character
byte 16- char array with character data, one byte per pixel in
each character, for a total of
(nchars*width*height) bytes.
See also ImageFontWidth() and ImageFontHeight().
ImagePolygon
ImagePolygon -- draw a polygon
Description
int imagepolygon(int im, array points, int num_points, int col);
ImagePolygon creates a polygon in image id. points is a PHP array containing
the polygon's vertices, ie. points[0] = x0, points[1] = y0, points[2] = x1,
points[3] = y1, etc. num_points is the total number of vertices.
See also imagecreate().
ImageRectangle
ImageRectangle -- draw a rectangle
Description
int imagerectangle(int im, int x1, int y1, int x2, int y2, int col);
ImageRectangle creates a rectangle of color col in image im starting at
upper left coordinate x1,y1 and ending at bottom right coordinate x2,y2. 0,0
is the top left corner of the image.
ImageSetPixel
ImageSetPixel -- set a single pixel
Description
int imagesetpixel(int im, int x, int y, int col);
ImageSetPixel draws a pixel at x,y (top left is 0,0) in image im of color
col.
See also imagecreate() and imagecolorallocate().
ImageString
ImageString -- draw a string horizontally
Description
int imagestring(int im, int font, int x, int y, string s, int col);
ImageString draws the string s in the image identified by im 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().
ImageStringUp
ImageStringUp -- draw a string vertically
Description
int imagestringup(int im, int font, int x, int y, string s, int col);
ImageStringUp draws the string s vertically in the image identified by im 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().
ImageSX
ImageSX -- get image width
Description
int imagesx(int im);
ImageSX returns the width of the image identified by im.
See also imagecreate() and imagesy().
ImageSY
ImageSY -- get image height
Description
int imagesy(int im);
ImageSY returns the height of the image identified by im.
See also imagecreate() and imagesx().
ImageTTFBBox
ImageTTFBBox -- give the bounding box of a text using TypeType fonts
Description
array ImageTTFBBox(int size, int angle, string fontfile, string text);
This function calculates and returns the bounding box in pixels a TrueType
text.
text
The string to be measured.
size
The font size.
fontfile
The name of the TrueType font file. (Can also be an URL.)
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:
0lower left corner, X position
1lower left corner, Y position
2lower right corner, X position
3lower right corner, Y position
4upper right corner, X position
5upper right corner, Y position
6upper left corner, X position
7upper 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 horizontallty.
This function requires both the GD library and the Freetype library.
See also ImageTTFText().
ImageTTFText
ImageTTFText -- write text to the image using a TrueType fonts
Description
array ImageTTFText(int im, int size, int angle, int x, int y, int col,
string fontfile, string text);
ImageTTFText draws the string text in the image identified by im, starting
at coordinates x,y (top left is 0,0), at an angle of angle in color col,
using the TrueType font file identified by fontfile.
The coordinates given by x,y will define the basepoint of the first
character (roughly the lower-left corner of the character). This is
different from the ImageString(), where x,y define the upper-right corner of
the first character.
angle is in degrees, with 0 degrees being left-to-right reading text (3
o'clock direction), and higher values representing a counter-clockwise
rotation. (i.e., a value of 90 would result in bottom-to-top reading text).
fontfile is the path to the TrueType font you wish to use.
text is the text string which may include UTF-8 character sequences (of the
form: { ) to access characters in a font beyond the first 255.
col is the color index. Using the negative of a color index has the effect
of turning off antialiasing.
ImageTTFText() returns an array with 8 elements representing four points
making the bounding box of the text. The order of the points is upper left,
upper right, lower right, lower left. The points are relative to the text
regardless of the angle, so "upper left" means in the top left-hand corner
when you see the text horizontallty.
This example script will produce a black GIF 400x30 pixels, with the words
"Testing..." in white in the font Arial.
Example 1. ImageTTFText
This function requires both the GD library and the FreeType library.
See also ImageTTFBBox().
ImageColorAt
ImageColorAt -- get the index of the color of a pixel
Description
int imagecolorat(int im, int x, int y);
Returns the index of the color of the pixel at the specified location in the
image.
See also imagecolorset() and imagecolorsforindex().
ImageColorClosest
ImageColorClosest -- get the index of the closest color to the specified
color
Description
int imagecolorclosest(int im, 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 imagecolorexact().
ImageColorExact
ImageColorExact -- get the index of the specified color
Description
int imagecolorexact(int im, int red, int green, int blue);
Returns the index of the specified color in the palette of the image.
If the color does not exist in the image's palette, -1 is returned.
See also imagecolorclosest().
ImageColorResolve
ImageColorResolve -- get the index of the specified color or its closest
possible alternative
Description
int imagecolorresolve(int im, int red, int green, int blue);
This function is guaranteed to return a color index for a requested color,
either the exact color or the closest possible alternative.
See also imagecolorclosest().
ImageColorSet
ImageColorSet -- set the color for the specified palette index
Description
bool imagecolorset(int im, int index, int red, int green, int blue);
This sets the specified index in the palette to the specified color. This is
useful for creating flood-fill-like effects in paletted images without the
overhead of performing the actual flood-fill.
See also imagecolorat().
ImageColorsForIndex
ImageColorsForIndex -- get the colors for an index
Description
array imagecolorsforindex(int im, int index);
This returns an associative array with red, green, and blue keys that
contain the appropriate values for the specified color index.
See also imagecolorat() and imagecolorexact().
ImageColorsTotal
ImageColorsTotal -- find out the number of colors in an image's palette
Description
int imagecolorstotal(int im);
This returns the number of colors in the specified image's palette.
See also imagecolorat() and imagecolorsforindex().
ImagePSLoadFont
ImagePSLoadFont -- load a PostScript Type 1 from file
Description
int imagepsloadfont(string filename);
In the case everything went right, a valid font index will be returned and
can be used for further purposes. Otherwise the function returns false and
prints a message describing what went wrong.
See also imagepsfreefont().
ImagePSFreeFont
ImagePSFreeFont -- free memory used by a PostScript Type 1 font
Description
void imagepsfreefont(int fontindex);
See also imagepsloadfont().
ImagePSEncodeFont
ImagePSEncodeFont -- change the character encoding vector of a font
Description
int imagepsencodefont(string encodingfile);
Loads a character encoding vector from from a file and changes the fonts
encoding vector to it. As a PostScript fonts default vector lacks most of
the character positions above 127, you'll definitely want to change this if
you use an other language than english. The exact format of this file is
described in T1libs documentation. T1lib comes with two ready-to-use files,
IsoLatin1.enc and IsoLatin2.enc.
If you find yourself using this function all the time, a much better way to
define the encoding is to set ps.default_encoding in the configuration file
to point to the right encoding file and all fonts you load will
automatically have the right encoding.
ImagePSText
ImagePSText -- to draw a text string over an image using PostScript Type1
fonts
Descriptiom
array imagepstext(int image, string text, int font, int size, int
foreground, int background, int x, int y, int [space], int [tightness],
float [angle], int [antialias_steps]);
size is expressed in pixels.
foreground is the color in which the text will be painted. background is the
color to which the text will try to fade in with antialiasing. No pixels
with the color background are actually painted, so the background image does
not need to be of solid color.
The coordinates given by x, y will define the origin (or reference point) of
the first character (roughly the lower-left corner of the character). This
is different from the ImageString(), where x, y define the upper-right
corner of the first character. Refer to PostScipt documentation about fonts
and their measuring system if you have trouble understanding how this works.
space allows you to change the default value of a space in a font. This
amount is added to the normal value and can also be negative.
tightness allows you to control the amount of white space between
characters. This amount is added to the normal character width and can also
be negative.
angle is in degrees.
antialias_steps allows you to control the number of colours used for
antialiasing text. Allowed values are 4 and 16. The higher value is
recommended for text sizes lower than 20, where the effect in text quality
is quite visible. With bigger sizes, use 4. It's less computationally
intensive.
Parameters space and tightness are expressed in character space units, where
1 unit is 1/1000th of an em-square.
Parameters space, tightness, angle and antialias are optional.
This function returns an array containing the following elements:
0lower left x-coordinate
1lower left y-coordinate
2upper right x-coordinate
3upper right y-coordinate
See also imagepsbbox().
ImagePSBBox
ImagePSBBox -- give the bounding box of a text rectangle using PostScript
Type1 fonts
Description
array imagepsbbox(string text, int font, int size, int space, int width,
float angle);
size is expressed in pixels.
space allows you to change the default value of a space in a font. This
amount is added to the normal value and can also be negative.
tightness allows you to control the amount of white space between
characters. This amount is added to the normal character width and can also
be negative.
angle is in degrees.
Parameters space and tightness are expressed in character space units, where
1 unit is 1/1000th of an em-square.
Parameters space, tightness and angle are optional.
The bounding box is calculated using information available from character
metrics, and unfortunately tends to differ slightly from the results
achieved by actually rasterizing the text. If the angle is 0 degrees, you
can expect the text to need 1 pixel more to every direction.
This function returns an array containing the following elements:
0lower left x-coordinate
1lower left y-coordinate
2upper right x-coordinate
3upper right y-coordinate
See also imagepstext().
XXII. IMAP functions
To get these functions to work, you have to compile PHP with --with-imap.
That requires the c-client library to be installed. Grab the latest version
from ftp://ftp.cac.washington.edu/imap/ and compile it. Then copy
c-client/c-client.a to /usr/local/lib or some other directory on your link
path and copy c-client/rfc822.h, mail.h and linkage.h to /usr/local/include
or some other directory in your include path.
Table of Contents
imap_append Ñ Append a string message to a specified mailbox
imap_base64 Ñ Decode BASE64 encoded text
imap_body Ñ Read the message body
imap_check Ñ Check current mailbox
imap_close Ñ Close an IMAP stream
imap_createmailbox Ñ Create a new mailbox
imap_delete Ñ Mark a messge for deletion from current mailbox
imap_deletemailbox Ñ Delete a mailbox
imap_expunge Ñ Delete all messages marked for deletion
imap_fetchbody Ñ Fetch a particular section of the body of the message
imap_fetchstructure Ñ Read the structure of a particular message
imap_header Ñ Read the header of the message
imap_headers Ñ Returns headers for all messages in a mailbox
imap_listmailbox Ñ Read the list of mailboxes
imap_getmailboxes Ñ Read the list of mailboxes, returning detailed
information on each one
imap_listsubscribed Ñ List all the subscribed mailboxes
imap_getsubscribed Ñ List all the subscribed mailboxes
imap_mail_copy Ñ Copy specified messages to a mailbox
imap_mail_move Ñ Move specified messages to a mailbox
imap_num_msg Ñ Gives the number of messages in the current mailbox
imap_num_recent Ñ Gives the number of recent messages in current mailbox
imap_open Ñ Open an IMAP stream to a mailbox
imap_ping Ñ Check if the IMAP stream is still active
imap_renamemailbox Ñ Rename an old mailbox to new mailbox
imap_reopen Ñ Reopen IMAP stream to new mailbox
imap_subscribe Ñ Subscribe to a mailbox
imap_undelete Ñ Unmark the message which is marked deleted
imap_unsubscribe Ñ Unsubscribe from a mailbox
imap_qprint Ñ Convert a quoted-printable string to an 8 bit string
imap_8bit Ñ Convert an 8bit string to a quoted-printable string.
imap_binary Ñ Convert an 8bit string to a base64 string.
imap_scanmailbox Ñ Read the list of mailboxes, takes a string to search for
in the text of the mailbox
imap_mailboxmsginfo Ñ Get information about the current mailbox
imap_rfc822_write_address Ñ Returns a properly formatted email address given
the mailbox, host, and personal info.
imap_rfc822_parse_adrlist Ñ Parses an address string
imap_setflag_full Ñ Sets flags on messages
imap_clearflag_full Ñ Clears flags on messages
imap_sort Ñ
imap_fetchheader Ñ Returns header for a message
imap_uid Ñ This function returns the UID for the given message sequence
number.
imap_msgno Ñ This function returns the message sequence number for the given
UID.
imap_search Ñ This function returns an array of messages matching the given
search criteria.
imap_last_error Ñ This function returns the last IMAP error (if any) that
occurred during this page request.
imap_errors Ñ This function returns all of the IMAP errors (if any) that
have occurred during this page request or since the error stack was reset.
imap_alerts Ñ This function returns all IMAP alert messages (if any) that
have occurred during this page request or since the alert stack was reset.
imap_status Ñ This function returns status information on a mailbox other
than the current one.
imap_append
imap_append -- Append a string message to a specified mailbox
Description
int imap_append(int imap_stream, string mbox, string message, stringflags);
Returns true on sucess, false on error.
imap_append() appends a string message to the specified mailbox mbox. If the
optional flags is specified, writes the flags to that mailbox also.
When talking to the Cyrus IMAP server, you must use "\r\n" as your
end-of-line terminator instead of "\n" or the operation will fail.
imap_base64
imap_base64 -- Decode BASE64 encoded text
Description
string imap_base64(string text);
imap_base64() function decodes BASE-64 encoded text. The decoded message is
returned as a string.
imap_body
imap_body -- Read the message body
Description
string imap_body(int imap_stream, int msg_number, int flags);
imap_body() returns the body of the message, numbered msg_number in the
current mailbox. The optional flags are a bit mask with one or more of the
following:
* FT_UID - The msgno is a UID
* FT_PEEK - Do not set the \Seen flag if not already set
* FT_INTERNAL - The return string is in internal format, will not
canonicalize to CRLF.
imap_check
imap_check -- Check current mailbox
Description
array imap_check(int imap_stream);
Returns information about the current mailbox. Returns FALSE on failure.
The imap_check() function checks the current mailbox status on the server
and returns the information in an object with following properties.
Date : date of the message
Driver : driver
Mailbox : name of the mailbox
Nmsgs : number of messages
Recent : number of recent messages
imap_close
imap_close -- Close an IMAP stream
Description
int imap_close(int imap_stream, int flags);
Close the imap stream. Takes an optional flag CL_EXPUNGE, which will
silently expunge the mailbox before closing.
imap_createmailbox
imap_createmailbox -- Create a new mailbox
Description
int imap_createmailbox(int imap_stream, string mbox);
imap_createmailbox() creates a new mailbox specified by mbox.
Returns true on success and false on error.
imap_delete
imap_delete -- Mark a messge for deletion from current mailbox
Description
int imap_delete(int imap_stream, int msg_number);
Returns true.
imap_delete() function marks message pointed by msg_number for deletion.
Actual deletion of the messages is done by imap_expunge().
imap_deletemailbox
imap_deletemailbox -- Delete a mailbox
Description
int imap_deletemailbox(int imap_stream, string mbox);
imap_deletemailbox() deletes the specified mailbox.
Returns true on success and false on error.
imap_expunge
imap_expunge -- Delete all messages marked for deletion
Description
int imap_expunge(int imap_stream);
imap_expunge() deletes all the messages marked for deletion by
imap_delete().
Returns true.
imap_fetchbody
imap_fetchbody -- Fetch a particular section of the body of the message
Description
string imap_fetchbody(int imap_stream, int msg_number, string part_number,
flags flags);
This function causes a fetch of a particular section of the body of the
specified messages as a text string and returns that text string. The
section specification is a string of integers delimited by period which
index into a body part list as per the IMAP4 specification. Body parts are
not decoded by this function.
The options for imap_fetchbody ()e a bitmask with one or more of the
following
* FT_UID - The msgono is a UID
* FT_PEEK - Do not set the \Seen flag if not already set
* FT_UID - The return string is in "internal" format, without any attempt
to canonicalize CRLF
imap_fetchstructure
imap_fetchstructure -- Read the structure of a particular message
Description
array imap_fetchstructure(int imap_stream, int msg_number);
This function causes a fetch of all the structured information for the given
msg_number. The returned value is an object with following elements.
type, encoding, ifsubtype, subtype, ifdescription, description, ifid,
id, lines, bytes, ifparameters
It also returns an array of objects called parameters[]. This object has
following properties.
attribute, value
In case of multipart, it also returns an array of objects of all the
properties, called parts[].
imap_header
imap_header -- Read the header of the message
Description
object imap_header(int imap_stream, int msg_number, int fromlength, int
subjectlength, int defaulthost);
This function returns an object of various header elements
remail,date,Date,subject,Subject,in_reply_to,message_id,newsgroups,
followup_to,references
message flags:
Recent - 'R' if recent and seen, 'N' if recent and not seen, ' ' if not recent
Unseen - 'U' if not seen AND not recent, ' ' if seen OR not seen and recent
Answered - 'A' if answered, ' ' if unanswered
Deleted - 'D' if deleted, ' ' if not deleted
Draft - 'X' if draft, ' ' if not draft
Flagged - 'F' if flagged, ' ' if not flagged
NOTE that the Recent/Unseen behavior is a little odd. If you want to know if a message is Unseen, you must check for
Unseen == 'U' || Recent == 'N'
toaddress (full to: line, up to 1024 characters)
to[] (returns an array of objects from the To line, containing:)
personal
adl
mailbox
host
fromaddress (full from: line, up to 1024 characters)
from[] (returns an array of objects from the From line, containing:)
personal
adl
mailbox
host
ccaddress (full cc: line, up to 1024 characters)
cc[] (returns an array of objects from the Cc line, containing:)
personal
adl
mailbox
host
bccaddress (full bcc line, up to 1024 characters)
bcc[] (returns an array of objects from the Bcc line, containing:)
personal
adl
mailbox
host
reply_toaddress (full reply_to: line, up to 1024 characters)
reply_to[] (returns an array of objects from the Reply_to line, containing:)
personal
adl
mailbox
host
senderaddress (full sender: line, up to 1024 characters)
sender[] (returns an array of objects from the sender line, containing:)
personal
adl
mailbox
host
return_path (full return-path: line, up to 1024 characters)
return_path[] (returns an array of objects from the return_path line, containing:)
personal
adl
mailbox
host
udate ( mail message date in unix time)
fetchfrom (from line formatted to fit fromlength characters)
fetchsubject (subject line formatted to fit subjectlength characters)
imap_headers
imap_headers -- Returns headers for all messages in a mailbox
Description
array imap_headers(int imap_stream);
Returns an array of string formatted with header info. One element per mail
message.
imap_listmailbox
imap_listmailbox -- Read the list of mailboxes
Description
array imap_listmailbox(int imap_stream, string ref, string pat);
Returns an array containing the names of the mailboxes.
imap_getmailboxes
imap_getmailboxes -- Read the list of mailboxes, returning detailed
information on each one
Description
array imap_getmailboxes(int imap_stream, string ref, string pat);
Returns an array of objects containing mailbox information. Each object has
the attributes name, specifying the full name of the mailbox; delimiter,
which is the hierarchy delimiter for the part of the hierarchy this mailbox
is in; and attributes. Attributes is a bitmask that can be tested against:
* LATT_NOINFERIORS - This mailbox has no "children" (there are no
mailboxes below this one)
* LATT_NOSELECT - This is only a container, not a mailbox - you cannot
open it.
* LATT_MARKED - This mailbox is marked. Only used by UW-IMAPD.
* LATT_UNMARKED - This mailbox is not marked. Only used by UW-IMAPD.
ref should normally be just the IMAP server, in the form:
{imap_server:imap_port}, and pattern specifies where in the mailbox
hierarchy to start searching. If you want all mailboxes, pass pattern as an
empty string.
There are two special characters you can pass as part of the pattern: '*'
and '%'. '*' means to return all mailboxes. If you pass pattern as '*', you
will get a list of the entire mailbox hierarchy. '%' means to return the
current level only. '%' as the pattern parameter will return only the top
level mailboxes; '~/mail/%' on UW_IMAPD will return every mailbox in the
~/mail directory, but none in subfolders of that directory.
imap_listsubscribed
imap_listsubscribed -- List all the subscribed mailboxes
Description
array imap_listsubscribed(int imap_stream, string ref, string pattern);
Returns an array of all the mailboxes that you have subscribed. The ref and
pattern arguments specify the base location to search from and the pattern
the mailbox name must match.
imap_getsubscribed
imap_getsubscribed -- List all the subscribed mailboxes
Description
array imap_getsubscribed(int imap_stream, string ref, string pattern);
This function is identical to imap_getmailboxes(), except that it only
returns mailboxes that the user is subscribed to.
imap_mail_copy
imap_mail_copy -- Copy specified messages to a mailbox
Description
int imap_mail_copy(int imap_stream, string msglist, string mbox, int flags);
Returns true on success and false on error.
Copies mail messages specified by msglist to specified mailbox. msglist is a
range not just message numbers.
flags is a bitmask of one or more of
* CP_UID - the sequence numbers contain UIDS
* CP_MOVE - Delete the messages from the current mailbox after copying
imap_mail_move
imap_mail_move -- Move specified messages to a mailbox
Description
int imap_mail_move(int imap_stream, string msglist, string mbox);
Moves mail messages specified by msglist to specified mailbox. msglist is a
range not just message numbers.
Returns true on success and false on error.
imap_num_msg
imap_num_msg -- Gives the number of messages in the current mailbox
Description
int imap_num_msg(int stream_id);
Return the number of messages in the current mailbox.
imap_num_recent
imap_num_recent -- Gives the number of recent messages in current mailbox
Description
int imap_num_recent(int imap_stream);
Returns the number of recent messages in the current mailbox.
imap_open
imap_open -- Open an IMAP stream to a mailbox
Description
int imap_open(string mailbox, string username, string password, int flags);
Returns an IMAP stream on success and false on error. This function can also
be used to open streams to POP3 and NNTP servers. To connect to an IMAP
server running on port 143 on the local machine, do the following:
$mbox = imap_open("{localhost:143}INBOX","user_id","password");
To connect to a POP3 server on port 110 on the local server, use:
$mbox = imap_open("{localhost/pop3:110}INBOX","user_id","password");
To connect to an NNTP server on port 119 on the local server, use:
$nntp = imap_open("{localhost/nntp:119}comp.test","","");
To connect to a remote server replace "localhost" with the name or the IP
address of the server you want to connect to.
The options are a bit mask with one or more of the following:
* OP_READONLY - Open mailbox read-only
* OP_ANONYMOUS - Dont use or update a .newsrc for news
* OP_HALFOPEN - For IMAP and NNTP names, open a connection but dont open
a mailbox
* CL_EXPUNGE - Expunge mailbox automatically upon mailbox close
imap_ping
imap_ping -- Check if the IMAP stream is still active
Description
int imap_ping(int imap_stream);
Returns true if the stream is still alive, false otherwise.
imap_ping() function pings the stream to see it is still active. It may
discover new mail; this is the preferred method for a periodic "new mail
check" as well as a "keep alive" for servers which have inactivity timeout.
imap_renamemailbox
imap_renamemailbox -- Rename an old mailbox to new mailbox
Description
int imap_renamemailbox(int imap_stream, string old_mbox, string new_mbox);
This function renames on old mailbox to new mailbox.
Returns true on success and false on error.
imap_reopen
imap_reopen -- Reopen IMAP stream to new mailbox
Description
int imap_reopen(string imap_stream, string mailbox, string [flags]);
Returns true on success and false on error.
This function reopens the specified stream to new mailbox.
The options are a bit mask with one or more of the following:
* OP_READONLY - Open mailbox read-only
* OP_ANONYMOUS - Dont use or update a .newsrc for news
* OP_HALFOPEN - For IMAP and NNTP names, open a connection but dont open
a mailbox
* CL_EXPUNGE - Expunge mailbox automatically upon mailbox close
imap_subscribe
imap_subscribe -- Subscribe to a mailbox
Description
int imap_subscribe(int imap_stream, string mbox);
Subscribe to a new mailbox.
Returns true on success and false on error.
imap_undelete
imap_undelete -- Unmark the message which is marked deleted
Description
int imap_undelete(int imap_stream, int msg_number);
This function removes the deletion flag for a specified message, which is
set by imap_delete().
Returns true on success and false on error.
imap_unsubscribe
imap_unsubscribe -- Unsubscribe from a mailbox
Description
int imap_unsubscribe(int imap_stream, string mbox);
Unsubscribe from a specified mailbox.
Returns true on success and false on error.
imap_qprint
imap_qprint -- Convert a quoted-printable string to an 8 bit string
Description
string imap_qprint(string string);
Convert a quoted-printable string to an 8 bit string
Returns an 8 bit (binary) string
imap_8bit
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.
Returns a quoted-printable string
imap_binary
imap_binary -- Convert an 8bit string to a base64 string.
Description
string imap_binary(string string);
Convert an 8bit string to a base64 string.
Returns a base64 string
imap_scanmailbox
imap_scanmailbox -- Read the list of mailboxes, takes a string to search for
in the text of the mailbox
Description
array imap_scanmailbox(int imap_stream, string string);
Returns an array containing the names of the mailboxes that have string in
the text of the mailbox.
imap_mailboxmsginfo
imap_mailboxmsginfo -- Get information about the current mailbox
Description
array imap_mailboxmsginfo(int imap_stream);
Returns information about the current mailbox. Returns FALSE on failure.
The imap_mailboxmsginfo() function checks the current mailbox status on the
server and returns the information in an object with following properties.
Date : date of the message
Driver : driver
Mailbox : name of the mailbox
Nmsgs : number of messages
Recent : number of recent messages
Unread : number of unread messages
Size : mailbox size
imap_rfc822_write_address
imap_rfc822_write_address -- Returns a properly formatted email address
given the mailbox, host, and personal info.
Description
string imap_rfc822_write_address(string mailbox, string host, string
personal);
Returns a properly formatted email address given the mailbox, host, and
personal info.
imap_rfc822_parse_adrlist
imap_rfc822_parse_adrlist -- Parses an address string
Description
string imap_rfc822_parse_adrlist(string address, string default_host);
This function parses the address tring and for each address, returns an
array of objects. The 4 objects are:
mailbox - the mailbox name (username)
host - the host name
personal - the personal name
adl - at domain source route
imap_setflag_full
imap_setflag_full -- Sets flags on messages
Description
string imap_setflag_full(int stream, string sequence, string flag, string
options);
This function causes a store to add the specified flag to the flags set for
the messages in the specified sequence.
The options are a bit mask with one or more of the following:
ST_UID The sequence argument contains UIDs instead of
sequence numbers
imap_clearflag_full
imap_clearflag_full -- Clears flags on messages
Description
string imap_clearflag_full(int stream, string sequence, string flag, string
options);
This function causes a store to delete the specified flag to the flags set
for the messages in the specified sequence.
The options are a bit mask with one or more of the following:
ST_UID The sequence argument contains UIDs instead of
sequence numbers
imap_sort
imap_sort --
Description
string imap_sort(int stream, int criteria, int reverse, int options);
Returns an array of message numbers sorted by the given parameters
Rev is 1 for reverse-sorting.
Criteria can be one (and only one) of the following:
SORTDATE message Date
SORTARRIVAL arrival date
SORTFROM mailbox in first From address
SORTSUBJECT message Subject
SORTTO mailbox in first To address
SORTCC mailbox in first cc address
SORTSIZE size of message in octets
The flags are a bitmask of one or more of the following:
SE_UID Return UIDs instead of sequence numbers
SE_NOPREFETCH Don't prefetch searched messages.
imap_fetchheader
imap_fetchheader -- Returns header for a message
Description
stringimap_fetchheader(int imap_stream, int msgno, int flags);
This function causes a fetch of the complete, unfiltered RFC 822 format
header of the specified message as a text string and returns that text
string.
The options are:
FT_UID The msgno argument is a UID
FT_INTERNAL The return string is in "internal" format,
without any attempt to canonicalize to CRLF
newlines
FT_PREFETCHTEXT The RFC822.TEXT should be pre-fetched at the
same time. This avoids an extra RTT on an
IMAP connection if a full message text is
desired (e.g. in a "save to local file"
operation)
imap_uid
imap_uid -- This function returns the UID for the given message sequence
number.
Description
int imap_uid(int imap_stream, int msgno);
This function returns the UID for the given message sequence number. It is
the inverse of imap_msgno().
imap_msgno
imap_msgno -- This function returns the message sequence number for the
given UID.
Description
int imap_msgno(int imap_stream, int uid);
This function returns the message sequence number for the given UID. It is
the inverse of imap_uid().
imap_search
imap_search -- This function returns an array of messages matching the given
search criteria.
Description
array imap_search(int imap_stream, string criteria, int flags);
This function performs a search on the mailbox currently opened in the given
imap stream. criteria is a string, delimited by spaces, in which the
following keywords are allowed. Any multi-word arguments (eg FROM "joe
smith") must be quoted.
* ALL - return all messages matching the rest of the criteria
* ANSWERED - match messages with the \\ANSWERED flag set
* BCC "string" - match messages with "string" in the Bcc: field
* BEFORE "date" - match messages with Date: before "date"
* BODY "string" - match messages with "string" in the body of the message
* CC "string" - match messages with "string" in the Cc: field
* DELETED - match deleted messages
* FLAGGED - match messages with the \\FLAGGED (sometimes referred to as
Important or Urgent) flag set
* FROM "string" - match messages with "string" in the From: field
* KEYWORD "string" - match messages with "string" as a keyword
* NEW - match new messages
* OLD - match old messages
* ON "date" - match messages with Date: matching "date"
* RECENT - match messages with the \\RECENT flag set
* SEEN - match messages that have been read (the \\SEEN flag is set)
* SINCE "date" - match messages with Date: after "date"
* SUBJECT "string" - match messages with "string" in the Subject:
* TEXT "string" - match messages with text "string"
* TO "string" - match messages with "string" in the To:
* UNANSWERED - match messages that have not been answered
* UNDELETED - match messages that are not deleted
* UNFLAGGED - match messages that are not flagged
* UNKEYWORD "string" - match messages that do not have the keyword
"string"
* UNSEEN - match messages which have not been read yet
For example, to match all unanswered messages sent by Mom, you'd use:
"UNANSWERED FROM mom". Searches appear to be case insensitive. This list of
criteria is from a reading of the UW c-client source code and may be
uncomplete or inaccurate. Searcher beware.
Valid values for flags are SE_UID, which causes the returned array to
contain UIDs instead of messages sequence numbers.
imap_last_error
imap_last_error -- This function returns the last IMAP error (if any) that
occurred during this page request.
Description
string imap_last_error(void );
This function returns the full text of the last IMAP error message that
occurred on the current page. The error stack is untouched; calling
imap_last_error() subsequently, with no intervening errors, will return the
same error.
imap_errors
imap_errors -- This function returns all of the IMAP errors (if any) that
have occurred during this page request or since the error stack was reset.
Description
array imap_errors(void );
This function returns an array of all of the IMAP error messages generated
since the last imap_errors() call, or the beginning of the page. When
imap_errors() is called, the error stack is subsequently cleared.
imap_alerts
imap_alerts -- This function returns all IMAP alert messages (if any) that
have occurred during this page request or since the alert stack was reset.
Description
array imap_alerts(void );
This function returns an array of all of the IMAP alert messages generated
since the last imap_alerts() call, or the beginning of the page. When
imap_alerts() is called, the alert stack is subsequently cleared. The IMAP
specification requires that these messages be passed to the user.
imap_status
imap_status -- This function returns status information on a mailbox other
than the current one.
Description
object imap_status(int imap_stream, string mailbox, int options);
This function returns an object containing status information. Valid flags
are:
* SA_MESSAGES - set status->messages to the number of messages in the
mailbox
* SA_RECENT - set status->recent to the number of recent messages in the
mailbox
* SA_UNSEEN - set status->unseen to the number of unseen (new) messages
in the mailbox
* SA_UIDNEXT - set status->uidnext to the next uid to be used in the
mailbox
* SA_UIDVALIDITY - set status->uidvalidity to a constant that changes
when uids for the mailbox may no longer be valid
* SA_ALL - set all of the above
status->flags is also set, which contains a bitmask which can be checked
against any of the above constants.
XXIII. PHP options & information
Table of Contents
error_log Ñ send an error message somewhere
error_reporting Ñ set which PHP errors are reported
getenv Ñ Get the value of an environment variable
get_cfg_var Ñ Get the value of a PHP configuration option.
get_current_user Ñ Get the name of the owner of the current PHP script.
get_magic_quotes_gpc Ñ Get the current active configuration setting of magic
quotes gpc.
get_magic_quotes_runtime Ñ Get the current active configuration setting of
magic_quotes_runtime.
getlastmod Ñ Get time of last page modification.
getmyinode Ñ Get the inode of the current script.
getmypid Ñ Get PHP's process ID.
getmyuid Ñ Get PHP script owner's UID.
getrusage Ñ Get the current resource usages.
phpinfo Ñ Output lots of PHP information.
phpversion Ñ Get the current PHP version.
extension_loaded Ñ find out whether an extension is loaded
putenv Ñ Set the value of an environment variable.
set_magic_quotes_runtime Ñ Set the current active configuration setting of
magic_quotes_runtime.
set_time_limit Ñ limit the maximum execution time
error_log
error_log -- send an error message somewhere
Description
int error_log(string message, int message_type, string [destination], string
[extra_headers]);
Sends an error message to the web server's error log, a TCP port or to a
file. The first parameter, message, is the error message that should be
logged. The second parameter, message_type says where the message should go:
Table 1. error_log() log types
0message is sent to PHP's system logger, using the Operating System's
system logging mechanism or a file, depending on what the error_log
configuration directive is set to.
1message is sent by email to the address in the destination parameter.
This is the only message type where the fourth parameter, extra_headers
is used. This message type uses the same internal function as Mail()
does.
2message is sent through the PHP debugging connection. This option is only
available if remote debugging has been enabled. In this case, the
destination parameter specifies the host name or IP address and
optionally, port number, of the socket receiving the debug information.
3message is appended to the file destination.
Example 1. error_log() examples
// Send notification through the server log if we can not
// connect to the database.
if (!Ora_Logon($username, $password)) {
error_log("Oracle database not available!", 0);
}
// Notify administrator by email if we run out of FOO
if (!($foo = allocate_new_foo()) {
error_log("Big trouble, we're all out of FOOs!", 1,
"operator@mydomain.com");
}
// other ways of calling error_log():
error_log("You messed up!", 2, "127.0.0.1:7000");
error_log("You messed up!", 2, "loghost");
error_log("You messed up!", 3, "/var/tmp/my-errors.log");
error_reporting
error_reporting -- set which PHP errors are reported
Description
int error_reporting(int [level]);
Sets PHP's error reporting level and returns the old level. The error
reporting level is a bitmask of the following values (follow the links for
the internal values to get their meanings):
Table 1. error_reporting() bit values
valueinternal name
1 E_ERROR
2 E_WARNING
4 E_PARSE
8 E_NOTICE
16 E_CORE_ERROR
32 E_CORE_WARNING
getenv
getenv -- Get the value of an environment variable
Description
string getenv(string varname);
Returns the value of the environment variable varname, or false on an error.
$ip = getenv("REMOTE_ADDR"); // get the ip number of the user
You can see a list of all the environmental variables by using phpinfo().
You can find out what many of them mean by taking a look at the CGI
specification, specifically the page on environmental variables.
get_cfg_var
get_cfg_var -- Get the value of a PHP configuration option.
Description
string get_cfg_var(string varname);
Returns the current value of the PHP configuration variable specified by
varname, or false if an error occurs.
It will not return configuration information set when the PHP was compiled,
or read from an Apache configuration file (using the
php3_configuration_option directives).
To check whether the system is using a configuration file, try retrieving
the value of the cfg_file_path configuration setting. If this is available,
a configuration file is being used.
get_current_user
get_current_user -- Get the name of the owner of the current PHP script.
Description
string get_current_user(void);
Returns the name of the owner of the current PHP script.
See also getmyuid(), getmypid(), getmyinode(), and getlastmod().
get_magic_quotes_gpc
get_magic_quotes_gpc -- Get the current active configuration setting of
magic quotes gpc.
Description
long get_magic_quotes_gpc(void);
Returns the current active configuration setting of magic_quotes_gpc. (0 for
off, 1 for on)
See also get_magic_quotes_runtime(), set_magic_quotes_runtime().
get_magic_quotes_runtime
get_magic_quotes_runtime -- Get the current active configuration setting of
magic_quotes_runtime.
Description
long get_magic_quotes_runtime(void);
Returns the current active configuration setting of magic_quotes_runtime. (0
for off, 1 for on)
See also get_magic_quotes_gpc(), set_magic_quotes_runtime().
getlastmod
getlastmod -- Get time of last page modification.
Description
int getlastmod(void);
Returns the time of the last modification of the current page. The value
returned is a Unix timestamp, suitable for feeding to date(). Returns false
on error.
Example 1. getlastmod() example
// outputs e.g. 'Last modified: March 04 1998 20:43:59.'
echo "Last modified: ".date( "F d Y H:i:s.", getlastmod() );
See alse date(), getmyuid(), get_current_user(), getmyinode(), and
getmypid().
getmyinode
getmyinode -- Get the inode of the current script.
Description
int getmyinode(void);
Returns the current script's inode, or false on error.
See also getmyuid(), get_current_user(), getmypid(), and getlastmod().
getmypid
getmypid -- Get PHP's process ID.
Description
int getmypid(void);
Returns the current PHP process ID, or false on error.
Note that when running as a server module, separate invocations of the
script are not guaranteed to have distinct pids.
See also getmyuid(), get_current_user(), getmyinode(), and getlastmod().
getmyuid
getmyuid -- Get PHP script owner's UID.
Description
int getmyuid(void);
Returns the user ID of the current script, or false on error.
See also getmypid(), get_current_user(), getmyinode(), and getlastmod().
getrusage
getrusage -- Get the current resource usages.
Description
array getrusage(int [who]);
This is an interface to getrusage(2). It returns an associative array
containing the data returned from the system call. If who is 1, getrusage
will be called with RUSAGE_CHILDREN. All entries are accessible by using
their documented field names.
Example 1. Getrusage Example
$dat = getrusage();
echo $dat["ru_nswap"]; # number of swaps
echo $dat["ru_majflt"]; # number of page faults
echo $dat["ru_utime.tv_sec"]; # user time used (seconds)
echo $dat["ru_utime.tv_usec"]; # user time used (microseconds)
See your system's man page for more details.
phpinfo
phpinfo -- Output lots of PHP information.
Description
int phpinfo(void);
Outputs a large amount of information about the current state of PHP. This
includes information about PHP compilation options and extensions, the PHP
version, server information and environment (if compiled as a module), the
PHP environment, OS version information, paths, master and local values of
configuration options, HTTP headers, and the GNU Public License.
See also phpversion().
phpversion
phpversion -- Get the current PHP version.
Description
string phpversion(void);
Returns a string containing the version of the currently running PHP parser.
Example 1. phpversion() example
// prints e.g. 'Current PHP version: 3.0rel-dev'
echo "Current PHP version: ".phpversion();
See also phpinfo().
extension_loaded
extension_loaded -- find out whether an extension is loaded
Description
bool extension_loaded(string name);
Returns true if the extension identified by name is loaded. You can see the
names of various extensions by using phpinfo().
See also phpinfo().
Note: This function was added in 3.0.10.
putenv
putenv -- Set the value of an environment variable.
Description
void putenv(string setting);
Adds setting to the environment.
Example 1. Setting an Environment Variable
putenv("UNIQID=$uniqid");
set_magic_quotes_runtime
set_magic_quotes_runtime -- Set the current active configuration setting of
magic_quotes_runtime.
Description
long set_magic_quotes_runtime(int new_setting);
Set the current active configuration setting of magic_quotes_runtime. (0 for
off, 1 for on)
See also get_magic_quotes_gpc(), get_magic_quotes_runtime().
set_time_limit
set_time_limit -- limit the maximum execution time
Description
void set_time_limit(int seconds);
Set the number of seconds a script is allowed to run. If this is reached,
the script returns a fatal error. The default limit is 30 seconds or, if it
exists, the max_execution_time value defined in the configuration file. If
seconds is set to zero, no time limit is imposed.
When called, set_time_limit() restarts the timeout counter from zero. In
other words, if the timeout is the default 30 seconds, and 25 seconds into
script execution a call such as set_time_limit(20) is made, the script will
run for a total of 45 seconds before timing out.
XXIV. Informix functions
The Informix driver for Online (ODS) 7.x, SE 7.x and Universal Server (IUS)
9.x is implemented in "functions/ifx.ec" and "functions/php3_ifx.h". ODS 7.x
support is fairly complete, with full support for BYTE and TEXT columns. IUS
9.x support is partly finished: the new data types are there, but SLOB and
CLOB support is still under construction.
Configuration notes:
Before you run the "configure" script, make sure that the
"INFORMIXDIR" variable has been set.
The configure script will autodetect the libraries and include
directories, if you run "configure --with_informix=yes". You can
overide this detection by specifying "IFX_LIBDIR", "IFX_LIBS" and
"IFX_INCDIR" in the environment. The configure script will also
try to detect your Informix server version. It will set the
"HAVE_IFX_IUS" conditional compilation variable if your Informix
version >= 9.00.
Some notes on the use of BLOBs (TEXT and BYTE columns):
BLOBs are normally addressed by integer BLOB identifiers. Select
queries return a "blob id" for every BYTE and TEXT column. You can
get at the contents with "string_var = ifx_get_blob($blob_id);" if
you choose to get the BLOBs in memory (with :
"ifx_blobinfile(0);"). If you prefer to receive the content of
BLOB columns in a file, use "ifx_blobinfile(1);", and
"ifx_get_blob($blob_id);" will get you the filename. Use normal
file I/O to get at the blob contents.
For insert/update queries you must create these "blob id's"
yourself with "ifx_create_blob(..);". You then plug the blob id's
into an array, and replace the blob columns with a question mark
(?) in the query string. For updates/inserts, you are responsible
for setting the blob contents with ifx_update_blob(...).
The behaviour of BLOB columns can be altered by configuration
variables that also can be set at runtime :
configuration variable : ifx.textasvarchar
configuration variable : ifx.byteasvarchar
runtime functions :
ifx_textasvarchar(0) : use blob id's for select queries with TEXT
columns
ifx_byteasvarchar(0) : use blob id's for select queries with BYTE
columns
ifx_textasvarchar(1) : return TEXT columns as if they were VARCHAR
columns, without the use of blob id's for select queries.
ifx_byteasvarchar(1) : return BYTE columns as if they were VARCHAR
columns, without the use of blob id's for select queries.
configuration variable : ifx.blobinfile
runtime function :
ifx_blobinfile_mode(0) : return BYTE columns in memory, the blob
id lets you get at the contents.
ifx_blobinfile_mode(1) : return BYTE columns in a file, the blob
id lets you get at the file name.
If you set ifx_text/byteasvarchar to 1, you can use TEXT and BYTE
columns in select queries just like normal (but rather long)
VARCHAR fields. Since all strings are "counted" in PHP, this
remains "binary safe". It is up to you to handle this correctly.
The returned data can contain anything, you are responsible for
the contents.
If you set ifx_blobinfile to 1, use the file name returned by
ifx_get_blob(..) to get at the blob contents. Note that in this
case YOU ARE RESPONSIBLE FOR DELETING THE TEMPORARY FILES CREATED
BY INFORMIX when fetching the row. Every new row fetched will
create new temporary files for every BYTE column.
The location of the temporary files can be influenced by the
environment variable "blobdir", default is "." (the current
directory). Something like : putenv(blobdir=tmpblob"); will ease
the cleaning up of temp files accidentally left behind (their
names all start with "blb").
Automatically trimming "char" (SQLCHAR and SQLNCHAR) data:
This can be set with the configuration variable
ifx.charasvarchar : if set to 1 trailing spaces will be
automatically trimmed.
NULL values:
The configuration variable ifx.nullformat (and the runtime
function ifx_nullformat()) when set to true will return NULL
columns as the string "NULL", when set to false they return the
empty string. This allows you to discriminate between NULL columns
and empty columns.
Table of Contents
ifx_connect Ñ Open Informix server connection
ifx_pconnect Ñ Open persistent Informix connection
ifx_close Ñ Close Informix connection
ifx_query Ñ Send Informix query
ifx_prepare Ñ Prepare an SQL-statement for execution
ifx_do Ñ Execute a previously prepared SQL-statement
ifx_error Ñ Returns error code of last Informix call
ifx_errormsg Ñ Returns error message of last Informix call
ifx_affected_rows Ñ Get number of rows affected by a query
ifx_getsqlca Ñ Get the contents of sqlca.sqlerrd[0..5] after a query
ifx_fetch_row Ñ Get row as enumerated array
ifx_htmltbl_result Ñ Formats all rows of a query into a HTML table
ifx_fieldtypes Ñ List of Informix SQL fields
ifx_fieldproperties Ñ List of SQL fieldproperties
ifx_num_fields Ñ Returns the number of columns in the query
ifx_num_rows Ñ Count the rows already fetched a query
ifx_free_result Ñ Releases resources for the query
ifx_create_char Ñ Creates an char object
ifx_free_char Ñ Deletes the char object
ifx_update_char Ñ Updates the content of the char object
ifx_get_char Ñ Return the content of the char object
ifx_create_blob Ñ Creates an blob object
ifx_copy_blob Ñ Duplicates the given blob object
ifx_free_blob Ñ Deletes the blob object
ifx_get_blob Ñ Return the content of a blob object
ifx_update_blob Ñ Updates the content of the blob object
ifx_blobinfile_mode Ñ Set the default blob mode for all select queries
ifx_textasvarchar Ñ Set the default text mode
ifx_byteasvarchar Ñ Set the default byte mode
ifx_nullformat Ñ Sets the default return value on a fetch row
ifxus_create_slob Ñ Creates an slob object and opens it
ifx_free_slob Ñ Deletes the slob object
ifxus_close_slob Ñ Deletes the slob object
ifxus_open_slob Ñ Opens an slob object
ifxus_tell_slob Ñ Returns the current file or seek position
ifxus_seek_slob Ñ Sets the current file or seek position
ifxus_read_slob Ñ Reads nbytes of the slob object
ifxus_write_slob Ñ Writes a string into the slob object
ifx_connect
ifx_connect -- Open Informix server connection
Description
int ifx_connect(string [database] , string [userid] , string [password] );
Returns an connection identifier on success, or FALSE on error.
ifx_connect() establishes a connection to an Informix server. All of the
arguments are optional, and if they're missing, defaults are taken from
values supplied in configuration file (ifx.default_host for the host
(Informix libraries will use INFORMIXSERVER environment value if not
defined), ifx.default_user for user, ifx.default_password for the password
(none if not defined).
In case a second call is made to ifx_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 ifx_close().
See also ifx_pconnect(), and ifx_close().
Example 1. Connect to a Informix database
$conn_id = ifx_pconnect (mydb@ol_srv1, "imyself", "mypassword");
ifx_pconnect
ifx_pconnect -- Open persistent Informix connection
Description
int ifx_pconnect(string [database] , string [userid] , string [password] );
Returns: A positive Informix persistent link identifier on success, or false
on error
ifx_pconnect() acts very much like ifx_connect() with two major differences.
This function behaves exactly like ifx_connect() when PHP is not running as
an Apache module. First, when connecting, the function would first try to
find a (persistent) link that's already open with the same host, username
and password. If one is found, an identifier for it will be returned instead
of opening a new connection.
Second, the connection to the SQL server will not be closed when the
execution of the script ends. Instead, the link will remain open for future
use (ifx_close() will not close links established by ifx_pconnect()).
This type of links is therefore called 'persistent'.
See also: ifx_connect().
ifx_close
ifx_close -- Close Informix connection
Description
int ifx_close(int [link_identifier] );
Returns: always true.
ifx_close() closes the link to an Informix database that's associated with
the specified link identifier. If the link identifier isn't specified, the
last opened link is assumed.
Note that this isn't usually necessary, as non-persistent open links are
automatically closed at the end of the script's execution.
ifx_close() will not close persistent links generated by ifx_pconnect().
See also: ifx_connect(), and ifx_pconnect().
Example 1. Closing a Informix connection
$conn_id = ifx_connect (mydb@ol_srv, "itsme", "mypassword");
... some queries and stuff ...
ifx_close($conn_id);
ifx_query
ifx_query -- Send Informix query
Description
int ifx_query(string query, int [link_identifier] , int [cursor_type] ,
mixed [blobidarray] );
Returns: A positive Informix result identifier on success, or false on
error.
An integer "result_id" used by other functions to retrieve the query
results. Sets "affected_rows" for retrieval by the ifx_affected_rows()
function.
ifx_query() sends a query to the currently active database on the server
that's associated with the specified link identifier. If the link identifier
isn't specified, the last opened link is assumed. If no link is open, the
function tries to establish a link as if ifx_connect() was called, and use
it.
Executes query on connection conn_id. For "select-type" queries a cursor is
declared and opened. The optional cursor_type parameter allows you to make
this a "scroll" and/or "hold" cursor. It's a mask and can be either
IFX_SCROLL, IFX_HOLD, or both or'ed together. Non-select queries are
"execute immediate".
For either query type the number of (estimated or real) affected rows is
saved for retrieval by ifx_affected_rows().
If you have BLOB (BYTE or TEXT) columns in an update query, you can add a
blobidarray parameter containing the corresponding "blob ids", and you
should replace those columns with a "?" in the query text.
If the contents of the TEXT (or BYTE) column allow it, you can also use
"ifx_textasvarchar(1)" and "ifx_byteasvarchar(1)". This allows you to treat
TEXT (or BYTE) columns just as if they were ordinary (but long) VARCHAR
columns for select queries, and you don't need to bother with blob id's.
With ifx_textasvarchar(0) or ifx_byteasvarchar(0) (the default situation),
select queries will return BLOB columns as blob id's (integer value). You
can get the value of the blob as a string or file with the blob functions
(see below).
See also: ifx_connect().
Example 1. Show all rows of the "orders" table as a html table
ifx_textasvarchar(1); // use "text mode" for blobs
$res_id = ifx_query("select * from orders", $conn_id);
if (! $res_id) {
printf("Can't select orders : %s\n%s
\n", ifx_error()); ifx_errormsg(); die; } ifx_htmltbl_result($res_id, "border=\"1\""); ifx_free_result($res_id); Example 2. Insert some values into the "catalog" table // create blob id's for a byte and text column $textid = ifx_create_blob(0, 0, "Text column in memory"); $byteid = ifx_create_blob(1, 0, "Byte column in memory"); // store blob id's in a blobid array $blobidarray[] = $textid; $blobidarray[] = $byteid; // launch query $query = "insert into catalog (stock_num, manu_code, " . "cat_descr,cat_picture) values(1,'HRO',?,?)"; $res_id = ifx_query($query, $conn_id, $blobidarray); if (! $res_id) { ... error ... } // free result id ifx_free_result($res_id); ifx_prepare ifx_prepare -- Prepare an SQL-statement for execution Description int ifx_prepare(string query, int conn_id, int [cursor_def], mixed blobidarray); Returns a integer result_id for use by ifx_do(). Sets affected_rows for retrieval by the ifx_affected_rows() function. Prepares query on connection conn_id. For "select-type" queries a cursor is declared and opened. The optional cursor_type parameter allows you to make this a "scroll" and/or "hold" cursor. It's a mask and can be either IFX_SCROLL, IFX_HOLD, or both or'ed together. For either query type the estimated number of affected rows is saved for retrieval by ifx_affected_rows(). If you have BLOB (BYTE or TEXT) columns in the query, you can add a blobidarray parameter containing the corresponding "blob ids", and you should replace those columns with a "?" in the query text. If the contents of the TEXT (or BYTE) column allow it, you can also use "ifx_textasvarchar(1)" and "ifx_byteasvarchar(1)". This allows you to treat TEXT (or BYTE) columns just as if they were ordinary (but long) VARCHAR columns for select queries, and you don't need to bother with blob id's. With ifx_textasvarchar(0) or ifx_byteasvarchar(0) (the default situation), select queries will return BLOB columns as blob id's (integer value). You can get the value of the blob as a string or file with the blob functions (see below). See also: ifx_do(). ifx_do ifx_do -- Execute a previously prepared SQL-statement Description int ifx_do(int result_id); Returns TRUE on success, FALSE on error. Executes a previously prepared query or opens a cursor for it. Does NOT free result_id on error. Also sets the real number of ifx_affected_rows() for non-select statements for retrieval by ifx_affected_rows() See also: ifx_prepare(). There is a example. ifx_error ifx_error -- Returns error code of last Informix call Description string ifx_error(void); The Informix error codes (SQLSTATE & SQLCODE) formatted as follows : x [SQLSTATE = aa bbb SQLCODE=cccc] where x = space : no error E : error N : no more data W : warning ? : undefined If the "x" character is anything other than space, SQLSTATE and SQLCODE describe the error in more detail. See the Informix manual for the description of SQLSTATE and SQLCODE Returns in a string one character describing the general results of a statement and both SQLSTATE and SQLCODE associated with the most recent SQL statement executed. The format of the string is "(char) [SQLSTATE=(two digits) (three digits) SQLCODE=(one digit)]". The first character can be ' ' (space) (success), 'W' (the statement caused some warning), 'E' (an error happened when executing the statement) or 'N' (the statement didn't return any data). See also: ifx_errormsg() ifx_errormsg ifx_errormsg -- Returns error message of last Informix call Description string ifx_errormsg(int [errorcode]); Returns the Informix error message associated with the most recent Informix error, or, when the optional "errorcode" param is present, the error message corresponding to "errorcode". See also: ifx_error() printf("%s\n
", ifx_errormsg(-201)); ifx_affected_rows ifx_affected_rows -- Get number of rows affected by a query Description int ifx_affected_rows(int result_id); result_id is a valid result id returned by ifx_query() or ifx_prepare(). Returns the number of rows affected by a query associated with result_id. For inserts, updates and deletes the number is the real number (sqlerrd[2]) of affected rows. For selects it is an estimate (sqlerrd[0]). Don't rely on it. Useful after ifx_prepare() to limit queries to reasonable result sets. See also: ifx_num_rows() Example 1. Informix affected rows $rid = ifx_prepare ("select * from emp where name like " . $name, $connid); if (! $rid) { ... error ... } $rowcount = ifx_affected_rows ($rid); if ($rowcount > 1000) { printf ("Too many rows in result set (%d)\n
", $rowcount); die ("Please restrict your query
\n"); } ifx_getsqlca ifx_getsqlca -- Get the contents of sqlca.sqlerrd[0..5] after a query Description array ifx_getsqlca(int result_id); result_id is a valid result id returned by ifx_query() or ifx_prepare(). Returns a pseudo-row (assiociative arry) with sqlca.sqlerrd[0] to sqlca.sqlerrd[5] after the query associated with result_id. For inserts, updates and deletes the values returned are those as set by the server after executing the query. This gives access to the number of affected rows and the serial insert value. For selects the values are those saved after the prepare statement. This gives access to the estimated number of affected rows. The use of this function saves the overhead of executing a "select dbinfo('sqlca.sqlerrdx')" query, as it retrieves the values that were saved by the ifx driver at the appropriate moment. Example 1. Retrieve Informix sqlca.sqlerrd[x] values /* assume the first column of 'sometable' is a serial */ $qid = ifx_query("insert into sometable values(0, '2nd column', 'another column' ", $connid); if (! $qid) { ... error ... } $sqlca = ifx_getsqlca ($qid); $serial_value = $sqlca["sqlerrd1"]; echo "The serial value of the inserted row is : " . $serial_value
\n"; ifx_fetch_row ifx_fetch_row -- Get row as enumerated array Description array ifx_fetch_row(int result_id, mixed [position] ); Returns an associative array that corresponds to the fetched row, or false if there are no more rows. Blob columns are returned as integer blob id values for use in ifx_get_blob() unless you have used ifx_textasvarchar(1) or ifx_byteasvarchar(1), in which case blobs are returned as string values. Returns FALSE on error result_id is a valid resultid returned by ifx_query() or ifx_prepare() (select type queries only!). [position] is an optional parameter for a "fetch" operation on "scroll" cursors: "NEXT", "PREVIOUS", "CURRENT", "FIRST", "LAST" or a number. If you specify a number, an "absolute" row fetch is executed. This parameter is optional, and only valid for scrollcursors. ifx_fetch_row() fetches one row of data from the result associated with the specified result identifier. The row is returned as an array. Each result column is stored in an array offset, starting at offset 0. Subsequent call to ifx_fetch_row() would return the next row in the result set, or false if there are no more rows. Example 1. Informix fetch rows $rid = ifx_prepare ("select * from emp where name like " . $name, $connid, IFX_SCROLL); if (! $rid) { ... error ... } $rowcount = ifx_affected_rows($rid); if ($rowcount > 1000) { printf ("Too many rows in result set (%d)\n
", $rowcount); die ("Please restrict your query
\n"); } if (! ifx_do ($rid)) { ... error ... } $row = ifx_fetch_row ($rid, "NEXT"); while (is_array($row)) { for(reset($row); $fieldname=key($row); next($row)) { $fieldvalue = $row[$fieldname]; printf ("%s = %s,", $fieldname, $fieldvalue); } printf("\n
"); $row = ifx_fetch_row ($rid, "NEXT"); } ifx_free_result ($rid); ifx_htmltbl_result ifx_htmltbl_result -- Formats all rows of a query into a HTML table Description int ifx_htmltbl_result(int result_id, string [html_table_options]); Returns the number of rows fetched or FALSE on error. Formats all rows of the result_id query into a html table. The optional second argument is a string of