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.
The short rule
Section titled “The short rule”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.
Files at the top
Section titled “Files at the top”| 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 |
Folders
Section titled “Folders”| 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.
The data folder
Section titled “The data folder”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/.
Folders next to the site
Section titled “Folders next to the site”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.
Blocked from the web
Section titled “Blocked from the web”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 source repository
Section titled “The source repository”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.

