Documentation

Requirements

We recommend the latest version of the following software to run phpSEL:

• Apache or Nginx for the web server with PHP
• MySQL or MariaDB for the database

Installation

Things to do before installing

1. Ensure that you have access to a web server with PHP and MySQL/MariaDB.
2. Create a database for phpSEL on your web server, as well as a MySQL/MariaDB user who has all privileges for accessing and modifying it.

Obtaining phpSEL

Dowloading the zip file

1. Download the latest version of phpSEL via the provided zip file.
2. Unpack the zip file and upload the contents of the phpsel directory to the desired location on your web server.

Download from Bitbucket via Git

You can clone the project from it's git repository with the following command:
git clone https://bitbucket.org/tenchi39/phpsel.git

After cloning the project, you need to run the following command in the command line to download the necessary components of phpSEL:
php composer.phar install

Automatic setup

1. Run the phpSEL setup script by accessing the URL in a web browser. This should be the URL where you uploaded the phpSEL files.
   If you installed phpSEL in the root directory, you should visit: http://example.com/
   If you installed phpSEL in its own subdirectory called phpsel, for example, you should visit: http://example.com/phpsel
   If you installed phpSEL on XAMPP on your local machine in the c:\xampp\htdocs\phpsel directory, you should visit: http://localhost/phpsel
2. Follow the on-screen instructions to create the configuration file and database for phpSEL on your server.
3. If the setup process could not create the config.php file, create it yourself and insert the configuration that is displayed at the end of the setup process.
4. Click the Log in button at the end of the setup process or access the URL again to open phpSEL.

Manual setup

If for any reason you do not wish to use the setup script to install the database and create the config.php file, you can install phpSEL manually:

1. Import the database dump into your MySQL/MariaDB server.
   If you want to include the example books with the installation, use the database-prepopulated.sql file.
   If you don't need the example books, use the database-empty.sql file.
   
2. If you imported the prepopulated database, copy over the contents of the example books and covers directories.
   /data/examples/books >>> /data/books
   /data/examples/covers >>> /data/covers
3. Rename config-sample.php to config.php and open it in a text editor.
   (Our recommendation is Sublime Text.)
4. Edit the basic settings:
   • $subdirectory
     If you installed phpSEL in the root directory, the values should be empty.
     If you installed phpSEL in its own subdirectory called phpsel, for example, the value should be 'phpsel'.
     If you installed phpSEL on XAMPP on your local machine in the c:\xampp\htdocs\phpsel directory, the values should be 'phpsel'.
   • $protocol
     The default connection protocol is http, but if you are using https, change the value to 'https'.
   • $site_title
     This variable defines the name of your library. Give it a unique name to make it your own.
5. Enter your database information:
   • $db_host
     The hostname of the database server. This is usually localhost, but can be different on your server.
   • $db_port
     The database port, if it differs from the default value on your server.
   • $db_database
     The name of the database you created for phpSEL.
   • $db_user
     The username you can access the database with.
   • $db_password
     The password associated with the database user.
6. Edit the user settings:
   • $login_username
     The username you can log into phpSEL with. It is a good idea to change it to something unique.
   • $login_password
     The password associated with your username. It is highly recommended to change this from the default value to protect your library. You might even give a password generator a try.
7. Save config.php and log in by visiting the URL in a web browser. This should be the URL where you uploaded the phpSEL files.
   If you installed phpSEL in the root directory, you should visit: http://example.com/
   If you installed phpSEL in its own subdirectory called phpsel, for example, you should visit: http://example.com/phpsel
   If you installed phpSEL on XAMPP on your local machine in the c:\xampp\htdocs\phpsel directory, you should visit: http://localhost/phpsel

Updating

Updating from a zip file

1. Delete all files and directories from your phpSEL directory except for /data. You might also want to keep a backup copy of config.php, so you can keep the changes you made to the configuration.
2. Extract the contents of the zip file into the phpSEL directory. You can allow it to overwrite /data as this will not effect your uploaded files.
3. Open phpSEL in your browser to run the setup process again, or copy back your previous config.php file. (Be sure to check if there was a change in the config.php file format since your previous installation by consulting the changelog.)

Updating via Git

Git will manage all changes automatically, but be sure to check the changelog if the config.php file was changed since your version. If it was, it might be a good idea to rename or delete config.php and to run the setup process again. (It will not overwrite your files or database.)

To upgrade, use the following command in the phpSEL directory:
git pull

Customization

You can customize some aspects of phpSEL by editing certain values in the config.php file:

• $demo_mode
  Setting this variable to 'true' will disable file upload and deletion. This is mainly used in the online demo of phpSEL on https://phpsel.randomblog.hu/demo.
• $check_for_updates
  Setting this variable 'false' will hide notifications and disable checking for newer versions once a day.
• $login_message
  You can set a message to appear under the login box here. You can use html to style it to your liking.
• $list_items
  This variable defines how many books the list page will show at once.
• $list_default_order
  This variable defines the default order the books are listed by.
  The possible values are: 'id', 'title', 'title_original', 'author', 'genre', 'series', 'world', 'publisher', 'year_of_publication', 'year_of_first_publication'
• $list_default_direction
  This variable defines the default listing direction on the list page.
  The possible values are: 'DESC' for descending, 'ASC' for ascending
• $list_image_max_width
  The default maximum image width on the list page.
• $list_image_max_height
  The default maximum image height on the list page.
• $details_image_max_width
  The default maximum image width on the details page.
• $details_image_max_height
  The default maximum image height on the details page.
• $file_conversion
  Setting this variable to 'false' will hide conversion links for the uploaded e-book files on the details page.
• $qr_code
  Setting this variable to 'false' will hide the QR code link for the uploaded e-book files on the details page that you can use with your phone camera to download said files.
• $time_format
  This variable defines the date format to use on the details page
  '1' - MM/DD/YYYY HH:MM:SS
  '2' - YYYY/MM/DD HH:MM:SS
• $search_links[]
  You can define custom search links to be displayed on the details page based on the given examples in the config.php file. For this you have to define an array that consists of the search url, the search term and the text for the search link. Just make a copy of a line starting with $search_links[] and change the values of the array.
  The search term can have the following values:
  
  • 'title' - The book's title
  • 'author' - The author's name
  • 'title_author' - The book's title and author

Email to device

If you have a book reader device that supports receiving book files via email (Kindle, PocketBook) or use such an app on your phone or tablet to read books, you can set up phpSEL to send your books to your device with the push of a button. You have to set up the corresponding variables in config.php to make the Email to device button appear - and work on the details page.

This feature works by sending the e-book file as an attachment via e-mail to your device's e-mail address (target e-mail) from an authorized address (source e-mail) that you have to set up first. Read more about how to set these for Kindle devices here.

• $email_to_device
  Setting this variable to 'true' will show the Email to device button on the details page.
• $email_to_device_address
  This is the target e-mail address where phpSEL sends the e-book file as an e-mail attachment.
• $email_to_device_from
  This is the source e-mail address from where phpSEL sends the e-book to the target e-mail.
• $email_to_device_smtp_server
  This is the smtp server address of the source e-mail.
• $email_to_device_smtp_username
  This is the smtp username of the source e-mail.
• $email_to_device_smtp_password
  This is the smtp password of the source e-mail.
• $email_to_device_smtp_security
  This is the smtp security type of the source e-mail.
• $email_to_device_smtp_port
  This is the smtp port number of the source e-mail.
• $email_to_device_formats
  This is the list of file formats that phpSEL will show the Email to device button for. The list is stored as an array, so you can easily add or remove elements from it.

Theming

phpSEL is built upon Zurb Foundation with minimal added styling. If you don't like the default look of phpSEL, you can customize it by editing the /css/style.css file.

Translating

The text visible on the user interface of phpSEL is not directly stored in the source code, but in a separate php file under /lng in an array that is made up of identifiers and the corresponding texts to be displayed like this:

$lng = array(
	"title_original" => "Original title", 
	"genre" => "Genre", 
	"genres" => "Genres", 
	"active_search" => "Active search", 
	"world" => "World", 
	"worlds" => "Worlds", 
	...
	...

Making a translation

1. Make a copy of any language file in /lng and name it based on the ISO 639-1 code of the target language.
   For example if you want to make a French translation of the English language file, make a copy of /lng/en.php and save it as /lng/fr.php.
2. Open the new language file in a text editor like Sublime Text and edit the right side of each line after the arrow between the quotation marks. Be sure to leave the left side unchanged and do not add or remove any lines.
3. Replace the value of the $site_language parameter in the config.php file to match the language code of your translation to switch to the new language on the user interface.

Making official translations

If you would like to help making phpSEL multilingual, please do contact us. Keep in mind that phpSEL could evolve and that could possibly require revisions of your translation in the future.

Languages available

Currently the following languages are supported by phpSEL and the community:

• English