Astra_Update_Footer_Builder::execute( array $args )

	public function execute( $args ) {
		if ( ! defined( 'ASTRA_THEME_SETTINGS' ) ) {
			return Astra_Abilities_Response::error(
				__( 'Astra theme is not active.', 'astra' ),
				__( 'Please activate the Astra theme to use this feature.', 'astra' )
			);
		}

		// Check if astra_get_option function exists (required for proper data retrieval).
		if ( ! function_exists( 'astra_get_option' ) || ! function_exists( 'astra_update_option' ) ) {
			return Astra_Abilities_Response::error(
				__( 'Astra theme helper functions not available.', 'astra' ),
				__( 'The astra_get_option and astra_update_option functions are required but not found.', 'astra' )
			);
		}

		$updated          = false;
		$update_messages  = array();
		$detailed_changes = array();

		if ( isset( $args['desktop'] ) && is_array( $args['desktop'] ) ) {
			// Get current desktop structure from database using Astra's helper function.
			$current_desktop_raw = astra_get_option( 'footer-desktop-items', array() );
			if ( ! is_array( $current_desktop_raw ) ) {
				$current_desktop_raw = array();
			}

			$default_desktop = $this->get_default_desktop_structure();
			// Merge current values with defaults to ensure all columns exist.
			$current_desktop = $this->array_merge_recursive_distinct( $default_desktop, $current_desktop_raw );

			$desktop_layout = $this->sanitize_footer_layout( $args['desktop'], 'desktop' );

			$changes = $this->get_layout_changes( $current_desktop, $desktop_layout, 'desktop' );
			if ( ! empty( $changes ) ) {
				$detailed_changes = array_merge( $detailed_changes, $changes );
			}

			$new_desktop = $this->array_merge_recursive_distinct( $current_desktop, $desktop_layout );

			// Update the option using Astra's update method to ensure proper storage.
			astra_update_option( 'footer-desktop-items', $new_desktop );
			$updated           = true;
			$update_messages[] = 'Desktop footer layout updated';
		}

		if ( isset( $args['mobile'] ) && is_array( $args['mobile'] ) ) {
			$current_mobile_raw = astra_get_option( 'footer-mobile-items', array() );
			if ( ! is_array( $current_mobile_raw ) ) {
				$current_mobile_raw = array();
			}

			// Initialize default mobile structure with all columns to prevent data loss during merge.
			$default_mobile = $this->get_default_mobile_structure();
			$current_mobile = $this->array_merge_recursive_distinct( $default_mobile, $current_mobile_raw );

			$mobile_layout = $this->sanitize_footer_layout( $args['mobile'], 'mobile' );

			$changes = $this->get_layout_changes( $current_mobile, $mobile_layout, 'mobile' );
			if ( ! empty( $changes ) ) {
				$detailed_changes = array_merge( $detailed_changes, $changes );
			}

			// Merge current with new layout to get final result.
			$new_mobile = $this->array_merge_recursive_distinct( $current_mobile, $mobile_layout );

			astra_update_option( 'footer-mobile-items', $new_mobile );
			$updated           = true;
			$update_messages[] = 'Mobile footer layout updated';
		}

		if ( isset( $args['above_footer_columns'] ) ) {
			$columns = absint( $args['above_footer_columns'] );
			if ( $columns < 1 || $columns > 5 ) {
				return Astra_Abilities_Response::error(
					/* translators: %d: column count */
					sprintf( __( 'Invalid above_footer_columns: %d.', 'astra' ), $columns ),
					__( 'Value must be between 1 and 5.', 'astra' )
				);
			}
			astra_update_option( 'hba-footer-column', (string) $columns );
			$updated = true;
			/* translators: %d: column count */
			$update_messages[] = sprintf( __( 'Above footer columns set to %d', 'astra' ), $columns );
		}

		if ( isset( $args['primary_footer_columns'] ) ) {
			$columns = absint( $args['primary_footer_columns'] );
			if ( $columns < 1 || $columns > 5 ) {
				return Astra_Abilities_Response::error(
					/* translators: %d: column count */
					sprintf( __( 'Invalid primary_footer_columns: %d.', 'astra' ), $columns ),
					__( 'Value must be between 1 and 5.', 'astra' )
				);
			}
			astra_update_option( 'hb-footer-column', (string) $columns );
			$updated = true;
			/* translators: %d: column count */
			$update_messages[] = sprintf( __( 'Primary footer columns set to %d', 'astra' ), $columns );
		}

		if ( isset( $args['below_footer_columns'] ) ) {
			$columns = absint( $args['below_footer_columns'] );
			if ( $columns < 1 || $columns > 5 ) {
				return Astra_Abilities_Response::error(
					/* translators: %d: column count */
					sprintf( __( 'Invalid below_footer_columns: %d.', 'astra' ), $columns ),
					__( 'Value must be between 1 and 5.', 'astra' )
				);
			}
			astra_update_option( 'hbb-footer-column', (string) $columns );
			$updated = true;
			/* translators: %d: column count */
			$update_messages[] = sprintf( __( 'Below footer columns set to %d', 'astra' ), $columns );
		}

		if ( isset( $args['above_footer_layout'] ) && ! empty( $args['above_footer_layout'] ) ) {
			$layout        = sanitize_text_field( $args['above_footer_layout'] );
			$valid_layouts = array( 'full', 'content' );
			if ( ! in_array( $layout, $valid_layouts, true ) ) {
				return Astra_Abilities_Response::error(
					/* translators: %s: layout value */
					sprintf( __( 'Invalid above_footer_layout: %s.', 'astra' ), $layout ),
					__( 'Valid options: full, content', 'astra' )
				);
			}
			astra_update_option( 'hba-footer-layout', $layout );
			$updated = true;
			/* translators: %s: layout value */
			$update_messages[] = sprintf( __( 'Above footer layout set to %s', 'astra' ), $layout );
		}

		if ( isset( $args['primary_footer_layout'] ) && ! empty( $args['primary_footer_layout'] ) ) {
			$layout        = sanitize_text_field( $args['primary_footer_layout'] );
			$valid_layouts = array( 'full', 'content' );
			if ( ! in_array( $layout, $valid_layouts, true ) ) {
				return Astra_Abilities_Response::error(
					/* translators: %s: layout value */
					sprintf( __( 'Invalid primary_footer_layout: %s.', 'astra' ), $layout ),
					__( 'Valid options: full, content', 'astra' )
				);
			}
			astra_update_option( 'hb-footer-layout', $layout );
			$updated = true;
			/* translators: %s: layout value */
			$update_messages[] = sprintf( __( 'Primary footer layout set to %s', 'astra' ), $layout );
		}

		if ( isset( $args['below_footer_layout'] ) && ! empty( $args['below_footer_layout'] ) ) {
			$layout        = sanitize_text_field( $args['below_footer_layout'] );
			$valid_layouts = array( 'full', 'content' );
			if ( ! in_array( $layout, $valid_layouts, true ) ) {
				return Astra_Abilities_Response::error(
					/* translators: %s: layout value */
					sprintf( __( 'Invalid below_footer_layout: %s.', 'astra' ), $layout ),
					__( 'Valid options: full, content', 'astra' )
				);
			}
			astra_update_option( 'hbb-footer-layout', $layout );
			$updated = true;
			/* translators: %s: layout value */
			$update_messages[] = sprintf( __( 'Below footer layout set to %s', 'astra' ), $layout );
		}

		if ( ! $updated ) {
			return Astra_Abilities_Response::error(
				__( 'No changes specified.', 'astra' ),
				__( 'Please provide at least one setting to update.', 'astra' )
			);
		}

		// Build detailed message.
		$message = implode( ', ', $update_messages ) . '.';
		if ( ! empty( $detailed_changes ) ) {
			$message .= ' Details: ' . implode( '; ', $detailed_changes ) . '.';
		}

		return Astra_Abilities_Response::success(
			$message,
			array(
				'updated' => true,
				'changes' => $detailed_changes,
			)
		);
	}