Location: PHPKode > scripts > Hololib > hololib/Hololib.txt
Welcome to Hololib. This is a library of PHP utility functions, provided
by Holotech Enterprises (http://www.holotech.net/)

This is free software, in the sense of "free beer" *and* "free speech"!
How cool is that? It costs nothing, and you may use and modify it as
desired. You may redistribute it freely, so long as it is unmodified and
has this documentation file attached.

Questions, comments, praise, criticism and beer are welcome.
Email hide@address.com

This library requires PHP4

Hololib and this document Copyright (C) 2000-2006 Holotech Enterprises

void hl_ArrayTrim ( array &$array )
A simple function to trim empty elements from an array.
  $Array - The array to be trimmed

mixed hl_ArrayDump (
  array $array [, bool $echo [, bool $text [, string $encap [,
  bool $html]]]] 
Dumps the contents of an array recursively. This function has a couple of
advantages over print_r() or var_dump(); namely, it can output HTML or
text and it can convert < and & characters to HTML entities for easier
HTML viewing. While it doesn't contain as much information as var_dump(),
I feel its output is cleaner and easier to read. Of course, I could be
biased. Anyway, it's been around since before either of those functions,
and has served me well.

  $array      - The array to dump
  $echo       - Whether to echo or return the output; default true
  $text       - Output text rather than HTML; default false
  $encap      - Character(s) to encapsulate array elements; default null
  $html       - Convert < and & to entities; default true

void hl_ArrayToList ( 
  array &$array [, string $separator [, string $conjunction]]
Converts an array to a string list. It has the advantage over implode() of
being able to specify a different conjunction between the last elements.

  $array       - The array to be converted.
  $separater   - Optional, the character(s) to put between the elements.
                 The default is ', '
  $conjunction - Optional, the character(s) to put between the last two
                 elements. The default is 'and'.

string hl_BoxIt ( string $Message [, int $Wrap] )
Breaks a string down into lines and draws a text box around it. Line breaks
are respective of word boundaries.

  $Message    - The message to box
  $Wrap       - Optional, the length to break the lines at. Default is 70

void hl_BreakOut ( string $String )
Breaks out a string character by character, displaying ASCII values. This
is useful for finding out exactly what characters a string contains,
especially when it contains nulls or other non-printing characters. It has
one parameter, the string to be broken out.

string hl_CardGen (
  mixed $StartWith [, int $Digits [, string $Split [, int $Size]]]
Generates a validly-formatted credit card number. Numbers generated by
this function will pass the hl_ValCard fuction. It is useful for generat-
ing test numbers.

  $StartWith  - Either specific digits to start with, or a card type code,
                which will automatically generate a number for that type.
                The type codes are:
                mcd - MasterCard
                vis - Visa
                amx - American Express
                dsc - Discover
                dnc - Diners Club
                jcb - JCB (That was a tough one)
                enr - EnRoute
                dlt - Delta
                swi - Switch
  $Digits     - The number of digits to generate. The default is 16, or
                dependent on the type code. If you use a type code it will
                override this parameter.
  $Split      - Optional, the character(s) to put between number segments.
                The default is '-'
  $Size       - Optional, the segment size. The default is 4.

string hl_CardType ( string $CardNum )
Given a card number, this function returns a type code indicating what
card type it is. The type codes are listed under hl_CardGen. Note that
Delta and Switch will be interpreted as Visa.

bool hl_CheckVers ( string $CheckVers [, string $PgmVers] )
Compares two version number strings.
  $CheckVers  - The version number to check.
  $PgmVers    - Optional, the version number to check against. The default
                is the installed PHP version.

Returns TRUE if $PgmVers is greater than or equal to $CheckVers.

string hl_DateSelector ( array $Parameters )
This function generates HTML <SELECT> fields for selecting dates. It has
12 parameters but only one argument, and that one is optional. It'll all
make sense; trust me -- I'm a professional. The parms are:

  $Prefix     - A prefix for the field names
  $FirstYear  - The first year in the year selector; default null or the
                current year, depending on $NullDate.
  $NumYears   - The number of years in the year selector; default 5
  $YearSet    - The year to set; default 0 or $FirstYear
  $YearSeq    - 'ASC' or 'DSC' to indicate ascending or descending
  $MonthSet   - The month to set; default 0 or January
  $DaySet     - The day to set; default 0 or 1
  $NullDate   - Whether to include null values in the fields; default true
  $ShortMo    - Whether to use short month names; default false
  $Suffix     - A suffix for the field names
  $ZPad       - Whether to zero-pad values; default false
  $Order      - The order of the fields; default MDY
  $SetToday   - Whether to set today's date; default false

$YearSet and $DaySet can be set to -1 to eliminate the associated selector.

All the parameters are optional. If none are set, the function will return
fields named 'Month', 'Day' and 'Year' in that order. There will be five
years in the Year selector, long month names in the Month selector, Null
options in all selectors, and all selectors set to the Null option.

There are three ways to pass parameters to this function: 1) create an
associative array named $hl_DateSelector in the global space; 2) simply
set the variables in the global space with the prefix 'hl_'; 3) pass an
associative array in the function call:

  $HTML = hl_DateSelector($DateParms);

If a value exists in more than one of these spaces, the order of prece-
dence is call-time values, $hl_ variables, $hl_DateSelector values.

array hl_GetIt (
  string $URL [, array $DataStream [, string $UP [, array $Headers]]]
Performs an HTTP GET on a URL, with optional query string, authentication
and custom headers.

  $URL        - The URL to GET.
  $DataStream - Optional associative array of data to form a query string,
                with variable names as keys and data as values.
  $UP         - Optional username:password
  $Headers    - Optional associative array of extra headers

If the request succeeds, the function returns the server response as an
associative array, with the following elements:

  Response    -> The entire server response
  Status      -> The complete server status line
  StatCode    -> The server status code
  StatMesg    -> The server status message
  [Header]    -> [Value] One for each response header
  Body        -> The response body

void hl_LineWrap ( string &$string [, int $width [, string $break]]] )
Breaks a string down into lines, respecting word boundaries.

  $string     - The string to be wrapped
  $width      - Optional, the length to break the lines at. Default is 75.
  $break      - Optional, the character(s) to break with. The default is
                the linebreak character(s) for the system the script is
                running on: CRLF for Windows, LF for *nix and CR for Mac.

bool hl_LuhnMod10 ( string $Number )
Checks a number with the Luhn mod 10 formula. Credit card numbers, bank
routing numbers and others conform to this formula.

array hl_ParseHTML (
  string $HTML, string $TagList [, bool $ParseTags [, bool $CloseTags [,
  bool $Reverse]]]
Parses HTML and returns specified tags, optionally with their attributes.

  $HTML       - The HTML to be parsed
  $TagList    - A comma-delimited list of tags to look for
  $ParseTags  - Indicates whether to parse the tags for their attributes.
                The default is true.
  $CloseTags  - Indicates whether to also return closing tags. The default
                is false.
  $Reverse    - Indicates whether to reverse-sort the result before
                returning it. The default is false.

The result returned by this function is an associative array, one element
per tag. The key is the zero-offset of the tag in the HTML. The element is
an associate array with keys 'tag' and 'len', with the tag and its length,
respectively. If $ParseTags is true, there will be an additional element
with the key 'TAG', and the tag type as the value; there will also be an
element for each attribute, with the attribute name as the key and its
value as the value. For example:

  1802 (The offset)
    tag   -> <INPUT TYPE=CHECKBOX NAME="Approval" VALUE="2">
    len   -> 49
    TAG   -> INPUT
    NAME  -> Approval
    VALUE -> 2

array hl_ParseName ( string $Name [, bool $Predicate] )
Breaks a name down into prefix, first, middle, last and suffix. It has two

  $Name       - The name to be parsed
  $Predicate  - Whether to return the family name predicate as a separate
                element. Default is false.

The family name predicate is the 'van' or 'de' portion in a name like 'van
Winkle' or 'de Palma'. If $Predicate is false, the predicate will be
returned as part of the family name (last name).

This function returns an associative array with keys 'Prefix', 'First 
Name', 'Middle Name', 'Predicate' (conditional), 'Last Name' and 'Suffix'.

array hl_ParseTag ( mixed $Tags )
Parses one or more tags and returns the attributes with their values. This
function has one parameter:

  $Tags       - Either a string with a single tag, or an array of tags.

The result returned by this function is an associative array in the same
format as hl_ParseHTML, but with the keys that were passed to it (or 0 if
just a single tag was passed) instead of the offsets as keys.

array hl_PostIt (
  string $URL, array $DataStream [, string $UP [, array $Headers]]]
Allows you to POST data to a URL, with optional authentication and custom

  $URL        - The URL to POST to.
  $DataStream - An associative array of data to post, with variable names
                as keys and data as values.
  $UP         - Optional username:password
  $Headers    - Optional associative array of extra headers

If the request succeeds, the function returns the server response as an
associative array, with the following elements:
  Response    -> The entire server response
  Status      -> The complete server status line
  StatCode    -> The server status code
  StatMesg    -> The server status message
  [Header]    -> [Value] One for each response header
  Body        -> The response body

string hl_SayNum (
  string $Number [, string $Punctuation [, string $Language]]
The newest member of the Hololib family, this takes a number and converts
it to words.

  $Number      - The number to spell out
  $Punctuation - A string indicating what punctuation to use. It can
                 contain any combination of these characters:
                 - Use hyphens; for example: fifty-four
                 , Use commas between thousands
                 ^ Capitalize words
  $Language    - Which language to use. Currently supports EN and ES.
                 Default is EN.

The $Punctuation parameter is optional; the default is '-'. This function
uses American billions rather than British.

array hl_TimeTil ( int $Time1, int $Time2 )
This function takes two Unix timestamps and returns the number of days,
hours, minutes and seconds between them. $Time2 must be greater than

void hl_TitleCase ( string &$String [, string $Separators] )
Converts a string to true title case, capitalizing the first word and all
major words. The word separators parameter is optional. The default is any
whitespace character (space, htab, vtab, ff, cr, lf) plus the hyphen. To
keep these separators and add to the list, put '+' as the first character
of this parameter. For example:

  hl_TitleCase('time/tide calculations and charts', '+/');

This will use the default separators plus '/'.

mixed hl_ValCard ( string $CardNum [, string $Exp [, string $Type]] )
Validates a credit card number with the Luhn formula, and optionally with
card-specific formatting and/or expiration date.

  $CardNum    - The number to be checked
  $Exp        - Optional, expiration date as MMYY. If omitted, the expira-
                tion check is skipped.
  $Type       - Optional, a card-type code. The type codes are listed
                under hl_CardGen. If omitted, the card-specific format
                check is skipped.

Returns false if the number fails the check or zero if the expiration
check fails. Otherwise returns true.

bool hl_ValEmail (
  string $Addr, int &$Fail [, int $Level [, int $Timeout]]
Validates an email address.

  $Addr       - The address to check
  $Fail       - On failure, the level at which it failed
  $Level      - Optional, the level of checking to do. The default is 2.
  $Timeout    - Optional, the timeout in seconds for a server response at
                Level 5. The default is 3 seconds.

This function has five levels of checking; each level above 1 includes all
the checks of the prior level(s). Level 1 checks that: a) There is an @
sign with something on the left and something on the right; b) to the right
of the @ there is at least one dot, with something to the left and to the
right; c) The string to the right of the last dot is two or three charac-
ters long, or one of the new, longer TLDs.
Level 2 checks to see if the string after the dot is a valid TLD (i.e. 
com, net, org, edu, gov, mil, int, arpa, aero, coop, info, museum, name or
a two-letter country code). If the TLD is a country code, it checks that
the next level domain is valid (com, net, org, edu, gov, mil, co, ne, or,
ed, go, mi -- for example, mydomain.com.au).

Level 3 checks to see if there is an MX record for the domain. Level 4
attempts to connect to port 25 on an MX host, and Level 5 checks if
there's an answer. 

Level 1 is (as far as I know) bulletproof: if the address fails level 1,
it's invalid. Level 2 is still pretty solid, but might fail a valid
address if there's a TLD I didn't know about (not) or others are added
(could happen). Levels 3-5 are less reliable, the higher you go.
Factually, in the end there is no completely foolproof way to check the
validity of an email address except to send something to it and see whether
it bounces. For this reason, I don't recommend that you flatly reject an
email address if it fails level 3, 4 or 5. You may want to ask the visitor
to confirm that it's correct, but then you should accept it. There are
simply too many ways a valid email address could fail levels 3, 4 or 5 at
any given time, and still work at another time.

Note that a network connection and ability to do socket operations are
required for levels 3, 4 and 5.

void hl_VarSub (
  &$string [, bool $KeepNulls [, string $Prefix [, string $Delim]]]
Performs variable substitution on a string. It searches for instances of a
pattern indicating a variable name, and substitutes it with the variable
value. The default pattern is {{Name}}.

  $String     - The string to perform substitution on
  $KeepNulls  - If this is set to TRUE, patterns for which the variable is
                not set will be preserved. The default is false.
  $Prefix     - Variables with this prefix will be skipped
  $Delimiter  - The pattern delimiters. The default is {}
The pattern will consist of two opening delimiters, a variable name, two
closing delimiters. It is not recommended that you use [] as your delimi-
ters, as you will then not be able to process array values.

You can limit the length of the value by putting a comma followed by a
number, after the variable name. For example {{Company,10}} will return
only the first 10 characters of $Company. If you include a period after
the length component, the last three characters of the truncated value
will be replaced with an ellipse (...)

Invalid variable names will be skipped. The regex used to determine if a
variable name is valid, does not work in some cases. If the function is
not working at all, set $hl_AltPattern to TRUE in your global space to use
an alternate pattern. If you use the alternate pattern, variable names
must consist of only A-Z, 0-9 and the underscore -- international letters
are not supported by the alternate pattern.

Return current item: Hololib