https://github.com/biblys/isbn
A PHP library to validate, convert and parse ISBNs and EANs
https://github.com/biblys/isbn
eans hacktoberfest isbn isbn-ranges php
Last synced: 29 days ago
JSON representation
A PHP library to validate, convert and parse ISBNs and EANs
- Host: GitHub
- URL: https://github.com/biblys/isbn
- Owner: biblys
- License: mit
- Created: 2014-04-19T17:54:57.000Z (about 12 years ago)
- Default Branch: main
- Last Pushed: 2026-04-15T07:20:49.000Z (2 months ago)
- Last Synced: 2026-04-15T09:30:25.633Z (2 months ago)
- Topics: eans, hacktoberfest, isbn, isbn-ranges, php
- Language: PHP
- Homepage:
- Size: 353 KB
- Stars: 56
- Watchers: 4
- Forks: 15
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
- Funding: .github/FUNDING.yml
- License: LICENSE
Awesome Lists containing this project
README
# biblys/isbn
[](https://github.com/biblys/isbn/actions/workflows/tests.yml)
[](https://packagist.org/packages/biblys/isbn)
[](https://packagist.org/packages/biblys/isbn)
[](http://opensource.org/licenses/MIT)
[](https://gitpod.io/#https://github.com/biblys/isbn)
biblys/isbn can be used to:
- [validate](#validate) a string against the ISBN-10, ISBN-13 and EAN-13 formats
- [convert](#convert) an ISBN to ISBN-10, ISBN-13, EAN-13, GTIN-14 and ISBN-A/DOI formats
- [parse](#parse) an ISBN to extract registration agency, publisher code, publication code, checksum, etc.
[CHANGELOG](https://github.com/biblys/isbn/releases)
## Installation
###
- Requirements: PHP 7.2 or above
Install with composer:
```console
composer require biblys/isbn:~3.0
```
## Usage
### Convert
Use case: converting an EAN (9782843449499) to an ISBN-13 (978-2-84344-949-9).
```php
getMessage();
}
```
All formatting methods:
- `Isbn::convertToIsbn10`
- `Isbn::convertToIsbn13`
- `Isbn::convertToEan13`
- `Isbn::convertToGtin14`
- `Isbn::convertToIsbnA`
### Validate
Use case: validating an incorrectly formed ISBN-13 (978-2-843-44949-9, should
be 978-2-84344-949-9).
```php
getMessage();
}
```
All validating methods:
- `Isbn::validateAsIsbn10`
- `Isbn::validateAsIsbn13`
- `Isbn::validateAsEan13`
- `Isbn::isParsable`
[Learn more about validating ISBNs](https://github.com/biblys/isbn/wiki/Validating-ISBNs-using-the-new-public-API)
### Parse
Use case: extracting the publisher code from an ISBN.
```php
getRegistrantElement(); // Prints "9564201"
```
`Isbn::parse` returns a `ParsedIsbn` object implementing the following methods:
- `ParsedIsbn->getGs1Element`:: EAN product code
- `ParsedIsbn->getRegistrationGroupElement`: Country, geographical region or language aera code
- `ParsedIsbn->getRegistrantElement`: Publisher (or imprint within a group) code
- `ParsedIsbn->getPublicationElement`: Publication code
- `ParsedIsbn->getCheckDigit`: Checksum used for validation
## Development
### Using Gitpod
You can start a dev environment by clicking
[](https://gitpod.io/#https://github.com/biblys/isbn)
and start hacking in your browser right away!
### Locally
If you'd rather set up a local dev environment, you'll need:
- PHP 7.x
- Composer
- (Optional) Docker to run tests and debug against different version of PHP
Clone this repository and run `composer install` to get started!
## Tests
Run tests with PHPUnit:
```console
composer install
composer test
```
Run tests in a docker container:
```console
composer docker:test
```
Run tests in a docker container using a specific PHP version:
```console
PHP_VERSION=7.1 composer docker:test
```
## ISBN ranges update
New ISBN ranges may be added from time to time by the
[International ISBN Agency](https://www.isbn-international.org/). Whenever it
happens, this library must be updated. If a range update is necessary, please
open an issue on GitHub.
You can also open a pull request after updating the ranges your self with the
following commands:
```console
composer install
composer run update-ranges
```
Or using a docker container:
```console
composer docker:update-ranges
```
## Create a minor release after ranges autoupdate
```shell
read "PR_NUMBER?Pull request number: "
gh pr merge --auto -dr "$PR_NUMBER" \
&& git fetch --tags \
&& CURRENT_VERSION=$(git tag --sort=-v:refname | head -n 1) \
&& IFS='.' read -r major minor patch <<< "$CURRENT_VERSION" \
&& NEW_VERSION="$major.$minor.$((patch + 1))" \
&& read "RELEASE_NOTES?Release notes: " \
&& gh release create "$NEW_VERSION" --title "$NEW_VERSION" --notes "$RELEASE_NOTES"
```
## Changelog
[See GitHub releases](https://github.com/biblys/isbn/releases)