Thank you for your purchase!

This one-page manual describes how to install the software, how to set up the preferences file, and how to use the software.

This index links to the indicated sections of the manual.

The Download Package

These files are in the download package:

README.txt
BackupRestore_common.php
BackupRestore_pagebottom.php
BackupRestore_pagetop.php
BackupRestoreDoBackup.php
BackupRestoreDoRestore.php
BackupRestoreManual.html
BackupRestoreMySQLclass.php
BackupRestorePreferences.php
BackupRestoreTableBackup.php

README.txt is a short text file introducing you to this installation and user's manual, file BackupRestoreManual.html.

The rest of the files are software files.

Installing the Software

Upload the files listed below somewhere that PHP software can run. Generally, a separate subdirectory keeps directories with other software files from getting overly cluttered.

BackupRestore_common.php
BackupRestore_pagebottom.php
BackupRestore_pagetop.php
BackupRestoreDoBackup.php
BackupRestoreDoRestore.php
BackupRestoreMySQLclass.php
BackupRestorePreferences.php
BackupRestoreTableBackup.php

The BackupRestorePreferences.php file will need to have preferences customized, as described in the next section, and then uploaded again.

The Preferences File

BackupRestorePreferences.php is the preferences file. It needs to be updated before Database Backup and Restore V2 is run.

Use a plain text processor to update the preferences file. Examples are TextWrangler for Mac and Notepad for Windows. Do an internet search for "plain text processor" to find more options.

Software that can format text (underlining, bolding, sizing) are not plain text processors and are likely to introduce code-breaking codes into the preferences file.

The preferences file is rather lengthy. Much of it is comments to make it easier to update. Many have default entries, but others require information you provide (like passwords, database names, and other information uniquely yours).

Here is an overview of the preferences file with links to sections in this manual.

• Control panel login preferences.
• Default MySQL host name.
• Memory management.
• Backup directory and files.
  • Backup directory.
  • Backup files in separate directories?
  • Subdirectory with database name?
  • Backup file name includes backup date?
  • Backup file name includes backup time?
  • Backup file name includes unique number?
  • Compress backup file?
  • Option to specify compression software.
  • Remove orignal JSON files after compression?
  • Delete old backup files? Keep how long?
• List database information for automatic backup.
• Notification options.

Each of the above items are addressed individually.

Section • Control panel login preferences.

This section is marked as  ~~ Control Panel ~~  in the BackupRestorePreferences.php file.

Specify your preferred username and password for the control panel. Space characters may be embedded within the username and/or password. Examples:

$LoginUsername = "Your Username";
$LoginPassword = "Your Password";

Replace Your Username with your preferred username and Your Password with your preferred password.

The password may be encrypted into a 40-character sha1 hash. (The sha1 hash is a cryptographic hexadecimal number, 40 characters long.)

To encrypt the password, use the public https://www.willmaster.com/secure/encrypt.php encryption form. When you obtain the encrypted version of your password, replace Your Password with your encrypted version.

Example with encrypted password:

$LoginUsername = "YourUsername";
$LoginPassword = "e405645aeb672561010680c471e9434e22c09a4f";

If the above-linked blog post is unavailable, you can make your own PHP script to encrypt your password.

<php
echo(sha1("YOURPASSWORD"));
?>

Replace YOURPASSWORD with your preferred password. Then do the following with the script:

1. Save it as temp.php

2. Upload temp.php to your server.

3. Run temp.php with your browser. If you can do so, use https:// instead of http:// to run temp.php

4. Copy the 40-character output and paste it where it belongs in the preferences file.

5. Delete temp.php from your server.

Section • Default MySQL host name.

This section is marked as  ~~ Default MySQL Host Name ~~  in the BackupRestorePreferences.php file.

Often, the MySQL host name is localhost, but may be something else for your hosting account.

Specify the host name where localhost is in this example.

$Hostname = "localhost";

Section • Memory management.

This section is marked as  ~~ Memory Management ~~  in the BackupRestorePreferences.php file.

Specify the number of megabytes of memory the backup software may utilize when doing its job. It is recommended that no more than 10% of memory available to PHP is specified here to avoid slowing down public access of your web pages. A decimal number may be specified. Example:

$MaxDataSize = 3;

Replace 3 with your preferred number.

<?php phpinfo(); ?>

If there is no value specified for the $MaxDataSize variable, or the variable is missing, no memory limit will be imposed by this software.

The software will take your specification into consideration, but may retrieve more than the maximum amount at various times. This could happen for table rows with larger amount of content than average for that table. And it would happen when the maximum data size is smaller than the average table row. In other words, your memory-limit specification it taken under advisement, not treated as a hard limit.

Section • Backup directory and files.

This section is marked as  ~~ Backup Directory and Files ~~  in the BackupRestorePreferences.php file.

Specify the directory for the backup files. The directory may be specified relative to document root (begins with "/" character) or relative to the Database Back Up and Restore installation directory (does not begin with "/" character).

Here are two examples, the first relative to document root and the second relative to the installation directory:

$BackupFilesDirectory = "/php/backup/backupfiles";
$BackupFilesDirectory = "backupfiles";

The backup files directory must have permissions sufficient to allow this software to create subdirectories as needed.

The rest of this section of the preferences file has numerous subsections. Each subsection is addressed individually.

Subsection ~ Backup files in separate directories?

This subsection is marked as  Backup File Sets in Separate Subdirectory --  in the BackupRestorePreferences.php file.

Shall backup file sets be placed in separate subdirectories? Specify "yes" (case insensitive) for yes or anything else for "no". Example:

$BackupFileSetsInSeparateSubdirectory = "Yes";

If "yes", the files of each back-up are saved in a subdirectory named according to the current date. The subdirectory is located within the backup files directory specified above.

Specifying Yes is required if old backup files are to be deleted automatically. (See the Subsection ~ Delete old backup files? Keep how long? section, further below.)

Subsection ~ Subdirectory with database name?

This subsection is marked as  Backup Files in Subdirectory With Database Name --  in the BackupRestorePreferences.php file.

Shall the backup files be in a subdirectory composed of the database name? Specify "yes" (case insensitive) for yes or anything else for "no". Example:

$BackupFileDatabasesInSeparateSubdirectories = "Yes";

If "yes", the backup files are saved in a subdirectory named as the database name.

Specifying "yes" is recommended so tables with identical names in multiple-databases won't clobber each other.

Subsection ~ Backup file name includes backup date?

This subsection is marked as  Backup Files Names Contain Date of Backup --  in the BackupRestorePreferences.php file.

Shall file names include date of backup? (case-insensitive "yes" or anything else for "no") If "yes", the file names of each back-up are saved separately, so long as the back-up is done on a different day. Otherwise, a backup may overwrite previous backup files. Example:

$EmbedDateWithinBackupFileName = "Yes";

Specifying "yes" is recommended unless each back-up's files are downloaded before another back-up is done. It will also allow recognition of backup date by file name.

Subsection ~ Backup file name includes backup time?

This subsection is marked as  Backup Files Names Contain Time of Backup --  in the BackupRestorePreferences.php file.

Shall file names include time of backup? (case-insensitive "yes" or anything else for "no") If "yes", the file names of each back-up are saved separately. Otherwise, a backup may overwrite previous backup files. Example:

$EmbedTimeWithinBackupFileName = "Yes";

Specifying "yes" is recommended if backups are made more than once per day. Specifying "yes" will allow recognition of backup time by file name.

Subsection ~ Backup file name includes unique number?

This subsection is marked as  Backup File Names Contain Unique Number --  in the BackupRestorePreferences.php file.

Shall file names always be unique, even if the same table is backed up into the same directory two or more times almost simultaneously? (case-insensitive "yes" or anything else for "no") If "yes", the file names of each back-up have a unique number, the same number per set of backup files. Example:

$EmbedUniqueNumberWithinBackupFileName = "Yes";

Subsection ~ Compress backup file?

This subsection is marked as  Compress Backed Up File --  in the BackupRestorePreferences.php file.

When a database table is backed up, shall the backed-up file be compressed? (case-insensitive "yes" or anything else for "no")

$CompressBackedUpFiles = "Yes";

Note: When a backup file is larger than the compression software can handle with the available server resources, the backup file is not compressed.

Subsection ~ Option to specify compression software.

This subsection is marked as  File Compression Software to Use --  in the BackupRestorePreferences.php file.

This software can determine which of two types of file compression software are available on the server. If you leave this item blank, it will do that determination. But if you want to specify which to use (assuming the above $CompressBackedUpFiles variable is set to "yes"), specify either 'ZIP' or 'GZ' (case-insensitive). Example:

$CompressionSoftware = "ZIP";

Unless there is a compelling reason to specify the compression software, leaving the value blank is recommended.

$CompressionSoftware = "";

Subsection ~ Remove orignal JSON files after compression?

This subsection is marked as  Delete Original Backup Files After Compression --  in the BackupRestorePreferences.php file.

When a JSON backup file is compressed, shall the original JSON backup file be removed immediately after compression? (case-insensitive "yes" or anything else for "no") Example:

$RemoveBackedUpFilesAfterCompression = "Yes";

If a backup file can't be compressed (generally because backup file is larger than available server resources can handle), the original JSON backup file will not be removed. Only if it can be compressed is the original removed immediately after compression.

Subsection ~ Delete old backup files? Keep how long?

This subsection is marked as  Delete Old Backup Files --  in the BackupRestorePreferences.php file.

If old backup files shall be deleted from the server automatically, specify the number of days to keep the backup files before they are deleted. To not automatically delete old backup files, specify the digit 0 or a negative number like -1.

$NumberOfDaysToKeepBackupFiles = 0;

Note: Old backup files will only be deleted if they were created with the $BackupFileSetsInSeparateSubdirectory = yes variable specified in the Subsection ~ Backup File Sets in Separate Subdirectory section, further above.

Section • List database information for automatic backup.

This section is marked as  ~~ Backup Databases and Tables ~~  in the BackupRestorePreferences.php file.

The part to update has two lines:

$BackupList = <<<'MARK'

MARK;

Between those two lines (each containing the word MARK), specify the username, password, database and, optionally, the tables for backing up.

The username password database need to be in that order, one or more spaces between each, all on the same line. If specific tables are listed, they need to come after database and on the same line and separated with one or more spaces. Each line is a set.

The set is a backup directive.

You may specify as many sets/backup directives as you wish between the two MARK lines, each set on a line by itself. There may be blank lines between sets.

Here is an example with three sets.

$BackupList = <<<'MARK'

user pass database
user2 pass2 database2 table

user3 pass3 database3 table1 table2 table3 table4
MARK;

Note that each element of a set (username, password, database, optional tables) is separated with one or more spaces. Do not separate with a comma or any other characters — just spaces.

Section • Notification options.

This section is marked as  ~~ Notification ~~  in the BackupRestorePreferences.php file.

Optionally, an email with backed-up table names may be sent when the BackupRestoreDoBackup.php PHP script is run. If the option is elected, the email will be sent whether BackupRestoreDoBackup.php is run as a cron job or via a browser.

To have an email notification sent, specify the destination email address for value $EmailAddress. Example:

$EmailAddress = "name@example.com";

Replace name@example.com with the correct destination address.

If an email notification is to be sent, specify the email subject line to use. Example:

$EmailSubject = "[backup] MySQL";

Replace [backup] MySQL with the subject line you prefer.

If an email notification is to be sent, shall the table names contain size information? (case-insensitive "yes" or anything else for "no").

$NotificationHasSizeInformation = "Yes";

Full Backup

A full backup backs up the databases and any individual database tables in the backup list specified in the BackupRestorePreferences.php preferences file at the ~~ Backup Databases and Tables ~~ section.

The URL to file BackupRestoreDoBackup.php does the trick. Example URL:

https://example.com/php/backup/BackupRestoreDoBackup.php

To do a manual full backup, type the URL of BackupRestoreDoBackup.php into your browser.

To set up a cron schedule, have it get the same URL.

Individual Tables Backup

Individual tables can be backed up as needed, perhaps before doing manual edits to the table or otherwise exposing the data to an unusual possibility of corruption.

Type the URL of file BackupRestoreTableBackup.php into your browser to get the control panel. Example URL:

https://example.com/php/backup/BackupRestoreTableBackup.php

When the control panel loads, you may need to log in. Log in with the control panel username and password specified in the preferences file.

After logging in, you'll see a list of all the databases that the full backup would do.

Each database has a checkbox next to it and a text box below it.

When you check the checkbox of a database, optionally use the textbox to list the tables in the database to be backed up. If no tables are listed, then the checked database will be backed up in its entirety.

To complete the backup, click the submit button.

Restoring From Backup Files

Use this to restore a table. The table can be restored in the original location or elsewhere (making it suitable for moving MySQL database table data to another server).

Backups are plain text, JSON-encoded files.

The first five lines of the file contain this essential information:

1. Database name.
2. Table name.
3. Table status.
4. Table structure.
5. Column Types.

The rest of the file is the backed-up table content.

Backup files to restore need to be on the server accessible by this software.

To restore a backup file, type the URL of file BackupRestoreDoRestore.php into your browser to get the control panel. Example URL:

https://example.com/php/backup/BackupRestoreDoRestore.php

When the control panel loads, you may need to log in. Log in with the control panel username and password specified in the preferences file.

After logging in, you'll see a text box for specifying the location of the JSON file to restore. Specify the location relative to the document root, which is the file's URI.

(The URI is the URL minus the http:// and domain name. If its URL is http://example.com/php/backup/file.json then its URI is /php/backup/file.json )

Next control panel page — When the button is clicked, the next page asks for information about the restoration.

The database name and table name are pre-filled in. But they can be changed in case you want to restore to a different location.

You'll see statistics related to number of rows and table data size.

You'll also see an HTML table listing the table column names and types. Each column name and type has an associated checkbox. The checkbox can be used to omit that particular column from the restoration.

Reasons for omitting a column include (i) restoring to a different server or table that doesn't have one or more of the columns in the backup or (ii) omitting a column of unique keys for appending to the current table instead of replacing the entire table with the backup.

Finally, there are two radio buttons, one to direct the software to replace the table data with the backed up data and the other to direct the software to append the backed up data to the information already in the table.

Click the button to restore the data in the JSON-encoded backup file.

Support

Because links and email addresses may change, let me first say that you can always get support by going to https://www.willmaster.com and clicking the "Support" menu item.

If links and email addresses haven't changed since you bought this software, these can be used for support or, if you wish, to ask software questions or just to talk.

• The will@ email address for the willmaster.com domain and/or the flowto.us domain.

• The help desk at https://www.willmaster.com/support/helpdesk.php

• The general contact form at https://www.willmaster.com/contact.php

Again, thank you for your purchase. We wish you the best of all you want.