User Action FREE

#User Action

The User Action is a template to create, update or log a user on form submission.

#User Settings

#Validation

You can use the acf/validate_value hook to validate each fields individually.

To validate the whole form, you can use the acfe/form/validate_user hook and throw errors with the acfe_add_validation_error() function.

Usage example:

/**
 * User Action: Validation
 * 
 * @array  $form    Form settings array
 * @array  $action  Action settings array
 */
 
action('acfe/form/validate_user',                $form, $action);
action('acfe/form/validate_user/form=my-form',   $form, $action);
action('acfe/form/validate_user/action=my-user', $form, $action);

add_action('acfe/form/validate_user/form=my-form', 'my_user_validation', 10, 2);
function my_user_validation($form, $action){
    
    // get current post id
    // where the form is displayed
    $post_id = $form['post_id'];
    
    // get field input value
    $my_field = get_field('my_field');
    
    // check field value
    if($my_field === 'Company'){
        
        // add validation error
        acfe_add_validation_error('my_field', 'The value Company is not allowed');
        
    }
    
}

#Built-in Validation

The Action is bundled with a “Validation” setting that will make sure any required fields to correctly create/update or log the user are validated before the submission.

You can change the built-in validation error messages using the acfe/form/validate_user_errors filter. Usage example:

/**
 * User Action: Validation Errors
 * 
 * @array  $errors  Error messages
 * @array  $form    Form settings array
 * @array  $action  Action settings array
 * 
 * @return array
 */
 
filter('acfe/form/validate_user_errors',                $errors, $form, $action);
filter('acfe/form/validate_user_errors/form=my-form',   $errors, $form, $action);
filter('acfe/form/validate_user_errors/action=my-user', $errors, $form, $action);

add_filter('acfe/form/validate_user_errors/form=my-form', 'my_user_validation_errors', 10, 3);
function my_user_validation_errors($errors, $form, $action){
    
    /**
     * $errors = array(
     *     'empty_user_pass'           => 'An error has occured. Please try again',
     *     'invalid_email'             => 'Invalid e-mail',
     *     'invalid_email_password'    => 'Invalid e-mail or password',
     *     'invalid_username'          => 'Invalid username',
     *     'invalid_username_password' => 'Invalid username or password',
     *     'used_email'                => 'E-mail address is already used',
     *     'used_username'             => 'Username is already used',
     *     'long_username'             => 'Username may not be longer than 60 characters.',
     * );
     */

    // change specific message
    $errors['long_username'] = 'Username is too long';

    // return
    return $errors;
    
}

#Prepare

The preparation phase is triggered after the form validation and before its submission. Returning false will stop the Action and go to the next one. Usage example:

/**
 * User Action: Prepare
 * 
 * @array  $action  Action settings array
 * @array  $form    Form settings array
 *
 * @return array|false
 */
 
filter('acfe/form/prepare_user',                $action, $form);
filter('acfe/form/prepare_user/form=my-form',   $action, $form);
filter('acfe/form/prepare_user/action=my-user', $action, $form);

add_filter('acfe/form/prepare_user/form=my-form', 'my_user_prepare', 10, 2);
function my_user_prepare($action, $form){
    
    // if user isn't logged in
    // do not create/update the user
    if(!is_user_logged_in()){
        return false;
    }
    
    // return normally
    return $action;
    
}

#Values Source

Change the user ID where meta values are loaded from. Usage example:

/**
 * User Action: Values Source
 * 
 * @int    $user_id  User ID source
 * @array  $form     Form settings array
 * @array  $action   Action settings array
 *
 * @return int
 */

filter('acfe/form/load_user_id',                $user_id, $form, $action);
filter('acfe/form/load_user_id/form=my-form',   $user_id, $form, $action);
filter('acfe/form/load_user_id/action=my-user', $user_id, $form, $action);

add_filter('acfe/form/load_user_id/form=my-form', 'my_user_load_id', 10, 3);
function my_user_load_id($user_id, $form, $action){
    
    // get field input value
    $my_field = get_field('my_field');
    
    // check field value
    // and force to load values from the user id 8
    if($my_field === 'Company'){
        $user_id = 8;
    }
    
    // return normally
    return $user_id;
    
}

#User Arguments

Change the user arguments before database insert/update. Those arguments are later passed to wp_insert_user() or wp_update_user() (See documentation). Usage example:

/**
 * User Action: Arguments
 * 
 * @array  $args    User arguments, later passed to wp_insert_user()
 * @array  $form    Form settings array
 * @array  $action  Action settings array
 * 
 * @return array|false
 */

filter('acfe/form/submit_user_args',                $args, $form, $action);
filter('acfe/form/submit_user_args/form=my-form',   $args, $form, $action);
filter('acfe/form/submit_user_args/action=my-user', $args, $form, $action);

add_filter('acfe/form/submit_user_args/form=my-form', 'my_user_submit_args', 10, 3);
function my_user_submit_args($args, $form, $action){
    
    // get current post id
    // where the form is displayed
    $post_id = $form['post_id'];

    // get the action type
    // either 'insert_user', 'update_user' or 'log_user'
    $action_type = $action['type'];
    
    // get the form input value
    $my_field = get_field('my_field');
    
    // check field value
    // and change the user first name
    if($my_field === 'Company'){
        $args['first_name'] = 'My Name';
    }

    // get previous post action output (if any)
    // retrieve the 'post_title' specifically
    $post_title = acfe_get_form_action('post.post_title');
    
    // check the post title
    // and change the user first name
    if($post_title === 'My Post'){
        $args['first_name'] = 'My Name';
    }

    // do not create/update user
    // return false;
    
    // return normally
    return $args;
    
}

#Submit

Trigger a custom action after the user was created/updated/logged using the acfe/form/submit_user hook. Usage example:

/**
 * User Action: Submit
 * 
 * @int    $user_id  Created/Updated/Logged user ID
 * @array  $args     User arguments
 * @array  $form     Form settings array
 * @array  $action   Action settings array
 */
 
action('acfe/form/submit_user',                $user_id, $args, $form, $action);
action('acfe/form/submit_user/form=my-form',   $user_id, $args, $form, $action);
action('acfe/form/submit_user/action=my-user', $user_id, $args, $form, $action);

add_action('acfe/form/submit_user/form=my-form', 'my_user_submit', 10, 4);
function my_user_submit($user_id, $args, $form, $action){
    
    // get current post id
    // where the form is displayed
    $post_id = $form['post_id'];

    // get the action type
    // either 'insert_user', 'update_user' or 'log_user'
    $action_type = $action['type'];
    
    // get the form input value
    $my_field = get_field('my_field');
    
    // check field value
    if($my_field === 'Company'){
        // do something
    }

    // get previous post action output (if any)
    // retrieve the 'post_title' specifically
    $post_title = acfe_get_form_action('post.post_title');
    
    // check the post title
    if($post_title === 'My Post'){
        // do something
    }

    // manually update a field on the created/updated user
    update_field('my_field', 'my_value', "user_{$user_id}");
    
}

#Output

The Action Output allows retrieve the action data in a future action within the Form UI using a Template Tag, or a PHP hook using a function.

For example, the Template Tag {action:user:user_login} will output the latest User “User Login”. The equivalent in PHP is acfe_get_form_action('user.user_login').

It is possible to change the output of a User Action using the acfe/form/submit_user_output filter. Usage example:

/**
 * User Action: Output
 * 
 * @array  $output   Output information
 * @array  $args     User arguments
 * @array  $form     Form settings array
 * @array  $action   Action settings array
 * 
 * @return array
 */
 
filter('acfe/form/submit_user_output',                $output, $args, $form, $action);
filter('acfe/form/submit_user_output/form=my-form',   $output, $args, $form, $action);
filter('acfe/form/submit_user_output/action=my-user', $output, $args, $form, $action);

add_filter('acfe/form/submit_user_output/form=my-form', 'my_user_output', 10, 4);
function my_user_output($output, $args, $form, $action){
    
    /**
     * $output = array(
     *     'ID' => 4,
     *     'user_login' => 'User',
     *     'user_pass' => 'mypassword',
     *     'user_nicename' => 'user',
     *     'user_email' => '[email protected]',
     *     'user_url' => '',
     *     'user_registered' => '2020-08-19 20:27:59',
     *     'user_activation_key' => '',
     *     'user_status' => 0,
     *     'display_name' => 'First name Last name',
     *     'nickname' => 'User',
     *     'first_name' => 'First name',
     *     'last_name' => 'Last name',
     *     'description' => '',
     *     'rich_editing' => true,
     *     'syntax_highlighting' => true,
     *     'comment_shortcuts' => false,
     *     'admin_color' => 'fresh',
     *     'use_ssl' => 0,
     *     'show_admin_bar_front' => true,
     *     'locale' => '',
     *     'wp_capabilities' => array('subscriber' => true),
     *     'wp_user_level' => 0,
     *     'permalink' => '/author/user',
     *     'admin_url' => '/wp-admin/user-edit.php?user_id=4',
     * );
     */
    
    // get field input value
    $my_field = get_field('my_field');
    
    // check field value
    if($my_field === 'Company'){
    
        // set a custom key/value pair in the output
        $output['custom_key'] = 'custom_value';
    
    }
    
    // return normally
    return $output;
    
}