Purpose

Returns the per-role button array for a given location. Used by the phone-data pipeline’s button-rendering loop in phase_content and by admin UIs that need to render the button list.

Signature

$buttons = apply_filters(
    'mam_app_settings_get_buttons',
    false,             // default sentinel — the handler ignores it and returns the built array
    $role,             // role slug (empty falls back to 'mam-all')
    $location          // 'main' | 'left'
);

Registered by the data manager at priority 10, 3 (three args).

Returns: array of button blobs — an empty array when the role/location has no rows (the core handler never returns false).

Returned shape

array(
    array(
        'id'     => 'btn_42',          // button_id column
        'name'   => 'Edit listing',    // name column
        'icon'   => 'black_edit',      // icon_url column
        'type'   => 'open_form',       // type column
        'source' => '3',               // source column
    ),
    array( 'id' => 'btn_43', ... ),
    // ...
)

The handler selects button_id, name, icon_url, type, source from the
wp_mam_app_settings_buttons table and re-keys them to id / name / icon / type / source.
See Button array storage for how the wider per-button settings are assembled downstream.

Locations

Both locations come from the same wp_mam_app_settings_buttons table, filtered on the
location column. Bottom tab-bar buttons are a separate path — see
mam_app_settings_get_tab_bar_settings.

Example: read the buttons for the current user

$req      = mam_current_request();
$buttons  = apply_filters(
    'mam_app_settings_get_buttons',
    false,
    $req->user_role(),
    'main'
);

Example: filter buttons before they’re rendered

add_filter( 'mam_app_settings_get_buttons', function ( $buttons, $role, $location ) {

    if ( $location !== 'main' ) {
        return $buttons;
    }

    // Hide buttons whose `id` is in our deactivation list.
    $hidden = (array) get_option( 'my_plugin_hidden_buttons', array() );
    $buttons = array_filter( $buttons, function ( $btn ) use ( $hidden ) {
        return ! in_array( $btn['id'], $hidden, true );
    } );

    return array_values( $buttons );  // re-key
}, 20, 3 );

⚠️ Re-key after filtering. Mobile clients expect a 0-indexed list.

Gotchas

• The core handler returns an empty array(), never false. The false you pass in is a caller convention; don’t rely on the resolved value ever being false. A subscriber that wants to signal “no buttons” should still return an array.
• Per-role. A role with no rows falls back to the global mam-all role via the data manager’s query.
• Hot path. Called multiple times per phone-data build (once per location).
• Don’t re-order arbitrarily. Use mam_app_settings_button_order for reordering; arbitrary reordering inside this filter confuses the admin UI.
• Re-key after array_filter. Mobile clients expect 0-indexed.

Related articles

• Button array storage
• Per-button and per-role settings
• Recipe: Add a button
• Hook: mam_app_settings_get_setting
• Hook: mam_tab_manager
• Hook: mam_final_button_settings

Metadata