mirror of
https://github.com/Dolibarr/dolibarr.git
synced 2025-12-06 17:48:25 +01:00
208 lines
8.9 KiB
Plaintext
208 lines
8.9 KiB
Plaintext
php-iban README
|
|
---------------
|
|
|
|
php-iban is a library for parsing and validating International Bank
|
|
Account Number (IBAN) information in PHP.
|
|
|
|
It also validates Internet International Bank Account Number
|
|
(IIBAN) as specified at http://tools.ietf.org/html/draft-iiban-01
|
|
(see also http://www.ifex-project.org/our-proposals/iiban)
|
|
|
|
php-iban lives at http://code.google.com/p/php-iban
|
|
|
|
What is an IBAN?
|
|
----------------
|
|
An IBAN is basically a standardised way of explaining a bank
|
|
account number that works across borders. Its structure is:
|
|
|
|
<Two Letter ISO Country Code> + <Two Digit Checksum] + <BBAN>
|
|
|
|
BBAN is the term used to describe the national-level format
|
|
for a bank account number, which varies between countries
|
|
(and was sometimes created just to get IBAN connectivity!).
|
|
Note that a BBAN may have its own checksum algorithm.
|
|
|
|
IBAN provides basic protection, using the checksum, against
|
|
transcription (ie: human copying) errors. It also provides
|
|
a registry of valid destination countries and their BBAN
|
|
formats. Thus, when you ask php-iban to 'validate' an IBAN
|
|
it ensures that these checks are passed. However, it cannot
|
|
ensure that a bank account actually exists - the only party
|
|
who can do that is the receiving bank or country.
|
|
|
|
IBAN was invented in Europe, however its usage is growing
|
|
rapidly to other parts of the world. Thus, the future of
|
|
this library looks pretty good.
|
|
|
|
For further information, please see 'docs/ISO13616.pdf' or
|
|
visit Wikipedia at http://en.wikipedia.org/wiki/IBAN
|
|
|
|
What is an IIBAN?
|
|
-----------------
|
|
An Internet IBAN (IIBAN) identifies an internet-based financial
|
|
endpoint in a manner that is superset-compatible with the existing
|
|
European Committee for Banking Standards (ECBS) International Bank
|
|
Account Number (IBAN) standard [ISO13616].
|
|
|
|
For more information see http://tools.ietf.org/html/draft-iiban-00
|
|
and http://www.ifex-project.org/our-proposals/iiban
|
|
|
|
To disable IIBAN support from your installation, simply remove
|
|
the second ('AA|...') line from the top of the registry.txt file.
|
|
|
|
Execution environment
|
|
---------------------
|
|
At present the library merely requires a PHP engine to be present
|
|
and has no external dependencies. It is recommended that your
|
|
PHP engine is configured to disable verbose warnings for events
|
|
such as access of unknown array indexes, though this should be
|
|
standard on almost any PHP deployment today. Any PHP engine
|
|
in use today should be compatible, though PHP3 or PHP4 execution
|
|
environments may require minor modifications (specifically,
|
|
some string functions may have changed).
|
|
|
|
Installation
|
|
------------
|
|
Simply copy 'php-iban.php' and 'registry.txt' to an appropriate
|
|
location for your project. The location of the files will affect
|
|
the 'require_once()' line used to load the library from your
|
|
codebase, and may have relevance security (see 'Security' below).
|
|
Note that 'php-iban.php' expects to find 'registry.txt' in the
|
|
same directory as itself.
|
|
|
|
Security
|
|
--------
|
|
Following best practice for library files, the location chosen
|
|
for the php-iban.php and registry.txt files should ideally be
|
|
outside of any web-accessible directories. Thus, if your
|
|
web project lives in /var/www/myproject/htdocs/ then it would
|
|
be preferably to place php-iban in /var/www/myproject or some
|
|
other directory that is not visible to regular web users.
|
|
|
|
Secondly, neither file should be writable by the web server
|
|
itself in order to prevent compromise of the execution path
|
|
(ie: getting hacked). So, for example if your web server runs
|
|
as user 'www', group 'www', you can ensure that the web server
|
|
has minimal required privileges against the files as follows
|
|
(note that you will need to be root to execute these commands):
|
|
|
|
# chown <myuser> php-iban registry.txt # where <myuser> is a
|
|
# non-root user that
|
|
# is not 'www'.
|
|
# chgrp www php-iban registry.txt # set group to 'www'
|
|
# chmod ugo-rwx php-iban registry.txt # remove privileges
|
|
# chmod g+r php-iban registry.txt # allow 'www' group
|
|
# to read the files
|
|
|
|
Obviously the above do not apply if you are using PHP in a
|
|
non web-oriented project (eg: a cronjob or daemon), a usage
|
|
of the language that is apparently growing - but limited.
|
|
|
|
Using the library
|
|
-----------------
|
|
Basic invocation is as follows:
|
|
|
|
# include the library
|
|
require_once('/path/to/php-iban.php'); # /path/to/ is optional
|
|
|
|
# use some library function or other...
|
|
if(!verify_iban($iban_to_verify)) {
|
|
# blame the user...
|
|
}
|
|
|
|
Note that because the library is designed in a procedural manner
|
|
rather than an object-oriented manner it should be easy to
|
|
integrate with a wide variety of established codebases and
|
|
PHP interpreter versions.
|
|
|
|
Using the library's OO wrapper
|
|
------------------------------
|
|
Because many new PHP programmers seems to learn the language via
|
|
books that only teach OO based programming and are thus unfamiliar
|
|
with procedural PHP (and often relatively inexperienced as
|
|
programmers, too) an OO wrapper-library has been provided.
|
|
|
|
======================= READ THIS =================================
|
|
However *you should avoid excessive use of OO*. For some thought
|
|
provoking discussions of the negative aspects of overusing OO,
|
|
please refer to 'Coders at Work' and 'The Art of UNIX Programming'.
|
|
(OO is great for some problems, but simply pointless for most.)
|
|
===================================================================
|
|
|
|
Anyway, to use the OO wrapper supplied, invocation is as follows:
|
|
|
|
# include the OO wrapper to the library
|
|
require_once('/path/to/oophp-iban.php'); # /path/to is optional
|
|
|
|
# instantiate an IBAN object
|
|
$myIban = new IBAN('AZ12345678901234');
|
|
if(!$myIban->Verify()) {
|
|
# blame the user...
|
|
}
|
|
|
|
Documentation
|
|
-------------
|
|
There are three types of functions provided by the library:
|
|
|
|
- IBAN-level functions
|
|
|
|
These are functions that operate on an IBAN. All of these
|
|
functions accept either machine format or human format
|
|
IBANs as input. Typically they return facts about an IBAN
|
|
as their output (for example whether it is valid or not,
|
|
or the BBAN (national-level) portion of the IBAN), though
|
|
some of them may perform other functions (eg: fixing a
|
|
broken IBAN checksum). These functions are named 'iban_*'
|
|
with the exception of the most commonly used function,
|
|
'verify_iban()', and excepting the country-level functions.
|
|
|
|
(Regarding the object oriented wrapper - all of these
|
|
functions are implemented as methods on IBAN objects)
|
|
|
|
- IBAN country-level functions
|
|
These functions return information about countries that are
|
|
part of the IBAN standard. They each take the two letter
|
|
ISO country code at the beginning of an IBAN as their
|
|
argument. They are named 'iban_country_*', with the
|
|
exception of 'iban_countries()' which returns a list of
|
|
the known IBAN countries. (For example, functions that
|
|
return an example IBAN or BBAN for the country, or the
|
|
name of the country.)
|
|
|
|
(Regarding the object oriented wrapper - all of these
|
|
functions are implemented as methods on IBANCountry
|
|
objects, except for 'iban_countries()' which is
|
|
implemented as the Countries() method on the IBAN class)
|
|
|
|
- Internal functions
|
|
These functions begin with '_iban_*' and can be ignored.
|
|
|
|
(Regarding the object oriented wrapper - these functions
|
|
are not present)
|
|
|
|
Please refer to either http://code.google.com/p/php-iban or the
|
|
commented source code of php-iban itself for the complete list of
|
|
which functions are available. Of course, in unix style one could
|
|
achieve the same in a pinch as follows (instant documentation!):
|
|
$ grep function php-iban.php
|
|
$ egrep '(Class|function)' oophp-iban.php
|
|
|
|
Community
|
|
---------
|
|
You are encouraged to contribute bugs, feedback and suggestions
|
|
through the project's website.
|
|
|
|
Particularly if you deploy php-iban in a commercial setting, you are
|
|
STRONGLY encouraged to join the project's mailing list, which can
|
|
be found via the website. Joining the mailing list ensures that you
|
|
can be made aware of important updates. Important updates include:
|
|
- Updates to new registry editions (support new countries that have
|
|
been added to the IBAN system)
|
|
- Bug fixes
|
|
- Security updates
|
|
|
|
The email list receives almost no traffic and as a 'Google Group' is
|
|
well protected from spam, so don't worry about junk in your inbox.
|
|
|
|
Thanks for choosing php-iban! You have excellent taste in software ;)
|