Download the PHP package kiwilan/php-opds without Composer

PHP OPDS

PHP package to create OPDS feed (Open Publication Distribution System) for eBooks.

• Demo: https://bookshelves.ink/opds from bookshelves-project/bookshelves

All old versions: 0.9, 1.0 and 1.1 have a fallback to OPDS 1.2.

Requirements

• php v8.1 minimum

About

OPDS is like RSS feeds but adapted for eBooks, it's a standard to share eBooks between libraries, bookstores, publishers, and readers. Developed by Hadrien Gardeur and Leonard Richardson.

This package has been created to be used with bookshelves-project/bookshelves, an open source eBook web app.

[!NOTE] The Open Publication Distribution System (OPDS) catalog format is a syndication format for electronic publications based on Atom and HTTP. OPDS catalogs enable the aggregation, distribution, discovery, and acquisition of electronic publications. OPDS catalogs use existing or emergent open standards and conventions, with a priority on simplicity.

The Open Publication Distribution System specification is prepared by an informal grouping of partners, combining Internet Archive, O'Reilly Media, Feedbooks, OLPC, and others.

From Wikipedia

Some resources about OPDS and eBooks:

• opds.io: OPDS official website
• OPDS feeds examples
  • bookshelves.ink: Bookshelves (eBook web app, which use kiwilan/php-opds)
  • gallica.bnf.fr: Gallica (French National Library)
  • cops-demo.slucas.fr: COPS (OPDS PHP Server)
  • feedbooks.com: Feedbooks
• kiwilan/php-ebook: PHP package to handle eBook
• koreader/koreader: eBook reader for Android, iOS, Kindle, Kobo, Linux, macOS, Windows, and more. If your eReader can't use OPDS feeds, you can install KOReader on it
• edrlab/thorium-reader: A cross platform desktop reading app, based on the Readium Desktop toolkit. You can use it to use OPDS feeds and read eBooks

Features

• ⚛️ Generate OPDS XML and JSON feed (navigation feeds and acquisition feeds)
• 👌 Support OPDS 1.2 and 2.0
• 🔖 With pagination option
• 🔍 Search page included, but NOT search engine
• 🌐 Option to handle response to browser as XML or JSON

Roadmap

• [ ] OPDS 1.2: support advanced acquisition feeds
• [ ] OPDS 2.0: support Facets, Groups, advanced belongsTo
• [ ] Add OPDS Page Streaming Extension from anansi-project

Installation

You can install the package via composer:

Usage

You have to use Opds::make() method to create an OPDS instance, the only param is config to set OPDS config, totally optional. Default response is XML with OPDS version 1.2, you can force JSON response with OpdsConfig::class method forceJson() to use only OPDS 2.0. With get() method, you can get full instance of Opds with OpdsEngine and OpdsResponse.

You have different informations into Opds::class.

Some informations about OPDS instance:

And about engine and response:

OPDS Version

You can use query parameter version to set it dynamically. You could change this query into OpdsConfig::class.

• Version 1.2 can be set with ?v=1.2
• Version 2.0 can be set with ?v=2.0

[!WARNING]

If you set v query parameter to 1.2 with OpdsConfig::class method forceJson(), query param will be ignored.

OPDS Engine

Engine will convert your feeds to OPDS, depending of OPDS version.

• OPDS 1.2 will use OpdsXmlEngine::class
• OPDS 2.0 will use OpdsJsonEngine::class

You can get engine used with getEngine() method from Opds::class. Property contents contains array of feeds, OpdsEngine allow conversion into XML or JSON with __toString() method, the output depends of OPDS version.

OPDS Response

To build OPDS feed, you have to get() method. It will return an instance of Opds with OpdsEngine, OpdsResponse and paginator filled.

To get response, you can use getResponse() method from Opds::class.

Send response

[!NOTE]

This method is totally optional, you can send response to browser by yourself.

You can send response to browser by yourself from OpdsResponse to get status code, headers and contents or use send() method available into Opds and OpdsResponse.

• You can use send() from Opds or OpdsResponse to send response to browser (exactly the same)
• You don't have to call get() method before send() method, send() will call get() automatically

You can call get() method before send() method if you want to get OpdsResponse instance.

To get response

[!NOTE]

You can use exit parameter from send() method to stop script after sending response.

OPDS Config

OPDS config can be set with OpdsConfig::class:

[!NOTE]

You can override OpdsConfig with setter methods.

OPDS Pagination

You can use pagination from Opds with paginate() method, it will generate pagination based on maxItemsPerPage property from OpdsConfig::class.

• If you not set any parameter, it will generate pagination
• If you set OpdsPaginate object, it will generate pagination based on it

You can use OpdsPaginate::class to handle manual pagination

OPDS entry

Navigation

You can create a navigation entry with OpdsEntryNavigation::class:

[!TIP]

You can override OpdsEntryNavigation with setter methods.

And you can add this entry to OPDS feed with feeds() method:

Book

You can create a book entry with OpdsEntryBook::class:

[!WARNING]

Some properties can be used only into OPDS 2.0, see OPDS 2.0 specification.

[!TIP]

You can override OpdsEntryBook with setter methods.

And you can add this entry to OPDS feed with feeds() method:

Search

This package do NOT implements any search engine, you can use your own search engine and use Opds::class to create OPDS feed.

Query parameters used for search are statically defined into specifications:

• q param is used by OPDS 1.2
• query param is used by OPDS 2.0

[!TIP]

I advice Meilisearch for search engine, it's a powerful and easy to use search engine.

Here an example:

More usages

• Basic usage
• Advanced usage

Testing

Changelog

Please see CHANGELOG for more information on what has changed recently.

Credits

• OPDS creators: for OPDS specifications
• ewilan-riviere: author
• Contributors
• spatie/array-to-xml: to convert array to XML
• spatie/package-skeleton-php: skeleton for PHP package

License

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