Docs

Filters and Actions

3 min readUpdated October 19, 2026

All hooks start with nahnu_spf_. Add them in your theme’s functions.php or a small plugin.

Field and label#

HookReceivesUse it to
nahnu_spf_field_label$labelChange the Phone number label.
nahnu_spf_fields$fieldsChange which checkout phone fields are set up.
nahnu_spf_field_args$argsChange every field made with the shortcode or nahnu_spf_field().
nahnu_spf_selectors$selectorsAdd CSS selectors of inputs to set up automatically, e.g. array( '#my_phone' ). The script then loads on every page.
nahnu_spf_load_api$loadLoad the script on the current page (true or false).
nahnu_spf_api_config$configChange the settings passed to the script.
nahnu_spf_account_phone$enabledTurn the My Account phone field on or off.
nahnu_spf_admin_order_phone$enabledTurn the admin order phone field on or off.

Countries#

HookReceivesUse it to
nahnu_spf_preferred_countries$countriesSet the preferred countries (lowercase codes).
nahnu_spf_only_countries$countriesSet the Show only list.
nahnu_spf_exclude_countries$countriesSet the Hide list.
nahnu_spf_countries_list$countriesChange the full country list.

Number checking and display#

HookReceivesUse it to
nahnu_spf_validate_number$enabledTurn number checking on or off.
nahnu_spf_phone_is_valid$valid, $value, $countryChange whether a number passes the server check.
nahnu_spf_check_result$result, $phone, $countryChange the result of nahnu_spf_check(), form plugin checks and the REST check.
nahnu_spf_readable_phone$enabledTurn readable numbers on or off.
nahnu_spf_display_phone$formatted, $phoneChange how a number is shown in emails and on order pages.

Location#

HookReceivesUse it to
nahnu_spf_detect_country$enabledTurn location detection on or off.
nahnu_spf_detected_location$result, $ipChange the detected country and state.
nahnu_spf_detected_country$countryChange the country sent to the field.
nahnu_spf_fill_state$enabledTurn state pre-fill on or off.
nahnu_spf_client_ip_headers$headersChange the headers read for the visitor’s real IP.
nahnu_spf_cdn_country_headers$headersChange the CDN headers read for the country.
nahnu_spf_cdn_state_headers$headersChange the CDN headers read for the state.
nahnu_spf_geo_cache_ttl$secondsHow long a visitor’s location is remembered. Default one day.
nahnu_spf_geo_wait$msLongest wait before a field starts on the fallback country. Default 2000.
nahnu_spf_geo_timeout$secondsTimeout for an outside API call, in seconds. Default 3.
nahnu_spf_geo_rate_limit$limit, $ipAPI lookups allowed per visitor IP per hour. Default 5.
nahnu_spf_geo_global_rate_limit$limit, $ipAPI lookups allowed site-wide per hour. Default 1000.

WhatsApp button#

HookReceivesUse it to
nahnu_spf_whatsapp_button$show, $order, $phone, $countryShow or hide the button.
nahnu_spf_whatsapp_message$message, $orderChange the starting message. Return '' for none.
nahnu_spf_whatsapp_url$url, $order, $digitsChange the full link.

REST endpoint#

HookReceivesUse it to
nahnu_spf_rest_enabled$enabledTurn the REST check off. Default true.
nahnu_spf_rest_permission$allowedLimit who can use it. Default true.

Admin#

HookReceivesUse it to
nahnu_spf_sections$sectionsAdd settings tabs.
nahnu_spf_after_settings_section (action)$section_idAdd content after a settings section.
nahnu_spf_menu_name$nameChange the admin menu name.
nahnu_spf_menu_icon$iconMenu icon when there’s no WooCommerce: a Dashicons class, image URL or SVG data URI. Default dashicons-smartphone.
nahnu_spf_menu_position$positionMenu position when there’s no WooCommerce. Default 58.

Form plugin integrations#

HookReceivesUse it to
nahnu_spf_register_integrations (action)$integrationsRegister your own integration.
nahnu_spf_builtin_integrations$classesRemove a built-in integration completely.
nahnu_spf_integration_enabled$enabled, $idSwitch an integration on or off in code.
nahnu_spf_integrations_loaded (action)$integrationsRun code after integrations have started.

Add support for another form plugin#

Extend Nahnu\SmartPhoneField\Integrations\Forms\FormIntegration and register it. Your integration gets an on/off switch on the Integrations tab. It’s off until the site owner turns it on, unless is_enabled_by_default() returns true.

add_action( 'nahnu_spf_register_integrations', function ( $integrations ) {
    $integrations->register( new Acme_Forms_Phone() );
} );

class Acme_Forms_Phone extends \Nahnu\SmartPhoneField\Integrations\Forms\FormIntegration {
    public function get_id(): string { return 'acme-forms'; }
    public function get_name(): string { return 'Acme Forms'; }
    public function is_available(): bool { return defined( 'ACME_FORMS_VERSION' ); }

    // Phone inputs the script sets up, and options for them.
    public function get_selectors(): array { return array( '.acme-form input[type="tel"]' ); }
    public function get_field_options(): array { return array( 'hiddenInput' => true ); }

    // Load the script on pages with a form.
    public function load_on_page(): bool {
        return is_singular() && has_shortcode( get_post()->post_content ?? '', 'acme_form' );
    }

    // Check the number on the server.
    public function init(): void {
        add_filter( 'acme_forms_validate_phone', function ( $error, $value ) {
            $result = $this->check( (string) $value );
            return $result['valid'] || $result['empty'] ? $error : $result['message'];
        }, 10, 2 );
    }
}
Code
add_action( 'nahnu_spf_register_integrations', function ( $integrations ) {
    $integrations->register( new Acme_Forms_Phone() );
} );

class Acme_Forms_Phone extends \Nahnu\SmartPhoneField\Integrations\Forms\FormIntegration {
    public function get_id(): string { return 'acme-forms'; }
    public function get_name(): string { return 'Acme Forms'; }
    public function is_available(): bool { return defined( 'ACME_FORMS_VERSION' ); }

    // Phone inputs the script sets up, and options for them.
    public function get_selectors(): array { return array( '.acme-form input[type="tel"]' ); }
    public function get_field_options(): array { return array( 'hiddenInput' => true ); }

    // Load the script on pages with a form.
    public function load_on_page(): bool {
        return is_singular() && has_shortcode( get_post()->post_content ?? '', 'acme_form' );
    }

    // Check the number on the server.
    public function init(): void {
        add_filter( 'acme_forms_validate_phone', function ( $error, $value ) {
            $result = $this->check( (string) $value );
            return $result['valid'] || $result['empty'] ? $error : $result['message'];
        }, 10, 2 );
    }
}

Optional methods: get_description() and is_enabled_by_default(). The built-in Contact Form 7 and Fluent Forms integrations in includes/Integrations/Forms/ are working examples.

This website uses cookies to enhance your browsing experience and ensure the site functions properly. By continuing to use this site, you acknowledge and accept our use of cookies.

Accept All Accept Required Only