phpBB

Development Wiki

Function.confirm box

From phpBB Development Wiki

confirm_box –– Present a confirmation screen which offers the user a Yes or No option. A confirmation should be used before committing any sensitive operation.

This article is a stub. You can help in improving Olympus Documentation by expanding it.


Description

  1.  bool confirm_box ( $check [, $title [, $hidden [, $html_body [, $u_action ]]]] )

The confirm boxes are phpBB3's system to secure critical actions against CSRF attacks and unintentional triggering. The system is quite simple: the function can be called in check mode, where it will check the presence of a one-time confirmation string passed as request parameter or in display mode, where it will display the confirm box.

Parameters

Parameter Required Default Usage
check Yes bool True for checking if confirmed (without any additional parameters) and false for displaying the confirm box
title No '' string - Title/Message used for confirm box. Specified as a language key used to explain to the user what action they are confirming. message text is _CONFIRM appended to title. If title cannot be found in user->lang a default one is displayed If title_CONFIRM cannot be found in user->lang the text given is used.
hidden No '' string - Hidden variables (in HTML) for passing within the script.
html_body No 'confirm_body.html' Template used for confirm box
u_action No '' string - Custom form action

Generally, you will need to supply the first three parameters, while the remaining two are usually fine left default. The second parameter should be a language key used to explain to the user what the confirm box is about. The third parameter, $hidden, should hold html for hidden fields containing all (user-)submitted values needed to get the current script to exactly the state where it is when calling the function.

Return Values

Returns true if the user confirmed the operation, false if the user cancelled or an error occurred resulting in the form being cancelled.

Examples

Example #1 Generic usage

if ($submit)
{
    
// check mode
    
if (confirm_box(true))
    {
        
submit($my_message);
    }
    else
    {
        
$s_hidden_fields build_hidden_fields(array(
            
'submit'    => true,
            
'my_message' => $my_message,
            )
        );

        
//display mode
        
confirm_box(false'SAMPLE_LANG_KEY'$s_hidden_fields);
    }
}

Notes

Note: When using confirm_box(), the add_form_key() and check_form_key() functions are not needed (for CSRF protection).

See Also