====== User's Guide: WP Code Integrator ====== |[[https://www.heartmindhabits.com/wp/product/wp-code-integrator-pro/|{{:soulsoft:wci_codeintegrator_main.png?200}}]]|Welcome to **[[https://www.heartmindhabits.com/wp/product/wp-code-integrator-pro/|WP Code Integrator (WPCI)]]**. This tool provides a professional, IDE-grade development environment directly inside your WordPress dashboard. It allows you to edit themes and plugins safely using a Visual Studio Code-powered interface with integrated backups and difference comparisons.| ===== 1. The Interface ===== {{:soulsoft:wp_code_integrator_fullview.png?400|}} When you open **Code Integrator**, you are presented with a three-pane layout designed for safety and clarity. * **The Header Bar:** Contains global actions (Save Draft, Jump To, Add/Update Function, Integrate). * //Note: Buttons are disabled until a file is loaded. Save buttons only activate when you make changes.// * **The Left Sidebar:** * **Search:** Quickly find files by name. * **File Actions:** Toolbar for creating files/folders, renaming, and deleting. * **Favorites:** Quick access to frequently used files //and// folders. * **File Tree:** Navigation of your server's file system (restricted to the WordPress root). * **Backups / Revert:** A history of changes and drafts for the currently selected file. * **The Editor Area (Monaco Editor):** * **Visual Diff:** As you type, the editor highlights changes (Green for additions, Red for deletions) in real-time. * **Dirty State:** If you have unsaved changes, the filename in the header will turn **Red and Italic**. ===== 2. File Management & Navigation ===== WPCI allows you to manage your file structure directly from the sidebar. ==== The Context Menu (Right-Click) ==== {{:soulsoft:wp_code_integrator_rightclickmenu_targetfilename.png?400|}} For the fastest workflow, **Right-Click** on any file or folder in the tree to access: * **Target Display:** The top of the menu shows exactly which item you clicked (e.g., //Target: my-script.js//). * **★ Add to Favorites:** Instantly add the item to your favorites list. * **New File / Folder:** Create items inside the selected folder. * **Rename / Delete:** Manage existing items. * **Cancel / Close:** A dedicated option to close the menu (clicking outside the menu also works). ==== Creating & Managing Files ==== You can also use the icons in the sidebar toolbar: * **{{:soulsoft:wp_code_integrator_newfile.png?nolink|}} File:** Creates a new file. If a folder is selected, it creates it there. If a file is selected, it creates it in the same directory. * **{{:soulsoft:wp_code_integrator_newfolder.png?nolink|}} Folder:** Creates a new directory. The system will automatically open and scroll to your new folder. * **{{:soulsoft:wp_code_integrator_favicon.png?nolink|}} Favorite:** You can add any selected file/folder to your Favorites list. * **{{:soulsoft:wp_code_integrator_rename.png?nolink|}} Rename / {{:soulsoft:wp_code_integrator_trash.png?nolink|}} Delete:** Select an item and click the corresponding icon. * //Safety Note:// If you delete a file that is currently open in the editor and/or in your Favorites list, the editor will automatically close and it will be removed from Favorites to prevent "ghost files/editing." ==== Favorites System ==== {{:soulsoft:wp_code_integratorfavoritesarea_unfavoriteaction.png|}} You can favorite both **Files** and **Folders**. * **Files:** Clicking a favorite file loads it immediately. * **Folders:** Clicking a favorite folder navigates the file tree directly to that folder and expands it. * **Unfavorite (Removing):** Click the small **"x" (Trash)** icon next to any favorite item to remove it from the list. ===== 3. Basic Workflow ===== ==== Loading a File ==== - Use the **File Tree** to navigate to your theme or plugin folder. - Click a file name (e.g., ''functions.php'') to load it. - The editor activates, and navigation buttons ("Jump To", "Add Function") become clickable. ==== Editing & Saving ==== {{:soulsoft:wp_code_integrator_confirmsavecancel.png|}} WPCI uses a "Safe Save" flow to prevent accidents. - **Save Draft:** Saves your changes to a temporary file on the server. **This does not affect your live site.** Use this to save work-in-progress safely. - **Integrate (Save):** Overwrites the live file. - Click **Integrate (Save)**. - The button will swap to a red **"Confirm Save?"** button. - Click **Confirm Save?** to commit your changes. - The system creates a backup automatically before writing. ===== 4. Surgical Editing Tools ===== WPCI includes powerful tools to modify code without manually scrolling through thousands of lines. ==== Update Function ==== {{:soulsoft:wp_code_integrator_updatefunc.png?400|}} Replace an existing PHP function with a new version, regardless of its location in the file. - Click **Update Function**. - Paste your **full new function code**. - Ensure **Auto-indent Code** is checked (recommended). - Click **Smart Replace**. The system finds the old function, replaces it, and fixes indentation automatically. Works with these PHP/JavaScript code grouping structures: * Classes: class MyClass { ... } (Handles abstract, final) * Traits: trait MyTrait { ... } * Interfaces: interface MyInterface { ... } * Standard Functions: function myFunction() { ... } (Handles public, static, async, etc.) * JS Arrow/Var Functions: const myFunction = () => { ... } or var myFunc = function() { ... } ==== Add Function ==== {{:soulsoft:wp_code_integrator_addfunc.png?400|}} Insert new code relative to existing structures. - Click **+ Add Function**. - **Select Target:** Choose an existing Class or Function from the list. - **Position:** Select **Above** or **Below**. - Click **Insert Code**. ==== Jump To... ==== {{:soulsoft:wp_code_integrator_jumpto.png?400|}} Click **Jump To...** to see an outline of the current file. Click any function or class name to immediately scroll to that location. ===== 5. Backup & Restoration ===== {{:soulsoft:wp_code_integrator_backupsreverts.png|}} Every time you "Integrate" (Save) a file, WPCI automatically creates a backup version before overwriting your live code. ==== Quick Restore (Single File) ==== If you make a mistake while editing a specific file, you can roll back immediately from the editor sidebar. * **Locate Backup:** Look at the "Backups / Revert" panel in the bottom-left corner. * **Load Version:** Click **[Load]** next to any timestamped entry. * **Visual Check:** The backup content loads into the "Modified" (Right) pane. The editor will highlight the differences between the backup and your current live file, allowing you to verify the restoration before saving. ==== WCI Recovery Console (Bulk Management) ==== {{:soulsoft:wp_code_integrator_wci_recovery_console.png?400|}} For deeper system management, use the included **Recovery Console**. This tool provides a centralized view of all backups created by Code Integrator across your entire WordPress installation. * **Access:** Navigate to **Tools > WCI Recovery** in your WordPress dashboard. * **Audit Trail:** View a master list of every file modified by WPCI, including the file path, backup size, and timestamp. * **Bulk Cleanup:** Select multiple old backups or draft files and delete them in one click to free up server space. * **Emergency Download:** Download backup files directly to your computer for off-site safekeeping or manual inspection. ===== 6. Technical Architecture Overview ===== This section outlines the technical stack and security measures implemented in WP Code Integrator. ^ Component ^ Specification ^ | **Frontend Editor** | **Monaco Editor** (Version 0.44 as of WPCI v11.13). Supports syntax highlighting, code folding, minimaps, and side-by-side diff views. | | **Backend Logic** | **PHP 7.4+**. Object-Oriented architecture. Uses WordPress AJAX API for all server communication. | | **Server Requirements** | WordPress 6.0+, PHP 7.4+. Access to ``ABSPATH`` (root directory) required for file operations. | | **Data Storage** | **Filesystem:** Direct manipulation of PHP/JS/CSS files. \\ **Backups:** Stored in ``wp-content/uploads/wci-backups/`` (protected by ``.htaccess``). \\ **Favorites:** Stored in User Meta (``wci_favorites``). | ==== Security Protocols ==== * **Path Traversal Protection:** All file paths are sanitized via a strict ``resolve_path()`` function that prevents accessing files outside the WordPress root (``ABSPATH``). * **Access Control:** All AJAX endpoints enforce ``current_user_can('administrator')``. * **Nonce Verification:** All requests require a valid WordPress Nonce (``wci_nonce``). * **Backup Isolation:** The backup directory is automatically secured with a ``deny from all`` ``.htaccess`` file to prevent public web access to backup files. ==== Compatibility ==== Code Integrator is designed to run alongside standard WordPress caching plugins. Since it operates entirely within the Admin Dashboard (``is_admin()``), it does not impact frontend performance.