Zend_Validate_SalesTaxNum

1. Overview

Zend_Validate_SalesTaxNum is a simple component that validates European (EU) sales tax numbers.

It offers two kinds of validation:

Whether the syntax of an EU sales tax number is correct (each country has its own pattern)
Whether an EU sales tax number exists and is being used (via VIES API)

Each EU member state has a different name for their sales tax numbers [1], hence a neutral term has been chosen for the class name: "sales tax number".

Comments on the class name are requested. For example, Zend_Validate_Eusalestaxno could also be possible.

A sample implementation of this class is attached to this page ("Zend_Validate_SalesTaxNum.tar.bz2")

[1] - UK: "VAT", DE: "MwSt", FR: "TVA" etc.

2. References

3. Component Requirements, Constraints, and Acceptance Criteria

This component will validate the syntax of an EU sales tax number

This component will validate the existence (whether it is being used used or not) of an EU sales tax number

This component will not validate sales tax from countries other than EU member states.

4. Dependencies on Other Framework Components

Zend_Exception
Zend_Validate_Abstract

5. Theory of Operation

Validates and checks existence of EU sales tax numbers. On failure, following error strings are available:

protected $_messageTemplates = array(
        self::STRING_EMPTY             => "'%value%' must contain a sales tax number",
        self::INVALID_COUNTRY_CODE     => "'%value%' contains an invalid member state country code",
        self::INVALID_SYNTAX           => "'%value%' is a syntactically invalid sales tax number",
        self::SERVICE_NONEXISTENT      => "'%value%' is syntactically valid, but VIES sales tax number database reports it is not in use",
        self::SERVICE_CANNOT_CONNECT   => "Cannot connect to VIES sales tax number database",
        self::SERVICE_UNKNOWN_RESPONSE => "Unknown response from VIES sales tax number database"
    );

6. Milestones / Tasks

Milestone 1: [DONE] write proposal

Milestone 2: get the proposal approved

Milestone 3: working prototype checked into the incubator

Milestone 4: write unit test, and check into SVN

Milestone 5: write documentation for this validator.

Milestone 6: introduce "component" to core.

8. Use Cases

<?php

error_reporting(E_ALL);

// developed with ZendFramework 1.0.3

set_include_path(
	'/usr/share/php-libs/zf/stable/library:'     .
	'/usr/share/php-libs/zf/extension/library:'
);

include_once 'Zend/Debug.php';
include_once 'Zend/Validate/SalesTaxNum.php';

// ----------------------------------------------------------------------------------------------------

// # Check just syntax AND whether exists

$validate = new Zend_Validate_SalesTaxNum();
$result = $validate->isValid('GB112102132');
Zend_Debug::dump($result); // (boolean) true
echo '<hr />';

// ----------------------------------------------------------------------------------------------------

// # Check syntax AND whether exists

$validate = new Zend_Validate_SalesTaxNum(true);
$result = $validate->isValid('GB112102132');
Zend_Debug::dump($result); // (boolean) false
echo '<hr />';

// ----------------------------------------------------------------------------------------------------

// # Syntax checking EU sales tax numbers in a loop

$sales_tax_nos = array (
	'ATU39725008', 'ATU40297406', 'ATO43491707', 'ATU47451109', 'ATU49693906', 'ATU51673005',
	'BE454195867', 'BE458269372', 'BE460306570', 'BE461742566', 'BE465048781', 'DE118537403',
	'DE150516811', 'DE176840663', 'DE813094186', 'ESB78557394', 'ESB82661935', 'ESE58902883',
	'ESG09226606', 'ESQ2818002D', 'GR095444247', 'GR095748821', 'GR099289535', 'GR502716630',
	'PT503183504', 'PT503300152', 'PT503453498', 'PT50378250X', 'GBHA999', 'GBGD999'
);

$validate = new Zend_Validate_SalesTaxNum();

foreach ($sales_tax_nos as $sales_tax_no) {
	if ($validate->isValid($sales_tax_no)) {
		printf('%s is syntactically valid.<br />', $sales_tax_no);
	}
	else {
		printf('%s is syntactically invalid.<br />', $sales_tax_no);
	}
}

echo '<hr />';

// ----------------------------------------------------------------------------------------------------

// # Syntax and Existence checking EU sales tax numbers in a loop

$sales_tax_nos = array (
	'ATU39725008', 'ATU40297406', 'ATO43491707', 'ATU47451109', 'ATU49693906', 'ATU51673005',
	'BE454195867', 'BE458269372', 'BE460306570', 'BE461742566', 'BE465048781', 'DE118537403'
);

$validate = new Zend_Validate_SalesTaxNum(true);

foreach ($sales_tax_nos as $sales_tax_no) {
	if ($validate->isValid($sales_tax_no)) {
		printf('%s is syntactically valid and has been issued and is in use.<br />', $sales_tax_no);
	}
	else {
		printf('%s is syntactically invalid or has not been issued or is not in use.<br />', $sales_tax_no);
	}
}

echo '<hr />';

// ----------------------------------------------------------------------------------------------------

// # Reading error messages

$validate = new Zend_Validate_SalesTaxNum(false);
$result = $validate->isValid('GB112102');

Zend_Debug::dump($validate->getMessages()); // (array) [0] 'GB112102' is a syntactically invalid sales tax number
Zend_Debug::dump($validate->getErrors());   // (array) [0] salestaxnoInvalidSyntax

$validate = new Zend_Validate_SalesTaxNum(true);
$result = $validate->isValid('GB112102132');

Zend_Debug::dump($validate->getMessages()); // (array) [0] 'GB112102132' is syntactically valid, but VIES sales tax number database reports it is not in use
Zend_Debug::dump($validate->getErrors());   // (array) [0] salestaxnoServiceNotExistent

// ----------------------------------------------------------------------------------------------------

?>

9. Class Skeletons

/**
 * @see Zend_Validate_Abstract
 */
require_once 'Zend/Validate/Abstract.php';


/**
 * Validate the syntax of a European Union sales tax number and (optionally) whether it has
 * been issued and is in use, according to the VIES (EU sales tax number validation) database.
 *
 * @category   Zend
 * @package    Zend_Validate
 * @copyright  Copyright (c) 2005-2007 Zend Technologies USA Inc. (http://www.zend.com)
 * @license    http://framework.zend.com/license/new-bsd     New BSD License
 */
class Zend_Validate_SalesTaxNum extends Zend_Validate_Abstract
{
    /**
     * If true, VIES sales tax number database is consulted to establish
     * whether the sales tax number has actually been issued and is in use.
     *
     * @var boolean
     */
    protected $_validateVies;


    /**
     * Validate the syntax of a European Union sales tax number.
     *
     * Optionally, the VIES sales tax number database can be consulted to establish
     * whether the sales tax number has actually been issued and is in use.
     *
     * @param bool $validateVies OPTIONAL
     * @return void
     */
    public function __construct($validateVies = false) { }

    /**
     * If true, VIES sales tax number database is consulted to establish
     * whether the sales tax number has actually been issued and is in use.
     *
     * @param boolean $validateVies Set allowed to true to check VIES sales tax number database
     */
    public function setValidateVies($validateVies) { }

    /**
     * Defined by Zend_Validate_Interface
     *
     * Returns true, if $value is a valid EU sales tax number.
     * $value must be specified as follows: "PT50378250X", "ATU47451888" or "DE150519875".
     *
     * @param  string $value
     * @return boolean
     */
    public function isValid($value) { }
}

Page Operations

Browse Space

Zend_Validate_SalesTaxNum Proposal

Labels