The schema, the endpoints, and how to give a module documents.

Permissions and search get their own page: Attached documents — permissions and search. The user-facing guide is Attached documents.

Built for discussion #76.

documents                     document_links
  id                            id
  kind  ('file' | 'link')       document_id  ──→ documents.id  (FK, cascade)
  title, description            parent_type  ('contract', 'asset', …)
  storage_key                   parent_id     ⚠️ NO FK POSSIBLE
  original_name, mime_type      linked_by_id
  size_bytes, content_hash      created_datetime
  external_url                UNIQUE (document_id, parent_type, parent_id)
  tenant_id, uploaded_by_id
  created/updated/deleted     document_text            document_access_log
                                document_id (PK)         document_id
                                status, extractor        analyst_id, action, ip
                                extracted_text, chars    created_datetime

The parent is a ROW, not a column on documents. That single choice is what lets one document belong to several records without a migration, and it is why deleting a record removes the link rather than a file somebody else is still using. It costs one table and one JOIN.

Five decisions came with it, all cheap at the time and expensive to retrofit:

1. A storage key, not a path. documents.storage_key is opaque; documentStoragePath() resolves it. Moving to another disk or to object storage is a change to that one function, not a data migration.
2. One table for files and links, separated by kind. Splitting later is mechanical; merging later means reconciling two sets of habits.
3. No permission columns. Ever. See the permissions page for why storing them is a bug and not merely duplication.
4. Delete the link, not the document. Garbage-collect what that orphans.
5. content_hash so the same file attached eleven times can be recognised as one.

One entry in documentEntityRegistry():

'contract' => [
    'module' => 'contracts',              // key in allowed_modules — the read gate
    'table'  => 'contracts',
    'label'  => 'Contract',               // shown in the UI
    'url'    => 'contracts/view.php?id=%d',
    'title'  => 'title',                  // column to display as the record's name
    'alive'  => null,                     // extra SQL keeping deleted parents out
    'can'    => null,                     // fn(PDO,$analystId,$id):bool — exact check
    'filter' => null,                     // fn(PDO,$analystId,$alias):[sql,params]
],

can and filter are the same question in two shapes — one row and a set. Pass null when module membership is the whole rule (contracts and tasks have no tenant_id).

⚠️ Do not invent a filter for a column that does not exist. The clause builder DROPS an entity type whose filter throws, so a filter on a missing tenant_id does not fail loudly — it silently hides every document on that entity.

Then mount the panel. Which of the two ways depends on how the page renders, and this is the thing that caught us out:

Server-rendered record — one line:

require_once __DIR__ . '/../includes/documents_panel.php';
renderDocumentsPanel('contract', (int) $contractId, '../');

JS-rendered detail view — the page mounts it itself, because the container is rebuilt every time the user picks a different record:

documentsPanelAssets('../');            // once, in <head>

FreeITSMDocuments.mount(document.getElementById('chgDocuments'), {
    parentType: 'change',
    parentId:   c.id,
    apiBase:    '../api/documents/'
});

Assets, Knowledge, Problems and Changes all take the second form. Mount, do not re-point — setParent() exists for a container that persists while the record changes, which none of them are.

document_text is its own table rather than a source_type column on attachment_text, for two reasons:

• attachment_text's primary key is the attachment id alone, and a document id is a different small integer from a different table. They would collide.
• The pipelines genuinely differ. An email attachment's text belongs to its ticket, so extraction ends by reindexing the ticket. A document has no ticket; it is its own corpus row.

What they share is attTextExtractFile(), which takes a path and returns text. That is the part worth sharing.

Two tiers, and mixing them up is a real bug we shipped and fixed:

⚠️ attTextSupports() is tier 1 only. Using it as the whole test marks every PDF unsupported at upload — "we looked and there is nothing to read", permanently — when the truth is "we never asked the thing that could". Use documentTextReadable().

Writing failed when the extractor is merely down would blacklist every PDF that arrived during a five-minute outage, permanently and silently. This is why Ed's three PDFs sat on pending while Tika was stopped and extracted themselves the moment it started.

document_links.parent_id is polymorphic, so no foreign key can protect it. Delete a contract and its links survive; nothing in the database objects.

The document is invisible from that instant — every permission check verifies the parent still exists — so nothing leaks. But without a sweep it is never collected: the row stays and the file sits on disk for ever.

documentsDetachParent($conn, 'contract', $id);   // tidy, at the moment of deletion
documentsCollectOrphans($conn, $limit);          // the net — correct on its own

The sweep is the primary mechanism, not the hook. Twelve delete paths, plus bulk deletes, plus anything that ever removes a row in SQL, is twelve chances to forget — and forgetting is silent. It runs bounded from list.php and from the maintenance script.

⚠️ A gotcha worth keeping. The first version used DELETE dl FROM document_links dl … LIMIT n. MySQL does not accept LIMIT on a multi-table delete; the syntax error was caught, logged and swallowed, and the sweep reported "0 removed" — indistinguishable from a clean run. It is a single-table DELETE now, and documentsCollectOrphans() returns its errors so a caller can tell "nothing to do" from "it broke".

• The upload folder must be denied by the web server. uploads/documents/ ships an .htaccess and a web.config; nginx needs the rule in deploy/nginx/freeitsm.conf. Run D009 Guarded paths to find out what your server is actually honouring — a random stored filename is not a permission.
• window.t is guarded in documents.js. This component lands on a dozen pages, which is a dozen chances to hit one that forgot i18n.js.
• Nothing in the panel's layout is inherited. .fd-drop is a <label>; a page that does not make labels block-level left it inline and the dashed border wrapped the text instead of drawing a box.
• The command palette drops result types it does not know. Adding a type server-side is not enough — it must be in the array in command-palette.js or the results vanish with no error.
• renderDocumentsPanel() renders nothing when $parentId is 0. An unsaved record has nothing to attach to.

The rule: a document on a knowledge_article can be downloaded from the self-service Help Centre by anyone who may read that article there, unless the link has show_in_help_centre = 0. No other parent_type ever reaches the portal by this route (ticket-note files have their own, api/self-service/get_document.php).

Things that will bite:

• The flag is on the LINK. A document is stored once and pinned to many records; showing it on one article must not show it anywhere else.
• The column defaults to 0, and that is deliberate. Adding it gives every existing link 0, so nothing attached before anyone was told goes public on upgrade. New article links get 1 from documentLinkHelpCentreDefault(). Never backfill existing rows to 1. (TRAP: in includes/db_verify_schema.php and includes/documents.php.)
• Write links through documentInsertLink(). It omits the column until Database Verification has added it - naming a missing column in an INSERT would break every upload on every module between pulling the code and running verification.
• Do not restate "may this requester read this article". Use portalCanReadArticle(); company, audience, lifecycle and the access list all follow from the one scope.

Tested by tests/knowledge-help-centre-documents.php - see Developer Tests - Knowledge.

• Attached documents — the user-facing guide
• Attached documents — permissions and search
• Attachment text extraction — Developer Guide — the email-attachment pipeline this borrows from
• Security — includes/uploads.php and the guarded folders