PHP Execution

Page Blocks can execute PHP code embedded in the HTML content. This is an advanced feature that enables dynamic content like database queries, conditional logic, and WordPress function calls directly within a section.

Enabling PHP Execution

In the Gutenberg editor, enable the “Execute PHP code” toggle in the block’s Inspector Controls sidebar panel.

In the visual builder, check the “PHP” checkbox in the code panel toolbar.

How It Works

When a Page Block with PHP execution enabled is rendered, the plugin scans the HTML content for PHP opening tags (<?php and <?=). If PHP tags are found, the content is written to a temporary file in the system’s temp directory and then included via PHP’s include statement. The output is captured via output buffering and returned as the rendered content.

<section class="stats">
    <h2>Site Statistics</h2>
    <p>Total posts: <?php echo wp_count_posts()->publish; ?></p>
    <p>Total users: <?php echo count_users()['total_users']; ?></p>
</section>

The temporary file is deleted immediately after execution, whether the code succeeds or throws an exception.

The plugin uses the temp file + include approach rather than direct code execution. This gives the PHP parser proper file context for error reporting and stack traces.

When PHP Executes

PHP execution happens in two contexts.

Frontend rendering. When a visitor loads the page, PHP code in the section is executed as part of the block’s render callback. This is the primary use case.

Preview rendering. When you request a server-side preview (by toggling phpExec on and editing the section), the AJAX preview endpoint executes the PHP and returns the rendered output.

Permission Model

PHP execution has a two-part permission check.

Default behavior. PHP is allowed to execute if any of these conditions is true.

1. The current user has the manage_options capability (administrators).
2. The request is a frontend page load (not admin, not AJAX, not REST API).

The second condition means PHP code always executes on the frontend for site visitors, regardless of who wrote it. This is because the code has already been reviewed and saved by an administrator.

Custom permission. You can override the permission check with the gt_page_blocks_can_execute_php filter.

// Only allow specific users to trigger PHP execution
add_filter( 'gt_page_blocks_can_execute_php', function( $can_execute, $content ) {
    // Your custom logic here
    return $can_execute;
}, 10, 2 );

When execution is denied. If PHP execution is not allowed (e.g., a non-admin editor previewing the block in the Gutenberg editor), all PHP tags are stripped from the content. The <?php ... ?> and <?= ... ?> blocks are removed entirely, and the remaining HTML is rendered normally.

Error Handling

PHP errors during execution are caught with a try/catch block around a Throwable handler.

• If WP_DEBUG is enabled, errors are output as HTML comments: <!-- Page Block PHP Error: error message -->.
• If WP_DEBUG is off, errors are silently suppressed.
• The temporary file is always cleaned up in the finally block, even if an exception occurs.

Security Considerations

PHP execution is a powerful feature that requires trust. Keep these points in mind.

Only administrators can enable it. The phpExec attribute is saved through Gutenberg’s block system, which respects user capabilities. The permission filter further restricts preview execution to administrators.

Frontend execution is unrestricted by design. Once an administrator saves a Page Block with PHP enabled, the code runs on every frontend page load for all visitors. This is intentional. The admin has reviewed and approved the code.

No sandbox. The PHP code executes in the full WordPress context with access to all WordPress functions, global variables, the database, and the filesystem. There is no sandboxing or restriction on what the PHP code can do.

Use Cases

Common use cases for PHP execution in Page Blocks.

• Displaying dynamic content (post counts, user data, custom queries).
• Conditional content based on user roles or other criteria.
• Calling WordPress template tags and functions.
• Rendering dynamic forms or interactive elements.
• Fetching and displaying data from custom database tables or APIs.

Combining with wpautop

You can enable both PHP execution and WordPress formatting (format/wpautop) on the same section. When both are enabled, PHP is executed first, and then the resulting HTML is passed through the the_content filter. This means your PHP output gets paragraph formatting applied.