Skip to content

File Stores Developer Guide

Ed Mozley edited this page Nov 21, 2026 · 1 revision

🗂️ File stores - Developer Guide

Where FreeITSM keeps uploaded files, and the one helper every piece of code asks. Step 1 of Choosing where FreeITSM keeps its files - design.

The rule

Never build a store's path yourself. Ask fileStoreDir() or fileStorePath():

require_once __DIR__ . '/../../includes/file_stores.php';   // already loaded by includes/uploads.php

$dir  = fileStoreDir('label-fonts');                         // the folder, no trailing slash
$path = fileStorePath('form-images', $row['image_path']);    // the folder + the path the database holds

Not this - the way every store used to do it, repeated in up to 21 files per store:

$path = dirname(dirname(__DIR__)) . '/forms/images/' . $rel;   // ❌ tests/file-stores.php fails

Why: in step 2 an administrator will be able to choose each store's folder. fileStoreDir() will read that choice. If one file still built the path by hand, FreeITSM would save a file in one folder and look for it in the other.

Files

File What
includes/file_stores.php FILE_STORES (every store: id → today's folder), fileStoreDir(), fileStorePath(), fileStoreAppRoot()
includes/uploads.php loads file_stores.php, so anything that saves an upload has the helper
tests/file-stores.php the guard (runs in CI, Web exposure workflow)

FILE_STORES

const FILE_STORES = [
    'ticket-attachments' => ['folder' => 'tickets/attachments'],
    ...
    'form-images'        => ['folder' => 'forms/images'],
    'label-fonts'        => ['folder' => 'system/uploads/label-fonts'],
    'branding'           => ['folder' => 'system/uploads/branding', 'fixed' => true],
    'lms-content'        => ['folder' => 'lms/content',             'fixed' => true],
];
  • The key is a stable id. Step 2 names a setting after it, so never rename one.
  • folder is today's folder, relative to the application root.
  • fixed marks a store that stays inside the application: the browser fetches its files straight from the folder (<img src>, the SCORM iframe), so it cannot leave the web root until it is served through PHP. Ed, 21 Nov 2026: revisit in a later release.
  • Files is not in the list. It already has its own location setting (files_storage_root) and safe move - see Files storage.

The helpers

  • fileStoreDir($store) - the store's folder: absolute, no trailing slash. In step 1 it is always today's folder, fileStoreAppRoot() . '/' . folder; nothing is read from the database. An unknown id throws InvalidArgumentException rather than guessing.
  • fileStorePath($store, $relative) - the folder, then $relative as the database holds it (25/<hex>.png), with any leading slash dropped. It only joins. Each caller keeps its own checks that the result is really inside the folder (the realpath containment checks, the strict preg_match on the stored value) - exactly as before.

The guard - tests/file-stores.php

  1. fileStoreDir() is today's folder for every store.
  2. Every store is a folder storagePersistenceDirectories() persists on Docker.
  3. For each store in CONVERTED, no PHP file names its folder in a string. It reads PHP's own tokens (token_get_all, string tokens only), so a folder named in a comment is fine and one in code is caught however the line is written. Files allowed to name the folders are in ALLOWED, each with a reason - today the four hand-kept folder lists and D009's web probes, which step 1 replaces in turn.
  4. Positive controls: a hand-built path is caught (single and double quotes), and a comment is not.

No database and no web server, so it runs in CI.

Converting a store - the recipe

  1. Grep the folder (tickets/attachments) across the PHP outside tests/.
  2. Replace each hand-built path with fileStoreDir() / fileStorePath(). Keep every check around it unchanged.
  3. Make sure each converted file loads the helper (includes/uploads.php does it; a file that does not load that requires includes/file_stores.php).
  4. Add the store to CONVERTED in tests/file-stores.php and run it.
  5. On the test install, save and read a real file through the real endpoint and compare the bytes - the folder must be exactly the one it was.

Progress

Store Converted Notes
Form pictures (form-images) ✅ 21 Nov 2026 api/forms/upload_image.php, image.php, card_image.php
Label fonts (label-fonts) ✅ 21 Nov 2026 api/assets/label_designs.php, label_font.php
War room (war-room) ✅ 21 Nov 2026 WARROOM_ATTACH_DIR in includes/warroom.php now comes from the helper
Change attachments, documents, knowledge pictures, emailed reports, API log archive, asset imports - next
Screen recordings - stores recordings/... with the folder name - fix first
Ticket attachments - 21 files
RFP uploads - stores a full path - make it relative first
Branding, LMS content stays fixed - later release

FreeITSM

Getting Started

Modules

Multi-tenancy (planned)

Responses to feedback

Blue sky thinking

Bugs resolved

Pull requests

Links

Clone this wiki locally