Skip to content

Developer Docs

Hooks & Filters Reference

Hooks & filters reference for Smart Add-Ons — all PHP actions and filters are prefixed with saue_.

Action hooks

Hook nameArgumentsDescription
saue_register_field_types$registry: FieldTypeRegistryFired during plugin boot. Register a custom field type class with the registry.
saue_addon_group_saved$group_id: int, $data: arrayFired after an addon group is created or updated via the REST API. $data contains all group fields.
saue_addon_field_deleted$field_id: intFired after a field row is deleted from an addon group.
saue_before_render_product_addons$product_id: intFired immediately before the storefront renders the addon groups for a product page. Use to inject custom markup or enqueue assets.
saue_integrations_loadednoneFired after all built-in integrations (WPML, Subscriptions, Bookings) have been registered. Use to register your own integration.
saue_bookings_before_product_addons$product_id: intFired specifically for WooCommerce Bookings products before addon groups render.

Filter hooks

Filter nameArgumentsReturn typeDescription
saue_addon_groups_for_product$groups: array, $product_id: intarrayModify, add, or remove the addon groups shown for a specific product. Return the modified $groups array.
saue_addon_field_html$html: string, $field: arraystringCustomize the rendered HTML for a single addon field on the storefront. Return modified HTML string.
saue_translate_string$string: string, $context: stringstringWPML / Polylang / custom translation hook. Called for every user-facing string. Return translated string.
saue_locate_template$path: string, $template: stringstringOverride any plugin template file. Return an absolute file path to your custom template.
saue_subscriptions_addon_groups$groups: array, $product_id: intarrayFilter the addon groups shown for WooCommerce Subscription products specifically.
saue_price_preview_result$result: array, $selections: arrayarrayModify the calculated price preview result before it is returned to the storefront. $result contains total, addons_total, breakdown.
saue_order_item_meta_label$label: string, $field: arraystringChange the label used for addon field values in the order item meta display.
saue_upload_allowed_mime_types$types: array, $field_id: intarrayModify allowed MIME types for a file upload field. Return an array of MIME type strings.

Examples

Register a custom field type

/**
 * Register a custom "Color Swatch" field type.
 * MyColorSwatchFieldType must implement:
 * SmartAddOns\Contracts\FieldTypeInterface
 */
add_action( 'saue_register_field_types', function( $registry ) {
    $registry->register( 'color_swatch', new MyColorSwatchFieldType() );
} );

Add a group to a product programmatically

/**
 * Inject an extra addon group for product ID 42
 * during storefront rendering.
 */
add_filter( 'saue_addon_groups_for_product', function( $groups, $product_id ) {
    if ( $product_id === 42 ) {
        $groups[] = [
            'id'     => 99,
            'label'  => 'VIP Packaging',
            'fields' => [],
        ];
    }
    return $groups;
}, 10, 2 );

Override a template file

/**
 * Load a custom version of the addon group template
 * from the active theme's /saue/ folder.
 */
add_filter( 'saue_locate_template', function( $path, $template ) {
    $theme_file = get_stylesheet_directory() . '/saue/' . $template;
    if ( file_exists( $theme_file ) ) {
        return $theme_file;
    }
    return $path;
}, 10, 2 );

Restrict allowed MIME types for file uploads

/**
 * Allow only PNG and JPG uploads for field ID 5.
 */
add_filter( 'saue_upload_allowed_mime_types', function( $types, $field_id ) {
    if ( $field_id === 5 ) {
        return [ 'image/png', 'image/jpeg' ];
    }
    return $types;
}, 10, 2 );

Translate addon labels with WPML

/**
 * Pass addon strings through WPML translation.
 */
add_filter( 'saue_translate_string', function( $string, $context ) {
    return apply_filters( 'wpml_translate_single_string', $string, 'smart-addons', $context );
}, 10, 2 );

Implementing FieldTypeInterface

A custom field type must implement SmartAddOns\Contracts\FieldTypeInterface. The interface requires:

interface FieldTypeInterface {
    // Machine name: 'color_swatch'
    public function get_type(): string;
    // Human label shown in the admin UI
    public function get_label(): string;
    // Schema for the admin field editor (JSON Schema)
    public function get_schema(): array;
    // Validate a submitted value; throw ValidationException on failure
    public function validate( $value, array $field ): void;
    // Sanitize the value before storing
    public function sanitize( $value, array $field );
    // Render the storefront HTML for this field
    public function render( array $field, $value ): string;
}
Next: REST API Reference →
← Developer Overview