Automatic Updater for phpList
Clone or download
Latest commit 557c094 Jan 12, 2019
Type Name Latest commit message Commit time
Failed to load latest commit information. Update Jan 11, 2019
index.php Link back dashboard and hover effect to logo Jan 3, 2019

Automatic updater for phpList

Provides an easy, automated, web-based update mechanism for phpList installations.


The new phpList updater gives you an easy way to upgrade your installation via web. In just four steps you can update your installation to the latest release.

The updater will be available in all releases starting with phpList 3.3.7-RC1


The automatic updater requires the following PHP extensions: curl, zip and pdo.

Technical details

The updater is currently performing the following steps. If one of those steps fail, you will have the possibility to correct the error and retry from the current step.

  1. Check if the user is authenticated (Only superadmins can update phpList)
  2. Check if there is an update available
  3. Check for write permissions
  4. Check whether all required phpList files are in place
  5. Ask the user if they want a backup of the software:
  • Yes: ask the user for the location
  • If no: continue to the next step.
  1. Download new version to a temporary folder
  2. Add maintenance mode
  3. Replace PHP entry points with "Update in progress" message
  4. Delete old files except config, updater and temporary directory
  5. Move new files in place
  6. Move new PHP entry points in place
  7. Move updater to a temporary directory
  8. Delete temporary files
  9. Remove maintenance mode
  10. Move new updater in place
  11. Deauthenticate updater session
  12. Redirect to the phpList dashboard


The whole phpList directory and the files within it must be writable by the HTTP user under which your web server is running as. If there is no match between the owner of your phpList files and the user under which your web server is running, you won’t be able to update. The ownership can be changed in a Linux terminal using this command:

 chown -R user:group /path/to/phpList-directory 

For instance:

 chown -R www-data:www-data /var/www/lists 

Change directory and file permissions:

 find . -type d -exec chmod 755 {} \; 
 find . -type f -exec chmod 644 {} \; 

Permissions vary from host to host. To find the HTTP user check the Apache Server configuration files. You can view a file's ownership, permissions, and other important information with the ls command, using the -la option:

 ls -la file.php 

The default Apache user and group for some Linux distributions are:

  • Debian/Ubuntu: www-data
  • Arch Linux: http
  • Fedora/CentOS: apache
  • openSUSE: user is wwwrun and the group is www

After you change the permissions, you can try again the update. After a successful update, please consider to re-apply any hardened directory permissions.

What the updater doesn't do (yet):

The updater is at the moment solely focused on replacing the files of the core installation. It does neither:

  • Upgrade the database (this uses the existing database migration code)
  • Upgrade the plugins (this uses the existing plugin updater)


  • The updater stops when it finds unexpected files (not from phpList default installation) and lists them. To continue, you should delete these files or move them outside lists directory.
  • Any plugins that are not included in releases are removed and need to reinstalled following update (settings for those plugins in the database are not affected; reinstalling the plugins should make them work as before).
  • It is possible to override the backup checks by reloading the page when the backup check fails. Do not reload the page unless you wish to proceed without a backup in this case.
  • When the update process fails you should manually remove actions.txt file inside the config folder in order to reset the process and be able to try again.
  • The config directory is required to be writable because the "current step" of the automatic updater is saved inside it.

Future development plans

At the moment only our current stable release, phpList 3, is supported by the updater. We’ll work on adding support to our upcoming phpList 4 release.

Report bugs and improvements:;185