Skip to content

Upgrading modules that are symlinked #36

Description

@jlahijani

This is not a bug, but how ProcessWire works with symlinks, which is not ideal for my usecase.


On my dev site, I have a local repository of a bunch of modules in a directory like this:

/home/jlahijani/processwire-modules/

Then I typically have a site like this:

/var/www/example.com/

I may symlink specific modules like this:

/var/www/example.com/site/modules/TracyDebugger/ (symlink to /home/jlahijani/processwire-modules/TracyDebugger/)

Now, if I use ProcessWireUpgrade to upgrade the module, it will do the following:

  • unlink the folder (!) -- see the backupDir method in ModulesDownloader.php
  • make the old version go into .TracyDebugger
  • make the new version go into TracyDebugger

So now the module is localized / no longer symlinked, which is unfortunate.

Is it possible to just upgrade the module and maintain the symlink? I understand this is an advanced usecase, so maybe there can be a special config variable that allows advanced users to enable this?

Activity

  1. matjazpotocnik commented on Jul 5, 2026

    @matjazpotocnik

    @jlahijani can you test this version?

    https://github.com/matjazpotocnik/ProcessWireUpgrade

    Add $config->processWireUpgradePreserveSymlinks = true; in /site/config.php

  2. jlahijani commented on Jul 6, 2026

    @jlahijani
    Author

    @matjazpotocnik I gave it a thorough test multipe times, making sure to have the $config options set but it doesn't seem to be working.

    It seems ProcessWire is still interfering... "Please note that /site/modules/TemplateFieldWidths/ was a symbolic link and has been converted to a regular directory".

    Here is the output of upgrading a module.

    ProcessModuleInstall: Downloaded ZIP file: https://github.com/Toutouwai/TemplateFieldWidths/archive/master.zip (14443 bytes) +14
    ProcessModuleInstall: Extracted: TemplateFieldWidths-master/
    ProcessModuleInstall: Extracted: TemplateFieldWidths-master/.editorconfig
    ProcessModuleInstall: Extracted: TemplateFieldWidths-master/.gitattributes
    ProcessModuleInstall: Extracted: TemplateFieldWidths-master/LICENSE
    ProcessModuleInstall: Extracted: TemplateFieldWidths-master/README.md
    ProcessModuleInstall: Extracted: TemplateFieldWidths-master/TemplateFieldWidths.css
    ProcessModuleInstall: Extracted: TemplateFieldWidths-master/TemplateFieldWidths.js
    ProcessModuleInstall: Extracted: TemplateFieldWidths-master/TemplateFieldWidths.module
    ProcessModuleInstall: Extracted: TemplateFieldWidths-master/TemplateFieldWidths.scss
    ProcessModuleInstall: Destination directory: /var/www/jonathanlahijani.com/site/modules/TemplateFieldWidths/
    ProcessModuleInstall: Please note that /site/modules/TemplateFieldWidths/ was a symbolic link and has been converted to a regular directory
    ProcessModuleInstall: Backed up existing TemplateFieldWidths => /site/modules/.TemplateFieldWidths/
    ProcessModuleInstall: Successfully copied files to new directory: /site/modules/TemplateFieldWidths/
    WireHttp: Downloaded https://github.com/Toutouwai/TemplateFieldWidths/archive/master.zip => /var/www/jonathanlahijani.com/site/assets/cache/WireTempDir/.ModulesDownloader/0/master.zip (using: curl) [14443 bytes]
    
  3. matjazpotocnik commented on Jul 6, 2026

    @matjazpotocnik
  4. matjazpotocnik commented on Jul 6, 2026

    @matjazpotocnik

    @jlahijani please test the new version (just replace ProcessWireUpgrade.module).

  5. jlahijani commented on Jul 6, 2026

    @jlahijani
    Author

    @matjazpotocnik Unfortunately that update didn't work either.

  6. matjazpotocnik commented on Jul 6, 2026

    @matjazpotocnik

    The upgrade link is called "Upgrade", not "Sync", right? And the url for the upgrade is /processwire/module/?update=moduleclassname?

  7. jlahijani commented on Jul 6, 2026

    @jlahijani
    Author

    The upgrade link is called "Upgrade", not "Sync", right? And the url for the upgrade is /processwire/module/?update=moduleclassname?

    Correct.

  8. matjazpotocnik commented on Jul 6, 2026

    @matjazpotocnik

    Please try again. Also check the logs process-wire-upgrade

  9. jlahijani commented on Jul 6, 2026

    @jlahijani
    Author

    It worked! Here's what I did.

    With the latest update, when I clicked Upgrade on a module, it said this (it didn't say this previously and I've never needed to add this to successfully install modules):

    ProcessModuleInstall: Module install option “download” - This install option is currently disabled. To enable, edit file /site/config.php and specify:
    `$config->moduleInstall('download', true);` to enable always …or…
    `$config->moduleInstall('download', 'debug');` to enable in debug mode only
    

    Therefore I set $config->moduleInstall('download', true); in my config.php.

    Then I clicked upgrade on a module that needed to be upgraded. The output was this:

    ProcessModuleInstall: Downloaded ZIP file: https://github.com/Toutouwai/TemplateFieldWidths/archive/HEAD.zip (15055 bytes) [+16](https://jonathanlahijani.test/admin/setup/upgrades/#)
    ProcessModuleInstall: Extracted: TemplateFieldWidths-2462310f48f931d4674ae57cfbaab6cba8c098df/
    ProcessModuleInstall: Extracted: TemplateFieldWidths-2462310f48f931d4674ae57cfbaab6cba8c098df/.editorconfig
    ProcessModuleInstall: Extracted: TemplateFieldWidths-2462310f48f931d4674ae57cfbaab6cba8c098df/.gitattributes
    ProcessModuleInstall: Extracted: TemplateFieldWidths-2462310f48f931d4674ae57cfbaab6cba8c098df/LICENSE
    ProcessModuleInstall: Extracted: TemplateFieldWidths-2462310f48f931d4674ae57cfbaab6cba8c098df/README.md
    ProcessModuleInstall: Extracted: TemplateFieldWidths-2462310f48f931d4674ae57cfbaab6cba8c098df/TemplateFieldWidths.css
    ProcessModuleInstall: Extracted: TemplateFieldWidths-2462310f48f931d4674ae57cfbaab6cba8c098df/TemplateFieldWidths.js
    ProcessModuleInstall: Extracted: TemplateFieldWidths-2462310f48f931d4674ae57cfbaab6cba8c098df/TemplateFieldWidths.module
    ProcessModuleInstall: Extracted: TemplateFieldWidths-2462310f48f931d4674ae57cfbaab6cba8c098df/TemplateFieldWidths.scss
    ProcessModuleInstall: Destination directory: /home/jlahijani/Code/processwire-modules/TemplateFieldWidths
    ProcessModuleInstall: Backed up existing TemplateFieldWidths => /home/jlahijani/Code/processwire-modules/.TemplateFieldWidths/
    ProcessModuleInstall: Successfully copied files to new directory: /home/jlahijani/Code/processwire-modules/TemplateFieldWidths
    ProcessWireUpgrade: Module TemplateFieldWidths updated from GitHub (symlink preserved).
    ModulesInfo: Upgrading module (TemplateFieldWidths: 0.2.2 => 0.3.2)
    Cleared the admin theme navigation cache (primary nav)
    WireHttp: Downloaded https://github.com/Toutouwai/TemplateFieldWidths/archive/HEAD.zip => /var/www/jonathanlahijani.com/site/assets/cache/WireTempDir/.ModulesDownloader/0/HEAD.zip (using: curl) [15055 bytes]
    
  10. matjazpotocnik commented on Jul 6, 2026

    @matjazpotocnik

    You didn't have to set $config->moduleInstall('download', true); as upgrades were handled natively via $modules->get('ProcessModule')->installer()->downloadModule() method. Unfortunately, this core method uses backupDir(), which intentionally does what you described. None of the methods is hookable, so I had to route it via the "Add module From URL" option, which requires these settings.

    I made a feature request; I will see if Ryan accepts it.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions