README

Utility class to validate, format and generate NHS numbers.

• NHS Numbers
  • 🤔 F.A.Q.
    • What is an NHS number?
    • How do you validate an NHS number?
  • 💾 Installation
  • 📝 Usage
  • ✅ Testing
  • 🔖 Changelog
  • ⬆️ Upgrading
  • 🎉 Contributing
    • 🔒 Security
  • 👷 Credits
  • ♻️ License

🤔 F.A.Q.

What is an NHS number?

An "NHS number" is a unique identifier that every individual patient registered with Great Britain's National Health Service (NHS) has.

You can find out more about NHS numbers on the nhs.uk website.

How do you validate an NHS number?

Not every number is a valid NHS number - they must conform to a simple algorithm to be considered valid. Before the algorithm is run, there are a few things to note about NHS numbers:

• An NHS number must be numeric
• An NHS number must be 10 digits long
• An NHS number can begin with a 0, so it should be handled as a string, not an integer
• The last digit of the NHS number is used as the "check digit" for the algorithm

The algorithm to validate an NHS number using its "check digit" is as follows:

1. Multiple each of the first nine digits by a defined weight, shown below:

1. Calculate the sum of all 9 multiplications
2. Divide this sum by 11 and get the remainder
3. Subtract 11 from the remainder to get the total
4. If the total is 11 then the identifier, otherwise the identifier is the total
5. If the identifier is 10, then the NHS number is wrong
6. If the identifier is the same as the check digit, then the NHS number is correct

💾 Installation

You can install the package with Composer using the following command:

composer require imliam/php-nhs-number:^1.1

📝 Usage

You can new up the NhsNumber object by passing through an NHS number.

$nhsNumber = new \ImLiam\NhsNumber\NhsNumber('9077844449');

The NHS recommend that when displaying an NHS number to a human, it should be spaced out in a 3-3-4 format, which helps it to be easier to read. To do this, call the ->format() method or cast the object to a string.

echo $nhsNumber->format();
// '907 784 4449'

echo (string) $nhsNumber;
// '907 784 4449'

To get a boolean representation of whether or not the current number is valid, call the ->isValid() method on the object.

$nhsNumber->isValid();
// true

If you need more information on why a given NHS number may be invalid, you can call the ->validate() method directly. This will throw an InvalidNhsNumberException exception whose message will explain why the number is not valid.

try {
    $nhsNumber = new \ImLiam\NhsNumber\NhsNumber('9077844446');
    $nhsNumber->validate();
} catch (\ImLiam\NhsNumber\InvalidNhsNumberException $e) {
    echo $e->getMessage();
    // "The NHS number's check digit does not match."
}

To generate a single or multiple random valid NHS numbers for testing purposes, call the ::getRandomNumber() or ::getRandomNumbers($count) static methods respectively.

echo \ImLiam\NhsNumber\NhsNumber::getRandomNumber();
// '9278462608'

echo \ImLiam\NhsNumber\NhsNumber::getRandomNumbers(5);
// ['7448556886', '0372104223', '8416367035']

✅ Testing

composer test

🔖 Changelog

Please see the changelog file for more information on what has changed recently.

⬆️ Upgrading

Please see the upgrading file for details on upgrading from previous versions.

🎉 Contributing

Please see the contributing file and code of conduct for details on contributing to the project.

🔒 Security

If you discover any security related issues, please email liam@liamhammett.com instead of using the issue tracker.

👷 Credits

• Liam Hammett
• Peter Fisher for the original class
• All Contributors

♻️ License

The MIT License (MIT). Please see the license file for more information.