OPDS PHP Ebook Publisher Class: Publish and distribute ebooks for download

                               OPDS Classes
                       Version 0.1 of May 17, 2020

                       -----===oooOO$OOooo===-----


    1. GENERAL
      1.1. Constraints

    2. PACKAGE
      2.1. What the package contains
          2.1.1. Restrictions
      2.2. What the package does not contain and what you will need

    3. IMPLEMENTATION

    4. ADVICE

    5. CREATE YOUR OWN EBOOKS



1. GENERAL
==========

In the rest of this document we will call ebook any digital document in
different formats (EPUB, MOBI, PDF, AZW3, etc.)

An OPDS system (Open Publication Distribution System) makes it possible to
offer a catalog of ebooks on a web server. These are classified by category
(e.g. Literature), subcategory (e.g. Theater), document (e.g. Le Cid). You
can consult the catalog according to the most recent publications or by
theme and download the chosen ebook among the proposed formats.

This catalog can be used for consultation and download :

-- Either from a smartphone or a tablet (which we will call device) with an
   embedded browser or better with an ebook reader (which is designed for
   this),

-- Or from a computer.

From a hardware or another, you will need on it the software or softwares
capable of reading ebooks in their format. We almost all have Acrobat
Reader on our computer to read PDF files, you will probably need another
software to read other formats (EPUB, MOBI, AZW3, etc.). The downloaded
ebooks can also be transfered to a commercial e-reader.

For your devices, you will probably find them on Google Play for Android
devices or Apple Store for Apple devices.

  1.1. Constraints
  ----------------

Catalogs are presented using XML files. The ebook-readers for devices are
designed to read these XML files (encoded in UTF-8) and the old browsers
were able to interpret the XML files which allowed the consultation of
these catalogs either from an ebook-reader, or from a web browser (on
computer or on device).

Mozilla Firefox, since version 56 (December 2018) has abandoned the
interpretation of XML. The other browsers followed and they have also
abandoned it since. As a result, with a current browser, the XML files
are no longer interpreted and are displayed as they are coded with the
information that no style sheet is associated with this XML file.


2. PACKAGE
==========

The package you downloaded from PHP Classes allows you to set up and offer
your visitors such a catalog of ebooks on your website.

    1.1. What the package contains
    ------------------------------

It contains, to consult the catalog of ebooks that you can offer and download
from it, two classes of PHP objects. Already integrated in PHP scripts :

-- index.php: contains the class that produces the XML necessary for use
   and download from a device ebook reader (smartphone or tablet)

-- ebooks.php: contains the class which produces the HTML necessary to do
   the same thing from a browser (computer or device) since these do not
   accept any more XML. This class (in the ebooks.php script) uses a style
   sheet: wopds.css, also provided, which you can modify if the
   presentation does not suit you.

-- A set of management files used to feed the database (MySQL, PostreSQL,
   mSQL, SQLite or any other database managed by the PDO API of PHP.

-- An SQL script allowing to create the necessary tables for the management
   of this catalog in a database created for this use or in an already
   existing database. There will be no confusion in the tables because they
   all start with the prefix opds_* (opds_Documents, opds_Authors, etc.)

The possibility is offered in the database, for various reasons which will
be yours, to hide one or more documents, one or more subcategories or one
or more complete categories of documents.

          1.1.1. Restrictions

PHP Classes is a PHP class repository, not an application repository. For
this reason, the management scripts used to feed this database do not
constitute a complete, professional application. It allows ONLY the
addition in the database but not the modifications, the main part of the
package being the OPDS classes (for ebook-readers and for web browsers).

Reason why, add only if you have all the information. If you have forgotten
or want to make changes to what has already been entered, use an interface
such as phpMyAdmin or similar to work directly in the database.

However, in the very near future, the scripts that make up the management
package will be used to add to their addition functionality, the
possibility of modifying existing records.

    1.2. What the package does not contain and what you will need
    -------------------------------------------------------------

If you are setting up such a catalog, you will need ebooks to make it work.
As PHP Classes is not an ebook repository, you can download a test set of
files from my website at:

     http://www.fauque.fr/dnl.php?f=182be0c5cdcd5072bb1864cdee4d3d6e

This ZIP file contains 3 documents (4 ebooks) and 2 thumbnails:

-- Cyberspace Declaration of Independence (EPUB and MOBI) + 1 thumbnail
-- Sigil version 0.7.2 User guide (EPUB)
-- Sigil version 0.9.15 User guide (EPUB) + the same thumbnail for both

The script for creating the necessary tables for managing the OPDS catalog
mentioned above already contains the information concerning these three
documents. You will not have to enter them but just put the downloaded
files in their place


3. IMPLEMENTATION
=================

I checked the procedure and it is operational. To make your tests, keep the
organization and the names which are proposed to you. When you have fully
assimilated the whole system, you will choose your own organization by
making the modifications (possibly in the scripts) that you deem useful.

-- On your hard drive create a directory called opds.

-- Unzip the entire downloaded package in this opds directory. This will
   create other subdirectories in it (authors, ebooks, management, img)
   containing files themselves.

-- Download from my website as indicated in the previous paragraph the zip
   file containing the test ebooks and unzip it in the opds directory of
   your hard drive (the ebooks and the thumbnails will be put in their
   respective places).

-- Open the file index.php (OPDS class for use by ebooks-readers) and
   modify the lines 48 to 55 to put your information (type of database,
   contact details for connection to the tables of your database)

-- Open the file ebooks.php (OPDS class for use by a browser) and modify
   the lines 49 to 56 to put your information (type of database, contact
   details for connection to the tables of your database) and the two
   lines 85 to 87 if, for some reason, you need to rename the ebooks.php,
   wopds.css or background-image files, otherwise, do not rename them.

-- Open the gestion/init.php file (located in the gestion subdirectory)
   and modify the lines 26 to 33 to modify your information (type of
   database, contact details for connection to the tables in your
   database).

-- Connect via FTP to your web server and transfer the opds directory and
   all its contents from your hard drive to the root of your web server.
   The opds directory will be the rootopds of your catalog. Your entire
   catalog is contained in this directory and in the database tables.
   Deleting the two (directory with their content and tables) will delete
   the complete OPDS system from your site.
  
-- use the opds.sql file to build tables and feed them with the necessary
   informations that are in this SAL script
   
-- Go to catalog management (the address just above) and start by
   configuring your catalog first (name, first name, email, etc.).
   Now read the documentation on the MCD site, Help, etc.

-- NB: The addresses to be used will be the following:
   For an ebook-reader:           http://www.yoursite.com/opds
   For a web browser:             http://www.yoursite.com/opds/ebooks.php
   For catalog management (adds): http://www.yoursite.com/opds/gestion

-- As soon as possible create the .htaccess and .htpasswd files mentionned
   in the help to protect your management directory.

If you follow this procedure exactly, you will obtain the same demo catalog
which is in:

-- http://www.fauque.fr/gopds  for ebook-readers of smartphones and tablets
-- http://www.fauque.fr/gopds/ebooks.php  for web browsers

Familiarize yourself with the catalog (on computer as on device), with the
creation of ebooks and put online your creations.

Any return message or request for help to my email address or here, on
PHP Classes, are welcome.


4. ADVICE
=========

For script modification (entering your login information or modifying the
code), be sure to use a text editor reading and recording in UTF-8. The
same goes for the database.

If you do not respect this encoding, the scripts will still work, maybe
with an altered display on the web, but they will cause a dead-lock error
with book-readers.


5. CREATE YOUR OWN EBOOKS
=========================

If you have a little HTML knowledge, you can relatively easily create your
own ebooks (Documentation, cooking recipes, poetry, instructions, etc.) to
always have them with you on your smartphone.

Indeed, an ebook in EPUB format is a set of zipped XHTML files. You can
also use Winzip to watch the content format and see how it is designed and
then be inspired by it to create your own.

You can download it from its original site or from the portable applications
site to install it on a USB key and be able to use it everywhere:

-- https://sigil-ebook.com (original site)
-- https://portableapps.com/apps/office/sigil-portable (portable application)

Have fun.

-----
05/30/2020. Pierre FAUQUE, pierre@fauque.net