00002 Renaming an existing HumHub Module with a script

Below is a concise “recipe” for safely renaming any HumHub module (or similarly structured PHP/JS project), followed by the typical order of operations and the corresponding shell commands you’d run at each step.

In our example we are using the Classified Spaces Module that resides in the classified-space folder and like to rename it to Abcdirectory and it will reside in the folder abcdirectory

We have chosen to write our new name as one word with only one capital letter at its beginning. The foldername will be written in only small letters and as one word too. This makes future development much easier in Yii2 and HumHub.

New Module name: Abcdirectory (seen as one word) - before Classified Spaces Foldername: abcdirectory - before classified-space Module ID: abcdirectory - before classified-space Class name: Abcdirectory - before ClassifiedSpace Method name (function): abcdirectory - before classifiedSpace

NOTE: Try to avoid Hypens or Underscores in your module names - keep it simple ro stay PSR12 conform

✏️ Essential Rules When Renaming a Module

  1. Always work on a backup or feature branch Never rename in-place on your production code—make a copy or branch first so you can roll back if anything breaks.

  2. Map out every identifier style Identify the various naming conventions you’ll need to change:

    • Kebab-case: classified-space → abcdirectory
    • lowercase: classifiedspace → abcdirectory
    • PascalCase: ClassifiedSpace → Abcdirectory
    • camelCase: classifiedSpace → abcdirectory
    • Mixed/typos: Classified-space, Classifiedspace, etc.

  3. Directory → Filename → In-file content Always rename the module folder first, then individual files, then bulk-replace inside files.

  4. Avoid accidental matches Restrict your sed or grep to relevant file types (.php, .js, .css, .less, etc.) so you don’t mangle documentation or unrelated assets.

  5. Clear caches & rebuild autoload After renaming, flush Yii’s runtime and assets caches, and (if using Composer) regenerate the autoloader.

🛠 Basic Order of Operations & Shell Commands

Assume your modules live in /path/to/humhub/modules and the old module is named classified-space.

1) Backup / Branch

cd /path/to/humhub/modules

# make a filesystem backup
cp -a classified-space classified-space.bak

# —or— create a Git branch
git checkout -b rename-classified-space

2) Rename the Module Directory

cd /path/to/humhub/modules
mv classified-space abcdirectory

3) Rename Files and Subdirectories

Note: adjust mv lines to match your actual file tree.

cd abcdirectory

# PHP model files
mv models/ClassifiedSpace.php            models/Abcdirectory.php
mv models/ClassifiedSpaceCategory.php    models/AbcdirectoryCategory.php
mv models/searches/UnClassifiedSpaceSearch.php \
   models/searches/UnAbcdirectorySearch.php

# JS assets
mv resources/js/humhub.classified-space.space-browser.js \
   resources/js/humhub.abcdirectory.space-browser.js

# CSS assets (+ sourcemaps)
for f in admin space-browser space-header; do
  mv resources/css/humhub.classified-space.$f.css         \
     resources/css/humhub.abcdirectory.$f.css

  mv resources/css/humhub.classified-space.$f.css.map     \
     resources/css/humhub.abcdirectory.$f.css.map
done

# LESS assets
for f in admin space-browser space-header; do
  mv resources/less/humhub.classified-space.$f.less       \
     resources/less/humhub.abcdirectory.$f.less
done

4) Bulk-Replace In-File References

# from inside /path/to/humhub/modules/abcdirectory
find . -type f \( -name "*.php" -o -name "*.js" -o -name "*.css" -o -name "*.less" \) -print0 \
  | xargs -0 sed -i \
    -e 's/Classified-Space/Abcdirectory/g' \
    -e 's/Classified-space/Abcdirectory/g' \
    -e 's/classified-space/abcdirectory/g' \
    -e 's/ClassifiedSpace/Abcdirectory/g' \
    -e 's/classifiedSpace/abcdirectory/g' \
    -e 's/Classifiedspace/Abcdirectory/g' \
    -e 's/classifiedspace/abcdirectory/g'

5) Update Composer Autoload & Clear Caches

# If module uses composer.json
composer dump-autoload

# Clear Yii cache & assets (adjust path if needed)
rm -rf /path/to/humhub/protected/runtime/cache/*
rm -rf /path/to/humhub/protected/runtime/assets/*

Once you’ve completed these steps, you can restart your HumHub instance and verify the renamed module loads correctly. If everything’s green, commit or merge your branch and you’re done!

Below is a general Note of Caution you can use any time you need to rename a HumHub (or similar) module. It covers the full spectrum of naming patterns, special‐character pitfalls, recommended order of operations, and regex tips to make sure nothing slips through the cracks.

🚨 Note of Caution: Renaming a HumHub Module

1. Always Start from a Safe Copy

  • Backup the folder or work on a Git branch.
  • Never rename in place on your production instance.

2. Identify Every Naming Pattern

Before you run any search-and-replace, list out all ways the module ID or class appears:

Style Example Old Name Example New Name
Kebab-case classified-space abcdirectory
Snake_case classified_space abcdirectory
Dot.case classified.space abcdirectory
lowercase classifiedspace abcdirectory
PascalCase ClassifiedSpace Abcdirectory
camelCase classifiedSpace abcdirectory
Mixed/typos Classified-space Abcdirectory
Upper_SNAKE CLASSIFIED_SPACE ABCDIRECTORY
Quotes 'classified-space' 'abcdirectory'
Double-quotes "ClassifiedSpace" "Abcdirectory"

And don’t forget to scan for module-specific identifiers in:

  • module.json → "id": "classified-space"
  • PHP namespaces → namespace humhub\modules\classifiedspace;
  • Module class → class Module extends …
  • AssetBundle classes → ClassifiedSpaceAsset
  • Migration filenames & classes → m210101_000001_create_classified_space
  • DB table names (if prefixed) → tbl_classified_space
  • JS module definitions → humhub.mod.classified-space
  • CSS selectors & icon classes → .classified-space-widget
  • Translation categories → Yii::t('ClassifiedSpaceModule.base', …)
  • URL routes & permissions → /classified-space/... & ['classified-space.*']

3. Watch Your Word-Boundaries & Special Characters

You don’t want to accidentally rename parts of longer words or JSON keys. Common pitfalls:

  • Hyphens (-) vs underscores (_)
  • Dots (.) in filenames or CSS
  • Parentheses (), brackets [], braces {} in config arrays
  • Quotes (' vs "), backticks ` in JS
  • Word boundaries: use regex \b so you don’t turn my-classified-space-id into my-abcdirectory-id unless that’s intended

4. Proper Order of Operations

  1. Branch or Backup

  2. Directory Rename

    mv classified-space abcdirectory

  3. Individual File Renames

    • module.json
    • PHP classes, controllers, models, migrations
    • JS/CSS/LESS/asset filenames

  4. Update Namespaces & Class Names

    • namespace humhub\modules\classifiedspace; → …\abcdirectory;
    • class ClassifiedSpaceAsset → class AbcdirectoryAsset

  5. Composer Autoload (if applicable)

    composer dump-autoload

  6. Bulk In-File Replacements Restrict to relevant extensions and use case-sensitive patterns:

    find . -type f \( -name "*.php" -o -name "*.js" -o -name "*.css" -o -name "*.less" \) -print0 \
 | xargs -0 sed -i \
   -e 's/\bclassified-space\b/abcdirectory/g' \
   -e 's/\bclassified_space\b/abcdirectory/g' \
   -e 's/\bClassifiedSpace\b/Abcdirectory/g' \
   -e 's/\bclassifiedSpace\b/abcdirectory/g' \
   -e 's/\bClassified-space\b/Abcdirectory/g' \
   -e 's/\bClassifiedspace\b/Abcdirectory/g' \
   -e 's/\bclassifiedspace\b/abcdirectory/g'
  7. Database Table Rename / Migration Adjust If your module created its own tables, update their names in migrations or run SQL ALTER TABLE.

  8. Clear Caches & Rebuild Assets

    rm -rf protected/runtime/cache/* protected/runtime/assets/*

  9. Final Grep & Sanity Check

    grep -R "classified" .
git diff

  10. Test

    • Hit every controller/action
    • Verify assets load
    • Check translations
    • Run Yii’s debug toolbar and your unit/integration tests (if any)

5. Regex & Sed Tips

  • Case-sensitive by default: good for catching ClassifiedSpace vs classifiedspace.
  • Use \b for word boundaries.
  • Test with grep -R first to see what matches.
  • Avoid global text editors that don’t respect file-type filters—stick to find | xargs sed.

By carefully cataloging every identifier style, restricting replacements to the correct file types, and following a strict rename order, you’ll eliminate nearly all surprises and keep your renamed module fully functional.

A Script to do all in one step in seconds

Below is a ready-to-run bash script that will, in order:

  1. Rename the module directory
  2. Rename every file whose name contains the old module ID
  3. Mass-replace only the various “classified-space” identifiers in your PHP/JS/CSS/LESS/build.sh

You’ll just need to set MODULE_BASE to the parent folder of your HumHub modules (where classified-space/ lives), then run it once.

#!/usr/bin/env bash
set -euo pipefail

# ─── CONFIG ────────────────────────────────────────────────────
# adjust this to point at your HumHub/modules folder:
MODULE_BASE="/path/to/humhub/modules"
# ────────────────────────────────────────────────────────────────

cd "$MODULE_BASE"

# 1) rename the module directory
mv classified-space abcdirectory
cd abcdirectory

# 2) rename files whose names contain the old ID
mv models/ClassifiedSpace.php                         models/Abcdirectory.php
mv models/ClassifiedSpaceCategory.php                 models/AbcdirectoryCategory.php
mv models/searches/UnClassifiedSpaceSearch.php        models/searches/UnAbcdirectorySearch.php

mv resources/js/humhub.classified-space.space-browser.js \
   resources/js/humhub.abcdirectory.space-browser.js

mv resources/css/humhub.classified-space.admin.css         resources/css/humhub.abcdirectory.admin.css
mv resources/css/humhub.classified-space.space-browser.css resources/css/humhub.abcdirectory.space-browser.css
mv resources/css/humhub.classified-space.space-header.css  resources/css/humhub.abcdirectory.space-header.css

mv resources/css/humhub.classified-space.admin.css.map         resources/css/humhub.abcdirectory.admin.css.map
mv resources/css/humhub.classified-space.space-browser.css.map resources/css/humhub.abcdirectory.space-browser.css.map
mv resources/css/humhub.classified-space.space-header.css.map  resources/css/humhub.abcdirectory.space-header.css.map

mv resources/less/humhub.classified-space.admin.less         resources/less/humhub.abcdirectory.admin.less
mv resources/less/humhub.classified-space.space-browser.less resources/less/humhub.abcdirectory.space-browser.less
mv resources/less/humhub.classified-space.space-header.less  resources/less/humhub.abcdirectory.space-header.less

# 3) replace all in‐file occurrences (case-sensitive!)
find . -type f \( -name "*.php" -o -name "*.js" -o -name "*.css" -o -name "*.less" -o -name "build.sh" \) -print0 |
  xargs -0 sed -i \
    -e 's/Classified-Space/Abcdirectory/g' \
    -e 's/Classified-space/Abcdirectory/g' \
    -e 's/classified-space/abcdirectory/g' \
    -e 's/ClassifiedSpace/Abcdirectory/g' \
    -e 's/classifiedSpace/abcdirectory/g' \
    -e 's/Classifiedspace/Abcdirectory/g' \
    -e 's/classifiedspace/abcdirectory/g'

echo "✅ Renaming complete."

Files and directories this touches

classified-space/ → 
abcdirectory/

models/ClassifiedSpace.php → 
Abcdirectory.php

ClassifiedSpaceCategory.php → 
AbcdirectoryCategory.php

models/searches/UnClassifiedSpaceSearch.php → 
UnAbcdirectorySearch.php

resources/js/humhub.classified-space.space-browser.js →
humhub.abcdirectory.space-browser.js

resources/css/humhub.classified-space.admin.css → 
humhub.abcdirectory.admin.css

humhub.classified-space.space-browser.css →
humhub.abcdirectory.space-browser.css

humhub.classified-space.space-header.css  →
humhub.abcdirectory.space-header.css

resources/css/*.map                      (same three files with .map suffix)

resources/less/humhub.classified-space.admin.less →
humhub.abcdirectory.admin.less

humhub.classified-space.space-browser.less →
humhub.abcdirectory.space-browser.less

humhub.classified-space.space-header.less  →
humhub.abcdirectory.space-header.less

resources/less/build.sh     (content updated via sed)

config.php, Module.php, Events.php, controllers/, views/, etc.
    (all occurrences of “classified-space”, “ClassifiedSpace”,
     “classifiedSpace”, etc. are replaced in-place)]()

Run this once on your clean copy, and you’ll have an exact rename from Classified-Space → Abcdirectory everywhere.

To make your shell script executable, just give it execute permission. From the directory where your script lives, run:

chmod +x rename_module.sh

(Replace rename_module.sh with whatever you named it.)

After that you can invoke it directly:

./rename_module.sh

If you ever need more permissive rights (e.g. for group or world execution), you can also do:

chmod 755 rename_module.sh

– which gives owner read/write/execute and everyone else read/execute.