innhold/docs/publiser-tool.md

Publiser Tool Reference

For LLM agents working on the /publiser publishing tool. Read when modifying anything under content/publiser/, custom/plugins/publiser-lib.php, or custom/plugins/global/scheduled-publisher.php.

Overview

Standalone admin app for authoring, managing, and scheduling content/nyheter/ and content/artikler/ posts without hand-editing files - built for non-technical editors. Password-protected (Basic Auth), served entirely outside the CMS routing/templating pipeline. Located in content/publiser/.

• content/publiser/index.php - the whole app: routing, auth, views, POST actions, image upload/serve, and the bounded Markdown<->HTML conversion used by the block editor.
• custom/plugins/publiser-lib.php - shared logic (paths, metadata I/O, block/file operations, publish/unpublish/trash/restore, scheduling). Required by both index.php and the scheduler plugin, so there is exactly one implementation of "what publishing a post means."
• custom/plugins/global/scheduled-publisher.php - auto-publishes due scheduled posts via a Hook::CONTEXT_READY callback (fires on every normal site page load).
• content/publiser/publiser.css / publiser.js - editor UI and the client-side half of the Markdown serialization.
• custom/tools/set-publiser-password.php - CLI to set/reset the login.

Why It's Not Routed Through the CMS

content/publiser/index.php is served directly by Apache, not via app/router.php. It has no Context, no templates, no site chrome - it only reuses the pure, hook-free helpers from app/helpers.php (findCoverImage, getSubdirectories, extractRawDateFromFolder). This keeps the admin tool decoupled from app/'s request-routing internals (a separate git repo - see main README) while still sharing its file-format conventions.

Routing & Auth

content/.htaccess.base (synced to content/.htaccess - see docs/security-cpanel.md) has two /publiser-specific additions:

1. A <FilesMatch> exception so .php/.html/.md/.ini files under /publiser aren't blocked by the CMS's "no direct file access" rule.
2. A RewriteRule dispatching everything under /publiser (except .css/.js/image requests) to content/publiser/index.php, bypassing the CMS's own catch-all-to-/index.php rule.

content/publiser/.htaccess sets DirectorySlash On (the site-wide default is Off - see Critical section below) and forwards the Authorization header via RewriteRule ... [E=HTTP_AUTHORIZATION:...] for SAPIs (LSAPI/CGI/FastCGI, used on cPanel) that strip it by default.

Auth itself is checked in PHP (publiserRequireAuth() in index.php), not via Apache's AuthUserFile - that directive needs an absolute path that differs between the podman dev container and cPanel, so a bcrypt .htpasswd (same format mod_authn_file would use) is read and verified manually instead. Set the login with:

php custom/tools/set-publiser-password.php <username> <password>

This writes content/publiser/.htpasswd (gitignored, 0644 - see comment in the script for why world-readable is fine here).

Content Model

Drafts and trash are staged outside the public content tree, mirroring the exact folder shape the CMS reads (so "publish" is just a directory move):

custom/data/publiser/         (gitignored - runtime state, not source content)
  drafts/
    nyheter/<slug>/           # metadata.ini, 10-*.md, 20-*.html, cover.*, images...
    artikler/<slug>/
  trash/
    nyheter/<slug>~<unix-timestamp>/
    artikler/<slug>~<unix-timestamp>/

• Folder naming: draft/trash folders are always just the slug (no date prefix), for both sections. Live nyheter folders get a YYYY-MM-DD- prefix at publish time; live artikler folders don't (matches the pre-existing convention - nyheter posts are dated, artikler aren't).
• Blocks: each content file (.md/.html/.php) in a folder is one editable "block" (publiserListBlocks()). .md is edited as WYSIWYG rich text; .html/.php as raw code (never parsed/rendered in the editor). Order is filename natural-sort; the tool renumbers to a step-10 prefix (10-, 20-...) whenever blocks are reordered or added, leaving room to insert between existing ones.
• Non-block files (subfolders, PDFs, .en.* translations) are listed read-only in the editor (publiserListExtraFiles()) with a note to edit them directly - the tool doesn't try to manage arbitrary file types or translations.
• Metadata: metadata.ini is read with INI_SCANNER_TYPED (not the CMS's default scanner mode) so bare true/false round-trip as real booleans instead of PHP's normal-mode "1"/"" quirk - see Critical section.

Editing Model: the H1/Title Convention

The site has no metadata-driven page heading - page.php just outputs $content directly, so the visible <h1> comes entirely from a leading # Title line in the first content file (same convention extractTitle() in app/helpers.php relies on). The editor's "Tittel" field owns that line:

• On load, publiserStripLeadingH1() (in index.php) strips a leading # ... line from the first richtext block only, so it doesn't show up duplicated inside the editable body.
• On save, publiserApplyFormSave() always re-prepends # {title}\n\n to that same block, keeping the file's real H1 in sync with the title field - even if the block's body wasn't otherwise touched.

Markdown <-> HTML (Bounded, Not General-Purpose)

No markdown library is used for the editor - a small, closed-world parser handles only the constructs the toolbar can produce: paragraphs, ##/###, bold/italic, links, images, > blockquotes, -/1. lists, and raw HTML blocks (see below). This is deliberate: it doesn't need to handle arbitrary CommonMark, only what this tool itself writes.

• Server -> client (publiserBlockMdToHtml() in index.php): runs once, when populating the contenteditable div on page load.
• Client -> server (serializeNode()/serializeChildren() in publiser.js): runs on save, walking the edited DOM back to Markdown.
• Untouched blocks are never rewritten: each block has a hidden .p-block-hidden textarea (default value = the block's raw, unmodified content) and a .p-dirty-flag (default 0). JS only overwrites the hidden field and flips the flag when the user actually edits that specific block. The backend skips saving any block whose dirty flag is 0. This protects legacy content with markdown constructs the bounded parser doesn't understand from being silently flattened/corrupted by a save the user never intended to touch that block.
• Raw HTML embedded in markdown (e.g. an <iframe> embed, common on older posts): rendered as a live, contenteditable="false" island with the exact source stashed in data-raw-html, so it displays correctly (not as escaped literal text) and round-trips byte-for-byte on save without needing DOM reconstruction. Prefer restructuring such content into its own .html block instead when editing an existing post (see Riksrevisjonen/SPLEIS posts for the pattern) - the raw-HTML island is a safety net, not the intended authoring path.

i18n

The site supports translations via paired files (article.md + article.en.md, [en] metadata sections). The tool only edits the base (Norwegian) language:

• publiserIsLanguageVariant() excludes *.en.{md,html,php} from publiserListBlocks() - they're a different language's version of the same content, not another sequential block.
• publiserExtractTitle() (title fallback for posts with no explicit metadata.ini title) mirrors app/helpers.php's extractTitle() but operates on the filtered block list - the site's own extractTitle() would otherwise pick article.en.md over article.md by alphabetical accident ("en" < "md"), surfacing an English title in the Norwegian-only dashboard.
• Translation files are surfaced as a read-only "🌐 (engelsk oversettelse)" entry in the editor instead of being hidden entirely.

There is no UI for editing or creating translations - that's still a manual, hand-edit-the-files task.

Scheduling

custom/plugins/global/scheduled-publisher.php is registered in custom/config.ini's [plugins] enabled list. It hooks Hook::CONTEXT_READY, which fires on every site page load (via app/config.php's createContext()), and calls publiserPublishDueScheduledItems(): scans custom/data/publiser/drafts/*/* for status = "scheduled" items whose publish_at has passed, and publishes them through the exact same publiserPublish() path the admin UI uses.

No cron job - publishing happens on the next real visitor request after the scheduled time. Accepted tradeoff for a low-traffic nonprofit site: no hosting-level cron setup required, at the cost of not being to-the-second.

Key Functions (custom/plugins/publiser-lib.php)

Function	Purpose
publiserContentRoot()	content/ dir, resolved via $_SERVER['DOCUMENT_ROOT'] - see Critical section
publiserLiveDir/DraftDir/TrashDir()	Path resolvers for the three storage locations
publiserSlugify() / publiserUniqueSlug()	Norwegian-char-aware slug generation with collision avoidance
publiserReadMetadata() / publiserWriteMetadataFile()	metadata.ini I/O (typed scanner on read; hand-rolled INI serializer on write)
publiserLockedRename() / publiserMoveDir()	flock()-guarded directory move, with a copy+delete fallback for cross-filesystem moves
publiserListBlocks() / publiserAddBlock() / publiserReorderBlock() / publiserDeleteBlock()	Block (content file) management
publiserExtractTitle()	Language-aware title fallback (see i18n section)
publiserSaveUploadedImage() / publiserSaveCoverImage()	GD resize (max 1600px wide, quality 82) + save
publiserCreateDraft() / publiserPublish() / publiserUnpublish() / publiserTrash() / publiserRestore()	The five state transitions; all soft (nothing is ever unlink()-ed except superseded cover images)
publiserSetSchedule() / publiserPublishDueScheduledItems()	Scheduling
publiserListLive() / publiserListStaged() / publiserSummarize()	Dashboard listing

Critical: Do Not Break

1. publiserContentRoot() must use DOCUMENT_ROOT, not a path relative to this file. The dev container mounts content/ at /var/www/html (named to match Apache's default docroot) while custom/ and app/ keep their real names - a fixed relative path would only be correct in production, where content/custom/app are plain siblings. Matches the same approach app/config.php's createContext() already uses.
2. DirectorySlash On in content/publiser/.htaccess. The site sets DirectorySlash Off globally. Without a local override, a bare /publiser (no trailing slash) request never reaches any rewrite rule at all - Apache falls through to mod_autoindex and 403s, since /publiser is a real directory. This is scoped to just this one directory; don't "fix" it by changing the site-wide setting.
3. publiserMoveDir()'s copy+delete fallback is load-bearing, not defensive fluff. rename() fails with EXDEV across bind-mount boundaries - content/ and custom/ are separate mounts in the dev container even though they're the same host filesystem. Don't simplify this back to a bare rename() call.
4. INI_SCANNER_TYPED in publiserReadMetadata(). The CMS's own loadMetadata() uses the default scanner, where bare true/false come back as "1"/"". Reading typed and writing bare booleans back out (via publiserIniValue()'s is_bool() check) is what keeps something like hide_list = true from being silently rewritten as hide_list = "1" the first time a post is saved through the tool.
5. Untouched blocks must stay byte-identical. Don't change the dirty-flag/hidden-field mechanism (see Markdown section) without preserving the guarantee that a block the user never focused is never rewritten - that's what makes it safe to open legacy posts with hand-crafted Markdown the bounded parser can't fully round-trip.
6. .htpasswd must stay world-readable (0644). It's regenerated by set-publiser-password.php with that mode deliberately - the web server user (www-data, uid varies by host/container) needs read access, and direct HTTP access is already denied by <Files ".htpasswd"> in the .htaccess. A stricter mode (e.g. 0640) breaks auth silently if the file's owning group doesn't include the web server user.
7. SELinux labels on Fedora/podman hosts. If you ever manipulate files under content/publiser/ via host-side shell tools (not through the app itself), watch for context drift (e.g. picking up user_tmp_t after being routed through /tmp) - the container needs container_file_t to read them. Symptom: Apache logs "Server unable to read htaccess file" or similar despite correct Unix permissions. Fix: chcon -t container_file_t <path> (or restorecon).
8. One publish code path. publiserPublish() is called both by the admin UI's "Publiser" button and by the scheduler. Don't duplicate publish logic elsewhere - both callers must go through this function so scheduled and manual publishing can never disagree about what "published" means.

Known Limitations (By Design, Not Oversights)

• No English/translation editing - read-only awareness only (see i18n).
• No permanent-delete UI - trash is soft-forever; cleanup is a manual filesystem task on the server.
• No per-editor accounts/audit trail - one shared Basic Auth login.
• Editing an existing post with multiple content files works (each is a block), but files outside the block model (subfolders, PDFs) must still be managed by hand.
• Scheduling fires on next page view, not at an exact time (see Scheduling section).

Local Dev Notes

• GD extension (image resize) requires the Containerfile addition (docker-php-ext-install gd) - not present in the stock php:8.4-apache image.
• compose.yaml's startup chown was extended to also cover content/nyheter and content/artikler - nothing previously needed to write into the (bind-mounted, host-owned) content tree, so the container's www-data had no write access there before this tool existed.
• Test login for local dev is whatever you last set with set-publiser-password.php; it's gitignored and won't carry over to a fresh checkout or to production.