This library provides the functionality to validate, format and convert ISBN numbers, that powers the nicebooks.com website. It is released under a permissive MIT open-source license for anyone to use.
ISBN formatting follows the rules defined by the ISBN range file published by ISBN International.
This library is installable via Composer:
composer require nicebooks/isbn
This library requires PHP 7.1 or higher.
While this library is still under development, it is well tested and should be stable enough to use in production environments. It is currently in use in production on nicebooks.com.
The current releases are numbered 0.x.y
. When a non-breaking change is introduced (adding new methods, optimizing
existing code, etc.), y
is incremented.
When a breaking change is introduced, a new 0.x
version cycle is always started.
It is therefore safe to lock your project to a given release cycle, such as 0.1.*
.
If you need to upgrade to a newer release cycle, check the release history
for a list of changes introduced by each further 0.x.0
version.
This class contains all the tools to work with ISBN numbers as plain strings.
use Nicebooks\Isbn\IsbnTools;
$tools = new IsbnTools();
Its constructor offers two configurable parameters:
public function __construct(bool $cleanupBeforeValidate = true, bool $validateCheckDigit = true)
$cleanupBeforeValidate
removes any non-alphanumeric ASCII character from the string before validating it.$validateCheckDigit
computes the checksum of the ISBN number before any operation.
Method summary:
-
isValidIsbn(string $isbn) : bool
checks that the given ISBN is valid.var_export($tools->isValidIsbn('123456789X')); // true var_export($tools->isValidIsbn('9781234567897')); // true
-
isValidIsbn10(string $isbn) : bool
checks that the given ISBN is a valid ISBN-10.var_export($tools->isValidIsbn10('123456789X')); // true
-
isValidIsbn13(string $isbn) : bool
checks that the given ISBN is a valid ISBN-13.var_export($tools->isValidIsbn13('9781234567897')); // true
-
convertIsbn10to13(string $isbn) : string
converts the given ISBN-10 to an ISBN-13.var_export($tools->convertIsbn10to13('123456789X')); // '9781234567897'
-
convertIsbn13to10(string $isbn) : string
converts the given ISBN-13 to an ISBN-10.var_export($tools->convertIsbn10to13('9781234567897')); // '123456789X'
-
format(string $isbn) : string
formats the given ISBN by adding hyphens at the proper places.var_export($formatter->format('123456789X')); // '1-234-56789-X' var_export($formatter->format('9781234567897')); // '978-1-234-56789-7'
The Isbn
class is an immutable class representing a valid ISBN-10 or ISBN-13.
It is an alternate way to access the functionality provided by IsbnTools
, and offers a convenient way to pass an ISBN number around,
guaranteeing both its validity and its integrity.
An Isbn
instance is obtained with the of()
factory method:
use Nicebooks\Isbn\Isbn;
$isbn = Isbn::of('123456789X');
Method summary:
is10() : bool
Returnstrue
for an ISBN-10, orfalse
for an ISBN-13.is13() : bool
Returnstrue
for an ISBN-13, orfalse
for an ISBN-10.isConvertibleTo10() : bool
Returnstrue
if the ISBN can be converted to an ISBN-10,false
otherwise.to10() : Isbn
Returns anIsbn
instance representing the ISBN converted to an ISBN-10.to13() : Isbn
Returns anIsbn
instance representing the ISBN converted to an ISBN-13.format() : string
Returns the formatted representation of the ISBN.
Exceptions live in the Nicebooks\Isbn\Exception
namespace.
InvalidIsbnException
is thrown when an invalid ISBN is detectedIsbnNotConvertibleException
is thrown when trying to convert an ISBN-13 that does not start with '978' to an ISBN-10.