# Hostname

`Zend_Validate_Hostname` allows you to validate a hostname against a set of known specifications. It is possible to check for three different types of hostnames: a DNS Hostname (i.e. domain.com), IP address (i.e. 1.2.3.4), and Local hostnames (i.e. localhost). By default only DNS hostnames are matched.

## Supported options for Zend_Validate_Hostname

The following options are supported for `Zend_Validate_Hostname`:

- allow: Defines the sort of hostname which is allowed to be used. See Hostname types for details.

- idn: Defines if IDN domains are allowed or not. This option defaults to `TRUE`.

- ip: Allows to define a own IP validator. This option defaults to a new instance of `Zend_Validate_Ip`.

- tld: Defines if TLDs are validated. This option defaults to `TRUE`.

## Basic usage

A basic example of usage is below:

    $validator = new Zend_Validate_Hostname();
    if ($validator->isValid($hostname)) {
        // hostname appears to be valid
    } else {
        // hostname is invalid; print the reasons
        foreach ($validator->getMessages() as $message) {
            echo "$message\n";
        }
    }

This will match the hostname `$hostname` and on failure populate `getMessages()` with useful error messages.

## Validating different types of hostnames

You may find you also want to match IP addresses, Local hostnames, or a combination of all allowed types. This can be done by passing a parameter to `Zend_Validate_Hostname` when you instantiate it. The parameter should be an integer which determines what types of hostnames are allowed. You are encouraged to use the `Zend_Validate_Hostname` constants to do this.

The Zend_Validate_Hostname constants are: `ALLOW_DNS` to allow only DNS hostnames, `ALLOW_IP` to allow IP addresses, `ALLOW_LOCAL` to allow local network names, and `ALLOW_ALL` to allow all three types. To just check for IP addresses you can use the example below:

    $validator = new Zend_Validate_Hostname(Zend_Validate_Hostname::ALLOW_IP);
    if ($validator->isValid($hostname)) {
        // hostname appears to be valid
    } else {
        // hostname is invalid; print the reasons
        foreach ($validator->getMessages() as $message) {
            echo "$message\n";
        }
    }

As well as using `ALLOW_ALL` to accept all hostnames types you can combine these types to allow for combinations. For example, to accept DNS and Local hostnames instantiate your Zend_Validate_Hostname object as so:

    $validator = new Zend_Validate_Hostname(Zend_Validate_Hostname::ALLOW_DNS |
                                            Zend_Validate_Hostname::ALLOW_IP);

## Validating International Domains Names

Some Country Code Top Level Domains (ccTLDs), such as 'de' (Germany), support international characters in domain names. These are known as International Domain Names (IDN). These domains can be matched by `Zend_Validate_Hostname` via extended characters that are used in the validation process.

### IDN domains

Until now more than 50 ccTLDs support IDN domains.

To match an IDN domain it's as simple as just using the standard Hostname validator since IDN matching is enabled by default. If you wish to disable IDN validation this can be done by either passing a parameter to the `Zend_Validate_Hostname` constructor or via the `setValidateIdn()` method.

You can disable IDN validation by passing a second parameter to the `Zend_Validate_Hostname` constructor in the following way.

    $validator =
        new Zend_Validate_Hostname(
            array(
                'allow' => Zend_Validate_Hostname::ALLOW_DNS,
                'idn'   => false
            )
        );

Alternatively you can either pass `TRUE` or `FALSE` to `setValidateIdn()` to enable or disable IDN validation. If you are trying to match an IDN hostname which isn't currently supported it is likely it will fail validation if it has any international characters in it. Where a ccTLD file doesn't exist in `Zend/Validate/Hostname` specifying the additional characters a normal hostname validation is performed.

### IDN validation

Please note that IDNs are only validated if you allow DNS hostnames to be validated.

## Validating Top Level Domains

By default a hostname will be checked against a list of known TLDs. If this functionality is not required it can be disabled in much the same way as disabling IDN support. You can disable TLD validation by passing a third parameter to the `Zend_Validate_Hostname` constructor. In the example below we are supporting IDN validation via the second parameter.

    $validator =
        new Zend_Validate_Hostname(
            array(
                'allow' => Zend_Validate_Hostname::ALLOW_DNS,
                'idn'   => true,
                'tld'   => false
            )
        );

Alternatively you can either pass `TRUE` or `FALSE` to `setValidateTld()` to enable or disable TLD validation.

### TLD validation

Please note TLDs are only validated if you allow DNS hostnames to be validated.