Skip to main content

Installing phpList manually

This chapter explains how to manually install phpList. You may wish to install it using an automated tool if one is available to you. See the auto-installation chapter for more information on this.

Overview of phpList installation

phpList lives in its own folder called "lists." Manual installation follows these steps:

  • Download phpList
  • Unzip phpList
  • Upload to your server using FTP
  • Local Windows installation
  • Create a database
  • Add the database details to the config.php file
  • Configure using web interface.

Download phpList

First check that your server meets the System Requirements. Then download the latest version of phpList from http://www.phplist.com/download by clicking either Download ZIP or Download TGZ.

Screenshot-from-2019-06-29-22-12-22.png

Unzip phpList

Once you have downloaded phpList to your computer, unpack it to a temporary folder. You can usually do this by right clicking and choosing Extract Here (Linux, as in screenshot), double clicking the folder (mac) or right click "extract all" (Windows).

phpList_extract_here.png

Upload to your server using FTP

Start your favourite FTP program, in this case we are using FileZilla.

Browse though to your temporary folder in the FTP program, then open the public_html folder to find the lists folder.

navigate_to_extracted_phplist.png
 

Upload this /lists folder into your public_html file on your server. This folder may have lots of files in it already. In the image below you can see the public_html folder on the server contains folders for a WordPress site.

phpList_upload_lists_1.png

Grab a Coffee!

This upload may take some time, you may even have to split it over a number of partial uploads depending on your connection speed, time outs and upload limits.


phpList_uploaded_lists.png

Local Windows installation

If you do not own a server or you want to develop locally, you can also install phpList on your Windows machine. First, you need to download the XAMPP package and install it in your PC. After installing, copy the /lists folder as stated in the previous section and paste it in the htdocs folder of XAMPP.

xampp_file_move.png
 

Next up, you must run the XAMPP Control Panel and start the Apache and MySQL server. Now we are ready to create a database for phpList on which to save the data.

xampp_control_panel.png
 

Create a database using your control panel

Once you have uploaded the /lists directory, go to your hosting control panel or to the localhost from your browser and create a database. If you need help, your web hosting company can help you with this.

Whatever the process, you will always end up with three things:

  • A database name, for example cl52-phplist
  • A database username, for example phplist
  • A password for your database, for example T!LcDaM/4

An example of creating a database

 

These screenshots provide an example. This may or may not be similar to the way you can create a new database on your server. That depends entirely on which software your hosting company uses.

First click MySQL Databases.

database_backup_phpList_1.png
 

Then type in the new database name (we used the name phpList) and enter or generate a strong password. Make sure you keep a copy of these details!

database_1_1.png

This system creates a user automatically, where the username is the same as the database name (a common preference). In other software you may need to add a new user separately and you may also need to allocate this user to your database.

Your database is now ready. Copy down the details because you will need them in a moment. 

new_database_1.png

Edit the phpList config.php file


Next, you need to put the details of your new database into your configuration file.

Browse your temp folder on your computer and go to lists > config > config.php. Load and edit this file in a text editor, such as Notepad (windows) TextEdit (mac) or Geany/Kate/Geddit/etc (Linux).

edit_config.png

Never use a word processor program (like Microsoft Word), it will only generate formatting and disruption.

Your freshly downloaded config.php should look something like this:

config_phpList_1.png

There are four places where you need to replace the word in "quotes" at the end of a line of code with something specific to your server:

What is your Mysql database server hostname

$database_host = "localhost";

If you do not know what to enter here, you will either need to use trial and error, or ask your hosting provider what to put here. If you want to keep things simple, ask your hosting provider.

Trial and error:

You may be lucky in that your server allows "localhost" for your $database_host entry,  in which case you don't need to make a change (this was true in our example below). The second option to try is "127.0.0.1".

If these fail you will receive an error towards the end of installation. If both of these fail then this entry must be something specific to your server. GoDaddy and 1&1 servers are pretty specific, for example.

What is the name of the database we are using

 $database_name = "phplistdb";

Replace the  phplistdb with the name of your database that you set up earlier. In our example below this is cl52-phplist.

 

# what user has access to this database 
$database_user = "phplist";

Replace the phplist with the name of your databse user you set up earlier (this may be the same name as your database). In our example below this is also cl52-phplist.

# and what is the password to login to control the database 
$database_password = 'phplist';

Replace the phplist with the password you created. The password in the example below is obscured.

phpList_initial_config.png

Test mode in phpList: ("TEST",0)

One other thing you will need to do, either now or at some point in the future, is to change the value of TEST in this file. Until you do this, your install is essentially in "sandbox" mode, and will not fully function.

By default test is defined ("TEST",1). Change this to define ("TEST",0) to be able to send messages out.

This is done automatically in the auto installers.

Note that subscribers cannot confirm themselves while Test is enabled, as they will not receive confirmation emails, and therefore neither campaigns.

External SMTP servers

Often you will want or need to use an external mail server for handling phpList email, instead of your local machine (by default phpList uses PHP's built-in mail(); function).

To use an external SMTP server with standard STARTTLS settings, customise, then add these lines to your config.php file:

define('PHPMAILERHOST', 'mail.server.hostname');
$phpmailer_smtpuser = 'user@login.com';
$phpmailer_smtppassword = 'user_password';
define("PHPMAILERPORT",'587');
define("PHPMAILER_SECURE",'tls');

If the mail server is using a self-signed certificate, then you need to add the following as well:

$phpmailer_smtpoptions = array(
    'ssl' => array(
        'verify_peer' => false,
        'verify_peer_name' => false,
        'allow_self_signed' => true
    )
);

Config_extended.php

You may need to add some extra lines to your config.php. These extra lines are ready made for you in config_extended.php, which is in the same directory as config.php. Simply copy the lines you need and paste them below the others in config.php

Save and upload

Once you have edited the config.php file you need to save it and upload this new version to your server. This can be done in the same way as your initial upload: open your ftp client, find the lists/config/config.php file on your pc and then upload it to lists/config/config.php on your server.

Go to your installation

Open your web browser and go to your installation. This is located at http://mywebsite.co.uk/lists/admin.

If you get an error saying that the database has not connected, then check your config.php file again: a tiny error such as a space before/after your database name/password will stop this from working.

When you see the grey and black interface with the phpList logo at the top, you are in the right place.

go_to_install.png

Or on your right, choose Initialize database under the Config option.

IMG_20190629_221830.png

The final steps

Click Initialise Database and fill out the form.

Initialise_database_phpList.png

Click Continue

sign_up_to_list.png

  • If you would like to email phpList to let us know you are using the software, click Tell us about it.
  • We recommend that you sign up to receive email announcements about new versions of phpList. You can enter your email and click Subscribe. If you do not want to sign up, for example because you are already on the list, then click Do not subscribe.

Finally click to continue with phpList seutp.


install_complete.png

You're done!

You have now finished installation, and the next step is configuration.

configuration.png

Downloading phpList from the command line

The wget command

To download the phpList files you can use the wget from a Unix-like command line.  You can use the wget command as follows:

wget [option]... [URL]...

In order to check further how to add more options to your command, you can check the GNU Wget 1.20 Manual or type "man wget" on your command line for a description of the command.

The scp command

scp copies files between hosts on a network. It uses ssh(1) for data transfer, and uses the same authentication and provides the same security as ssh(1). scp will ask for passwords or passphrases if they are needed for authentication. You can use the scp command as follows: 

scp [OPTION] [user@]SRC_HOST:]file1 [user@]DEST_HOST:]file2

Here is a detailed guide on how to use the scp command.

Feedback

Discuss this chapter here.

Back to top