How to remove a file from a template using the installer?

Question

I am developing a template for a small group of sites. In the old J3 days, I had to make an override for some core templates to fix some minor things. With the update to J4 this was no longer necessary.

I created a new release for J4 only and dropped the overrides from that release. After updating the template, it did not work. Looking into the files showed that Joomla did update but refused to remove any preexisting files. So, the old overrides were still active. I deleted them manually in the files and it worked.

Now my question is: How can I tell the Joomla extension installer to remove a certain file during update?

I understand that it is not easy to understand for the installer which files are from the previous installed package and which ones are created by the user/admin in order to do whatever (think of a custom user.css file).

Answer 1

You have to create an installer script. The provided generic installer, Joomla\CMS\Installer\InstallerScript, has some functionality for removing files and folders so you could extend it.

Create a file with class [your_template]InstallerScript in it, e.g. ProtostarInstallerScript. Populate deleteFiles property with a list of files to be deleted. Then in update() or postflight() method call removeFiles() method:

defined('_JEXEC') || exit;

use Joomla\CMS\Installer\InstallerScript;

class ProtostarInstallerScript extends InstallerScript
{
    protected $extension = 'protostar';

    protected $deleteFiles = [
        '/templates/protostar/html/mod_foo/default.php',
    ];

    public function update($adapter): bool
    {
        $this->removeFiles();

        return true;
    }
}

When using postflight method you need to check that it's an update that's being performed:

public function postflight($type, $adapter): bool
{
    if ($type === 'update')
    {
        $this->removeFiles();
    }

    return true;
}

Finally, declare the script in your templateDetails.xml manifest:

<scriptfile>install.script.php</scriptfile>