Download | Documentation | Forums

Extra Components

There are a number of extra components that ship with the core Barebones CMS product that are not documented anywhere else in the documentation. Many of the components are not even used by Barebones CMS itself.

These components are designed to make certain common tasks on websites easier. Connecting to a MySQL database, running queries, and gathering results, for example, is encapsulated in 'support/mysql.php'. Other common tasks are encapsulated as well - sending and receiving e-mail, setting browser cookies, and web scraping.

Bit Stream Class: 'support/bits.php'

The StreamBitStream class allows a string to be treated as a stream of bits for easy bit-level manipulation. There is currently just 'read' functionality in this class. It is used by the official Barebones CMS Flash Shortcode to analyze Flash objects (SWF files) to determine the optimal width and height of the Flash object.

Example from the Flash Shortcode:

<?php
	...
	require_once ROOT_PATH . "/" . SUPPORT_PATH . "/bits.php";

	$sbs = new StringBitStream;
	$sbs->Init($data);
	$numbits = $sbs->ReadBits(5);
	$x = $sbs->ReadBits($numbits);
	$x2 = $sbs->ReadBits($numbits);
	$y = $sbs->ReadBits($numbits);
	$y2 = $sbs->ReadBits($numbits);

	$info["width"] = (int)(($x2 - $x) / 20);
	$info["height"] = (int)(($y2 - $y) / 20);
	...
?>

StringBitStream::Init($data = "")

Parameters:

Returns: Nothing.

This function initializes a StringBitStream instance with the data that will be used and resets all internal variables.

StringBitStream::ReadBits($numbits, $toint = true, ...)

Parameters:

Returns: An integer if $toint is true, an array otherwise on success. If there are insufficient bits for the request, a boolean of false is returned.

This function reads in the specified number of bits and returns an integer or an array containing those bits.

The array form is an array of arrays where the first element of each subarray is the number of bits and the second element are the extracted bits in integer form. Each subarray contains up to one byte of the stream. The $toint option is a shortcut to calling ConvertBitsToInt() after each ReadBits() call.

StringBitStream::ConvertBitsToInt($data, ...)

Parameters:

Returns: An integer containing the converted array.

This function is intended to be used after a call to ReadBits(). The ReadBits() function uses this function when the $toint option of that function is set to true.

StringBitStream::GetBytePos()

Parameters: None.

Returns: An integer containing the current byte being processed.

This function can be useful to know where in the data stream the byte pointer is at. Usually used in conjunction with the AlignBytes() function. If processing hasn't begun, it will return -1.

StringBitStream::AlignBytes($base, $size)

Parameters:

Returns: Nothing.

This function aligns the byte pointer and resets the bit pointer. For instance, if binary data in a row is DWORD-aligned (4 bytes), then $base could be 0 and $size would be 4 to move the internal byte pointer to the start of the next row once the end of the current row was reached with ReadBits(). Basically, this offers a flushing mechanism.

Browser Cookie Functions: 'support/cookie.php'

This file contains one function for setting browser cookies. The main Barebones CMS login system and editor both use the function to set the login cookie. The built-in PHP setcookie() function is okay, but this offers a couple features over that function.

SetCookieFixDomain($name, $value = "", ...)

Parameters:

Returns: Nothing.

This functions sends a cookie to the browser. To expire a cookie, call the function with $expires set to a low value (e.g. 1). This function corrects $domain issues that are frequently encountered when using cookies.

Cookies are a security issue. Make sure that cookies containing session information use $httponly set to true so that Javascript can't send the session information to a remote server. How Barebones CMS detects a login (so Easy Edit works) is to set a second cookie containing useless information that has $httponly set to false. Javascript detects the second cookie and, by inference, the first cookie is assumed to exist and therefore the 'Edit' link appears in the browser.

HTTP Functions: 'support/http.php'

These functions are designed to perform the first half of a process known as "web scraping". Web scraping is essentially retrieving content, parsing the content, and extracting whatever data is needed for whatever nefarious purposes the user has in mind. I'm not responsible with what you choose to do with these functions - that is, try to only do legal stuff with these functions. They are incredibly powerful PHP routines that go far beyond what PHP cURL or file_get_contents() calls typically do. It is easy to create web requests that look exactly like they came from a web browser.

Retrieving a webpage is half of the battle. Parsing it is the other half. Included with Barebones CMS is Simple HTML DOM located in 'support/simple_html_dom.php', which parses the page and then allows for jQuery-style selectors to be used to extract the content (not all selectors are supported though). This approach is significantly better than the traditional regular expression route that web scraping is associated with. The product is initially frustrating to work with because of insufficient documentation BUT it really is the best parser out there for serious web scraping. It helps to know how to use jQuery prior to using Simple HTML DOM.

ExtractURL($url)

Parameters:

Returns: An array containing the URL split up into its component pieces according to RFC 3986.

This function takes apart a URL and breaks it up into "scheme", "authority", "login", "host", "port", "path", "query", "queryvars", and "fragment" pieces. In many cases, this function works where the PHP parse_url() function fails. It also breaks up the query string (the part after the question mark '?') into name => array of values pairs.

This function can also occasionally handle broken/incomplete URLs but don't rely on that.

CondenseURL($data)

Parameters:

Returns: A string containing a valid URL.

This function takes data in the format returned from ExtractURL() and condenses it into a string containing a valid URL. Useful for taking apart a URL with ExtractURL(), modifying it a little bit, and then generating a new URL from that to pass to another routine that expects a URL.

ConvertRelativeToAbsoluteURL($baseurl, $relativeurl)

Parameters:

Returns: A string containing an absolute URL.

This function converts a relative URL into an absolute URL based on a base URL. Useful for parsing scraped HTML documents.

GetWebUserAgent($type)

Parameters:

Returns: A string containing a valid user agent for the specified web browser.

This function returns a popular user agent string. These aren't always up-to-date but are usually good enough to get the job done on servers that require a user agent. If you feel a string is too out of date, post a message to the forums.

GetHTTPDateTimestamp($httpdate)

Parameters:

Returns: A boolean of false on failure, otherwise an integer containing a UNIX timestamp.

This function parses the valid set of valid timestamp formats specified by RFC2616 and returns a UNIX timestamp. It is somewhat flexible though and accepts some minor character differences from the actual specification.

HTTPTranslate($format, ...)

Parameters:

Returns: A string containing a translation.

This internal function takes input strings and translates them from English to some other language if CS_TRANSLATE_FUNC is defined to be a valid PHP function name.

HTTPHeaderNameCleanup($name)

Parameters:

Returns: A string containing a purified HTTP header name.

This internal function cleans up a HTTP header name. Used by RetrieveWebpage().

HTTPHeaderValueCleanup($value)

Parameters:

Returns: A string containing a purified HTTP header value.

This internal function cleans up a HTTP header value. Used by RetrieveWebpage().

HTTPNormalizeHeaders($headers)

Parameters:

Returns: An array containing normalized name-value pairs.

This internal function cleans up and normalizes the names and values of a set of HTTP headers.

HTTPProcessSSLOptions(&$options, $key, $host)

Parameters:

Returns: Nothing.

This internal function processes the "auto_cainfo", "auto_cn_match", and "auto_sni" options for "sslopts" and "proxysslopts" for SSL/TLS context purposes.

HTTPExtractFilename($dirfile)

Parameters:

Returns: A string containing the filename.

This internal function is identical to the global function ExtractFilename(). It exists so that the HTTP library can be self-contained.

HTTPFilenameSafe($filename)

Parameters:

Returns: A string containing a safe filename prefix.

This internal function is identical to the global function FilenameSafe(). It exists so that the HTTP library can be self-contained.

HTTPGetTimeLeft($start, $limit)

Parameters:

Returns: A boolean of false if $limit is false, 0 if the time limit has been reached/exceeded, or a numeric value representing the amount of time left in seconds.

This internal function is used to calculate whether an operation has taken too long and then terminate the connection.

HTTPRateLimit($size, $start, $limit)

Parameters:

Returns: Nothing.

This internal function calculates the current rate at which bytes are being transferred over the network. If the rate exceeds the limit, it calculates exactly how long to wait and then sleeps for that amount of time so that the average transfer rate is within the limit.

HTTPGetResponse($fp, $debug, $options, $startts, $timeout)

Parameters:

Returns: An array containing the results of the call.

This internal function processes the response to the request sent by RetrieveWebpage().

RetrieveWebpage($url, $options = array())

Parameters:

Returns: An array containing the results of the call.

This function retrieves a webpage. It has full HTTP and HTTPS support. It can upload files, perform GET, POST, HEAD, PUT, and custom requests, and can even place requests through a HTTP proxy server. It handles chunked data responses, provides detailed responses, and has support for callbacks. It can also be used to precisely emulate a web browser.

HTTPS support requires PHP to have been compiled and enabled with SSL protocol wrapper support via OpenSSL.

The BB_IsValidURL() and BB_IsValidHTMLImage() functions are generally easier to use than this function. They are decent examples of how to use this function.

The $options array can contain:

This function does not process redirects (e.g. HTTP 30x codes) or cookies. Robust code may need to detect redirects and automatically re-run the request at the destination URL and handle cookies correctly. Look at the Web Browser State class for decent support.

SSL/TLS certificates are verified against the included 'cacert.pem' file. This file comes from the cURL website.

Web Browser State Class: 'support/web_browser.php'

The HTTP functions are fine for most purposes. However, they fall short when emulating web browser states such as session cookies, redirects, forms, and other commonly desired features. That is where the Web Browser State class comes in. This class handles cookies, redirects (including relative URL redirects), HTTP 'referer's, and supports enhanced browser emulation for the most common browsers in use.

Example:

<?php
	require_once ROOT_PATH . "/" . SUPPORT_PATH . "/http.php";
	require_once ROOT_PATH . "/" . SUPPORT_PATH . "/web_browser.php";

	$web = new WebBrowser();
	$result = $web->Process("https://www.google.com/");

	// Do something with $result here...
?>

The example uses the default profile to retrieve a webpage using the underlying HTTP library.

WebBrowser::__construct($prevstate = array())

Parameters:

Returns: Nothing.

This function initializes a WebBrowser instance.

WebBrowser::ResetState()

Parameters: None.

Returns: Nothing.

This function resets a WebBrowser instance state to the default state.

WebBrowser::SetState($options = array())

Parameters:

Returns: Nothing.

This function modifies the internal structures of a WebBrowser instance by merging in the specified options. Valid options are:

Some of the information in the instance state can be overridden temporarily with the WebBrowser::Process() call.

WebBrowser::GetState()

Parameters: None.

Returns: An array containing the current state of the WebBrowser instance.

This function is useful for saving the state of a WebBrowser instance for later use.

WebBrowser::Process($url, $profile = "auto", $tempoptions = array())

Parameters:

Returns: An array containing the results of the call.

This function processes a request for a specific URL against the specified profile and the internal state of the WebBrowser instance. When "auto" is used for $profile, it uses the 'useragent' setting in the instance state. The cURL emulation layer (emulate_curl.php) uses a $profile of "" (empty string) and relies on its own settings instead being passed through $tempoptions to accomplish similar results. $tempoptions is used to construct an options array for a RetrieveWebpage() call.

When the instance state variable 'extractforms' is true, a successful result will also automatically extract forms from the HTML response. This feature won't work as expected if body callbacks are used.

WebBrowser::ExtractForms($baseurl, $data)

Parameters:

Returns: An array containing the forms and fields in the HTML.

This function extracts all the forms and fields from HTML via Simple HTML DOM (must be loaded) into an array. The array is supposed to be passed around to FindFormFields(), GetFormValue(), SetFormValue(), and GenerateFormRequest() to manipulate the fields in preparation for a future request to the server.

Also correctly handles HTML 5 form fields that may not reside inside the usual 'form' tag.

WebBrowser::ExtractFieldFromDOM(&$fields, $row)

Parameters:

Returns: Nothing.

This internal function processes the 'form' element defined by $row and converts it into an array object. Used by ExtractForms() for each form element.

WebBrowser::DeleteSessionCookies()

Parameters: None.

Returns: Nothing.

This function scans the WebBrowser instance cookies for session cookies (cookies with no expiration date) and deletes them. This is equivalent to closing a web browser and opening it again. Cookies with expiration dates are left alone.

WebBrowser::DeleteCookies($domainpattern, $pathpattern, $namepattern)

Parameters:

Returns: Nothing.

This function scans the WebBrowser instance cookies for any cookies that matches the specified patterns and deletes them. Using "" (an empty string) for any pattern will match all of that type. Deleting all cookies with this method is slow, so use WebBrowser::SetState(array("cookies" => array())) instead.

WebBrowser::GetExpiresTimestamp($ts)

Parameters:

Returns: An integer containing a UNIX timestamp.

This internal function converts internal cookie timestamps into UNIX timestamps for calculating whether or not the cookie has expired.

Web Browser Form Class: 'support/web_browser.php'

The web browser form class is specifically designed to manage HTML forms for later submission with the WebBrowser class. $form->info and $form->fields are public arrays that can be read and manipulated but use of the convenient helper functions is highly recommended.

WebBrowserForm::FindFormFields($name = false, $value = false, $type = false)

Parameters:

Returns: An array of fields that match the input parameters.

This function finds one or more form elements in an extracted form. Specifically, if there are multiple 'input.submit' buttons on the page that have strange names but the ordering is guaranteed to always be the same, FindFormFields can find all fields of the type 'input.submit' and return it. After that, the name of the submit button is easily identified.

WebBrowserForm::GetFormValue($name, $checkval = false, $type = false)

Parameters:

Returns: A boolean if $checkval is a string, or a string if $checkval is false.

This function retrieves the value of a specific form item's value or 'checked' status when the 'name' is known.

WebBrowserForm::SetFormValue($name, $value, $checked = false, $type = false, $create = false)

Parameters:

Returns: A boolean of true on success, false otherwise.

This function sets the value or alters the 'checked' status of a form element depending on the element's type. When $create is set to true, if the form element doesn't exist, it will be created with the type specified by $type or 'input.text' if the $type is false.

WebBrowserForm::GenerateFormRequest($submitname = false, $submitvalue = false)

Parameters:

Returns: A boolean of false if $form is not an extracted form, otherwise an array containing a WebBrowser class compliant URL and options set.

This function processes the form and returns WebBrowser compatible information. If the form is a GET request, all the variables are condensed into the URL. If the form is a POST request, the variables are broken out to be sent as part of the body later. File uploads are also correctly handled.

The $submitname and $submitvalue options help select the correct 'input.submit' or 'button.submit' item in the form to include. If both options are false, then all submit buttons are included. It is highly recommended to use a specific submission button to avoid confusing the target web server.

MySQL Database Class: 'support/mysql.php'

While Barebones CMS does not use a database, a lot of websites use MySQL to accomplish database-oriented tasks. Almost every PHP host out there also includes MySQL as part of the package deal because they go hand-in-hand and work well together.

Anyone who has worked extensively with MySQL and PHP, though, learns the hard way about SQL injection vulnerabilities by getting hacked or they use one of the many wrapper classes available for the mysql_... series of PHP functions to reduce the likelihood.

This class also provides a wrapper around the PHP functions. However, it is based on years of experience with various classes and is a best-of-breed sort of class that combines the best of everything. Once you've used it, you won't use anything else.

Example:

<?php
	require_once ROOT_PATH . "/" . SUPPORT_PATH . "/mysql.php";

	$db = new DB(MYSQL_SERVER, MYSQL_USER, MYSQL_PASS, "some_database");

	$result = $db->Query("SELECT * FROM shapes WHERE id > %d AND type = '%s'", 3, "square");
	while ($row = $result->NextRow())
	{
		$coords = unserialize($row->coords);
		foreach ($coords as $x => $y)  echo $x . ", " . $y . "\n";
	}
?>

Keep in mind that PHP functions are case-insensitive. So, if you want to call 'query()' instead of 'Query()', you can. Just try to be consistent.

MySQL::__construct(...)

Parameters:

Returns: Nothing. Triggers an error on failure.

This function initializes a MySQL class instance and optionally connects to a MySQL database server and optionally selects a database. This function is called when the 'new' keyword is used. See the example above.

MySQL::Connect($server, $username, $password, $dbname = "")

Parameters:

Returns: A boolean of true on success, triggers an error on failure.

This function connects an instance of this class to a MySQL database server and optionally selects a database. If a connection is already established for the instance, this function will disconnect the old connection and start a new one.

This function attempts to switch the default language to general UTF-8 via a "SET NAMES 'utf8'" query. Errors during this initial query are ignored.

MySQL::Disconnect()

Parameters: None.

Returns: A boolean of true if the connection was successfully disconnected, false otherwise.

This function disconnects a MySQL connection created with DB::Connect().

MySQL::UseDB($dbname)

Parameters:

Returns: A boolean of true if the database change was successful, a boolean of false if the connection has not been established, and triggers an error if the database change fails.

This function selects a new database for an existing connection.

Note: MySQL has historically had cross-database join issues involving performance. While it may be convenient to create multiple databases for readability, my experience is that MySQL tends to perform better when all database tables for a site are in one database. That said, MySQL starts having issues when a database grows to about 500 tables in a single database and serious problems start happening around 10,000 tables. That is a lot of tables and most sites will never reach that number.

MySQL::Query($sql, ...)

Parameters:

Returns: A DB_Statement instance on success, a boolean of false on failure, and triggers an error if the SQL query is invalid.

This function runs a query against the database and returns a result set. See InternalQuery() for details on the parameter list.

If you have a particularly large query to run, don't mind the table being locked until every row has been read, and will be reading every row of the result set, you may wish to consider using UnbufferedQuery(). Normal query calls store the entire result set in memory.

MySQL::UnbufferedQuery($sql, ...)

Parameters:

Returns: A DB_Statement instance on success, a boolean of false on failure, and triggers an error if the SQL query is invalid.

This function runs a query against the database and returns a result set. See InternalQuery() for details on the parameter list.

While this function typically starts returning results immediately and has a significantly reduced memory footprint with large result sets, it has the downsides of requiring every row to be read before the next query can be run and locks the table(s) used during the query.

MySQL::GetRow($sql, ...)

Parameters:

Returns: A DB_Row instance on success, a boolean of false on failure or no rows returned, and triggers an error if the SQL query is invalid.

This function runs a query against the database and returns the first row of the result set. See InternalQuery() for details on the parameter list.

This function is very useful for retrieving exactly one row of data.

MySQL::GetCol($sql, ...)

Parameters:

Returns: An array of the first column of the result set on success, a boolean of false on failure, and triggers an error if the SQL query is invalid.

This function runs a query against the database and returns the first column of each row in the result set. See InternalQuery() for details on the parameter list.

MySQL::GetOne($sql, ...)

Parameters:

Returns: A string containing the value of the the first column of the first row of the result set on success, a boolean of false on failure or no rows returned, and triggers an error if the SQL query is invalid.

This function runs a query against the database and returns the first column of the first row of the result set. See InternalQuery() for details on the parameter list.

This function is very useful for SELECT COUNT(*) queries.

MySQL::GetVersion()

Parameters: None.

Returns: The currently executing MySQL version.

This function gets the version of MySQL that is running. This function is used by the Barebones CMS installer to test a MySQL connection configuration.

Runs a "SELECT VERSION()" query.

MySQL::TableExists($name)

Parameters:

Returns: A boolean of true if the table exists, false otherwise.

This function tests to see if a table exists in the currently selected database.

Runs a "SHOW TABLES LIKE '%L'" query.

MySQL::NumQueries()

Parameters: None.

Returns: An integer containing the number of queries executed.

This function returns the internal query counter for the class instance.

MySQL::ExecutionTime()

Parameters: None.

Returns: A double containing the amount of time spent executing database functions.

This function returns the number of seconds spent executing SQL queries and other database functions (e.g. connecting).

MySQL::InternalQuery($unbuffered, $args)

Parameters:

Returns: A MySQL_DB_Statement instance on success, a boolean of false on failure, and triggers an error/exception if the SQL query is invalid.

This internal function runs a query against the database and returns a result set. Supports unbuffered queries.

The first element of $args is a sprintf()-style SQL query. The following format specifiers are supported:

The remaining elements of the array are the values to substitute in place of the various format specifiers. The most common specifiers are %b, %s, and %d.

MySQL_DB_Statement::Free()

Parameters: None.

Returns: A boolean of true on success, false otherwise.

This function frees the memory associated with a MySQL statement. This function is automatically called by the destructor of MySQL_DB_Statement or when the end of the result set is reached.

MySQL_DB_Statement::NextRow()

Parameters: None.

Returns: A MySQL_DB_Row containing the next row on success, false on failure or when the end of the result set has been reached.

This function returns the next row of the result set in a MySQL_DB_Row object. Typically used in a while loop after a Query() is run:

<?php
	...
	$result = $db->Query("SELECT * FROM my_table");
	while ($row = $result->NextRow())
	{
		...
	}
	...
?>

MySQL_DB_Row::RawData()

Parameters: None.

Returns: An array of columns and values for the row.

This function returns the raw data for a row from a result set. Prefer to access the data using the object-oriented approach (e.g. $row->my_column_name).

MySQL::ConvertToDBDate($ts)

Parameters:

Returns: A string containing an SQL timestamp in date/time format for the selected date suitable for a MySQL query.

This static function returns the date only portion of the SQL timestamp for the specified UNIX timestamp. Typically called with ConvertToDBDate(time()).

MySQL::ConvertToDBTime($ts)

Parameters:

Returns: A string containing an SQL timestamp in date/time format for the selected date and time suitable for a MySQL query.

This static function returns the SQL timestamp for the specified UNIX timestamp. Typically called with ConvertToDBTime(time()).

MySQL::ConvertFromDBTime($ts)

Parameters:

Returns: An integer containing the UNIX timestamp for the SQL timestamp.

This static function converts a standard SQL timestamp string into a UNIX timestamp. Very useful for performing date/time manipulation for display purposes.

POP3 Mail Functions: 'support/pop3.php'

These functions provide parsing routines to extract content from e-mails and a class to communicate with a POP3 server. There are several uses for these functions - some servers require "POP before SMTP" to send e-mail and these functions meet that requirement. They also afford being able to send e-mail to an e-mail address that is checked by an automated script and then the content gets processed in some fashion.

Full MIME parsing, Quoted Printable, and binary transfer support.

For a working example, of how to use the POP3 class, see the Ultimate E-mail Toolkit documentation.

ConvertFromRFC1341($data)

Parameters:

Returns: A string containing the converted data.

This function converts RFC 1341 encoded data (also known as "Quoted Printable") into 8-bit clean data. 8-bit data (e.g. UTF-8) has to be converted into 7-bit clean ASCII for transport across the Internet. This reverses the process.

ConvertFromRFC1342($data)

Parameters:

Returns: A string containing the converted data.

This function converts RFC 1342 encoded header data into UTF-8 data. 8-bit headers have to be converted into 7-bit clean ASCII for transport across the Internet. This reverses the process.

MIMEExplodeHeader($data)

Parameters:

Returns: An array containing the parsed MIME header.

This function parses a single MIME header into its component pieces. The first piece's key is an empty string "". The rest are split up by key => value pairs. This function is called by MIMEParse() and MIMEExtractContent().

MIMEParse($data)

Parameters:

Returns: An array containing the parsed MIME data.

This function parses MIME data into headers, body, and sub-MIME components. It recursively calls itself up to a depth of 10 to parse most MIME content. Do not use the $depth parameter when calling this function (second parameter).

This function is typically used to parse an e-mail message retrieved from a POP3 server. This code also handles non-MIME e-mail content.

MIMEExtractContent($message)

Parameters:

This function takes the output from MIMEParse() and extracts "text/plain" and "text/html" components from the message. It recursively calls itself up to a depth of 10 to parse the content. Do not use the $depth parameter when calling this function (second parameter).

This function is typically used to extract just the text and HTML components of a MIME message that have been parsed by MIMEParse().

POP3::Connect($username, $password, $options = array())

Parameters:

Returns: An array containing the results of the call.

This function connects to a POP3 server using the specified username and password.

The $options array can contain:

While the $options array is optional, the best approach is to be as specific as possible.

POP3::GetMessageList()

Parameters: None.

Returns: An array containing the results of the call.

This function retrieves the list of message IDs and message sizes on the server. This information is returned in key-value ID and size pairs.

POP3::GetMessage($id)

Parameters:

Returns: An array containing the results of the call.

Retrieves a single message from the POP3 server that matches the specified message ID. Message IDs are retrieved with POP3::GetMessageList().

The message is typically processed with the MIMEParse() function and then text and HTML components are further extracted with the MIMEExtractContent() function.

POP3::DeleteMessage($id)

Parameters:

Returns: An array containing the results of the call.

This function deletes a single message from a POP3 server based on the message ID. Message IDs are retrieved with POP3::GetMessageList().

POP3::Disconnect()

Parameters: None.

Returns: A boolean of true if the instance was successfully disconnected from the POP3 server, false otherwise.

This function disconnects from a POP3 server and performs cleanup for a potential future connection with the same instance.

POP3::POP3Request($command, &$rawsend, &$rawrecv, $multiline = false)

Parameters:

Returns: An array containing the results of the call.

This internal function sends a command to the POP3 server and retrieves the response. Drastically simplifies and improves maintainability of the class.

POP3::GetPOP3Response($multiline)

Parameters:

Returns: An array containing the results of the call.

This internal function retrieves a response from a POP3 server.

SMTP Mail Functions: 'support/smtp.php'

These functions provide SMTP mail sending functionality and e-mail address filtering. The mail sending functions directly connect to a SMTP/ESMTP server to send an e-mail and offer more functionality and flexibility than the built-in PHP mail() function.

I'm not responsible with what you choose to do with these functions - that is, try to only do legal stuff with these functions. They are incredibly powerful PHP routines that go far beyond what PHP mail() calls typically do. It is easy to create e-mails that look exactly like they came from a real e-mail client and will get through spam filters.

Due to spam proliferation across the Internet and the fact that each mail server is set up uniquely makes it nearly impossible to diagnose problems with these functions and YOUR mail server. In other words: You are on your own and, in the event of problems, you should contact your web hosting provider. These functions are a good place to start though and offer significantly more functionality than anything you'll likely need.

Full MIME, Quoted Printable, and binary transfer support.

ConvertToRFC1341($data, $restrictmore = false)

Parameters:

Returns: A string containing the converted data.

This function takes an input string of data and converts it into a RFC1341-compliant string. RFC1341 is a hacky workaround to allow 8-bit data to be transmitted cleanly over 7-bit transports (SMTP is a 7-bit transport) in the body of a message. Also known as Quoted Printable. Typically used for e-mail in Latin-based languages (e.g. U.S. English).

ConvertEmailMessageToRFC1341($data, $restrictmore = false)

Parameters:

Returns: A string containing the converted data.

This function takes an input string of data, converts newlines, and then converts the data into a RFC1341-compliant string. See ConvertToRFC1341() for details.

ConvertToRFC1342($data, $lang = "UTF-8", $encodeb64 = true)

Parameters:

Returns: A string containing the converted data.

This function takes an input string and converts it into a RFC1342-compliant string. RFC1342 is a hacky workaround to allow 8-bit data to be transmitted cleanly over 7-bit transports in an e-mail header. Used primarily to encode the name portion of an e-mail address.

By default Base64 encoding is used but Quoted Printable can be used - $encodeb64 can be set to false - when $lang is "ISO-8859-1" or "US-ASCII".

MakeValidIPv4Address($ipaddr)

Parameters:

Returns: A string containing the cleaned up IP address.

This function takes an input IP address, removes invalid characters, and fixes each value. The output IP address isn't guaranteed to work but it will be guaranteed to be valid as far as basic constraints go - four octets, each octet is in the range of 0-255, etc.

ConvertIPv4ToIPv6Hex($ipaddr)

Parameters:

Returns: A string containing two octets of a IPv6 address.

This function takes a valid IPv4 address and converts it into an IPv6 address. No checks are made to see if it is valid prior to conversion - call MakeValidIPv4Address() to convert the address.

Typically only called from MakeValidIPv6Address() to process the '0::127.0.0.1' IPv6 alternate format.

MakeValidIPv6Address($ipaddr)

Parameters:

Returns: A string containing the cleaned up IP address.

This function takes an input IP address, removes invalid characters and blank parts, converts IPv4 addresses into IPv6 addresses, makes each octet four bytes in length, and expands compact fields ('::'). The output IP address isn't guaranteed to work but it will be guaranteed to be valid as far as basic constraints go.

MakeValidEmailAddress($email, $options = array())

Parameters:

Returns: An array containing whether or not conversion was successful, the cleaned up e-mail address, and whether or not the domain passes DNS checks.

This function takes an input e-mail address of the form 'local@domain', parses it one character at a time using a state engine, cleans it up of common mistakes, and validates that the resulting domain is valid. For example, "someone@hotmail,com" would become "someone@hotmail.com". This function allows all non-obsolete address formats.

This function is not a validation routine but it can be used as such. If it successfully completes, just check the resulting e-mail address ('email') for a match with the original. If they match exactly, then the original is valid. This function, however, is much more desirable for its repairing capabilities. It becomes possible to use AJAX to send a query to the server to determine if the address is valid. Instead of saying, "Invalid e-mail address" to the user, it could say, "Did you mean ...?" with the corrected e-mail address.

The $options array can contain the following options:

Checking for the existence of a SMTP mail server via DNS is a great way to avoid bounced e-mail. DNS checking is done with a slightly modified PEAR::Net_DNS library, which is more versatile than the built-in PHP functions that aren't always available for all platforms.

E-mail validation/clean up is hard. As of this writing, Dominic Sayers has a decent test suite. This function passes most tests with flying colors - everything except obsolete address formats - and even passes most of the tests that are supposed to "fail" because of the repairing capabilities, which only a state engine could accomplish.

EmailAddressesToNamesAndEmail(&$destnames, &$destaddrs, ...)

Parameters:

Returns: A boolean of true if at least one valid e-mail address was successfully processed, false otherwise.

This function takes a string of '"name" <emailaddr>', 'name <emailaddr>', or 'emailaddr' and extracts each component. Multiple e-mail addresses can be separated with commas (',') [preferred] or semi-colons (';').

This function attempts to deal with malformed strings as best as possible but there are limits as to what it can do. MakeValidEmailAddress() is called for each e-mail address to check its validity.

EmailAddressesToEmailHeaders($emailaddrs, $headername, ...)

Parameters:

Returns: A string containing an e-mail header if the e-mail addresses were successfully processed, an empty string otherwise.

This function generates a valid mail header from one or more e-mail addresses. If $headername is an empty string, e-mail addresses will be returned without a header name.

GetEmailUserAgent($type)

Parameters:

Returns: A string containing a valid user agent for the specified e-mail client.

This function returns a popular user agent string. These aren't always up-to-date but are usually good enough to get the job done on servers that require a user agent and helps to get past most spam filters. If you feel a string is too out of date, post a message to the forums.

ProcessSMTPRequest($command, &$code, &$data, &$rawsend, &$rawrecv, $fp, $debug)

Parameters:

Returns: A boolean of true if the $fp socket handle is still successfully connected at the end of the function, false otherwise.

An internal function to send a command to a SMTP server and extract the response code and data. Correctly handles responses with multiple lines.

SMTP_RandomHexString($length)

Parameters:

Returns: A randomly generated string containing hexadecimal letters and numbers (0-9, A-F).

An internal function to generate a unique string for the 'Message-ID' portion of an e-mail.

SendSMTPEmail($toaddr, $fromaddr, $message, $options = array())

Parameters:

Returns: An array containing the results of the call.

This function sends an e-mail message by directly connecting to a SMTP server. The returned array has a 'success' boolean that can be used to determine success or failure of the call. On failure, 'error' and 'info' are also defined with the technical error message and additional information respectively.

The $options array can contain all the $options for MakeValidEmailAddress() plus:

Some SMTP servers may use the HELO/EHLO 'hostname' option for blocking incoming messages via SPF records.

While it might seem to make sense to connect to the target SMTP server (the "To" address), that isn't how e-mail works. The source SMTP server (the "From" address) is the correct server to connect to. On many web hosts, the mail server is "localhost" but not always.

Some popular web hosts will block SMTP requests made with this function. PHP mail() also tends to not work on such hosts. The host isn't usually specifically blocking sending e-mail via the web server but rather generally blocking until a POP3 login occurs for the same "From" address. This is known as POP before SMTP. To successfully send e-mail in this situation, you should attempt to send an e-mail and, if it fails, then use the POP3 functions to connect to the mail server. Once the POP3 login is successful, attempt to send the same message again over SMTP. If the message is still blocked, then something else is the problem.

ConvertHTMLToText_FixWhitespace($data, &$depth)

Parameters:

Returns: A string with whitespace modified/removed.

An internal function to modify whitespace for a given chunk of data. Used by ConvertHTMLToText().

ConvertHTMLToText($data)

Parameters:

Returns: A string containing the formatted text version of the HTML.

This function is intended to be used to generate a text version of a HTML document for sending via e-mail but is versatile enough for most other purposes. The output attempts to create a visually appealing version of the text found within the HTML.

The downside to this particular function is that it is rather slow. As the number of HTML tags increases, the slower this function runs. A complex template can take up to five seconds to parse. On the upside, the output is generally very good.

MIME_RandomString($length)

Parameters:

Returns: A string containing alphanumeric characters suitable for MIME encoding.

An internal function to generate MIME headers for e-mails.

SendEmail($fromaddr, $toaddr, $subject, $options = array())

Parameters:

Returns: An array of processed information, the result of the mail() command, or the result of SendSMTPEmail() depending on the various $options. The default is to return the result of SendSMTPEmail().

This function sends an e-mail message or returns processed data intended to be sent via e-mail. In terms of capabilities, this function does it all: E-mail address validation and cleanup, DNS checking, direct SMTP server communication, plain-text and HTML e-mails, MIME, attachments, etc. It does its best to look and smell like an actual e-mail client.

The $options array can contain all the $options for SendSMTPEmail() plus:

The optional 'attachments' array can contain a number of different options:

When specifying an attachment that someone can open, only use 'name'. For inline attachments, such as embedded images, do not use 'name' but use either 'location' or 'cid' instead (avoid using both). Inline images are generally not blocked by e-mail clients. For most web developers who want to use inline images, 'location' is probably the easiest to use but 'cid' is more likely to get through spam filters since that is what most e-mail clients use.

CSPRNG Functions/Classes: 'support/random.php'

These functions and classes provide a CSPRNG to generate root seeds and user session tokens. These also make up a product with the uncreative name of CSPRNG. See the product's documentation for instructions on use.

Functions and classes are prefixed with 'RSG_' because the primary reason for the library is to be a Random String Generator. The ability to generate random numbers is an extra feature.

Do not use this class with the two root seeds in Barebones CMS. Keep root seeds isolated from each other on a per application basis.

RSG_GetRootSeedURLs()

Parameters: None.

Returns: An array containing key-value pairs of secure URLs mapped to an alternate, less secure URL and whether or not to reduce the content with a hash.

Example:

array(3) {
  ["https://www.random.org/integers/?num=100&min=0&max=255&col=10&base=16&format=plain&rnd=new"]=>
  array(2) {
    ["alt"]=>
    string(89) "http://www.random.org/integers/?num=100&min=0&max=255&col=10&base=16&format=plain&rnd=new"
    ["reduce"]=>
    bool(false)
  }
  ["https://www.fourmilab.ch/cgi-bin/Hotbits?nbytes=128&fmt=bin"]=>
  array(2) {
    ["alt"]=>
    string(58) "http://www.fourmilab.ch/cgi-bin/Hotbits?nbytes=128&fmt=bin"
    ["reduce"]=>
    bool(false)
  }
  ["https://www.grc.com/passwords.htm"]=>
  array(2) {
    ["alt"]=>
    string(0) ""
    ["reduce"]=>
    bool(true)
  }
}

This returns the list of trusted URLs for improving entropy when generating root seeds. Intended for use with the 'url' option that is passed to RSG_GenerateRootSeed(). The 'alt' option offers a way to recover from a retrieval failure at the cost of reduced cryptographic strength. The 'reduce' option specifies whether or not the $reduce option of RSG_WriteSeedData() is true or false.

The trusted list of URLs have rate limits on a per-IP address basis. Do not use these more frequently than two or three times every 24 hours when generating root seeds or there is increased risk of being blocked by the various providers.

The URLs returned from this function are not the only ones that can be used but they are the only trusted URLs with high-quality random data sources with HTTPS RESTful APIs. Other URLs can be used too but will have a slightly lower impact on the resulting cryptographic strength.

RSG_GetURL($url)

Parameters:

Returns: An array containing the results of the call.

This takes a URL and attempts to retrieve it. If the HTTP library functions are available, this will attempt use those to retrieve the page. Otherwise, this falls back to file_get_contents().

RSG_WriteSeedData(&$data, &$hash, $str, $reduce = true)

Parameters:

Returns: A numeric value to be used to calculate a new cryptographic strength.

This internal function is used to build upon previous calls to this function with new sources of entropy. When $hash is false, $reduce is used to help save memory by hashing the data being input and packing the result. When $hash is a resource, all data is run through the SHA-512 hash algorithm in a streaming fashion, so reduction doesn't matter.

RSG_GenerateRootSeed($options = array())

Parameters:

Returns: An array containing the results of the call.

This function generates a root seed. Root seeds are expensive to create and take approximately two seconds per seed to generate. When leveraging the 'url' option using the RSG_GetRootSeedURLs() call to get trusted URLs, cryptographic strength is greatly improved. An application should warn users if the resulting 'strength' of a root seed is less than 5 or simply refuse to use the root seed depending on the application.

Once a root seed has been generated, it should be stored somewhere and kept safe. Root seeds can be used to generate as many additional tokens as needed.

RSG_GenerateToken($rootseed, $entropy = "")

Parameters:

Returns: A hex encoded string containing a token.

This function takes a root seed, assumed to be secure and have sufficient cryptographic strength for the application, along with optional, additional entropy, and generates a new token. This function is much faster than RSG_GenerateRootSeed() and is designed to generate any number of tokens.

RSG_Stream::Init($rootseed)

Parameters:

Returns: Nothing.

This function initializes a RSG_Stream instance with the root seed that will be used and resets all internal variables.

RSG_Stream::RandomBytes($length, $entropy = "")

Parameters:

Returns: A string containing random bytes.

This function assumes an initialized RSG_Stream object and returns a string of $length bytes of random data based on the root seed and input entropy. Calls RSG_GenerateToken() behind the scenes to turn its output into a stream of random bytes.

RSG_Stream::RandomInt($min, $max, $entropy = "")

Parameters:

Returns: A boolean of false if $max is less than $min. Otherwise, returns a string containing a random integer from $min to $max (inclusive).

This function assumes an initialized RSG_Stream object and returns a random integer in the range of $min and $max (inclusive) based on the root seed and input entropy.

Calls RSG_GenerateToken() behind the scenes to turn its output into a stream of random bytes that get converted into the appropriate number of bits in the selected range of numbers. This function throws out numbers that do not immediately fall into the range based on the calculated bitmask, which is the correct way to select an arbitrary random number but it does mean that selection of integers is slower than bytes.

RSG_Stream::AddMoreBits()

Parameters: None.

Returns: Nothing.

This internal function uses RSG_GenerateToken() to generate more bits of data when RandomBytes() and RandomInt() exhaust the available supply.

RSG_NormalizedStream::Init($min, $max, $rootseed)

Parameters:

Returns: A boolean of false if $max is less than $min, true otherwise.

This function initializes a RSG_NormalizedStream instance with the root seed that will be used and resets all internal variables so that calls to RandomInt() return values between $min and $max (inclusive).

RSG_NormalizedStream::RandomInt($entropy = "")

Parameters:

Returns: A string containing a random integer from $min to $max (inclusive) as specified by the Init() call.

This function assumes an initialized RSG_Stream object and returns a random integer in the range of $min and $max (inclusive) along a standard normal distribution. Each number in the range can only be used one time. Once all numbers in the range have been used one time, the process starts over.

RSG_GenerateRandString($seed, $entropy = "", $size = 32)

Parameters:

Returns: A string containing randomly selected alphanumeric characters.

This function uses RSG_Stream::RandomInt() to generate a random string with only alphanumeric characters (0-9, A-Z, and a-z). Useful for generating shorter random strings.

IP Address Class: 'support/ipaddr.php'

The IPAddr class transforms and matches IP addresses. This class works primarily with IPv6 addresses but will automatically detect IPv4 addresses and patterns and act appropriately. Every IPv4 address has an IPv6 equivalent and all new applications should be built to support IPv6 because it is "the future".

This class also slices, dices, chops, minces, and deals with security vulnerabilities involving IP addresses like you've never seen before! Yes, Virginia, there is a class of security vulnerabilities involving IP addresses.

IPAddr::NormalizeIP($ipaddr)

Parameters:

Retruns: An array containing an IPv6 address, a short version of the IPv6 address, an IPv4 address (or an empty string).

This static function takes an input IP address string and normalizes it to a full IPv6 address. Then it takes that and creates the short IPv6 and IPv4 addresses from that. The result is normalized output that an application can rely upon.

IPAddr::GetRemoteIP($proxies = array())

Parameters:

Returns: A normalized remote IP address.

This static function takes the usual $_SERVER["REMOTE_ADDR"] IP address and normalizes it. If any trusted proxies are specified, any relevant "HTTP_X_FORWARDED_FOR" and "HTTP_CLIENT_IP" headers are analyzed looking for the real remote IP address, stopping at the first untrusted proxy. Valid HTTP header types for $proxies are "xforward" and "clientip".

IPAddr::IsMatch($pattern, $ipaddr)

Parameters:

Returns: A boolean of true if the IP address matches the pattern, false otherwise.

This static function normalizes the IP address if it isn't already normalized and then attempts to match the input pattern against the address. The pattern must contain the correct number of ':' (colon) or '.' (dot) characters corresponding to an IPv6 or IPv4 address respectively. Special characters may be used within each segment of the pattern:

IPv6 segments can also contain IPv4-style notation, but it looks a little weird (e.g. '*:*:*:*:*:*:127.0:0.1' notice the colon).

© CubicleSoft