BP_Optout::get( array $args = array() )

Get opt-outs, based on provided filter parameters.


Parameters Parameters

$args

(array) (Optional) Associative array of arguments. All arguments but $page and $per_page can be treated as filter values for get_where_sql() and get_query_clauses(). All items are optional.

  • 'id'
    (int|array) ID of opt-out. Can be an array of IDs.
  • 'email_address'
    (string|array) Email address of users who have opted out being queried. Can be an array of addresses.
  • 'user_id'
    (int|array) ID of user whose communication prompted the opt-out. Can be an array of IDs.
  • 'email_type'
    (string|array) Name of the emil type to filter by. Can be an array of email types.
  • 'search_terms'
    (string) Term to match against email_address field.
  • 'order_by'
    (string) Database column to order by.
  • 'sort_order'
    (string) Either 'ASC' or 'DESC'.
  • 'page'
    (int) Number of the current page of results. Default: false (no pagination, all items).
  • 'per_page'
    (int) Number of items to show per page. Default: false (no pagination, all items).
  • 'fields'
    (string) Which fields to return. Specify 'email_addresses' to fetch a list of opt-out email_addresses. Specify 'user_ids' to fetch a list of opt-out user_ids. Specify 'ids' to fetch a list of opt-out IDs. Default: 'all' (return BP_Optout objects).

Default value: array()


Top ↑

Return Return

(array) BP_Optout objects | IDs of found opt-outs | Email addresses of matches.


Source Source

File: bp-core/classes/class-bp-optout.php

	public static function get( $args = array() ) {
		global $wpdb;
		$optouts_table_name = BP_Optout::get_table_name();

		// Parse the arguments.
		$r = bp_parse_args(
			$args,
			array(
				'id'            => false,
				'email_address' => false,
				'user_id'       => false,
				'email_type'    => false,
				'search_terms'  => '',
				'order_by'      => false,
				'sort_order'    => false,
				'page'          => false,
				'per_page'      => false,
				'fields'        => 'all',
			),
			'bp_optout_get'
		);

		$sql = array(
			'select'     => "SELECT",
			'fields'     => '',
			'from'       => "FROM {$optouts_table_name} o",
			'where'      => '',
			'orderby'    => '',
			'pagination' => '',
		);

		if ( 'user_ids' === $r['fields'] ) {
			$sql['fields'] = "DISTINCT o.user_id";
		} else if ( 'email_addresses' === $r['fields'] ) {
			$sql['fields'] = "DISTINCT o.email_address_hash";
		} else {
			$sql['fields'] = 'DISTINCT o.id';
		}

		// WHERE.
		$sql['where'] = self::get_where_sql(
			array(
				'id'            => $r['id'],
				'email_address' => $r['email_address'],
				'user_id'       => $r['user_id'],
				'email_type'    => $r['email_type'],
				'search_terms'  => $r['search_terms'],
			)
		);

		// ORDER BY.
		$sql['orderby'] = self::get_order_by_sql(
			array(
				'order_by'   => $r['order_by'],
				'sort_order' => $r['sort_order']
			)
		);

		// LIMIT %d, %d.
		$sql['pagination'] = self::get_paged_sql(
			array(
				'page'     => $r['page'],
				'per_page' => $r['per_page'],
			)
		);

		$paged_optouts_sql = "{$sql['select']} {$sql['fields']} {$sql['from']} {$sql['where']} {$sql['orderby']} {$sql['pagination']}";

		/**
		 * Filters the pagination SQL statement.
		 *
		 * @since 8.0.0
		 *
		 * @param string $value Concatenated SQL statement.
		 * @param array  $sql   Array of SQL parts before concatenation.
		 * @param array  $r     Array of parsed arguments for the get method.
		 */
		$paged_optouts_sql = apply_filters( 'bp_optouts_get_paged_optouts_sql', $paged_optouts_sql, $sql, $r );

		$cached = bp_core_get_incremented_cache( $paged_optouts_sql, 'bp_optouts' );
		if ( false === $cached ) {
			$paged_optout_ids = $wpdb->get_col( $paged_optouts_sql );
			bp_core_set_incremented_cache( $paged_optouts_sql, 'bp_optouts', $paged_optout_ids );
		} else {
			$paged_optout_ids = $cached;
		}

		// Special return format cases.
		if ( in_array( $r['fields'], array( 'ids', 'user_ids' ), true ) ) {
			// We only want the field that was found.
			return array_map( 'intval', $paged_optout_ids );
		} else if ( 'email_addresses' === $r['fields'] ) {
			return $paged_optout_ids;
		}

		$uncached_ids = bp_get_non_cached_ids( $paged_optout_ids, 'bp_optouts' );
		if ( $uncached_ids ) {
			$ids_sql = implode( ',', array_map( 'intval', $uncached_ids ) );
			$data_objects = $wpdb->get_results( "SELECT o.* FROM {$optouts_table_name} o WHERE o.id IN ({$ids_sql})" );
			foreach ( $data_objects as $data_object ) {
				wp_cache_set( $data_object->id, $data_object, 'bp_optouts' );
			}
		}

		$paged_optouts = array();
		foreach ( $paged_optout_ids as $paged_optout_id ) {
			$paged_optouts[] = new BP_optout( $paged_optout_id );
		}

		return $paged_optouts;
	}


Top ↑

Changelog Changelog

Changelog
Version Description
8.0.0 Introduced.

Top ↑

User Contributed Notes User Contributed Notes

You must log in before being able to contribute a note or feedback.