kiwilan/php-ebook

PHP package to read metadata and extract covers from eBooks (.epub, .cbz, .cbr, .cb7, .cbt, .pdf).

Maintainers

Details

github.com/kiwilan/php-ebook

Homepage

Source

Issues

Fund package maintenance!
kiwilan

Installs: 24

Dependents: 0

Suggesters: 0

Security: 0

Stars: 1

Watchers: 0

Forks: 0

Open Issues: 0

0.34.0 2023-05-25 07:53 UTC

Requires

Requires (Dev)

MIT 639d72ca309ea4e0c80cbe0c285c1c324b865f09

  • Ewilan Rivière <ewilan.riviere.woop@gmail.com>

phpmetadatapdfbookebookepubcovercomicopfCBAcalibrecbrcbtcbzcb7epub2epub3comicinfocbam

This package is auto-updated.

Last update: 2023-05-29 12:04:55 UTC

README

php version downloads license

tests codecov

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 install rar binary to extract files, p7zip not support .rar extraction.
  • On Windows, for .pdf extract, 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

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

Applications

Desktop

Server

Tools

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

Credits

License

The MIT License (MIT). Please see License File for more information.