PHPackages nicebooks/isbn - PHPackages - PHPackages [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register) 1. [Directory](/) 2. / 3. [Utility & Helpers](/categories/utility) 4. / 5. nicebooks/isbn ActiveLibrary[Utility & Helpers](/categories/utility) nicebooks/isbn ============== ISBN tools 0.7.3(2mo ago)29336.9k↓13%3[1 PRs](https://github.com/nicebooks-com/isbn/pulls)3MITPHPPHP ^8.2CI passing Since May 31Pushed 2mo ago2 watchersCompare [ Source](https://github.com/nicebooks-com/isbn)[ Packagist](https://packagist.org/packages/nicebooks/isbn)[ RSS](/packages/nicebooks-isbn/feed)WikiDiscussions master Synced 1mo ago READMEChangelog (10)Dependencies (8)Versions (226)Used By (3) Nicebooks ISBN library for PHP ============================== [](#nicebooks-isbn-library-for-php) This library provides functionality for validating, formatting, and converting ISBN numbers. It powers the [nicebooks.com](https://nicebooks.com) website and is available for use under the permissive MIT open-source license. ISBN validation and formatting follow the rules defined by the [ISBN range file](https://www.isbn-international.org/range_file_generation) published by the International ISBN Agency. [![Build Status](https://github.com/nicebooks-com/isbn/workflows/CI/badge.svg)](https://github.com/nicebooks-com/isbn/actions)[![Coverage Status](https://camo.githubusercontent.com/99e031f576ea2f2bb9b0942b1226d135b620f26a675e3e87f1b1e1cb9beb287f/68747470733a2f2f636f766572616c6c732e696f2f7265706f732f6769746875622f6e696365626f6f6b732d636f6d2f6973626e2f62616467652e7376673f6272616e63683d6d6173746572)](https://coveralls.io/github/nicebooks-com/isbn?branch=master)[![Latest Stable Version](https://camo.githubusercontent.com/9e202a7345f9a8ae6d0a2095bc04c6501df469d340b4e9e21261b2d24831b5fa/68747470733a2f2f706f7365722e707567782e6f72672f6e696365626f6f6b732f6973626e2f762f737461626c65)](https://packagist.org/packages/nicebooks/isbn)[![Total Downloads](https://camo.githubusercontent.com/0acc24ea34ffeec970b3605171aa1ea24eb52bf5bc302e43e7eff28efba40c57/68747470733a2f2f706f7365722e707567782e6f72672f6e696365626f6f6b732f6973626e2f646f776e6c6f616473)](https://packagist.org/packages/nicebooks/isbn)[![License](https://camo.githubusercontent.com/7013272bd27ece47364536a221edb554cd69683b68a46fc0ee96881174c4214c/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f6c6963656e73652d4d49542d626c75652e737667)](http://opensource.org/licenses/MIT) Installation ------------ [](#installation) This library is installable via [Composer](https://getcomposer.org/): ``` composer require nicebooks/isbn ``` Requirements ------------ [](#requirements) The current version of this library requires PHP 8.2 or higher. You may use earlier versions of `nicebooks/isbn` with earlier versions of PHP, but you will only receive ISBN range updates if you use the latest version. Project status & release process ------------------------------------ [](#project-status--release-process) 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](https://nicebooks.com/). The current releases are numbered `0.x.y`. When a non-breaking change is introduced (updating ISBN ranges, 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.6.*`. If you need to upgrade to a newer release cycle, check the [release history](https://github.com/nicebooks-com/isbn/releases)for a list of changes introduced by each further `0.x.0` version. Overview -------- [](#overview) ### The `Isbn` class [](#the-isbn-class) The `Isbn` class is an abstract, immutable class representing an ISBN-10 or ISBN-13 with a valid format and a valid check digit. It has 2 subclasses: `Isbn10` and `Isbn13`, allowing for narrower typing if your application expects only ISBN-10 or only ISBN-13 at some point. An `Isbn` instance is obtained with the `of()` factory method: ``` use Nicebooks\Isbn\Isbn; $isbn = Isbn::of('123456789X'); // will return an instance of Isbn10 $isbn = Isbn::of('9781234567897'); // will return an instance of Isbn13 ``` You can also use the `Isbn10::of()` and `Isbn13::of()` factory methods, which will attempt to convert the given ISBN to the corresponding subclass: ``` Isbn10::of('123456789X'); // equivalent to Isbn::of('123456789X')->to10(); Isbn13::of('9781234567897'); // equivalent to Isbn::of('9781234567897')->to13(); ``` If the given string does not have a valid format or check digit, an `InvalidIsbnException` is thrown. Note Before validation, the provided string is stripped of all non-alphanumeric ASCII characters. ### Checking the type of an ISBN [](#checking-the-type-of-an-isbn) You can check the type of an ISBN with the `is10()` and `is13()` methods: ``` Isbn::of('123456789X')->is10(); // true Isbn::of('123456789X')->is13(); // false Isbn::of('9781234567897')->is10(); // false Isbn::of('9781234567897')->is13(); // true ``` You can also use `instanceof` checks: ``` Isbn::of('123456789X') instanceof Isbn10; // true Isbn::of('9781234567897') instanceof Isbn13; // true ``` ### Converting between ISBN-10 and ISBN-13 [](#converting-between-isbn-10-and-isbn-13) An ISBN-10 can be converted to an ISBN-13 with the `to13()` method: ``` Isbn::of('123456789X')->to13(); // Isbn13 instance with value 9781234567897 ``` An ISBN-13 can be converted to an ISBN-10 with the `to10()` method: ``` Isbn::of('9781234567897')->to10(); // Isbn10 instance with value 123456789X ``` Only ISBN-13 numbers starting with `978` can be converted to ISBN-10. You can check if an ISBN can be converted to an ISBN-10 with the `isConvertibleTo10()` method: ``` Isbn::of('9781234567897')->isConvertibleTo10(); // true Isbn::of('9791234567896')->isConvertibleTo10(); // false ``` If you call `to10()` on an ISBN-13 that does not start with `978`, an `IsbnNotConvertibleException` is thrown. ### Comparing ISBN numbers [](#comparing-isbn-numbers) You can compare two `Isbn` instances with the `isEqualTo()` method. An ISBN-10 can be compared to an ISBN-13, and the comparison will be successful if both numbers resolve to the same ISBN-13 number: ``` Isbn::of('123456789X')->isEqualTo(Isbn::of('9781234567897')); // true ``` ### Validating an ISBN [](#validating-an-isbn) While an `Isbn` instance is guaranteed to have a valid format and a valid check digit, it may not belong to a valid range according to the range file published by the International ISBN Agency. The `Isbn` class provides two methods to further validate an ISBN: MethodDescription`hasValidRegistrationGroup()`Only checks if the ISBN belongs to a **known registration group**.`isValid()`Checks if the ISBN belongs to a **known registration group** and a **known range**. This is the highest level of validation that can be performed by looking at the ISBN number alone.Note Which ISBNs are considered valid depends on the library version you are using. This library is kept in sync with the ISBN ranges published by the International ISBN Agency, so keep it up to date for proper validation. ### Formatting an ISBN [](#formatting-an-isbn) The library provides two methods to format an ISBN: MethodDescriptionISBN-10 exampleISBN-13 example`toString()`Returns the unformatted ISBN`133887893X``9781338878936``toFormattedString()`Returns the formatted ISBN if the ISBN is valid, otherwise returns the unformatted number`1-338-87893-X``978-1-338-87893-6`### Splitting an ISBN into parts [](#splitting-an-isbn-into-parts) An ISBN-13 is divided into 5 parts: ``` 978-1-338-87893-6 ——— — ——— ————— — A B C D E ``` While an ISBN-10 is divided into 4 parts: ``` 1-338-87893-X — ——— ————— — B C D E ``` The `Isbn` class provides getters for each part: PartExampleDescriptionGetter`A``978`Prefix`getRegistrationGroup()->prefix``B``1`Registration group identifier`getRegistrationGroup()->identifier``C``338`Publisher identifier (registrant)`getPublisherIdentifier()``D``87893`Title identifier (publication)`getTitleIdentifier()``E``6`Check digit`getCheckDigit()`Important - Parts `A` and `B` require `hasValidRegistrationGroup()` (or `isValid()`, which implies it) - Parts `C` and `D` require `isValid()` You can also get the ISBN parts as an array: ``` Isbn::of('9781338878936')->getParts(); // ['978', '1', '338', '87893', '6'] ``` Important `getParts()` requires `isValid()` If the part you're trying to access is not available because the ISBN does not belong to a valid registration group or range, an `IsbnException` is thrown. #### Getting the registration group name [](#getting-the-registration-group-name) `getRegistrationGroup()` also exposes the group's `name`: ``` Isbn::of('9781338878936')->getRegistrationGroup()->name; // 'English language' ``` ### Exceptions [](#exceptions) Exceptions live in the `Nicebooks\Isbn\Exception` namespace. - `IsbnException` is the base class for all exceptions thrown by this library. - `InvalidIsbnException` is thrown when an invalid ISBN is detected - `IsbnNotConvertibleException` is thrown when trying to convert an ISBN-13 that does not start with `978` to an ISBN-10. ### Health Score 64 — FairBetter than 99% of packages Maintenance88 Actively maintained with recent releases Popularity45 Moderate usage in the ecosystem Community19 Small or concentrated contributor base Maturity85 Battle-tested with a long release history Bus Factor1 Top contributor holds 97.8% of commits — single point of failure How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window. **Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores. **Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement. **Maturity (30%)** — Project age, version count, PHP version support, and release stability. ### Release Activity Cadence Every ~12 days Recently: every ~6 days Total 225 Last Release 61d ago PHP version history (6 changes)0.1.0PHP >=5.4 0.2.0PHP >=7.1 0.2.76PHP ^7.1 || ^8.0 0.3.0PHP ^7.4 || ^8.0 0.4.0PHP ^8.1 0.5.0PHP ^8.2 ### Community Maintainers ![](https://www.gravatar.com/avatar/57189121968030f0770811b461cc92f9c19c08f5c4767292f2ede48b7277cfad?d=identicon)[BenMorel](/maintainers/BenMorel) --- Top Contributors [![BenMorel](https://avatars.githubusercontent.com/u/1952838?v=4)](https://github.com/BenMorel "BenMorel (403 commits)")[![dependabot[bot]](https://avatars.githubusercontent.com/in/29110?v=4)](https://github.com/dependabot[bot] "dependabot[bot] (4 commits)")[![szepeviktor](https://avatars.githubusercontent.com/u/952007?v=4)](https://github.com/szepeviktor "szepeviktor (4 commits)")[![JayAhrDe](https://avatars.githubusercontent.com/u/930553?v=4)](https://github.com/JayAhrDe "JayAhrDe (1 commits)") --- Tags isbnphpISBNbookISBN-10ISBN-13booksNicebooks ### Code Quality TestsPHPUnit ### Embed Badge ![Health badge](/badges/nicebooks-isbn/health.svg) ``` [![Health](https://phpackages.com/badges/nicebooks-isbn/health.svg)](https://phpackages.com/packages/nicebooks-isbn) ``` ### Alternatives [fale/isbn ISBN library 88524.8k6](/packages/fale-isbn)[ronanguilloux/isocodes PHP library - Validators for standards from ISO, International Finance, Public Administrations, GS1, Book and Music Industries, Phone numbers & Zipcodes for many countries 8013.3M23](/packages/ronanguilloux-isocodes)[biblys/isbn A PHP library to convert and validate ISBNs 56346.8k1](/packages/biblys-isbn)[johndoh/globaladdressbook Adds global address books to Roundcube 706.0k](/packages/johndoh-globaladdressbook)[barcode-bakery/barcode-1d Generates 1D barcodes from a PHP server to a file or HTML document. 10146.1k1](/packages/barcode-bakery-barcode-1d) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)