{"id":34980442,"url":"https://github.com/nicebooks-com/isbn","last_synced_at":"2026-04-06T11:01:23.354Z","repository":{"id":22684252,"uuid":"26027947","full_name":"nicebooks-com/isbn","owner":"nicebooks-com","description":"A PHP library to validate, format, and convert ISBN numbers","archived":false,"fork":false,"pushed_at":"2026-04-01T06:09:22.000Z","size":299,"stargazers_count":28,"open_issues_count":3,"forks_count":3,"subscribers_count":2,"default_branch":"master","last_synced_at":"2026-04-01T11:36:46.489Z","etag":null,"topics":["isbn","php"],"latest_commit_sha":null,"homepage":"","language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/nicebooks-com.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2014-10-31T18:18:31.000Z","updated_at":"2026-03-19T10:30:51.000Z","dependencies_parsed_at":"2024-01-19T18:56:39.120Z","dependency_job_id":"bcfa0f21-0e50-4757-9640-80053d24db31","html_url":"https://github.com/nicebooks-com/isbn","commit_stats":{"total_commits":259,"total_committers":2,"mean_commits":129.5,"dds":"0.0038610038610038533","last_synced_commit":"8e7230b36dd568095d964dc0bd64e84e68cc5dcb"},"previous_names":[],"tags_count":221,"template":false,"template_full_name":null,"purl":"pkg:github/nicebooks-com/isbn","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nicebooks-com%2Fisbn","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nicebooks-com%2Fisbn/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nicebooks-com%2Fisbn/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nicebooks-com%2Fisbn/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/nicebooks-com","download_url":"https://codeload.github.com/nicebooks-com/isbn/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nicebooks-com%2Fisbn/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31469743,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-06T08:36:52.050Z","status":"ssl_error","status_checked_at":"2026-04-06T08:36:51.267Z","response_time":112,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["isbn","php"],"created_at":"2025-12-27T00:58:37.789Z","updated_at":"2026-04-06T11:01:23.338Z","avatar_url":"https://github.com/nicebooks-com.png","language":"PHP","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Nicebooks ISBN library for PHP\n\nThis 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.\n\nISBN 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.\n\n[![Build Status](https://github.com/nicebooks-com/isbn/workflows/CI/badge.svg)](https://github.com/nicebooks-com/isbn/actions)\n[![Coverage Status](https://coveralls.io/repos/github/nicebooks-com/isbn/badge.svg?branch=master)](https://coveralls.io/github/nicebooks-com/isbn?branch=master)\n[![Latest Stable Version](https://poser.pugx.org/nicebooks/isbn/v/stable)](https://packagist.org/packages/nicebooks/isbn)\n[![Total Downloads](https://poser.pugx.org/nicebooks/isbn/downloads)](https://packagist.org/packages/nicebooks/isbn)\n[![License](https://img.shields.io/badge/license-MIT-blue.svg)](http://opensource.org/licenses/MIT)\n\n## Installation\n\nThis library is installable via [Composer](https://getcomposer.org/):\n\n```bash\ncomposer require nicebooks/isbn\n```\n\n## Requirements\n\nThe current version of this library requires PHP 8.2 or higher.\n\nYou 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.\n\n## Project status \u0026 release process\n\nWhile this library is still under development, it is well tested and should be stable enough to use in production\nenvironments. It is currently in use in production on [nicebooks.com](https://nicebooks.com/).\n\nThe current releases are numbered `0.x.y`. When a non-breaking change is introduced (updating ISBN ranges,\nadding new methods, optimizing existing code, etc.), `y` is incremented.\n\n**When a breaking change is introduced, a new `0.x` version cycle is always started.**\n\nIt is therefore safe to lock your project to a given release cycle, such as `0.6.*`.\n\nIf you need to upgrade to a newer release cycle, check the [release history](https://github.com/nicebooks-com/isbn/releases)\nfor a list of changes introduced by each further `0.x.0` version.\n\n## Overview\n\n### The `Isbn` class\n\nThe `Isbn` class is an abstract, immutable class representing an ISBN-10 or ISBN-13 with a valid format and a valid check digit.\n\nIt has 2 subclasses: `Isbn10` and `Isbn13`, allowing for narrower typing if your application expects only ISBN-10 or only ISBN-13 at some point.\n\nAn `Isbn` instance is obtained with the `of()` factory method:\n\n```php\nuse Nicebooks\\Isbn\\Isbn;\n\n$isbn = Isbn::of('123456789X'); // will return an instance of Isbn10\n$isbn = Isbn::of('9781234567897'); // will return an instance of Isbn13\n```\n\nYou can also use the `Isbn10::of()` and `Isbn13::of()` factory methods, which will attempt to convert the given ISBN to the corresponding subclass:\n\n```php\nIsbn10::of('123456789X'); // equivalent to Isbn::of('123456789X')-\u003eto10();\nIsbn13::of('9781234567897'); // equivalent to Isbn::of('9781234567897')-\u003eto13();\n```\n\nIf the given string does not have a valid format or check digit, an `InvalidIsbnException` is thrown.\n\n\u003e [!NOTE]\n\u003e Before validation, the provided string is stripped of all non-alphanumeric ASCII characters.\n\n### Checking the type of an ISBN\n\nYou can check the type of an ISBN with the `is10()` and `is13()` methods:\n\n```php\nIsbn::of('123456789X')-\u003eis10(); // true\nIsbn::of('123456789X')-\u003eis13(); // false\n\nIsbn::of('9781234567897')-\u003eis10(); // false\nIsbn::of('9781234567897')-\u003eis13(); // true\n```\n\nYou can also use `instanceof` checks:\n\n```php\nIsbn::of('123456789X') instanceof Isbn10; // true\nIsbn::of('9781234567897') instanceof Isbn13; // true\n```\n\n### Converting between ISBN-10 and ISBN-13\n\nAn ISBN-10 can be converted to an ISBN-13 with the `to13()` method:\n\n```php\nIsbn::of('123456789X')-\u003eto13(); // Isbn13 instance with value 9781234567897\n```\n\nAn ISBN-13 can be converted to an ISBN-10 with the `to10()` method:\n\n```php\nIsbn::of('9781234567897')-\u003eto10(); // Isbn10 instance with value 123456789X\n```\n\nOnly 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:\n\n```php\nIsbn::of('9781234567897')-\u003eisConvertibleTo10(); // true\nIsbn::of('9791234567896')-\u003eisConvertibleTo10(); // false\n```\n\nIf you call `to10()` on an ISBN-13 that does not start with `978`, an `IsbnNotConvertibleException` is thrown.\n\n### Comparing ISBN numbers\n\nYou 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:\n\n```php\nIsbn::of('123456789X')-\u003eisEqualTo(Isbn::of('9781234567897')); // true\n```\n\n### Validating an ISBN\n\nWhile 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.\n\nThe `Isbn` class provides two methods to further validate an ISBN:\n\n| Method                        | Description                                                                                                                                                                              |\n|-------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| `hasValidRegistrationGroup()` | Only checks if the ISBN belongs to a **known registration group**.                                                                                                                       |\n| `isValid()`                   | Checks if the ISBN belongs to a **known registration group** and a **known range**.\u003cbr\u003eThis is the highest level of validation that can be performed by looking at the ISBN number alone. |\n\n\u003e [!NOTE]\n\u003e 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.\n\n\n### Formatting an ISBN\n\nThe library provides two methods to format an ISBN:\n\n| Method                | Description                                                                               | ISBN-10 example | ISBN-13 example     |\n|-----------------------|-------------------------------------------------------------------------------------------|-----------------|---------------------|\n| `toString()`          | Returns the unformatted ISBN                                                              | `133887893X`    | `9781338878936`     |\n| `toFormattedString()` | Returns the formatted ISBN if the ISBN is valid, otherwise returns the unformatted number | `1-338-87893-X` | `978-1-338-87893-6` |\n\n### Splitting an ISBN into parts\n\nAn ISBN-13 is divided into 5 parts:\n\n```\n978-1-338-87893-6\n——— — ——— ————— —\n A  B  C    D   E\n```\n\nWhile an ISBN-10 is divided into 4 parts:\n\n```\n1-338-87893-X\n— ——— ————— —\nB  C    D   E\n```\n\nThe `Isbn` class provides getters for each part:\n\n| Part | Example | Description                       | Getter                               |\n|------|---------|-----------------------------------|--------------------------------------|\n| `A`  | `978`   | Prefix                            | `getRegistrationGroup()-\u003eprefix`     |\n| `B`  | `1`     | Registration group identifier     | `getRegistrationGroup()-\u003eidentifier` |\n| `C`  | `338`   | Publisher identifier (registrant) | `getPublisherIdentifier()`           |\n| `D`  | `87893` | Title identifier (publication)    | `getTitleIdentifier()`               |\n| `E`  | `6`     | Check digit                       | `getCheckDigit()`                    |\n\n\u003e [!IMPORTANT]\n\u003e - Parts `A` and `B` require `hasValidRegistrationGroup()` (or `isValid()`, which implies it)\n\u003e - Parts `C` and `D` require `isValid()`\n\nYou can also get the ISBN parts as an array:\n\n```php\nIsbn::of('9781338878936')-\u003egetParts(); // ['978', '1', '338', '87893', '6']\n```\n\n\u003e [!IMPORTANT]\n\u003e `getParts()` requires `isValid()`\n\nIf the part you're trying to access is not available because the ISBN does not belong to a valid registration group or range, an `IsbnNotRecognizedException` is thrown.\n\n#### Getting the registration group name\n\n`getRegistrationGroup()` also exposes the group's `name`:\n\n```php\nIsbn::of('9781338878936')-\u003egetRegistrationGroup()-\u003ename; // 'English language'\n```\n\n### Exceptions\n\nExceptions live in the `Nicebooks\\Isbn\\Exception` namespace.\n\n- `IsbnException` is the abstract base class for all exceptions thrown by this library.\n  - `InvalidIsbnException` is thrown when an invalid ISBN is detected\n  - `IsbnNotConvertibleException` is thrown when trying to convert an ISBN-13 that does not start with `978` to an ISBN-10\n  - `IsbnNotRecognizedException` is thrown when an ISBN is semantically valid but does not belong to a recognized group or range\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnicebooks-com%2Fisbn","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnicebooks-com%2Fisbn","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnicebooks-com%2Fisbn/lists"}