Using Sam’s Whois
The file samswhois.inc.php provides an easy way to use the samswhois.class.php class. Using it, you can install a basic whois lookup with just one line of code:
A Simple Example
<html> <head> <title>SamsWhois Example</title> <link rel="stylesheet" type="text/css" href="swstyles.css" /> </head> <body style="font-family: verdana, arial; font-size: 10pt;"> <?php include(dirname(__FILE__).'/samswhois/samswhois.inc.php'); ?> </body> </html>
The code above will display the following form and handle all processing and display of the whois lookup:
Setting Options
Most of the options for Sams Whois can be set by setting various variables in the script above before the line that includes samswhois.inc.php.
For example, the following code turns on caching, turns on the use of a secure code image, limits the tlds supported to com, net and org, and displays a drop-down select box for the user to choose the tld from:
<html> <head> <title>SamsWhois Example</title> <link rel="stylesheet" type="text/css" href="swstyles.css" /> </head> <body style="font-family: verdana, arial; font-size: 10pt;"> <?php // limit tlds to com,net and org $swTlds = 'com,net,org'; // display a drop-down select for the tlds $swTldOptions = true; // cache results for 60 minutes $swCacheLifetime = 60; // require user to enter a 4 digit code $swSecure = true; include(dirname(__FILE__).'/samswhois/samswhois.inc.php'); ?> </body> </html>
This code will result in a form like this and will handle all aspects of checking the secure code, looking up the domain and displaying the result:
As you can see above, customizing the options is a simple process. The following options are available for customization:
Tld Related Options
Set the following variables to alter which tlds are available and whether or not they are displayed:
<html> <head> <title>SamsWhois Example</title> <link rel="stylesheet" type="text/css" href="swstyles.css" /> </head> <body style="font-family: verdana, arial; font-size: 10pt;"> <?php // Only lookup com, net and org domains. // Set to '' (the default) to lookup all supported tlds. $swTlds = 'com,net,org'; // Set to true to display a list of supported tlds below the form in the format: // Supported Tlds: com,net,org,info,etc // Default is false (ie. do not display the list. $swListTlds = true; // Include a <select> drop down box for the user to choose the tld to lookup. // If the user enters a tld with the domain name, then this is used instead. // Default is false. $swTldOptions = true; // If $swTldOptions = true or $swListTlds = true, display the tlds alphabetically. // The default (false) causes them to be displayed in the order they are listed in // the config.txt file, or in the $swTlds variable (if set). $swAlphabeticalTlds = false; include(dirname(__FILE__).'/samswhois/samswhois.inc.php'); ?> </body> </html>
Caching Options
Sams Whois has built-in support for caching whois lookup results so that the next time the domain is looked-up these results can be used instead of re-querying the whois servers.
This reduces the amount of work the script has to do, speeding it up. It is recommended that you do not cache results for more than 24 hours.
To use caching, you need to set the permissions of the “samswhois/cache” folder so that the script can create files in it. You may also need to delete the files in this folder from time to time.
<html> <head> <title>SamsWhois Example</title> <link rel="stylesheet" type="text/css" href="swstyles.css" /> </head> <body style="font-family: verdana, arial; font-size: 10pt;"> <?php // cache whois results for 60 minutes - set to 0 to turn off caching (default) $swCacheLifetime = 60; include(dirname(__FILE__).'/samswhois/samswhois.inc.php'); ?> </body> </html>
Secure Code Options
The secure code option displays a random 4-digit code to the user as an image, and asks them to enter it when they perform a whois lookup.
This serves as a deterrent to people who might otherwise abuse the service by using automated scripts to check 100s or 1000s of domains per minute, usually to extract email addresses to use for spamming. As an excessive amount of queries can result in your i.p. address being banned by the whois servers, stopping this type of activity is in your interest.
This option requires the gd image library which is installed by default on most php distributions. Contact your hosting company if you are unsure if it is installed.
It requires that the file “swsecureimage.php” (included in the samswhois distribution) is uploaded to your server. This file outputs the image. To use the secure code option you must call the function session_start() at the top of your page, and set the $swSecure variable as illustrated below:
You must ensure sure that the $m_font variable in the “/samswhois/secureimagecode.class.php” is set to the name of a .ttf font stored in the same folder. By default this should already be set up correctly.
Options (font, size, number of characters, and whether or not to use lower and upper case characters) can be set by editing the variables at the top of the “/samswhois/secureimage.class.php” file.
<?php // session_start() must be at the top of your script, before anything is // output to the browser. Sessions are used to store the current random // code so it can be output as an image and checked when the user submits the form. session_start(); ?> <html> <head> <title>SamsWhois Example</title> <link rel="stylesheet" type="text/css" href="swstyles.css" /> </head> <body style="font-family: verdana, arial; font-size: 10pt;"> <?php // Require the user to enter a random code that is displayed // to them as an image when they submit a whois query. // The default value is false (do not require a code). $swSecure = true; include(dirname(__FILE__).'/samswhois/samswhois.inc.php'); ?> </body> </html>
Messages
Most of the default messages displayed by the script can be overridden by setting them in your script before including the samswhois.inc.php file. The following messages can be set:
<html>
<head>
<title>SamsWhois Example</title>
<link rel="stylesheet" type="text/css" href="swstyles.css" />
</head>
<body style="font-family: verdana, arial; font-size: 10pt;">
<?php
// The label that appears on the whois lookup form submit button
$swSubmitLabel = 'Lookup Domain';
// The instructions displayed below the whois lookup form
$swInstructions = 'Enter a domain and click "lookup"';
// Message displayed asking users to enter the security code
// (only displayed if $swSecure = true)
$swSecurityMessage = 'Enter the 4 digit code.';
// Text that says what server the lookup was from.
// The value {server} will be replaced by the actual server name.
$swServerText = 'whois lookup at {server}...';
// Message displayed if the domain name is available.
// The values {domain}, {sld}, {tld} will be replaced
// with their respective values.
$swAvailableMessage = '{domain} is <span style="color: green;">Available.</span>';
// Message displayed if the domain name is registered.
// The values {domain}, {sld}, {tld} will be replaced
// with their respective values.
$swRegisteredMessage = '{domain} is <span style="color: red;">Registered.</span>';
// Error message displayed if the user submits the form without
// entering the correct security code (if $swSecure = true)
$swSecurityError = 'For security purposes you MUST enter the 4-digit code shown above.';
// Error message displayed if the whois lookup fails.
$swLookupError = 'Sorry, an error occurred.';
// Error message displayed if the user enters an unsupported tld
// The value {tld} will be replaced by the tld they entered.
// The value {tlds} will be replaced by a comma separated list
// of supported tlds.
$swTldError = 'Sorry, {tld} is not supported.<br />The following tlds are supported:<br />{tlds}.';
// Heading text displayed above the form...
$swHeadingText = 'Whois Lookup';
// the default sld (domain without extension) to display in the
// form before the user has submitted it.
$swDefaultSld = 'domain';
// the default tld to display (or select if $swTldOptions = true).
$swDefaultTld = 'com';
include(dirname(__FILE__).'/samswhois/samswhois.inc.php');
?>
</body>
</html>Whois Data Processing / Display Options
There are several additional options you can set that affect the whois data that is displayed to the user.
The “clean” option removes extraneous text from the whois results (for example, whois server terms of use) resulting in a clearer presentation of the result to your users.
The “hilight” option hilights certain fields in the result such as expiration date and registrant name, again resulting in clearer presentation of the results.
Both these options depend on configuration settings in the config.txt file being set for the whois server used for the lookup. You can set the script to never use these options, always use these options, or present the user with checkboxes to choose whether or not to clean or hilight the whois result.
<html> <head> <title>SamsWhois Example</title> <link rel="stylesheet" type="text/css" href="swstyles.css" /> </head> <body style="font-family: verdana, arial; font-size: 10pt;"> <?php $swClean = 'on'; // Always clean whois output. //$swClean = 'off'; never clean output (default) //$swClean = 'optional'; // let the user choose via checkbox $swHilite = 'on'; // Always hilight data //$swHilite = 'off'; // never hilight data (default) //$swHilite = 'optional'; Let the user choose via a checkbox. include(dirname(__FILE__).'/samswhois/samswhois.inc.php'); ?> </body> </html>
Authoratitive Whois Server Options
Finally, you can tell the script whether or not to check the authoratitive whois server for certain tlds (notably com and net). The default, registry whois data for these tlds only contains basic whois information, as well as the address of the registrar’s whois server for full information.
By default the script redirects to the authoratitive server, but you can turn this option off. You can also set whether the script displays both sets of whois data (default), or just the authoratitive one.
<html> <head> <title>SamsWhois Example</title> <link rel="stylesheet" type="text/css" href="swstyles.css" /> </head> <body style="font-family: verdana, arial; font-size: 10pt;"> <?php // get whois data from authoratitive whois server (com & net) $swAuth = true; // only display the result from the authoratitive server $swOnlyShowAuth = true; include(dirname(__FILE__).'/samswhois/samswhois.inc.php'); ?> </body> </html>
For information on changing the design of the lookup form and results, see the css styles documentation, or the code in the samswhois.inc.php file.
