kiwilan / php-ebook
PHP package to read metadata and extract covers from eBooks (.epub, .cbz, .cbr, .cb7, .cbt, .pdf).
Fund package maintenance!
kiwilan
Requires
- php: ^8.1
- kiwilan/php-archive: ^1.2.01
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: 2023-05-29 12:04:55 UTC
README
PHP package to read metadata and extract covers from eBooks (.epub
, .cbz
, .cbr
, .cb7
, .cbt
, .pdf
).
Supports Linux, macOS and Windows.
Warning
Works with kiwilan/php-archive, for some formats (
.cbr
and.cb7
)rar
PHP extension or p7zip binary could be necessary, see Requirements.
About
This package was built for bookshelves-project/bookshelves-back, a web app to handle eBooks.
Requirements
- PHP >= 8.1
- Depends of extension and features you want to use
Type | Native | Dependency |
---|---|---|
.epub , .cbz |
✅ | N/A |
.cbt |
✅ | N/A |
.cbr |
❌ | rar PHP extension or p7zip binary |
.cb7 |
❌ | p7zip binary |
.pdf |
✅ | Optional (for extraction) imagick PHP extension |
ALL | ❌ | p7zip binary (rar PHP extension and imagick PHP extension are optional) |
Note
Here you can read some installation guides for dependencies
Warning
- On macOS, for
.rar
extract, you have to installrar
binary to extract files,p7zip
not support.rar
extraction.- On Windows, for
imagick
PHP extension have to work but my tests failed on this feature. So to extract PDF pages I advice to use WSL.
If you want more informations, you can read kiwilan/php-archive.
Features
- Read metadata from eBooks
- Extract covers from eBooks
- Support metadata
- EPUB v2 and v3 from IDPF
calibre:series
for EPUB from Calibrecalibre:series_index
for EPUB from CalibreComicInfo.xml
(CBAM) format from ComicRack and maintained by anansi-project- PDF by smalot/pdfparser
Installation
You can install the package via composer:
composer require kiwilan/php-ebook
Usage
With eBook files (.epub
, .cbz
, .cba
, .cbr
, .cb7
, .cbt
, .pdf
)
$ebook = Ebook::read('path/to/archive.epub'); $metadata = $ebook->metadata(); // OpfMetadata|CbaMetadata|null => metadata OPF for EPUB, metadata CBA for CBA $format = $book->format(); // epub, pdf, cba $book = $ebook->book(); // ?BookEntity $cover = $ebook->cover(bool $convertBase64 = true); // string => cover as string ($toString convert base64) $path = $ebook->path(); // string $filename = $ebook->filename(); // string $extension = $ebook->extension(); // string $hasMetadata = $ebook->hasMetadata(); // bool
Metadata
$metadata = $ebook->metadata(); // OpfMetadata|CbaMetadata|null => metadata OPF for EPUB, metadata CBA for CBA // For OpfMetadata $metadata->metadata(); // `metadata` entry from `.opf` file $metadata->manifest(); // `manifest` entry from `.opf` file $metadata->spine(); // `spine` entry from `.opf` file $metadata->guide(); // `guide` entry from `.opf` file $metadata->dcX(); // `dcX` entries from `.opf` file // For CbaMetadata, see docs https://anansi-project.github.io/docs/comicinfo/documentation $metadata->writers(); // `writers` entry from `ComicInfo` format $metadata->pencillers(); // `pencillers` entry from `ComicInfo` format // more from `ComicInfo` format
Book
$book = $ebook->book(); // BookEntity $book->title(); // string $book->metaTitle(); // ?MetaTitle, with slug and sort properties for `title` and `series` $book->authors(); // BookCreator[] (name: string, role: string) $book->authorFirst(); // ?BookCreator => First BookCreator (name: string, role: string) $book->description(); // ?string $book->contributor(); // ?string $book->rights(); // ?string $book->publisher(); // ?string $book->identifiers(); // BookIdentifier[] (content: string, type: string) $book->date(); // ?DateTime $book->language(); // ?string $book->tags(); // string[] => `subject` in EPUB, `keywords` in PDF, `genres` in CBA $book->series(); // ?string => `calibre:series` in EPUB, `series` in CBA $book->volume(); // ?int => `calibre:series_index` in EPUB, `number` in CBA $book->rating(); // ?float => `rating` in CBA $book->pageCount(); // ?int => computed from words (250 words by page) in EPUB, `pageCount` in PDF, `pageCount` in CBA $book->wordsCount(); // ?int => words count in EPUB $book->editors(); // string[] => `editors` in CBA $book->review(); // ?string => `review` in CBA $book->web(); // ?string => `web` in CBA $book->manga(); // ?MangaEnum => `manga` in CBA | Additional data about mangas $book->isBlackAndWhite(); // bool => `blackAndWhite` in CBA $book->ageRating(); // ?AgeRatingEnum => `ageRating` in CBA | Additional data about age rating $book->comicMeta(); // ?ComicMeta => Additional data for CBA
MetaTitle
Can be set if book's title is not null.
$metaTitle = $book->metaTitle(); // ?MetaTitle $metaTitle->slug(); // string => slugify title, like `the-clan-of-the-cave-bear` $metaTitle->slugSort(); // string => slugify title without determiners, like `clan-of-the-cave-bear` $metaTitle->slugLang(); // string => slugify title with language and type, like `the-clan-of-the-cave-bear-epub-en` $metaTitle->serieSlug(); // ?string => slugify series title, like `earths-children` $metaTitle->serieSort(); // ?string => slugify series title without determiners, like `earths-children` $metaTitle->serieLang(); // ?string => slugify series title with language and type, like `earths-children-epub-en` $metaTitle->slugSortWithSerie(); // string => slugify title with series title and volume, like `earths-children-01_clan-of-the-cave-bear`
Testing
composer test
Changelog
Please see CHANGELOG for more information on what has changed recently.
Resources
OS
- koreader/koreader: an ebook reader application supporting many more formats, running on ereaders and Android devices
- baskerville/plato: document reader
Applications
Desktop
- kovidgoyal/calibre: calibre ebook manager
- troyeguo/koodo-reader: modern ebook manager and reader with sync and backup capacities for Windows, macOS, Linux and Web
- thorium: EPUB reader for Windows, MacOS and Linux (support OPDS)
Server
- greizgh/bookshelf: lightweight epub online catalog (support OPDS)
- Bookshelf: publier ses ebooks simplement: usage of
greizgh/bookshelf
(french)
- Bookshelf: publier ses ebooks simplement: usage of
- Kareadita/Kavita: fast, feature rich, cross platform reading server, built with a focus for manga (support OPDS)
- gotson/komga: media server for comics/mangas/BDs with API (support OPDS)
- advplyr/audiobookshelf: self-hosted audiobook and podcast server
- bookshelves-project: web application to manage eBooks (support OPDS)
- seblucas/cops: Calibre OPDS PHP Server, web-based light alternative to Calibre content server (support OPDS)
- janeczku/calibre-web: Web app for browsing, reading and downloading eBooks stored in a Calibre database
Tools
- framabook/systeme-publication-framabook: with pandoc, provides the basics for deploying an accessibility compliant epub production system using only command line tools in a Bash shell terminal. (french)
- pandoc.org: creating an ebook with pandoc
- dino-/epub-tools: command line utilities for working with epub files
- comictagger/comictagger: a multi-platform app for writing metadata to digital comics
Metadata
- IDPF/epub3-samples: EPUB 3 Sample Documents
- anansi-project: initiative to bring structure and cohesion to the world of metadata for Comic Books, Mangas, and other graphic novels.
- Comic Book Archive (CBA) metadata
- Comic Book Archive Metadata (CBAM) / ComicRack Metadata (CRM)
- Comic Book Markup Language (CBML)
- comictagger/wiki/MetadataSchemes: all the details [...] on various open metadata schemes for comic archives
- comicvine: the largest comic book wiki in the universe
- w3.org: EPUB specs by W3C
- opds.io: OPDS specs
OPDS
The Open Publication Distribution System (OPDS) is an application of the Atom Syndication Format intended to enable content creators and distributors to distribute digital books via a simple catalog format. This format is designed to work interchangeably across multiple desktop and device software programs. From mobileread
- atramenta.net
- ebooksgratuits.com (french)
- gallica.bnf.fr
- wikisource.org
- bibebook.com (french)
- standardebooks.org
- gutenberg.org
- feedbooks.com
Credits
- Kiwilan
- All Contributors
- spatie for
spatie/package-skeleton-php
License
The MIT License (MIT). Please see License File for more information.