To directly use the libtld library within PHP. More...

#include <php.h>
#include "libtld/tld.h"

Include dependency graph for php_libtld.c:

Functions
zend_module_entry *	get_module (void)
	Function called to retrieve the module information.

	PHP_FUNCTION (check_email)
	Declaration of the check_email() function in PHP.

	PHP_FUNCTION (check_tld)
	Declaration of the check_tld() function in PHP.

	PHP_FUNCTION (check_uri)
	Declaration of the check_uri() function in PHP.

Variables
const zend_function_entry	libtld_functions []
	The list of functions we offer to PHP.

zend_module_entry	libtld_module_entry
	The module definition.

Detailed Description

This file declares the necessary functions to interface the libtld library in the PHP environment.

Some of the code is based on information found in various locations. However, the Zend information for creating PHP variables is pretty well explained on this page:

http://devzone.zend.com/317/extension-writing-part-ii-parameters-arrays-and-zvals/

check_tld($domain);

See also: tld()

This PHP function takes one string representing a domain name including a valid TLD (top level domain.)

The result of the function is an associative array with the following fields:

$result["result"]

The result returned by the check_tld() function. This is one of the TLD_RESULT_... values as defined in the php_libtld.php "header" file. Note that a result other than TLD_RESULT_SUCCESS does not mean that the TLD wasn't found. However, if found, it either is not in use or you are missing a sub-TLD name (for example .uk cannot be used by itself except with a very few domains; most domains must use .co.uk, .ac.uk, etc.).

$result["category"]

The result category. This is a number as defined in the php_libtld.php "header" file. Most TLDs have the TLD_CATEGORY_COUNTRY value. This is useful information, but in most cases useless to make use of the domain name itself.

$result["status"]

The status of this TLD as defined by IANA and other similar organization. The status is a number as defined in the php_libtld.php "header" file. Only TLDs that are marked as TLD_STATUS_VALID should be used. Other TLDs should either not be used or a user intervention should apply. For example, the TLD_STATUS_PROPOSED should not be used until the TLD is in effect, but some precursors may want to allow such as they test that TLD.

$result["offset"]

This value is the offset where the TLD starts in the unmodified input string. You can therefore extract the result using this offset in a substr() call:

$domain = "some.tld.here.com";
$result = check_tld($domain);
// IMPORTANT: here test that $result is valid... do not use the offset otherwise
$tld = substr($domain, $result["offset"]);
$domain_name = substr($domain, 0, $result["offset"] - 1);

$result["country"] (optional)

If the category was set to TLD_CATEGORY_COUNTRY, then this entry defines the country that owns this TLD. For example, ".fr" is owned by France.

Note that this field is NOT defined if the category is not country.

$result["tld"] (optional)

If the function succeeded and a TLD is available, then this variable is the TLD part of the domain. This is similar to taking that TLD using the substr() function as shown in the $result["offset"].

check_uri($uri, $protocols, $flags);

See also: tld_check_uri()

The check_uri() function verifies that the specified $uri is indeed a valid URI. The $protocols is a list of schemes that the check_uri() should accept. Any scheme that is not listed in that parameter are viewed as invalid (unknown.) The flags define a few different ways to behave.

The check process is to detect the scheme, verify that it is a supported (acceptable) scheme, process the sub-domains, domain, and TLD, then parse the path, variables, and anchor if present.

The result of the function is an associative array that matches the array returned by the earlier check_tld() function.

check_email($emails, $flags);

See also: tld_email_parse()

This function parses a string of emails and returns an array with the results. The array is composed of one sub-array per email found in the $emails parameter and indexed numerically starting at 0. The main array also includes the result of the tld_email_parse() function as an integer associated under the name "result".

$r = check_email("blah@m2osw.com", 0);
if ($r["result"] == TLD_RESULT_SUCCESS)
{
  // the email is valid check more about it
  $max = $r["count"];
  for($i = 0; $i < $max; ++$i)
  {
     // get email $i
     $e = $r[$i];
     // now $e is one of the emails, you can work on it...
     $canonical = $e["canonicalized_email"];
  }
}

If the result is not TLD_RESULT_SUCCESS, then the list of emails will be empty (not even defined) and the "count" parameter will be zero. Otherwise, each email is an array with the following fields:

$e["group"] (optional)

The name of the group. This is rarely used and in most cases it will be empty. Note that when a group is defined, one entry appears representing the group itself. That special entry has the group parameter defined and all the other parameters are the empty string.

Note that because the group is rarely used it was marked as optional, so if not group was defined this parameter is not defined.

$e["original_email"]

The email as found in the original string, with all white spaces, new lines, and carriage returns stripped from the start and end of the email.

This entry may still include comments and it may mix atom syntax with quoted strings and domain literal when those could be simplified.

$e["fullname"]

The display name is called fullname in our library. In most cases, this is used to name the owner of the mailbox; for example "Alexis Wilke" or "Wilke, Alexis".

This string may be empty since the display name is not required.

$e["username"]

The username part of the email address. This is the atom that appears before the @ character. In most cases, these are atom characters, although when the name is written between double quotes, many more characters can appear in a username (For example, "\\"" represents a user named ".) \li $e["domain"] The domain part of the email address. This is the atom that appears after the @ character. As with the username, the domain names are generally limited to atom characters but it is possible to make use of other characters when written between square brackets. Note that before returning the tld_check_uri() function verifies that the domain is valid so in all cases this domain information is likely correct. Although note that we do not check whether the domain is currently registered (no whois...) The check is done against the TLD. So if you are validating an email entered by a user and, for example, they put an extra m at the end as in [m2osw.comm], then the parser fails and you do not get any information about this email. \li $e["email_only"] The email-only field includes just and only the email. That is the part with the user name, the @ character, and the domain name. The user name and domain are protected as required (in the event it was necessary.) In a way this is a canonicalized version of the email address. \li $e["canonicalized_email"]

The canonicalized email is the display name (fullname), the user name, and the domain name all in one as we most often see in complete email addresses.

This email does not include any comments, group, or useless spaces. It is as short as possible. Also if one of the parts needs quotation, it is used, but if no quotations are necessary, then none are used.

Definition in file php_libtld.c.

Function Documentation

◆ get_module()

get_module ( void )

This global function is used to retrieve the module definition of this PHP extension. That definition includes all the necessary declarations for PHP to understand our extension.

Returns: The pointer to the module structure.

Definition at line 267 of file php_libtld.c.

References libtld_module_entry.

◆ PHP_FUNCTION() [1/3]

PHP_FUNCTION ( check_email )

Definition at line 353 of file php_libtld.c.

References tld_email::f_canonicalized_email, tld_email::f_domain, tld_email::f_email_only, tld_email::f_fullname, tld_email::f_group, tld_email::f_original_email, tld_email::f_username, list(), tld_email_alloc(), tld_email_free(), tld_email_next(), tld_email_parse(), and TLD_RESULT_SUCCESS.

◆ PHP_FUNCTION() [2/3]

PHP_FUNCTION ( check_tld )

Definition at line 275 of file php_libtld.c.

References tld_info::f_category, tld_info::f_country, tld_info::f_offset, tld_info::f_status, tld_info::f_tld, and tld().

◆ PHP_FUNCTION() [3/3]

PHP_FUNCTION ( check_uri )

Definition at line 313 of file php_libtld.c.

References tld_info::f_category, tld_info::f_country, tld_info::f_offset, tld_info::f_status, tld_info::f_tld, and tld_check_uri().

Variable Documentation

◆ libtld_functions

libtld_functions

Initial value:

= {
 
    PHP_FE_END
}

This table is the list of functions offered to the PHP interpreter from our library. The list is null terminated.

Definition at line 238 of file php_libtld.c.

◆ libtld_module_entry

libtld_module_entry