uo_csv_overwrite_existing_roles

Description

Usage

add_filter( 'uo_csv_overwrite_existing_roles', 'your_function_name', 10, 1 );

Return Value

The filtered value.

Examples

add_filter( 'uo_csv_overwrite_existing_roles', function( $overwrite_existing ) {
	/**
	 * This filter allows developers to control whether existing user roles should be overwritten
	 * when importing users from CSV.
	 *
	 * By default, if the filter returns 'true', existing roles will be overwritten.
	 * If it returns 'false', existing roles will be preserved and the new role from the CSV
	 * will be added in addition to existing roles (if the user has multiple roles).
	 *
	 * In this example, we'll decide to NOT overwrite existing roles if the imported user
	 * is already a "subscriber".
	 */

	// This filter is applied within a function that already has access to the $user_id and $csv_role.
	// However, the filter itself doesn't receive these directly. For a realistic scenario
	// where we'd use this information, we might need to store it in a transient or a global
	// temporarily before the filter is applied, or rely on the context of the $wp_user object
	// if it were passed.
	//
	// For this example, we'll simulate a condition where we *don't* overwrite if
	// the current user being processed has a role of 'subscriber'.
	// In a real-world scenario, you might pass more context to the filter if the plugin allowed it,
	// or use a more advanced approach.
	//
	// For demonstration purposes, let's assume we are currently processing a user with ID 123,
	// and the CSV role is 'editor'. We want to prevent overwriting if the user is a subscriber.

	// Simulate checking if the user being imported is already a subscriber.
	// In a real scenario, you'd get the user ID and the intended CSV role from the context.
	// Since this filter is quite simple and only receives a boolean, a more practical
	// approach for complex logic might be to modify the core function to pass more arguments.

	// For this example, let's say we *always* want to add the role if the user is NOT a subscriber.
	// So, we will return false if the user *is* a subscriber and we *don't* want to overwrite.
	// If the user is *not* a subscriber, we'll let the default 'true' (overwrite) behavior happen.
	//
	// This is a hypothetical scenario to show how you *might* influence the logic.
	// The actual context of $user_id and $csv_role isn't directly available here without
	// modifying the plugin's filter signature or using globals/transients.

	// Let's assume for this example, we want to *add* the role if the user is a subscriber
	// and *overwrite* otherwise. This means we *don't* overwrite if they are a subscriber.
	// The filter's purpose is `uo_csv_overwrite_existing_roles`.
	// If it returns `false`, it means *don't* overwrite.
	// If it returns `true`, it means *do* overwrite.

	// If we want to *preserve* existing roles for subscribers and *overwrite* for others:
	// We need to return `false` if the user is a subscriber (to prevent overwrite)
	// and `true` otherwise (to allow overwrite).

	// IMPORTANT: The original code applies this filter *after* determining if the user
	// is an administrator. It also doesn't pass the $user_id or $csv_role to the filter.
	// This makes it difficult to write a truly realistic example that uses that data.
	//
	// Given the limitations of the current filter signature, a common use case would be
	// to *always* disable overwriting, or *always* enable it, or base it on some global state.
	//
	// Let's create an example that *always* disables overwriting and instead adds the role.
	// This is a common requirement if you want to ensure users gain new roles without losing existing ones.

	// return false; // This would *always* disable overwriting, meaning `set_role` is not used.

	// Another realistic example: Only overwrite if the user is *not* an administrator.
	// The plugin already checks for administrator, but this filter can further refine.
	// If we want to *allow* overwriting by default (as the filter implies with `true`),
	// but then selectively *disable* it for certain conditions.

	// Let's simulate a scenario: We want to overwrite roles unless the user is already
	// an administrator (which the core code handles), AND the CSV role is NOT 'subscriber'.
	// If the CSV role *is* 'subscriber', we want to ADD it, not overwrite.

	// This filter's return value dictates whether `$wp_user->set_role( $csv_role );` is used.
	// If `true` is returned, `set_role` is used (overwriting).
	// If `false` is returned, `add_role` is used (adding, if it doesn't exist).

	// To *add* a role if the CSV role is 'subscriber', and *overwrite* otherwise:
	// We need to return `false` if `$csv_role` is 'subscriber'.
	// We need to return `true` otherwise.

	// To do this, we need access to `$csv_role`. Since it's not passed, we'd have to rely on
	// accessing a global or transient variable that was set just before this filter. This is bad practice.
	//
	// A more realistic scenario given the filter's signature:
	// Let's say we want to *always* add roles instead of overwriting, unless a specific
	// option is set in the WordPress admin that's checked *outside* this filter's scope
	// but accessible globally.

	// Realistic Example: Always add roles and never overwrite, unless a specific
	// plugin setting is enabled that forces overwriting.
	// This filter, when `false`, leads to `wp_user->add_role()`.
	// When `true`, leads to `wp_user->set_role()`.

	// We want to control `set_role` vs `add_role`.
	// If $overwrite_existing is true, `set_role` is used.
	// If $overwrite_existing is false, `add_role` is used.

	// Let's assume a setting `my_plugin_force_role_overwrite` exists.
	// If that setting is true, we return true (overwrite).
	// Otherwise, we return false (add).

	$force_overwrite_setting = get_option( 'my_plugin_force_role_overwrite', false ); // Get setting, default to false.

	if ( $force_overwrite_setting ) {
		// If the setting is enabled, we allow overwriting.
		return true;
	} else {
		// Otherwise, we prefer to add roles and not overwrite existing ones.
		return false;
	}

}, 10, 1 ); // Priority 10, accepts 1 argument (the initial value of the filter)

Placement

This code should be placed in the functions.php file of your active theme, a custom plugin, or using a code snippets plugin.

Source Code

src/classes/import-learndash-users-from-csv.php:1486

private static function perform_wp_role_col_import( $user_id, $current_row, $key_location, $options ) {
		if ( isset( $current_row[ $key_location['wp_role'] ] ) ) {

			if ( '' === $current_row[ $key_location['wp_role'] ] ) {
				$csv_role = $options['uo_import_set_roles'][0];
			} else {
				$csv_role = $current_row[ $key_location['wp_role'] ];
			}
			if ( current_user_can( 'manage_options' ) && 'administrator' !== (string) $csv_role ) {
				unset( $current_row[ $key_location['wp_role'] ] );
				$wp_user                         = new WP_User( $user_id );
				$uo_csv_overwrite_existing_roles = apply_filters( 'uo_csv_overwrite_existing_roles', true );
				if ( ! $uo_csv_overwrite_existing_roles ) {
					$wp_user->add_role( $csv_role );
				} else {
					$wp_user->set_role( $csv_role );
				}
			}
			// Remove values that are needed anymore so we can loop the rest as meta
			unset( $current_row[ $key_location['wp_role'] ] );
		}
		do_action( 'uo_toolkit_csv_import_row_wp_role_col', $user_id, $current_row, $key_location );

		return $current_row;
	}

Related Hooks

• uo_toolkit_csv_import_row_wp_role_col — fires_nearby