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...<br>\n");
}
See also: rename()
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()
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 fopen(), popen(), fsockopen(), and fgets().
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.
The file pointer must be valid, and must point to a file successfully opened by fopen(), popen(), or fsockopen().
See also 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(), and popen().
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.
See also clearstatcache().
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.
filectime
filectime -- get inode modification time of file
Description
int filectime(string filename);
Returns the time the file was last changed, or false in case of an error.
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.
fileinode
fileinode -- get file inode
Description
int fileinode(string filename);
Returns the inode number of the file, or false in case of an error.
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.
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 error.
fileperms
fileperms -- get file permissions
Description
int fileperms(string filename);
Returns the permissions on the file, or false in case of an error.
filesize
filesize -- get file size
Description
int filesize(string filename);
Returns the size of the file, or false in case of an error.
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.
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().
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.
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.
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.
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.
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.
See also is_writeable().
is_writeable
is_writeable -- tells whether the filename is writeable
Description
bool is_readable(string filename);
Returns true if the filename exists and 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.
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:
device
inode
number of links
user id of owner
group id owner
device type if inode device *
size in bytes
time of last access
time of last modification
time of last change
blocksize for filesystem I/O *
number of blocks allocated
* - only valid on systems supporting the st_blksize type--other systems (i.e. Windows) return -1
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:
device
inode
number of links
user id of owner
group id owner
device type if inode device *
size in bytes
time of last access
time of last modification
time of last change
blocksize for filesystem I/O *
number of blocks allocated
* - only valid on systems supporting the st_blksize type--other systems (i.e. Windows) return -1
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.
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.
XIV. Functions related to HTTP
Table of Contents
header
setcookie
These functions let you manipulate the output sent back to the remote browser right down to the HTTP protocol level.
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. All the arguments except the name argument are optional. If only the name argument is present, the cookie by that name will be deleted from the remote client. You may also replace any argument with an empty string ("") in order to skip that argument. The expire and secure arguments are integers and cannot be skipped with an empty string. Use a zero (0) instead. The expire argument is a regular Unix time integer as returned by the time() or mktime() functions. The secure indicates that the cookie should only be transmitted over a secure HTTPS connection. Some examples follow:
Example 1. SetCookie examples
SetCookie("TestCookie","Test Value");
SetCookie("TestCookie",$value,time()+3600); /* expire in 1 hour */
SetCookie("TestCookie",$value,time()+3600,"/~rasmus/",".utoronto.ca",1);
Note that the value portion of the cookie will automatically be urlencoded when you send the cookie, and when it is received, it is automatically decoded and assigned to a variable by the same name as the cookie name. To see the contents of our test cookie in a script, simply do:
echo $TestCookie;
For more information on cookies, see Netscape's cookie specification at http://www.netscape.com/newsref/std/cookie_spec.html.
Microsoft Internet Explorer 4 with Service Pack 1 applied does not correctly deal with cookies that have their path parameter set.
XV. Hyperwave functions
Table of Contents
hw_Changeobject
hw_Children
hw_ChildrenObj
hw_Close
hw_Connect
hw_Cp
hw_Deleteobject
hw_DocByAnchor
hw_DocByAnchorObj
hw_DocumentAttributes
hw_DocumentBodyTag
hw_DocumentSize
hw_ErrorMsg
hw_EditText
hw_Error
hw_Free_Document
hw_GetParents
hw_GetParentsObj
hw_GetChildColl
hw_GetChildCollObj
hw_GetSrcByDestObj
hw_GetObject
hw_GetAndLock
hw_GetText
hw_GetObjectByQuery
hw_GetObjectByQueryObj
hw_GetObjectByQueryColl
hw_GetObjectByQueryCollObj
hw_GetChildDocColl
hw_GetChildDocCollObj
hw_GetAnchors
hw_GetAnchorsObj
hw_Mv
hw_Identify
hw_InCollections
hw_Info
hw_InsColl
hw_InsDoc
hw_InsertDocument
hw_New_Document
hw_Objrec2Array
hw_OutputDocument
hw_pConnect
hw_PipeDocument
hw_Root
hw_Unlock
hw_Username
--------------------------------------------------------------------------------
Introduction
Hyperwave has been developed at IICM in Graz. It started with the name Hyper-G and changed to Hyperwave when it was commercialised (If I remember properly it was in 1996).
Hyperwave is not free software. The current version, 4.0, is available at www.hyperwave.com. A time limited version can be downloaded for free (30 days).
Hyperwave is an information system similar to a database (HIS, Hyperwave Information Server). Its focus is the storage and management of documents. A document can be any possible piece of data that may as well be stored in file. Each document is accompanied by its object record. The object record contains meta data for the document. The meta data is a list of attributes which can be extended by the user. Certain attributes are always set by the Hyperwave server, other may be modified by the user.
Besides the documents, all hyper links contained in a document are stored as object records as well. Hyper links which are in a document will be removed from it and stored as individual objects, when the document is inserted into the database. The object record of the link contains information about where it starts and where it ends. In order to gain the original document you will have to retrieve the plain document without the links and the list of links and reinsert them (The functions hw_pipedocument() and hw_gettext() do this for you. The advantage of separating links from the document is obvious. Once a document to which a link is pointing to changes its name, the link can easily be modified accordingly. The document containing the link is not affected at all. You may even add a link to a document without modifying the document itself.
Saying that hw_pipedocument() and hw_gettext() do the link insertion automatically is not as simple as it sounds. Inserting links implies a certain hierachy of the documents. On a web server this is given by the file system, but Hyperwave has its own hierachy and names do not reflect the position of an object in that hierachy. Therefore creation of links first of all requires a mapping from the Hyperwave hierachy and namespace into a web hierachy respective web namespace. The fundamental difference between Hyperwave and the web is the clear distingtion between names and hierachy in Hyperwave. The name does not contain any information about the objects position in the hierachy. In the web the name also contains the information on where the object is located in the hierachy. This leads to two possibles ways of mapping. Either the Hyperwave hierachy and name of the Hyperwave object is reflected in the URL or the name only. To make things simple the second approach is used. Hyperwave object with name 'my_object' is mapped to 'http://host/my_object' diregarding where it resides in the Hyperwave hierachy. An object with name 'parent/my_object' could be the child of 'my_object' in the Hyperwave hierachy, though in a web namespace it appears to be just the opposite and the user might get confused. This can only be prevented by selecting reasonable obect names.
Having made this decission a second problem arises. How do you involve php3? The URL http://host/my_object will not call any php3 script unless you tell your web server to rewrite it to e.g. 'http://host/php3_script/my_object' and the script 'php3_script' evaluates the $PATH_INFO variable and retrieves the object with name 'my_object' from the Hyperwave server. Their is just one little drawback which can be fixed easily. Rewriting any URL would not allow any access to other document on the web server. A php3 script for searching in the Hyperwave server would be impossible. Therefore you will need at least a second rewriting rule to exclude certain URLS like all e.g. starting with http://host/Hyperwave. This is basically sharing of a namespace by the web and Hyperwave server.
Based on the above mechanism links are insert into documents.
It gets more complicated if php3 is not run as a module/CGI script but as a standalone application e.g. to dump the content of the Hyperwave server on a CD-ROM. In such a case it makes sense to retain the Hyperwave hierachy and map in onto the filesystem. This conflicts with the object names if they reflect its own hierachy (e.g. by chosing names including '/'). Therefore '/' has to be replaced by another character, e.g. '_'. to be continued.
The network protocol to communicate with the Hyperwave server is called HG-CSP (Hyper-G Client/Server Protocol). It is based on messages to initiate certain actions, e.g. get object record. In early versions of the Hyperwave Server two native clients (Harmony, Amadeus) were provided for communication with the server. Those two disappeared when Hyperwave was commercialized. As a replacement a so called wavemaster was provided. The wavemaster is like a protocol converter from HTTP to HG-CSP. The idea is to do all the administration of the database and visualisation of documents by a web interface. The wavemaster implements a set of placeholders for certain actions to customise the interface. This set of placeholders is called the PLACE Language. PLACE lacks a lot of features of a real programming language and any extension to it only enlarges the list of placeholders. This has led to the use of JavaScript which IMO does not make life easier.
Adding Hyperwave support to PHP3 should fill in the gap of a missing programming language for interface customisation. It implements all the messages as defined by the HG-CSP but also provides more powerful commands to e.g. retrieve complete documents.
Hyperwave has its own terminology to name certain pieces of information. This has widely been taken over and extended. Almost all functions operate on one of the following data types.
object ID: An unique integer value for each object in the Hyperwave server. It is also one of the attributes of the object record (ObjectID). Object ids are often used as an input parameter to specify an object.
object record: A string with attribute-value pairs of the form attribute=value. The pairs are separated by a carriage return from each other. An object record can easily be converted into an object array with hw_object2array(). Several functions return object records. The names of those functions end with obj.
object array: An associated array with all attributes of an object. The key is the attribute name. If an attribute occurs more than once in an object record it will result in another indexed or associated array. Attributes which are language depended (like the title, keyword, description) will form an associated array with the key set to the language abbreviation. All other multiple attributes will form an indexed array. php3 functions never return object arrays.
hw_document: This is a complete new data type which holds the actual document, e.g. HTML, PDF etc. It is somewhat optimised for HTML documents but may be used for any format.
Several functions which return an array of object records do also return an associated array with statistical information about them. The array is the last element of the object record array. The statistical array contains the following entries:
Hidden
Number of object records with attribute PresentationHints set to Hidden.
CollectionHead
Number of object records with attribute PresentationHints set to CollectionHead.
FullCollectionHead
Number of object records with attribute PresentationHints set to FullCollectionHead.
CollectionHeadNr
Index in array of object records with attribute PresentationHints set to CollectionHead.
FullCollectionHeadNr
Index in array of object records with attribute PresentationHints set to FullCollectionHead.
Total
Total: Number of object records.
--------------------------------------------------------------------------------
Integration with Apache
The Hyperwave module is best used when PHP3 is compiled as an apache module. In such a case the underlying Hyperwave server can be hidden from users almost completely if apache uses its rewriting engine. The following instructions will explain this.
Since PHP3 with Hyperwave support build into apache is intended to replace the native Hyperwave solution based on wavemaster I will assume that the apache server will only serve as a Hyperwave web interface. This is not necessary but it simplifies the configuration. The concept is quite simple. First of all you need a PHP3 script which evaluates the PATH_INFO variable and treats its value as the name of a Hyperwave object. Let's call this script 'Hyperwave'. The URL http://your.hostname/Hyperwave/name_of_object would than return the Hyperwave object with the name 'name_of_object'. Depending on the type of the object the script has to react accordingly. If it is a collection, it will probably return a list of children. If it is a document it will return the mime type and the content. A slight improvement can be achieved if the apache rewriting engine is used. From the users point of view it would be more straight forward if the URL http://your.hostname/name_of_object would return the object. The rewriting rule is quite easy:
RewriteRule ^/(.*) /usr/local/apache/htdocs/HyperWave/$1 [L]
Now every URL relates to an object in the Hyperwave server. This causes a simple to solve problem. There is no way to execute a different script, e.g. for searching, than the 'Hyperwave' script. This can be fixed with another rewriting rule like the following:
RewriteRule ^/hw/(.*) /usr/local/apache/htdocs/hw/$1 [L]
This will reserve the directory /usr/local/apache/htdocs/hw for additional scripts and other files. Just make sure this rule is evaluated before the one above. There is just a little drawback: all Hyperwave objects whose name starts with 'hw/' will be shadowed. So, make sure you don't use such names. If you need more directories, e.g. for images just add more rules or place them all in one directory. Finally, don't forget to turn on the rewriting engine with
RewriteEngine on
My experiences have shown that you will need the following scripts:
to return the object itself
to allow searching
to identify yourself
to set your profile
one for each additional function like to show the object attributes, to show information about users, to show the status of the server, etc.
--------------------------------------------------------------------------------
Todo
There are still some things todo:
The hw_InsertDocument has to be split into hw_InsertObject() and hw_PutDocument().
The names of several functions are not fixed, yet.
Most functions require the current connection as its first parameter. This leads to a lot of typing, which is quite often not necessary if there is just one open connection. A default connection will improve this.
hw_Changeobject
hw_Changeobject -- changes object
Description
int hw_changeobject(int connection, int object_to_change, string commands);
This command allows to remove, add, or modify individual attributes of an object record. The object is specified by the Object ID object_to_change; commands adhere to the following syntax:
<command> ::= <remcmd> |
<addcmd> |
<remcmd> "\" <addcmd>
<remcmd> ::= "rem " <attribute> "=" <value>
<addcmd> ::= "add " <attribute> "=" <value>
Note that in order to delete or remove an attribute its old value has to be supplied (some attributes are allowed more than once). A command like rem attr=value\add attr=value allows to modify attributes in one operation.
Returns TRUE if no error occurs otherwise FALSE.
hw_Children
hw_Children -- object ids of children
Description
array hw_children(int connection, int objectID);
Returns an array of object ids. Each id belongs to a child of the collection with ID objectID. The array contains all children both documents and collections.
hw_ChildrenObj
hw_ChildrenObj -- object records of children
Description
array hw_childrenobj(int connection, int objectID);
Returns an array of object records. Each object record belongs to a child of the collection with ID objectID. The array contains all children both documents and collections.
hw_Close
hw_Close -- closes the Hyperwave connection
Description
int hw_close(int connection);
Returns false if connection is not a valid connection index, otherwise true. Closes down the connection to a Hyperwave server with the given connection index.
hw_Connect
hw_Connect -- opens a connection
Description
int hw_connect(string host, int port, string username, string password);
Opens a connection to a Hyperwave server and returns a connection index on success, or false if the connection could not be made. Each of the arguments should be a quoted string, except for the port number. The username and password arguments are optional and can be left out. In such a case no identification with the server will be done. It is similar to identify as user anonymous. This function returns a connection index that is needed by other Hyperwave functions. You can have multiple connections open at once. Keep in mind, that the password is not encrypted.
See also hw_pConnect().
hw_Cp
hw_Cp -- copies objects
Description
int hw_cp(int connection, array object_id_array, int destination id);
Copies the objects with object ids as specified in the second parameter to the collection with the id destination id.
The value return is the number of copied objects.
See also hw_mv().
hw_Deleteobject
hw_Deleteobject -- deletes object
Description
int hw_deleteobject(int connection, int object_to_delete);
Deletes the the object with the given object id in the second parameter. It will delete all instances of the object.
Returns TRUE if no error occurs otherwise FALSE.
See also hw_mv().
hw_DocByAnchor
hw_DocByAnchor -- object id object belonging to anchor
Description
int hw_docbyanchor(int connection, int anchorID);
Returns an th object id of the document to which anchorID belongs.
hw_DocByAnchorObj
hw_DocByAnchorObj -- object record object belonging to anchor
Description
string hw_docbyanchorobj(int connection, int anchorID);
Returns an th object record of the document to which anchorID belongs.
hw_DocumentAttributes
hw_DocumentAttributes -- object record of hw_document
Description
string hw_documentattributes(int hw_document);
Returns the object record of the document.
See also hw_DocumentBodyTag(), hw_DocumentSize().
hw_DocumentBodyTag
hw_DocumentBodyTag -- body tag of hw_document
Description
string hw_documentbodytag(int hw_document);
Returns the BODY tag of the document. If the document is an HTML document the BODY tag should be printed before the document.
See also hw_DocumentAttributes(), hw_DocumentSize().
hw_DocumentSize
hw_DocumentSize -- size of hw_document
Description
int hw_documentsize(int hw_document);
Returns the size in bytes of the document.
See also hw_DocumentBodyTag(), hw_DocumentAttributes().
hw_ErrorMsg
hw_ErrorMsg -- returns error message
Description
string hw_errormsg(int connection);
Returns a string containing the last error message or 'No Error'. If false is returned, this function failed. The message relates to the last command.
hw_EditText
hw_EditText -- retrieve text document
Description
int hw_edittext(int connection, int hw_document);
Uploads the text document to the server. The object record of the document may not be modified while the document is edited. This function will only works for pure text documents. It will not open a special data connection and therefore blocks the control connection during the transfer.
See also hw_PipeDocument(), hw_FreeDocument(), hw_DocumentBodyTag(), hw_DocumentSize(), hw_OutputDocument(), hw_GetText().
hw_Error
hw_Error -- error number
Description
int hw_error(int connection);
Returns the last error number. If the return value is 0 no error has occurred. The error relates to the last command.
hw_Free_Document
hw_Free_Document -- frees hw_document
Description
int hw_free_document(int hw_document);
Frees the memory occupied by the Hyperwave document.
hw_GetParents
hw_GetParents -- object ids of parents
Description
array hw_getparentsobj(int connection, int objectID);
Returns an indexed array of object ids. Each object id belongs to a parent of the object with ID objectID.
hw_GetParentsObj
hw_GetParentsObj -- object records of parents
Description
array hw_getparentsobj(int connection, int objectID);
Returns an indexed array of object records plus an associated array with statistical information about the object records. The associated array is the last entry of the returned array. Each object record belongs to a parent of the object with ID objectID.
hw_GetChildColl
hw_GetChildColl -- object ids of child collections
Description
array hw_getchildcoll(int connection, int objectID);
Returns an array of object ids. Each object ID belongs to a child collection of the collection with ID objectID. The function will not return child documents.
See also hw_GetChildren(), hw_GetChildDocColl().
hw_GetChildCollObj
hw_GetChildCollObj -- object records of child collections
Description
array hw_getchildcollobj(int connection, int objectID);
Returns an array of object records. Each object records belongs to a child collection of the collection with ID objectID. The function will not return child documents.
See also hw_ChildrenObj(), hw_GetChildDocCollObj().
hw_GetSrcByDestObj
hw_GetSrcByDestObj -- Returns anchors pointing at object
Description
array hw_getsrcbydestobj(int connection, int objectID);
Returns the object records of all anchors pointing to the object with ID objectID. The object can either be a document or an anchor of type destination.
See also hw_GetAnchors().
hw_GetObject
hw_GetObject -- object record
Description
array hw_getobject(int connection, int objectID);
Returns the object record for the object with ID objectID.
See also hw_GetAndLock().
hw_GetAndLock
hw_GetAndLock -- return bject record and lock object
Description
string hw_getandlock(int connection, int objectID);
Returns the object record for the object with ID objectID. It will also lock the object, so other users cannot access it until it is unlocked.
See also hw_Unlock(), hw_GetObject().
hw_GetText
hw_GetText -- retrieve text document
Description
int hw_gettext(int connection, int objectID, int rootID);
Returns the document with object ID objectID. If the document has anchors which can be inserted, they will be inserted already. The optional parameter rootID determines how links are inserted into the document. The default is 0 and will result in links that are constructed from the name of the link's destination object. This is useful for web applications. If a link points to an object with name 'internet_movie' the HTML link will be <A HREF="/internet_movie">. The actual location of the source and destination object in the document hierachy is disregarded. You will have to set up your web browser, to rewrite that URL to for example '/my_script.php3/internet_movie'. 'my_script.php3' will have to evaluate $PATH_INFO and retrieve the document.
If rootID is unequal to 0 the link is constructed from all the names starting at the object with the id rootID separated by a slash relative to the current object. If for example the above document 'internet_movie' is located at 'a-b-c-internet_movie' with '-' being the seperator between hierachy levels and the source document is located at 'a-b-d-source' the resulting HTML link would be: <A HREF="../c/internet_movie">. This is useful if you want to download the whole server content onto disk and map the document hierachy onto the file system.
This function will only work for pure text documents. It will not open a special data connection and therefore blocks the control connection during the transfer.
See also hw_PipeDocument(), hw_FreeDocument(), hw_DocumentBodyTag(), hw_DocumentSize(), hw_OutputDocument().
hw_GetObjectByQuery
hw_GetObjectByQuery -- search object
Description
array hw_getobjectbyquery(int connection, string query, int max_hits);
Searches for objects on the whole server and returns an array of object ids. The maximum number of matches is limited to max_hits. If max_hits is set to -1 the maximum number of matches is unlimited.
See also hw_GetObjectByQueryObj().
hw_GetObjectByQueryObj
hw_GetObjectByQueryObj -- search object
Description
array hw_getobjectbyqueryobj(int connection, string query, int max_hits);
Searches for objects on the whole server and returns an array of object records. The maximum number of matches is limited to max_hits. If max_hits is set to -1 the maximum number of matches is unlimited.
See also hw_GetObjectByQuery().
hw_GetObjectByQueryColl
hw_GetObjectByQueryColl -- search object in collection
Description
array hw_getobjectbyquerycoll(int connection, int objectID, string query, int max_hits);
Searches for objects in collection with ID objectID and returns an array of object ids. The maximum number of matches is limited to max_hits. If max_hits is set to -1 the maximum number of matches is unlimited.
See also hw_GetObjectByQueryCollObj().
hw_GetObjectByQueryCollObj
hw_GetObjectByQueryCollObj -- search object in collection
Description
array hw_getobjectbyquerycollobj(int connection, int objectID, string query, int max_hits);
Searches for objects in collection with ID objectID and returns an array of object records. The maximum number of matches is limited to max_hits. If max_hits is set to -1 the maximum number of matches is unlimited.
See also hw_GetObjectByQueryColl().
hw_GetChildDocColl
hw_GetChildDocColl -- object ids of child documents of collection
Description
array hw_getchilddoccoll(int connection, int objectID);
Returns array of object ids for child documents of a collection.
See also hw_GetChildren(), hw_GetChildColl().
hw_GetChildDocCollObj
hw_GetChildDocCollObj -- object records of child documents of collection
Description
array hw_getchilddoccollobj(int connection, int objectID);
Returns an array of object records for child documents of a collection.
See also hw_ChildrenObj(), hw_GetChildCollObj().
hw_GetAnchors
hw_GetAnchors -- object ids of anchors of document
Description
array hw_getanchors(int connection, int objectID);
Returns an array of object ids with anchors of the document with object ID objectID.
hw_GetAnchorsObj
hw_GetAnchorsObj -- object records of anchors of document
Description
array hw_getanchorsobj(int connection, int objectID);
Returns an array of object records with anchors of the document with object ID objectID.
hw_Mv
hw_Mv -- moves objects
Description
int hw_mv(int connection, array object id array, int source id, int destination id);
Moves the objects with object ids as specified in the second parameter from the collection with id source id to the collection with the id destination id. If the source id is 0 the objects will be unlinked from the source collection. If this is the last instance of that object it will be deleted.
The value return is the number of moved objects.
See also hw_cp(), hw_deleteobject().
hw_Identify
hw_Identify -- identifies as user
Description
int hw_identify(string username, string password);
Identifies as user with username and password. Identification is only valid for the current session. I do not thing this function will be needed very often. In most cases it will be easier to identify with the opening of the connection.
See also hw_Connect().
hw_InCollections
hw_InCollections -- check if object ids in collections
Description
array hw_incollections(int connection, array object_id_array, array collection_id array, int return_collections);
Checks whether a set of objects (documents or collections) specified by the object_id_array is part of the collections defined by collection id_array. When the fourth parameter return_collectionsis 0, the subset of object ids that is part of the collections (i.e., the documents or collections that are children of one or more collections of collection ids or their subcollections, recursively) is returned as an array. When the fourth parameter is 1, however, the set of collections that have one or more objects of this subset as children are returned as an array. This option allows a client to, e.g., highlight the part of the collection hierarchy that contains the matches of a previous query, in a graphical overview.
hw_Info
hw_Info -- info about connection
Description
string hw_info(int connection);
Returns information about the current connection. The returned string has the following format: <Serverstring>, <Host>, <Port>, <Username>, <Port of Client>, <Byte swapping>
hw_InsColl
hw_InsColl -- insert collection
Description
int hw_inscoll(int connection, int objectID, array object_array);
Inserts a new collection with attributes as in object_array into collection with object ID objectID.
hw_InsDoc
hw_InsDoc -- insert document
Description
int hw_insdoc(int connection, int parentID, string object_record, string text);
Inserts a new document with attributes as in object_record into collection with object ID parentID. This function inserts either an object record only or an object record and a pure ascii text in text if text is given. If you want to insert a general document of any kind use hw_insertdocument() instead.
See also hw_InsertDocument(), hw_InsColl().
hw_InsertDocument
hw_InsertDocument -- upload any document
Description
int hw_putdocument(int connection, int parent_id, int hw_document);
Uploads a document into the collection with parent_id. The document has to be created before with hw_NewDocument(). Make sure that the object record of the new document contains at least the attributes: Type, DocumentType, Title and Name. Possibly you also want to set the MimeType.
See also hw_PipeDocument().
hw_New_Document
hw_New_Document -- create new document
Description
int hw_new_document(string document_data, string object_record, int document_size);
Returns a new Hyperwave document with document data set to document_data and object record set to object_record. The length of the document_data has to passed in document_sizeThis function does not insert the document into the Hyperwave server.
See also hw_FreeDocument(), hw_DocumentSize(), hw_DocumentBodyTag(), hw_OutputDocument(), hw_InsertDocument().
hw_Objrec2Array
hw_Objrec2Array -- convert attributes from object record to object array
Description
array hw_objrec2array(string object_record);
Converts an object_record into an object array.
hw_OutputDocument
hw_OutputDocument -- prints hw_document
Description
int hw_outputdocument(int hw_document);
Prints the document without the BODY tag.
hw_pConnect
hw_pConnect -- make a persistent database connection
Description
int hw_pconnect(string host, int port, string username, string password);
Returns a connection index on success, or false if the connection could not be made. Opens a persistent connection to a Hyperwave server. Each of the arguments should be a quoted string, except for the port number. The username and password arguments are optional and can be left out. In such a case no identification with the server will be done. It is similar to identify as user anonymous. This function returns a connection index that is needed by other Hyperwave functions. You can have multiple persistent connections open at once.
See also hw_Connect().
hw_PipeDocument
hw_PipeDocument -- retrieve any document
Description
int hw_pipedocument(int connection, int objectID);
Returns the Hyperwave document with object ID objectID. If the document has anchors which can be inserted, they will have been inserted already. The document will be transfered via a special data connection which does not block the control connection.
See also hw_GetText() for more on link insertion, hw_FreeDocument(), hw_DocumentSize(), hw_DocumentBodyTag(), hw_OutputDocument().
hw_Root
hw_Root -- root object id
Description
int hw_root();
Returns the object ID of the hyperroot collection. Currently this is always 0. The child collection of the hyperroot is the root collection of the connected server.
hw_Unlock
hw_Unlock -- unlock object
Description
int hw_unlock(int connection, int objectID);
Unlocks a document, so other users regain access.
See also hw_GetAndLock().
hw_Username
hw_Username -- name of currently logged in user
Description
string hw_getusername(int connection);
Returns the username of the connection.
XVI. Image functions
Table of Contents
GetImageSize
ImageArc
ImageChar
ImageCharUp
ImageColorAllocate
ImageColorTransparent
ImageCopyResized
ImageCreate
ImageCreateFromGif
ImageDashedLine
ImageDestroy
ImageFill
ImageFilledPolygon
ImageFilledRectangle
ImageFillToBorder
ImageFontHeight
ImageFontWidth
ImageGif
ImageInterlace
ImageLine
ImageLoadFont
ImagePolygon
ImageRectangle
ImageSetPixel
ImageString
ImageStringUp
ImageSX
ImageSY
ImageTTFBBox
ImageTTFText
ImageColorAt
ImageColorClosest
ImageColorExact
ImageColorResolve
ImageColorSet
ImageColorsForIndex
ImageColorsTotal
You can use the image functions in PHP to get the size of JPEG, GIF, and PNG images, and if you have the GD library (available at http://www.boutell.com/gd/) you will also be able to create and manipulate GIF images.
GetImageSize
GetImageSize -- get the size of a GIF, JPG or PNG image
Description
array getimagesize(string filename, array [imageinfo]);
The GetImageSize() function will determine the size of any GIF, JPG or PNG image file and return the dimensions along with the file type and a height/width text string to be used inside a normal HTML IMG tag.
Returns an array with 4 elements. Index 0 contains the width of the image in pixels. Index 1 contains the height. Index 2 a flag indicating the type of the image. 1 = GIF, 2 = JPG, 3 = PNG. Index 3 is a text string with the correct "height=xxx width=xxx" string that can be used directly in an IMG tag.
Example 1. GetImageSize
<?php $size = GetImageSize("img/flag.jpg"); ?>
<IMG SRC="img/flag.jpg" <?php echo $size[3]; ?>>
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
<?php
$size = GetImageSize("testimg.jpg",&$info);
if (isset($info["APP13"])) {
$iptc = iptcparse($info["APP13"]);
var_dump($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.
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 the header function, you can create a PHP script that outputs GIF images directly.
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 position C data type description
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:
0 lower left corner, X position
1 lower left corner, Y position
2 lower right corner, X position
3 lower right corner, Y position
4 upper right corner, X position
5 upper right corner, Y position
6 upper left corner, X position
7 upper left corner, Y position
The points are relative to the text regardless of the angle, so "upper left" means in the top left-hand corner seeing the text 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
<?php
Header("Content-type: image/gif");
$im = imagecreate(400,30);
$black = ImageColorAllocate($im, 0,0,0);
$white = ImageColorAllocate($im, 255,255,255);
ImageTTFText($im, 20, 0, 10, 20, $white, "/path/arial.ttf", "Testing... Omega: Ω");
ImageGif($im);
ImageDestroy($im);
?>
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().
XVII. IMAP Functions
Table of Contents
imap_append
imap_base64
imap_body
imap_check
imap_close
imap_createmailbox
imap_delete
imap_deletemailbox
imap_expunge
imap_fetchbody
imap_fetchstructure
imap_header
imap_headers
imap_listmailbox
imap_listsubscribed
imap_mail_copy
imap_mail_move
imap_num_msg
imap_num_recent
imap_open
imap_ping
imap_renamemailbox
imap_reopen
imap_subscribe
imap_undelete
imap_unsubscribe
imap_qprint
imap_8bit
imap_binary
imap_scanmailbox
imap_mailboxmsginfo
imap_rfc822_write_address
imap_rfc822_parse_adrlist
imap_setflag_full
imap_clearflag_full
imap_sort
imap_fetchheader
imap_uid
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.
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
