Utilities

Utility library.  Implements some general purpose functions plus some wrappers that implement functionality available in PHP 5.

Summary
UtilitiesUtility library.
Functions
write_fileWrite contents to a file.
mkdir_recMakes directory recursively.
scan_directoryDoes essentially the same thing as scandir on PHP 5.
calculate_document_rootAn alternate way to find the document root.
test_server_rootTests a root-relative path against the document root and subdomain root directory and determines which one “works.”
SESSIONA wrapper for the $_SESSION superglobal.
SERVER
COOKIE
POST
GET
has_postDetermine if there is any POST data.
current_uriConvenience function to return the path to the current script.
current_fileAn alias for current_uri(true, false, $no_escape).
current_urlThe absolute URL of the requested script.
localpath_to_uriConvert a local path to a URI.
uri_to_localpathThe reverse of localpath_to_uri, this function takes a URI handled by LnBlog and converts it into a local path to the file or directory in question.
get_ipQuick function to get the user’s IP address.
getlinkReturns a path suitable for use with <link> tags or as an href or src attribute.
sanitizeStrips the input of certain characters.
in_arrayiLike in_array() standard function, except case-insensitive for strings.
make_uriBuilds a correct URI with query string.
set_domain_cookieA convenience wrapper for the setcookie() function.
get_entry_from_uriTakes a URI and converts it into an entry object.
HTML String Convenience Functions
Functions
ahrefCreates markup for a hyperlink.

Functions

write_file

function write_file($path,
$contents)

Write contents to a file.  Basically a wrapper around fopen and fwrite.  This function was rewritten to use the FS abstract interface.  For one-off writes, this is fine, but for writing multiple files in the same call, the FS interface should be used directly to avoid overhead.

Parameters

pathThe path to write to.
contentsA string to write to the file.

Returns

Passes on the return value of the fs->write_file() method.

mkdir_rec

function mkdir_rec($path,  
$mode = false)

Makes directory recursively.  As with write_file, is a wrapper around the FS interface.  Same deal.

Parameters

pathThe path to create.
modeThe optional octal directory permissions for the path.

Returns

Passes on the return value of the underlying class method.

scan_directory

function scan_directory($path,  
$dirs_only = false)

Does essentially the same thing as scandir on PHP 5.  Gets all the entries in the given directory.

Parameters

pathThe directory path to scan.
dirs_onlyOptional parameter to list only the directories in the path.  The default is false.

Returns

An array of directory entry names, removing “.” and “..” entries.

calculate_document_root

function calculate_document_root()

An alternate way to find the document root.  This one works by comparing the current URL on the server to the current directory.  The idea is that we can find the location of the current URL in the path and remove it to get the document root.  Note that this function IS case-sensitive.

Returns

The calculated document root path.

test_server_root

function test_server_root($path,  
$assume_subdomain = false)

Tests a root-relative path against the document root and subdomain root directory and determines which one “works.”

Parameters

pathThe root-relative path to test.
assume_subdomainOptional boolean which, when set to true, tells the routine to assume a subdomain path when the test results are ambiguous.  Defaults to false.

SESSION

function SESSION($key,  
$val = "")

A wrapper for the $_SESSION superglobal.  Provides a handy way to avoid undefined variable warnings without explicitly calling isset() or empty() every time.

Parameters

keyThe key for the superglobal index.
valThe optional value to set to the superglobal.

Returns

The value of the superglobal at index key, false if index is not set.

SERVER

function SERVER($key,  
$val = "")

Parameters

keyThe key for the superglobal index.
valThe optional value to set to the superglobal.

Returns

The value of the superglobal at index key, false if index is not set.

COOKIE

function COOKIE($key,  
$val = "")

Parameters

keyThe key for the superglobal index.
valThe optional value to set to the superglobal.

Returns

The value of the superglobal at index key, false if index is not set.

POST

function POST($key,  
$val = "")

Parameters

keyThe key for the superglobal index.
valThe optional value to set to the superglobal.

Returns

The value of the superglobal at index key, false if index is not set.

GET

function GET($key,  
$val = "")

Parameters

keyThe key for the superglobal index.
valThe optional value to set to the superglobal.

Returns

The value of the superglobal at index key, false if index is not set.

has_post

function has_post()

Determine if there is any POST data.

Returns

True if $_POST has any members, false otherwise.

current_uri

function current_uri ($relative = false,
$query_string = false,
$no_escape = false)

Convenience function to return the path to the current script.  Useful for the action attribute in form tags.

Parameters

relativeOptionally get the URI relative to the current directory, i.e. just the file name.  Default is false.
query_stringQuery string to append to URI.  Default is false, which mean that the current query string will be used.
no_escapeIndicates whether or not ampersands in the query string should be escaped as &amp;, which is needed for XHTML compliance.

Returns

A string with the URI.

current_file

function current_file($no_escape = false)

An alias for current_uri(true, false, $no_escape).

current_url

function current_url()

Returns

The absolute URL of the requested script.

localpath_to_uri

function localpath_to_uri($path,  
$full_uri = true,
$https = false)

Convert a local path to a URI.

Parameters

pathThe path to convert.
full_uriOption to return the full URI, as opposed to just a root-relative URI.  Defaults to true.

Returns

A string with the URL oc the given path.

uri_to_localpath

function uri_to_localpath($uri)

The reverse of localpath_to_uri, this function takes a URI handled by LnBlog and converts it into a local path to the file or directory in question.  This function assumes that the URI is fully qualified, e.g.

http://somehost.com/somepath/somefile.ext

Note that this may or may not play well with Apache .htaccess files.

Parameters

uriThe URI to convert.

Returns

A string containing the local path referenced by the URI.  Not that this path may or may not exist.

get_ip

function get_ip()

Quick function to get the user’s IP address.  This should probably be extended to account for proxies and such.

Returns

The numeric IP address of the client.

getlink

function getlink($name,  
$type = false)

Returns a path suitable for use with <link> tags or as an href or src attribute.  Takes a file name and optional type (script, image, or style sheet) and returns a URI.  If the type is not given, the function guesses it from the file extension.

Parameters

nameThe filename of the item to link.
typeThe optional type of the item.  May be one of the defined constants LINK_IMAGE, LINK_SCRIPT, of LINK_STYLESHEET.

Returns

The root-relative path to the item.  If no item is found in any path, returns the name parameter as-is.

sanitize

function sanitize($str,  
$pattern = "/\W/",
$sub = "")

Strips the input of certain characters.  This is a thin wrapper around the preg_replace function.

Parameters

strThe string to strip.
patternThe pattern to match.  Default is /\W/, i.e. non-word chars.
subThe substitution string for pattern, default is null string.

Returns

The string with all characters matching sub replaced by the sub character.

in_arrayi

function in_arrayi($needle,
$haystack)

Like in_array() standard function, except case-insensitive for strings.

make_uri

function make_uri($base = false,
$query_string = false,
$no_get = true,
$link_sep = '&amp;',
$add_host = false)

Builds a correct URI with query string.  This is an all-purpose kind of function designed to handle most contingencies.

Parameters

baseThe base URI to use.  If not given, the current URI is used.
query_stringAn associative array representing the query string.
no_getA boolean set to true to suppress automatic importing of the $_GET superglobal into the query_string parameter.
link_sepCharacter to separate query string parameters.  Default value is ‘&amp;’ for link hrefs.  Use ‘&’ for redirects.
add_hostIf set to true, adds a host and protocol to the returned URI if they are not already present.

Returns

A string containing the resulting URI.

set_domain_cookie

function set_domain_cookie($name,  
$value = '',
$expire = 0)

A convenience wrapper for the setcookie() function.  If the DOMAIN_NAME constant is set, then this will set the cookie for .domain.whatever, but will simply skip the domain parameter otherwise.  This also sets the path to the root directory.

get_entry_from_uri

function get_entry_from_uri($uri)

Takes a URI and converts it into an entry object.

HTML String Convenience Functions

Summary
Functions
ahrefCreates markup for a hyperlink.

Functions

ahref

function ahref($href,  
$text,  
$attribs = false)

Creates markup for a hyperlink.

Parameters

hrefThe URL to link to.
textThe main link text.
attribsAn associative array of additional attributes, with the key as the attribute name.
function write_file($path,
$contents)
Write contents to a file.
function mkdir_rec($path,  
$mode = false)
Makes directory recursively.
function scan_directory($path,  
$dirs_only = false)
Does essentially the same thing as scandir on PHP 5.
function calculate_document_root()
An alternate way to find the document root.
function test_server_root($path,  
$assume_subdomain = false)
Tests a root-relative path against the document root and subdomain root directory and determines which one “works.”
function SESSION($key,  
$val = "")
A wrapper for the $_SESSION superglobal.
function SERVER($key,  
$val = "")
function COOKIE($key,  
$val = "")
function POST($key,  
$val = "")
function GET($key,  
$val = "")
function has_post()
Determine if there is any POST data.
function current_uri ($relative = false,
$query_string = false,
$no_escape = false)
Convenience function to return the path to the current script.
function current_file($no_escape = false)
An alias for current_uri(true, false, $no_escape).
function current_url()
The absolute URL of the requested script.
function localpath_to_uri($path,  
$full_uri = true,
$https = false)
Convert a local path to a URI.
function uri_to_localpath($uri)
The reverse of localpath_to_uri, this function takes a URI handled by LnBlog and converts it into a local path to the file or directory in question.
function get_ip()
Quick function to get the user’s IP address.
function getlink($name,  
$type = false)
Returns a path suitable for use with link tags or as an href or src attribute.
function sanitize($str,  
$pattern = "/\W/",
$sub = "")
Strips the input of certain characters.
function in_arrayi($needle,
$haystack)
Like in_array() standard function, except case-insensitive for strings.
function make_uri($base = false,
$query_string = false,
$no_get = true,
$link_sep = '&amp;',
$add_host = false)
Builds a correct URI with query string.
function set_domain_cookie($name,  
$value = '',
$expire = 0)
A convenience wrapper for the setcookie() function.
function get_entry_from_uri($uri)
Takes a URI and converts it into an entry object.
function ahref($href,  
$text,  
$attribs = false)
Creates markup for a hyperlink.
Close