Skip to content

ClientFence file structure

This page maps the ClientFence directory: what the release archive contains, what appears when you install and run it, and which files are yours to change. Use it before you edit a file, move a folder or plan backups.

An update unpacks the new release over the old one and writes every shipped file that changed. Anything the release does not contain stays as it is. So:

  • Never edit a shipped file. Your change is lost at the next update. Before it updates, System → Update ClientFence lists the shipped files that differ from the release and lets you download them.
  • Put your own work in places the release does not ship: your own modules, adapters, themes/palisade/html_custom/ or a theme of your own.
  • An update does not delete files a newer release no longer ships, except a few old files it removes on purpose.
File What it is for Change it? Update
index.php Handles every page and API request. No Replaces
ipn.php Receives payment gateway notifications. No Replaces
cron.php Runs the scheduled tasks. Command line only. See Cron. No Replaces
console.php The command line tool. Command line only. No Replaces
load.php, di.php Start-up code and the list of services the code uses. No Replaces
clientfence-security-headers.php Sends the security headers of every page. No Replaces
config-sample.php The defaults the installer starts config.php from. No Replaces
config.php Your settings: database, URL, security. Made by the installer. See The config.php file. Yes, with care Keeps; may add new settings
config.old.php A copy of the previous config.php, saved each time ClientFence rewrites it. Delete if not needed Keeps
.htaccess Web server rules: clean URLs and blocked paths. No Replaces
robots.txt Tells search engines to skip the private folders. No Replaces
rewrite-missing.html Shown when the web server has no URL rewriting. No Replaces
README.md, LICENSE, NOTICE Project and licence files. No Replaces
Folder What it holds Change it? Update
modules/ One folder per module: the built-in ones and yours. Add your own folders only Replaces built-in modules, keeps yours
library/ Core PHP classes. Gateways in library/Payment/Adapter/, registrars in library/Registrar/Adapter/, control panels in library/Server/Manager/. Add your own adapter files only Replaces shipped files, keeps yours
vendor/ Third-party PHP libraries. No Replaces
themes/admin_default/ The admin area theme, including its own html_custom/. No Replaces
themes/palisade/ The client area theme. Only html_custom/ Replaces html/ and assets/
themes/palisade/html_custom/ Your copies of client area templates. Not shipped. See Change the client area templates. Yes Keeps
themes/<theme>/config/settings_data.json The theme’s saved settings, written when you save its Settings page. Through the admin area Keeps
locale/ Compiled translations, one folder per language. No Replaces
public/assets/, public/branding/, public/gateways/ Built scripts and styles, default logos, gateway icons. No Replaces
public/uploads/brand/ Logos, icon and brand colour stylesheet you upload in the branding settings. Through the admin area Keeps
install/ The installer. No Brought back by the release, then removed
data/ Cache, logs, uploads and update state. See below. No Keeps (cache emptied)

library/ClientFence/release-files.json lists every shipped file with its checksum, and modules/Clientfence/pack-manifest.json is what System Health compares the install with. Both come with the release.

The installer removes install/install.php when it finishes. On a production site, ClientFence removes the whole install/ folder on the first request once config.php exists, and an update removes it again after unpacking.

data/ holds what ClientFence writes while it runs. Its .htaccess blocks web access, apart from gateway images in data/assets/gateways/.

Path What it is
data/cache/ Compiled templates, cached data and the downloaded update archive. Safe to empty: ClientFence builds it again.
data/log/ Log files, one folder per channel, plus php_error.log and exception_handler.log. See Logs and debugging.
data/uploads/ Files of downloadable products. Back it up.
data/update-finalization.json The state of the last update.
data/csp-reports.json Blocked scripts, counted by System Health.
data/patcher.lock, data/update.flock Locks that stop two updates or database updates running at once.

While an update unpacks files, a .update-lock file sits in the ClientFence directory and visitors see the maintenance page.

The path_data setting in config.php can move the cache, logs and update state elsewhere. Uploads always stay in data/uploads/.

Private files live outside the web root, in folders next to the ClientFence directory, so a web request can never reach them. Include them in your server backups.

Folder What it holds Move it with
.clientfence-backups/<site folder name>/ Daily database backups and the backup made before each update CLIENTFENCE_BACKUP_DIR
.clientfence-ticket-files/ Ticket attachments CLIENTFENCE_TICKET_FILES_DIR
.clientfence-receipts/ Payment receipts clients upload CLIENTFENCE_RECEIPT_DIR
.clientfence-id-documents/ Client ID documents, encrypted CLIENTFENCE_ID_DOCUMENT_DIR
.clientfence-client-files/ Files staff attach to a client

The variables are environment variables of the PHP process. The backups folder must stay outside the website: ClientFence refuses one inside it.

The update backup is a folder named update-<old>-to-<new>-<date>-<time>. It holds database.sql.gz, files.zip with every file the update replaced and added.json with the files it added. Each update keeps only its own backup and removes the older update backups. See Restore a backup.

The shipped .htaccess answers only index.php, ipn.php and the installer’s two PHP files. Every other .php file, and .twig, .sql, .log, .ini, .yaml, .lock and similar files, get a not-found page. library/, vendor/ and locale/ are refused, and so is each module’s and theme’s manifest.json and each theme’s config/ folder. On Nginx, add the same rules yourself: see Run ClientFence on Nginx.

The release is built from the ClientFence repository. Its layout differs from an install:

Path What it is
src/ The application. It becomes the release, without the module tests/ folders.
tests/ The Pest test suite.
frontend/ Shared browser code and the asset build. npm run build writes to src/public/assets/ and src/themes/*/assets/build/.
src/themes/palisade/assets/src/ The client theme’s sources. It builds on its own with its own package.json.
translations/, src/themes/palisade/locale/ Translation sources, compiled into src/locale/.
tools/ Release build, translation and test scripts. Not in the release.
Dockerfile Builds the release tree and the test image.

vendor/ is not in the repository: Composer installs it during the build. CONTRIBUTING.md explains how to run the checks.