Sandbox

New in v3.7.0. The Sandbox is where code your AI agent generates through the MCP tools actually lives: custom Gutenberg blocks, custom Elementor widgets, and PHP snippets. Everything is isolated under wp-content/emcp-sandbox, never your theme, WordPress core, or another plugin, and every artifact is created inactive. A human has to review and activate it before it runs. That review step is the whole point: the AI never writes raw PHP or JS directly into your site.

AI can only create inactive drafts (3.18.0)

No MCP tool can make a widget, block or snippet live. create-custom-widget, create-custom-block and create-php-snippet always save an inactive draft; the widget and block tools also return a note naming the Sandbox screen where you activate it. set-widget-status and set-block-status accept only draft (to switch an artifact off) and refuse active with a 403 activation_requires_admin error. Cloud pulls, Marketplace installs and bundle imports also land as drafts. Only an administrator activates an artifact, on its Sandbox list. Until then an agent cannot place a custom widget or block, so it should ask you to activate it.

EMCP Tools → Build → Sandbox (admin.php?page=emcp-tools-widgets) opens an overview with three cards (Widgets / PHP Snippets / Blocks), each opening its own list, and an Awaiting your review queue.

Pillar	Tier	What it is
Blocks	Pro	AI-generated custom Gutenberg blocks, compiled from a spec. Active blocks appear in the block editor inserter under “EMCP Custom.” List: &view=blocks.
Widgets	Pro	AI-generated custom Elementor widgets, sandboxed and shown in the panel under “Custom (EMCP).” List: &view=widgets. Tool reference: Widget Builder.
PHP Snippets	Free (capability-gated)	Small PHP snippets an AI agent can draft, run as a shortcode or on a hook, that stay inactive until reviewed. List: &view=snippets.

This page covers the PHP Snippets tools (undocumented elsewhere) and the admin review workflow shared by all three pillars. For creating custom Elementor widgets, see Widget Builder; for custom Gutenberg blocks, the tool reference is below.

PHP Snippets tools

A snippet runs as a shortcode ([emcp_snippet id="N"]), on a WordPress hook, or both. Code is validated on every create/update, and rejected only if it trips a critical finding, the kind that blocks activation outright (eval, file writes, network calls, and similar). create-php-snippet always produces an inactive draft; it never runs until an admin activates it in the Sandbox.

Findings come in three levels (severity on each finding), so routine code doesn’t get lost in noise: critical blocks activation; warning doesn’t block but is worth a reviewer’s attention (writing a site option, sending email); notice is routine and expected in working code (exiting after a redirect, reading request input). Only critical findings stop a snippet from saving or activating; warnings and notices come back alongside a successful save so an agent or reviewer can see them without being blocked by them. On the Sandbox screen the three levels read Must change, Worth a read and Note.

Tool	Purpose
emcp-tools/validate-php-snippet	Dry-run validation, no code is saved.
emcp-tools/create-php-snippet	Create a snippet as an inactive draft.
emcp-tools/update-php-snippet	Update code/settings; re-validates. An active snippet is recompiled, or demoted to draft if it no longer passes.
emcp-tools/get-php-snippet	Return a snippet’s code, settings, and status.
emcp-tools/list-php-snippets	List snippets (id, title, status).
emcp-tools/delete-php-snippet	Delete a snippet.

create-php-snippet / update-php-snippet input:

• title: a label for the snippet.
• code (required on create): PHP code, no <?php tag needed, runs inside an isolated function. Use return or echo for shortcode output.
• context: "shortcode", "hook", or "both". Defaults to shortcode.
• hook: the WordPress action to attach to when context is hook/both (e.g. wp_footer, init).
• priority: hook priority, default 10.

Activation always requires a human, in the Sandbox UI, regardless of who created the draft. There is no activate tool for snippets.

Custom Gutenberg Blocks tools

Same shape as Widget Builder, for the block editor instead of Elementor: the agent submits a JSON spec plus an HTML template with {{control}} placeholders, never raw JS, and the plugin compiles a real block.

Tool	Purpose
emcp-tools/list-block-control-types	List supported attribute types + template syntax, call first.
emcp-tools/validate-block-spec	Dry-run the generator, no code saved.
emcp-tools/create-custom-block	Generate a block as an inactive draft from a spec.
emcp-tools/update-custom-block	Replace a block’s spec, regenerate, re-validate.
emcp-tools/get-custom-block	Return a block’s spec, generated code, and status.
emcp-tools/list-custom-blocks	List generated blocks (id, title, block name, status).
emcp-tools/set-block-status	Return a block to an inactive draft. Accepts only draft; activation happens on the Sandbox screen.
emcp-tools/delete-custom-block	Delete a block (record + sandbox files).

Template syntax matches the Widget Builder: {{attribute_name}} for values, {{#if name}}…{{/if}} for conditionals, {{#each repeater}}…{{/each}} for loops, every value escaped by its declared attribute type. A runtime safety net isolates compile failures, a malformed block is demoted to draft with a recorded error rather than breaking the block editor.

The Sandbox admin screens

Overview and review queue

Each overview card shows how many artifacts are active and how many are inactive / drafts (a free site shows “Requires Pro” on the Widgets and Blocks cards). Click a card to open its list.

Awaiting your review lists every inactive widget, block and snippet, newest first, with who drafted it, when, and the validator summary (“Nothing flagged”, “N ordinary notes” or “N things worth reading”). Review code opens that item’s code drawer on its list. The Sandbox entry in the sidebar shows a badge with the number of drafts the validator flagged, and the Dashboard’s Needs your attention card links here with Review drafts.

The lists

The Widgets, Blocks and PHP Snippets lists share one layout:

• On or off switch: the human review gate. Nothing an agent creates runs until you switch it on here. A PHP snippet asks “Activate this snippet?” first, because it runs real PHP.
• Filter tabs All / Active / Inactive (the snippet list adds Needs reading) and a search box. Lists show 20 items per page.
• View code: inspect the generated PHP, JS and CSS before deciding whether to activate it. Blocks also have Preview, which renders the block on the server with its default values in a sandboxed frame.
• Export: download a .json bundle of the artifact.
• Import bundle: upload a .json bundle exported from another site (or from Export); imports always land as a new inactive draft.
• More actions (the three-dot menu): Cloud and Marketplace actions (below) and Delete, which removes the record and its sandbox files after a confirmation.

The PHP Snippets list also has Add snippet and Edit, which open an editor drawer with a title, Runs as (Shortcode, Hook or Both, with the hook name and priority), the code and the validator findings. Saving there never switches a draft on; an edited active snippet stays active.

Cloud Library and Marketplace

If the EMCP Cloud module is on and this site is connected, each list also gets:

• A Cloud column: “Not in Cloud”, “Synced” (the Cloud copy matches) or “Changed” (edited since it was saved). Refresh cloud status re-checks it.
• Save to Cloud / Update in Cloud in the row menu, and Save all to Cloud above the table: back up artifacts to your EMCP Cloud account.
• Cloud library (marked CROSS-SITE): browse artifacts you’ve saved from any of your connected sites and Import one into the current site, as a new inactive draft to review.
• Publish to Marketplace in the row menu: publish an artifact to the EMCP Marketplace for others to install. Once published, the menu offers Push update to Marketplace (with a “What changed” note, sent for review) and View on Marketplace.

These buttons, and the plain Export / Import bundle buttons above, are calls to MCP tools an agent can also use directly: export-sandbox-artifact / import-sandbox-artifact for the general portable-bundle mechanism (no Cloud connection needed), and cloud-backup / cloud-pull / cloud-marketplace-list / cloud-marketplace-install for the Cloud-connected versions. Full tool reference: EMCP Cloud & Marketplace.

Export as plugin (Pro)

The Export as plugin button on the overview (&view=export, shown while the Sandbox Plugin Export module is on) packages every active widget, block and snippet as a standalone plugin ZIP. Fill in the plugin name, slug, author and version, choose what to include, and click Build and download ZIP. Install the plugin on a site and deactivate EMCP Tools there: the exported plugin stays dormant while EMCP Tools is active and takes over on the next request after it is deactivated. One export can be installed per site. See Export as plugin for what is bundled, API keys and the limits.

Permissions

Creating, updating and deleting any Sandbox artifact requires manage_options plus unfiltered_html, the same bar as site-wide custom code, and so does activating one on the Sandbox screen. Read/validate tools require edit_posts.