Upgrading Elgg
##############

This document will guide you through steps necessary to upgrade your Elgg installation to the latest version.

If you've written custom plugins, you should also read the developer guides for
:doc:`information on upgrading plugin code </appendix/upgrade-notes>` for the latest version of Elgg.

.. contents:: Contents
   :depth: 2
   :local:

Advice
======

* **Back up your database, data directory and code**
* Mind any version-specific comments below
* Version below 2.0 are advised to only upgrade **one minor version at a time**
* You can upgrade from any minor version to any higher minor version in the same major (2.0 -> 2.1 or 2.0 -> 2.3)
* You can only upgrade the latest minor version in the previous major version to any minor version in the next version (2.3 -> 3.0 or 2.3 -> 3.2, but not 2.2 -> 3.x).
* From Elgg 2.3.* you can upgrade to any future version of Elgg without having to go through each minor version (e.g. you can upgrade directly from 2.3.8 to 3.2.5, without having to upgrade to 3.0 and 3.1)
* Try out the new version on a test site before doing an upgrade
* Report any problems in plugins to the plugin authors
* If you are a plugin author you can `report any backwards-compatibility issues to GitHub <issues_>`_

.. _issues: https://github.com/Elgg/Elgg/issues

From 2.3 to 3.0
===============

1. Update ``composer.json``
---------------------------

If you have used Elgg's starter project to install Elgg 2.3, you may need to update your ``composer.json``:

 * change platform requirements to PHP >= 7.0
 * optionally, set autoloader optimization parameters
 * optionally, disable fxp-asset plugin in favor of asset-packagist

Your ``composer.json`` would look something like this (depending what changes you may have introduced yourself):

.. code-block:: json

	{
		"type": "project",
		"name": "elgg/starter-project",
		"require": {
			"elgg/elgg": "3.*"
		},
		"config": {
			"process-timeout": 0,
			"platform": {
				"php": "7.0"
			},
			"fxp-asset": {
				"enabled": false
			},
			"optimize-autoloader": true,
			"apcu-autoloader": true
		},
		"repositories": [
			{
				"type": "composer",
				"url": "https://asset-packagist.org"
		  }
		]
	}


2. Update ``.htaccess``
-----------------------

Find the line:

.. code-block:: apache

	RewriteRule ^(.*)$ index.php?__elgg_uri=$1 [QSA,L]

And replace it with:

.. code-block:: apache

	RewriteRule ^(.*)$ index.php [QSA,L]


3a. Composer Upgrade (recommended)
----------------------------------

If you had your Elgg 2.3 project installed using composer, you can follow this sequence:

**Back up your database, data directory, and code**


.. code-block:: sh

	composer self-update

	cd ./path/to/project/root
	composer require elgg/elgg:~3.0.0
	composer update
	vendor/bin/elgg-cli upgrade async -v


.. note::

	In some cases the command line upgrade will fail because some database schema changes need to be applied first.
	In that case you need to execute the :ref:`Phinx migrations <contribute/database#execute-migration>` manually

3b. Manual Upgrade (legacy approach)
------------------------------------

Manual upgrades are a major undertaking for site admins. We discourage you from maintaining an Elgg installation using
ZIP dist packages. Save yourself some time by learning how to use ``composer`` and version control systems, such as ``git``.
This task will also be complicated if you have third-party plugins and/or have made any modifications to core files!

#. **Back up your database, data directory, and code**
#. Log in as an admin to your site
#. Download the new version of Elgg from http://elgg.org
#. Update the files
    * If upgrading to a major version, you need to overwrite all core files and remove any files that were removed from Elgg core,
      as they may interfere with proper functioning of your site.
    * If upgrading to a minor version or patching, you need to overwrite all core files.
#. Merge any new changes to the rewrite rules
    * For Apache from ``install/config/htaccess.dist`` into ``.htaccess``
    * For Nginx from ``install/config/nginx.dist`` into your server configuration (usually inside ``/etc/nginx/sites-enabled``)
#. Visit http://your-elgg-site.com/upgrade.php
#. Execute asynchronous upgrades at http://your-elgg-site.com/admin/upgrades

.. note::

   Any modifications should have been written within plugins, so that they are not lost on overwriting.
   If this is not the case, take care to maintain your modifications.

.. note::

   If you are unable to access ``upgrade.php`` script and receive an error, add ``$CONFIG->security_protect_upgrade = false;``
   to your ``settings.php`` and remove it after you have completed all of the upgrade steps.

.. note::

   If you encounter issues with plugins during the upgrade, add an empty file called ``disabled`` in your ``/mod/`` directory.
   This will disable the plugins, so that you can finish the core upgrade. You can then deal with issues on per-plugin basis.


If you have installed Elgg using a dist package but would now like to switch to composer:

 * Upgrade your current installation using Manual Upgrade method
 * Move your codebase to a temporary location
 * Create a new composer project using Elgg's starter project following :doc:`installation instructions </intro/install>` in the root directory of your current installation
 * Copy third-party plugins from your old installation into ``/mod`` directory
 * Run Elgg's installer using your browser or ``elgg-cli`` tool
 * When you reach the database step, provide the same credentials you have used for manual installation, Elgg will understand that is's an existing installation and will not override any database values
 * Optionally commit your new project to version control

Applying a patch using Composer
===============================

The definition of a patch can be found in the :doc:`Release policy </appendix/releases>`.

Your ``composer.json`` requirement for Elgg should be ``~3.y.0`` (where ``y`` is the minor version ``0``, ``1``, etc. you wish to have 
installed). This will make sure you can easily install patches without the risk of installing the next minor release.

.. code-block:: json

	{
		"require": {
			"elgg/elgg": "~3.0.0"
		}
	}

Just to be sure you can first verify what will be installed / upgraded by executing the folowing command

.. code-block:: sh

	# to get a full list of all packages which can be upgraded
	composer update --dry-run
	
	# or if you only wish to check for Elgg
	composer update elgg/elgg --dry-run

To upgrade Elgg simply execute

.. code-block:: sh

	# to upgrade all packages
	composer update
	
	# or to only upgrade Elgg
	composer update elgg/elgg

Earlier versions
================

Check Elgg documentation that corresponds to the Elgg version you want to upgrade to, by switching the documentation
version in the lower left corner of :doc:`Upgrading docs <upgrading>`
