The page editor is an optional, password-protected screen at yoursite.com/edit/. From it you can see every page and post on the site, open one to change its content and metadata, create new pages and posts, and preview a draft through your live theme before anything is saved — all in the browser, with no database.
Nothing from the editor is ever mixed into your public pages. It has its own screen, its own styling, and it only ever reads and writes files inside pages/.
An optional second factor is also available: a six-digit code from an authenticator app, on top of the password. It is off by default and requires no third-party service.
When $editorEnabled is set to false, zero editor code runs anywhere on the site. It is completely inert.
Installation
The editor plugin ships as a set of PHP files and an .htaccess file inside plugins/editor/, plus one rewrite rule in the site's root .htaccess that maps /edit/ onto it. They are included in the framework repository. No additional setup is needed beyond configuration.
| File | Purpose |
|---|---|
index.php |
The editor itself — login, the page and post lists, the edit form and the preview pane. This is what /edit/ serves. |
editor.php |
Kept for the old way in: appending ?editor=yourtoken to a page now simply sends you to /edit/ with that page open. |
editor-preview.php |
Lets a draft held by your editor session render through the theme when a page is loaded with ?preview. |
editor-auth.php |
Authentication, sessions, CSRF tokens and the IP lockout. |
editor-save.php |
The endpoint that writes pages to disk and stages preview drafts. |
editor-totp.php |
Two-factor code generation and verification. Inert unless you switch it on. |
editor-totp-setup.php |
The two-factor enrolment screen. |
editor-qr.php |
Draws the enrolment QR code. Optional — see below. |
.htaccess |
Blocks direct web access to the plugin's .json state files. |
The plugin also expects config/.htaccess to be present, denying web access to the configuration directory. This ships with the framework and matters more than usual if you enable two-factor — see Keeping the secret safe.
plugins/editor/ must be writable by the user PHP runs as. The editor keeps two small state files there and will refuse to run if it cannot write them.
Configuration
All editor settings live in config/config.php inside the if ($loadplugins == true) block. There are five values:
$editorEnabled = true; $editorToken = 'your-random-token'; $editorPasswordHash = '$2y$10$...'; $editorTotpSecret = ''; $editorSessionTimeout = 1800;
$editorTotpSecret is optional. Left as an empty string, two-factor is off and the editor behaves exactly as it always has — no code field on the login form and nothing else to configure.
Generating a Password Hash
The editor uses a bcrypt password hash — you never store the plaintext password anywhere. To generate a hash:
Step 1. Create a new file anywhere in your site root — for example hash.php — containing exactly this:
<?php echo password_hash('yourpassword', PASSWORD_BCRYPT); ?>
Step 2. Visit that file in your browser: yoursite.com/hash.php
You will see a long string starting with $2y$10$ — something like:
$2y$10$92IXUNpkjO0rOQ5byMi.Ye4oKoEa3Ro9llC/.og/at2.uheWG/igi
Step 3. Copy that entire string and paste it as the value of $editorPasswordHash in config.php.
Step 4. Delete hash.php immediately. Do not leave it on your server.
If you ever want to change your password, repeat this process with the new password and replace the hash in config.php.
Setting the URL Token
The $editorToken is a secret string, and it is required. Until the token has been presented on a device, /edit/ returns the site's ordinary 404 page — not a login form, not an error, nothing that distinguishes it from any other address that does not exist. Bots that scan for admin screens find nothing to catalogue and nothing to hammer. That is the whole point of the token, and it is why the editor refuses to run without one.
You present it once per device by visiting /edit/?editor=yourtoken (or the old anypage?editor=yourtoken). The editor then sets a cookie that remembers the device for 30 days, and plain /edit/ works from then on. The cookie does not contain the token — it holds a keyed hash of it — and changing either the token or the password invalidates every remembered device at once.
A wrong token counts as a failed login attempt against the same per-IP lockout as a wrong password, so the token cannot be guessed at for free. The response is a 404 either way.
Choose something long and random. The easiest way is to generate one at the command line:
php -r "echo bin2hex(random_bytes(16));"
This produces a 32-character hex string like a3f8c2d1e4b7906f2a1d3c5e7b9f0d2e. Paste that as your token:
$editorToken = 'a3f8c2d1e4b7906f2a1d3c5e7b9f0d2e';
Alternatively, make up any string you like — just keep it long (16+ characters) and don't reuse a password or other credential.
Two-Factor Authentication
Setting $editorTotpSecret adds a six-digit code to the login form, alongside your password. The code comes from an authenticator app on your phone — Google Authenticator, Aegis, 1Password, Ente, or any other TOTP app.
It is entirely optional. Leave the value as an empty string and nothing changes.
How it works
No third-party service is involved at any point, and nothing is exchanged over the network. Your authenticator app is an offline calculator: it holds a secret and reads the clock. The server holds the same secret and reads its own clock. Both compute the same number independently, and the server compares what you typed against what it computed.
The maths is RFC 6238. Divide the current Unix timestamp by 30 to get a counter, HMAC-SHA1 it with the secret, then truncate the result to six digits. PHP ships every piece needed, so the implementation has no dependencies, no build step and no external calls.
Turning it on
Step 1. Log into the editor as normal, with just your password.
Step 2. Click Two-factor: off in the editor toolbar, or go directly to:
https://yoursite.com/edit/?totp=setup
The enrolment screen is only reachable once you are already logged in, so your password remains the gate even before a second factor exists.
Step 3. Scan the QR code with your authenticator app, or type the key in by hand — it is shown in groups of four to make that easier. The app will use six digits, a 30-second period and SHA1, which are the defaults everywhere, so you should not need to change any settings.
Step 4. Type the code your app is showing into the test box and press Test code. This only checks the code — it is not used up, and you can test as many times as you like. Do not skip this step. It is much easier to sort out a mismatch now than after you have committed the secret and logged out.
Step 5. Copy the line the screen prints and paste it into config/config.php:
$editorTotpSecret = 'LL2ITCZZLBF4UVYMCOQDTYXUJIFPCNCD';
Step 6. Log out and back in. You will be asked for a code from now on.
The enrolment screen never writes to config.php — it prints the line and you paste it. The editor does not need write access to your configuration.
Logging in with a code
The login form gains a second field next to the password box. Enter your password and the six digits your app is currently showing.
Codes are accepted within 30 seconds either side of the server's clock, which absorbs the usual drift on shared hosting. A code that has been used successfully cannot be used again, even while it is still on screen, so watching someone log in over their shoulder does not help you.
Failed codes count towards the same lockout as failed passwords: five failures from one IP disables the login form for 15 minutes.
The secret must be Base32
$editorTotpSecret must contain only the letters A–Z and the digits 2–7. A plain passphrase will not work. Authenticator apps decode whatever you type as Base32 before hashing it, so a passphrase would decode to different bytes on the app's side than on the server's, and every code would be rejected.
Use the enrolment screen to generate a valid secret rather than inventing one. If the configured value is not valid Base32, the editor refuses to run and tells you so, rather than silently rejecting every code you type.
Keeping the secret safe
Unlike your password, this secret cannot be hashed. The server needs the real value in order to recompute codes, so it sits in config/config.php as plain text.
That is fine as long as Apache executes the file, but if PHP ever stops handling it — the module disabled during an upgrade, a stray config.php.bak, a misconfigured vhost — the file would be served as text and the secret handed to whoever asked. This is what config/.htaccess is for. Make sure it is in place and that nothing in your host's configuration overrides it.
Keep a copy of the secret somewhere safe as well, such as a password manager. See If you lose your phone.
Turning it off
Set the value back to an empty string:
$editorTotpSecret = '';
The code field disappears from the login form and the editor goes back to password only. Remove the entry from your authenticator app too, since it will no longer be checked.
If you lose your phone
There are no backup codes and no recovery email. If you cannot produce a code, the way back in is to edit config/config.php over FTP or SSH and blank the value, which switches two-factor off and lets you log in with your password alone.
To avoid needing that: keep a copy of the Base32 secret in a password manager, or use an authenticator app that syncs or exports its entries. Adding the same secret to a second device also works — TOTP has no concept of a single registered device.
The QR code file is optional
editor-qr.php draws the enrolment QR code in pure PHP. It exists so that your secret is never sent to a hosted QR generator, which would rather defeat the point of the exercise.
It is the largest file in the plugin by some margin. If you would rather not carry it, delete it — the enrolment screen falls back to showing the key for manual entry, which every authenticator app supports. Nothing else in the editor depends on it.
Accessing the Editor
Once configured, go to /edit/, presenting your token the first time if you set one:
https://yoursite.com/edit/?editor=a3f8c2d1e4b7906f2a1d3c5e7b9f0d2e
Two shortcuts also work, and are handy when you are looking at a page and spot something to fix:
https://yoursite.com/about?editor=a3f8c2d1e4b7906f2a1d3c5e7b9f0d2e https://yoursite.com/edit/?page=posts/my-post
Both open the editor with that page already loaded. The first is the address the editor has always used, so old bookmarks keep working.
For end users: bookmark https://yoursite.com/edit/?editor=yourtoken. The first visit on any device remembers it for 30 days; after that, plain /edit/ works too. Nobody has to edit a URL by hand.
You will see a password prompt — with a second field for your authenticator code if two-factor is enabled. The session lasts for the duration set in $editorSessionTimeout (default 30 minutes) and expires automatically on inactivity.
If the token is missing on a device that has not been remembered, or wrong, you get the site's normal 404 page with no indication that an editor exists.
Using the Editor
Once you are logged in the editor shows two lists side by side: Pages (everything in pages/) and Posts (everything in pages/posts/, newest first). Each has a filter box and a button to create a new one. Click any entry to open it.
Editing
The edit screen shows the page's metadata — title, layout, type, date, author, image, excerpt and keywords — above the content.
Posts also get a Categories picker: one chip for every category the site knows about, which is every postcategory an archive page filters on plus every pagecategory already used by a post. Tick any that apply, or type a new one and press Add. Ticking nothing leaves the post uncategorized. A ticked category that no page lists yet is marked with a note — visitors can't browse this yet — and a Create a "…" page link. Clicking it creates the category page right there, without leaving the post: a styled archive filtered on that category, titled after it, at /the-category. The note then offers to open it if you want to change its title or intro text. Category pages are labelled Lists posts in … in the Pages list and show a banner explaining what they are when opened; their Which posts this page lists dropdown offers the same categories, with (all posts) and uncategorized as fixed choices. Both write the plain pagecategory and postcategory tags described in Posts and Categories; nothing about the file format changes.
The Layout list is built from the templates in your active theme, so any page-*.php file a theme adds shows up automatically. Pages that use the page-md layouts are edited as plain Markdown source; everything else gets a rich text editor, with a </> button for raw HTML.
Click Save to write the file. The cache for that page is cleared straight away, and saving a post also clears the archive pages so the new content lists immediately.
Drafts
Every save has a Save as draft alternative. A draft is a page, or a set of changes to a page, that visitors cannot see:
- A new page saved as a draft is not published. It does not appear in archives, category pages, the RSS feed or anywhere on the site, and its address gives visitors the 404 page. You can view it at that address while logged in, and it shows in the editor list with a Draft badge. Publish makes it live.
- Changes saved as a draft on a live page leave the published page exactly as it was. The editor opens the draft from then on, marked Unpublished changes, with Publish (replaces the live page, keeping the old one in History) and Discard draft (throws the changes away, also keeping them in History). Preview shows the draft.
On disk a draft is a sidecar file, pages/<name>.html.draft, next to (or instead of) the live pages/<name>.html. Nothing on the public side of the framework looks for that extension, which is what keeps drafts invisible without any theme needing to know about them. Backups include them.
Unsaved work
Separately from drafts, the editor keeps a copy of whatever you are typing in your browser's own storage, a moment after each change. If the tab is closed, the browser crashes or the session times out before you save, reopening the same page (or the new post form) offers to restore that work. It is cleared when you save, publish or discard. This never leaves your browser; it is a safety net, not a place anything is stored.
History, Delete and Backups
Every save keeps a copy of the page as it was. History on the edit screen lists those copies with what changed in each, and can restore any of them. Delete moves a page to a trash rather than removing it. The Backups link in the toolbar makes and downloads zips of the site, and is where deleted pages are restored from. All of this is covered on its own page: Versions, Trash and Backups.
Files and images
The Files link in the toolbar uploads images and other files into the site's media folders, with drag and drop, subfolders, and a trash. The picture button in the content editor uploads the picked image to the right folder and inserts its path, rather than embedding it in the page. Both are described on Uploading Files.
Preview
Preview renders the draft you are looking at — content and metadata, exactly as they are in the form — through your real theme, in a pane beside the editor. Nothing is saved: the draft lives only in your editor session, is never written to pages/, and is never cached. Close the pane or click Refresh after more edits. You can preview a brand new page before it exists.
New pages and posts
+ New page and + New post open the same form with an extra Address field, which decides where the file is created inside pages/:
aboutcreatespages/about.html, accessible at/aboutposts/my-postcreatespages/posts/my-post.html, accessible at/posts/my-postdocumentation/setup/myguidecreates the file in a subfolder, accessible at that path
Addresses may contain lowercase letters, digits and hyphens, with forward slashes for folders — the same characters the framework's rewrite rule routes. Subfolders are created automatically. You cannot overwrite an existing page, and you cannot use a name that clashes with a real folder in the site root (such as images) or with edit itself, because those addresses would never reach the page.
After a page is created the editor reopens it in edit mode so you can carry on.
Session Timeout
$editorSessionTimeout controls how long an authenticated session lasts without activity, in seconds. The default is 1800 (30 minutes). Adjust it to suit your workflow:
$editorSessionTimeout = 3600; // 1 hour $editorSessionTimeout = 900; // 15 minutes
When a session expires you will be prompted to enter your password again — and your code, if two-factor is enabled.
Update Notices
The version chip in the editor's top bar (SWF 1.1.5) doubles as an update check. Once a day, when you open the editor, it asks GitHub for the newest framework release; if that is newer than the site, the chip turns amber (SWF 1.1.5 → 1.2.0) and a bar appears under the top bar with the release's first line of notes and three links: What's new (the release page), Download the upgrade zip, and How to upgrade (the upgrade instructions). Dismiss hides it until the next release after that one. Click the chip at any time to check now; its tooltip tells you when it last looked.
Nothing is installed for you. Upgrading is still "download the zip, unzip it over the site" — the editor deliberately never writes to the framework's own files from the network.
How it works, for the record: GitHub publishes every release of the framework as JSON at api.github.com/repos/ScarylePoo/simple-website-framework/releases/latest. The editor fetches that once a day at most, from your server, with a 5-second timeout, and remembers the answer in plugins/editor/update-check.json (which the editor's .htaccess refuses to serve). The only thing GitHub sees is an ordinary request from your server's address. A site nobody logs in to never checks at all. If the request fails — a host that blocks outgoing connections, say — nothing is shown and it tries again an hour later.
To never check, set in config/config.php:
$editorUpdateCheck = false;
Without the editor, or from cron, the same check is available on the command line and exits with 10 when an update is available, so it can trigger an email:
php plugins/editor/backup-cli.php check-update
Security Model
The editor uses several layers of protection:
| Layer | What it does |
|---|---|
| URL token (required) | Makes /edit/ answer with the site's 404 page until the token has been presented once on the device. No login form is ever publicly visible, so there is nothing for scanners to find or pound on. Wrong tokens count toward the lockout. |
| Device cookie | Remembers a device for 30 days after the token is presented. Holds a keyed hash of the token, never the token. HttpOnly, SameSite Strict, Secure on HTTPS. Rotating the token or password invalidates it everywhere. |
| Password + bcrypt | Verifies identity on login. The plaintext password is never stored anywhere. |
| Two-factor code (optional) | When $editorTotpSecret is set, a six-digit time-based code from your authenticator app is required alongside the password. Defends against a leaked or reused password. |
| Replay protection | A code stays valid for its full 30-second window, so the same digits would otherwise work twice. The last accepted counter is recorded and anything at or below it is rejected. |
| IP-based lockout | After 5 failed login attempts from the same IP address, the login form is disabled for 15 minutes. Persists across cookie resets. Failed codes count the same as failed passwords. |
| Session regeneration | The session ID is rotated immediately on successful login, preventing session fixation attacks. |
| CSRF token | Every save, create, and logout action must include a cryptographically random token tied to the current session. Protects against cross-site request forgery. |
| Session timeout | Sessions expire automatically after the configured period of inactivity. |
| Secure cookie flags | The session cookie is flagged HttpOnly (no JavaScript access) and SameSite Strict. When $SSL is on, or the request arrived over HTTPS, it is also flagged Secure. Plain-HTTP installs get a cookie without the Secure flag so that login actually works there. |
| Path validation | All file write operations validate that the target path resolves inside pages/. Path traversal attempts are rejected, and new page names are restricted to the characters the router accepts. |
| Private previews | A preview draft is held in the server-side session of the person editing. A page loaded with ?preview only shows a draft to the session that staged it, for that exact page, and such requests are never read from or written to the cache. |
| Misconfiguration guards | The editor refuses to run — rather than failing quietly — if its state files cannot be written or if the two-factor secret is not valid Base32. |
It is worth being clear about what the second factor does and does not buy you. It protects against a password that has leaked, been reused, or been guessed. It does not protect against a hijacked session or a compromised server, and the secret itself sits in plain text on disk because verifying a code requires the real value. Worth having, but a narrower gain than two-factor is usually advertised as.
Troubleshooting
Every code is rejected
Almost always one of two things. Either the secret is not what your app has — regenerate it from the enrolment screen and re-add it — or the server clock has drifted. Codes are accepted within 30 seconds either side of the server's time, so a clock more than half a minute out will reject everything no matter how carefully you type. Check the server's time before suspecting anything else.
"Two-factor secret is not valid Base32"
The value in config.php contains characters outside A–Z and 2–7 — most often because a passphrase was typed in instead of a generated key. Use the enrolment screen to produce a valid one, or set the value back to an empty string to switch two-factor off.
"Editor cannot write its state files"
plugins/editor/ is not writable by the user PHP runs as. The editor stores its failed-attempt counts and its last accepted code counter there, and without them the lockout and replay protections would silently stop working — so it refuses to run rather than pretending to be protected. Make the directory writable and check its ownership.
The Two-factor link in the toolbar does nothing useful
The enrolment screen requires you to be logged in. If your session expired between loading the page and clicking the link, log in again and retry.
Preview shows the old content of the page
The two bundled themes read page content through swf_page_source(), which is what lets a draft stand in for the file on disk. A theme that reads pages/<pagename>.html directly in its page-*.php templates will show the saved file instead. See Themes and the preview.
/edit/ gives a 404
This is the expected response for anyone who has not presented the token on this device, so first try /edit/?editor=yourtoken. If that also 404s: $editorEnabled may be false, your IP may be in the 15 minute lockout from earlier failed attempts, or the RewriteRule ^edit/?$ plugins/editor/index.php line may be missing from the site's root .htaccess (or mod_rewrite is off). If $editorToken or $editorPasswordHash is empty, /edit/?editor=anything shows a message saying which one to set.
Themes and the Preview
The preview works by substituting an unsaved draft for the page file at render time. Every place the framework reads a page's source goes through one function, swf_page_source($pagename) in required/vitalfunctions.php, which returns the draft when one is being previewed and the file contents otherwise.
If you write your own theme, read page content in your layout templates the same way:
$filename = swf_page_source($pagename);
rather than calling file_get_contents("./pages/" . $pagename . ".html") directly. With no preview in progress the two are identical, so an existing theme keeps working if you do not change it — its previews will just show the saved content rather than the draft.
Disabling the Editor
Set $editorEnabled = false in config.php. When false, /edit/ returns the site's 404 page, no editor code runs on any page, and the ?editor and ?preview query parameters are ignored entirely. To sign out every remembered device without disabling the editor, change $editorToken.