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

Get media items, as specified by parameters.

Description

Parameters

$args

(array) (Optional) An array of arguments. All items are optional.

  • 'page'
    (int) Which page of results to fetch. Using page=1 without per_page will result in no pagination. Default: 1.
  • 'per_page'
    (int|bool) Number of results per page. Default: 20.
  • 'max'
    (int|bool) Maximum number of results to return. Default: false (unlimited).
  • 'fields'
    (string) Media fields to return. Pass 'ids' to get only the media IDs. 'all' returns full media objects.
  • 'sort'
    (string) ASC or DESC. Default: 'DESC'.
  • 'order_by'
    (string) Column to order results by.
  • 'exclude'
    (array) Array of media IDs to exclude. Default: false.
  • 'search_terms'
    (string) Limit results by a search term. Default: false.
  • 'count_total'
    (string|bool) If true, an additional DB query is run to count the total media items for the query. Default: false.

Default value: array()

Return

(array) The array returned has two keys: - 'total' is the count of located medias - 'medias' is an array of the located medias

Source

File: bp-media/classes/class-bp-media.php

	public static function get( $args = array() ) {

		global $wpdb;

		$bp = buddypress();
		$r  = wp_parse_args( $args, array(
			'page'              => 1,               // The current page.
			'per_page'          => 20,              // Media items per page.
			'max'               => false,           // Max number of items to return.
			'fields'            => 'all',           // Fields to include.
			'sort'              => 'DESC',          // ASC or DESC.
			'order_by'          => 'date_created',  // Column to order by.
			'exclude'           => false,           // Array of ids to exclude.
			'in'                => false,           // Array of ids to limit query by (IN).
			'search_terms'      => false,           // Terms to search by.
			'privacy'           => false,           // public, loggedin, onlyme, friends, grouponly, message.
			'count_total'       => false,           // Whether or not to use count_total.
		) );

		// Select conditions.
		$select_sql = "SELECT DISTINCT m.id";

		$from_sql   = " FROM {$bp->media->table_name} m";

		$join_sql   = '';

		// Where conditions.
		$where_conditions = array();

		// Searching.
		if ( $r['search_terms'] ) {
			$search_terms_like = '%' . bp_esc_like( $r['search_terms'] ) . '%';
			$where_conditions['search_sql'] = $wpdb->prepare( 'm.title LIKE %s', $search_terms_like );

			/**
			 * Filters whether or not to include users for search parameters.
			 *
			 * @since BuddyBoss 1.0.0
			 *
			 * @param bool $value Whether or not to include user search. Default false.
			 */
			if ( apply_filters( 'bp_media_get_include_user_search', false ) ) {
				$user_search = get_user_by( 'slug', $r['search_terms'] );
				if ( false !== $user_search ) {
					$user_id                         = $user_search->ID;
					$where_conditions['search_sql'] .= $wpdb->prepare( ' OR m.user_id = %d', $user_id );
				}
			}
		}

		// Sorting.
		$sort = $r['sort'];
		if ( $sort != 'ASC' && $sort != 'DESC' ) {
			$sort = 'DESC';
		}

		switch( $r['order_by'] ) {
			case 'id' :
			case 'user_id' :
			case 'blog_id' :
			case 'attachment_id' :
			case 'title' :
			case 'album_id' :
			case 'activity_id' :
			case 'group_id' :
			case 'menu_order' :
				break;

			default :
				$r['order_by'] = 'date_created';
				break;
		}
		$order_by = 'm.' . $r['order_by'];

		// Exclude specified items.
		if ( ! empty( $r['exclude'] ) ) {
			$exclude = implode( ',', wp_parse_id_list( $r['exclude'] ) );
			$where_conditions['exclude'] = "m.id NOT IN ({$exclude})";
		}

		// The specific ids to which you want to limit the query.
		if ( ! empty( $r['in'] ) ) {
			$in = implode( ',', wp_parse_id_list( $r['in'] ) );
			$where_conditions['in'] = "m.id IN ({$in})";

			// we want to disable limit query when include media ids
			$r['page']     = false;
			$r['per_page'] = false;
		}

		if ( ! empty( $r['activity_id'] ) ) {
			$where_conditions['activity'] = "m.activity_id = {$r['activity_id']}";
		}

		// existing-media check to query media which has no albums assigned
		if ( ! empty( $r['album_id'] ) && 'existing-media' != $r['album_id'] ) {
			$where_conditions['album'] = "m.album_id = {$r['album_id']}";
		} else if ( ! empty( $r['album_id'] ) && 'existing-media' == $r['album_id'] ) {
			$where_conditions['album'] = "m.album_id = 0";
		}

		if ( ! empty( $r['user_id'] ) ) {
			$where_conditions['user'] = "m.user_id = {$r['user_id']}";
		}

		if ( ! empty( $r['group_id'] ) ) {
			$where_conditions['user'] = "m.group_id = {$r['group_id']}";
		}

		if ( ! empty( $r['privacy'] ) ) {
			$privacy                     = "'" . implode ( "', '", $r['privacy'] ) . "'";
			$where_conditions['privacy'] = "m.privacy IN ({$privacy})";
		}

		/**
		 * Filters the MySQL WHERE conditions for the Media items get method.
		 *
		 * @since BuddyBoss 1.0.0
		 *
		 * @param array  $where_conditions Current conditions for MySQL WHERE statement.
		 * @param array  $r                Parsed arguments passed into method.
		 * @param string $select_sql       Current SELECT MySQL statement at point of execution.
		 * @param string $from_sql         Current FROM MySQL statement at point of execution.
		 * @param string $join_sql         Current INNER JOIN MySQL statement at point of execution.
		 */
		$where_conditions = apply_filters( 'bp_media_get_where_conditions', $where_conditions, $r, $select_sql, $from_sql, $join_sql );

		if ( empty( $where_conditions ) ) {
			$where_conditions['2'] = '2';
		}

		// Join the where conditions together.
		$where_sql = 'WHERE ' . join( ' AND ', $where_conditions );

		/**
		 * Filter the MySQL JOIN clause for the main media query.
		 *
		 * @since BuddyBoss 1.0.0
		 *
		 * @param string $join_sql   JOIN clause.
		 * @param array  $r          Method parameters.
		 * @param string $select_sql Current SELECT MySQL statement.
		 * @param string $from_sql   Current FROM MySQL statement.
		 * @param string $where_sql  Current WHERE MySQL statement.
		 */
		$join_sql = apply_filters( 'bp_media_get_join_sql', $join_sql, $r, $select_sql, $from_sql, $where_sql );

		// Sanitize page and per_page parameters.
		$page     = absint( $r['page']     );
		$per_page = absint( $r['per_page'] );

		$retval = array(
			'medias'         => null,
			'total'          => null,
			'has_more_items' => null,
		);

		// Query first for media IDs.
		$media_ids_sql = "{$select_sql} {$from_sql} {$join_sql} {$where_sql} ORDER BY {$order_by} {$sort}, m.id {$sort}";

		if ( ! empty( $per_page ) && ! empty( $page ) ) {
			// We query for $per_page + 1 items in order to
			// populate the has_more_items flag.
			$media_ids_sql .= $wpdb->prepare( " LIMIT %d, %d", absint( ( $page - 1 ) * $per_page ), $per_page + 1 );
		}

		/**
		 * Filters the paged media MySQL statement.
		 *
		 * @since BuddyBoss 1.0.0
		 *
		 * @param string $media_ids_sql    MySQL statement used to query for Media IDs.
		 * @param array  $r                Array of arguments passed into method.
		 */
		$media_ids_sql = apply_filters( 'bp_media_paged_activities_sql', $media_ids_sql, $r );

		$cache_group = 'bp_media';

		$cached = bp_core_get_incremented_cache( $media_ids_sql, $cache_group );
		if ( false === $cached ) {
			$media_ids = $wpdb->get_col( $media_ids_sql );
			bp_core_set_incremented_cache( $media_ids_sql, $cache_group, $media_ids );
		} else {
			$media_ids = $cached;
		}

		$retval['has_more_items'] = ! empty( $per_page ) && count( $media_ids ) > $per_page;

		// If we've fetched more than the $per_page value, we
		// can discard the extra now.
		if ( ! empty( $per_page ) && count( $media_ids ) === $per_page + 1 ) {
			array_pop( $media_ids );
		}

		if ( 'ids' === $r['fields'] ) {
			$medias = array_map( 'intval', $media_ids );
		} else {
			$medias = self::get_media_data( $media_ids );
		}

		if ( 'ids' !== $r['fields'] ) {
			// Get the fullnames of users so we don't have to query in the loop.
			//$medias = self::append_user_fullnames( $medias );

			// Pre-fetch data associated with media users and other objects.
			$medias = BP_Media::prefetch_object_data( $medias );
		}

		$retval['medias'] = $medias;

		// If $max is set, only return up to the max results.
		if ( ! empty( $r['count_total'] ) ) {

			/**
			 * Filters the total media MySQL statement.
			 *
			 * @since BuddyBoss 1.0.0
			 *
			 * @param string $value     MySQL statement used to query for total medias.
			 * @param string $where_sql MySQL WHERE statement portion.
			 * @param string $sort      Sort direction for query.
			 */
			$total_medias_sql = apply_filters( 'bp_media_total_medias_sql', "SELECT count(DISTINCT m.id) FROM {$bp->media->table_name} m {$join_sql} {$where_sql}", $where_sql, $sort );
			$cached = bp_core_get_incremented_cache( $total_medias_sql, $cache_group );
			if ( false === $cached ) {
				$total_medias = $wpdb->get_var( $total_medias_sql );
				bp_core_set_incremented_cache( $total_medias_sql, $cache_group, $total_medias );
			} else {
				$total_medias = $cached;
			}

			if ( !empty( $r['max'] ) ) {
				if ( (int) $total_medias > (int) $r['max'] ) {
					$total_medias = $r['max'];
				}
			}

			$retval['total'] = $total_medias;
		}

		return $retval;
	}

Changelog

Changelog
Version Description
BuddyBoss 1.0.0 Introduced.

Questions?

We're always happy to help with code or other questions you might have! Search our developer docs, contact support, or connect with our sales team.