How to create your own integration with Automator

How-Tos

1. How to create your own integration with Automator

2. How to create your own trigger with Automator

3. Comparison between 2.x and 3.x Automator code

4. How to create a simple trigger with Automator

5. How to create a simple Automator action

Difficulty: Easy

Creating a custom integration with Automator 3.0 is a lot easier than you might think. To get started, you can download this working sample from our Github repository.

Create a plugin:

Start by creating a new plugin in your dev environment and define your plugin file:

<?php // phpcs:ignore WordPress.Files.FileName.InvalidClassFileName

/**
 * @wordpress-plugin
 * Plugin Name:       Your plugin name
 * Plugin URI:        Your plugin URI
 * Description:       Your plugin description
 * Version:           1.0.0
 * Author:            Author
 * Author URI:        Author URI
 * License:           GPL-3.0+
 * License URI:       http://www.gnu.org/licenses/gpl-3.0.txt
 */

After defining your plugin, create a class:

class My_Example_Integration {

}

new My_Example_Integration();

To register your own integration, Automator requires few things from an external integration:

Integration name
- Example: My Example (What integration name should Recipe UI display for your integration)
Integration code
- MYEX (This is shortcode of your integration and will used with in triggers/actions and class names)
Integration directory path
- Absolute path of your integration so that Automator can read triggers and/or actions

You will now add these properties in the class created in the last step:

class My_Example_Integration {
	/**
	 * @var
	 */
	public $integration_dir;
	/**
	 * @var string
	 */
	public $integration_code = 'MYEX';
	/**
	 * @var string
	 */
	public $directory;
}

new My_Example_Integration();

Automator follows a standard directory structure for its integrations. If you look at Automator’s integrations, you will find following structure:

integration-directory
|_actions
| |_myex_myaction.php
|
|_helpers
| |_myex-helpers.php
|
|_img
| |_myex-icon.svg
|
|_tokens
| |_myex-tokens.php
|
|_triggers
| |_myex-mytrigger.php
|
|_add-my-example-integration.php

Your simple integration may not need all of the files, specially tokens and helpers. They are for more advanced developers and will be discussed in a separate article.

Looking at above directory structure, you are now going to create a new folder called my-example with in your plugin. Depending on your requirement, you will also have to either create actions, triggers or both folders inside my-example directory. If you want to add your custom icon to your integration, you will also create an img directory with in my-example directory.

Once your are done with the last step, you will update your plugin file and following code:

class My_Example_Integration {
	/**
	 * @var
	 */
	public $integration_dir;
	/**
	 * @var string
	 */
	public $integration_code = 'MYEX';
	/**
	 * @var string
	 */
	public $directory;

    public function __construct() {
		$this->directory = __DIR__ . DIRECTORY_SEPARATOR . 'my-example';
		/**
		 * Waiting for the Automator to load.
		 */
		add_action( 'plugins_loaded', array( $this, 'setup_integration' ) );

		/**
		 * Automator loaded. Add this integration.
		 */
		add_action( 'automator_configuration_complete', array( $this, 'add_this_integration' ) );
	}

	/**
	 * Add custom integration to Automator
	 *
	 * @throws Exception
	 */
	public function setup_integration() {
		if ( function_exists( 'automator_add_integration' ) ) {
            // Add my-example directory path for Automator to read and get all your integration files
			$this->integration_dir = automator_add_integration( $this->directory );
		} else {
			trigger_error( 'automator_add_integration() function not found. Please upgrade Uncanny Automator to version 3.0+' ); //phpcs:ignore WordPress.PHP.DevelopmentFunctions.error_log_trigger_error
		}
	}

	/**
	 * Add integration and all related files to Automator so that it shows up under Triggers / Actions
	 *
	 * @return bool|null
	 */
	public function add_this_integration() {
		// validate
		if ( empty( $this->integration_dir ) ) {
			return false;
		}
		if ( empty( $this->integration_code ) ) {
			return false;
		}

        // Add all loaded files in my-example to display in Recipe UI
		automator_add_integration_directory( $this->integration_code, $this->integration_dir );
	}
}

new My_Example_Integration();

At this point, you have set up your plugin and pointed Automator to read your integration directory, but the integration directory has not files yet to display in Recipe UI.

Create your integration file:

Now in your my-example directory, create a new .php file and name it add-my-example-integration.php. Automator expects main integration file to have add- and -integration.php added in it’s filename.

Start this file by adding some basic code, which includes using Automator’s namespace, class and methods.

<?php

use Uncanny_Automator\Recipe;

class Add_My_Example_Integration {
	use Recipe\Integrations;

	public function __construct() {
		$this->setup();
	}

	protected function setup() {
	}

}

Each of the integration file must contain Recipe\Integrations. This will allow you to use Automator’s built in integration methods to define your own integration.

Now, using Automator’s Recipe\Integrations following methods, you’ll define your integration:

$this->set_integration( 'MYEX' ); // Shortcode, it could be MY_EXAMPLE as well
$this->set_name( 'My Example' ); // Integration name to appear on Recipe UI
$this->set_icon( 'my-example.svg' ); // Icon filename
$this->set_icon_path( __DIR__ . '/img/' ); // Path to icon
$this->set_plugin_file_path( dirname( __DIR__ ) . DIRECTORY_SEPARATOR . 'my-example-plugin.php' ); // path to your plugin's main file. This will allow to check if your plugin is active before reading/adding your files in to Automator

Check this link for a complete list of available methods.

Your file will look like this now:

<?php

use Uncanny_Automator\Recipe;

class Add_My_Example_Integration {
	use Recipe\Integrations;

	public function __construct() {
		$this->setup();
	}

	protected function setup() {
		$this->set_integration( 'MYEX' );
		$this->set_name( 'My Example' );
		$this->set_icon( 'my-example-icon.svg' );
		$this->set_icon_path( __DIR__ . '/img/' );
		$this->set_plugin_file_path( dirname( __DIR__ ) . DIRECTORY_SEPARATOR . 'my-example-plugin.php' );
	}

	/**
	 * Explicitly return true because this plugin code will only run if it's active.
	 * Add your own plugin active logic here, for example, check for a specific function exists before integration is
	 * returned as active.
	 *
	 * This is an optional override. By default Uncanny Automator will check $this->get_plugin_file_path() to validate
	 * if plugin is active.
	 *
	 * @return bool
	 */
	public function plugin_active() {
		return true;
	}
}

Once this code is added, your integration is almost setup. To display it in the Recipe UI, you will have to create at least one trigger or an action.

Continue reading: Create a simple trigger…

Difficulty: Easy

Create a plugin:

Create your integration file:

Share This

Related Posts