To continue, click here The strip_tags() is used when printing the SID in order to prevent XSS related attacks. Printing the SID, like shown above, is not necessary if --enable-trans-sid was used to compile PHP. Note: Non-relative URLs are assumed to point to external sites and hence don't append the SID, as it would be a security risk to leak the SID to a different server. Custom Session Handlers To implement database storage, or any other storage method, you will need to use session_set_save_handler() to create a set of user-level storage functions. 3226 session_cache_expire (PHP 4 >= 4.2.0) session_cache_expire - Return current cache expire Description int session_cache_expire ([int new_cache_expire]) session_cache_expire() returns the current setting of session.cache_expire. The value returned should be read in minutes, defaults to 180. If new_cache_expire is given, the current cache expire is replaced with new_cache_expire. The cache expire is reset to the default value of 180 stored in session.cache_limiter at request startup time. Thus, you need to call session_cache_expire() for every request (and before session_start() is called). Example 771. session_cache_expire() example "; echo "The cached session pages expire after $cache_expire minutes"; ?> Note: Setting new_cache_expire is of value only, if session.cache_limiter is set to a value different from nocache. See also the configuration settings session.cache_expire, session.cache_limiter and session_cache_limiter(). 3227 session_cache_limiter (PHP 4 >= 4.0.3) session_cache_limiter - Get and/or set the current cache limiter Description string session_cache_limiter ([string cache_limiter]) session_cache_limiter() returns the name of the current cache limiter. If cache_limiter is specified, the name of the current cache limiter is changed to the new value. The cache limiter defines which cache control HTTP headers are sent to the client. These headers determine the rules by which the page content may be cached by the client and intermediate proxies. Setting the cache limiter to nocache disallows any client/proxy caching. A value of public permits caching by proxies and the client, whereas private disallows caching by proxies and permits the client to cache the contents. In private mode, the Expire header sent to the client may cause confusion for some browsers, including Mozilla. You can avoid this problem by using private_no_expire mode. The expire header is never sent to the client in this mode. Note: private_no_expire was added in PHP 4.2.0. The cache limiter is reset to the default value stored in session.cache_limiter at request startup time. Thus, you need to call session_cache_limiter() for every request (and before session_start() is called). Example 772. session_cache_limiter() example "; ?> Also see the session.cache_limiter configuration directive. 3228 session_decode (PHP 4 ) session_decode - Decodes session data from a string Description bool session_decode (string data) session_decode() decodes the session data in data, setting variables stored in the session. See also session_encode(). 3229 session_destroy (PHP 4 ) session_destroy - Destroys all data registered to a session Description bool session_destroy (void) session_destroy() destroys all of the data associated with the current session. It does not unset any of the global variables associated with the session, or unset the session cookie. This function returns TRUE on success and FALSE on failure to destroy the session data. Example 773. Destroying a session Example 774. Destroying a session with $_SESSION 3230 session_encode (PHP 4 ) session_encode - Encodes the current session data as a string Description string session_encode (void) session_encode() returns a string with the contents of the current session encoded within. See also session_decode() 3231 session_get_cookie_params (PHP 4 ) session_get_cookie_params - Get the session cookie parameters Description array session_get_cookie_params (void) The session_get_cookie_params() function returns an array with the current session cookie information, the array contains the following items: • "lifetime" - The lifetime of the cookie. • "path" - The path where information is stored. • "domain" - The domain of the cookie. • "secure" - The cookie should only be sent over secure connections. (This item was added in PHP 4.0.4.) See also the configuration directives session.cookie_lifetime, session.cookie_path, session.cookie_domain, session.cookie_secure, and session_set_cookie_params(). 3232 session_id (PHP 4 ) session_id - Get and/or set the current session id Description string session_id ([string id]) session_id() returns the session id for the current session. If id is specified, it will replace the current session id. session_id() needs to be called before session_start() for that purpose. Depending on the session handler, not all characters are allowed within the session id. For example, the file session handler only allows characters in the range a-z, A-Z and 0-9! The constant SID can also be used to retrieve the current name and session id as a string suitable for adding to URLs. Note that SID is only defined if the client didn't send the right cookie. See also Session handling. See also session_start(), session_set_save_handler(), and session.save_handler. 3233 session_is_registered (PHP 4 ) session_is_registered - Find out whether a global variable is registered in a session Description bool session_is_registered (string name) session_is_registered() returns TRUE if there is a global variable with the name name registered in the current session. Note: If $_SESSION (or $HTTP_SESSION_VARS for PHP 4.0.6 or less) is used, use isset() to check a variable is registered in $_SESSION. Caution If you are using $_SESSION (or $HTTP_SESSION_VARS), do not use session_register(), session_is_registered() and session_unregister(). 3234 session_module_name (PHP 4 ) session_module_name - Get and/or set the current session module Description string session_module_name ([string module]) session_module_name() returns the name of the current session module. If module is specified, that module will be used instead. 3235 session_name (PHP 4 ) session_name - Get and/or set the current session name Description string session_name ([string name]) session_name() returns the name of the current session. If name is specified, the name of the current session is changed to its value. The session name references the session id in cookies and URLs. It should contain only alphanumeric characters; it should be short and descriptive (i.e. for users with enabled cookie warnings). The session name is reset to the default value stored in session.name at request startup time. Thus, you need to call session_name() for every request (and before session_start() or session_register() are called). Example 775. session_name() examples "; ?> See also the session.name configuration directive. 3236 session_regenerate_id (PHP 4 >= 4.3.2) session_regenerate_id - Update the current session id with a newly generated one Description bool session_regenerate_id (void) session_regenerate_id() will replace the current session id with a new one, and keep the current session information. Returns TRUE on success or FALSE on failure. Example 776. A session_regenerate_id() example Note: As of PHP 4.3.3, if session cookies are enabled, use of session_regenerate_id() will also submit a new session cookie with the new session id. See also session_id(), session_start(), and session_name(). 3237 session_register (PHP 4 ) session_register - Register one or more global variables with the current session Description bool session_register (mixed name [, mixed ...]) session_register() accepts a variable number of arguments, any of which can be either a string holding the name of a variable or an array consisting of variable names or other arrays. For each name, session_register() registers the global variable with that name in the current session. Caution If you want your script to work regardless of register_globals, you need to use the $_SESSION array. All $_SESSION entries are automatically registered. If your script uses session_register(), it will not work in environments where register_globals is disabled. Caution This registers a global variable. If you want to register a session variable from within a function, you need to make sure to make it global using the global keyword or the $GLOBALS[] array, or use the special session arrays as noted below. Caution If you are using $_SESSION (or $HTTP_SESSION_VARS), do not use session_register(), session_is_registered(), and session_unregister(). This function returns TRUE when all of the variables are successfully registered with the session. If session_start() was not called before this function is called, an implicit call to session_start() with no parameters will be made. $_SESSION does not mimic this behavior and requires session_start() before use. You can also create a session variable by simply setting the appropriate member of the $_SESSION or $HTTP_SESSION_VARS (PHP < 4.1.0) array. $barney = "A big purple dinosaur."; session_register("barney"); $_SESSION["zim"] = "An invader from another planet."; # The old way was to use $HTTP_SESSION_VARS $HTTP_SESSION_VARS["spongebob"] = "He's got square pants."; Note: It is currently impossible to register resource variables in a session. For example, you cannot create a connection to a database and store the connection id as a session variable and expect the connection to still be valid the next time the session is restored. PHP functions that return a resource are identified by having a return type of resource in their function definition. A list of functions that return resources are available in the resource types appendix. If $_SESSION (or $HTTP_SESSION_VARS for PHP 4.0.6 or less) is used, assign values to $_SESSION. For example: $_SESSION['var'] = 'ABC'; See also session_is_registered() and session_unregister(). 3238 session_save_path (PHP 4 ) session_save_path - Get and/or set the current session save path Description string session_save_path ([string path]) session_save_path() returns the path of the current directory used to save session data. If path is specified, the path to which data is saved will be changed. session_save_path() needs to be called before session_start() for that purpose. Note: On some operating systems, you may want to specify a path on a filesystem that handles lots of small files efficiently. For example, on Linux, reiserfs may provide better performance than ext2fs. See also the session.save_path configuration directive. 3239 session_set_cookie_params (PHP 4 ) session_set_cookie_params - Set the session cookie parameters Description void session_set_cookie_params (int lifetime [, string path [, string domain [, bool secure]]]) Set cookie parameters defined in the php.ini file. The effect of this function only lasts for the duration of the script. Note: The secure parameter was added in PHP 4.0.4. See also the configuration directives session.cookie_lifetime, session.cookie_path, session.cookie_domain, session.cookie_secure, and session_get_cookie_params(). 3240 session_set_save_handler (PHP 4 ) session_set_save_handler - Sets user-level session storage functions Description bool session_set_save_handler (string open, string close, string read, string write, string destroy, string gc) session_set_save_handler() sets the user-level session storage functions which are used for storing and retrieving data associated with a session. This is most useful when a storage method other than those supplied by PHP sessions is preferred. i.e. Storing the session data in a local database. Returns TRUE on success or FALSE on failure. Note: The "write" handler is not executed until after the output stream is closed. Thus, output from debugging statements in the "write" handler will never be seen in the browser. If debugging output is necessary, it is suggested that the debug output be written to a file instead. Note: The write handler is not executed if the session contains no data; this applies even if empty session variables are registered. This differs to the default file-based session save handler, which creates empty session files. The following example provides file based session storage similar to the PHP sessions default save handler files. This example could easily be extended to cover database storage using your favorite PHP supported database engine. Read function must return string value always to make save handler work as expected. Return empty string if there is no data to read. Return values from other handlers are converted to boolean expression. TRUE for success, FALSE for failure. Example 777. session_set_save_handler() example See also the session.save_handler configuration directive. 3242 session_start (PHP 4 ) session_start - Initialize session data Description bool session_start (void) session_start() creates a session or resumes the current one based on the current session id that's being passed via a request, such as GET, POST, or a cookie. If you want to use a named session, you must call session_name() before calling session_start(). This function always returns TRUE. Note: If you are using cookie-based sessions, you must call session_start() before anything is output to the browser. session_start() will register internal output handler for URL rewriting when trans-sid is enabled. If a user uses ob_gzhandler or like with ob_start(), the order of output handler is important for proper output. For example, user must register ob_gzhandler before session start. Note: Use of zlib.output_compression is recommended rather than ob_gzhandler() 3243 session_unregister (PHP 4 ) session_unregister - Unregister a global variable from the current session Description bool session_unregister (string name) session_unregister() unregisters the global variable named name from the current session. This function returns TRUE when the variable is successfully unregistered from the session. Note: If $_SESSION (or $HTTP_SESSION_VARS for PHP 4.0.6 or less) is used, use unset() to unregister a session variable. Do not unset() $_SESSION itself as this will disable the special function of the $_SESSION superglobal. Caution This function does not unset the corresponding global variable for name, it only prevents the variable from being saved as part of the session. You must call unset() to remove the corresponding global variable. Caution If you are using $_SESSION (or $HTTP_SESSION_VARS), do not use session_register(), session_is_registered() and session_unregister(). 3244 session_unset (PHP 4 ) session_unset - Free all session variables Description void session_unset (void) The session_unset() function frees all session variables currently registered. Note: If $_SESSION (or $HTTP_SESSION_VARS for PHP 4.0.6 or less) is used, use unset() to unregister session variable. i.e. $_SESSION = array(); Caution Do NOT unset the whole $_SESSION with unset($_SESSION) as this will disable the registering of session variables through the $_SESSION superglobal. 3245 session_write_close (PHP 4 >= 4.0.4) session_write_close - Write session data and end session Description void session_write_close (void) End the current session and store session data. Session data is usually stored after your script terminated without the need to call session_write_close(), but as session data is locked to prevent concurrent writes only one script may operate on a session at any time. When using framesets together with sessions you will experience the frames loading one by one due to this locking. You can reduce the time needed to load all the frames by ending the session as soon as all changes to session variables are done. 3246 Shared Memory Functions Table of Contents shmop_close ................................................................................................................................... 3250 shmop_delete .................................................................................................................................. 3251 shmop_open .................................................................................................................................... 3252 shmop_read .................................................................................................................................... 3253 shmop_size ..................................................................................................................................... 3254 shmop_write ................................................................................................................................... 3255 3247 Introduction Shmop is an easy to use set of functions that allows PHP to read, write, create and delete UNIX shared memory segments. These functions will not typically work on Windows, as it does not support shared memory. As of Windows 2000 though, enabling the php_shmop.dll in your php.ini will enable this functionality though. Note: In PHP 4.0.3, these functions were prefixed by shm rather than shmop. Requirements No external libraries are needed to build this extension. Installation To use shmop you will need to compile PHP with the --enable-shmop parameter in your configure line. Runtime Configuration This extension has no configuration directives defined in php.ini. Resource Types Predefined Constants This extension has no constants defined. Examples Example 778. Shared Memory Operations Overview 3249 shmop_close (PHP 4 >= 4.0.4) shmop_close - Close shared memory block Description int shmop_close (int shmid) shmop_close() is used to close a shared memory block. shmop_close() takes the shmid, which is the shared memory block identifier created by shmop_open(). Example 779. Closing shared memory block This example will close shared memory block identified by $shm_id. 3250 shmop_delete (PHP 4 >= 4.0.4) shmop_delete - Delete shared memory block Description int shmop_delete (int shmid) shmop_delete() is used to delete a shared memory block. shmop_delete() takes the shmid, which is the shared memory block identifier created by shmop_open(). On success 1 is returned, on failure 0 is returned. Example 780. Deleting shared memory block This example will delete shared memory block identified by $shm_id. 3251 shmop_open (PHP 4 >= 4.0.4) shmop_open - Create or open shared memory block Description int shmop_open (int key, string flags, int mode, int size) shmop_open() can create or open a shared memory block. shmop_open() takes 4 parameters: key, which is the system's id for the shared memory block, this parameter can be passed as a decimal or hex. The second parameter are the flags that you can use: • "a" for access (sets SHM_RDONLY for shmat) use this flag when you need to open an existing shared memory segment for read only • "c" for create (sets IPC_CREATE) use this flag when you need to create a new shared memory segment or if a segment with the same key exists, try to open it for read and write • "w" for read & write access use this flag when you need to read and write to a shared memory segment, use this flag in most cases. • "n" create a new memory segment (sets IPC_CREATE|IPC_EXCL) use this flag when you want to create a new shared memory segment but if one already exists with the same flag, fail. This is useful for security purposes, using this you can prevent race condition exploits. The third parameter is the mode, which are the permissions that you wish to assign to your memory segment, those are the same as permission for a file. Permissions need to be passed in octal form ex. 0644. The last parameter is size of the shared memory block you wish to create in bytes. Note: Note: the 3rd and 4th should be entered as 0 if you are opening an existing memory segment. On success shmop_open() will return an id that you can use to access the shared memory segment you've created. Example 781. Create a new shared memory block This example opened a shared memory block with a system id returned by ftok(). 3252 shmop_read (PHP 4 >= 4.0.4) shmop_read - Read data from shared memory block Description string shmop_read (int shmid, int start, int count) shmop_read() will read a string from shared memory block. shmop_read() takes 3 parameters: shmid, which is the shared memory block identifier created by shmop_open(), offset from which to start reading and count on the number of bytes to read. Example 782. Reading shared memory block This example will read 50 bytes from shared memory block and place the data inside $shm_data. 3253 shmop_size (PHP 4 >= 4.0.4) shmop_size - Get size of shared memory block Description int shmop_size (int shmid) shmop_size() is used to get the size, in bytes of the shared memory block. shmop_size() takes the shmid, which is the shared memory block identifier created by shmop_open(), the function will return and int, which represents the number of bytes the shared memory block occupies. Example 783. Getting the size of the shared memory block This example will put the size of shared memory block identified by $shm_id into $shm_size. 3254 shmop_write (PHP 4 >= 4.0.4) shmop_write - Write data into shared memory block Description int shmop_write (int shmid, string data, int offset) shmop_write() will write a string into shared memory block. shmop_write() takes 3 parameters: shmid, which is the shared memory block identifier created by shmop_open(), data, a string that you want to write into shared memory block and offset, which specifies where to start writing data inside the shared memory segment. Example 784. Writing to shared memory block This example will write data inside $my_string into shared memory block, $shm_bytes_written will contain the number of bytes written. 3255 Shockwave Flash functions Table of Contents swf_actiongeturl .............................................................................................................................. 3261 swf_actiongotoframe ........................................................................................................................ 3262 swf_actiongotolabel .......................................................................................................................... 3263 swf_actionnextframe ......................................................................................................................... 3264 swf_actionplay ................................................................................................................................ 3265 swf_actionprevframe ........................................................................................................................ 3266 swf_actionsettarget ........................................................................................................................... 3267 swf_actionstop ................................................................................................................................ 3268 swf_actiontogglequality .................................................................................................................... 3269 swf_actionwaitforframe ..................................................................................................................... 3270 swf_addbuttonrecord ........................................................................................................................ 3271 swf_addcolor ................................................................................................................................... 3272 swf_closefile ................................................................................................................................... 3273 swf_definebitmap ............................................................................................................................. 3275 swf_definefont ................................................................................................................................ 3276 swf_defineline ................................................................................................................................. 3277 swf_definepoly ................................................................................................................................ 3278 swf_definerect ................................................................................................................................. 3279 swf_definetext ................................................................................................................................. 3280 swf_endbutton ................................................................................................................................. 3281 swf_enddoaction .............................................................................................................................. 3282 swf_endshape .................................................................................................................................. 3283 swf_endsymbol ................................................................................................................................ 3284 swf_fontsize .................................................................................................................................... 3285 swf_fontslant ................................................................................................................................... 3286 swf_fonttracking .............................................................................................................................. 3287 swf_getbitmapinfo ........................................................................................................................... 3288 swf_getfontinfo ............................................................................................................................... 3289 swf_getframe .................................................................................................................................. 3290 swf_labelframe ................................................................................................................................ 3291 swf_lookat ...................................................................................................................................... 3292 swf_modifyobject ............................................................................................................................ 3293 swf_mulcolor .................................................................................................................................. 3294 swf_nextid ...................................................................................................................................... 3295 swf_oncondition .............................................................................................................................. 3296 swf_openfile ................................................................................................................................... 3297 swf_ortho2 ..................................................................................................................................... 3298 swf_ortho ....................................................................................................................................... 3299 swf_perspective ............................................................................................................................... 3300 swf_placeobject ............................................................................................................................... 3301 swf_polarview ................................................................................................................................. 3302 swf_popmatrix ................................................................................................................................ 3303 swf_posround .................................................................................................................................. 3304 swf_pushmatrix ............................................................................................................................... 3305 swf_removeobject ............................................................................................................................ 3306 swf_rotate ....................................................................................................................................... 3307 swf_scale ........................................................................................................................................ 3308 swf_setfont ..................................................................................................................................... 3309 3256 SWF swf_setframe ................................................................................................................................... 3310 swf_shapearc ................................................................................................................................... 3311 swf_shapecurveto3 ........................................................................................................................... 3312 swf_shapecurveto ............................................................................................................................. 3313 swf_shapefillbitmapclip .................................................................................................................... 3314 swf_shapefillbitmaptile ..................................................................................................................... 3315 swf_shapefilloff ............................................................................................................................... 3316 swf_shapefillsolid ............................................................................................................................ 3317 swf_shapelinesolid ........................................................................................................................... 3318 swf_shapelineto ............................................................................................................................... 3319 swf_shapemoveto ............................................................................................................................. 3320 swf_showframe ............................................................................................................................... 3321 swf_startbutton ................................................................................................................................ 3322 swf_startdoaction ............................................................................................................................. 3323 swf_startshape ................................................................................................................................. 3324 swf_startsymbol ............................................................................................................................... 3325 swf_textwidth .................................................................................................................................. 3326 swf_translate ................................................................................................................................... 3327 swf_viewport .................................................................................................................................. 3328 3257 Introduction PHP offers the ability to create Shockwave Flash files via Paul Haeberli's libswf module. Note: SWF support was added in PHP 4 RC2. The libswf does not have support for Windows. The development of that library has been stopped, and the source is not available to port it to another systems. For up to date SWF support take a look at the MING functions. Requirements You need the libswf library to compile PHP with support for this extension. You can download libswf at ftp://ftp.sgi.com/ sgi/graphics/grafica/flash/. Installation Once you have libswf all you need to do is to configure --with-swf[=DIR] where DIR is a location containing the directories include and lib. The include directory has to contain the swf.h file and the lib directory has to contain the libswf.a file. If you unpack the libswf distribution the two files will be in one directory. Consequently you will have to copy the files to the proper location manually. Runtime Configuration This extension has no configuration directives defined in php.ini. Resource Types This extension has no resource types defined. Predefined Constants The constants below are defined by this extension, and will only be available when the extension has either been compiled into PHP or dynamically loaded at runtime. MOD_COLOR (integer) MOD_MATRIX (integer) TYPE_PUSHBUTTON (integer) TYPE_MENUBUTTON (integer) BSHitTest (float) BSDown (float) BSOver (float) BSUp (float) 3258 Shockwave Flash functions OverDowntoIdle (integer) IdletoOverDown (integer) OutDowntoIdle (integer) OutDowntoOverDown (integer) OverDowntoOutDown (integer) OverUptoOverDown (integer) OverUptoIdle (integer) IdletoOverUp (integer) ButtonEnter (integer) ButtonExit (integer) MenuEnter (integer) MenuExit (integer) Examples Once you've successfully installed PHP with Shockwave Flash support you can then go about creating Shockwave files from PHP. You would be surprised at what you can do, take the following code: Example 785. SWF example 3260 swf_actiongeturl (PHP 4 <= 4.3.2) swf_actiongeturl - Get a URL from a Shockwave Flash movie Description void swf_actiongeturl (string url, string target) The swf_actiongeturl() function gets the URL specified by the parameter url with the target target. 3261 swf_actiongotoframe (PHP 4 <= 4.3.2) swf_actiongotoframe - Play a frame and then stop Description void swf_actiongotoframe (int framenumber) The swf_actiongotoframe() function will go to the frame specified by framenumber, play it, and then stop. 3262 swf_actiongotolabel (PHP 4 <= 4.3.2) swf_actiongotolabel - Display a frame with the specified label Description void swf_actiongotolabel (string label) The swf_actiongotolabel() function displays the frame with the label given by the label parameter and then stops. 3263 swf_actionnextframe (PHP 4 <= 4.3.2) swf_actionnextframe - Go foward one frame Description void swf_actionnextframe (void) Go foward one frame. 3264 swf_actionplay (PHP 4 <= 4.3.2) swf_actionplay - Start playing the flash movie from the current frame Description void swf_actionplay (void) Start playing the flash movie from the current frame. 3265 swf_actionprevframe (PHP 4 <= 4.3.2) swf_actionprevframe - Go backwards one frame Description void swf_actionprevframe (void) 3266 swf_actionsettarget (PHP 4 <= 4.3.2) swf_actionsettarget - Set the context for actions Description void swf_actionsettarget (string target) The swf_actionsettarget() function sets the context for all actions. You can use this to control other flash movies that are currently playing. 3267 swf_actionstop (PHP 4 <= 4.3.2) swf_actionstop - Stop playing the flash movie at the current frame Description void swf_actionstop (void) Stop playing the flash movie at the current frame. 3268 swf_actiontogglequality (PHP 4 <= 4.3.2) swf_actiontogglequality - Toggle between low and high quality Description void swf_actiontogglequality (void) Toggle the flash movie between high and low quality. 3269 swf_actionwaitforframe (PHP 4 <= 4.3.2) swf_actionwaitforframe - Skip actions if a frame has not been loaded Description void swf_actionwaitforframe (int framenumber, int skipcount) The swf_actionwaitforframe() function will check to see if the frame, specified by the framenumber parameter has been loaded, if not it will skip the number of actions specified by the skipcount parameter. This can be useful for "Loading..." type animations. 3270 swf_addbuttonrecord (PHP 4 <= 4.3.2) swf_addbuttonrecord - Controls location, appearance and active area of the current button Description void swf_addbuttonrecord (int states, int shapeid, int depth) The swf_addbuttonrecord() function allows you to define the specifics of using a button. The first parameter, states, defines what states the button can have, these can be any or all of the following constants: BSHitTest, BSDown, BSOver or BSUp. The second parameter, the shapeid is the look of the button, this is usually the object id of the shape of the button. The depth parameter is the placement of the button in the current frame. Example 786. swf_addbuttonrecord() function example swf_startButton ($objid, TYPE_MENUBUTTON); swf_addButtonRecord (BSDown|BSOver, $buttonImageId, 340); swf_onCondition (MenuEnter); swf_actionGetUrl ("http://www.designmultimedia.com", "_level1"); swf_onCondition (MenuExit); swf_actionGetUrl ("", "_level1"); swf_endButton (); 3271 swf_addcolor (PHP 4 <= 4.3.2) swf_addcolor - Set the global add color to the rgba value specified Description void swf_addcolor (float r, float g, float b, float a) The swf_addcolor() function sets the global add color to the rgba color specified. This color is then used (implicitly) by the swf_placeobject(), swf_modifyobject() and the swf_addbuttonrecord() functions. The color of the object will be add by the rgba values when the object is written to the screen. Note: The rgba values can be either positive or negative. 3272 swf_closefile (PHP 4 <= 4.3.2) swf_closefile - Close the current Shockwave Flash file Description void swf_closefile ([int return_file ]) Close a file that was opened by the swf_openfile() function. If the return_file parameter is set then the contents of the SWF file are returned from the function. Example 787. Creating a simple flash file based on user input and outputting it and saving it in a database 3274 swf_definebitmap (PHP 4 <= 4.3.2) swf_definebitmap - Define a bitmap Description void swf_definebitmap (int objid, string image_name) The swf_definebitmap() function defines a bitmap given a GIF, JPEG, RGB or FI image. The image will be converted into a Flash JPEG or Flash color map format. 3275 swf_definefont (PHP 4 <= 4.3.2) swf_definefont - Defines a font Description void swf_definefont (int fontid, string fontname) The swf_definefont() function defines a font given by the fontname parameter and gives it the id specified by the fontid parameter. It then sets the font given by fontname to the current font. 3276 swf_defineline (PHP 4 <= 4.3.2) swf_defineline - Define a line Description void swf_defineline (int objid, float x1, float y1, float x2, float y2, float width) The swf_defineline() defines a line starting from the x coordinate given by x1 and the y coordinate given by y1 parameter. Up to the x coordinate given by the x2 parameter and the y coordinate given by the y2 parameter. It will have a width defined by the width parameter. 3277 swf_definepoly (PHP 4 <= 4.3.2) swf_definepoly - Define a polygon Description void swf_definepoly (int objid, array coords, int npoints, float width) The swf_definepoly() function defines a polygon given an array of x, y coordinates (the coordinates are defined in the parameter coords). The parameter npoints is the number of overall points that are contained in the array given by coords. The width is the width of the polygon's border, if set to 0.0 the polygon is filled. 3278 swf_definerect (PHP 4 <= 4.3.2) swf_definerect - Define a rectangle Description void swf_definerect (int objid, float x1, float y1, float x2, float y2, float width) The swf_definerect() defines a rectangle with an upper left hand coordinate given by the x, x1, and the y, y1. And a lower right hand coordinate given by the x coordinate, x2, and the y coordinate, y2 . Width of the rectangles border is given by the width parameter, if the width is 0.0 then the rectangle is filled. 3279 swf_definetext (PHP 4 <= 4.3.2) swf_definetext - Define a text string Description void swf_definetext (int objid, string str, int docenter) Define a text string (the str parameter) using the current font and font size. The docenter is where the word is centered, if docenter is 1, then the word is centered in x. 3280 swf_endbutton (PHP 4 <= 4.3.2) swf_endbutton - End the definition of the current button Description void swf_endbutton (void) The swf_endbutton() function ends the definition of the current button. 3281 swf_enddoaction (PHP 4 <= 4.3.2) swf_enddoaction - End the current action Description void swf_enddoaction (void) Ends the current action started by the swf_startdoaction() function. 3282 swf_endshape (PHP 4 <= 4.3.2) swf_endshape - Completes the definition of the current shape Description void swf_endshape (void) The swf_endshape() completes the definition of the current shape. 3283 swf_endsymbol (PHP 4 <= 4.3.2) swf_endsymbol - End the definition of a symbol Description void swf_endsymbol (void) The swf_endsymbol() function ends the definition of a symbol that was started by the swf_startsymbol() function. 3284 swf_fontsize (PHP 4 <= 4.3.2) swf_fontsize - Change the font size Description void swf_fontsize (float size) The swf_fontsize() function changes the font size to the value given by the size parameter. 3285 swf_fontslant (PHP 4 <= 4.3.2) swf_fontslant - Set the font slant Description void swf_fontslant (float slant) Set the current font slant to the angle indicated by the slant parameter. Positive values create a foward slant, negative values create a negative slant. 3286 swf_fonttracking (PHP 4 <= 4.3.2) swf_fonttracking - Set the current font tracking Description void swf_fonttracking (float tracking) Set the font tracking to the value specified by the tracking parameter. This function is used to increase the spacing between letters and text, positive values increase the space and negative values decrease the space between letters. 3287 swf_getbitmapinfo (PHP 4 <= 4.3.2) swf_getbitmapinfo - Get information about a bitmap Description array swf_getbitmapinfo (int bitmapid) The swf_getbitmapinfo() function returns an array of information about a bitmap given by the bitmapid parameter. The returned array has the following elements: • "size" - The size in bytes of the bitmap. • "width" - The width in pixels of the bitmap. • "height" - The height in pixels of the bitmap. 3288 swf_getfontinfo (PHP 4 <= 4.3.2) swf_getfontinfo - The height in pixels of a capital A and a lowercase x Description array swf_getfontinfo (void) The swf_getfontinfo() function returns an associative array with the following parameters: • Aheight - The height in pixels of a capital A. • xheight - The height in pixels of a lowercase x. 3289 swf_getframe (PHP 4 <= 4.3.2) swf_getframe - Get the frame number of the current frame Description int swf_getframe (void) The swf_getframe() function gets the number of the current frame. 3290 swf_labelframe (PHP 4 <= 4.3.2) swf_labelframe - Label the current frame Description void swf_labelframe (string name) Label the current frame with the name given by the name parameter. 3291 swf_lookat (PHP 4 <= 4.3.2) swf_lookat - Define a viewing transformation Description void swf_lookat (float view_x, float view_y, float view_z, float reference_x, float reference_y, float reference_z, float twist) The swf_lookat() function defines a viewing transformation by giving the viewing position (the parameters view_x, view_y, and view_z) and the coordinates of a reference point in the scene, the reference point is defined by the reference_x, reference_y , and reference_z parameters. The twist controls the rotation along with viewer's z axis. 3292 swf_modifyobject (PHP 4 <= 4.3.2) swf_modifyobject - Modify an object Description void swf_modifyobject (int depth, int how) Updates the position and/or color of the object at the specified depth, depth. The parameter how determines what is updated. how can either be the constant MOD_MATRIX or MOD_COLOR or it can be a combination of both (MOD_MATRIX|MOD_COLOR). MOD_COLOR uses the current mulcolor (specified by the function swf_mulcolor()) and addcolor (specified by the function swf_addcolor()) to color the object. MOD_MATRIX uses the current matrix to position the object. 3293 swf_mulcolor (PHP 4 <= 4.3.2) swf_mulcolor - Sets the global multiply color to the rgba value specified Description void swf_mulcolor (float r, float g, float b, float a) The swf_mulcolor() function sets the global multiply color to the rgba color specified. This color is then used (implicitly) by the swf_placeobject(), swf_modifyobject() and the swf_addbuttonrecord() functions. The color of the object will be multiplied by the rgba values when the object is written to the screen. Note: The rgba values can be either positive or negative. 3294 swf_nextid (PHP 4 <= 4.3.2) swf_nextid - Returns the next free object id Description int swf_nextid (void) The swf_nextid() function returns the next available object id. 3295 swf_oncondition (PHP 4 <= 4.3.2) swf_oncondition - Describe a transition used to trigger an action list Description void swf_oncondition (int transition) The swf_oncondition() function describes a transition that will trigger an action list. There are several types of possible transitions, the following are for buttons defined as TYPE_MENUBUTTON: • IdletoOverUp • OverUptoIdle • OverUptoOverDown • OverDowntoOverUp • IdletoOverDown • OutDowntoIdle • MenuEnter (IdletoOverUp|IdletoOverDown) • MenuExit (OverUptoIdle|OverDowntoIdle) For TYPE_PUSHBUTTON there are the following options: • IdletoOverUp • OverUptoIdle • OverUptoOverDown • OverDowntoOverUp • OverDowntoOutDown • OutDowntoOverDown • OutDowntoIdle • ButtonEnter (IdletoOverUp|OutDowntoOverDown) • ButtonExit (OverUptoIdle|OverDowntoOutDown) 3296 swf_openfile (PHP 4 <= 4.3.2) swf_openfile - Open a new Shockwave Flash file Description void swf_openfile (string filename, float width, float height, float framerate, float r, float g, float b) The swf_openfile() function opens a new file named filename with a width of width and a height of height a frame rate of framerate and background with a red color of r a green color of g and a blue color of b. The swf_openfile() must be the first function you call, otherwise your script will cause a segfault. If you want to send your output to the screen make the filename: "php://stdout" (support for this is in 4.0.1 and up). 3297 swf_ortho2 (PHP 4 <= 4.3.2) swf_ortho2 - Defines 2D orthographic mapping of user coordinates onto the current viewport Description void swf_ortho2 (float xmin, float xmax, float ymin, float ymax) The swf_ortho2() function defines a two dimensional orthographic mapping of user coordinates onto the current viewport, this defaults to one to one mapping of the area of the Flash movie. If a perspective transformation is desired, the swf_perspective () function can be used. 3298 swf_ortho (4.0.1 - 4.3.2 only) swf_ortho - Defines an orthographic mapping of user coordinates onto the current viewport Description void swf_ortho (float xmin, float xmax, float ymin, float ymax, float zmin, float zmax) The swf_ortho() function defines an orthographic mapping of user coordinates onto the current viewport. 3299 swf_perspective (PHP 4 <= 4.3.2) swf_perspective - Define a perspective projection transformation Description void swf_perspective (float fovy, float aspect, float near, float far) The swf_perspective() function defines a perspective projection transformation. The fovy parameter is field-of-view angle in the y direction. The aspect parameter should be set to the aspect ratio of the viewport that is being drawn onto. The near parameter is the near clipping plane and the far parameter is the far clipping plane. Note: Various distortion artifacts may appear when performing a perspective projection, this is because Flash players only have a two dimensional matrix. Some are not to pretty. 3300 swf_placeobject (PHP 4 <= 4.3.2) swf_placeobject - Place an object onto the screen Description void swf_placeobject (int objid, int depth) Places the object specified by objid in the current frame at a depth of depth. The objid parameter and the depth must be between 1 and 65535. This uses the current mulcolor (specified by swf_mulcolor()) and the current addcolor (specified by swf_addcolor()) to color the object and it uses the current matrix to position the object. Note: Full RGBA colors are supported. 3301 swf_polarview (PHP 4 <= 4.3.2) swf_polarview - Define the viewer's position with polar coordinates Description void swf_polarview (float dist, float azimuth, float incidence, float twist) The swf_polarview() function defines the viewer's position in polar coordinates. The dist parameter gives the distance between the viewpoint to the world space origin. The azimuth parameter defines the azimuthal angle in the x,y coordinate plane, measured in distance from the y axis. The incidence parameter defines the angle of incidence in the y,z plane, measured in distance from the z axis. The incidence angle is defined as the angle of the viewport relative to the z axis. Finally the twist specifies the amount that the viewpoint is to be rotated about the line of sight using the right hand rule. 3302 swf_popmatrix (PHP 4 <= 4.3.2) swf_popmatrix - Restore a previous transformation matrix Description void swf_popmatrix (void) The swf_popmatrix() function pushes the current transformation matrix back onto the stack. 3303 swf_posround (PHP 4 <= 4.3.2) swf_posround - Enables or Disables the rounding of the translation when objects are placed or moved Description void swf_posround (int round) The swf_posround() function enables or disables the rounding of the translation when objects are placed or moved, there are times when text becomes more readable because rounding has been enabled. The round is whether to enable rounding or not, if set to the value of 1, then rounding is enabled, if set to 0 then rounding is disabled. 3304 swf_pushmatrix (PHP 4 <= 4.3.2) swf_pushmatrix - Push the current transformation matrix back unto the stack Description void swf_pushmatrix (void) The swf_pushmatrix() function pushes the current transformation matrix back onto the stack. 3305 swf_removeobject (PHP 4 <= 4.3.2) swf_removeobject - Remove an object Description void swf_removeobject (int depth) Removes the object at the depth specified by depth. 3306 swf_rotate (PHP 4 <= 4.3.2) swf_rotate - Rotate the current transformation Description void swf_rotate (float angle, string axis) The swf_rotate() rotates the current transformation by the angle given by the angle parameter around the axis given by the axis parameter. Valid values for the axis are 'x' (the x axis), 'y' (the y axis) or 'z' (the z axis). 3307 swf_scale (PHP 4 <= 4.3.2) swf_scale - Scale the current transformation Description void swf_scale (float x, float y, float z) The swf_scale() scales the x coordinate of the curve by the value of the x parameter, the y coordinate of the curve by the value of the y parameter, and the z coordinate of the curve by the value of the z parameter. 3308 swf_setfont (PHP 4 <= 4.3.2) swf_setfont - Change the current font Description void swf_setfont (int fontid) The swf_setfont() sets the current font to the value given by the fontid parameter. 3309 swf_setframe (PHP 4 <= 4.3.2) swf_setframe - Switch to a specified frame Description void swf_setframe (int framenumber) The swf_setframe() changes the active frame to the frame specified by framenumber. 3310 swf_shapearc (PHP 4 <= 4.3.2) swf_shapearc - Draw a circular arc Description void swf_shapearc (float x, float y, float r, float ang1, float ang2) The swf_shapearc() function draws a circular arc from angle A given by the ang1 parameter to angle B given by the ang2 parameter. The center of the circle has an x coordinate given by the x parameter and a y coordinate given by the y, the radius of the circle is given by the r parameter. 3311 swf_shapecurveto3 (PHP 4 <= 4.3.2) swf_shapecurveto3 - Draw a cubic bezier curve Description void swf_shapecurveto3 (float x1, float y1, float x2, float y2, float x3, float y3) Draw a cubic bezier curve using the x,y coordinate pairs x1, y1 and x2,y2 as off curve control points and the x,y coordinate x3, y3 as an endpoint. The current position is then set to the x,y coordinate pair given by x3,y3. 3312 swf_shapecurveto (PHP 4 <= 4.3.2) swf_shapecurveto - Draw a quadratic bezier curve between two points Description void swf_shapecurveto (float x1, float y1, float x2, float y2) The swf_shapecurveto() function draws a quadratic bezier curve from the current location, though the x coordinate given by x1 and the y coordinate given by y1 to the x coordinate given by x2 and the y coordinate given by y2. The current position is then set to the x,y coordinates given by the x2 and y2 parameters 3313 swf_shapefillbitmapclip (PHP 4 <= 4.3.2) swf_shapefillbitmapclip - Set current fill mode to clipped bitmap Description void swf_shapefillbitmapclip (int bitmapid) Sets the fill to bitmap clipped, empty spaces will be filled by the bitmap given by the bitmapid parameter. 3314 swf_shapefillbitmaptile (PHP 4 <= 4.3.2) swf_shapefillbitmaptile - Set current fill mode to tiled bitmap Description void swf_shapefillbitmaptile (int bitmapid) Sets the fill to bitmap tile, empty spaces will be filled by the bitmap given by the bitmapid parameter (tiled). 3315 swf_shapefilloff (PHP 4 <= 4.3.2) swf_shapefilloff - Turns off filling Description void swf_shapefilloff (void) The swf_shapefilloff() function turns off filling for the current shape. 3316 swf_shapefillsolid (PHP 4 <= 4.3.2) swf_shapefillsolid - Set the current fill style to the specified color Description void swf_shapefillsolid (float r, float g, float b, float a) The swf_shapefillsolid() function sets the current fill style to solid, and then sets the fill color to the values of the rgba parameters. 3317 swf_shapelinesolid (PHP 4 <= 4.3.2) swf_shapelinesolid - Set the current line style Description void swf_shapelinesolid (float r, float g, float b, float a, float width) The swf_shapelinesolid() function sets the current line style to the color of the rgba parameters and width to the width parameter. If 0.0 is given as a width then no lines are drawn. 3318 swf_shapelineto (PHP 4 <= 4.3.2) swf_shapelineto - Draw a line Description void swf_shapelineto (float x, float y) The swf_shapelineto() draws a line to the x,y coordinates given by the x parameter & the y parameter. The current position is then set to the x,y parameters. 3319 swf_shapemoveto (PHP 4 <= 4.3.2) swf_shapemoveto - Move the current position Description void swf_shapemoveto (float x, float y) The swf_shapemoveto() function moves the current position to the x coordinate given by the x parameter and the y position given by the y parameter. 3320 swf_showframe (PHP 4 <= 4.3.2) swf_showframe - Display the current frame Description void swf_showframe (void) The swf_showframe function will output the current frame. 3321 swf_startbutton (PHP 4 <= 4.3.2) swf_startbutton - Start the definition of a button Description void swf_startbutton (int objid, int type) The swf_startbutton() function starts off the definition of a button. The type parameter can either be TYPE_MENUBUTTON or TYPE_PUSHBUTTON. The TYPE_MENUBUTTON constant allows the focus to travel from the button when the mouse is down, TYPE_PUSHBUTTON does not allow the focus to travel when the mouse is down. 3322 swf_startdoaction (PHP 4 <= 4.3.2) swf_startdoaction - Start a description of an action list for the current frame Description void swf_startdoaction (void) The swf_startdoaction() function starts the description of an action list for the current frame. This must be called before actions are defined for the current frame. 3323 swf_startshape (PHP 4 <= 4.3.2) swf_startshape - Start a complex shape Description void swf_startshape (int objid) The swf_startshape() function starts a complex shape, with an object id given by the objid parameter. 3324 swf_startsymbol (PHP 4 <= 4.3.2) swf_startsymbol - Define a symbol Description void swf_startsymbol (int objid) Define an object id as a symbol. Symbols are tiny flash movies that can be played simultaneously. The objid parameter is the object id you want to define as a symbol. 3325 swf_textwidth (PHP 4 <= 4.3.2) swf_textwidth - Get the width of a string Description float swf_textwidth (string str) The swf_textwidth() function gives the width of the string, str, in pixels, using the current font and font size. 3326 swf_translate (PHP 4 <= 4.3.2) swf_translate - Translate the current transformations Description void swf_translate (float x, float y, float z) The swf_translate() function translates the current transformation by the x, y, and z values given. 3327 swf_viewport (PHP 4 <= 4.3.2) swf_viewport - Select an area for future drawing Description void swf_viewport (float xmin, float xmax, float ymin, float ymax) The swf_viewport() function selects an area for future drawing for xmin to xmax and ymin to ymax, if this function is not called the area defaults to the size of the screen. 3328 SNMP functions Table of Contents snmp_get_quick_print ....................................................................................................................... 3331 snmp_set_quick_print ....................................................................................................................... 3332 snmpget ......................................................................................................................................... 3333 snmprealwalk .................................................................................................................................. 3334 snmpset .......................................................................................................................................... 3335 snmpwalk ....................................................................................................................................... 3336 snmpwalkoid ................................................................................................................................... 3337 3329 Introduction Requirements In order to use the SNMP functions on Unix you need to install the UCD SNMP [http://net-snmp.sourceforge.net/] package. On Windows these functions are only available on NT and not on Win95/98. Installation Important: In order to use the UCD SNMP package, you need to define NO_ZEROLENGTH_COMMUNITY to 1 before compiling it. After configuring UCD SNMP, edit config.h and search for NO_ZEROLENGTH_COMMUNITY. Uncomment the #define line. It should look like this afterwards: #define NO_ZEROLENGTH_COMMUNITY 1 Now compile PHP --with-snmp[=DIR]. If you see strange segmentation faults in combination with SNMP commands, you did not follow the above instructions. If you do not want to recompile UCD SNMP, you can compile PHP with the --enable-ucd-snmp-hack switch which will work around the misfeature. The Windows distribution contains support files for SNMP in the mibs directory. This directory should be moved to DRIVE:\usr\mibs, where DRIVE must be replaced with the driveletter where PHP is installed on, e.g.: c:\usr\mibs. Runtime Configuration This extension has no configuration directives defined in php.ini. Resource Types Predefined Constants This extension has no constants defined. 3330 snmp_get_quick_print (PHP 3>= 3.0.8, PHP 4 ) snmp_get_quick_print - Fetch the current value of the UCD library's quick_print setting Description bool snmp_get_quick_print (void) Returns the current value stored in the UCD Library for quick_print. quick_print is off by default. $quickprint = snmp_get_quick_print(); Above function call would return FALSE if quick_print is off, and TRUE if quick_print is on. snmp_get_quick_print() is only available when using the UCD SNMP library. This function is not available when using the Windows SNMP library. See: snmp_set_quick_print() for a full description of what quick_print does. 3331 snmp_set_quick_print (PHP 3>= 3.0.8, PHP 4 ) snmp_set_quick_print - Set the value of quick_print within the UCD SNMP library Description void snmp_set_quick_print (bool quick_print) Sets the value of quick_print within the UCD SNMP library. When this is set (1), the SNMP library will return 'quick printed' values. This means that just the value will be printed. When quick_print is not enabled (default) the UCD SNMP library prints extra information including the type of the value (i.e. IpAddress or OID). Additionally, if quick_print is not enabled, the library prints additional hex values for all strings of three characters or less. Setting quick_print is often used when using the information returned rather then displaying it. snmp_set_quick_print(0); $a = snmpget("127.0.0.1", "public", ".1.3.6.1.2.1.2.2.1.9.1"); echo "$a
\n"; snmp_set_quick_print(1); $a = snmpget("127.0.0.1", "public", ".1.3.6.1.2.1.2.2.1.9.1"); echo "$a
\n"; The first value printed might be: 'Timeticks: (0) 0:00:00.00', whereas with quick_print enabled, just '0:00:00.00' would be printed. By default the UCD SNMP library returns verbose values, quick_print is used to return only the value. Currently strings are still returned with extra quotes, this will be corrected in a later release. snmp_set_quick_print() is only available when using the UCD SNMP library. This function is not available when using the Windows SNMP library. 3332 snmpget (PHP 3, PHP 4 ) snmpget - Fetch an SNMP object Description string snmpget (string hostname, string community, string object_id [, int timeout [, int retries]]) Returns SNMP object value on success and FALSE on error. The snmpget() function is used to read the value of an SNMP object specified by the object_id. SNMP agent is specified by the hostname and the read community is specified by the community parameter. $syscontact = snmpget("127.0.0.1", "public", "system.SysContact.0"); 3333 snmprealwalk (PHP 3>= 3.0.8, PHP 4 ) snmprealwalk - Return all objects including their respective object ID within the specified one Description array snmprealwalk (string host, string community, string object_id [, int timeout [, int retries]]) Warning This function is currently not documented; only the argument list is available. 3334 snmpset (PHP 3>= 3.0.12, PHP 4 ) snmpset - Set an SNMP object Description bool snmpset (string hostname, string community, string object_id, string type, mixed value [, int timeout [, int retries]]) Sets the specified SNMP object value, returning TRUE on success and FALSE on error. The snmpset() function is used to set the value of an SNMP object specified by the object_id. SNMP agent is specified by the hostname and the read community is specified by the community parameter. 3335 snmpwalk (PHP 3, PHP 4 ) snmpwalk - Fetch all the SNMP objects from an agent Description array snmpwalk (string hostname, string community, string object_id [, int timeout [, int retries]]) Returns an array of SNMP object values starting from the object_id as root and FALSE on error. snmpwalk() function is used to read all the values from an SNMP agent specified by the hostname. Community specifies the read community for that agent. A NULL object_id is taken as the root of the SNMP objects tree and all objects under that tree are returned as an array. If object_id is specified, all the SNMP objects below that object_id are returned. $a = snmpwalk("127.0.0.1", "public", ""); Above function call would return all the SNMP objects from the SNMP agent running on localhost. One can step through the values with a loop for ($i=0; $i < count($a); $i++) { echo $a[$i]; } 3336 snmpwalkoid (PHP 3>= 3.0.8, PHP 4 ) snmpwalkoid - Query for a tree of information about a network entity Description array snmpwalkoid (string hostname, string community, string object_id [, int timeout [, int retries]]) Returns an associative array with object ids and their respective object value starting from the object_id as root and FALSE on error. snmpwalkoid() function is used to read all object ids and their respective values from an SNMP agent specified by the hostname. Community specifies the read community for that agent. A NULL object_id is taken as the root of the SNMP objects tree and all objects under that tree are returned as an array. If object_id is specified, all the SNMP objects below that object_id are returned. The existence of snmpwalkoid() and snmpwalk() has historical reasons. Both functions are provided for backward compatibility. $a = snmpwalkoid("127.0.0.1", "public", ""); Above function call would return all the SNMP objects from the SNMP agent running on localhost. One can step through the values with a loop for (reset($a); $i = key($a); next($a)) { echo "$i: $a[$i]
\n"; } 3337 Socket functions Table of Contents socket_accept .................................................................................................................................. 3344 socket_bind ..................................................................................................................................... 3345 socket_clear_error ............................................................................................................................ 3346 socket_close .................................................................................................................................... 3347 socket_connect ................................................................................................................................ 3348 socket_create_listen .......................................................................................................................... 3349 socket_create_pair ............................................................................................................................ 3350 socket_create ................................................................................................................................... 3351 socket_get_option ............................................................................................................................ 3353 socket_getpeername ......................................................................................................................... 3354 socket_getsockname ......................................................................................................................... 3355 socket_iovec_add ............................................................................................................................. 3356 socket_iovec_alloc ........................................................................................................................... 3357 socket_iovec_delete .......................................................................................................................... 3358 socket_iovec_fetch ........................................................................................................................... 3359 socket_iovec_free ............................................................................................................................ 3360 socket_iovec_set .............................................................................................................................. 3361 socket_last_error .............................................................................................................................. 3362 socket_listen ................................................................................................................................... 3363 socket_read ..................................................................................................................................... 3364 socket_readv ................................................................................................................................... 3365 socket_recv ..................................................................................................................................... 3366 socket_recvfrom .............................................................................................................................. 3367 socket_recvmsg ............................................................................................................................... 3368 socket_select ................................................................................................................................... 3369 socket_send .................................................................................................................................... 3371 socket_sendmsg ............................................................................................................................... 3372 socket_sendto .................................................................................................................................. 3373 socket_set_block .............................................................................................................................. 3374 socket_set_nonblock ......................................................................................................................... 3375 socket_set_option ............................................................................................................................. 3376 socket_shutdown .............................................................................................................................. 3377 socket_strerror ................................................................................................................................. 3378 socket_write .................................................................................................................................... 3379 socket_writev .................................................................................................................................. 3380 3338 Introduction The socket extension implements a low-level interface to the socket communication functions based on the popular BSD sockets, providing the possibility to act as a socket server as well as a client. For a more generic client-side socket interface, see stream_socket_client(), stream_socket_server(), fsockopen(), and pfsockopen(). When using these functions, it is important to remember that while many of them have identical names to their C counterparts, they often have different declarations. Please be sure to read the descriptions to avoid confusion. Those unfamiliar with socket programming can find a lot of useful material in the appropriate Unix man pages, and there is a great deal of tutorial information on socket programming in C on the web, much of which can be applied, with slight modifications, to socket programming in PHP. The UNIX Socket FAQ [http://www.developerweb.net/sock-faq/] might be a good start. Warning This extension is EXPERIMENTAL. The behaviour of this extension -- including the names of its functions and anything else documented about this extension -- may change without notice in a future release of PHP. Use this extension at your own risk. Requirements No external libraries are needed to build this extension. Installation The socket functions described here are part of an extension to PHP which must be enabled at compile time by giving the -enable-sockets option to configure. Note: IPv6 Support was added with PHP 5.0 . Runtime Configuration This extension has no configuration directives defined in php.ini. Resource Types This extension has no resource types defined. Predefined Constants The constants below are defined by this extension, and will only be available when the extension has either been compiled into PHP or dynamically loaded at runtime. AF_UNIX (integer) AF_INET (integer) AF_INET6 (integer) 3339 Socket functions SOCK_STREAM (integer) SOCK_DGRAM (integer) SOCK_RAW (integer) SOCK_SEQPACKET (integer) SOCK_RDM (integer) MSG_OOB (integer) MSG_WAITALL (integer) MSG_PEEK (integer) MSG_DONTROUTE (integer) SO_DEBUG (integer) SO_REUSEADDR (integer) SO_KEEPALIVE (integer) SO_DONTROUTE (integer) SO_LINGER (integer) SO_BROADCAST (integer) SO_OOBINLINE (integer) SO_SNDBUF (integer) SO_RCVBUF (integer) SO_SNDLOWAT (integer) SO_RCVLOWAT (integer) SO_SNDTIMEO (integer) SO_RCVTIMEO (integer) SO_TYPE (integer) SO_ERROR (integer) SOL_SOCKET (integer) PHP_NORMAL_READ (integer) PHP_BINARY_READ (integer) SOL_TCP (integer) SOL_UDP (integer) 3340 Socket functions Socket Errors The socket extension was written to provide a useable interface to the powerful BSD sockets. Care has been taken that the functions work equally well on Win32 and Unix implementations. Almost all of the sockets functions may fail under certain conditions and therefore emit an E_WARNING message describing the error. Sometimes this doesn't happen to the desire of the developer. For example the function socket_read() may suddenly emit an E_WARNING message because the connection broke unexpectedly. It's common to suppress the warning with the @-operator and catch the error code within the application with the socket_last_error() function. You may call the socket_strerror() function with this error code to retrieve a string describing the error. See their description for more information. Note: The E_WARNING messages generated by the socket extension are in english though the retrieved error message will appear depending on the current locale (LC_MESSAGES): Warning - socket_bind() unable to bind address [98]: Die Adresse wird bereits verwendet Examples Example 788. Socket example: Simple TCP/IP server This example shows a simple talkback server. Change the address and port variables to suit your setup and execute. You may then connect to the server with a command similar to: telnet 192.168.1.53 10000 (where the address and port match your setup). Anything you type will then be output on the server side, and echoed back to you. To disconnect, enter 'quit'. #!/usr/local/bin/php -q Example 789. Socket example: Simple TCP/IP client This example shows a simple, one-shot HTTP client. It simply connects to a page, submits a HEAD request, echoes the reply, and exits. TCP/IP Connection\n"; /* Get the port for the WWW service. */ $service_port = getservbyname ('www', 'tcp'); /* Get the IP address for the target host. */ $address = gethostbyname ('www.example.com'); /* Create a TCP/IP socket. */ $socket = socket_create (AF_INET, SOCK_STREAM, 0); if ($socket < 0) { echo "socket_create() failed: reason: " . socket_strerror ($socket) . "\n"; } else { echo "OK.\n"; } echo "Attempting to connect to '$address' on port '$service_port'..."; $result = socket_connect ($socket, $address, $service_port); if ($result < 0) { echo "socket_connect() failed.\nReason: ($result) " . socket_strerror($result) . "\n"; } else { echo "OK.\n"; } $in = "HEAD / HTTP/1.0\r\n\r\n"; $out = ''; echo "Sending HTTP HEAD request..."; socket_write ($socket, $in, strlen ($in)); echo "OK.\n"; echo "Reading response:\n\n"; while ($out = socket_read ($socket, 2048)) { echo $out; } echo "Closing socket..."; 3342 Socket functions socket_close ($socket); echo "OK.\n\n"; ?> 3343 socket_accept (PHP 4 >= 4.1.0) socket_accept - Accepts a connection on a socket Description resource socket_accept (resource socket) Warning This function is EXPERIMENTAL. The behaviour of this function, the name of this function, and anything else documented about this function may change without notice in a future release of PHP. Use this function at your own risk. After the socket socket has been created using socket_create(), bound to a name with socket_bind(), and told to listen for connections with socket_listen(), this function will accept incoming connections on that socket. Once a successful connection is made, a new socket resource is returned, which may be used for communication. If there are multiple connections queued on the socket, the first will be used. If there are no pending connections, socket_accept() will block until a connection becomes present. If socket has been made non-blocking using socket_set_blocking() or socket_set_nonblock(), FALSE will be returned. The socket resource returned by socket_accept() may not be used to accept new connections. The original listening socket socket, however, remains open and may be reused. Returns a new socket resource on success, or FALSE on error. The actual error code can be retrieved by calling socket_last_error(). This error code may be passed to socket_strerror() to get a textual explanation of the error. See also socket_bind(), socket_connect(), socket_listen(), socket_create(), and socket_strerror(). 3344 socket_bind (PHP 4 >= 4.1.0) socket_bind - Binds a name to a socket Description bool socket_bind (resource socket, string address [, int port]) Warning This function is EXPERIMENTAL. The behaviour of this function, the name of this function, and anything else documented about this function may change without notice in a future release of PHP. Use this function at your own risk. socket_bind() binds the name given in address to the socket described by socket, which must be a valid socket resource created with socket_create(). The address parameter is either an IP address in dotted-quad notation (e.g. 127.0.0.1), if the socket is of the AF_INET family; or the pathname of a Unix-domain socket, if the socket family is AF_UNIX. The port parameter is only used when connecting to an AF_INET socket, and designates the port on the remote host to which a connection should be made. Returns TRUE on success or FALSE on failure. The error code can be retrieved with socket_last_error(). This code may be passed to socket_strerror() to get a textual explanation of the error. Note that socket_last_error() is reported to return an invalid error code in case you are trying to bind the socket to a wrong address that does not belong to your Windows 9x/ME machine. See also socket_connect(), socket_listen(), socket_create(), socket_last_error() and socket_strerror(). 3345 socket_clear_error (PHP 4 >= 4.2.0) socket_clear_error - Clears the error on the socket or the last error code Description void socket_clear_error ([resource socket]) Warning This function is EXPERIMENTAL. The behaviour of this function, the name of this function, and anything else documented about this function may change without notice in a future release of PHP. Use this function at your own risk. This function clears the error code on the given socket or the global last socket error. This function allows explicitely resetting the error code value either of a socket or of the extension global last error code. This may be useful to detect within a part of the application if an error occured or not. See also socket_last_error() and socket_strerror(). 3346 socket_close (PHP 4 >= 4.1.0) socket_close - Closes a socket resource Description void socket_close (resource socket) Warning This function is EXPERIMENTAL. The behaviour of this function, the name of this function, and anything else documented about this function may change without notice in a future release of PHP. Use this function at your own risk. socket_close() closes the socket resource given by socket. Note: socket_close() can't be used on PHP file resources created with fopen(), popen(), fsockopen(), or pfsockopen(); it is meant for sockets created with socket_create() or socket_accept(). See also socket_bind(), socket_listen(), socket_create() and socket_strerror(). 3347 socket_connect (PHP 4 >= 4.1.0) socket_connect - Initiates a connection on a socket Description bool socket_connect (resource socket, string address [, int port]) Warning This function is EXPERIMENTAL. The behaviour of this function, the name of this function, and anything else documented about this function may change without notice in a future release of PHP. Use this function at your own risk. Initiates a connection using the socket resource socket, which must be a valid socket resource created with socket_create(). The address parameter is either an IP address in dotted-quad notation (e.g. 127.0.0.1), if the socket is of the AF_INET family; or the pathname of a Unix-domain socket, if the socket family is AF_UNIX. The port parameter is only used when connecting to an AF_INET socket, and designates the port on the remote host to which a connection should be made. Returns TRUE on success or FALSE on failure. The error code can be retrieved with socket_last_error(). This code may be passed to socket_strerror() to get a textual explanation of the error. See also socket_bind(), socket_listen(), socket_create(), socket_last_error() and socket_strerror(). 3348 socket_create_listen (PHP 4 >= 4.1.0) socket_create_listen - Opens a socket on port to accept connections Description resource socket_create_listen (int port [, int backlog]) Warning This function is EXPERIMENTAL. The behaviour of this function, the name of this function, and anything else documented about this function may change without notice in a future release of PHP. Use this function at your own risk. This function is meant to ease the task of creating a new socket which only listens to accept new connections. socket_create_listen() create a new socket resource of type AF_INET listening on all local interfaces on the given port waiting for new connections. The backlog parameter defines the maximum length the queue of pending connections may grow to. SOMAXCONN may be passed as backlog parameter, see socket_listen() for more information. socket_create_listen() returns a new socket resource on success or FALSE on error. The error code can be retrieved with socket_last_error(). This code may be passed to socket_strerror() to get a textual explanation of the error. Note: If you want to create a socket which only listens on a certain interfaces you need to use socket_create(), socket_bind() and socket_listen(). See also socket_create(), socket_bind(), socket_listen(), socket_last_error() and socket_strerror(). 3349 socket_create_pair (PHP 4 >= 4.1.0) socket_create_pair - Creates a pair of indistinguishable sockets and stores them in fds. Description bool socket_create_pair (int domain, int type, int protocol, array &fd) Warning This function is EXPERIMENTAL. The behaviour of this function, the name of this function, and anything else documented about this function may change without notice in a future release of PHP. Use this function at your own risk. Warning This function is currently not documented; only the argument list is available. 3350 socket_create (PHP 4 >= 4.1.0) socket_create - Create a socket (endpoint for communication) Description resource socket_create (int domain, int type, int protocol) Creates and returns a socket resource, also referred to as an endpoint of communication. A typical network connection is made up of 2 sockets, one performing the role of the client, and another performing the role of the server. The domain parameter specifies the protocol family to be used by the socket. Table 155. Available address/protocol families Domain Description AF_INET IPv4 Internet based protocols. TCP and UDP are common protocols of this protocol family. AF_INET6 IPv6 Internet based protocols. TCP and UDP are common protocols of this protocol family. Support added in PHP 5.0. AF_UNIX Local communication protocol family. High efficiency and low overhead make it a great form of IPC (Interprocess Communication). The type parameter selects the type of communication to be used by the socket. Table 156. Available socket types Type Description SOCK_STREAM Provides sequenced, reliable, full-duplex, connection-based byte streams. An out-of-band data transmission mechanism may be supported. The TCP protocol is based on this socket type. SOCK_DGRAM Supports datagrams (connectionless, unreliable messages of a fixed maximum length). The UDP protocol is based on this socket type. SOCK_SEQPACKET Provides a sequenced, reliable, two-way connection-based data transmission path for datagrams of fixed maximum length; a consumer is required to read an entire packet with each read call. SOCK_RAW Provides raw network protocol access. This special type of socket can be used to manually construct any type of protocol. A common use for this socket type is to perform ICMP requests (like ping, traceroute, etc). SOCK_RDM Provides a reliable datagram layer that does not guarantee ordering. This is most likely not implemented on your operating system. 3351 socket_create The protocol parameter sets the specific protocol within the specified domain to be used when communicating on the returned socket. The proper value can be retrieved by name by using getprotobyname(). If the desired protocol is TCP, or UDP the corresponding constants SOL_TCP, and SOL_UDP can also be used. Table 157. Common protocols Name Description icmp The Internet Control Message Protocol is used primarily by gateways and hosts to report errors in datagram communication. The "ping" command (present in most modern operating systems) is an example application of ICMP. udp The User Datagram Protocol is a connectionless, unreliable, protocol with fixed record lengths. Due to these aspects, UDP requires a minimum amount of protocol overhead. tcp The Transmission Control Protocol is a reliable, connection based, stream oriented, full duplex protocol. TCP guarantees that all data packets will be received in the order in which they were sent. If any packet is somehow lost during communication, TCP will automatically retransmit the packet until the destination host acknowledges that packet. For reliability and performance reasons, the TCP implementation itself decides the appropriate octet boundaries of the underlying datagram communication layer. Therefore, TCP applications must allow for the possibility of partial record transmission. socket_create() Returns a socket resource on success, or FALSE on error. The actual error code can be retrieved by calling socket_last_error(). This error code may be passed to socket_strerror() to get a textual explanation of the error. Note: If an invalid domain or type is given, socket_create() defaults to AF_INET and SOCK_STREAM respectively and additionally emits an E_WARNING message. See also socket_accept(), socket_bind(), socket_connect(), socket_listen(), socket_last_error(), and socket_strerror(). 3352 socket_get_option (PHP 4 >= 4.3.0) socket_get_option - Gets socket options for the socket Description mixed socket_get_option (resource socket, int level, int optname) Warning This function is EXPERIMENTAL. The behaviour of this function, the name of this function, and anything else documented about this function may change without notice in a future release of PHP. Use this function at your own risk. Warning This function is currently not documented; only the argument list is available. Note: This function used to be called socket_getopt() prior to PHP 4.3.0 3353 socket_getpeername (PHP 4 >= 4.1.0) socket_getpeername - Queries the remote side of the given socket which may either result in host/port or in a UNIX filesystem path, dependent on its type. Description bool socket_getpeername (resource socket, string &addr [, int &port]) Warning This function is EXPERIMENTAL. The behaviour of this function, the name of this function, and anything else documented about this function may change without notice in a future release of PHP. Use this function at your own risk. If the given socket is of type AF_INET or AF_INET6, socket_getpeername() will return the peers (remote) IP address in appropriate notation (e.g. 127.0.0.1 or fe80::1) in the address parameter and, if the optional port parameter is present, also the associated port. If the given socket is of type AF_UNIX, socket_getpeername() will return the UNIX filesystem path (e.g. / var/run/daemon.sock) in the address parameter. Note: socket_getpeername() should not be used with AF_UNIX sockets created with socket_accept(). Only sockets created with socket_connect() or a primary server socket following a call to socket_bind() will return meaningful values. Returns TRUE on success or FALSE on failure. socket_getpeername() may also return FALSE if the socket type is not any of AF_INET, AF_INET6, or AF_UNIX, in which case the last socket error code is not updated. See also socket_getsockname(), socket_last_error() and socket_strerror(). 3354 socket_getsockname (PHP 4 >= 4.1.0) socket_getsockname - Queries the local side of the given socket which may either result in host/port or in a UNIX filesystem path, dependent on its type. Description bool socket_getsockname (resource socket, string &addr [, int &port]) Warning This function is EXPERIMENTAL. The behaviour of this function, the name of this function, and anything else documented about this function may change without notice in a future release of PHP. Use this function at your own risk. If the given socket is of type AF_INET or AF_INET6, socket_getsockname() will return the local IP address in appropriate notation (e.g. 127.0.0.1 or fe80::1) in the address parameter and, if the optional port parameter is present, also the associated port. If the given socket is of type AF_UNIX, socket_getsockname() will return the UNIX filesystem path (e.g. / var/run/daemon.sock) in the address parameter. Note: socket_getsockname() should not be used with AF_UNIX sockets created with socket_connect(). Only sockets created with socket_accept() or a primary server socket following a call to socket_bind() will return meaningful values. Returns TRUE on success or FALSE on failure. socket_getsockname() may also return FALSE if the socket type is not any of AF_INET, AF_INET6, or AF_UNIX, in which case the last socket error code is not updated. See also socket_getpeername(), socket_last_error() and socket_strerror(). 3355 socket_iovec_add (PHP 4 >= 4.1.0) socket_iovec_add - Adds a new vector to the scatter/gather array Description bool socket_iovec_add (resource iovec, int iov_len) Warning This function is EXPERIMENTAL. The behaviour of this function, the name of this function, and anything else documented about this function may change without notice in a future release of PHP. Use this function at your own risk. Warning This function is currently not documented; only the argument list is available. 3356 socket_iovec_alloc (PHP 4 >= 4.1.0) socket_iovec_alloc - Builds a 'struct iovec' for use with sendmsg, recvmsg, writev, and readv Description resource socket_iovec_alloc (int num_vectors [, int ]) Warning This function is EXPERIMENTAL. The behaviour of this function, the name of this function, and anything else documented about this function may change without notice in a future release of PHP. Use this function at your own risk. Warning This function is currently not documented; only the argument list is available. 3357 socket_iovec_delete (PHP 4 >= 4.1.0) socket_iovec_delete - Deletes a vector from an array of vectors Description bool socket_iovec_delete (resource iovec, int iov_pos) Warning This function is EXPERIMENTAL. The behaviour of this function, the name of this function, and anything else documented about this function may change without notice in a future release of PHP. Use this function at your own risk. Warning This function is currently not documented; only the argument list is available. 3358 socket_iovec_fetch (PHP 4 >= 4.1.0) socket_iovec_fetch - Returns the data held in the iovec specified by iovec_id[iovec_position] Description string socket_iovec_fetch (resource iovec, int iovec_position) Warning This function is EXPERIMENTAL. The behaviour of this function, the name of this function, and anything else documented about this function may change without notice in a future release of PHP. Use this function at your own risk. Warning This function is currently not documented; only the argument list is available. 3359 socket_iovec_free (PHP 4 >= 4.1.0) socket_iovec_free - Frees the iovec specified by iovec_id Description bool socket_iovec_free (resource iovec) Warning This function is EXPERIMENTAL. The behaviour of this function, the name of this function, and anything else documented about this function may change without notice in a future release of PHP. Use this function at your own risk. Warning This function is currently not documented; only the argument list is available. 3360 socket_iovec_set (PHP 4 >= 4.1.0) socket_iovec_set - Sets the data held in iovec_id[iovec_position] to new_val Description bool socket_iovec_set (resource iovec, int iovec_position, string new_val) Warning This function is EXPERIMENTAL. The behaviour of this function, the name of this function, and anything else documented about this function may change without notice in a future release of PHP. Use this function at your own risk. Warning This function is currently not documented; only the argument list is available. 3361 socket_last_error (PHP 4 >= 4.1.0) socket_last_error - Returns the last error on the socket Description int socket_last_error ([resource socket]) Warning This function is EXPERIMENTAL. The behaviour of this function, the name of this function, and anything else documented about this function may change without notice in a future release of PHP. Use this function at your own risk. This function returns a socket error code. If a socket resource is passed to this function, the last error which occured on this particular socket is returned. If the socket resource is ommited, the error code of the last failed socket function is returned. The latter is in particular helpful for functions like socket_create() which don't return a socket on failure and socket_select() which can fail for reasons not directly tied to a particular socket. The error code is suitable to be fed to socket_strerror() which returns a string describing the given error code. if (false == ($socket = @socket_create(AF_INET, SOCK_STREAM, SOL_TCP))) { die("Couldn't create socket, error code is: " . socket_last_error() . ",error message is: " . socket_strerror(socket_last_error())); } Note: socket_last_error() does not clear the error code, use socket_clear_error() for this purpose. 3362 socket_listen (PHP 4 >= 4.1.0) socket_listen - Listens for a connection on a socket Description bool socket_listen (resource socket [, int backlog]) Warning This function is EXPERIMENTAL. The behaviour of this function, the name of this function, and anything else documented about this function may change without notice in a future release of PHP. Use this function at your own risk. After the socket socket has been created using socket_create() and bound to a name with socket_bind(), it may be told to listen for incoming connections on socket. A maximum of backlog incoming connections will be queued for processing. If a connection request arrives with the queue full the client may receive an error with an indication of ECONNREFUSED, or, if the underlying protocol supports retransmission, the request may be ignored so that retries may succeed. Note: The maximum number passed to the backlog parameter highly depends on the underlying platform. On linux, it is silently truncated to SOMAXCONN. On win32, if passed SOMAXCONN, the underlying service provider responsible for the socket will set the backlog to a maximum reasonable value. There is no standard provision to find out the actual backlog value on this platform. socket_listen() is applicable only to sockets of type SOCK_STREAM or SOCK_SEQPACKET. Returns TRUE on success or FALSE on failure. The error code can be retrieved with socket_last_error(). This code may be passed to socket_strerror() to get a textual explanation of the error. See also socket_accept(), socket_bind(), socket_connect(), socket_create() and socket_strerror(). 3363 socket_read (PHP 4 >= 4.1.0) socket_read - Reads a maximum of length bytes from a socket Description string socket_read (resource socket, int length [, int type]) Warning This function is EXPERIMENTAL. The behaviour of this function, the name of this function, and anything else documented about this function may change without notice in a future release of PHP. Use this function at your own risk. The function socket_read() reads from the socket resource socket created by the socket_create() or socket_accept() functions. The maximum number of bytes read is specified by the length parameter. Otherwise you can use \r, \n, or \0 to end reading (depending on the type parameter, see below). socket_read() returns the data as a string on success, or FALSE on error. The error code can be retrieved with socket_last_error(). This code may be passed to socket_strerror() to get a textual representation of the error. Note: socket_read() may return a zero length string ("") indicating the end of communication (i.e. the remote end point has closed the connection). Optional type parameter is a named constant: • PHP_BINARY_READ - use the system read() function. Safe for reading binary data. (Default in PHP >= 4.1.0) • PHP_NORMAL_READ - reading stops at \n or \r. (Default in PHP <= 4.0.6) See also socket_accept(), socket_bind(), socket_connect(), socket_listen(), socket_last_error(), socket_strerror() and socket_write(). 3364 socket_readv (PHP 4 >= 4.1.0) socket_readv - Reads from an fd, using the scatter-gather array defined by iovec_id Description bool socket_readv (resource socket, resource iovec_id) Warning This function is EXPERIMENTAL. The behaviour of this function, the name of this function, and anything else documented about this function may change without notice in a future release of PHP. Use this function at your own risk. Warning This function is currently not documented; only the argument list is available. 3365 socket_recv (PHP 4 >= 4.1.0) socket_recv - Receives data from a connected socket Description int socket_recv (resource socket, string &buf, int len, int flags) Warning This function is EXPERIMENTAL. The behaviour of this function, the name of this function, and anything else documented about this function may change without notice in a future release of PHP. Use this function at your own risk. Warning This function is currently not documented; only the argument list is available. 3366 socket_recvfrom (PHP 4 >= 4.1.0) socket_recvfrom - Receives data from a socket, connected or not Description int socket_recvfrom (resource socket, string &buf, int len, int flags, string &name [, int &port]) Warning This function is EXPERIMENTAL. The behaviour of this function, the name of this function, and anything else documented about this function may change without notice in a future release of PHP. Use this function at your own risk. Warning This function is currently not documented; only the argument list is available. 3367 socket_recvmsg (PHP 4 >= 4.1.0) socket_recvmsg - Used to receive messages on a socket, whether connection-oriented or not Description bool socket_recvmsg (resource socket, resource iovec, array &control, int &controllen, int &flags, string &addr [, int &port]) Warning This function is EXPERIMENTAL. The behaviour of this function, the name of this function, and anything else documented about this function may change without notice in a future release of PHP. Use this function at your own risk. Warning This function is currently not documented; only the argument list is available. 3368 socket_select (PHP 4 >= 4.1.0) socket_select - Runs the select() system call on the given arrays of sockets with a timeout specified by tv_sec and tv_usec Description int socket_select (resource &read, resource &write, resource &except, int tv_sec [, int tv_usec]) Warning This function is EXPERIMENTAL. The behaviour of this function, the name of this function, and anything else documented about this function may change without notice in a future release of PHP. Use this function at your own risk. The socket_select() accepts arrays of sockets and waits for them to change status. Those coming with BSD sockets background will recognize that those socket resource arrays are in fact the so-called file descriptor sets. Three independent arrays of socket resources are watched. The sockets listed in the read array will be watched to see if characters become available for reading (more precisely, to see if a read will not block - in particular, a socket resource is also ready on end-of-file, in which case a socket_read() will return a zero length string). The sockets listed in the write array will be watched to see if a write will not block. The sockets listed in the except array will be watched for exceptions. Warning On exit, the arrays are modified to indicate which socket resource actually changed status. You do not need to pass every array to socket_select(). You can leave it out and use an empty array or NULL instead. Also do not forget that those arrays are passed by reference and will be modified after socket_select() returns. Example: /* Prepare the read array */ $read = array($socket1, $socket2); $num_changed_sockets = socket_select($read, $write = NULL, $except = NULL, 0); if ($num_changed_sockets === false) { /* Error handling */ } else if ($num_changed_sockets > 0) { /* At least at one of the sockets something interesting happened */ } Note: Due a limitation in the current Zend Engine it is not possible to pass a constant modifier like NULL directly as a parameter to a function which expects this parameter to be passed by reference. Instead use a temporary variable or an expression with the leftmost member being a temporary variable: socket_select($r, $w, $e = NULL, 0); The tv_sec and tv_usec together form the timeout parameter. The timeout is an upper bound on the amount of time elapsed before socket_select() return. tv_sec may be zero , causing socket_select() to return immediately. This is useful for polling. 3369 socket_select If tv_sec is NULL (no timeout), socket_select() can block indefinitely. On success socket_select() returns the number of socket resorces contained in the modified arrays, which may be zero if the timeout expires before anything interesting happens. On error FALSE is returned. The error code can be retrieved with socket_last_error(). Note: Be sure to use the === operator when checking for an error. Since the socket_select() may return 0 the comparison with == would evaluate to TRUE: if (false === socket_select($r, $w, $e = NULL, 0)) { echo "socket_select() failed, reason: " . socket_strerror(socket_last_error()) . "\n"; } Note: Be aware that some socket implementations need to be handled very carefully. A few basic rules: • You should always try to use socket_select() without timeout. Your program should have nothing to do if there is no data available. Code that depends on timeouts is not usually portable and difficult to debug. • No socket resource must be added to any set if you do not intend to check its result after the socket_select() call, and respond appropriately. After socket_select() returns, all socket resources in all arrays must be checked. Any socket resource that is available for writing must be written to, and any socket resource available for reading must be read from. • If you read/write to a socket returns in the arrays be aware that they do not necessarily read/write the full amount of data you have requested. Be prepared to even only be able to read/write a single byte. • It's common to most socket implementations that the only exception caught with the except array is outof-bound data received on a socket. See also socket_read(), socket_write(), socket_last_error() and socket_strerror(). 3370 socket_send (PHP 4 >= 4.1.0) socket_send - Sends data to a connected socket Description int socket_send (resource socket, string buf, int len, int flags) Warning This function is EXPERIMENTAL. The behaviour of this function, the name of this function, and anything else documented about this function may change without notice in a future release of PHP. Use this function at your own risk. The function socket_send() sends len bytes to the socket socket from buf The value of flags can be any ORed combination of the following: Table 158. possible values for flags 0x1 Process OOB (out-of-band) data 0x2 Peek at incoming message 0x4 Bypass routing, use direct interface 0x8 Data completes record 0x100 Data completes transaction See also socket_sendmsg() and socket_sendto(). 3371 socket_sendmsg (PHP 4 >= 4.1.0) socket_sendmsg - Sends a message to a socket, regardless of whether it is connection-oriented or not Description bool socket_sendmsg (resource socket, resource iovec, int flags, string addr [, int port]) Warning This function is EXPERIMENTAL. The behaviour of this function, the name of this function, and anything else documented about this function may change without notice in a future release of PHP. Use this function at your own risk. Warning This function is currently not documented; only the argument list is available. 3372 socket_sendto (PHP 4 >= 4.1.0) socket_sendto - Sends a message to a socket, whether it is connected or not Description int socket_sendto (resource socket, string buf, int len, int flags, string addr [, int port]) Warning This function is EXPERIMENTAL. The behaviour of this function, the name of this function, and anything else documented about this function may change without notice in a future release of PHP. Use this function at your own risk. The function socket_sendto() sends len bytes from buf through the socket socket to the port at the address addr The value of flags can be one of the following: Table 159. possible values for flags 0x1 Process OOB (out-of-band) data. 0x2 Peek at incoming message. 0x4 Bypass routing, use direct interface. 0x8 Data completes record. 0x100 Data completes transaction. Example 790. socket_sendto() Example See also socket_send() and socket_sendmsg(). 3373 socket_set_block (PHP 4 >= 4.2.0) socket_set_block - Sets blocking mode on a socket resource Description bool socket_set_block (resource socket) Warning This function is currently not documented; only the argument list is available. Returns TRUE on success or FALSE on failure. See also socket_set_nonblock() and socket_set_option() 3374 socket_set_nonblock (PHP 4 >= 4.1.0) socket_set_nonblock - Sets nonblocking mode for file descriptor fd Description bool socket_set_nonblock (resource socket) Warning This function is EXPERIMENTAL. The behaviour of this function, the name of this function, and anything else documented about this function may change without notice in a future release of PHP. Use this function at your own risk. Warning This function is currently not documented; only the argument list is available. 3375 socket_set_option (PHP 4 >= 4.3.0) socket_set_option - Sets socket options for the socket Description bool socket_set_option (resource socket, int level, int optname, mixed optval) Warning This function is EXPERIMENTAL. The behaviour of this function, the name of this function, and anything else documented about this function may change without notice in a future release of PHP. Use this function at your own risk. Warning This function is currently not documented; only the argument list is available. Note: This function used to be called socket_setopt() prior to PHP 4.3.0 3376 socket_shutdown (PHP 4 >= 4.1.0) socket_shutdown - Shuts down a socket for receiving, sending, or both. Description bool socket_shutdown (resource socket [, int how]) Warning This function is EXPERIMENTAL. The behaviour of this function, the name of this function, and anything else documented about this function may change without notice in a future release of PHP. Use this function at your own risk. The socket_shutdown() function allows you to stop incoming, outgoing or all data (the default) from being sent through the socket The value of how can be one of the following: Table 160. possible values for how 0 Shutdown socket reading 1 Shutdown socket writing 2 Shutdown socket reading and writing 3377 socket_strerror (PHP 4 >= 4.1.0) socket_strerror - Return a string describing a socket error Description string socket_strerror (int errno) Warning This function is EXPERIMENTAL. The behaviour of this function, the name of this function, and anything else documented about this function may change without notice in a future release of PHP. Use this function at your own risk. socket_strerror() takes as its errno parameter a socket error code as returned by socket_last_error() and returns the corresponding explanatory text. This makes it a bit more pleasant to figure out why something didn't work; for instance, instead of having to track down a system include file to find out what '-111' means, you just pass it to socket_strerror(), and it tells you what happened. Example 791. socket_strerror() example The expected output from the above example (assuming the script is not run with root privileges): socket_bind() failed: reason: Permission denied See also socket_accept(), socket_bind(), socket_connect(), socket_listen(), and socket_create(). 3378 socket_write (PHP 4 >= 4.1.0) socket_write - Write to a socket Description int socket_write (resource socket, string buffer [, int length]) Warning This function is EXPERIMENTAL. The behaviour of this function, the name of this function, and anything else documented about this function may change without notice in a future release of PHP. Use this function at your own risk. The function socket_write() writes to the socket socket from buffer. The optional parameter length can specify an alternate length of bytes written to the socket. If this length is greater then the buffer length, it is silently truncated to the length of the buffer. Returns the number of bytes successfully written to the socket or FALSE one error. The error code can be retrieved with socket_last_error(). This code may be passed to socket_strerror() to get a textual explanation of the error. Note: socket_write() does not necessarily write all bytes from the given buffer. It's valid that, depending on the network buffers etc., only a certain amount of data, even one byte, is written though your buffer is greater. You have to watch out so you don't unintentionally forget to transmit the rest of your data. Note: It is perfectly valid for socket_write() to return zero which means no bytes have been written. Be sure to use the === operator to check for FALSE in case of an error. See also socket_accept(), socket_bind(), socket_connect(), socket_listen(), socket_read() and socket_strerror(). 3379 socket_writev (PHP 4 >= 4.1.0) socket_writev - Writes to a file descriptor, fd, using the scatter-gather array defined by iovec_id Description bool socket_writev (resource socket, resource iovec_id) Warning This function is EXPERIMENTAL. The behaviour of this function, the name of this function, and anything else documented about this function may change without notice in a future release of PHP. Use this function at your own risk. Warning This function is currently not documented; only the argument list is available. 3380 Stream functions Table of Contents stream_context_create ....................................................................................................................... 3386 stream_context_get_options ............................................................................................................... 3387 stream_context_set_option ................................................................................................................. 3388 stream_context_set_params ................................................................................................................ 3389 stream_copy_to_stream ..................................................................................................................... 3390 stream_filter_append ........................................................................................................................ 3391 stream_filter_prepend ....................................................................................................................... 3392 stream_filter_register ........................................................................................................................ 3393 stream_get_filters ............................................................................................................................. 3395 stream_get_line ............................................................................................................................... 3396 stream_get_meta_data ....................................................................................................................... 3397 stream_get_transports ....................................................................................................................... 3398 stream_get_wrappers ........................................................................................................................ 3399 stream_register_wrapper .................................................................................................................... 3400 stream_select ................................................................................................................................... 3401 stream_set_blocking ......................................................................................................................... 3403 stream_set_timeout ........................................................................................................................... 3404 stream_set_write_buffer .................................................................................................................... 3405 stream_socket_accept ....................................................................................................................... 3406 stream_socket_client ......................................................................................................................... 3407 stream_socket_get_name ................................................................................................................... 3409 stream_socket_server ........................................................................................................................ 3410 stream_wrapper_register .................................................................................................................... 3412 3381 Introduction Streams were introduced with PHP 4.3.0 as a way of generalizing file, network, data compression, and other operations which share a common set of functions and uses. In its simplest definition, a stream is a resource object which exhibits streamable behavior. That is, it can be read from or written to in a linear fashion, and may be able to fseek() to an arbitrary locations within the stream. A wrapper is additional code which tells the stream how to handle specific protocols/encodings. For example, the http wrapper knows how to translate a URL into an HTTP/1.0 request for a file on a remote server. There are many wrappers built into PHP by default (See Appendix I, List of Supported Protocols/Wrappers), and additional, custom wrappers may be added either within a PHP script using stream_wrapper_register(), or directly from an extension using the API Reference in Chapter 43, Streams API for PHP Extension Authors. Because any variety of wrapper may be added to PHP, there is no set limit on what can be done with them. To access the list of currently registered wrappers, use stream_get_wrappers(). A stream is referenced as: scheme://target • scheme(string) - The name of the wrapper to be used. Examples include: file, http, https, ftp, ftps, compress.zlib, compress.bz2, and php. See Appendix I, List of Supported Protocols/Wrappers for a list of PHP builtin wrappers. If no wrapper is specified, the function default is used (typically file://). • target - Depends on the wrapper used. For filesystem related streams this is typically a path and filename of the desired file. For network related streams this is typically a hostname, often with a path appended. Again, see Appendix I, List of Supported Protocols/Wrappers for a description of targets for builtin streams. Stream Filters A filter is a final piece of code which may perform operations on data as it is being read from or written to a stream. Any number of filters may be stacked onto a stream. Custom filters can be defined in a PHP script using stream_filter_register() or in an extension using the API Reference in Chapter 43, Streams API for PHP Extension Authors. To access the list of currently registered filters, use stream_get_filters(). Stream Contexts A context is a set of parameters and wrapper specific options which modify or enhance the behavior of a stream. Contexts are created using stream_context_create() and can be passed to most filesystem related stream creation functions (i.e. fopen(), file(), file_get_contents(), etc...). Options can be specified when calling stream_context_create(), or later using stream_context_set_option(). A list of wrapper specific options can be found with the list of built-in wrappers (See Appendix I, List of Supported Protocols/ Wrappers). In addition, parameters may be set on a context using stream_context_set_params(). Currently the only context parameter supported by PHP is notification. The value of this parameter must be the name of a function to be called when an event occurs on a stream. The notification function called during an event should accept the following six parameters: void my_notifier (int notification_code, int severity, string message, int message_code, int bytes_transferred, int bytes_max) notification_code and severity are numerical values which correspond to the STREAM_NOTIFY_* constants listed below. If a descriptive message is available from the stream, message and message_code will be populated with the appropriate values. The meaning of these values is dependent on the specific wrapper in use. bytes_transferred and bytes_max will be populated when applicable. 3382 Stream functions Installation Streams are an integral part of PHP as of version 4.3.0. No steps are required to enable them. Stream Classes User designed wrappers can be registered via stream_wrapper_register(), using the class definition shown on that manual page. class php_user_filter is predefined and is an abstract baseclass for use with user defined filters. See the manual page for stream_filter_register() for details on implementing user defined filters. Predefined Constants The constants below are defined by this extension, and will only be available when the extension has either been compiled into PHP or dynamically loaded at runtime. Constant Description STREAM_FILTER_READ Used with stream_filter_append() and stream_filter_prepend() to indicate that the specified filter should only be applied when reading STREAM_FILTER_WRITE Used with stream_filter_append() and stream_filter_prepend() to indicate that the specified filter should only be applied when writting STREAM_FILTER_ALL This constant is equivalent to STREAM_FILTER_READ | STREAM_FILTER_WRITE PSFS_PASS_ON Return Code indicating that the userspace filter returned buckets in $out. PSFS_FEED_ME Return Code indicating that the userspace filter did not re- turn buckets in $out (i.e. No data available). Code indicating that the userspace filter encountered an unrecoverable error (i.e. Invalid data received). PSFS_ERR_FATAL Return STREAM_USE_PATH Flag indicating if the stream used the include path. STREAM_REPORT_ERRORS Flag indicating if the wrapper is responsible for raising er- rors using trigger_error() during opening of the stream. If this flag is not set, you should not raise any errors. STREAM_CLIENT_ASYNC_CONNECT Open client socket stream_socket_client(). STREAM_CLIENT_PERSISTENT Client socket opened with stream_socket_client() should remain persistent between page loads. STREAM_SERVER_BIND Tells a stream created with stream_socket_server() to bind to the specified target. Server sockets should always include this flag. STREAM_SERVER_LISTEN Tells a stream created with stream_socket_server() and bound using the STREAM_SERVER_BIND flag to start listening on the socket. Server sockets should always include this flag. STREAM_NOTIFY_RESOLVE A remote address required for this stream has been resolved, or the resolution failed. See severity for an indication of which happened. 3383 asynchronously. Used with Stream functions Constant Description STREAM_NOTIFY_CONNECT A connection with an external resource has been established. STREAM_NOTIFY_AUTH_REQUIRED Additional authorization is required to access the specified resource. Typical issued with severity level of STREAM_NOTIFY_SEVERITY_ERR. STREAM_NOTIFY_MIME_TYPE_IS The mime-type of resource has been identified, refer to message for a description of the discovered type. STREAM_NOTIFY_FILE_SIZE_IS The size of the resource has been discovered. STREAM_NOTIFY_REDIRECTED The external resource has redirected the stream to an alternate location. Refer to message. STREAM_NOTIFY_PROGRESS Indicates current progress of the stream transfer in bytes_transferred and possibly bytes_max as well. STREAM_NOTIFY_COMPLETED There is no more data available on the stream. STREAM_NOTIFY_FAILURE A generic error occured on the stream, consult message and message_code for details. STREAM_NOTIFY_AUTH_RESULT Authorization has been completed (with or without success). STREAM_NOTIFY_SEVERITY_INFO Normal, non-error realted, notification. STREAM_NOTIFY_SEVERITY_WARN Non critical error condition. Processing may continue. STREAM_NOTIFY_SEVERITY_ERR A critical error occured. Processing cannot continue. Stream Errors As with any file or socket related function, an operation on a stream may fail for a variety of normal reasons (i.e.: Unable to connect to remote host, file not found, etc...). A stream related call may also fail because the desired stream is not registered on the running system. See the array returned by stream_get_wrappers() for a list of streams supported by your installation of PHP. As with most PHP internal functions if a failure occours an E_WARNING message will be generated describing the nature of the error. Examples Example 792. Using file_get_contents() to retrieve data from multiple sources 3384 Stream functions Example 793. Making a POST request to an https server Example 794. Writting data to a compressed file 3385 stream_context_create (PHP 4 >= 4.3.0) stream_context_create - Create a streams context Description resource stream_context_create (array options) Creates and returns a stream context with any options supplied in options preset. options must be an associative array of associative arrays in the format $arr['wrapper']['option'] = $value. Example 795. Using stream_context_create() array( 'method'=>"GET", 'header'=>"Accept-language: en\r\n" . "Cookie: foo=bar\r\n" ) ); $context = stream_context_create($opts); /* Sends an http request to www.example.com with additional headers shown above */ $fp = fopen('http://www.example.com', 'r', false, $context); fpassthru($fp); fclose($fp); ?> See Also: stream_context_set_option(), and Listing of supported wrappers with context options (Appendix I, List of Supported Protocols/Wrappers) 3386 stream_context_get_options (PHP 4 >= 4.3.0) stream_context_get_options - Retrieve options for a stream/wrapper/context Description array stream_context_get_options (resource stream|context) Returns an array of options on the specified stream or context. 3387 stream_context_set_option (PHP 4 >= 4.3.0) stream_context_set_option - Sets an option for a stream/wrapper/context Description bool stream_context_set_option (resource context|stream, string wrapper, string option, mixed value) Sets an option on the specified context. value is set to option for wrapper 3388 stream_context_set_params (PHP 4 >= 4.3.0) stream_context_set_params - Set parameters for a stream/wrapper/context Description bool stream_context_set_params (resource stream|context, array params) params should be an associative array of the structure: $params['paramname'] = "paramvalue";. Table 161. Parameters Parameters Purpose notification Name of user-defined callback function to be called whenever a stream triggers a notification. 3389 stream_copy_to_stream (PHP 5 CVS only) stream_copy_to_stream - Copies data from one stream to another Description int stream_copy_to_stream (resource source, resource dest [, int maxlength]) Makes a copy of up to maxlength bytes of data from the current position in source to dest. If maxlength is not specified, all remaining content in source will be copied. Returns the total count of bytes copied. Example 796. stream_copy_to_stream() example See also copy(). 3390 stream_filter_append (PHP 4 >= 4.3.0) stream_filter_append - Attach a filter to a stream. Description bool stream_filter_append (resource stream, string filtername [, int read_write [, string params]]) Adds filtername to the list of filters attached to stream. This filter will be added with the specified params to the end of the list and will therefore be called last during stream operations. To add a filter to the beginning of the list, use stream_filter_prepend(). By default, stream_filter_append() will attach the filter to the read filter chain if the file was opened for reading (i.e. File Mode: r, and/or +). The filter will also be attached to the write filter chain if the file was opened for writing (i.e. File Mode: w, a, and/or +). STREAM_FILTER_READ, STREAM_FILTER_WRITE, and/or STREAM_FILTER_ALL can also be passed to the read_write parameter to override this behavior. Example 797. Controlling where filters are applied When using custom (user) filters: stream_filter_register() must be called first in order to register the desired user filter to filtername. See also stream_filter_register(), and stream_filter_prepend() 3391 stream_filter_prepend (PHP 4 >= 4.3.0) stream_filter_prepend - Attach a filter to a stream. Description bool stream_filter_prepend (resource stream, string filtername [, int read_write [, string params]]) Adds filtername to the list of filters attached to stream. This filter will be added with the specified params to the beginning of the list and will therefore be called first during stream operations. To add a filter to the end of the list, use stream_filter_append(). By default, stream_filter_prepend() will attach the filter to the read filter chain if the file was opened for reading (i.e. File Mode: r, and/or +). The filter will also be attached to the write filter chain if the file was opened for writing (i.e. File Mode: w, a, and/or +). STREAM_FILTER_READ, STREAM_FILTER_WRITE, and/or STREAM_FILTER_ALL can also be passed to the read_write parameter to override this behavior. See stream_filter_append() for an example of using this parameter. When using custom (user) filters: stream_filter_register() must be called first in order to register the desired user filter to filtername. See also stream_filter_register(), and stream_filter_append() 3392 stream_filter_register (PHP 5 CVS only) stream_filter_register - Register a stream filter implemented as a PHP class derived from php_user_filter Description bool stream_filter_register (string filtername, string classname) stream_filter_register() allows you to implement your own filter on any registered stream used with all the other filesystem functions (such as fopen(), fread() etc.). To implement a filter, you need to define a class as an extension of php_user_filter with a number of member functions as defined below. When performing read/write operations on the stream to which your filter is attached, PHP will pass the data through your filter (and any other filters attached to that stream) so that the data may be modified as desired. You must implement the methods exactly as described below - doing otherwise will lead to undefined behaviour. stream_filter_register() will return FALSE if the filtername is already defined. int filter (resource in, resource out, int &consumed, boolean closing) This method is called whenever data is read from or written to the attached stream (such as with fread() or fwrite()). in is a resource pointing to a bucket brigade which contains one or more bucket objects containing data to be filtered. out is a resource pointing to a second bucket brigade into which your modified buckets should be placed. consumed, which must always be declared by reference, should be incremented by the length of the data which your filter reads in and alters. In most cases this means you will increment consumed by $bucket->datalen for each $bucket. If the stream is in the process of closing (and therefore this is the last pass through the filterchain), the closing parameter will be set to TRUE The filter method must return one of three values upon completion. PSFS_PASS_ON indicates success with data available in the out bucket brigade. PSFS_FEED_ME indicates that the filter has no data available to return and requires additional data from the stream. PSFS_ERR_FATAL indicates that the filter experienced an unrecoverable error and cannot continue. If no value is returned by this method, PSFS_ERR_FATAL will be assumed. void oncreate (void) This method is called during instantiation of the filter class object. If your filter allocates or initializes any other resources (such as a buffer), this is the place to do it. void onclose (void) This method is called upon filter shutdown (typically, this is also during stream shutdown), and is executed after the flush method is called. If any resources were allocated or initialzed during oncreate this would be the time to destroy or dispose of them. The example below implements a filter named strtoupper on the foo-bar.txt stream which will capitalize all letter characters written to/read from that stream. Example 798. Filter for capitalizing characters on foo-bar.txt stream data = strtoupper($bucket->data); $consumed += $bucket->datalen; stream_bucket_append($out, $bucket); } return PSFS_PASS_ON; 3393 stream_filter_register } } /* Register our filter with PHP */ stream_filter_register("strtoupper", "strtoupper_filter") or die("Failed to register filter"); $fp = fopen("foo-bar.txt", "w"); /* Attach the registered filter to the stream just opened */ stream_filter_append($fp, "strtoupper"); fwrite($fp, "Line1\n"); fwrite($fp, "Word - 2\n"); fwrite($fp, "Easy As 123\n"); fclose($fp); /* Read the contents back out */ readfile("foo-bar.txt"); /* Output * -----LINE1 WORD - 2 EASY AS 123 */ ?> See Also: stream_wrapper_register(), stream_filter_prepend(), and stream_filter_append() 3394 stream_get_filters (PHP 5 CVS only) stream_get_filters - Retrieve list of registered filters Description array stream_get_filters (void) Returns an indexed array containing the name of all stream filters available on the running system. Example 799. Using stream_get_filters() string.rot13 [1] => string.toupper [2] => string.tolower [3] => string.base64 [4] => string.quoted-printable ) */ ?> See also stream_filter_register(), and stream_get_wrappers() 3395 stream_get_line (PHP 5 CVS only) stream_get_line - Gets line from stream resource up to a given delimiter Description string stream_get_line (resource handle, int length, string ending) Returns a string of up to length bytes read from the file pointed to by handle. Reading ends when length bytes have been read, when the string specified by ending is found (which is notincluded in the return value), or on EOF (whichever comes first). If an error occurs, returns FALSE. This function is nearly identical to fgets() except in that it allows end of line delimiters other than the standard \n, \r, and \r\n, and does not return the delimiter itself. See also fread(), fgets(), and fgetc(), 3396 stream_get_meta_data (PHP 4 >= 4.3.0) stream_get_meta_data - Retrieves header/meta data from streams/file pointers Description array stream_get_meta_data (resource stream) Returns information about an existing stream. The stream can be any stream created by fopen(), fsockopen() and pfsockopen(). The result array contains the following items: • timed_out (bool) - TRUE if the stream timed out while waiting for data on the last call to fread() or fgets(). • blocked (bool) - TRUE if the stream is in blocking IO mode. See socket_set_blocking(). • eof (bool) - TRUE if the stream has reached end-of-file. Note that for socket streams this member can be TRUE even when unread_bytes is non-zero. To determine if there is more data to be read, use feof() instead of reading this item. • unread_bytes (int) - the number of bytes currently contained in the read buffer. The following items were added in PHP 4.3: • stream_type (string) - a label describing the underlying implementation of the stream. • wrapper_type (string) - a label describing the protocol wrapper implementation layered over the stream. See Appendix I, List of Supported Protocols/Wrappers for more information about wrappers. • wrapper_data (mixed) - wrapper specific data attached to this stream. See Appendix I, List of Supported Protocols/ Wrappers for more information about wrappers and their wrapper data. • filters (array) - and array containing the names of any filters that have been stacked onto this stream. Filters are currently undocumented. Note: This function was introduced in PHP 4.3, but prior to this version, socket_get_status() could be used to retrieve the first four items, for socket based streams only. In PHP 4.3 and later, socket_get_status() is an alias for this function. Note: This function does NOT work on sockets created by the Socket extension. 3397 stream_get_transports (PHP 5 CVS only) stream_get_transports - Retrieve list of registered socket transports Description array stream_get_transports (void) Returns an indexed array containing the name of all socket transports available on the running system. Example 800. Using stream_get_transports() tcp [1] => udp [2] => unix [3] => udg ) */ ?> See also stream_get_filters(), and stream_get_wrappers() 3398 stream_get_wrappers (PHP 5 CVS only) stream_get_wrappers - Retrieve list of registered streams Description array stream_get_wrappers (void) Returns an indexed array containing the name of all stream wrappers available on the running system. See also stream_wrapper_register() 3399 stream_register_wrapper (PHP 4 >= 4.3.0) stream_register_wrapper - Alias of stream_wrapper_register() Description This function is an alias of stream_wrapper_register(). This function is included for compatability with PHP 4.3.0 and PHP 4.3.1 only. stream_wrapper_register() should be used instead. 3400 stream_select (PHP 4 >= 4.3.0) stream_select - Runs the equivalent of the select() system call on the given arrays of streams with a timeout specified by tv_sec and tv_usec Description int stream_select (resource &read, resource &write, resource &except, int tv_sec [, int tv_usec]) The stream_select() function accepts arrays of streams and waits for them to change status. Its operation is equivalent to that of the socket_select() function except in that it acts on streams. The streams listed in the read array will be watched to see if characters become available for reading (more precisely, to see if a read will not block - in particular, a stream resource is also ready on end-of-file, in which case an fread() will return a zero length string). The streams listed in the write array will be watched to see if a write will not block. The streams listed in the except array will be watched for exceptions. Warning On exit, the arrays are modified to indicate which stream resource actually changed status. You do not need to pass every array to stream_select(). You can leave it out and use an empty array or NULL instead. Also do not forget that those arrays are passed by reference and will be modified after stream_select() returns. Example: /* Prepare the read array */ $read = array($stream1, $stream2); if (false === ($num_changed_streams = stream_select($read, $write = NULL, $except = NULL, 0))) { /* Error handling */ else if ($num_changed_streams > 0) { /* At least on one of the streams something interesting happened */ } Note: Due to a limitation in the current Zend Engine it is not possible to pass a constant modifier like NULL directly as a parameter to a function which expects this parameter to be passed by reference. Instead use a temporary variable or an expression with the leftmost member being a temporary variable: stream_select($r, $w, $e = NULL, 0); The tv_sec and tv_usec together form the timeout parameter. The timeout is an upper bound on the amount of time elapsed before stream_select() returns. tv_sec may be zero , causing stream_select() to return immediately. This is useful for polling. If tv_sec is NULL (no timeout), stream_select() can block indefinitely. On success stream_select() returns the number of stream resorces contained in the modified arrays, which may be zero if the timeout expires before anything interesting happens. On error FALSE is returned. Note: Be sure to use the === operator when checking for an error. Since the stream_select() may return 0 the comparison with == would evaluate to TRUE: if (false === stream_select($r, $w, $e = NULL, 0)) { 3401 stream_select echo "stream_select() failed\n"; } Note: Be aware that some stream implementations need to be handled very carefully. A few basic rules: • You should always try to use stream_select() without timeout. Your program should have nothing to do if there is no data available. Code that depends on timeouts is not usually portable and difficult to debug. • If you read/write to a stream returned in the arrays be aware that they do not necessarily read/write the full amount of data you have requested. Be prepared to even only be able to read/write a single byte. Windows 98 Note: stream_select() used on a pipe returned from proc_open() may cause data loss under Windows 98. See also stream_set_blocking() 3402 stream_set_blocking (PHP 4 >= 4.3.0) stream_set_blocking - Set blocking/non-blocking mode on a stream Description bool stream_set_blocking (resource stream, int mode) If mode is FALSE, the given stream will be switched to non-blocking mode, and if TRUE, it will be switched to blocking mode. This affects calls like fgets() and fread() that read from the stream. In non-blocking mode an fgets() call will always return right away while in blocking mode it will wait for data to become available on the stream. This function was previously called as set_socket_blocking() and later socket_set_blocking() but this usage is deprecated. Note: Prior to PHP 4.3, this function only worked on socket based streams. Since PHP 4.3, this function works for any stream that supports non-blocking mode (currently, regular files and socket streams). See also stream_select() 3403 stream_set_timeout (PHP 4 >= 4.3.0) stream_set_timeout - Set timeout period on a stream Description bool stream_set_timeout (resource stream, int seconds, int microseconds) Sets the timeout value on stream, expressed in the sum of seconds and microseconds. Example 801. stream_set_timeout() Example Note: As of PHP 4.3, this function can (potentially) work on any kind of stream. In PHP 4.3, socket based streams are still the only kind supported in the PHP core, although streams from other extensions may support this function. This function was previously called as set_socket_timeout() and later socket_set_timeout() but this usage is deprecated. See also: fsockopen() and fopen(). 3404 stream_set_write_buffer (PHP 4 >= 4.3.0) stream_set_write_buffer - Sets file buffering on the given stream Description int stream_set_write_buffer (resource stream, int buffer) Output using fwrite() is normally buffered at 8K. This means that if there are two processes wanting to write to the same output stream (a file), each is paused after 8K of data to allow the other to write. stream_set_write_buffer() sets the buffering for write operations on the given filepointer stream to buffer bytes. If buffer is 0 then write operations are unbuffered. This ensures that all writes with fwrite() are completed before other processes are allowed to write to that output stream. The function returns 0 on success, or EOF if the request cannot be honored. The following example demonstrates how to use stream_set_write_buffer() to create an unbuffered stream. Example 802. stream_set_write_buffer() example $fp = fopen($file, "w"); if ($fp) { stream_set_write_buffer($fp, 0); fputs($fp, $output); fclose($fp); } See also fopen() and fwrite(). 3405 stream_socket_accept (PHP 5 CVS only) stream_socket_accept - Accept a connection on a socket created by stream_socket_server() Description resource stream_socket_accept (resource server_socket [, int timeout [, string &peername]]) Accept a connection on a socket previously created by stream_socket_server(). If timeout is specified, the default socket accept timeout will be overridden with the time specified in seconds. The name (address) of the client which connected will be passed back in peername if included and available from the selected transport. peername can also be determined later using stream_socket_get_name(). If the call fails, it will return FALSE. See also stream_socket_server(), stream_socket_get_name(), stream_set_blocking(), stream_set_timeout(), fgets(), fgetss(), fputs(), fclose(), feof(), and the Curl extension. 3406 stream_socket_client (PHP 5 CVS only) stream_socket_client - Open Internet or Unix domain socket connection Description resource stream_socket_client (string remote_socket [, int &errno [, string &errstr [, float timeout [, int flags [, resource context]]]]]) Initiates a stream or datagram connection to the destination specified by remote_socket. The type of socket created is determined by the transport specified using standard url formatting: transport://target. For Internet Domain sockets (AF_INET) such as TCP and UDP, the target portion of the remote_socket parameter should consist of a hostname or IP address followed by a colon and a port number. For Unix Domain sockets, the target portion should point to the socket file on the filesystem. The optional timeout can be used to set a timeout in seconds for the connect system call. flags is a bitmask field which may be set to any combination of connection flags. Currently the selection of connection flags is limited to STREAM_CLIENT_ASYNC_CONNECT and STREAM_CLIENT_PERSISTENT. Note: If you need to set a timeout for reading/writing data over the socket, use stream_set_timeout(), as the timeout parameter to stream_socket_client() only applies while connecting the socket. stream_socket_client() returns a stream resource which may be used together with the other file functions (such as fgets(), fgetss(), fputs(), fclose(), and feof()). If the call fails, it will return FALSE and if the optional errno and errstr arguments are present they will be set to indicate the actual system level error that occurred in the system-level connect() call. If the value returned in errno is 0 and the function returned FALSE, it is an indication that the error occurred before the connect() call. This is most likely due to a problem initializing the socket. Note that the errno and errstr arguments will always be passed by reference. Depending on the environment, the Unix domain or the optional connect timeout may not be available. A list of available transports can be retrieved using stream_get_transports(). See Appendix J, List of Supported Socket Transports for a list of built in transports. The stream will by default be opened in blocking mode. You can switch it to non-blocking mode by using stream_set_blocking(). Example 803. stream_socket_client() Example \n"; } else { fputs ($fp, "GET / HTTP/1.0\r\nHost: www.example.com\r\nAccept: */*\r\n\r\n"); while (!feof($fp)) { echo fgets ($fp,1024); } fclose ($fp); } ?> The example below shows how to retrieve the day and time from the UDP service "daytime" (port 13) in your own machine. Example 804. Using UDP connection \n"; } else { fwrite($fp,"\n"); echo fread($fp, 26); fclose($fp); } ?> Warning UDP sockets will sometimes appear to have opened without an error, even if the remote host is unreachable. The error will only become apparent when you read or write data to/from the socket. The reason for this is because UDP is a "connectionless" protocol, which means that the operating system does not try to establish a link for the socket until it actually needs to send or receive data. Note: When specifying a numerical IPv6 address (e.g. fe80::1) you must enclose the IP in square brackets. For example, tcp://[fe80::1]:80. See also stream_socket_server(), stream_set_blocking(), stream_set_timeout(), fgets(), fgetss(), fputs(), fclose(), feof(), and the Curl extension. 3408 stream_socket_get_name (PHP 5 CVS only) stream_socket_get_name - Retrieve the name of the local or remote sockets Description string stream_socket_get_name (resource handle, boolean want_peer) Returns the local or remote name of a given socket connection. If want_peer is set to TRUE the remote socket name will be returned, if it is set to FALSE the local socket name will be returned. See also stream_socket_accept() 3409 stream_socket_server (PHP 5 CVS only) stream_socket_server - Create an Internet or Unix domain server socket Description resource stream_socket_server (string local_socket [, int &errno [, string &errstr [, int flags [, resource context]]]]) Creates a stream or datagram socket on the specified local_socket. The type of socket created is determined by the transport specified using standard url formatting: transport://target. For Internet Domain sockets (AF_INET) such as TCP and UDP, the target portion of the remote_socket parameter should consist of a hostname or IP address followed by a colon and a port number. For Unix Domain sockets, the target portion should point to the socket file on the filesystem. flags is a bitmask field which may be set to any combination of socket creation flags. The default value of flags is STREAM_SERVER_BIND | STREAM_SERVER_LISTEN. This function only creates a socket, to begin accepting connections use stream_socket_accept(). If the call fails, it will return FALSE and if the optional errno and errstr arguments are present they will be set to indicate the actual system level error that occurred in the system-level connect() call. If the value returned in errno is 0 and the function returned FALSE, it is an indication that the error occurred before the connect() call. This is most likely due to a problem initializing the socket. Note that the errno and errstr arguments will always be passed by reference. Depending on the environment, Unix domain sockets may not be available. A list of available transports can be retrieved using stream_get_transports(). See Appendix J, List of Supported Socket Transports for a list of bulitin transports. stream_socket_server(). Example 805. stream_socket_server() Example \n"; } else { while ($conn = stream_socket_accept($socket)) { fputs ($conn, 'The local time is ' . date('n/j/Y g:i a') . "\n"); fclose ($conn); } fclose($socket); } ?> The example below shows how to act as a time server which can respond to time queries as shown in an example on stream_socket_client(). Note: Most systems require root access to create a server socket on a port below 1024. Example 806. Using UDP server sockets \n"; } else { while ($conn = stream_socket_accept($socket)) { fwrite($conn, date("D M j H:i:s Y\r\n")); 3410 stream_socket_server fclose($conn); } fclose($socket); } ?> Note: When specifying a numerical IPv6 address (e.g. fe80::1) you must enclose the IP in square brackets. For example, tcp://[fe80::1]:80. See also stream_socket_client(), stream_set_blocking(), stream_set_timeout(), fgets(), fgetss(), fputs(), fclose(), feof(), and the Curl extension. 3411 stream_wrapper_register (PHP 4 >= 4.3.2) stream_wrapper_register - Register a URL wrapper implemented as a PHP class Description bool stream_wrapper_register (string protocol, string classname) stream_wrapper_register() allows you to implement your own protocol handlers and streams for use with all the other filesystem functions (such as fopen(), fread() etc.). To implement a wrapper, you need to define a class with a number of member functions, as defined below. When someone fopens your stream, PHP will create an instance of classname and then call methods on that instance. You must implement the methods exactly as described below - doing otherwise will lead to undefined behaviour. stream_wrapper_register() will return FALSE if the protocol already has a handler. bool stream_open (string path, string mode, int options, string opened_path) This method is called immediately after your stream object is created. path specifies the URL that was passed to fopen() and that this object is expected to retrieve. You can use parse_url() to break it apart. mode is the mode used to open the file, as detailed for fopen(). You are responsible for checking that mode is valid for the path requested. options holds additional flags set by the streams API. It can hold one or more of the following values OR'd together. Flag Description STREAM_USE_PATH If path is relative, search for the resource using the include_path. STREAM_REPORT_ERRORS If this flag is set, you are responsible for raising errors using trigger_error() during opening of the stream. If this flag is not set, you should not raise any errors. If the path is opened successfully, and STREAM_USE_PATH is set in options, you should set opened_path to the full path of the file/resource that was actually opened. If the requested resource was opened successfully, you should return TRUE, otherwise you should return FALSE void stream_close (void ) This method is called when the stream is closed, using fclose(). You must release any resources that were locked or allocated by the stream. string stream_read (int count) This method is called in response to fread() and fgets() calls on the stream. You must return up-to count bytes of data from the current read/write position as a string. If there are less than count bytes available, return as many as are available. If no more data is available, return either FALSE or an empty string. You must also update the read/write position of the stream by the number of bytes that were successfully read. int stream_write (string data) This method is called in response to fwrite() calls on the stream. You should store data into the underlying storage used by your stream. If there is not enough room, try to store as many bytes as possible. You should return the number of bytes that were successfully stored in the stream, or 0 if none could be stored. You must also update the read/write position of the 3412 stream_wrapper_register stream by the number of bytes that were successfully written. bool stream_eof (void ) This method is called in response to feof() calls on the stream. You should return TRUE if the read/write position is at the end of the stream and if no more data is available to be read, or FALSE otherwise. int stream_tell (void ) This method is called in response to ftell() calls on the stream. You should return the current read/write position of the stream. bool stream_seek (int offset, int whence) This method is called in response to fseek() calls on the stream. You should update the read/write position of the stream according to offset and whence. See fseek() for more information about these parameters. Return TRUE if the position was updated, FALSE otherwise. bool stream_flush (void ) This method is called in response to fflush() calls on the stream. If you have cached data in your stream but not yet stored it into the underlying storage, you should do so now. Return TRUE if the cached data was successfully stored (or if there was no data to store), or FALSE if the data could not be stored. The example below implements a var:// protocol handler that allows read/write access to a named global variable using standard filesystem stream functions such as fread(). The var:// protocol implemented below, given the url "var://foo" will read/write data to/from $GLOBALS["foo"]. Example 807. A Stream for reading/writing global variables class VariableStream { var $position; var $varname; function stream_open($path, $mode, $options, &$opened_path) { $url = parse_url($path); $this->varname = $url["host"]; $this->position = 0; return true; } function stream_read($count) { $ret = substr($GLOBALS[$this->varname], $this->position, $count); $this->position += strlen($ret); return $ret; } function stream_write($data) { $left = substr($GLOBALS[$this->varname], 0, $this->position); $right = substr($GLOBALS[$this->varname], $this->position + strlen($data)); $GLOBALS[$this->varname] = $left . $data . $right; $this->position += strlen($data); return strlen($data); } function stream_tell() { return $this->position; } function stream_eof() { return $this->position >= strlen($GLOBALS[$this->varname]); } function stream_seek($offset, $whence) 3413 stream_wrapper_register { switch($whence) { case SEEK_SET: if ($offset < strlen($GLOBALS[$this->varname]) && $offset >= 0) { $this->position = $offset; return true; } else { return false; } break; case SEEK_CUR: if ($offset >= 0) { $this->position += $offset; return true; } else { return false; } break; case SEEK_END: if (strlen($GLOBALS[$this->varname]) + $offset >= 0) { $this->position = strlen($GLOBALS[$this->varname]) + $offset; return true; } else { return false; } break; default: return false; } } } stream_wrapper_register("var", "VariableStream") or die("Failed to register protocol"); $myvar = ""; $fp = fopen("var://myvar", "r+"); fwrite($fp, "line1\n"); fwrite($fp, "line2\n"); fwrite($fp, "line3\n"); rewind($fp); while(!feof($fp)) { echo fgets($fp); } fclose($fp); var_dump($myvar); 3414 String functions Table of Contents addcslashes ..................................................................................................................................... 3419 addslashes ...................................................................................................................................... 3420 bin2hex .......................................................................................................................................... 3421 chop .............................................................................................................................................. 3422 chr ................................................................................................................................................ 3423 chunk_split ..................................................................................................................................... 3424 convert_cyr_string ........................................................................................................................... 3425 count_chars ..................................................................................................................................... 3426 crc32 ............................................................................................................................................. 3427 crypt .............................................................................................................................................. 3428 echo .............................................................................................................................................. 3430 explode .......................................................................................................................................... 3432 fprintf ............................................................................................................................................ 3433 get_html_translation_table ................................................................................................................. 3435 hebrev ............................................................................................................................................ 3436 hebrevc .......................................................................................................................................... 3437 html_entity_decode .......................................................................................................................... 3438 htmlentities ..................................................................................................................................... 3440 htmlspecialchars .............................................................................................................................. 3442 implode .......................................................................................................................................... 3444 join ............................................................................................................................................... 3445 levenshtein ..................................................................................................................................... 3446 localeconv ...................................................................................................................................... 3447 ltrim .............................................................................................................................................. 3449 md5_file ......................................................................................................................................... 3450 md5 ............................................................................................................................................... 3451 metaphone ...................................................................................................................................... 3452 money_format ................................................................................................................................. 3453 nl_langinfo ..................................................................................................................................... 3456 nl2br .............................................................................................................................................. 3457 number_format ................................................................................................................................ 3458 ord ................................................................................................................................................ 3459 parse_str ......................................................................................................................................... 3460 print .............................................................................................................................................. 3461 printf ............................................................................................................................................. 3462 quoted_printable_decode ................................................................................................................... 3463 quotemeta ....................................................................................................................................... 3464 rtrim .............................................................................................................................................. 3465 setlocale ......................................................................................................................................... 3466 sha1_file ........................................................................................................................................ 3468 sha1 ............................................................................................................................................... 3469 similar_text ..................................................................................................................................... 3470 soundex .......................................................................................................................................... 3471 sprintf ............................................................................................................................................ 3472 sscanf ............................................................................................................................................ 3474 str_ireplace ..................................................................................................................................... 3475 str_pad ........................................................................................................................................... 3476 str_repeat ........................................................................................................................................ 3477 3415 Strings str_replace ...................................................................................................................................... 3478 str_rot13 ......................................................................................................................................... 3479 str_shuffle ...................................................................................................................................... 3480 str_split .......................................................................................................................................... 3481 str_word_count ................................................................................................................................ 3483 strcasecmp ...................................................................................................................................... 3485 strchr ............................................................................................................................................. 3486 strcmp ............................................................................................................................................ 3487 strcoll ............................................................................................................................................ 3488 strcspn ........................................................................................................................................... 3489 strip_tags ........................................................................................................................................ 3490 stripcslashes .................................................................................................................................... 3491 stripos ............................................................................................................................................ 3492 stripslashes ..................................................................................................................................... 3493 stristr ............................................................................................................................................. 3494 strlen ............................................................................................................................................. 3495 strnatcasecmp .................................................................................................................................. 3496 strnatcmp ........................................................................................................................................ 3497 strncasecmp .................................................................................................................................... 3498 strncmp .......................................................................................................................................... 3499 strpos ............................................................................................................................................. 3500 strrchr ............................................................................................................................................ 3501 strrev ............................................................................................................................................. 3502 strripos ........................................................................................................................................... 3503 strrpos ............................................................................................................................................ 3504 strspn ............................................................................................................................................. 3505 strstr .............................................................................................................................................. 3506 strtok ............................................................................................................................................. 3507 strtolower ....................................................................................................................................... 3509 strtoupper ....................................................................................................................................... 3510 strtr ............................................................................................................................................... 3511 substr_count .................................................................................................................................... 3512 substr_replace ................................................................................................................................. 3513 substr ............................................................................................................................................. 3514 trim ............................................................................................................................................... 3516 ucfirst ............................................................................................................................................ 3517 ucwords ......................................................................................................................................... 3518 vprintf ............................................................................................................................................ 3519 vsprintf .......................................................................................................................................... 3520 wordwrap ....................................................................................................................................... 3521 3416 Introduction These functions all manipulate strings in various ways. Some more specialized sections can be found in the regular expression and URL handling sections. For information on how strings behave, especially with regard to usage of single quotes, double quotes, and escape sequences, see the Strings entry in the Types section of the manual. Requirements No external libraries are needed to build this extension. Installation There is no installation needed to use these functions; they are part of the PHP core. Predefined Constants The constants below are defined by this extension, and will only be available when the extension has either been compiled into PHP or dynamically loaded at runtime. CRYPT_SALT_LENGTH integer CRYPT_STD_DES integer CRYPT_EXT_DES integer CRYPT_MD5 integer CRYPT_BLOWFISH integer HTML_SPECIALCHARS (integer) HTML_ENTITIES (integer) ENT_COMPAT (integer) ENT_QUOTES (integer) ENT_NOQUOTES (integer) CHAR_MAX (integer) LC_CTYPE (integer) LC_NUMERIC (integer) LC_TIME (integer) LC_COLLATE (integer) LC_MONETARY (integer) LC_ALL (integer) 3417 String functions LC_MESSAGES (integer) STR_PAD_LEFT (integer) STR_PAD_RIGHT (integer) STR_PAD_BOTH (integer) See Also For even more powerful string handling and manipulating functions take a look at the POSIX regular expression functions and the Perl compatible regular expression functions. 3418 addcslashes (PHP 4 ) addcslashes - Quote string with slashes in a C style Description string addcslashes (string str, string charlist) Returns a string with backslashes before characters that are listed in charlist parameter. It escapes \n, \r etc. in C-like style, characters with ASCII code lower than 32 and higher than 126 are converted to octal representation. Be careful if you choose to escape characters 0, a, b, f, n, r, t and v. They will be converted to \0, \a, \b, \f, \n, \r, \t and \v. In PHP \0 (NULL), \r (carriage return), \n (newline) and \t (tab) are predefined escape sequences, while in C all of these are predefined escape sequences. charlist like "\0..\37", which would escape all characters with ASCII code between 0 and 31. Example 808. addcslashes() example When you define a sequence of characters in the charlist argument make sure that you know what characters come between the characters that you set as the start and end of the range. Also, if the first character in a range has a lower ASCII value than the second character in the range, no range will be constructed. Only the start, end and period characters will be escaped. Use the ord() function to find the ASCII value for a character. See also stripcslashes(), stripslashes(), htmlspecialchars(), and quotemeta(). 3419 addslashes (PHP 3, PHP 4 ) addslashes - Quote string with slashes Description string addslashes (string str) Returns a string with backslashes before characters that need to be quoted in database queries etc. These characters are single quote ('), double quote ("), backslash (\) and NUL (the NULL byte). Note: magic_quotes_gpc is ON by default. See also stripslashes(), htmlspecialchars(), and quotemeta(). 3420 bin2hex (PHP 3>= 3.0.9, PHP 4 ) bin2hex - Convert binary data into hexadecimal representation Description string bin2hex (string str) Returns an ASCII string containing the hexadecimal representation of str. The conversion is done byte-wise with the highnibble first. See also pack() and unpack(). 3421 chop (PHP 3, PHP 4 ) chop - Alias of rtrim() Description This function is an alias of rtrim(). Note: chop() is different than the Perl chop() function, which removes the last character in the string. 3422 chr (PHP 3, PHP 4 ) chr - Return a specific character Description string chr (int ascii) Returns a one-character string containing the character specified by ascii. Example 809. chr() example You can find an ASCII-table over here: http://www.asciitable.com. This function complements ord(). See also sprintf() with a format string of %c. 3423 chunk_split (PHP 3>= 3.0.6, PHP 4 ) chunk_split - Split a string into smaller chunks Description string chunk_split (string body [, int chunklen [, string end]]) Can be used to split a string into smaller chunks which is useful for e.g. converting base64_encode output to match RFC 2045 semantics. It inserts end (defaults to "\r\n") every chunklen characters (defaults to 76). It returns the new string leaving the original string untouched. Example 810. chunk_split() example See also explode(), split(), wordwrap() and RFC 2045 [http://www.faqs.org/rfcs/rfc2045]. 3424 convert_cyr_string (PHP 3>= 3.0.6, PHP 4 ) convert_cyr_string - Convert from one Cyrillic character set to another Description string convert_cyr_string (string str, string from, string to) This function returns the given string converted from one Cyrillic character set to another. The from and to arguments are single characters that represent the source and target Cyrillic character sets. The supported types are: • k - koi8-r • w - windows-1251 • i - iso8859-5 • a - x-cp866 • d - x-cp866 • m - x-mac-cyrillic 3425 count_chars (PHP 4 ) count_chars - Return information about characters used in a string Description mixed count_chars (string string [, int mode]) Counts the number of occurrences of every byte-value (0..255) in string and returns it in various ways. The optional parameter Mode default to 0. Depending on mode count_chars() returns one of the following: • 0 - an array with the byte-value as key and the frequency of every byte as value. • 1 - same as 0 but only byte-values with a frequency greater than zero are listed. • 2 - same as 0 but only byte-values with a frequency equal to zero are listed. • 3 - a string containing all used byte-values is returned. • 4 - a string containing all not used byte-values is returned. See also strpos() and substr_count(). 3426 crc32 (PHP 4 >= 4.0.1) crc32 - Calculates the crc32 polynomial of a string Description int crc32 (string str) Generates the cyclic redundancy checksum polynomial of 32-bit lengths of the str. This is usually used to validate the integrity of data being transmitted. Note: Because PHP's integer type is signed, and many crc32 checksums will result in negative integers, you need to use the "%u" formatter of sprintf() or printf() to get the string representation of the unsigned crc32 checksum. This second example shows how to print a converted checksum with the printf() function : Example 811. Displaying a crc32 checksum See also md5() and sha1(). 3427 crypt (PHP 3, PHP 4 ) crypt - One-way string encryption (hashing) Description string crypt (string str [, string salt]) crypt() will return an encrypted string using the standard Unix DES-based encryption algorithm or alternative algorithms that may be available on the system. Arguments are a string to be encrypted and an optional salt string to base the encryption on. See the Unix man page for your crypt function for more information. If the salt argument is not provided, one will be randomly generated by PHP. Some operating systems support more than one type of encryption. In fact, sometimes the standard DES-based encryption is replaced by an MD5-based encryption algorithm. The encryption type is triggered by the salt argument. At install time, PHP determines the capabilities of the crypt function and will accept salts for other encryption types. If no salt is provided, PHP will auto-generate a standard two character salt by default, unless the default encryption type on the system is MD5, in which case a random MD5-compatible salt is generated. PHP sets a constant named CRYPT_SALT_LENGTH which tells you whether a regular two character salt applies to your system or the longer twelve character salt is applicable. If you are using the supplied salt, you should be aware that the salt is generated once. If you are calling this function recursively, this may impact both appearance and security. The standard DES-based encryption crypt() returns the salt as the first two characters of the output. It also only uses the first eight characters of str, so longer strings that start with the same eight characters will generate the same result (when the same salt is used). On systems where the crypt() function supports multiple encryption types, the following constants are set to 0 or 1 depending on whether the given type is available: • CRYPT_STD_DES - Standard DES-based encryption with a two character salt • CRYPT_EXT_DES - Extended DES-based encryption with a nine character salt • CRYPT_MD5 - MD5 encryption with a twelve character salt starting with $1$ • CRYPT_BLOWFISH - Blowfish encryption with a sixteen character salt starting with $2$ Note: There is no decrypt function, since crypt() uses a one-way algorithm. Example 812. crypt() examples 3428 crypt See also md5() and the Mcrypt extension. 3429 echo (PHP 3, PHP 4 ) echo - Output one or more strings Description void echo (string arg1 [, string argn...]) Outputs all parameters. echo() is not actually a function (it is a language construct) so you are not required to use parentheses with it. In fact, if you want to pass more than one parameter to echo, you must not enclose the parameters within parentheses. Example 813. echo() examples echo() also has a shortcut syntax, where you can immediately follow the opening tag with an equals sign. I have foo. 3430 echo Note: This short syntax only works with the short_open_tag configuration setting enabled. For a short discussion about the differences between print() and echo(), see this FAQTs Knowledge Base Article: http:// www.faqts.com/knowledge_base/view.phtml/aid/1/fid/40 Note: Because this is a language construct and not a function, it cannot be called using variable functions See also print(), printf(), and flush(). 3431 explode (PHP 3, PHP 4 ) explode - Split a string by string Description array explode (string separator, string string [, int limit]) Returns an array of strings, each of which is a substring of string formed by splitting it on boundaries formed by the string separator. If limit is set, the returned array will contain a maximum of limit elements with the last element containing the rest of string. If separator is an empty string (""), explode() will return FALSE. If separator contains a value that is not contained in string, then explode() will return an array containing string. Note: The limit parameter was added in PHP 4.0.1 Example 814. explode() examples Note: Although implode() can, for historical reasons, accept its parameters in either order, explode() cannot. You must ensure that the separator argument comes before the string argument. See also preg_split(), spliti(), split(), and implode(). 3432 fprintf (PHP 5 CVS only) fprintf - Write a formatted string to a stream Description int fprintf (resource handle, string format [, mixed args]) Write a string produced according to the formatting string format to the stream resource specified by handle.. The format string is composed of zero or more directives: ordinary characters (excluding %) that are copied directly to the result, and conversion specifications, each of which results in fetching its own parameter. This applies to fprintf(), sprintf(), and printf(). Each conversion specification consists of a percent sign (%), followed by one or more of these elements, in order: 1. An optional padding specifier that says what character will be used for padding the results to the right string size. This may be a space character or a 0 (zero character). The default is to pad with spaces. An alternate padding character can be specified by prefixing it with a single quote ('). See the examples below. 2. An optional alignment specifier that says if the result should be left-justified or right-justified. The default is rightjustified; a - character here will make it left-justified. 3. An optional number, a width specifier that says how many characters (minimum) this conversion should result in. 4. An optional precision specifier that says how many decimal digits should be displayed for floating-point numbers. This option has no effect for other types than float. (Another function useful for formatting numbers is number_format().) 5. A type specifier that says what type the argument data should be treated as. Possible types: % - a literal percent character. No argument is required. b - the argument is treated as an integer, and presented as a binary number. c - the argument is treated as an integer, and presented as the character with that ASCII value. d - the argument is treated as an integer, and presented as a (signed) decimal number. u - the argument is treated as an integer, and presented as an unsigned decimal number. f - the argument is treated as a float, and presented as a floating-point number. o - the argument is treated as an integer, and presented as an octal number. s - the argument is treated as and presented as a string. x - the argument is treated as an integer and presented as a hexadecimal number (with lowercase letters). X - the argument is treated as an integer and presented as a hexadecimal number (with uppercase letters). See also: printf(), sprintf(), sscanf(), fscanf(), vsprintf(), and number_format(). Examples Example 815. sprintf(): zero-padded integers Example 816. sprintf(): formatting currency 3434 get_html_translation_table (PHP 4 ) get_html_translation_table - Returns the translation table used by htmlspecialchars() and htmlentities() Description array get_html_translation_table (int table [, int quote_style]) get_html_translation_table() will return the translation table that is used internally for htmlspecialchars() and htmlentities(). There are two new constants (HTML_ENTITIES, HTML_SPECIALCHARS) that allow you to specify the table you want. And as in the htmlspecialchars() and htmlentities() functions you can optionally specify the quote_style you are working with. The default is ENT_COMPAT mode. See the description of these modes in htmlspecialchars(). Example 817. Translation Table Example & Krämer"; $encoded = strtr($str, $trans); ?> The $encoded variable will now contain: "Hallo & <Frau> & Krämer". Another interesting use of this function is to, with help of array_flip(), change the direction of the translation. The content of $original would be: "Hallo & & Krämer". See also htmlspecialchars(), htmlentities(), strtr(), and array_flip(). 3435 hebrev (PHP 3, PHP 4 ) hebrev - Convert logical Hebrew text to visual text Description string hebrev (string hebrew_text [, int max_chars_per_line]) The optional parameter max_chars_per_line indicates maximum number of characters per line will be output. The function tries to avoid breaking words. See also hebrevc() 3436 hebrevc (PHP 3, PHP 4 ) hebrevc - Convert logical Hebrew text to visual text with newline conversion Description string hebrevc (string hebrew_text [, int max_chars_per_line]) This function is similar to hebrev() with the difference that it converts newlines (\n) to "
\n". The optional parameter max_chars_per_line indicates maximum number of characters per line will be output. The function tries to avoid breaking words. See also hebrev() 3437 html_entity_decode (PHP 4 >= 4.3.0) html_entity_decode - Convert all HTML entities to their applicable characters Description string html_entity_decode (string string [, int quote_style [, string charset]]) html_entity_decode() is the opposite of htmlentities() in that it converts all HTML entities to their applicable characters from string. The optional second quote_style parameter lets you define what will be done with 'single' and "double" quotes. It takes on one of three constants with the default being ENT_COMPAT: Table 162. Available quote_style constants Constant Name Description ENT_COMPAT Will convert double-quotes and leave single-quotes alone. ENT_QUOTES Will convert both double and single quotes. ENT_NOQUOTES Will leave both double and single quotes unconverted. The ISO-8859-1 character set is used as default for the optional third charset. This defines the character set used in conversion. Support for this third argument was added in PHP 4.1.0. Following character sets are supported in PHP 4.3.0 and later. Table 163. Supported charsets Charset Aliases Description ISO-8859-1 ISO8859-1 Western European, Latin-1 ISO-8859-15 ISO8859-15 Western European, Latin-9. Adds the Euro sign, French and Finish letters missing in Latin-1(ISO-8859-1). UTF-8 ASCII compatible multi-byte 8-bit Unicode. cp866 ibm866, 866 DOS specific charset for Russian. This charset is supported in 4.3.2. cp1251 Windows-1251, win-1251, 1251 Windows specific charset for Russian. This charset is supported in 4.3.2. cp1252 Windows-1252, 1252 Windows specific charset for Western European. KOI8-R koi8-ru, koi8r Russian. This charset is supported in 4.3.2. BIG5 950 Traditional Chinese, mainly used in Taiwan. GB2312 936 Simplified Chinese, national standard character set. BIG5-HKSCS Big5 with Hong Kong extensions, Traditional Chinese. 3438 html_entity_decode Charset Aliases Description Shift_JIS SJIS, 932 Japanese EUC-JP EUCJP Japanese Note: Any other character sets are not recognized and ISO-8859-1 will be used instead. Example 818. Decoding html entities dog now"; $a = htmlentities($orig); $b = html_entity_decode($a); echo $a; // I'll "walk" the <b>dog</b> now echo $b; // I'll "walk" the dog now // For users prior to PHP 4.3.0 you may do this: function unhtmlentities ($string) { $trans_tbl = get_html_translation_table (HTML_ENTITIES); $trans_tbl = array_flip ($trans_tbl); return strtr ($string, $trans_tbl); } $c = unhtmlentities($a); echo $c; // I'll "walk" the dog now ?> Note: You might wonder why trim(html_entity_decode(' ')); doesn't reduce the string to an empty string, that's because the ' ' entity is not ASCII code 32 (which is stripped by trim()) but ASCII code 160 (0xa0) in the default ISO 8859-1 characterset. See also htmlentities(), htmlspecialchars(), get_html_translation_table(), htmlspecialchars() and urldecode(). 3439 htmlentities (PHP 3, PHP 4 ) htmlentities - Convert all applicable characters to HTML entities Description string htmlentities (string string [, int quote_style [, string charset]]) This function is identical to htmlspecialchars() in all ways, except with htmlentities(), all characters which have HTML character entity equivalents are translated into these entities. Like htmlspecialchars(), the optional second quote_style parameter lets you define what will be done with 'single' and "double" quotes. It takes on one of three constants with the default being ENT_COMPAT: Table 164. Available quote_style constants Constant Name Description ENT_COMPAT Will convert double-quotes and leave single-quotes alone. ENT_QUOTES Will convert both double and single quotes. ENT_NOQUOTES Will leave both double and single quotes unconverted. Support for the optional quote parameter was added in PHP 4.0.3. Like htmlspecialchars(), it takes an optional third argument charset which defines character set used in conversion. Support for this argument was added in PHP 4.1.0. Presently, the ISO-8859-1 character set is used as the default. Following character sets are supported in PHP 4.3.0 and later. Table 165. Supported charsets Charset Aliases Description ISO-8859-1 ISO8859-1 Western European, Latin-1 ISO-8859-15 ISO8859-15 Western European, Latin-9. Adds the Euro sign, French and Finish letters missing in Latin-1(ISO-8859-1). UTF-8 ASCII compatible multi-byte 8-bit Unicode. cp866 ibm866, 866 DOS specific charset for Russian. This charset is supported in 4.3.2. cp1251 Windows-1251, win-1251, 1251 Windows specific charset for Russian. This charset is supported in 4.3.2. cp1252 Windows-1252, 1252 Windows specific charset for Western European. KOI8-R koi8-ru, koi8r Russian. This charset is supported in 4.3.2. BIG5 950 Traditional Chinese, mainly used in Taiwan. GB2312 936 Simplified Chinese, national standard character set. 3440 htmlentities Charset Aliases Description BIG5-HKSCS Big5 with Hong Kong extensions, Traditional Chinese. Shift_JIS SJIS, 932 Japanese EUC-JP EUCJP Japanese Note: Any other character sets are not recognized and ISO-8859-1 will be used instead. If you're wanting to decode instead (the reverse) you can use html_entity_decode(). See also html_entity_decode(), get_html_translation_table(), htmlspecialchars(), nl2br(), and urlencode(). 3441 htmlspecialchars (PHP 3, PHP 4 ) htmlspecialchars - Convert special characters to HTML entities Description string htmlspecialchars (string string [, int quote_style [, string charset]]) Certain characters have special significance in HTML, and should be represented by HTML entities if they are to preserve their meanings. This function returns a string with some of these conversions made; the translations made are those most useful for everyday web programming. If you require all HTML character entities to be translated, use htmlentities() instead. This function is useful in preventing user-supplied text from containing HTML markup, such as in a message board or guest book application. The optional second argument, quote_style, tells the function what to do with single and double quote characters. The default mode, ENT_COMPAT, is the backwards compatible mode which only translates the double-quote character and leaves the single-quote untranslated. If ENT_QUOTES is set, both single and double quotes are translated and if ENT_NOQUOTES is set neither single nor double quotes are translated. The translations performed are: • '&' (ampersand) becomes '&' • '"' (double quote) becomes '"' when ENT_NOQUOTES is not set. • ''' (single quote) becomes ''' only when ENT_QUOTES is set. • '<' (less than) becomes '<' • '>' (greater than) becomes '>' Example 819. htmlspecialchars() example Test", ENT_QUOTES); echo $new; // <a href='test'>Test</a> ?> Note that this function does not translate anything beyond what is listed above. For full entity translation, see htmlentities(). Support for the optional second argument was added in PHP 3.0.17 and PHP 4.0.3. The third argument charset defines character set used in conversion. The default character set is ISO-8859-1. Support for this third argument was added in PHP 4.1.0. Following character sets are supported in PHP 4.3.0 and later. Table 166. Supported charsets Charset Aliases Description ISO-8859-1 ISO8859-1 Western European, Latin-1 ISO-8859-15 ISO8859-15 Western European, Latin-9. Adds the Euro sign, French and Finish letters 3442 htmlspecialchars Charset Aliases Description missing in Latin-1(ISO-8859-1). UTF-8 ASCII compatible multi-byte 8-bit Unicode. cp866 ibm866, 866 DOS specific charset for Russian. This charset is supported in 4.3.2. cp1251 Windows-1251, win-1251, 1251 Windows specific charset for Russian. This charset is supported in 4.3.2. cp1252 Windows-1252, 1252 Windows specific charset for Western European. KOI8-R koi8-ru, koi8r Russian. This charset is supported in 4.3.2. BIG5 950 Traditional Chinese, mainly used in Taiwan. GB2312 936 Simplified Chinese, national standard character set. BIG5-HKSCS Big5 with Hong Kong extensions, Traditional Chinese. Shift_JIS SJIS, 932 Japanese EUC-JP EUCJP Japanese Note: Any other character sets are not recognized and ISO-8859-1 will be used instead. See also get_html_translation_table(), htmlentities(), and nl2br(). 3443 implode (PHP 3, PHP 4 ) implode - Join array elements with a string Description string implode ([string glue, array pieces]) Returns a string containing a string representation of all the array elements in the same order, with the glue string between each element. Example 820. implode() example Note: implode() can, for historical reasons, accept its parameters in either order. For consistency with explode(), however, it may be less confusing to use the documented order of arguments. Note: As of PHP 4.3.0, the glue parameter of implode() is optional and defaults to the empty string(''). See also explode(), and split(). 3444 join (PHP 3, PHP 4 ) join - Alias for implode() Description This function is an alias of implode(). 3445 levenshtein (PHP 3>= 3.0.17, PHP 4 >= 4.0.1) levenshtein - Calculate Levenshtein distance between two strings Description int levenshtein (string str1, string str2) int levenshtein (string str1, string str2, int cost_ins, int cost_rep, int cost_del) int levenshtein (string str1, string str2, function cost) This function returns the Levenshtein-Distance between the two argument strings or -1, if one of the argument strings is longer than the limit of 255 characters (255 should be more than enough for name or dictionary comparison, and nobody serious would be doing genetic analysis with PHP). The Levenshtein distance is defined as the minimal number of characters you have to replace, insert or delete to transform str1 into str2. The complexity of the algorithm is O(m*n), where n and m are the length of str1 and str2 (rather good when compared to similar_text(), which is O(max(n,m)**3), but still expensive). In its simplest form the function will take only the two strings as parameter and will calculate just the number of insert, replace and delete operations needed to transform str1 into str2. A second variant will take three additional parameters that define the cost of insert, replace and delete operations. This is more general and adaptive than variant one, but not as efficient. The third variant (which is not implemented yet) will be the most general and adaptive, but also the slowest alternative. It will call a user-supplied function that will determine the cost for every possible operation. The user-supplied function will be called with the following arguments: • operation to apply: 'I', 'R' or 'D' • actual character in string 1 • actual character in string 2 • position in string 1 • position in string 2 • remaining characters in string 1 • remaining characters in string 2 The user-supplied function has to return a positive integer describing the cost for this particular operation, but it may decide to use only some of the supplied arguments. The user-supplied function approach offers the possibility to take into account the relevance of and/or difference between certain symbols (characters) or even the context those symbols appear in to determine the cost of insert, replace and delete operations, but at the cost of losing all optimizations done regarding cpu register utilization and cache misses that have been worked into the other two variants. See also soundex(), similar_text(), and metaphone(). 3446 localeconv (PHP 4 >= 4.0.5) localeconv - Get numeric formatting information Description array localeconv (void) Returns an associative array containing localized numeric and monetary formatting information. localeconv() returns data based upon the current locale as set by setlocale(). The associative array that is returned contains the following fields: Array element Description decimal_point Decimal point character thousands_sep Thousands separator grouping Array containing numeric groupings int_curr_symbol International currency symbol (i.e. USD) currency_symbol Local currency symbol (i.e. $) mon_decimal_point Monetary decimal point character mon_thousands_sep Monetary thousands separator mon_grouping Array containing monetary groupings positive_sign Sign for positive values negative_sign Sign for negative values int_frac_digits International fractional digits frac_digits Local fractional digits p_cs_precedes TRUE if currency_symbol precedes a positive value, FALSE if it succeeds one p_sep_by_space TRUE if a space separates currency_symbol from a positive value, FALSE otherwise n_cs_precedes TRUE if currency_symbol precedes a negative value, FALSE if it succeeds one n_sep_by_space TRUE if a space separates currency_symbol from a negative value, FALSE otherwise p_sign_posn 0 n_sign_posn 0 The sign string succeeds the quantity and currency_symbol Parentheses surround the3 quantity and currency_symbol 1 The sign string immediately precedes the currency_symbol The sign string precedes the4 quantity and currency_symbol 2 The sign string immediately succeeds the currency_symbol 3447 The sign string succeeds the quantity and currency_symbol localeconv Array element Description Parentheses surround the3 quantity and currency_symbol 1 The sign string immediately precedes the currency_symbol The sign string precedes the4 quantity and currency_symbol 2 The sign string immediately succeeds the currency_symbol The grouping fields contain arrays that define the way numbers should be grouped. For example, the grouping field for the en_US locale, would contain a 2 item array with the values 3 and 3. The higher the index in the array, the farther left the grouping is. If an array element is equal to CHAR_MAX, no further grouping is done. If an array element is equal to 0, the previous element should be used. Example 821. localeconv() example \n"; "--------------------------------------------\n"; " Monetary information for current locale: \n"; "--------------------------------------------\n\n"; echo echo echo echo echo echo echo echo echo echo echo echo echo echo echo ?> "int_curr_symbol: "currency_symbol: "mon_decimal_point: "mon_thousands_sep: "positive_sign: "negative_sign: "int_frac_digits: "frac_digits: "p_cs_precedes: "p_sep_by_space: "n_cs_precedes: "n_sep_by_space: "p_sign_posn: "n_sign_posn: "\n"; {$locale_info["int_curr_symbol"]}\n"; {$locale_info["currency_symbol"]}\n"; {$locale_info["mon_decimal_point"]}\n"; {$locale_info["mon_thousands_sep"]}\n"; {$locale_info["positive_sign"]}\n"; {$locale_info["negative_sign"]}\n"; {$locale_info["int_frac_digits"]}\n"; {$locale_info["frac_digits"]}\n"; {$locale_info["p_cs_precedes"]}\n"; {$locale_info["p_sep_by_space"]}\n"; {$locale_info["n_cs_precedes"]}\n"; {$locale_info["n_sep_by_space"]}\n"; {$locale_info["p_sign_posn"]}\n"; {$locale_info["n_sign_posn"]}\n"; The constant CHAR_MAX is also defined for the use mentioned above. See also setlocale(). 3448 ltrim (PHP 3, PHP 4 ) ltrim - Strip whitespace from the beginning of a string Description string ltrim (string str [, string charlist]) Note: The second parameter was added in PHP 4.1.0 This function returns a string with whitespace stripped from the beginning of str. Without the second parameter, ltrim() will strip these characters: • " " (ASCII 32 (0x20)), an ordinary space. • "\t" (ASCII 9 (0x09)), a tab. • "\n" (ASCII 10 (0x0A)), a new line (line feed). • "\r" (ASCII 13 (0x0D)), a carriage return. • "\0" (ASCII 0 (0x00)), the NUL-byte. • "\x0B" (ASCII 11 (0x0B)), a vertical tab. You can also specify the characters you want to strip, by means of the charlist parameter. Simply list all characters that you want to be stripped. With .. you can specify a range of characters. Example 822. Usage example of ltrim() See also trim() and rtrim(). 3449 md5_file (PHP 4 >= 4.2.0) md5_file - Calculates the md5 hash of a given filename Description string md5_file (string filename [, bool raw_output]) Calculates the MD5 hash of the specified filename using the RSA Data Security, Inc. MD5 Message-Digest Algorithm [http://www.faqs.org/rfcs/rfc1321], and returns that hash. The hash is a 32-character hexadecimal number. If the optional raw_output is set to TRUE, then the md5 digest is instead returned in raw binary format with a length of 16. Note: The optional raw_output parameter was added in PHP 5.0.0 and defaults to FALSE This function has the same purpose of the command line utility md5sum. See also md5(), crc32(), and sha1_file(). 3450 md5 (PHP 3, PHP 4 ) md5 - Calculate the md5 hash of a string Description string md5 (string str [, bool raw_output]) Calculates the MD5 hash of str using the RSA Data Security, Inc. MD5 Message-Digest Algorithm [http://www.faqs.org/ rfcs/ rfc1321], and returns that hash. The hash is a 32-character hexadecimal number. If the optional raw_output is set to TRUE, then the md5 digest is instead returned in raw binary format with a length of 16. Note: The optional raw_output parameter was added in PHP 5.0.0 and defaults to FALSE See also crc32(), md5_file(), and sha1(). 3451 metaphone (PHP 4 ) metaphone - Calculate the metaphone key of a string Description string metaphone (string str) Calculates the metaphone key of str. Similar to soundex() metaphone creates the same key for similar sounding words. It's more accurate than soundex() as it knows the basic rules of English pronunciation. The metaphone generated keys are of variable length. Metaphone was developed by Lawrence Philips . It is described in ["Practical Algorithms for Programmers", Binstock & Rex, Addison Wesley, 1995]. 3452 money_format (PHP 4 >= 4.3.0) money_format - Formats a number as a currency string Description string money_format (string format, float number) money_format() returns a formatted version of number. This function wraps the C library function strfmon(), with the difference that this implementation converts only one number at a time. Note: The function money_format() is only defined if the system has strfmon capabilities. For example, Windows does not, so money_format() is undefined in Windows. The format specification consists of the following sequence: • a % character • optional flags • optional field width • optional left precision • optional right precision • a required conversion character Flags. One or more of the optional flags below can be used: =f The character = followed by a a (single byte) character f to be used as the numeric fill character. The default fill character is space. ^ Disable the use of grouping characters (as defined by the current locale). + or ( Specify the formatting style for positive and negative numbers. If + is used, the locale's equivalent for + and - will be used. If ( is used, negative amounts are enclosed in parenthesis. If no specification is given, the default is +. ! Suppress the currency symbol from the output string. - If present, it will make all fields left-justified (padded to the right), as opposed to the default which is for the fields to be right-justified (padded to the left). Field width. w 3453 money_format A decimal digit string specifying a minimum field width. Field will be right-justified unless the flag - is used. Default value is 0 (zero). Left precision. #n The maximum number of digits (n) expected to the left of the decimal character (e.g. the decimal point). It is used usually to keep formatted output aligned in the same columns, using the fill character if the number of digits is less than n. If the number of actual digits is bigger than n, then this specification is ignored. If grouping has not been suppressed using the ^ flag, grouping separators will be inserted before the fill characters (if any) are added. Grouping separators will not be applied to fill characters, even if the fill character is a digit. To ensure alignment, any characters appearing before or after the number in the formatted output such as currency or sign symbols are padded as necessary with space characters to make their positive and negative formats an equal length. Right precision . .p A period followed by the number of digits (p) after the decimal character. If the value of p is 0 (zero), the decimal character and the digits to its right will be omitted. If no right precision is included, the default will dictated by the current local in use. The amount being formatted is rounded to the specified number of digits prior to formatting. Conversion characters . i The number is formatted according to the locale's international currency format (e.g. for the USA locale: USD 1,234.56). n The number is formatted according to the locale's national currency format (e.g. for the de_DE locale: DM1.234,56). % Returns the the % character. Note: The LC_MONETARY category of the locale settings, affects the behavior of this function. Use setlocale() to set to the appropriate default locale before using this function. Characters before and after the formatting string will be returned unchanged. Example 823. money_format() Example We will use different locales and format specifications to illustrate the use of this function. See also: setlocale(), number_format(),sprintf(), printf() and sscanf(). 3455 nl_langinfo (PHP 4 >= 4.1.0) nl_langinfo - Query language and locale information Description string nl_langinfo (int item) Warning This function is currently not documented; only the argument list is available. 3456 nl2br (PHP 3, PHP 4 ) nl2br - Inserts HTML line breaks before all newlines in a string Description string nl2br (string string) Returns string with '
' inserted before all newlines. Note: Starting with PHP 4.0.5, nl2br() is now XHTML compliant. All versions before 4.0.5 will return string with '
' inserted before newlines instead of '
'. See also htmlspecialchars(), htmlentities(), wordwrap(), and str_replace(). 3457 number_format (PHP 3, PHP 4 ) number_format - Format a number with grouped thousands Description string number_format (float number [, int decimals [, string dec_point [, string thousands_sep]]]) number_format() returns a formatted version of number. This function accepts either one, two or four parameters (not three): If only one parameter is given, number will be formatted without decimals, but with a comma (",") between every group of thousands. If two parameters are given, number will be formatted with decimals decimals with a dot (".") in front, and a comma (",") between every group of thousands. If all four parameters are given, number will be formatted with decimals decimals, dec_point instead of a dot (".") before the decimals and thousands_sep instead of a comma (",") between every group of thousands. Note: Only the first character of thousands_sep is used. For example, if you use foo as thousands_sep on the number 1000, number_format() will return 1f000. Example 824. number_format() Example For instance, French notation usually use two decimals, comma (',') as decimal separator, and space (' ') as thousand separator. This is achieved with this line : See also: sprintf(), printf() and sscanf(). 3458 ord (PHP 3, PHP 4 ) ord - Return ASCII value of character Description int ord (string string) Returns the ASCII value of the first character of string. This function complements chr(). Example 825. ord() example You can find an ASCII-table over here: http://www.asciitable.com. See also chr(). 3459 parse_str (PHP 3, PHP 4 ) parse_str - Parses the string into variables Description void parse_str (string str [, array arr ]) Parses str as if it were the query string passed via an URL and sets variables in the current scope. If the second parameter arr is present, variables are stored in this variable as array elements instead. Note: Support for the optional second parameter was added in PHP 4.0.3. Note: To get the current QUERY_STRING, you may use the variable $_SERVER['QUERY_STRING']. Also, you may want to read the section on variables from outside of PHP. Example 826. Using parse_str() See also parse_url(), pathinfo(), set_magic_quotes_runtime(), and urldecode(). 3460 print (PHP 3, PHP 4 ) print - Output a string Description void print (string arg) Outputs arg. Returns TRUE on success or FALSE on failure. print() is not actually a real function (it is a language construct) so you are not required to use parentheses with it. Example 827. print() examples For a short discussion about the differences between print() and echo(), see this FAQTs Knowledge Base Article: http:// www.faqts.com/knowledge_base/view.phtml/aid/1/fid/40 Note: Because this is a language construct and not a function, it cannot be called using variable functions See also echo(), printf(), and flush(). 3461 printf (PHP 3, PHP 4 ) printf - Output a formatted string Description void printf (string format [, mixed args]) Produces output according to format, which is described in the documentation for sprintf(). See also print(), sprintf(), sscanf(), fscanf(), and flush(). 3462 quoted_printable_decode (PHP 3>= 3.0.6, PHP 4 ) quoted_printable_decode - Convert a quoted-printable string to an 8 bit string Description string quoted_printable_decode (string str) This function returns an 8-bit binary string corresponding to the decoded quoted printable string. This function is similar to imap_qprint(), except this one does not require the IMAP module to work. 3463 quotemeta (PHP 3, PHP 4 ) quotemeta - Quote meta characters Description string quotemeta (string str) Returns a version of str with a backslash character (\) before every character that is among these: . \\ + * ? [ ^ ] ( $ ) See also addslashes(), htmlentities(), htmlspecialchars(), nl2br(), and stripslashes(). 3464 rtrim (PHP 3, PHP 4 ) rtrim - Strip whitespace from the end of a string Description string rtrim (string str [, string charlist]) Note: The second parameter was added in PHP 4.1.0 This function returns a string with whitespace stripped from the end of str. Without the second parameter, rtrim() will strip these characters: • " " (ASCII 32 (0x20)), an ordinary space. • "\t" (ASCII 9 (0x09)), a tab. • "\n" (ASCII 10 (0x0A)), a new line (line feed). • "\r" (ASCII 13 (0x0D)), a carriage return. • "\0" (ASCII 0 (0x00)), the NUL-byte. • "\x0B" (ASCII 11 (0x0B)), a vertical tab. You can also specify the characters you want to strip, by means of the charlist parameter. Simply list all characters that you want to be stripped. With .. you can specify a range of characters. Example 828. Usage example of rtrim() See also trim() and ltrim(). 3465 setlocale (PHP 3, PHP 4 ) setlocale - Set locale information Description string setlocale (mixed category, string locale [, string ...]) string setlocale (mixed category, array locale) Category is a named constant (or string) specifying the category of the functions affected by the locale setting: • LC_ALL for all of the below • LC_COLLATE for string comparison, see strcoll() • LC_CTYPE for character classification and conversion, for example strtoupper() • LC_MONETARY for localeconv() • LC_NUMERIC for decimal separator (See also localeconv()) • LC_TIME for date and time formatting with strftime() If locale is the empty string "", the locale names will be set from the values of environment variables with the same names as the above categories, or from "LANG". If locale is zero or "0", the locale setting is not affected, only the current setting is returned. If locale is an array or followed by additional parameters then each array element or parameter is tried to be set as new locale until success. This is usefull if a locale is known under different names on different systems or for providing a fallback for a possibly not available locale. Note: Passing multiple locales is not available before PHP 4.3.0 Setlocale returns the new current locale, or FALSE if the locale functionality is not implemented in the platform, the specified locale does not exist or the category name is invalid. An invalid category name also causes a warning message. Note: The return value of setlocale() depends on the system that PHP is running. It returns exactly what the system setlocale function returns. Example 829. setlocale() Examples 3466 setlocale 3467 sha1_file (PHP 4 >= 4.3.0) sha1_file - Calculate the sha1 hash of a file Description string sha1_file (string filename [, bool raw_output]) Calculates the sha1 hash of filename using the US Secure Hash Algorithm 1 [http://www.faqs.org/rfcs/rfc3174], and returns that hash. The hash is a 40-character hexadecimal number. Upon failure, FALSE is returned. If the optional raw_output is set to TRUE, then the sha1 digest is instead returned in raw binary format with a length of 20. Note: The optional raw_output parameter was added in PHP 5.0.0 and defaults to FALSE See also sha1(), crc32(), and md5_file() 3468 sha1 (PHP 4 >= 4.3.0) sha1 - Calculate the sha1 hash of a string Description string sha1 (string str [, bool raw_output]) Calculates the sha1 hash of str using the US Secure Hash Algorithm 1 [http://www.faqs.org/rfcs/rfc3174], and returns that hash. The hash is a 40-character hexadecimal number. If the optional raw_output is set to TRUE, then the sha1 digest is instead returned in raw binary format with a length of 20. Note: The optional raw_output parameter was added in PHP 5.0.0 and defaults to FALSE See also sha1_file(), crc32(), and md5() 3469 similar_text (PHP 3>= 3.0.7, PHP 4 ) similar_text - Calculate the similarity between two strings Description int similar_text (string first, string second [, float percent]) This calculates the similarity between two strings as described in Oliver [1993]. Note that this implementation does not use a stack as in Oliver's pseudo code, but recursive calls which may or may not speed up the whole process. Note also that the complexity of this algorithm is O(N**3) where N is the length of the longest string. By passing a reference as third argument, similar_text() will calculate the similarity in percent for you. It returns the number of matching chars in both strings. 3470 soundex (PHP 3, PHP 4 ) soundex - Calculate the soundex key of a string Description string soundex (string str) Calculates the soundex key of str. Soundex keys have the property that words pronounced similarly produce the same soundex key, and can thus be used to simplify searches in databases where you know the pronunciation but not the spelling. This soundex function returns a string 4 characters long, starting with a letter. This particular soundex function is one described by Donald Knuth in "The Art Of Computer Programming, vol. 3: Sorting And Searching", Addison-Wesley (1973), pp. 391-392. Example 830. Soundex Examples See also levenshtein(), metaphone(), and similar_text(). 3471 sprintf (PHP 3, PHP 4 ) sprintf - Return a formatted string Description string sprintf (string format [, mixed args]) Returns a string produced according to the formatting string format. The format string is composed of zero or more directives: ordinary characters (excluding %) that are copied directly to the result, and conversion specifications, each of which results in fetching its own parameter. This applies to both sprintf() and printf(). Each conversion specification consists of a percent sign (%), followed by one or more of these elements, in order: 1. An optional padding specifier that says what character will be used for padding the results to the right string size. This may be a space character or a 0 (zero character). The default is to pad with spaces. An alternate padding character can be specified by prefixing it with a single quote ('). See the examples below. 2. An optional alignment specifier that says if the result should be left-justified or right-justified. The default is rightjustified; a - character here will make it left-justified. 3. An optional number, a width specifier that says how many characters (minimum) this conversion should result in. 4. An optional precision specifier that says how many decimal digits should be displayed for floating-point numbers. This option has no effect for other types than float. (Another function useful for formatting numbers is number_format().) 5. A type specifier that says what type the argument data should be treated as. Possible types: % - a literal percent character. No argument is required. b - the argument is treated as an integer, and presented as a binary number. c - the argument is treated as an integer, and presented as the character with that ASCII value. d - the argument is treated as an integer, and presented as a (signed) decimal number. u - the argument is treated as an integer, and presented as an unsigned decimal number. f - the argument is treated as a float, and presented as a floating-point number. o - the argument is treated as an integer, and presented as an octal number. s - the argument is treated as and presented as a string. x - the argument is treated as an integer and presented as a hexadecimal number (with lowercase letters). X - the argument is treated as an integer and presented as a hexadecimal number (with uppercase letters). As of PHP version 4.0.6 the format string supports argument numbering/swapping. Here is an example: Example 831. Argument swapping This might output, "There are 5 monkeys in the tree". But imagine we are creating a format string in a separate file, commonly because we would like to internationalize it and we rewrite it as: 3472 sprintf Example 832. Argument swapping We now have a problem. The order of the placeholders in the format string does not match the order of the arguments in the code. We would like to leave the code as is and simply indicate in the format string which arguments the placeholders refer to. We would write the format string like this instead: Example 833. Argument swapping An added benefit here is that you can repeat the placeholders without adding more arguments in the code. For example: Example 834. Argument swapping See also printf(), sscanf(), fscanf(), vsprintf(), and number_format(). Examples Example 835. sprintf(): zero-padded integers Example 836. sprintf(): formatting currency 3473 sscanf (PHP 4 >= 4.0.1) sscanf - Parses input from a string according to a format Description mixed sscanf (string str, string format [, string var1]) The function sscanf() is the input analog of printf(). sscanf() reads from the string str and interprets it according to the specified format. If only two parameters were passed to this function, the values parsed will be returned as an array. Any whitespace in the format string matches any whitespace in the input string. This means that even a tab \t in the format string can match a single space character in the input string. Example 837. sscanf() Example If optional parameters are passed, the function will return the number of assigned values. The optional parameters must be passed by reference. Example 838. sscanf() - using optional parameters $first $last \n"; ?> See also fscanf(), printf(), and sprintf(). 3474 str_ireplace (PHP 5 CVS only) str_ireplace - Case-insensitive version of str_replace(). Description mixed str_ireplace (mixed search, mixed replace, mixed subject [, int &count]) This function returns a string or an array with all occurences of search in subject (ignoring case) replaced with the given replace value. If you don't need fancy replacing rules, you should generally use this function instead of eregi_replace() or preg_replace() with the i modifier. If subject is an array, then the search and replace is performed with every entry of subject, and the return value is an array as well. If search and replace are arrays, then str_ireplace() takes a value from each array and uses them to do search and replace on subject. If replace has fewer values than search, then an empty string is used for the rest of replacement values. If search is an array and replace is a string; then this replacement string is used for every value of search. Example 839. str_ireplace() example "); ?> This function is binary safe. Note: As of PHP 5.0 the number of matched and replaced needles will be returned in count which is passed by reference. See also: str_replace(), ereg_replace(), preg_replace(), and strtr(). 3475 str_pad (PHP 4 >= 4.0.1) str_pad - Pad a string to a certain length with another string Description string str_pad (string input, int pad_length [, string pad_string [, int pad_type]]) This functions returns the input string padded on the left, the right, or both sides to the specified padding length. If the optional argument pad_string is not supplied, the input is padded with spaces, otherwise it is padded with characters from pad_string up to the limit. Optional argument pad_type can be STR_PAD_RIGHT, STR_PAD_LEFT, or STR_PAD_BOTH. If pad_type is not specified it is assumed to be STR_PAD_RIGHT. If the value of pad_length is negative or less than the length of the input string, no padding takes place. Example 840. str_pad() example // produces "Alien " // produces "-=-=-Alien" // produces "__Alien___" 3476 str_repeat (PHP 4 ) str_repeat - Repeat a string Description string str_repeat (string input, int multiplier) Returns input_str repeated multiplier times. multiplier has to be greater than or equal to 0. If the multiplier is set to 0, the function will return an empty string. Example 841. str_repeat() example This will output "-=-=-=-=-=-=-=-=-=-=". See also for, str_pad(), and substr_count(). 3477 str_replace (PHP 3>= 3.0.6, PHP 4 ) str_replace - Replace all occurrences of the search string with the replacement string Description mixed str_replace (mixed search, mixed replace, mixed subject [, int &count]) This function returns a string or an array with all occurences of search in subject replaced with the given replace value. If you don't need fancy replacing rules, you should always use this function instead of ereg_replace() or preg_replace(). In PHP 4.0.5 and later, every parameter to str_replace() can be an array. If subject is an array, then the search and replace is performed with every entry of subject, and the return value is an array as well. If search and replace are arrays, then str_replace() takes a value from each array and uses them to do search and replace on subject. If replace has fewer values than search, then an empty string is used for the rest of replacement values. If search is an array and replace is a string; then this replacement string is used for every value of search. Example 842. str_replace() example "); ?> This function is binary safe. Note: str_replace() was added in PHP 3.0.6, but was buggy up until PHP 3.0.8. Note: As of PHP 5.0 the number of matched and replaced needles will be returned in count which is passed by reference. See also str_ireplace(), ereg_replace(), preg_replace(), and strtr(). 3478 str_rot13 (PHP 4 >= 4.2.0) str_rot13 - Perform the rot13 transform on a string Description string str_rot13 (string str) This function performs the ROT13 encoding on the str argument and returns the resulting string. The ROT13 encoding simply shifts every letter by 13 places in the alphabet while leaving non-alpha characters untouched. Encoding and decoding are done by the same function, passing an encoded string as argument will return the original version. 3479 str_shuffle (PHP 4 >= 4.3.0) str_shuffle - Randomly shuffles a string Description string str_shuffle (string str) str_shuffle() shuffles a string. One permutation of all possible is created. Example 843. str_shuffle() example See also shuffle() and rand(). 3480 str_split (PHP 5 CVS only) str_split - Convert a string to an array Description array str_split (string string [, int split_length]) Converts a string to an array. If the optional split_length parameter is specified, the returned array will be broken down into chunks with each being split_length in length, otherwise each chunk will be one character in length. FALSE is returned if split_length is less than 1. If the split_length length exceeds the length of string, the entire string is re- turned as the first (and only) array element. Example 844. Example uses of str_split() H [1] => e [2] => l [3] => l [4] => o [5] => [6] => F [7] => r [8] => i [9] => e [10] => n [11] => d ) Array ( [0] [1] [2] [3] ) */ ?> => => => => Hel lo Fri end Example 845. Examples related to str_split() See also preg_split(), split(), count_chars(), str_word_count(), and for. 3482 str_word_count (PHP 4 >= 4.3.0) str_word_count - Return information about words used in a string Description mixed str_word_count (string string [, int format]) Counts the number of words inside string. If the optional format is not specified, then the return value will be an integer representing the number of words found. In the event the format is specified, the return value will be an array, content of which is dependent on the format. The possible value for the format and the resultant outputs are listed below. • 1 - returns an array containing all the words found inside the string. • 2 - returns an associative array, where the key is the numeric position of the word inside the string and the value is the actual word itself. For the purpose of this function, 'word' is defined as a locale dependent string containing alphabetic characters, which also may contain, but not start with "'" and "-" characters. Example 846. Example uses for str_word_count() => => => => => Hello friend you're looking good today Array ( [0] => Hello [6] => friend [14] => you're [29] => looking [46] => good [51] => today ) 6 3483 str_word_count */ ?> See also explode(), preg_split(), split(), count_chars(), and substr_count(). 3484 strcasecmp (PHP 3>= 3.0.2, PHP 4 ) strcasecmp - Binary safe case-insensitive string comparison Description int strcasecmp (string str1, string str2) Returns < 0 if str1 is less than str2; > 0 if str1 is greater than str2, and 0 if they are equal. Example 847. strcasecmp() example See also ereg(), strcmp(), substr(), stristr(), strncasecmp(), and strstr(). 3485 strchr (PHP 3, PHP 4 ) strchr - Alias for strstr() Description This function is an alias of strstr(). 3486 strcmp (PHP 3, PHP 4 ) strcmp - Binary safe string comparison Description int strcmp (string str1, string str2) Returns < 0 if str1 is less than str2; > 0 if str1 is greater than str2, and 0 if they are equal. Note that this comparison is case sensitive. See also ereg(), strcasecmp(), substr(), stristr(), strncasecmp(), strncmp(), and strstr(). 3487 strcoll (PHP 4 >= 4.0.5) strcoll - Locale based string comparison Description int strcoll (string str1, string str2) Returns < 0 if str1 is less than str2; > 0 if str1 is greater than str2, and 0 if they are equal. strcoll() uses the current locale for doing the comparisons. If the current locale is C or POSIX, this function is equivalent to strcmp(). Note that this comparison is case sensitive, and unlike strcmp() this function is not binary safe. Note: strcoll() was added in PHP 4.0.5, but was not enabled for win32 until 4.2.3. See also ereg(), strcmp(), strcasecmp(), substr(), stristr(), strncasecmp(), strncmp(), strstr(), and setlocale(). 3488 strcspn (PHP 3>= 3.0.3, PHP 4 ) strcspn - Find length of initial segment not matching mask Description int strcspn (string str1, string str2) Returns the length of the initial segment of str1 which does not contain any of the characters in str2. See also strspn(). 3489 strip_tags (PHP 3>= 3.0.8, PHP 4 ) strip_tags - Strip HTML and PHP tags from a string Description string strip_tags (string str [, string allowable_tags]) This function tries to return a string with all HTML and PHP tags stripped from a given str. It errors on the side of caution in case of incomplete or bogus tags. It uses the same tag stripping state machine as the fgetss() function. You can use the optional second parameter to specify tags which should not be stripped. Note: allowable_tags was added in PHP 3.0.13 and PHP 4.0b3. Example 848. strip_tags() example '); ?> Warning This function does not modify any attributes on the tags that you allow using allowable_tags, including the style and onmouseover attributes that a mischievous user may abuse when posting text that will be shown to other users. 3490 stripcslashes (PHP 4 ) stripcslashes - Un-quote string quoted with addcslashes() Description string stripcslashes (string str) Returns a string with backslashes stripped off. Recognizes C-like \n, \r ..., octal and hexadecimal representation. See also addcslashes(). 3491 stripos (PHP 5 CVS only) stripos - Find position of first occurrence of a case-insensitive string Description int stripos (string haystack, string needle [, int offset]) Returns the numeric position of the first occurrence of needle in the haystack string. Unlike strpos(), stripos() is caseinsensitive. And unlike strrpos(), this function can take a full string as the needle parameter and the entire string will be used. If needle is not found, strpos() will return boolean FALSE. Warning This function may return Boolean FALSE, but may also return a non-Boolean value which evaluates to FALSE, such as 0 or "". Please read the section on Booleans for more information. Use the === operator for testing the return value of this function. Example 849. stripos() examples If needle is not a string, it is converted to an integer and applied as the ordinal value of a character. The optional offset parameter allows you to specify which character in haystack to start searching. The position returned is still relative to the the beginning of haystack. See also strpos(), strrpos(), strrchr(), substr(), stristr(), strstr() and stri_replace(). 3492 stripslashes (PHP 3, PHP 4 ) stripslashes - Un-quote string quoted with addslashes() Description string stripslashes (string str) Returns a string with backslashes stripped off. (\' becomes ' and so on.) Double backslashes are made into a single backslash. See also addslashes(). 3493 stristr (PHP 3>= 3.0.6, PHP 4 ) stristr - Case-insensitive strstr() Description string stristr (string haystack, string needle) Returns all of haystack from the first occurrence of needle to the end. needle and haystack are examined in a case-insensitive manner. If needle is not found, returns FALSE. If needle is not a string, it is converted to an integer and applied as the ordinal value of a character. Example 850. stristr() example See also strchr(), strrchr(), substr(), and ereg(). 3494 strlen (PHP 3, PHP 4 ) strlen - Get string length Description int strlen (string str) Returns the length of string. 3495 strnatcasecmp (PHP 4 ) strnatcasecmp - Case insensitive string comparisons using a "natural order" algorithm Description int strnatcasecmp (string str1, string str2) This function implements a comparison algorithm that orders alphanumeric strings in the way a human being would. The behaviour of this function is similar to strnatcmp(), except that the comparison is not case sensitive. For more infomation see: Martin Pool's Natural Order String Comparison [http://naturalordersort.org/] page. Similar to other string comparison functions, this one returns < 0 if str1 is less than str2; > 0 if str1 is greater than str2, and 0 if they are equal. See also ereg(), strcasecmp(), substr(), stristr(), strcmp(), strncmp(), strncasecmp(), strnatcmp(), and strstr(). 3496 strnatcmp (PHP 4 ) strnatcmp - String comparisons using a "natural order" algorithm Description int strnatcmp (string str1, string str2) This function implements a comparison algorithm that orders alphanumeric strings in the way a human being would, this is described as a "natural ordering". An example of the difference between this algorithm and the regular computer string sorting algorithms (used in strcmp()) can be seen below: The code above will generate the following output: Standard string comparison Array ( [0] => img1.png [1] => img10.png [2] => img12.png [3] => img2.png ) Natural Array ( [0] [1] [2] [3] ) order string comparison => => => => img1.png img2.png img10.png img12.png For more information see: Martin Pool's Natural Order String Comparison [http://naturalordersort.org/] page. Similar to other string comparison functions, this one returns < 0 if str1 is less than str2; > 0 if str1 is greater than str2, and 0 if they are equal. Note that this comparison is case sensitive. See also ereg(), strcasecmp(), substr(), stristr(), strcmp(), strncmp(), strncasecmp(), strnatcasecmp(), strstr(), natsort() and natcasesort(). 3497 strncasecmp (PHP 4 >= 4.0.2) strncasecmp - Binary safe case-insensitive string comparison of the first n characters Description int strncasecmp (string str1, string str2, int len) This function is similar to strcasecmp(), with the difference that you can specify the (upper limit of the) number of characters (len) from each string to be used in the comparison. If any of the strings is shorter than len, then the length of that string will be used for the comparison. Returns < 0 if str1 is less than str2; > 0 if str1 is greater than str2, and 0 if they are equal. See also ereg(), strcasecmp(), strcmp(), substr(), stristr(), and strstr(). 3498 strncmp (PHP 4 ) strncmp - Binary safe string comparison of the first n characters Description int strncmp (string str1, string str2, int len) This function is similar to strcmp(), with the difference that you can specify the (upper limit of the) number of characters (len) from each string to be used in the comparison. If any of the strings is shorter than len, then the length of that string will be used for the comparison. Returns < 0 if str1 is less than str2; > 0 if str1 is greater than str2, and 0 if they are equal. Note that this comparison is case sensitive. See also ereg(), strncasecmp(), strcasecmp(), substr(), stristr(), strcmp(), and strstr(). 3499 strpos (PHP 3, PHP 4 ) strpos - Find position of first occurrence of a string Description int strpos (string haystack, string needle [, int offset]) Returns the numeric position of the first occurrence of needle in the haystack string. Unlike the strrpos(), this function can take a full string as the needle parameter and the entire string will be used. If needle is not found, strpos() will return boolean FALSE. Warning This function may return Boolean FALSE, but may also return a non-Boolean value which evaluates to FALSE, such as 0 or "". Please read the section on Booleans for more information. Use the === operator for testing the return value of this function. Example 851. strpos() examples If needle is not a string, it is converted to an integer and applied as the ordinal value of a character. The optional offset parameter allows you to specify which character in haystack to start searching. The position returned is still relative to the the beginning of haystack. See also strrpos(), stripos(), strripos(), strrchr(), substr(), stristr(), and strstr(). 3500 strrchr (PHP 3, PHP 4 ) strrchr - Find the last occurrence of a character in a string Description string strrchr (string haystack, string needle) This function returns the portion of haystack which starts at the last occurrence of needle and goes until the end of haystack. Returns FALSE if needle is not found. If needle contains more than one character, the first is used. If needle is not a string, it is converted to an integer and applied as the ordinal value of a character. Example 852. strrchr() example See also strchr(), substr(), stristr(), and strstr(). 3501 strrev (PHP 3, PHP 4 ) strrev - Reverse a string Description string strrev (string string) Returns string, reversed. Example 853. Reversing a string with strrev() 3502 strripos (PHP 5 CVS only) strripos - Find position of last occurrence of a case-insensitive string in a string Description int strripos (string haystack, string needle) Returns the numeric position of the last occurrence of needle in the haystack string. Unlike strrpos(), strripos() is caseinsensitive. Also note that string positions start at 0, and not 1. If needle is not found, FALSE is returned. Warning This function may return Boolean FALSE, but may also return a non-Boolean value which evaluates to FALSE, such as 0 or "". Please read the section on Booleans for more information. Use the === operator for testing the return value of this function. Example 854. A simple strripos() example See also strrpos(), strrchr(), substr(), and stristr(). 3503 strrpos (PHP 3, PHP 4 ) strrpos - Find position of last occurrence of a char in a string Description int strrpos (string haystack, char needle) Returns the numeric position of the last occurrence of needle in the haystack string. Note that the needle in this case can only be a single character. If a string is passed as the needle, then only the first character of that string will be used. If needle is not found, returns FALSE. Note: It is easy to mistake the return values for "character found at position 0" and "character not found". Here's how to detect the difference: // in PHP 4.0b3 and newer: $pos = strrpos($mystring, "b"); if ($pos === false) { // note: three equal signs // not found... } // in versions older than 4.0b3: $pos = strrpos($mystring, "b"); if (is_string($pos) && !$pos) { // not found... } If needle is not a string, it is converted to an integer and applied as the ordinal value of a character. See also strpos(), strripos(), strrchr(), substr(), stristr(), and strstr(). 3504 strspn (PHP 3>= 3.0.3, PHP 4 ) strspn - Find length of initial segment matching mask Description int strspn (string str1, string str2) Returns the length of the initial segment of str1 which consists entirely of characters in str2. The line of code: will assign 2 to $var, because the string "42" will be the longest segment containing characters from "1234567890". See also strcspn(). 3505 strstr (PHP 3, PHP 4 ) strstr - Find first occurrence of a string Description string strstr (string haystack, string needle) Returns part of haystack string from the first occurrence of needle to the end of haystack. If needle is not found, returns FALSE. If needle is not a string, it is converted to an integer and applied as the ordinal value of a character. Note: This function is case-sensitive. For case-insensitive searches, use stristr(). Example 855. strstr() example Note: If you only want to determine if a particular needle occurs within haystack, use the faster and less memory intensive function strpos() instead. See also ereg(), preg_match(), strchr(), stristr(), strpos(), strrchr(), and substr(). 3506 strtok (PHP 3, PHP 4 ) strtok - Tokenize string Description string strtok (string arg1, string arg2) strtok() splits a string (arg1) into smaller strings (tokens), with each token being delimited by any character from arg2. That is, if you have a string like "This is an example string" you could tokenize this string into its individual words by using the space character as the token. Example 856. strtok() example "; $tok = strtok(" \n\t"); } ?> */ Note that only the first call to strtok uses the string argument. Every subsequent call to strtok only needs the token to use, as it keeps track of where it is in the current string. To start over, or to tokenize a new string you simply call strtok with the string argument again to initialize it. Note that you may put multiple tokens in the token parameter. The string will be tokenized when any one of the characters in the argument are found. The behavior when an empty part was found changed with PHP 4.1.0. The old behavior returned an empty string, while the new, correct, behavior simply skips the part of the string: Example 857. Old strtok() behavior Example 858. New strtok() behavior Also be careful that your tokens may be equal to "0". This evaluates to FALSE in conditional expressions. See also split() and explode(). 3508 strtolower (PHP 3, PHP 4 ) strtolower - Make a string lowercase Description string strtolower (string str) Returns string with all alphabetic characters converted to lowercase. Note that 'alphabetic' is determined by the current locale. This means that in i.e. the default "C" locale, characters such as umlaut-A (Ä) will not be converted. Example 859. strtolower() example See also strtoupper(), ucfirst(), and ucwords(). 3509 strtoupper (PHP 3, PHP 4 ) strtoupper - Make a string uppercase Description string strtoupper (string string) Returns string with all alphabetic characters converted to uppercase. Note that 'alphabetic' is determined by the current locale. For instance, in the default "C" locale characters such as umlaut-a (ä) will not be converted. Example 860. strtoupper() example See also strtolower(), ucfirst(), and ucwords(). 3510 strtr (PHP 3, PHP 4 ) strtr - Translate certain characters Description string strtr (string str, string from, string to) string strtr (string str, array replace_pairs) This function returns a copy of str, translating all occurrences of each character in from to the corresponding character in to and returning the result. If from and to are different lengths, the extra characters in the longer of the two are ignored. Example 861. strtr() example strtr() may be called with only two arguments. If called with two arguments it behaves in a new way: from then has to be an array that contains string -> string pairs that will be replaced in the source string. strtr() will always look for the longest possible match first and will *NOT* try to replace stuff that it has already worked on. Example 862. strtr() example with two arguments "hi", "hi" => "hello"); echo strtr("hi all, I said hello", $trans); ?> This will show: hello all, I said hi Note: This optional to and from parameters were added in PHP 4.0.0 See also ereg_replace(). 3511 substr_count (PHP 4 ) substr_count - Count the number of substring occurrences Description int substr_count (string haystack, string needle) substr_count() returns the number of times the needle substring occurs in the haystack string. Example 863. substr_count() example See also count_chars(), strpos(), substr(), and strstr(). 3512 substr_replace (PHP 4 ) substr_replace - Replace text within a portion of a string Description string substr_replace (string string, string replacement, int start [, int length]) substr_replace() replaces a copy of string delimited by the start and (optionally) length parameters with the string given in replacement. The result is returned. If start is positive, the replacing will begin at the start'th offset into string. If start is negative, the replacing will begin at the start'th character from the end of string. If length is given and is positive, it represents the length of the portion of string which is to be replaced. If it is negative, it represents the number of characters from the end of string at which to stop replacing. If it is not given, then it will default to strlen( string ); i.e. end the replacing at the end of string. Example 864. substr_replace() example \n"; /* These two examples replace all of $var with 'bob'. */ echo substr_replace($var, 'bob', 0) . "
\n"; echo substr_replace($var, 'bob', 0, strlen($var)) . "
\n"; /* Insert 'bob' right at the beginning of $var. */ echo substr_replace($var, 'bob', 0, 0) . "
\n"; /* These next two replace 'MNRPQR' in $var with 'bob'. */ echo substr_replace($var, 'bob', 10, -1) . "
\n"; echo substr_replace($var, 'bob', -7, -1) . "
\n"; /* Delete 'MNRPQR' from $var. */ echo substr_replace($var, '', 10, -1) . "
\n"; ?> See also str_replace() and substr(). 3513 substr (PHP 3, PHP 4 ) substr - Return part of a string Description string substr (string string, int start [, int length]) substr() returns the portion of string specified by the start and length parameters. If start is non-negative, the returned string will start at the start'th position in string, counting from zero. For instance, in the string 'abcdef', the character at position 0 is 'a', the character at position 2 is 'c', and so forth. Example 865. Basic substr() usage If start is negative, the returned string will start at the start'th character from the end of string. Example 866. Using a negative start If length is given and is positive, the string returned will contain at most length characters beginning from start (depending on the length of string). If string is less than start characters long, FALSE will be returned. If length is given and is negative, then that many characters will be omitted from the end of string (after the start position has been calculated when a start is negative). If start denotes a position beyond this truncation, an empty string will be returned. Example 867. Using a negative length = = = = substr("abcdef", substr("abcdef", substr("abcdef", substr("abcdef", 0, -1); 2, -1); 4, -4); -3, -1); // // // // returns returns returns returns "abcde" "cde" "" "de" 3514 substr See also strrchr() and ereg(). 3515 trim (PHP 3, PHP 4 ) trim - Strip whitespace from the beginning and end of a string Description string trim (string str [, string charlist]) Note: The optional charlist parameter was added in PHP 4.1.0 This function returns a string with whitespace stripped from the beginning and end of str. Without the second parameter, trim() will strip these characters: • " " (ASCII 32 (0x20)), an ordinary space. • "\t" (ASCII 9 (0x09)), a tab. • "\n" (ASCII 10 (0x0A)), a new line (line feed). • "\r" (ASCII 13 (0x0D)), a carriage return. • "\0" (ASCII 0 (0x00)), the NUL-byte. • "\x0B" (ASCII 11 (0x0B)), a vertical tab. You can also specify the characters you want to strip, by means of the charlist parameter. Simply list all characters that you want to be stripped. With .. you can specify a range of characters. Example 868. Usage example of trim() See also ltrim() and rtrim(). 3516 ucfirst (PHP 3, PHP 4 ) ucfirst - Make a string's first character uppercase Description string ucfirst (string str) Returns a string with the first character of str capitalized, if that character is alphabetic. Note that 'alphabetic' is determined by the current locale. For instance, in the default "C" locale characters such as umlaut-a (ä) will not be converted. Example 869. ucfirst() example See also strtolower(), strtoupper(), and ucwords(). 3517 ucwords (PHP 3>= 3.0.3, PHP 4 ) ucwords - Uppercase the first character of each word in a string Description string ucwords (string str) Returns a string with the first character of each word in str capitalized, if that character is alphabetic. Example 870. ucwords() example Note: The definition of a word is any string of characters that is immediately after a whitespace (These are: space, form-feed, newline, carriage return, horizontal tab, and vertical tab). See also strtoupper(), strtolower() and ucfirst(). 3518 vprintf (PHP 4 >= 4.1.0) vprintf - Output a formatted string Description void vprintf (string format, array args) Display array values as a formatted string according to format (which is described in the documentation for sprintf()). Operates as printf() but accepts an array of arguments, rather than a variable number of arguments. See also printf(), sprintf(), vsprintf() 3519 vsprintf (PHP 4 >= 4.1.0) vsprintf - Return a formatted string Description string vsprintf (string format, array args) Return array values as a formatted string according to format (which is described in the documentation for sprintf()). Operates as sprintf() but accepts an array of arguments, rather than a variable number of arguments. See also sprintf() and vprintf() 3520 wordwrap (PHP 4 >= 4.0.2) wordwrap - Wraps a string to a given number of characters using a string break character. Description string wordwrap (string str [, int width [, string break [, boolean cut]]]) Returns a string with str wrapped at the column number specified by the optional width parameter. The line is broken using the (optional) break parameter. wordwrap() will automatically wrap at column 75 and break using '\n' (newline) if width or break are not given. If the cut is set to 1, the string is always wrapped at the specified width. So if you have a word that is larger than the given width, it is broken apart. (See second example). Note: The optional cut parameter was added in PHP 4.0.3 Example 871. wordwrap() example This example would display: The quick brown fox jumped over the lazy dog. Example 872. wordwrap() example This example would display: A very long wooooooo ooooord. 3521 wordwrap See also nl2br(). 3522 Sybase functions Table of Contents sybase_affected_rows ....................................................................................................................... 3527 sybase_close ................................................................................................................................... 3528 sybase_connect ................................................................................................................................ 3529 sybase_data_seek ............................................................................................................................. 3530 sybase_deadlock_retry_count ............................................................................................................. 3531 sybase_fetch_array ........................................................................................................................... 3532 sybase_fetch_assoc ........................................................................................................................... 3533 sybase_fetch_field ............................................................................................................................ 3534 sybase_fetch_object .......................................................................................................................... 3535 sybase_fetch_row ............................................................................................................................. 3536 sybase_field_seek ............................................................................................................................ 3537 sybase_free_result ............................................................................................................................ 3538 sybase_get_last_message ................................................................................................................... 3539 sybase_min_client_severity ................................................................................................................ 3540 sybase_min_error_severity ................................................................................................................. 3541 sybase_min_message_severity ............................................................................................................ 3542 sybase_min_server_severity ............................................................................................................... 3543 sybase_num_fields ........................................................................................................................... 3544 sybase_num_rows ............................................................................................................................ 3545 sybase_pconnect .............................................................................................................................. 3546 sybase_query ................................................................................................................................... 3547 sybase_result ................................................................................................................................... 3548 sybase_select_db .............................................................................................................................. 3549 sybase_set_message_handler .............................................................................................................. 3550 sybase_unbuffered_query .................................................................................................................. 3551 3523 Introduction Requirements Installation To enable Sybase-DB support configure PHP --with-sybase[=DIR]. DIR is the Sybase home directory, defaults to / home/sybase. To enable Sybase-CT support configure PHP --with-sybase-ct[=DIR]. DIR is the Sybase home directory, defaults to /home/sybase. Runtime Configuration The behaviour of these functions is affected by settings in php.ini. Table 167. Sybase configuration options Name Default Changeable sybase.allow_persistent "On" PHP_INI_SYSTEM sybase.max_persistent "-1" PHP_INI_SYSTEM sybase.max_links "-1" PHP_INI_SYSTEM sybase.interface_file "/usr/sybase/interfaces" PHP_INI_SYSTEM sybase.min_error_severity "10" PHP_INI_ALL sybase.min_message_severity "10" PHP_INI_ALL sybase.compatability_mode "Off" PHP_INI_SYSTEM magic_quotes_sybase "Off" PHP_INI_ALL Here's a short explanation of the configuration directives. sybase.allow_persistent boolean Whether to allow persistent Sybase connections. sybase.max_persistent integer The maximum number of persistent Sybase connections per process. -1 means no limit. sybase.max_links integer The maximum number of Sybase connections per process, including persistent connections. -1 means no limit. sybase.min_error_severity integer Minimum error severity to display. sybase.min_message_severity integer Minimum message severity to display. sybase.compatability_mode boolean Compatability mode with old versions of PHP 3.0. If on, this will cause PHP to automatically assign types to results according to their Sybase type, instead of treating them all as strings. This compatability mode will probably not stay 3524 Sybase functions around forever, so try applying whatever necessary changes to your code, and turn it off. magic_quotes_sybase boolean If magic_quotes_sybase is on, a single-quote is escaped with a single-quote instead of a backslash if magic_quotes_gpc or magic_quotes_runtime are enabled. Note: Note that when magic_quotes_sybase is ON it completely overrides magic_quotes_gpc . In this case even when magic_quotes_gpc is enabled neither double quotes, backslashes or NUL's will be escaped. Table 168. Sybase-CT configuration options Name Default Changeable sybct.allow_persistent "On" PHP_INI_SYSTEM sybct.max_persistent "-1" PHP_INI_SYSTEM sybct.max_links "-1" PHP_INI_SYSTEM sybct.min_server_severity "10" PHP_INI_ALL sybct.min_client_severity "10" PHP_INI_ALL sybct.hostname NULL PHP_INI_ALL sybct.deadlock_retry_count "-1" PHP_INI_ALL Here's a short explanation of the configuration directives. sybct.allow_persistent boolean Whether to allow persistent Sybase-CT connections. The default is on. sybct.max_persistent integer The maximum number of persistent Sybase-CT connections per process. The default is -1 meaning unlimited. sybct.max_links integer The maximum number of Sybase-CT connections per process, including persistent connections. The default is -1 meaning unlimited. sybct.min_server_severity integer Server messages with severity greater than or equal to sybct.min_server_severity will be reported as warnings. This value can also be set from a script by calling sybase_min_server_severity(). The default is 10 which reports errors of information severity or greater. sybct.min_client_severity integer Client library messages with severity greater than or equal to sybct.min_client_severity will be reported as warnings. This value can also be set from a script by calling sybase_min_client_severity(). The default is 10 which effectively disables reporting. sybct.hostname string The name of the host you claim to be connecting from, for display by sp_who. The default is none. sybct.deadlock_retry_count int Allows you to to define how often deadlocks are to be retried. The default is -1, or "forever". For further details and definition of the PHP_INI_* constants see ini_set(). 3525 Sybase functions Resource Types Predefined Constants This extension has no constants defined. 3526 sybase_affected_rows (PHP 3>= 3.0.6, PHP 4 ) sybase_affected_rows - get number of affected rows in last query Description int sybase_affected_rows ([int link_identifier]) Returns: The number of affected rows by the last query. sybase_affected_rows() returns the number of rows affected by the last INSERT, UPDATE or DELETE query on the server associated with the specified link identifier. If the link identifier isn't specified, the last opened link is assumed. This command is not effective for SELECT statements, only on statements which modify records. To retrieve the number of rows returned from a SELECT, use sybase_num_rows(). Note: This function is only available using the CT library interface to Sybase, and not the DB library. 3527 sybase_close (PHP 3, PHP 4 ) sybase_close - close Sybase connection Description bool sybase_close ([int link_identifier]) sybase_close() closes the link to a Sybase database that's associated with the specified link link_identifier. If the link identifier isn't specified, the last opened link is assumed. Returns TRUE on success or FALSE on failure. Note that this isn't usually necessary, as non-persistent open links are automatically closed at the end of the script's execution. sybase_close() will not close persistent links generated by sybase_pconnect(). See also: sybase_connect(), sybase_pconnect(). 3528 sybase_connect (PHP 3, PHP 4 ) sybase_connect - open Sybase server connection Description int sybase_connect (string servername, string username, string password [, string charset]) Returns: A positive Sybase link identifier on success, or FALSE on error. sybase_connect() establishes a connection to a Sybase server. The servername argument has to be a valid servername that is defined in the 'interfaces' file. In case a second call is made to sybase_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 sybase_close(). See also sybase_pconnect(), sybase_close(). 3529 sybase_data_seek (PHP 3, PHP 4 ) sybase_data_seek - move internal row pointer Description bool sybase_data_seek (int result_identifier, int row_number) Returns: TRUE on success, FALSE on failure sybase_data_seek() moves the internal row pointer of the Sybase result associated with the specified result identifier to pointer to the specifyed row number. The next call to sybase_fetch_row() would return that row. See also: sybase_data_seek(). 3530 sybase_deadlock_retry_count (PHP 4 >= 4.3.0) sybase_deadlock_retry_count - set the deadlock retry count Description void sybase_deadlock_retry_count (int retry_count) Using sybase_deadlock_retry_count(), the number of retries can be defined in cases of deadlocks. By default, every deadlock is retried an infinite number of times or until the process is killed by Sybase, the executing script is killed (for instance, by set_time_limit()) or the query succeeds. Table 169. Values for retry_count -1 Retry forever (default) 0 Do not retry n Retry n times Note: This function is only available using the CT library interface to Sybase, and not the DB library. 3531 sybase_fetch_array (PHP 3, PHP 4 ) sybase_fetch_array - fetch row as array Description array sybase_fetch_array (int result) Returns: An array that corresponds to the fetched row, or FALSE if there are no more rows. sybase_fetch_array() is an extended version of sybase_fetch_row(). In addition to storing the data in the numeric indices of the result array, it also stores the data in associative indices, using the field names as keys. An important thing to note is that using sybase_fetch_array() is NOT significantly slower than using sybase_fetch_row(), while it provides a significant added value. Note: When selecting fields with identical names (for instance, in a join), the associative indices will have a sequential number prepended. See the example for details. Example 873. Identical fieldnames The above example would produce the following output (assuming the two tables only have each one column called "person_id"): array(4) { [0]=> int(1) ["person_id"]=> int(1) [1]=> int(1) ["person_id1"]=> int(1) } For further details, also see sybase_fetch_row(), sybase_fetch_assoc() and sybase_fetch_object(). 3532 sybase_fetch_assoc (PHP 4 >= 4.3.0) sybase_fetch_assoc - fetch row as associative array Description array sybase_fetch_assoc (resource result) Returns: An array that corresponds to the fetched row, or FALSE if there are no more rows. sybase_fetch_assoc() is a version of sybase_fetch_row() that uses column names instead of integers for indices in the result array. Columns from different tables with the same names are returned as name, name1, name2, ..., nameN. An important thing to note is that using sybase_fetch_assoc() is NOT significantly slower than using sybase_fetch_row(), while it provides a significant added value. See also sybase_fetch_array(), sybase_fetch_object(), and sybase_fetch_row(). 3533 sybase_fetch_field (PHP 3, PHP 4 ) sybase_fetch_field - get field information Description object sybase_fetch_field (int result [, int field_offset]) Returns an object containing field information. sybase_fetch_field() can be used in order to obtain information about fields in a certain query result. If the field offset isn't specified, the next field that wasn't yet retreived by sybase_fetch_field() is retreived. The properties of the object are: • name - column name. if the column is a result of a function, this property is set to computed#N, where #N is a serial number. • column_source - the table from which the column was taken • max_length - maximum length of the column • numeric - 1 if the column is numeric • type - datatype of the column See also sybase_field_seek() 3534 sybase_fetch_object (PHP 3, PHP 4 ) sybase_fetch_object - fetch row as object Description int sybase_fetch_object (int result [, mixed object]) Returns: An object with properties that correspond to the fetched row, or FALSE if there are no more rows. sybase_fetch_object() is similar to sybase_fetch_assoc(), with one difference - an object is returned, instead of an array. Use the second object to specify the type of object you want to return. If this parameter is omitted, the object will be of type stdClass. Note: As of PHP 4.3.0, this function will no longer return numeric object members. Old behaviour: object(stdclass)(3) { [0]=> string(3) "foo" ["foo"]=> string(3) "foo" [1]=> string(3) "bar" ["bar"]=> string(3) "bar" } New behaviour: object(stdclass)(3) { ["foo"]=> string(3) "foo" ["bar"]=> string(3) "bar" } Example 874. sybase_fetch_object() return as Foo Speed-wise, the function is identical to sybase_fetch_array(), and almost as quick as sybase_fetch_row() (the difference is insignificant). See also sybase_fetch_array(), and sybase_fetch_row(). 3535 sybase_fetch_row (PHP 3, PHP 4 ) sybase_fetch_row - get row as enumerated array Description array sybase_fetch_row (int result) Returns: An array that corresponds to the fetched row, or FALSE if there are no more rows. sybase_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 sybase_fetch_row() would return the next row in the result set, or FALSE if there are no more rows. Table 170. Data types PHP Sybase string VARCHAR, TEXT, CHAR, IMAGE, BINARY, VARBINARY, DATETIME int NUMERIC (w/o precision), DECIMAL (w/o precision), INT, BIT, TINYINT, SMALLINT float NUMERIC (w/ precision), DECIMAL (w/ precision), REAL, FLOAT, MONEY NULL NULL See also: sybase_fetch_array(), sybase_fetch_assoc(), base_fetch_lengths(), and sybase_result(). 3536 sybase_fetch_object(), sybase_data_seek(), sy- sybase_field_seek (PHP 3, PHP 4 ) sybase_field_seek - set field offset Description int sybase_field_seek (int result, int field_offset) Seeks to the specified field offset. If the next call to sybase_fetch_field() won't include a field offset, this field would be returned. See also: sybase_fetch_field(). 3537 sybase_free_result (PHP 3, PHP 4 ) sybase_free_result - free result memory Description bool sybase_free_result (int result) sybase_free_result() only needs to be called if you are worried about using too much memory while your script is running. All result memory will automatically be freed when the script ends. You may call sybase_free_result() with the result identifier as an argument and the associated result memory will be freed. 3538 sybase_get_last_message (PHP 3, PHP 4 ) sybase_get_last_message - Returns the last message from the server Description string sybase_get_last_message (void) sybase_get_last_message() returns the last message reported by the server. 3539 sybase_min_client_severity (PHP 3, PHP 4 ) sybase_min_client_severity - Sets minimum client severity Description void sybase_min_client_severity (int severity) sybase_min_client_severity() sets the minimum client severity level. Note: This function is only available using the CT library interface to Sybase, and not the DB library. See also: sybase_min_server_severity(). 3540 sybase_min_error_severity (PHP 3, PHP 4 ) sybase_min_error_severity - Sets minimum error severity Description void sybase_min_error_severity (int severity) sybase_min_error_severity() sets the minimum error severity level. See also: sybase_min_message_severity(). 3541 sybase_min_message_severity (PHP 3, PHP 4 ) sybase_min_message_severity - Sets minimum message severity Description void sybase_min_message_severity (int severity) sybase_min_message_severity() sets the minimum message severity level. See also: sybase_min_error_severity(). 3542 sybase_min_server_severity (PHP 3, PHP 4 ) sybase_min_server_severity - Sets minimum server severity Description void sybase_min_server_severity (int severity) sybase_min_server_severity() sets the minimum server severity level. Note: This function is only available using the CT library interface to Sybase, and not the DB library. See also: sybase_min_client_severity(). 3543 sybase_num_fields (PHP 3, PHP 4 ) sybase_num_fields - get number of fields in result Description int sybase_num_fields (int result) sybase_num_fields() returns the number of fields in a result set. See also: sybase_db_query(), sybase_query(), sybase_fetch_field(), sybase_num_rows(). 3544 sybase_num_rows (PHP 3, PHP 4 ) sybase_num_rows - Get number of rows in result Description int sybase_num_rows (int result) sybase_num_rows() returns the number of rows in a result set. See also sybase_db_query(), sybase_query(), and sybase_fetch_row(). 3545 sybase_pconnect (PHP 3, PHP 4 ) sybase_pconnect - open persistent Sybase connection Description int sybase_pconnect (string servername, string username, string password [, string charset]) Returns: A positive Sybase persistent link identifier on success, or FALSE on error sybase_pconnect() acts very much like sybase_connect() with two major differences. 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 (sybase_close() will not close links established by sybase_pconnect()()). This type of links is therefore called 'persistent'. 3546 sybase_query (PHP 3, PHP 4 ) sybase_query - Send Sybase query Description int sybase_query (string query, int link_identifier) Returns: A positive Sybase result identifier on success, or FALSE on error. sybase_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 sybase_connect() was called, and use it. See also sybase_db_query(), sybase_select_db(), and sybase_connect(). 3547 sybase_result (PHP 3, PHP 4 ) sybase_result - get result data Description string sybase_result (int result, int row, mixed field) Returns: The contents of the cell at the row and offset in the specified Sybase result set. sybase_result() returns the contents of one cell from a Sybase result set. The field argument can be the field's offset, or the field's name, or the field's table dot field's name (tablename.fieldname). If the column name has been aliased ('select foo as bar from...'), use the alias instead of the column name. When working on large result sets, you should consider using one of the functions that fetch an entire row (specified below). As these functions return the contents of multiple cells in one function call, they're MUCH quicker than sybase_result(). Also, note that specifying a numeric offset for the field argument is much quicker than specifying a fieldname or tablename.fieldname argument. Recommended high-performance alternatives: sybase_fetch_row(), sybase_fetch_array(), and sybase_fetch_object(). 3548 sybase_select_db (PHP 3, PHP 4 ) sybase_select_db - select Sybase database Description bool sybase_select_db (string database_name, int link_identifier) sybase_select_db() sets the current active database on the server that's associated with the specified link identifier. If no link identifier is specified, the last opened link is assumed. If no link is open, the function will try to establish a link as if sybase_connect() was called, and use it. Returns TRUE on success or FALSE on failure. Every subsequent call to sybase_query() will be made on the active database. See also: sybase_connect(), sybase_pconnect(), and sybase_query() 3549 sybase_set_message_handler (PHP 4 >= 4.3.0) sybase_set_message_handler - set handler called when a server message is raised Description bool sybase_set_message_handler (callback handler) sybase_set_message_handler() sets a user function to handle messages generated by the server. You may specify the name of a global function, or use an array to specify an object reference and a method name. The handler expects five arguments in the following order: message number, severity, state, line number and description. The first four are integers. The last is a string. If the function returns FALSE, PHP generates an ordinary error message. Returns TRUE on success or FALSE on failure. Example 875. sybase_set_message_handler() callback function Example 876. sybase_set_message_handler() callback to a class Example 877. sybase_set_message_handler() unhandled messages 3550 sybase_unbuffered_query (PHP 4 >= 4.3.0) sybase_unbuffered_query - send Sybase query and do not block Description resource sybase_unbuffered_query (string query, int link_identifier) Returns: A positive Sybase result identifier on success, or FALSE on error. sybase_unbuffered_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 sybase_connect() was called, and use it. Unlike sybase_query(), sybase_unbuffered_query() reads only the first row of the result set. sybase_fetch_array() and similar function read more rows as needed. sybase_data_seek() reads up to the target row. The behavior may produce better performance for large result sets. sybase_num_rows() will only return the correct number of rows if all result sets have been read. To Sybase, the number of rows is not known and is therefore computed by the client implementation. Note: If you don't read all of the resultsets prior to executing the next query, PHP will raise a warning and cancel all of the pending results. To get rid of this, use sybase_free_result() which will cancel pending results of an unbuffered query. The optional store_result can be FALSE to indicate the resultsets should'nt be fetched into memory, thus minimizing memory usage which is particularily interesting with very large resultsets. Example 878. sybase_unbuffered_query() 40000) break; } sybase_free_result($q); sybase_close($dbh); ?> 3551 Tokenizer functions Table of Contents token_get_all ................................................................................................................................... 3558 token_name .................................................................................................................................... 3559 3552 Introduction The tokenizer functions provide an interface to the PHP tokenizer embedded in the Zend Engine. Using these functions you may write your own PHP source analyzation or modification tools without having to deal with the language specification at the lexical level. See also the appendix about tokens. Requirements No external libraries are needed to build this extension. Installation Beginning with PHP 4.3.0 these functions are enabled by default. For older versions you have to configure and compile PHP with --enable-tokenizer. You can disable tokenizer support with --disable-tokenizer. The windows version of PHP has built in support for this extension. You do not need to load any additional extension in order to use these functions. Note: Builtin support for tokenizer is available with PHP 4.3.0. Predefined Constants The constants below are defined by this extension, and will only be available when the extension has either been compiled into PHP or dynamically loaded at runtime. T_INCLUDE (integer) T_INCLUDE_ONCE (integer) T_EVAL (integer) T_REQUIRE (integer) T_REQUIRE_ONCE (integer) T_LOGICAL_OR (integer) T_LOGICAL_XOR (integer) T_LOGICAL_AND (integer) T_PRINT (integer) T_PLUS_EQUAL (integer) T_MINUS_EQUAL (integer) T_MUL_EQUAL (integer) T_DIV_EQUAL (integer) T_CONCAT_EQUAL (integer) 3553 Tokenizer functions T_MOD_EQUAL (integer) T_AND_EQUAL (integer) T_OR_EQUAL (integer) T_XOR_EQUAL (integer) T_SL_EQUAL (integer) T_SR_EQUAL (integer) T_BOOLEAN_OR (integer) T_BOOLEAN_AND (integer) T_IS_EQUAL (integer) T_IS_NOT_EQUAL (integer) T_IS_IDENTICAL (integer) T_IS_NOT_IDENTICAL (integer) T_IS_SMALLER_OR_EQUAL (integer) T_IS_GREATER_OR_EQUAL (integer) T_SL (integer) T_SR (integer) T_INC (integer) T_DEC (integer) T_INT_CAST (integer) T_DOUBLE_CAST (integer) T_STRING_CAST (integer) T_ARRAY_CAST (integer) T_OBJECT_CAST (integer) T_BOOL_CAST (integer) T_UNSET_CAST (integer) T_NEW (integer) T_EXIT (integer) T_IF (integer) T_ELSEIF (integer) T_ELSE (integer) 3554 Tokenizer functions T_ENDIF (integer) T_LNUMBER (integer) T_DNUMBER (integer) T_STRING (integer) T_STRING_VARNAME (integer) T_VARIABLE (integer) T_NUM_STRING (integer) T_INLINE_HTML (integer) T_CHARACTER (integer) T_BAD_CHARACTER (integer) T_ENCAPSED_AND_WHITESPACE (integer) T_CONSTANT_ENCAPSED_STRING (integer) T_ECHO (integer) T_DO (integer) T_WHILE (integer) T_ENDWHILE (integer) T_FOR (integer) T_ENDFOR (integer) T_FOREACH (integer) T_ENDFOREACH (integer) T_DECLARE (integer) T_ENDDECLARE (integer) T_AS (integer) T_SWITCH (integer) T_ENDSWITCH (integer) T_CASE (integer) T_DEFAULT (integer) T_BREAK (integer) T_CONTINUE (integer) T_OLD_FUNCTION (integer) 3555 Tokenizer functions T_FUNCTION (integer) T_CONST (integer) T_RETURN (integer) T_USE (integer) T_GLOBAL (integer) T_STATIC (integer) T_VAR (integer) T_UNSET (integer) T_ISSET (integer) T_EMPTY (integer) T_CLASS (integer) T_EXTENDS (integer) T_OBJECT_OPERATOR (integer) T_DOUBLE_ARROW (integer) T_LIST (integer) T_ARRAY (integer) T_LINE (integer) T_FILE (integer) T_COMMENT (integer) T_ML_COMMENT (integer) T_OPEN_TAG (integer) T_OPEN_TAG_WITH_ECHO (integer) T_CLOSE_TAG (integer) T_WHITESPACE (integer) T_START_HEREDOC (integer) T_END_HEREDOC (integer) T_DOLLAR_OPEN_CURLY_BRACES (integer) T_CURLY_OPEN (integer) T_PAAMAYIM_NEKUDOTAYIM (integer) T_DOUBLE_COLON (integer) 3556 Tokenizer functions Examples Here is a simple example PHP scripts using the tokenizer that will read in a PHP file, strip all comments from the source and print the pure code only. Example 879. Strip comments with the tokenizer output "as is" echo $text; break; } } } ?> 3557 token_get_all (PHP 4 >= 4.2.0) token_get_all - Split given source into PHP tokens Description array token_get_all (string source) token_get_all() parses the given source string into PHP language tokens using the Zend engines lexical scanner. The function returns an array of token descriptions. Each array element itself is either a one character string or itself an array containing a token id and the string representation of that token in the source code. Example 880. token_get_all() example array(";") $tokens = token_get_all("foreach"); // => array(T_FOREACH => "foreach") $tokens = token_get_all("/* comment */"); // => array(T_ML_COMMENT => "/* comment */") ?> 3558 token_name (PHP 4 >= 4.2.0) token_name - Get the symbolic name of a given PHP token Description string token_name (int token) token_name() returns the symbolic name for a PHP token value. The symbolic name returned matches the name of the matching token constant. Example 881. token_name() example "T_REQUIRE" // a token constant maps to its own name echo token_name(T_FUNCTION); // -> "T_FUNCTION" ?> 3559 URL Functions Table of Contents base64_decode ................................................................................................................................ 3562 base64_encode ................................................................................................................................ 3563 get_meta_tags ................................................................................................................................. 3564 parse_url ........................................................................................................................................ 3565 rawurldecode ................................................................................................................................... 3566 rawurlencode ................................................................................................................................... 3567 urldecode ........................................................................................................................................ 3568 urlencode ........................................................................................................................................ 3569 3560 Introduction Dealing with URL strings: encoding, decoding and parsing. Requirements No external libraries are needed to build this extension. Installation There is no installation needed to use these functions; they are part of the PHP core. Runtime Configuration This extension has no configuration directives defined in php.ini. Resource Types This extension has no resource types defined. Predefined Constants This extension has no constants defined. 3561 base64_decode (PHP 3, PHP 4 ) base64_decode - Decodes data encoded with MIME base64 Description string base64_decode (string encoded_data) base64_decode() decodes encoded_data and returns the original data. The returned data may be binary. See also: base64_encode(), RFC 2045 [http://www.faqs.org/rfcs/rfc2045] section 6.8. 3562 base64_encode (PHP 3, PHP 4 ) base64_encode - Encodes data with MIME base64 Description string base64_encode (string data) base64_encode() returns data encoded with base64. This encoding is designed to make binary data survive transport through transport layers that are not 8-bit clean, such as mail bodies. Base64-encoded data takes about 33% more space than the original data. See also: base64_decode(), chunk_split(), RFC 2045 [http://www.faqs.org/rfcs/rfc2045] section 6.8. 3563 get_meta_tags (PHP 3>= 3.0.4, PHP 4 ) get_meta_tags - Extracts all meta tag content attributes from a file and returns an array Description array get_meta_tags (string filename [, int use_include_path]) Opens filename and parses it line by line for tags in the file. This can be a local file or an URL. The parsing stops at . Setting use_include_path to 1 will result in PHP trying to open the file along the standard include path as per the include_path directive. This is used for local files, not URLs. Example 882. What get_meta_tags() parses (pay attention to line endings - PHP uses a native function to parse the input, so a Mac file won't work on Unix). The value of the name property becomes the key, the value of the content property becomes the value of the returned array, so you can easily use standard array functions to traverse it or access single values. Special characters in the value of the name property are substituted with '_', the rest is converted to lower case. If two meta tags have the same name, only the last one is returned. Example 883. What get_meta_tags() returns Note: As of PHP 4.0.5, get_meta_tags() supports unquoted html attributes. See also htmlentities() and urlencode(). 3564 parse_url (PHP 3, PHP 4 ) parse_url - Parse a URL and return its components Description array parse_url (string url) This function returns an associative array returning any of the various components of the URL that are present. This includes the • scheme - e.g. http • host • port • user • pass • path • query - after the question mark ? • fragment - after the hashmark # This function is not meant to validate the given URL, it only breaks it up into the above listed parts. Partial urls are also accepted, parse_url() tries its best to parse them correctly. Example 884. Using parse_url() $ php -r 'print_r( parse_url("http://username:password@hostname/path?arg=value#anchor"));' Array ( [scheme] => http [host] => hostname [user] => username [pass] => password [path] => /path [query] => arg=value [fragment] => anchor ) $ php -r 'print_r( parse_url("http://invalid_host..name/"));' Array ( [scheme] => http [host] => invalid_host..name [path] => / ) See also pathinfo(), parse_str(), dirname(), and basename(). 3565 rawurldecode (PHP 3, PHP 4 ) rawurldecode - Decode URL-encoded strings Description string rawurldecode (string str) Returns a string in which the sequences with percent (%) signs followed by two hex digits have been replaced with literal characters. For example, the string foo%20bar%40baz decodes into foo bar@baz . Note: rawurldecode() does not decode plus symbols ('+') into spaces. urldecode() does. See also rawurlencode(), urldecode(), urlencode(). 3566 rawurlencode (PHP 3, PHP 4 ) rawurlencode - URL-encode according to RFC 1738 Description string rawurlencode (string str) Returns a string in which all non-alphanumeric characters except -_. have been replaced with a percent (%) sign followed by two hex digits. This is the encoding described in RFC 1738 for protecting literal characters from being interpreted as special URL delimiters, and for protecting URL's from being mangled by transmission media with character conversions (like some email systems). For example, if you want to include a password in an FTP URL: Example 885. rawurlencode() example 1 echo ''; Or, if you pass information in a PATH_INFO component of the URL: Example 886. rawurlencode() example 2 echo ''; See also rawurldecode(), urldecode(), urlencode() and RFC 1738 [http://www.faqs.org/rfcs/rfc1738] 3567 urldecode (PHP 3, PHP 4 ) urldecode - Decodes URL-encoded string Description string urldecode (string str) Decodes any %## encoding in the given string. The decoded string is returned. Example 887. urldecode() example $a = explode('&', $QUERY_STRING); $i = 0; while ($i < count($a)) { $b = split('=', $a[$i]); echo 'Value for parameter ', htmlspecialchars(urldecode($b[0])), ' is ', htmlspecialchars(urldecode($b[1])), "
\n"; $i++; } See also urlencode(), rawurlencode(), rawurldecode(). 3568 urlencode (PHP 3, PHP 4 ) urlencode - URL-encodes string Description string urlencode (string str) Returns a string in which all non-alphanumeric characters except -_. have been replaced with a percent (%) sign followed by two hex digits and spaces encoded as plus (+) signs. It is encoded the same way that the posted data from a WWW form is encoded, that is the same way as in application/x-www-form-urlencoded media type. This differs from the RFC1738 encoding (see rawurlencode()) in that for historical reasons, spaces are encoded as plus (+) signs. This function is convenient when encoding a string to be used in a query part of an URL, as a convenient way to pass variables to the next page: Example 888. urlencode() example echo ''; Note: Be careful about variables that may match HTML entities. Things like &, © and £ are parsed by the browser and the actual entity is used instead of the desired variable name. This is an obvious hassle that the W3C has been telling people about for years. The reference is here: http://www.w3.org/TR/html4/appendix/notes.html#h-B.2.2 PHP supports changing the argument separator to the W3C-suggested semi-colon through the arg_separator .ini directive. Unfortunately most user agents do not send form data in this semi-colon separated format. A more portable way around this is to use & instead of & as the separator. You don't need to change PHP's arg_separator for this. Leave it as &, but simply encode your URLs using htmlentities()(urlencode($data)). Example 889. urlencode() and htmlentities() example echo ''; See also urldecode(), htmlentities(), rawurldecode(), and rawurlencode(). 3569 Variable Functions Table of Contents doubleval ........................................................................................................................................ 3572 empty ............................................................................................................................................ 3573 floatval .......................................................................................................................................... 3574 get_defined_vars .............................................................................................................................. 3575 get_resource_type ............................................................................................................................ 3576 gettype ........................................................................................................................................... 3577 import_request_variables ................................................................................................................... 3578 intval ............................................................................................................................................. 3579 is_array .......................................................................................................................................... 3580 is_bool ........................................................................................................................................... 3581 is_callable ...................................................................................................................................... 3582 is_double ........................................................................................................................................ 3583 is_float ........................................................................................................................................... 3584 is_int ............................................................................................................................................. 3585 is_integer ........................................................................................................................................ 3586 is_long ........................................................................................................................................... 3587 is_null ............................................................................................................................................ 3588 is_numeric ...................................................................................................................................... 3589 is_object ......................................................................................................................................... 3590 is_real ............................................................................................................................................ 3591 is_resource ..................................................................................................................................... 3592 is_scalar ......................................................................................................................................... 3593 is_string ......................................................................................................................................... 3594 isset ............................................................................................................................................... 3595 print_r ............................................................................................................................................ 3597 serialize .......................................................................................................................................... 3599 settype ........................................................................................................................................... 3600 strval ............................................................................................................................................. 3601 unserialize ...................................................................................................................................... 3602 unset .............................................................................................................................................. 3604 var_dump ....................................................................................................................................... 3606 var_export ...................................................................................................................................... 3607 3570 Introduction For information on how variables behave, see the Variables entry in the Language Reference section of the manual. Requirements No external libraries are needed to build this extension. Installation There is no installation needed to use these functions; they are part of the PHP core. Runtime Configuration The behaviour of these functions is affected by settings in php.ini. Table 171. Variables Configuration Options Name Default Changeable unserialize_callback_func "" PHP_INI_ALL For further details and definition of the PHP_INI_* constants see ini_set(). Here's a short explanation of the configuration directives. unserialize_callback_func string The unserialize callback function will called (with the undefind class' name as parameter), if the unserializer finds an undefined class which should be instanciated. A warning appears if the specified function is not defined, or if the function doesn't include/implement the missing class. So only set this entry, if you really want to implement such a callback-function. See also unserialize(). Resource Types This extension has no resource types defined. Predefined Constants This extension has no constants defined. 3571 doubleval (PHP 3, PHP 4 ) doubleval - Alias of floatval() Description This function is an alias of floatval(). Note: This alias is a left-over from a function-renaming. In older versions of PHP you'll need to use this alias of the floatval() function, because floatval() wasn't yet available in that version. 3572 empty (PHP 3, PHP 4 ) empty - Determine whether a variable is empty Description bool empty (mixed var) empty() returns FALSE if var has a non-empty or non-zero value. In otherwords, "", 0, "0", NULL, FALSE, array(), var $var;, and objects with empty properties, are all considered empty. TRUE is returned if var is not empty. empty() is the opposite of (boolean) var, except that no warning is generated when the variable is not set. See converting to boolean for more information. Example 890. A simple empty() / isset() comparison. Note: Because this is a language construct and not a function, it cannot be called using variable functions Note: empty() only checks variables as anything else will result in a parse error. In otherwords, the following will not work: empty(addslashes($name)). See also isset(), unset(), array_key_exists(), count(), and strlen(). 3573 floatval (PHP 4 >= 4.2.0) floatval - Get float value of a variable Description float floatval (mixed var) Returns the float value of var. Var may be any scalar type. You cannot use floatval() on arrays or objects. See also intval(), strval(), settype() and Type juggling. 3574 get_defined_vars (PHP 4 >= 4.0.4) get_defined_vars - Returns an array of all defined variables Description array get_defined_vars (void) This function returns an multidimensional array containing a list of all defined variables, be them environment, server or user-defined variables. See also get_defined_functions() and get_defined_constants(). 3575 get_resource_type (PHP 4 >= 4.0.2) get_resource_type - Returns the resource type Description string get_resource_type (resource handle) This function returns a string representing the type of the resource passed to it. If the paramater is not a valid resource, it generates an error. doc)."\n"; // prints: domxml document ?> 3576 gettype (PHP 3, PHP 4 ) gettype - Get the type of a variable Description string gettype (mixed var) Returns the type of the PHP variable var. Warning Never use gettype() to test for a certain type, since the returned string may be subject to change in a future version. In addition, it is slow too, as it involves string comparision . Instead, use the is_* functions. Possibles values for the returned string are: • "boolean" (since PHP 4) • "integer" • "double" (for historical reasons "double" is returned in case of a float, and not simply "float") • "string" • "array" • "object" • "resource" (since PHP 4) • "NULL" (since PHP 4) • "user function" (PHP 3 only, deprecated) • "unknown type" For PHP 4, you should use function_exists() and method_exists() to replace the prior usage of gettype() on a function. See also settype(), is_array(), is_bool(), is_float(), is_integer(), is_null(), is_numeric(), is_object(), is_resource(), is_scalar(), and is_string(). 3577 import_request_variables (PHP 4 >= 4.1.0) import_request_variables - Import GET/POST/Cookie variables into the global scope Description bool import_request_variables (string types [, string prefix]) Imports GET/POST/Cookie variables into the global scope. It is useful if you disabled register_globals, but would like to see some variables in the global scope. Using the types parameter, you can specify which request variables to import. You can use 'G', 'P' and 'C' characters respectively for GET, POST and Cookie. These characters are not case sensitive, so you can also use any combination of 'g', 'p' and 'c'. POST includes the POST uploaded file information. Note that the order of the letters matters, as when using "gp", the POST variables will overwrite GET variables with the same name. Any other letters than GPC are discarded. The prefix parameter is used as a variable name prefix, prepended before all variable's name imported into the global scope. So if you have a GET value named "userid", and provide a prefix "pref_", then you'll get a global variable named $pref_userid. If you're interested in importing other variables into the global scope, such as SERVER, consider using extract(). Note: Although the prefix parameter is optional, you will get an E_NOTICE level error if you specify no prefix, or specify an empty string as a prefix. This is a possible security hazard. Notice level errors are not displayed using the default error reporting level. See also $_REQUEST, register_globals, Predefined Variables, and extract(). 3578 intval (PHP 3, PHP 4 ) intval - Get integer value of a variable Description int intval (mixed var [, int base]) Returns the integer value of var, using the specified base for the conversion (the default is base 10). var may be any scalar type. You cannot use intval() on arrays or objects. Note: The base argument for intval() has no effect unless the var argument is a string. See also floatval(), strval(), settype() and Type juggling. 3579 is_array (PHP 3, PHP 4 ) is_array - Finds whether a variable is an array Description bool is_array (mixed var) Returns TRUE if var is an array, FALSE otherwise. See also is_float(), is_int(), is_integer(), is_string(), and is_object(). 3580 is_bool (PHP 4 ) is_bool - Finds out whether a variable is a boolean Description bool is_bool (mixed var) Returns TRUE if the var parameter is a boolean. Example 891. is_bool() examples See also is_array(), is_float(), is_int(), is_integer(), is_string(), and is_object(). 3581 is_callable (PHP 4 >= 4.0.6) is_callable - Find out whether the argument is a valid callable construct Description bool is_callable (mixed var [, bool syntax_only [, string callable_name]]) Warning This function is currently not documented; only the argument list is available. 3582 is_double (PHP 3, PHP 4 ) is_double - Alias of is_float() Description This function is an alias of is_float(). 3583 is_float (PHP 3, PHP 4 ) is_float - Finds whether a variable is a float Description bool is_float (mixed var) Returns TRUE if var is a float, FALSE otherwise. Note: To test if a variable is a number or a numeric string (such as form input, which is always a string), you must use is_numeric(). See also is_bool(), is_int(), is_integer(), is_numeric(), is_string(), is_array(), and is_object(), 3584 is_int (PHP 3, PHP 4 ) is_int - Find whether a variable is an integer Description bool is_int (mixed var) Returns TRUE if var is an integer FALSE otherwise. Note: To test if a variable is a number or a numeric string (such as form input, which is always a string), you must use is_numeric(). See also is_bool(), is_float(), is_integer(), is_numeric(), is_string(), is_array(), and is_object(). 3585 is_integer (PHP 3, PHP 4 ) is_integer - Alias of is_int() Description This function is an alias of is_int(). 3586 is_long (PHP 3, PHP 4 ) is_long - Alias of is_int() Description This function is an alias of is_int(). 3587 is_null (PHP 4 >= 4.0.4) is_null - Finds whether a variable is NULL Description bool is_null (mixed var) Returns TRUE if var is null, FALSE otherwise. See the NULL type when a variable is considered to be NULL and when not. See also NULL, is_bool(), is_numeric(), is_float(), is_int(), is_string(), is_object(), is_array(), is_integer(), and is_real(). 3588 is_numeric (PHP 4 ) is_numeric - Finds whether a variable is a number or a numeric string Description bool is_numeric (mixed var) Returns TRUE if var is a number or a numeric string, FALSE otherwise. See also is_bool(), is_float(), is_int(), is_string(), is_object(), is_array(), and is_integer(). 3589 is_object (PHP 3, PHP 4 ) is_object - Finds whether a variable is an object Description bool is_object (mixed var) Returns TRUE if var is an object, FALSE otherwise. See also is_bool(), is_int(), is_integer(), is_float(), is_string(), and is_array(). 3590 is_real (PHP 3, PHP 4 ) is_real - Alias of is_float() Description This function is an alias of is_float(). 3591 is_resource (PHP 4 ) is_resource - Finds whether a variable is a resource Description bool is_resource (mixed var) is_resource() returns TRUE if the variable given by the var parameter is a resource, otherwise it returns FALSE. See the documentation on the resource-type for more information. 3592 is_scalar (PHP 4 >= 4.0.5) is_scalar - Finds whether a variable is a scalar Description bool is_scalar (mixed var) is_scalar() returns TRUE if the variable given by the var parameter is a scalar, otherwise it returns FALSE. Scalar variables are those containing an integer, float, string or boolean. Types array, object and resource or not scalar. // string(10) "hemoglobin" // [1]=> // string(20) "cytochrome c oxidase" // [2]=> // string(10) "ferredoxin" // } ?> Note: is_scalar() does not consider resource type values to be scalar as resources are abstract datatypes which are currently based on integers. This implementation detail should not be relied upon, as it may change. See also is_bool(), is_numeric(), is_float(), is_int(), is_real(), is_string(), is_object(), is_array(), and is_integer(). 3593 is_string (PHP 3, PHP 4 ) is_string - Finds whether a variable is a string Description bool is_string (mixed var) Returns TRUE if var is a string, FALSE otherwise. See also is_bool(), is_int(), is_integer(), is_float(), is_real(), is_object(), and is_array(). 3594 isset (PHP 3, PHP 4 ) isset - Determine whether a variable is set Description bool isset (mixed var [, mixed var [, ...]]) Returns TRUE if var exists; FALSE otherwise. If a variable has been unset with unset(), it will no longer be isset(). isset() will return FALSE if testing a variable that has been set to NULL. Also note that a NULL byte ("\0") is not equivalent to the PHP NULL constant. Warning: isset() only works with variables as passing anything else will result in a parse error. For checking if constants are set use the defined() function. This also work for elements in arrays: 1, 'hello' => NULL); var_dump( isset ($a['test']) ); var_dump( isset ($a['foo']) ); var_dump( isset ($a['hello']) ); // TRUE // FALSE // FALSE // The key 'hello' equals NULL so is considered unset // If you want to check for NULL key values then try: var_dump( array_key_exists('hello', $a) ); // TRUE ?> 3595 isset Note: Because this is a language construct and not a function, it cannot be called using variable functions See also empty(), unset(), defined(), array_key_exists() and the error control @ operator. 3596 print_r (PHP 4 ) print_r - Prints human-readable information about a variable Description bool print_r (mixed expression [, bool return]) Note: The return parameter was added in PHP 4.3.0 print_r() displays information about a variable in a way that's readable by humans. If given a string, integer or float, the value itself will be printed. If given an array, values will be presented in a format that shows keys and elements. Similar notation is used for objects. Remember that print_r() will move the array pointer to the end. Use reset() to bring it back to beginning.

 'apple', 'b' => 'banana', 'c' => array ('x','y','z'));
print_r ($a);
?>

Array
(
[a] => apple
[b] => banana
[c] => Array
(
[0] => x
[1] => y
[2] => z
)
)

int(1)
[1]=>
int(2)
[2]=>
array(3) {
[0]=>
string(1) "a"
[1]=>
string(1) "b"
[2]=>
string(1) "c"
}
}
*/
$b = 3.1;
$c = TRUE;
var_dump($b,$c);
/* output:
float(3.1)
bool(true)
*/
?>

 1,
1 => 2,
2 =>
array (
0 => 'a',
1 => 'b',
2 => 'c',
),
)
*/
$b = 3.1;
$v = var_export($b, TRUE);
echo $v;
/* output:
3.1
*/
?>