—- plugin —-

description: This plugin adds a page that updates the phpList code.
author : Duncan Cameron
compatible : 3.x

sourcerepo : https://github.com/bramley/phplist-plugin-updater

This plugin is now included with phpList therefore you should not usually need to install it.

You can upgrade the plugin to the latest version through the Plugins page (menu Config > Manage plugins) using the package URL

https://github.com/bramley/phplist-plugin-updater/archive/master.zip

A configuration variable $updaterConfig needs to be set in the config.php file.

The plugin provides a page that updates the phplist code to the latest release. The main differences to the core phplist updater are

• it ignores unexpected files and directories in the top-level of the phplist installation directory (usually 'lists')
• it restores any additional files in the config directory
• it restores any additional plugins that have been installed
• it can restore specific phplist files that have been modified, such as a language file, or custom modifications
• it can not install specific files or directories

There are some important requirements:

• need to create a work directory that is writeable by the web server process. This should be outside the 'lists' directory and need not be within the web root at all, although it can be.
• the phplist installation directory (usually 'lists' but could have been renamed) must be writeable by the web server process
• the files in the phplist installation directory must be owned by the web server process, because they will be moved to the work directory

The plugin uses the work directory to download and expand the phplist distribution zip file, and stores a backup of the current phplist files and directories.

To enable the updater, add this to the end of config.php giving the file system path to the work directory

$updaterConfig = [
    'work' => '/path/to/work/directory',
];

The plugin replaces only the files and directories that are in the phplist distribution zip file. All other files and directories in the installed phplist top-level directory (usually lists) are left alone. For clarity, these are the files/directories that are replaced

The config directory including the config.php file will be replaced by that in the new distribution.

When config.php is in the default location, the config directory, the updater will restore it and any additional files from the backup config directory.

If you use the ConfigFile environment variable to place config.php elsewhere then the updater will not copy or overwrite that file. This assumes that the file is located outside of the phplist installation.

The admin directory, including the plugins subdirectory, will be replaced by that from the new distribution. When the plugins directory is in the default location, admin/plugins, then the updater will restore any additional files and directories from the backup admin/plugins directory.

After replacing the phplist code with the new release, the updater can then restore specific files from the backup. This can be useful if you have made changes to phplist files that you want to keep.

You should first verify that the new phplist release has not modified the files in question. If they have been modified then you will need to reapply manually the changes to the files in the new release.

To have the updater restore specific files, add a list of the files to the $updaterConfig variable. The path of each file should be relative to the lists directory.

For example to restore the English front-end translation file that is in the texts directory

$updaterConfig = [
    'work' => '/path/to/work/directory',
    'files' => [
        'texts/english.inc',
    ],
];

The updater will install all the items, files and directories, that are in the lists directory of the phplist distribution, i.e. index.php, lt.php, the admin directory, the config directory, etc.

You can give the updater a set of files and directories that should not be installed. The path of each should be relative to the lists directory. For example, to not install the phplist REST API and the index.html file

$updaterConfig = [
    'work' => '/path/to/work/directory',
    'do_not_install' => ['index.html', 'api.php', 'base'],
];

The web server php configuration might limit the elapsed time for which a php script can run, or the maximum amount of memory that can be used. You can give new values for those php configuration values

$updaterConfig = [
    'work' => '/path/to/work/directory',
    'do_not_install' => ['index.html', 'api.php', 'base'],
    'max_execution_time' => 240,
    'memory_limit' => '1024M',
];

The updater can delete old backups that were created during previous upgrades. A setting indicates the number of backups to keep. This must be an integer greater than 0. A value of 1 means that only the backup for the current upgrade will be kept. The setting is optional, you can always remove old backups manually when you are sure they are not needed. This example will keep the backup for the current upgrade and for the previous upgrade.

$updaterConfig = [
    'work' => '/path/to/work/directory',
    'do_not_install' => ['index.html', 'api.php', 'base'],
    'max_execution_time' => 240,
    'memory_limit' => '1024M',
    'keep_backups' => 2,
];

There will then be a menu entry System > Update phpList

The page will indicate whether a new release is available.

The update process has three stages

• download the phplist zip file
• expand the zip file
• install the new phplist code

Only the third step changes anything, so if either of the first two steps has a problem, such as timing out, then you can repeat the process or just stop and upgrade manually. Downloading the zip file can take a while depending on your web server, sometimes more than 20s. Expanding the zip file can also take even longer, sometimes more than 40s.

When the phplist code has been updated there is a link to upgrade the phplist database, that should be applied, then logout and login again.

At some point phplist will display a popup window regarding initialising phplist in your language, just let this complete normally.

You can install a release candidate to test the version of phplist that is being prepared for release.

The Updater page will indicate that phplist is up to date.

In the browser URL bar, manually edit the URL to add a force parameter giving the version of the release candidate

https://mysite.com/lists/admin/?page=update&pi=UpdaterPlugin&tk=282f29d25c2d319a74252e8db16327be&force=3.6.14-RC1

The plugin will display a warning about installing a release candidate. You can then continue the installation.

Please raise any questions or problems in the user forum https://discuss.phplist.org/