3. Hustle Providers API Doc
If you want to create your own provider for Hustle, we create three main classes to make it easier for you. You can extend those classes and add the necessary methods or properties. Then Hustle will show it as a new provider on the plugin UI.
For your new provider core properties and global settings, you need to extend Hustle_Provider_Abstract class. For provider module settings you need to extend Hustle_Provider_Form_Settings_Abstract class. And lastly, you need to extend Hustle_Provider_Form_Hooks_Abstract class to specify the provider’s actions to be performed along with the plugin’s flow.
You can find all the necessary classes, properties and methods below and each of them has examples too.
3.1 Register Provider
Copy chapter anchor to clipboardDescription
This method is used for registering your integration into Hustle’s framework. This is the first step toward integrating your script. No validation has been done until this point. Because of that, it’s possible that an integration registered with this method ends up not being included in Hustle if the requirements are not met.
The available integrations will show up on “Email collection services” from modules.
Usage
Hustle_Providers::get_instance()->register( $class_name );
Parameters
Return
Boolean.
TRUE => If registered successfully.
FALSE => If registration failed.
Registration will fail if:
- The class name passed on $class_name does not exist.
- The registered class is not an instance of “Hustle_Provider_Abstract” class.
- The registered class does not have a “_slug” property.
- The registered class does not have a “_version” property.
- The registered class does not have a “_title” property.
- The registered class does not have a “_class” property.
- The provider’s method “check_is_compatible” returns false.
- The registered class has the same slug as another registered integration.
See “Hustle_Provider_Abstract” class section for more information about the existing methods, properties, and requirements.
Example
3.2 Class: Hustle_Provider_Abstract
Copy chapter anchor to clipboardDescription
This class is the provider’s core and it’s required. What this class does:
-Defines the provider’s base properties such as the slug, title, version, etc.
-Sets the conditions for loading within Hustle, like the minimum PHP and Hustle versions, and customized checks.
-Handles the provider’s global settings.
Example
3.2.1 Properties: Provider
Link to chapter 2Description
These are the useful properties for you within Hustle_Provider_Abstract class. Some of them must be defined on the integration in order to be properly loaded.
Properties to be defined
Required
Protected
Required
Protected
Required
Protected
Required
Protected
Default: 3.0.5
Optional
Protected Static
Optional
Protected
Optional
Protected
Optional
Protected
Default: false
Optional
Protected
Default: false
Optional
Protected
Optional
Protected
Optional
Protected
Default: [‘api_key’]
3.2.2 Methods to Define: Provider
Link to chapter 2Description
This is a required method. It is used by Hustle to get an instance of your provider class.
Usage
Used by Hustle to get an instance of the provider.
Parameters
This method doesn’t have any parameters.
Return
Object. An instance of your provider class.
Example
Description
Optional.
This method checks if the provider meets the requirements to be instantiated. If the provider is not compatible, it won’t be instantiated. Instantiating a not compatible provider may trigger PHP errors. By default, it will return false if:
– The installed PHP version is lower than the required by your integration.
– The installed Hustle version is lower than the required by your integration.
Usage
Used by Hustle when filtering out the providers that should not be loaded.
Override this method if you have another logic for checking if your integration is compatible.
Parameters
Return
Boolean.
TRUE => If the integration is compatible. Everything is good, proceed with the load.
FALSE => If the integration is not compatible. Don’t proceed with the load. Don’t instantiate the integration.
Example
Description
Optional.
This method is called by is_activable() to verify if the integration can be activated. The final validation of the integration is done on this step. If it passes, it will be listed on Hustle.
By default, this method will return false if the method check_is_compatible() returns False. No other validation is done on this step. In the standard Hustle workflow, this method is not even called if check_is_compatible() returns False because that validation is done first and prevents the integration from being instantiated and included.
Usage
Used by Hustle when filtering out the providers that should not be loaded. Override it if there are other variables you would like to check so your integration runs properly, such as the existence of required third-party plugins, for example.
Parameters
It doesn’t have any parameters.
Return
TRUE => If the integration is activable.
FALSE=> If the integration is not activable.
If not overridden, this method will return false if the method check_is_compatible() returns false. No other validation is done here.
Example
Description
Optional.
This method is called to check if the integration has settings to be displayed. It returns false when the request is not made on the admin side, and it checks if the current array of settings is valid.
Usage
Used by Hustle to define whether your integration has a valid settings wizard to be displayed.
Override it if you want to do some extra checks to hide or show the provider’s module settings.
Parameters
It doesn’t have any parameters.
Return
TRUE => If form settings are available.
FALSE => If form settings are not available.
If not overridden, the method will return false if:
is_admin() returns false.
The property $_form_settings is null.
The class instantiated by $_form_settings class name is not an instance of Hustle_Provider_Form_Settings_Abstract.
The settings steps defined in the integration’s settings is not a valid array.
The number of steps defined in the integration’s settings is less than 1.
See “Hustle_Provider_Form_Settings_Abstract” class section for more information about the existing methods, properties, and requirements.
Example
Description
Optional.
Similar to “Husle_Provider_Form_Settings_Abstract::form_settings_wizaard()”, but for global settings. With this method, you will be able to display a form with settings for users to configure your integration in global settings. On these settings is where you allow users to save their API key, webhook URL, or anything you want to be accessible for your provider along with all the modules. This method is used by Hustle to get the settings from your integration to be displayed on each step and to get the values to be stored after submission.
Usage
Used by Hustle when getting the settings to be displayed and saving their values.
Override it if your integration has global configurations to set up.
Parameters
It doesn’t have any parameters.
Return
It must return an array. This array must contain one array for each settings step.
Each step must contain two key => value pairs.
One key must be named “callback”. Its value should be an array to be used as the first argument for call_user_func() function.
The other key must be named “is_completed”. Its value should be an array to be used as the first argument for call_user_func() function.
The array might contain the number of steps your integration requires.
Example
3.2.3 Methods to Use: Provider
Link to chapter 2Description
Helper. Get the current global data for integration. Receives an array with the name of the setting to retrieve and it’s a default value, and another array with the submitted data. If the setting is not in the submitted data, this function will retrieve it from the stored settings. The defaults will be used if the setting wasn’t found. Handles the stored settings for global multi-instances if the property $is_multi_on_global is set to “true”.
Usage
Use it to retrieve a merge of your provider’s stored global settings, with the submitted values, and defaults as a fallback.
Parameters
Return
Associative array. The settings names will be the keys, and their stored value will be the value of the pair.
Example
Description
Get the stored global settings for this provider.
Usage
Use it to retrieve the stored settings of your provider.
Parameters
It doesn’t have any parameters.
Return
Associative array.
Example
Description
Helper. Get the requested global settings for this provider, given the setting name and the global instance ID if needed.
Uses “Hustle_Provider_Abstract::get_settings_values()”.
Usage
Use it to retrieve the global stored setting of your provider.
Parameters
Return
Mixed.
Example
Description
Saves the given array as the provider’s global settings. If your provider allows global multi-instances, you can use the helper method “Hustle_Provider_Abstract::save_multi_settings_values()”.
Usage
Use it to save the given array as your provider’s global settings.
Parameters
Return
There’s nothing to return.
Example
Description
Helper. Saves the given array as the provider’s settings for the given global multi-instance ID.
Uses “Hustle_Provider_Abstract::save_settings_values()”.
Usage
Use it to save the given array as your provider’s settings for the given global multi-instance ID.
Parameters
Return
There’s nothing to return.
Example
Description
For providers supporting multi-instances on modules. Checks whether a module instance of your provider was successfully set up.
Usage
Used by Hustle to check if an instance of your provider was successfully configured.
Override it to set the condition that flags your provider’s instance as “completed”.
Parameters
Return
Boolean.
Example
Description
Verify if the global instance of the provider has been successfully connected. It checks if the settings defined in “Hustle_Provider_Abstract::$_completion_options” are stored and aren’t empty.
Usage
Use it to check if your provider is globally connected.
Overwrite it if the validation you require is different than the default one.
Parameters
Return
Boolean.
Example
Description
Helper. Return the submitted global_id if passed in the given array, or generates a new one if none was submitted.
Usage
Only for when your provider supports multiple global instances. Use it to get the global ID instance when displaying wizards.
Parameters
Return
String
Example
3.3 Class: Hustle_Provider_Form_Settings_Abstract
Copy chapter anchor to clipboardDescription
Extend this class to create the settings for your integration.
Example
3.3.1 Properties: Form Settings
Link to chapter 3Description
Useful properties for your integration within Hustle_Provider_Form_Settings_Abstract class.
Properties to be used
Protected
Protected
Protected
3.3.2 Methods to Define: Form Settings
Link to chapter 3Description
Optional
This method is used to initialize the integration’s settings. If overridden, call the parent constructor function. If your integration requires an external file that might not be compatible with the current PHP or Hustle version and might cause errors if included in those cases, this is a good place to include it.
Hustle will check if the current PHP and Hustle installations are compatible with your provider before instantiating it.
Usage
Used by Hustle when instantiating the class. Extend this method if you want to do anything during the instantiation. If you’re extending this method, make sure to call the parent’s constructor.
Parameters
Return
There’s nothing to return.
Example
Description
Optional.
With this method, you will be able to display a form with settings for users to configure your integration. On these settings is where you allow users to save their API key, email list name, webhook URL, or anything your integration requires to work properly. This method is used by Hustle to get the settings from your integration to be displayed on each step and to get the values to be stored after submission.
Usage
Used by Hustle when getting the settings to be displayed and saving their values.
Override this method to define the module’s settings wizard.
Parameters
It doesn’t have any parameters.
Return
It must return an array. This array must contain one array for each settings step.
- Each step must contain two key => value pairs.
- One key must be named “callback”. Its value should be an array to be used as the first argument for call_user_func() function.
- The other key must be named “is_completed”. Its value should be an array to be used as the first argument for call_user_func() function.
- The array might contain the number of steps your integration requires.
Below is explained how each of these two functions works.
Example
Description
You can name this method as you wish, as long as it’s properly defined at Hustle_Provider_Abstract::form_settings_wizards() method. This method handles the wizard steps by returning an array of key => value pairs.
Usage
Used by Hustle when retrieving the settings to be shown and the data to be saved.
Override it to set the wizard steps for your integrations.
Parameters
Return
Associative array. It will handle the current step of settings. These are the expected keys and values:
- ‘html’ => String. HTML markup of what’s inside the form for the current step.
- ‘buttons’ => Array. It must contain an array for each “next” and “previous” button with its markup. If the helper functions are not used to get the markup, make sure your “Previous” button has the class “hustle-provider-prev”, and your “Next” button has the class. “hustle-provider-next” so the pagination works as expected.
- ‘has_errors’ => Boolean. If true, the wizard will stay on the current step when the user clicks on the “next” button. Errors messages are shown.
- ‘is_close’ => Boolean. If true, no settings will be shown and the modal will close. Useful when applying conditionals between steps. For example, when the setting required for the 4th step is optional and it’s not selected, simply set “is_close” as true in order to close the modal when arriving at this step under these conditions.
Example
Description
You can name this method as you wish, as long as it’s properly defined at form_settings_wizards() method.
This method is called when moving from one step to the following one. That is after the current step validation has been done and approved, and before the following step’s callback is called. This will check the previous steps have been completed before proceeding. If false, the previous step will be shown.
Usage
Used by Hustle when moving forward on the integration’s settings wizard.
Parameters
Return
Boolean.
TRUE => If the step is completed.
FALSE => If the step is not completed.
Example
3.3.3 Methods to Use: Form Settings
Link to chapter 3Description
Helper. Get the current module settings for the integration. Receives an array with the name of the settings to retrieve and it’s a default value, and another array with the submitted data. If the setting is not in the submitted data, this function will retrieve it from the stored settings. The defaults will be used if the setting wasn’t found. Handles the stored settings for multi-instances if the property $is_multi_on_form is set to “true”.
Usage
Use it to retrieve a merge of your provider’s stored module settings, with the submitted values, and defaults as a fallback.
Parameters
Return
Associative array. The settings names will be the keys, and their stored value will be the value of the pair.
Example
Description
Retrieve the stored module settings of your provider.
Usage
Use it to retrieve the stored module settings of your provider.
Parameters
Default: true.
Return
Array
Example
Description
Saves the given array as the provider’s module settings. If your provider allows multi-instances on modules, you can use the helper method “Hustle_Provider_Form_Settings_Abstract::save_form_multi_id_settings_values()”.
Usage
Use it to save the given array as your provider’s module settings.
Parameters
Return
There’s nothing to return.
Example
Description
Helper. Saves the given array as the provider’s settings for the given global multi-instance ID.
Uses “Hustle_Provider_Form_Settings_Abstract::save_form_settings_values()”.
Usage
Use it to save the given array as your provider’s settings for the given global multi-instance ID.
Parameters
Return
There’s nothing to return.
Example
3.4 Class: Hustle_Provider_Form_Hooks_Abstract
Copy chapter anchor to clipboardDescription
Extend this class to perform actions on your provider’s side when certain actions happen in Hustle’s side. What this class does:
-Adds custom fields to the frontend form.
-Performs a validation to data submitted from the frontend, and makes the submission fail if needed.
-Sends the data submitted by frontend users to your provider’s API.
-Lets the admin know about the status of the subscription (or any action) done by the form submission in the Emails lists global page.
Example
3.4.1 Properties: Form Hooks
Link to chapter 4Description
These are the useful properties for you within Hustle_Provider_Form_Hooks_Abstract class.
Properties to be defined
Assign the class’ constant “ALREADY_SUBSCRIBED_ERROR” to use the shared error for when an email is already subscribed.
-Default: ‘’.
-protected
Properties to be used
3.4.2 Methods to Define: Form Hooks
Link to chapter 4Description
Optional.
Define the validation your provider need. Make the whole form of submission fail if required. Set a string to the property Hustle_Provider_Form_Hooks_Abstract::_submit_form_error_message to display this message in frontend.
Usage
Called by Hustle on form submission to run a validation done by providers. For extending. Extend it to apply your own validation. Ignore if you don’t need to make the submission fail under any condition.
Parameters
Return
True on success. Anything else on failure.
Example
Description
Required.
Extend this method to connect Hustle with your API. This method is called on form submission after the validation from all providers was done and there weren’t errors. Optionally, you can add data related to the request to the current entry (this is each submission you see on the Emails Lists page). See Hustle_Provider_Form_Hooks_Abstract::on_entry_render() on how to actually display it.
Usage
Called by Hustle after the form submission was done and all validations were successfully passed. Extend it to send your data to your API, and optionally store data in the current entry.
Parameters
Return
Array. It must be a multi-array with this format, or will be ignored otherwise:
array(
‘name’ => NAME,
‘value’ => VALUE’, => can be an array/object/scalar, it will be serialized on storage.
),
array(
‘name’ => NAME,
‘value’ => VALUE’
)
Example
Description
Optional.
Display the data from when your provider connected to its API on the Emails List page.
Usage
Called by Hustle when rendering the module’s submissions on the Emails List page. Extend this method to display the data you stored on Hustle_Provider_Form_Hooks_Abstract::add_entry_fields() on the entries’ details from the Emails List page. You might not need to extend the base method if your provider already stores what’s used in there.
Parameters
Return
Array. It must be a multi-array with this format, or will be ignored otherwise:
array(
‘name’ => NAME,
‘value’ => VALUE’, => its output is on html mode, so you can do styling. Don’t forget to escape!
),
array(
‘name’ => NAME,
‘value’ => VALUE’
)
Example
Description
Optional.
Display custom fields in the frontend form.
Usage
Called by Hustle after the core form’s fields are retrieved. Extend this method to add form fields to the frontend form.
Parameters
Return
String. The HTML code to be added after the core form’s fields.
Example
3.5 Helper Functions
Copy chapter anchor to clipboardDescription
Use Hustle’s options template to get the HTML for the given array of options.
Usage
hustle_get_html_for_options( $options );
Parameters
Return
String with the markup.
Example
Description
Retrieve the markup for the title of the provider’s modal.
Usage
hustle_get_integration_modal_title_markup( $options );
Parameters
Default: ‘’.
Default: ‘’.
Default: ‘’.
Return
String with the markup.
Example
Description
Retrieve the markup for the buttons of the provider’s modal.
Usage
hustle_get_provider_button_markup( $options );
Parameters
Default: ‘’.
Default: ‘’.
Possible values: next|prev|close|connect|disconnect|disconnect_form.
Default: ‘’.
Default: ‘’.
Default: ‘’.
Return
String with the markup.
Example
Description
Add an entry to the debug.log file. For that to happen the constants “WP_DEBUG”, “HUSTLE_DEBUG”, and “HUSTLE_PROVIDER_DEBUG” must be defined and set to true.
Usage
hustle_provider_maybe_log( $error_data );
Parameters
This function grabs all the function’s arguments so the number of parameters is only limited by the “func_get_args()” function. Also, the resulting array is JSON encoded to be printed as a string.
Return
There’s nothing to return.
Example
3.6 Get Support
Copy chapter anchor to clipboardIf you still have questions or need assistance after reading this document, please don’t hesitate to contact our support superheroes using the available options under the Support tab in your Hub or via the Support tab in your WPMU DEV Dashboard.
