Best Practices

This documentation provides the best practices for coding when you're creating an add-on for WP All Import.

1. Follow an Object-Oriented design pattern.

You should use a singleton to ensure that your add-on works properly with WP All Import's WP-CLI integration. A singleton is a class that is limited to a single instance.

Example - ensuring a class has only a single instance

static public function get_instance() {
        if ( self::$instance == NULL ) {
            self::$instance = new self();
        }
        return self::$instance;
    }

Be sure to instantiate the Rapid Add-On when the class is constructed:

$this->add_on = new RapidAddon( 'Yoast SEO Add-On', 'yoast_seo_add_on' );

Here's an overview showing how it all fits together:

/*
Plugin Name: WP All Import Yoast SEO Add-On
Description: A complete example add-on for importing data to certain Yoast SEO fields.
Version: 1.0
Author: WP All Import
Text Domain: import-yoast-seo
*/

if (!defined('ABSPATH')) {
    exit; // Exit if accessed directly
}

final class Yoast_SEO_Add_On {

    protected static $instance;
    protected $add_on;
    protected $addon_name = 'Yoast SEO Add-On'; // Define the add-on name
    protected $addon_slug = 'wpai_yoast_seo_add_on'; // Define a unique slug for the add-on

    public static function get_instance() {
        if (self::$instance === null) {
            self::$instance = new self();
        }
        return self::$instance;
    }

    protected function __construct() {
        add_action('init', array($this, 'init'));
    }

    public function init() {
        // Load the text domain for localization
        load_plugin_textdomain('import-yoast-seo', false, dirname(plugin_basename(__FILE__)) . '/languages');

        // Check for required classes and display an admin notice if not found
        if (!class_exists('PMXI_Plugin') || !class_exists('PMXI_RapidAddon')) {
            add_action('admin_notices', function() {
                echo '
' . esc_html__('The Yoast SEO Add-On requires WP All Import Pro to be installed and active.', 'import-yoast-seo') . '
';
            });
            return;
        }

        // Include the 'is_plugin_active' function if it doesn't exist
        if (!function_exists('is_plugin_active')) {
            include_once(ABSPATH . 'wp-admin/includes/plugin.php');
        }

        // Check if the Yoast SEO plugin is active
        if (!is_plugin_active('wordpress-seo/wp-seo.php') && !is_plugin_active('wordpress-seo-premium/wp-seo-premium.php')) {
            add_action('admin_notices', function() {
                echo '
' . esc_html__('The Yoast SEO Add-On requires the Yoast WordPress SEO plugin to be installed and active.', 'import-yoast-seo') . '
';
            });
            return;
        }

        // Initialize the add-on with its name and slug
        $this->add_on = new PMXI_RapidAddon($this->addon_name, $this->addon_slug);
        $this->wpai_setup_fields(); // Add fields to the add-on
        $this->add_on->set_import_function([$this, 'import']); // Set the import function
        $this->add_on->run(); // Run the add-on
    }

    // Define the fields for the import template
    public function wpai_setup_fields() {
        $this->add_on->add_field('yoast_wpseo_title', esc_html__('SEO Title', 'import-yoast-seo'), 'text');
        // Other fields you want to add
    }

    // Import function to handle the actual data import
    public function import($post_id, $data, $import_options, $article) {
        if (empty($article['ID']) || $this->add_on->can_update_meta('_yoast_wpseo_title', $import_options)) {
            update_post_meta($post_id, '_yoast_wpseo_title', sanitize_text_field($data['yoast_wpseo_title']));
        }
        // Other fields you want to add
    }
}

// Initialize the add-on
Yoast_SEO_Add_On::get_instance();

2. Make the add-on run only when necessary.

Your add-on should only run when the user is importing to the theme or post types supported by the add-on.

Otherwise, your add-on’s import function would save data in the database when the user is doing an import that isn’t making use of your add-on.

Specify when your add-on runs using the run function.

This code is placed in the 'init' method, as shown in section 1 above.

Example A – only when certain plugins are active

// This approach is needed when you need one OR another plugin active. 
if ( function_exists('is_plugin_active') ) {
    // Only run this add-on if the free or pro version of the Yoast plugin is active.
    if ( is_plugin_active( 'wordpress-seo/wp-seo.php' ) || is_plugin_active( 'wordpress-seo-premium/wp-seo-premium.php' ) ) {
        $this->add_on->run();
    }
}

// This approach works when you need one or more plugins active at the same time. 
// Only run this add-on if BOTH the premium version of the Yoast plugin and WP All Export are active.
$this->add_on->run(array(
    'plugins' => array( 
        'wordpress-seo-premium/wp-seo-premium.php',
        'wp-all-export/wp-all-export.php'
    )
));

}

Example B – only when importing to “listing” Custom Post Type

$this->add_on->run( 
    array( 
        "post_types" => array( "listing" ),
    ) 
);

Example C – only when “Twenty Fourteen” OR “Twenty Fifteen” themes are activated

 $this->add_on->run(
    array(
        "themes" => array( "Twenty Fourteen", "Twenty Fifteen" )
    )
);

Example D – only when importing to “post” OR “page” Custom Post Type AND when “Max Estate” theme is activated AND when the "Max Estate Helper" plugin is activated

$this->add_on->run( 
    array( 
        "themes" => array( "Max Estate" ), 
        "post_types" => array( "post", "page" ),
        "plugins" => array( "Max Estate Helper" ) 
    ) 
);

Example E – always run the add-on

 $this->add_on->run();

3. Make the add-on respect the user’s “Choose which data to update…” import Settings.

On future runs of the same import, users can choose not to update custom fields, images, and more.

The rapid add-on API supports checking if custom fields or images should be updated.

To do that, use the following methods. These should be placed in the 'import' method, as shown in section 1 above.

Use can_update_meta to see if a Custom Field should be updated

if ( $this->add_on->can_update_meta( '_yoast_wpseo_title', $import_options ) ) {
    // Update the field if the user has allowed it in the import settings.
    update_post_meta( $post_id, '_yoast_wpseo_title', $data['yoast_wpseo_title'] );
}

Use can_update_image to check if the “Images” box is checked

if ( $this->add_on->can_update_image( $import_options ) ) {
    // Retrieve the imported image's URL if images are set to be updated.
    $image_url = wp_get_attachment_url( $data['yoast_wpseo_opengraph-image']['attachment_id'] );

    // Save that image URL to our custom field.
    update_post_meta( $post_id, '_yoast_wpseo_opengraph-image', $image_url );
}

There are more options in the Choose which data to update section, but they are rarely used by add-ons. These options are stored in the $import_options variable, which is passed to the registered import function. If your add-on does advanced things like changing parent posts, menu orders, etc., and you want to support these options, the settings you need to check are stored inside $import_options.

Please note that can_update_image only tells you if the Images box is checked. It doesn’t tell you the settings. If you care, read it from $import_options.

4. Warn the user to install WP All Import.

You can display a dismissible notice warning the user to install WP All Import to use your add-on:

 $this->add_on->admin_notice();

Customize the notice text by passing a string to admin_notice(), i.e.:

$this->add_on->admin_notice(
    'The Yoast WordPress SEO Add-On requires WP All Import Free and the Yoast WordPress SEO plugin.'
);

Add conditions for displaying the admin notice:

$this->add_on->admin_notice(
    // Provide the notice text here. 
    "This Add-On requires WP All Import, the WP All Export Plugin and Twenty Fifteen theme.",
    // This array should contain all of your conditions. 
    array( 
        // Multiple themes and plugins can be required.
        "themes" => array( "Twenty Fifteen" ), 
        "plugins" => array( "wp-all-export/wp-all-export.php" ) 
    ) 
);

5. Use tooltips to explain fields to users, when necessary.

The fifth parameter of the add_field() function can take a string that will be used as a tooltip for the field. This will work for any of the field types.

$this->add_on->add_field( 
    // Field slug.
    'property_price',
    // Field display name. 
    'Price',
    // Field type. 
    'text',
    // Used for nested fields. 
    null,
    // Set your tooltip text here. 
    'Numbers only, no symbols' 
);

6. Add entries to the import log.

The log() function must be placed within the import function.

// Ensure it's either a new record or the settings allow updating images.
if ( empty( $article['ID'] ) || $this->add_on->can_update_image( $import_options ) ) {

    // Retrieve the URL for our image.
    $image_url = wp_get_attachment_url( $data['yoast_wpseo_opengraph-image']['attachment_id'] );

    // Save our image URL as required by Yoast.
    update_post_meta( $post_id, '_yoast_wpseo_opengraph-image', $image_url );

}

7. Disable the default images section if it’s not being used.

This should be placed within the add-on's constructor.

 $this->add_on->disable_default_images();

8. Additional WordPress Guidelines

The following practices are not required but are recommended to make your plugin compliant with a wide range of WordPress guidelines. Adhering to these practices will improve the compatibility, security, and localization of your plugin.

Localization

To make your add-on translatable and accessible to a wider audience, ensure that your plugin is localized. Use the load_plugin_textdomain function to load the text domain for localization.

// Load the text domain for localization
load_plugin_textdomain('import-yoast-seo', false, dirname(plugin_basename(__FILE__)) . '/languages');

Add this in the init method of your add-on class to load the text domain.

Escaping Content

When adding fields to the import template, always use functions like esc_html__ to escape content. This ensures that any HTML entities are properly encoded, protecting against potential XSS attacks.

// Define the fields for the import template
public function wpai_setup_fields() {
    $this->add_on->add_field('yoast_wpseo_title', esc_html__('SEO Title', 'import-yoast-seo'), 'text');
    // Other fields you want to add
}

Sanitizing Data

When handling data import, always sanitize input data before saving it to the database. Use functions like sanitize_text_field to ensure data integrity and security.

// Import function to handle the actual data import
public function import($post_id, $data, $import_options, $article) {
    if (empty($article['ID']) || $this->add_on->can_update_meta('_yoast_wpseo_title', $import_options)) {
        update_post_meta($post_id, '_yoast_wpseo_title', sanitize_text_field($data['yoast_wpseo_title']));
    }
    // Other fields you want to add
}

Related Docs

Learn how to add support for your theme or plugin.

Here's a complete add-on example that you can use as a template.

Show you how to set up and use nested fields in an add-on.