chrizus / php-ebook
PHP package to read metadata and extract covers from eBooks, comics and audiobooks.
Fund package maintenance!
kiwilan
Requires
- php: >=8.1
- kiwilan/php-archive: >=2.1.02
- kiwilan/php-audio: >=3.0.01
- kiwilan/php-xml-reader: >=1.0.11
Requires (Dev)
- laravel/pint: ^1.7
- pestphp/pest: ^1.20
- pestphp/pest-plugin-parallel: ^1.2
- phpstan/phpstan: ^1.10
- spatie/ray: ^1.28
This package is auto-updated.
Last update: 2025-03-06 00:59:13 UTC
README
Warning
This package is forked from kiwilan/php-ebook and adapted for my personal preference and use. I do not recommend using this package in your project, but use the original project kiwilan/php-ebook
![downloads][downloads-src]
![license][license-src]
![tests][tests-src]
[![codecov][codecov-src]][codecov-href]
PHP package to read metadata and extract covers from eBooks, comics and audiobooks.
- eBooks:
.epub
,.pdf
,.azw
,.azw3
,.kf8
,.kfx
,.mobi
,.prc
- Comics:
.cbz
,.cbr
,.cb7
,.cbt
(metadata from github.com/anansi-project) - Audiobooks:
.mp3
,.m4a
,.m4b
,.flac
,.ogg
To know more see Supported formats. Supports Linux, macOS and Windows.
Note
This package favors eBooks in open formats such as
.epub
(from IDPF) or.cbz
(from CBA) and which be parsed with native PHP, so for the best possible experience we recommend converting the eBooks you use. If you want to know more about eBook ecosystem, you can read documentation.
Warning
For DRM (Digital Rights Management) eBooks, in some cases you could read metadata but not contents (like HTML files for EPUB). To use all features, you have to use a software to remove DRM before using this package. For EPUB, you can use calibre with DeDRM plugin, this guide can help you.
Requirements
- PHP version
>=8.1
- PHP extensions:
- Binaries
p7zip
(optional) binarys for.CB7
(can handle.CBR
too)
- To know more about requirements, see Supported formats.
Note
You have to install requirements only if you want to read metadata for these formats, e.g. if you want to read metadata from
.cbr
files, you have to installrar
PHP extension orp7zip
binary. So all requirements for PHP extensions and binaries are optional.
Warning
Archives are handle with
kiwilan/php-archive
, for some formats (.cbr
and.cb7
)rar
PHP extension orp7zip
binary could be necessary. Some guides to install these requirements are available onkiwilan/php-archive
.
Features
- Support multiple formats, see Supported formats
- π Read metadata from eBooks, comics, and audiobooks
- πΌοΈ Extract covers from eBooks, comics, and audiobooks
- π Support metadata
- eBooks:
EPUB
v2 and v3 from IDPF withcalibre:series
from Calibre |MOBI
from Mobipocket (and derivatives) |FB2
from FictionBook - Comics:
CBAM
(Comic Book Archive Metadata) :ComicInfo.xml
format from ComicRack and maintained byanansi-project
PDF
withsmalot/pdfparser
- Audiobooks:
ID3
,vorbis
andflac
tags withkiwilan/php-audio
- eBooks:
- π Chapters extraction (
EPUB
only) - π¦
EPUB
andCBZ
creation supported
- Works perfectly with
kiwilan/php-opds
: PHP package to generate OPDS feeds (not included)
Roadmap
- Better
.epub
creation support - Add
.epub
metadata update support - Add better handling of MOBI files:
libmobi
andebook-convert
from Calibre (fallback is available) - Add support of
ebook-convert
from Calibre - Add suport for DJVU:
djvulibre
- Support FB2 archive
Installation
You can install the package via composer:
composer require chrizus/php-ebook
Usage
With eBook files or audiobook files (to know more about formats, see Supported formats).
use BergPlaza\Ebook\Ebook; $ebook = Ebook::read('path/to/ebook.epub'); $ebook->getPath(); // string => path to ebook $ebook->getFilename(); // string => filename of ebook $ebook->getExtension(); // string => extension of ebook $ebook->getTitle(); // string $ebook->getAuthors(); // BookAuthor[] (`name`: string, `role`: string) $ebook->getAuthorMain(); // ?BookAuthor => First BookAuthor (`name`: string, `role`: string) $ebook->getDescription(); // ?string $ebook->getDescriptionHtml(); // ?string $ebook->getCopyright(); // ?string $ebook->getPublisher(); // ?string $ebook->getIdentifiers(); // BookIdentifier[] (`value`: string, `scheme`: string) $ebook->getPublishDate(); // ?DateTime $ebook->getLanguage(); // ?string $ebook->getTags(); // string[] => `subject` in EPUB, `keywords` in PDF, `genres` in CBA $ebook->getSeries(); // ?string => `calibre:series` in EPUB, `series` in CBA $ebook->getVolume(); // ?int => `calibre:series_index` in EPUB, `number` in CBA
For pages count, you can use these methods:
$ebook->getPagesCount(); // ?int => estimated pages count (250 words by page) in `EPUB`, `pageCount` in PDF, `pageCount` in CBA $ebook->getWordsCount(); // ?int => words count in `EPUB`
Note
For performance reasons, with
EPUB
,pagesCount
andwordsCount
are only available on demand. If you usevar_dump
to check eBook, these properties will benull
.
Some metadata can be stored into extras()
method, without typing, directly from metadata.
$ebook->getExtras(); // array<string, mixed> => additional data for book $ebook->getExtra(string $key); // mixed => safely extract data from `extras` array
To know if eBook is valid, you can use isValid()
static method, before read()
.
use BergPlaza\Ebook\Ebook; $isValid = Ebook::isValid('path/to/ebook.epub');
To get additional data, you can use these methods:
$ebook->getMetadata(); // ?EbookMetadata => metadata with parsers $ebook->getMetaTitle(); // ?MetaTitle, with slug and sort properties for `title` and `series` $ebook->getFormat(); // ?EbookFormatEnum => `epub`, `pdf`, `cba` $ebook->getCover(); // ?EbookCover => cover of book
To access to archive of eBook, you can use getArchive()
method. You can find more informations about archive in kiwilan/php-archive
.
$ebook->getArchive(); // ?BaseArchive => archive of book from `kiwilan/php-archive`
And to test if some data exists:
$ebook->isArchive(); // bool => `true` if `EPUB`, `CBA` $ebook->isMobi(); // bool => `true` if Mobipocket derivatives $ebook->isAudio(); // bool => `true` if `mp3`, `m4a`, `m4b`, `flac`, `ogg` $ebook->hasMetadata(); // bool => `true` if metadata exists $ebook->hasCover(); // bool => `true` if cover exists $ebook->isBadFile(); // bool => `true` if file is not readable
Metadata
Ebook::class
contains many informations but if you want to access to raw metadata, metadata()
method is available.
use BergPlaza\Ebook\Ebook; $ebook = Ebook::read('path/to/ebook.epub'); $metadata = $ebook->getMetadata(); $metadata->getModule(); // Used into parsing can be any of `EbookModule::class` $metadata->getAudiobook(); // `AudiobookModule::class` $metadata->getCba(); // `CbaModule::class` $metadata->getEpub(); // `EpubModule::class` $metadata->getFb2(); // `Fb2Module::class` $metadata->getMobi(); // `MobiModule::class` $metadata->getPdf(); // `PdfModule::class` $metadata->isAudiobook(); // bool $metadata->isCba(); // bool $metadata->isEpub(); // bool $metadata->isFb2(); // bool $metadata->isMobi(); // bool $metadata->isPdf(); // bool
MetaTitle
Can be set if book's title is not null.
use BergPlaza\Ebook\Ebook; $ebook = Ebook::read('path/to/ebook.epub'); $metaTitle = $ebook->getMetaTitle(); // ?MetaTitle $metaTitle->getSlug(); // string => slugify title, like `the-clan-of-the-cave-bear` $metaTitle->getSlugSort(); // string => slugify title without determiners, like `clan-of-the-cave-bear` $metaTitle->getSlugLang(); // string => slugify title with language and type, like `the-clan-of-the-cave-bear-epub-en` $metaTitle->getSerieSlug(); // ?string => slugify series title, like `earths-children` $metaTitle->getSerieSort(); // ?string => slugify series title without determiners, like `earths-children` $metaTitle->getSerieLang(); // ?string => slugify series title with language and type, like `earths-children-epub-en` $metaTitle->getSlugSortWithSerie(); // string => slugify title with series title and volume, like `earths-children-01_clan-of-the-cave-bear` $metaTitle->getUniqueFilename(); // string => unique filename for storage, like `jean-m-auel-earths-children-01-clan-of-the-cave-bear-en-epub`
Cover
Cover can be extracted from ebook.
use BergPlaza\Ebook\Ebook; $ebook = Ebook::read('path/to/ebook.epub'); $cover = $ebook->getCover(); // ?EbookCover $cover->getPath(); // ?string => path to cover $cover->getContents(bool $toBase64 = false); // ?string => content of cover, if `$toBase64` is true, return base64 encoded content
Note
- For
imagick
PHP extension.- For Audiobook, cover can be extracted with some formats.
Formats specifications
EPUB
With EPUB
, metadata are extracted from OPF
file, META-INF/container.xml
files, you could access to these metatada but you can also get chapters from NCX
file. And with chapters()
method you can merge NCX
and HTML
chapters to get full book chapters with label
, source
and content
.
use BergPlaza\Ebook\Ebook; $ebook = Ebook::read('path/to/ebook.epub'); $epub = $ebook->getMetadata()?->getEpub(); $epub->getContainer(); // ?EpubContainer => {`opfPath`: ?string, `version`: ?string, `xml`: array} $epub->getOpf(); // ?OpfItem => {`metadata`: array, `manifest`: array, `spine`: array, `guide`: array, `epubVersion`: ?int, `filename`: ?string, `dcTitle`: ?string, `dcCreators`: BookAuthor[], `dcContributors`: BookContributor[], `dcDescription`: ?string, `dcPublisher`: ?string, `dcIdentifiers`: BookIdentifier[], `dcDate`: ?DateTime, `dcSubject`: string[], `dcLanguage`: ?string, `dcRights`: array, `meta`: BookMeta[], `coverPath`: ?string, `contentFile`: string[]} $epub->getNcx(); // ?NcxItem => {`head`: NcxItemHead[]|null, `docTitle`: ?string, `navPoints`: NcxItemNavPoint[]|null, `version`: ?string, `lang`: ?string} $epub->getChapters(); // EpubChapter[] => {`label`: string, `source`: string, `content`: string}[] $epub->getHtml(); // EpubHtml[] => {`filename`: string, `head`: ?string, `body`: ?string}[] $epub->getFiles(); // string[] => all files in EPUB
Note
For performance reasons, with
ncx
,html
andchapters
are only available on demand. If you usevar_dump
to check metadata, these properties will benull
.
Creation
You can create an EPUB or CBZ file with create()
static method.
Note
Only
EPUB
andCBZ
are supported for creation.
use BergPlaza\Ebook\Ebook; $creator = Ebook::create('path/to/ebook.epub'); // Build manually $creator->addFromString('mimetype', 'application/epub+zip') ->addFromString('META-INF/container.xml', '<?xml version="1.0" encoding="UTF-8" standalone="no" ?><container version="1.0" xmlns="urn:oasis:names:tc:opendocument:xmlns:container"><rootfiles><rootfile full-path="OEBPS/content.opf" media-type="application/oebps-package+xml"/></rootfiles></container>') ->save(); // Build from files $creator->addFile('mimetype', 'path/to/mimetype') ->addFile('META-INF/container.xml', 'path/to/container.xml') ->save(); // Build from directory $creator->addDirectory('./', 'path/to/directory') ->save();
Supported formats
There is a lot of different formats for eBooks and comics, if you want to know more about:
- Comparison of e-book formats for eBooks
- Comic book archive for comics
- Amazing MobileRead wiki
Name | Extensions | Supported | Uses | Support cover | Support series |
---|---|---|---|---|---|
EPUB (IDPF) | .epub |
β | Native zip |
β | β |
Kindle (Amazon) | .azw , .azw3 , .kf8 , .kfx |
β | Native filesystem |
β (See MOBI cover note) | β |
Mobipocket | .mobi , .prc |
β | Native filesystem |
β (See MOBI cover note) | β |
.pdf |
β | smalot/pdfparser (included) |
Uses imagick |
β | |
iBook (Apple) | .ibooks |
β | N/A | N/A | |
DjVu | .djvu , .djv |
β | N/A | N/A | |
Rich Text Format | .rtf |
β | N/A | N/A | |
FictionBook | .fb2 |
β | Native filesystem |
β | β |
Broadband eBooks | .lrf , .lrx |
β | N/A | N/A | |
Palm Media | .pdb |
β | N/A | N/A | |
Comics CBZ | .cbz |
β | Native zip |
β | β |
Comics CBR | .cbr |
β | rar PHP extension or p7zip binary |
β | β |
Comics CB7 | .cb7 |
β | p7zip binary |
β | β |
Comics CBT | .cbt |
β | Native phar |
β | β |
Audio | .mp3 , .m4a , .m4b , .flac , .ogg |
β | See kiwilan/php-audio |
Depends of format | β |
MOBI cover note
Mobipocket files and derivatives (.mobi
, .prc
, .azw
, .azw3
, .kf8
, .kfx
) can have a cover image embedded in the file. With native solution of php-ebook
cover could be extracted but resolution is not good. Best solution is to convert file with calibre
and use EPUB
format.
Testing
composer test
Changelog
Please see CHANGELOG for more information on what has changed recently.
Credits
spatie
forspatie/package-skeleton-php
kiwilan
forkiwilan/php-archive
,kiwilan/php-audio
,kiwilan/php-xml-reader
,kiwilan/php-ebook
- All Contributors
License
The MIT License (MIT). Please see License File for more information.