FileSmith Editor documentation

What is FileSmith Editor

The theme and plugin editors that ship with WordPress can only change files that already exist. FileSmith Editor keeps the same familiar layout, with the code editor on the left, the file list on the right and the theme or plugin selector on top, and adds what is missing. The free version has tabs, quick open, image preview, a PHP syntax check, backups with restore and access by role. Pro adds creating, uploading, renaming, moving, duplicating, trash, compare with disk, formatting, code checks, draft recovery, a site test with rollback, an activity log and access by user.

There is a free version and a Pro version, both GPLv2 or later. Neither is hosted on WordPress.org. You download them from this site. The free version updates itself from here, and Pro updates through Freemius. Features marked Pro in this guide are not in the free version, see the plans.

Requirements

Installation

Upload from the admin

1. Download filesmith-editor.zip from the plugin page.
2. In WordPress, go to Plugins, Add New, Upload Plugin.
3. Choose the zip and click Install Now.
4. Click Activate Plugin.
5. Open FileSmith, Editor in the admin menu.

Upload by FTP

Unzip the file and upload the filesmith-editor folder to /wp-content/plugins/. Then activate it on the Plugins screen.

Upgrade to Pro

Buy a licence, download the Pro zip, upload it the same way and activate it. The free version is deactivated automatically. Pro uses the same settings and backups, so nothing is lost.

Admin menu

The plugin adds a FileSmith menu with the Editor and Settings screens. Pro adds the Activity log. The free version adds an Upgrade to Pro screen with the plans.

Quick start

1. Go to FileSmith, Editor.
2. Choose Theme or Plugin in the Type box, then pick the item in the Item box.
3. Click a file in the list on the right. It opens in a tab.
4. Edit the code. The tab shows a dot and the status bar says Unsaved changes.
5. Press Ctrl + S or click Save file. A backup is made first.
6. Press Ctrl + P to jump to another file by name.

Screen layout

On narrow screens the layout stacks and the less-used header buttons show icons only, so the header does not overflow.

Choosing a theme or plugin

The Type box switches between themes and plugins. The Item box lists everything of that type that is installed, active or not. The editor only shows files inside the chosen folder, so nothing outside it can be reached.

• Plugins must live in their own folder. Single-file plugins, such as hello.php directly in the plugins folder, are not supported yet.
• Switching to another item closes the open tabs. If any have unsaved changes you are asked first.
• Your last choice is remembered, see Remembered files.

Open files and tabs

• Each file you open gets its own tab. Opening a file that is already open just switches to its tab.
• Each tab keeps its own text, cursor position and undo history, so you can switch freely.
• A tab with unsaved changes shows a dot. The close button asks before discarding changes.
• Up to 15 files can be open at once. Close a tab to open another.
• Image files open in a tab too, see Image preview.

Status bar

Under the editor, the status bar shows:

• The file type (PHP, CSS, JS and so on).
• The cursor position as line and column.
• In Pro, the Compare with disk button, see Compare with disk.
• A badge: Unsaved changes (amber) or No changes (green).
• A badge: Editable or Read-only.

The file list

• Folders show an arrow and a folder icon that is open or closed. Click a folder to open or close it.
• Files show a colored icon for their type.
• The selected file or folder is highlighted, and its path is shown above the list after Selected:. In Pro, the toolbar actions work on the selected item.
• The file you have open is marked, and its folders open automatically.
• Files the editor cannot edit are greyed out. Images can be opened for preview.
• Folders listed under Excluded folders in Settings (by default .git, .svn and node_modules) are hidden.

Create files and folders Pro

1. Select the folder where the new item should go. With nothing selected, it goes in the root folder.
2. Click New file or New folder in the toolbar, or use the right-click menu.
3. Type a name and click Create. The dialog states where it will be created.

• File names must use an allowed file type, see File types.
• Names are limited to 100 characters. Invalid names, path tricks such as ../ and names that already exist are refused with a message.
• A new file opens in a tab, ready to edit.
• Needs the Create permission.

Upload files Pro

Click Upload files (or choose it in the right-click menu on a folder), pick one or more files and click Upload. They go into the selected folder.

Developers can change the type list and the size with fsed_upload_extensions and fsed_max_upload_size.

Rename and move Pro

Rename

Select a file or folder, click Rename and type the new name. If the file is open, its tab updates.

Move

Select an item, click Move and choose the target folder from the list, including Root folder. A folder cannot be moved into itself or one of its own subfolders. If there is no other folder, you are told so.

Backups follow a file when it is renamed or moved, so its history is not lost. Needs the Rename or Move permission.

Duplicate Pro

Select a file, click Duplicate and type a name for the copy. The copy is created in the same folder. It is useful for trying a change on a copy, or starting a new file from a template. Needs the Create permission.

Delete and trash Pro

Select a file or folder and click Delete. You are asked to confirm.

• When the trash is on (the default), the item is moved to the trash and can be restored, see Trash.
• When the trash is turned off with fsed_trash_enabled, the delete is permanent and the confirm message says so.
• Deleting a folder deletes everything inside it.
• If the file is open, its tab closes.
• Needs the Delete permission.

Download as a zip Pro

• Version control folders and node_modules are left out, plus any folder you list under Excluded folders.
• The zip is made on the server from the files on disk. Unsaved changes in the editor are not included, and you are warned if you have some.
• The temporary zip is deleted after it is sent.
• A size limit protects the server, change it with fsed_zip_max_size.
• Needs the Download zip permission. Each download is written to the activity log.

Right-click menu Pro

Right-click any file or folder in the list, or select it and press Shift + F10 (or the Menu key). The menu offers only what you have permission for and what makes sense for the item:

Use the arrow keys to move in the menu, Enter to choose and Esc to close it.

The code editor

FileSmith Editor uses CodeMirror, the same code editor WordPress ships with, so highlighting and shortcuts behave as you expect.

• Syntax highlighting for PHP, CSS, SCSS, LESS, JavaScript, JSON, HTML, XML and SVG, Markdown and YAML. Other text files open as plain text.
• Line numbers, tab size, line wrapping, font size and a light or dark theme are set in Settings, Editor.
• Undo and redo work per tab.
• If the editor library cannot load, a plain text box is used instead, so you can still edit and save.

Saving a file

Press Ctrl + S (Cmd + S on Mac) or click Save file. In this order, FileSmith Editor:

1. Checks that the file on disk is still the version you opened, see Changed-on-disk warning.
2. Checks the code. PHP files with errors are not saved (JSON too, in Pro), see PHP syntax check.
3. Makes a backup of the current file, see Backups. If the backup cannot be made, the save stops.
4. Writes the file.
5. In Pro, if the site test is on and it is a PHP file, loads the site and rolls back if it breaks, see Site test.
6. Marks the tab as saved (and, in Pro, clears any saved draft).

PHP's opcode cache is cleared for the file, so the change takes effect at once. Needs the Edit and save permission.

Quick open (Ctrl+P)

Press Ctrl + P (Cmd + P on Mac) to open a search box over the editor.

• Type part of a file name. Matches update as you type, with the folder shown next to each name.
• Use ↑ and ↓ to choose and Enter to open the file in a tab. You can also click a result.
• Esc, a click outside or Ctrl + P again closes it.
• Ranking: names that start with your text first, then names that contain it, then paths that contain it, then letters in order (clsapi finds class-api.php). The top 50 are shown.
• It searches the open theme or plugin, including image files.
• It does not open while another dialog is open. On this screen it replaces the browser's Print shortcut.

Format Pro

Format tidies the indentation of the open file. Use the Format entry in the right-click menu or press Shift + Alt + F.

• Works on CSS, SCSS, LESS, JS and JSON files.
• It only changes the text in the editor. Nothing is saved until you click Save, and you can undo it with Ctrl + Z.
• You are told when the file was already formatted.
• JSON with a syntax error is not formatted, and the error is shown.
• The tab size from Settings is used for the indentation.
• JS and CSS formatting uses the small open-source library js-beautify (MIT license) in assets/js/vendor/beautifier.min.js. If the file is missing you see a message. JSON is formatted without it.

Syntax checks and markers

Hover a marker to read the message. In Pro, the JSON check can be turned off with fsed_check_json_syntax.

Image preview

Click a PNG, JPG, GIF, WebP, BMP, ICO or AVIF file in the list to see it, instead of a "cannot edit" message. The preview shows the picture on a checkered background, with its type and size underneath.

• Images are read-only. In Pro, rename, move, download and delete still work.
• Images up to 5 MB can be previewed. Change it with fsed_max_preview_size.
• SVG files stay editable as text.
• Needs the View permission.

Read-only files

A file opens read-only, with a message and a Read-only badge, when:

• PHP cannot write to it (file permissions or ownership), or
• your account has View but not Edit and save.

You can still read and copy it. In Pro, you can also compare and download it.

Refresh

Click Refresh or press Ctrl + Alt + R to reload the open file and the file list from disk without reloading the page. Use it after changing files by FTP, Git or a build tool.

• Your tabs, cursor position and scroll position stay where they are.
• If the open file has unsaved changes, you are asked first, because Refresh replaces them with the disk version.
• In Pro, to see what changed before you decide, use Compare with disk.

Fullscreen

Click Fullscreen to give the editor and the file list the whole browser window. Press Esc or click Exit fullscreen to go back. If a dialog is open, Esc closes the dialog first.

Remembered files

FileSmith Editor remembers, for your user in your browser, the theme or plugin you had open and the files in your tabs. After a page reload, or when you come back later, you land in the same place. Files that no longer exist are skipped.

Tooltips

Every button has a tooltip that says what it does, including its shortcut and what happens to unsaved work. The icon-only buttons in the file list show their name when you hover them or focus them with the keyboard.

How the safety net works

No tool can make live code editing risk-free. FileSmith Editor stacks several layers so that most mistakes can be undone:

PHP syntax check

Before a PHP file is written, the code is parsed on the server. If it has a parse error, such as a missing semicolon, an unclosed bracket or a stray character, the file is not saved and you see the message with the line number.

• The code is parsed, never run.
• It catches parse errors only. It cannot know that a function does not exist. For that, Pro has the site test.
• Turn it off with add_filter( 'fsed_check_php_syntax', '__return_false' ); (not recommended).

Backups and restore

Every time you save a changed file, the version that was on disk is copied to a backup first. If the backup cannot be made, the file is not saved.

Where backups live

In a folder with a random name inside your uploads folder, protected by an index.php and an .htaccess file. Backups use the .bak extension, so they can never be executed. Each backup records the name of the user who saved the change.

How many are kept

Free keeps the latest 5 per file. Pro keeps 20 by default, and you can set 1 to 100 in Settings, Files, or use fsed_max_backups. The oldest are deleted when the number is passed.

Using the Backups screen

1. Open a file and click Backups in the header.
2. Pick a backup from the list on the left. Each shows its date, size and who saved it.
3. Pro: the Changes tab shows a line-by-line diff between the backup and what is in the editor now. Red lines are in the backup only, green lines are in the editor only, and unchanged lines are folded away.
4. The full text of the backup is shown. In Pro it has its own Backup tab.
5. Click Load into editor to put the backup into the editor. Nothing is saved until you click Save file, so you can review it first.

Files that are very large or very different may be too big to compare, and you are told. Needs the Backups permission. When a file is renamed or moved, its backups move with it.

Changed-on-disk warning

If the file was changed by something else after you opened it (FTP, Git, a build tool, another admin), saving would silently replace those changes. To prevent that, every save first reads the file from disk and compares it with the version you opened.

• If they are the same, the save goes on.
• If they differ, Free asks you to confirm before it overwrites. In Pro, the comparison dialog opens and shows the difference. You choose Save anyway (a backup is made first) or Load disk version, or close the dialog to cancel the save.
• Line-ending differences (Windows and Unix) are ignored.
• If the file cannot be read, for example because it was deleted, the save is left to decide.

Compare with disk Pro

Click Compare with disk in the status bar under the editor to see how the open file differs from the version on disk, any time, without saving or reloading.

• The dialog reads the file from disk and shows a line-by-line diff. Red lines are on disk only, green lines are in the editor only. A summary shows how many lines were added and removed.
• If the file on disk changed after you opened it, a line at the top says so.
• If both are the same, it says so.
• Load disk version replaces the editor content with the disk version and drops your unsaved edits. It is off when both are the same or the file is read-only.
• The button is off for image tabs and while a save or refresh is running.

The same dialog opens by itself when a save finds a changed file, with the extra Save anyway button. Press Esc to close it.

Site test and rollback Pro

An optional extra for PHP files. Turn it on in Settings, Files. It is off by default.

What happens

1. You save a PHP file that belongs to an active theme or plugin.
2. The file is written, then FileSmith Editor loads your front page and admin-ajax.php with a short-lived secret token.
3. If either returns an HTTP 500 or shows a fatal or parse error, the old file is put back automatically, the save is reported as failed and you see why.
4. If both load, the save stands and a note says the test passed.

Details you should know

• No false rollbacks. If the site was already failing before your change, the new file is kept so you can fix it.
• Paused extensions. If WordPress's fatal error protection paused the plugin or theme during the test, that pause is cleared on rollback.
• Skipped when blocked. If the server does not allow the site to call itself (HTTP 401 or 403, or a connection error), the test is skipped and you are told.
• Only active code. Files of inactive themes and plugins are not tested, since they do not run.
• Speed. It adds a few seconds to each PHP save.
• Email. WordPress may email its admin about the failed test, as it does for any fatal error.
• Skip it for chosen files with the fsed_test_save filter.

Unsaved-draft recovery Pro

A moment after you stop typing, unsaved edits are stored in your browser. If the browser crashes, the laptop dies, the page reloads or you close the tab by mistake, your work is not lost.

• Open the file again and the draft comes back, marked as unsaved, with a note showing the time of the last edit.
• If the file also changed on disk after the draft was made, you are told, and Save will ask before overwriting.
• A draft is removed when you save, close the tab, click Refresh, or switch to another theme or plugin.
• Drafts older than 30 days are deleted, and at most 25 are kept.
• Drafts are stored in your browser (local storage), for your user only. Nothing is sent to the server. They do not follow you to another browser or computer.
• If your browser blocks local storage, for example in some private windows, the feature quietly turns itself off.

Trash Pro

Deleted files and folders are moved to a trash folder instead of being removed.

1. Click the Trash icon at the end of the file list toolbar. The button only shows if you have the Trash permission.
2. Each item shows its original path, who deleted it, when, and for a folder how many files it holds.
3. Click Restore to put it back where it was.
4. Click Delete permanently to remove one item for good, or Empty trash to remove everything. Both ask first.

• Items are removed for good after 30 days, and the trash keeps up to 100 items. Change this with fsed_trash_days and fsed_trash_max_items.
• The trash folder is protected like the backup folder.
• Turn the trash off with fsed_trash_enabled. Deletes are then permanent.
• Restoring, permanent deletes and emptying the trash are written to the activity log.

Save error messages

When a save fails, you are told why, not just that something went wrong:

Settings

Go to FileSmith, Settings. In Pro the screen has five tabs. The free version has fewer settings: the Activity log tab, the site test and access per user are Pro. Click Save settings at the bottom after changing anything. Only administrators can change settings (on multisite, only super admins).

Editor tab

Files tab

Activity log tab Pro

Access control tab

See Access control.

About tab

Shows the installed version, links to this documentation and to support, the update status with Check for updates and Update now buttons (see Updates and privacy), and a list of other plugins by WpWebGuru.

Access control

Decide who can do what, per role (Free) or per user (Pro), in FileSmith, Settings, Access control.

The ten permissions

Free has three: View, Edit and save, and Backups. The other seven are Pro.

Access by role

A table lists every role with a checkbox for each permission, and an All box to tick the whole row. Administrators always have full access and are not listed. Ticking any permission also grants View, because nothing works without it.

Access by user Pro

Type a username or email under Add a user and save. The new user starts with View only. Tick what they may do and save again. A user entry replaces the role settings for that person, so you can give one developer more, or one person less, than their role. Tick Remove to go back to the role settings. An entry with no ticks means no access at all. Administrators cannot be limited.

Rules that cannot be changed

• The settings can only limit access. A user still needs the WordPress capability edit_themes or edit_plugins. The Editor and Author roles do not have them, so they cannot use FileSmith. Their boxes are locked and a warning explains why. A role editor plugin or custom code can give a role those capabilities.
• DISALLOW_FILE_EDIT and DISALLOW_FILE_MODS switch the editor off for everyone, the same as the built-in editors.
• Every request is checked on the server. Hiding a button is only a courtesy.

Activity log Pro

Open FileSmith, Activity log to see who did what and when. The log is stored in its own database table, with the user name saved on each row, so it stays readable after a user is deleted.

What is recorded

Saved, Created file, Created folder, Duplicated, Uploaded, Renamed, Moved, Moved to trash, Deleted, Restored from trash, Deleted from trash, Emptied trash and Downloaded zip.

Columns

Date (in your site's date and time format), User, Action, Theme / plugin and File. For renames and moves, the new path is shown after an arrow.

Using it

• Filter by action and by user, then click Filter.
• 25 entries are shown per page.
• Clear log deletes every entry after a confirmation.
• Entries older than the retention period (90 days by default) are deleted automatically, once a day.
• Turn logging off in Settings. The log screen then shows a warning.

Updates and privacy

Because the free version is not on WordPress.org, it checks this site for new versions. Pro gets its updates through Freemius with your licence, on the normal Plugins and Updates screens.

Free version

1. At most once every 12 hours, the plugin requests a small JSON file from plugins.wpwebguru.com over HTTPS.
2. When a newer version exists, an alert shows on the Dashboard, the Plugins screen and the FileSmith screens. You can also click Check for updates in Settings, About.
3. Click Update now. The normal WordPress updater installs it, so your settings and backups are kept.
4. Before installing, the package's SHA-256 hash must match the one in the update file, and it may only be downloaded from this author's host.

Turn the check off with define( 'FSED_DISABLE_UPDATE_CHECK', true ); in wp-config.php, or the fsed_disable_update_check filter. Settings, About then says so. Updating needs the WordPress update_plugins capability.

Pro version

Updates and licensing run through the Freemius SDK. After activation, Freemius asks for an opt-in. If you agree, basic site and account data (name, email, site URL, plugin version) is shared with Freemius for updates, licensing and product news. You can skip the opt-in, and the plugin works the same. A licence includes 1 year of updates and support. After that, Pro keeps working, and you can renew to get updates again.

Multisite

On a multisite network, only super admins can use the editor and change its settings. Themes and plugins are shared by the whole network, so editing them affects every site.

Keyboard shortcuts

On Mac, use Cmd in place of Ctrl.

Limits and defaults

File types

Change the editable list in Settings, Files, or with fsed_editable_extensions. Do not add binary types to it.

wp-config.php constants

define( 'FSED_KEEP_DATA', true );
define( 'FSED_DISABLE_UPDATE_CHECK', true );

Hooks for developers

All hooks are filters. Settings are applied at priority 5, so your own filters at the default priority 10 override them. The arguments each filter receives are documented in the code comments next to its apply_filters() call.

Files and types

Saving

Trash, zip and updates

Examples

// Allow editing .twig files.
add_filter( 'fsed_editable_extensions', function ( $extensions ) {
    $extensions[] = 'twig';
    return $extensions;
} );

// Keep 50 backups of every file.
add_filter( 'fsed_max_backups', function () {
    return 50;
} );

// Pro: keep deleted items for 90 days.
add_filter( 'fsed_trash_days', function () {
    return 90;
} );

// Pro: leave a folder out of zip downloads.
add_filter( 'fsed_zip_excluded', function ( $names ) {
    $names[] = 'vendor';
    return $names;
} );

Put such code in a small must-use plugin rather than in a theme you edit with FileSmith Editor.

Security model

• Authorization. Every request carries a nonce and passes a capability check (edit_themes or edit_plugins) plus the permission for that specific action.
• Path safety. Every path is validated. Nothing outside the chosen theme or plugin folder can be read or changed, and tricks such as ../ are refused.
• File types. Only text types can be edited, and created in Pro. In Pro, uploads are limited to a safe list, and double extensions such as file.php.jpg are refused. An upload never overwrites an existing file.
• PHP is parsed, never run by the syntax check.
• Backups and trash live in a protected, randomly named folder and use non-executable extensions.
• Output. The interface is built with DOM methods and text content, not raw HTML, so file names and file content cannot inject markup.
• Site test (Pro). Uses a short-lived secret token, only for the two test requests.
• Updates. Free: HTTPS only, from the author's host only, verified with SHA-256 before install. Pro: delivered by Freemius over HTTPS.
• Drafts (Pro) stay in your browser and never reach the server.
• Respects DISALLOW_FILE_EDIT and DISALLOW_FILE_MODS.

To report a security problem, write to the author through the contact page.

Troubleshooting

I cannot see the FileSmith menu

Check that DISALLOW_FILE_EDIT and DISALLOW_FILE_MODS are not set, that your user is an administrator (or has edit_themes or edit_plugins and is allowed in Access control), and that you are a super admin on multisite.

My Editor role cannot see it

The Editor role does not have edit_themes or edit_plugins. FileSmith cannot grant more than WordPress allows. Use a role editor plugin to give those capabilities, then allow the role in Access control.

The file opens read-only

Either the server cannot write to it (fix the permissions or owner) or your account lacks the Edit and save permission.

A save fails with HTTP 403 or 406

A firewall or ModSecurity rule is blocking the code. Ask your host to allow the request, or check the security plugin log. The error message names the status code.

"Your session has expired"

The page security token is older than WordPress allows, usually after leaving the tab open for a day. Copy your work, reload and log in. In Pro, your draft is also kept, see Unsaved-draft recovery.

The site test says it was skipped Pro

The server did not let the site call itself (HTTP 401 or 403 from a password-protected site or a firewall, or a loopback connection error). Allow loopback requests, or leave the test off.

The site test rolled back a change I think is good Pro

The front page or admin-ajax.php failed because of the change, even if the file itself is valid PHP. Read the message it shows. Use fsed_test_save to skip a file.

Format says the formatter library is missing Pro

Make sure assets/js/vendor/beautifier.min.js exists in the plugin folder. Reinstall the plugin zip if it does not.

Quick open or Format shortcuts do nothing

Some browser extensions use Ctrl + P or Shift + Alt + F. Click inside the page first so it has focus, or use the right-click menu for Format.

The file list is empty

The theme or plugin folder may only hold excluded folders or file types the editor does not list. Check Settings, Files. Plugins must live in their own folder.

Backups are missing

A backup is only made when a changed file is saved. Check Backups per file in Settings, and whether other code lowers it with fsed_max_backups.

The zip download fails Pro

The PHP ZipArchive extension must be installed, and the folder must be under the size limit. Raise it with fsed_zip_max_size, or exclude large folders.

The update check says the server could not be reached

Your server cannot reach plugins.wpwebguru.com over HTTPS (free version), or Freemius (Pro). Allow outbound requests, try again later, or update by uploading the new zip.

My site broke even though the syntax check passed

The check only finds parse errors. Use WordPress's recovery mode link (sent to the admin email), restore the file from Backups, or replace it by FTP. In Pro, consider turning on the site test.

Uninstall and data

Deactivating the plugin keeps all data. Deleting it removes the settings, the activity log table (Pro) and the backup folder, unless you add define( 'FSED_KEEP_DATA', true ); to wp-config.php first. Your theme and plugin files are never touched by uninstalling. Drafts live in each user's browser and are not removed by WordPress.

FAQ

Changelog

1.0.0

• Initial release, as a Free and a Pro edition. Features marked Pro in this guide are not in the free edition.
• Editor with tabs, create, upload, rename, move, duplicate and delete.
• Backups with diff and restore, trash, PHP syntax check and zip download.
• Refresh button and changed-on-disk warning before saving.
• Right-click menu, folder icons, fullscreen, tooltips and session restore.
• Image preview, unsaved-draft recovery and download of a single file or folder.
• Editor options (tab size, wrap, line numbers), Format, JSON, JS and CSS checks.
• Optional site test after saving PHP, with automatic rollback.
• Quick open (Ctrl+P) and Compare with disk.
• Detailed save error messages.
• Settings, activity log and access control by role or user.
• Built-in update alerts with one-click update and hash verification (free version). Pro updates through Freemius.

Support

Questions, bug reports and ideas are welcome through the contact page. When you write, include your WordPress and PHP versions, what you did, what you expected, and the exact message shown. Tutorials are at wpwebguru.com.

Download free version 1.0.0 Get Pro