• File: update-settings-ability.php
  • Full Path: /home/slvgwrnz/public_html/wp-content/plugins/elementor/modules/mcp/abilities/update-settings-ability.php
  • Date Modified: 11/09/2026 10:39 AM
  • File size: 11.76 KB
  • MIME-type: text/x-php
  • Charset: utf-8
<?php

namespace Elementor\Modules\Mcp\Abilities;

use Elementor\Core\Base\Document;
use Elementor\Core\Utils\Document\Document_Mutator;
use Elementor\Modules\Components\Documents\Component as Component_Document;
use Elementor\Modules\Mcp\Abilities\Utils\Document_Mutation_Links;
use Elementor\Modules\Mcp\Abilities\Utils\Document_Mutation_Save;
use Elementor\Modules\Mcp\Abilities\Utils\Document_Revision_Snapshots;
use Elementor\Plugin;

if ( ! defined( 'ABSPATH' ) ) {
	exit;
}

class Update_Settings_Ability extends Abstract_Ability {

	// Post fields that a draft copy of a published document can't carry to the live post on publish.
	const UNSTAGEABLE_SETTINGS = [ 'post_status', 'menu_order', 'comment_status' ];

	const FEATURED_IMAGE_SETTING = 'post_featured_image';

	const EXCERPT_SETTING = 'post_excerpt';

	const TITLE_SETTING = 'post_title';

	const FEATURED_IMAGE_META_KEY = '_thumbnail_id';

	// The autosave snapshots every post field when it is created, so publish-document promotes only the ones listed
	// here and doesn't overwrite live changes made since. Must not start with `_elementor`: `DB::copy_elementor_meta`
	// copies those keys from the autosave to the live post.
	const STAGED_POST_FIELDS_META_KEY = '_mcp_staged_post_fields';

	private ?Document_Mutator $mutator;

	public function __construct( ?Document_Mutator $mutator = null ) {
		$this->mutator = $mutator;
	}

	protected function get_ability_id(): string {
		return 'elementor/update-page-settings';
	}

	public function is_exposed_via_proxy(): bool {
		return false;
	}

	protected function get_definition(): Ability_Definition {
		return new Ability_Definition(
			__( 'Update Elementor Page Settings', 'elementor' ),
			__( 'Updates Elementor document-level settings for a post (for example page layout, title visibility, or custom page settings). Pass only the keys you want to change. Ask the user for the URL or post ID. Use get-page-structure when you also need the element tree. On published documents the change is staged in a draft copy like other MCP edits (staged=true): the live page is unchanged until you call elementor/publish-document, and post_status, menu_order and comment_status cannot be changed there. Requires permission to edit the target post.', 'elementor' ),
			'elementor',
			[
				'type' => 'object',
				'properties' => [
					'success' => [ 'type' => 'boolean' ],
					'post_id' => [ 'type' => 'integer' ],
					'staged' => [
						'type' => 'boolean',
						'description' => 'True when the settings were written to a draft copy of a published document and still need publishing to go live.',
					],
					'preview_url' => Document_Mutation_Links::preview_schema_property(),
					'llm_instructions' => Document_Mutation_Links::llm_instructions_schema_property(),
					'undo_revision_id' => Document_Mutation_Links::undo_revision_id_schema_property(),
				],
			],
			[
				'annotations' => [
					'readonly' => false,
					'idempotent' => false,
					'destructive' => true,
				],
				'mutates_page' => true,
			],
			function () {
				return current_user_can( 'edit_posts' );
			},
			[
				'type' => 'object',
				'required' => [ 'post_id', 'settings' ],
				'properties' => [
					'post_id' => [
						'type' => 'integer',
						'description' => 'WordPress post ID of the Elementor document.',
					],
					'settings' => [
						'type' => 'object',
						'description' => 'Partial document settings object; merged into existing settings. Schema enforcement is delegated to document->save().',
						'additionalProperties' => true,
					],
				],
			]
		);
	}

	public function execute( $input = [] ) {
		$post_id = isset( $input['post_id'] ) ? absint( $input['post_id'] ) : 0;
		$settings = isset( $input['settings'] ) && is_array( $input['settings'] ) ? $input['settings'] : null;

		if ( ! $post_id ) {
			return new \WP_Error( 'invalid_post_id', __( 'A valid post_id is required.', 'elementor' ), [ 'status' => \WP_Http::BAD_REQUEST ] );
		}

		if ( null === $settings ) {
			return new \WP_Error( 'invalid_settings', __( 'The settings object is required.', 'elementor' ), [ 'status' => \WP_Http::BAD_REQUEST ] );
		}

		$document = Plugin::$instance->documents->get( $post_id );

		if ( ! $document ) {
			return new \WP_Error( 'document_not_found', __( 'Document not found.', 'elementor' ), [ 'status' => \WP_Http::NOT_FOUND ] );
		}

		if ( ! $document->is_editable_by_current_user() ) {
			return new \WP_Error( 'rest_cannot_edit', __( 'Sorry, you are not allowed to edit this document.', 'elementor' ), [ 'status' => \WP_Http::FORBIDDEN ] );
		}

		$is_staged = $this->is_live( $document );

		if ( $is_staged ) {
			$stageable_error = $this->validate_stageable_settings( $document, $settings );

			if ( $stageable_error ) {
				return $stageable_error;
			}
		}

		$undo_point = Document_Revision_Snapshots::capture( $document, $this->get_id() );
		$saved = $is_staged ? $this->save_staged( $document, $settings ) : $this->save_live( $document, $settings );

		if ( is_wp_error( $saved ) ) {
			return $saved;
		}

		$response = [
			'success' => true,
			'post_id' => $post_id,
			'staged' => $is_staged,
		] + Document_Mutation_Links::for_document( $document, $this->get_staged_message( $document, $is_staged ) );

		if ( $undo_point ) {
			$undo_point->commit();
			$response = $undo_point->add_to_response( $response );
		}

		return $response;
	}

	private function is_live( Document $document ): bool {
		return in_array( get_post_status( $document->get_main_id() ), Document_Mutator::LIVE_STATUSES, true );
	}

	private function validate_stageable_settings( Document $document, array $settings ): ?\WP_Error {
		$unstageable = array_values( array_intersect( self::UNSTAGEABLE_SETTINGS, array_keys( $settings ) ) );

		if ( $unstageable ) {
			return new \WP_Error(
				'invalid_settings',
				sprintf(
					/* translators: %s: Comma-separated setting keys. */
					__( '%s cannot be changed on a published document, because MCP changes there are staged in a draft copy. Remove these keys and retry. Publish staged changes with elementor/publish-document; change the post status, order or comments in WordPress.', 'elementor' ),
					implode( ', ', $unstageable )
				),
				[ 'status' => \WP_Http::BAD_REQUEST ]
			);
		}

		if ( ! $this->should_stage_featured_image( $document, $settings ) ) {
			return null;
		}

		if ( ! current_user_can( 'publish_posts' ) ) {
			return new \WP_Error( 'rest_cannot_edit', __( 'You do not have permission to modify the featured image.', 'elementor' ), [ 'status' => \WP_Http::FORBIDDEN ] );
		}

		$attachment_id = $this->get_featured_image_id( $settings );

		if ( $attachment_id && ! wp_attachment_is_image( $attachment_id ) ) {
			return new \WP_Error(
				'invalid_settings',
				__( 'post_featured_image.id must be the ID of an image in the media library. Pass an empty id to remove the featured image.', 'elementor' ),
				[ 'status' => \WP_Http::BAD_REQUEST ]
			);
		}

		return null;
	}

	/**
	 * @return bool|\WP_Error
	 */
	private function save_live( Document $document, array $settings ) {
		if ( ! $document->save( [ 'settings' => $settings ] ) ) {
			return new \WP_Error( 'save_failed', __( 'Could not save document settings.', 'elementor' ), [ 'status' => \WP_Http::INTERNAL_SERVER_ERROR ] );
		}

		return true;
	}

	/**
	 * The featured image and excerpt are staged here because core can't write them to an autosave: `set_post_thumbnail`
	 * writes through `update_post_meta`, which redirects revision IDs to the live post, and the excerpt is only saved
	 * when the `revision` post type supports excerpts, which it never does.
	 *
	 * @return Document|\WP_Error
	 */
	private function save_staged( Document $document, array $settings ) {
		$stage_featured_image = $this->should_stage_featured_image( $document, $settings );
		$attachment_id = $this->get_featured_image_id( $settings );
		$excerpt = $this->get_stageable_excerpt( $document, $settings );
		$staged_post_fields = $this->get_staged_post_fields( $settings, $stage_featured_image );
		unset( $settings[ self::FEATURED_IMAGE_SETTING ], $settings[ self::EXCERPT_SETTING ] );

		$target = Document_Mutation_Save::settings_preserving_live_status( $this->get_mutator(), $document, $settings );

		if ( is_wp_error( $target ) ) {
			return $target;
		}

		$target_id = (int) $target->get_post()->ID;

		if ( $stage_featured_image ) {
			$this->stage_featured_image( $target_id, $attachment_id );
		}

		$this->mark_staged_post_fields( $target_id, $staged_post_fields );

		if ( null === $excerpt ) {
			return $target;
		}

		$excerpt_result = $this->stage_excerpt( $target_id, $excerpt );

		if ( is_wp_error( $excerpt_result ) ) {
			return $excerpt_result;
		}

		$this->mark_staged_post_fields( $target_id, [ self::EXCERPT_SETTING ] );

		return $target;
	}

	/**
	 * Core stages a non-empty title on the autosave itself (`Page\Manager::ajax_before_save_settings`).
	 *
	 * @return string[]
	 */
	private function get_staged_post_fields( array $settings, bool $stage_featured_image ): array {
		$fields = [];

		if ( ! empty( $settings[ self::TITLE_SETTING ] ) ) {
			$fields[] = self::TITLE_SETTING;
		}

		if ( $stage_featured_image ) {
			$fields[] = self::FEATURED_IMAGE_SETTING;
		}

		return $fields;
	}

	private function mark_staged_post_fields( int $target_id, array $fields ): void {
		if ( ! $fields ) {
			return;
		}

		$already_staged = (array) get_metadata( 'post', $target_id, self::STAGED_POST_FIELDS_META_KEY, true );

		update_metadata( 'post', $target_id, self::STAGED_POST_FIELDS_META_KEY, array_values( array_unique( array_merge( array_filter( $already_staged ), $fields ) ) ) );
	}

	private function stage_featured_image( int $target_id, int $attachment_id ): void {
		if ( $attachment_id ) {
			update_metadata( 'post', $target_id, self::FEATURED_IMAGE_META_KEY, $attachment_id );

			return;
		}

		delete_metadata( 'post', $target_id, self::FEATURED_IMAGE_META_KEY );
	}

	/**
	 * An empty `page_template` stops `wp_update_post` from re-validating the revision's template, which would
	 * write `default` to the live post.
	 *
	 * @return true|\WP_Error
	 */
	private function stage_excerpt( int $target_id, string $excerpt ) {
		$updated = wp_update_post( wp_slash( [
			'ID' => $target_id,
			'post_excerpt' => $excerpt,
			'page_template' => '',
		] ), true );

		if ( is_wp_error( $updated ) ) {
			return new \WP_Error(
				'save_failed',
				sprintf(
					/* translators: %s: Error message returned by WordPress. */
					__( 'The settings were staged, but post_excerpt could not be saved to the draft copy: %s', 'elementor' ),
					$updated->get_error_message()
				),
				[ 'status' => \WP_Http::INTERNAL_SERVER_ERROR ]
			);
		}

		return true;
	}

	private function get_stageable_excerpt( Document $document, array $settings ): ?string {
		if ( ! isset( $settings[ self::EXCERPT_SETTING ] ) || ! post_type_supports( get_post_type( $document->get_main_id() ), 'excerpt' ) ) {
			return null;
		}

		return (string) $settings[ self::EXCERPT_SETTING ];
	}

	private function should_stage_featured_image( Document $document, array $settings ): bool {
		return isset( $settings[ self::FEATURED_IMAGE_SETTING ] ) && post_type_supports( get_post_type( $document->get_main_id() ), 'thumbnail' );
	}

	private function get_featured_image_id( array $settings ): int {
		return absint( $settings[ self::FEATURED_IMAGE_SETTING ]['id'] ?? 0 );
	}

	private function get_staged_message( Document $document, bool $is_staged ): ?string {
		if ( ! $is_staged ) {
			return null;
		}

		if ( $document instanceof Component_Document ) {
			return __( 'Settings saved to a draft copy of the component. Pages using it are unchanged until you call elementor/manage-component with action=publish.', 'elementor' );
		}

		return __( 'Settings saved to a draft copy. The live page is unchanged until you call elementor/publish-document.', 'elementor' );
	}

	private function get_mutator(): Document_Mutator {
		return $this->mutator ?? Document_Mutator::instance();
	}
}