roi-theme/wp-content/plugins/advanced-ads/includes/functions-placement.php

<?php
/**
 * Placement CRUD Helpers
 *
 * @since 2.0.0
 * @package AdvancedAds
 * @author  Advanced Ads <info@wpadvancedads.com>
 *
 * Content:
 *   1. Template
 *   2. Repositories functions
 *   3. CRUD functions
 *   4. Conditional functions
 *   5. Getter functions
 *   6. Finder functions
 */

use AdvancedAds\Constants;
use AdvancedAds\Abstracts\Placement;
use AdvancedAds\Interfaces\Placement_Type;
use AdvancedAds\Placements\Placement_Types;
use AdvancedAds\Placements\Placement_Factory;
use AdvancedAds\Placements\Placement_Repository;

/* 1. Template ------------------- */

/**
 * Get the placement object.
 *
 * @param Placement|WP_Post|int|bool $placement_id Placement instance, post instance, numeric or false to use global $post.
 * @param string                     $new_type     Change type of placement.
 * @param array                      $args         Additional arguments.
 *
 * @return string|mixed placement output string or an entity.
 */
function get_the_placement( $placement_id = 0, $new_type = '', $args = [] ) {
	if ( ! \Advanced_Ads::get_instance()->can_display_ads() ) {
		return '';
	}
	if ( defined( 'ADVANCED_ADS_DISABLE_CHANGE' ) && ADVANCED_ADS_DISABLE_CHANGE ) {
		$args = [];
	}
	// Early bail!!
	// TODO: remove later once we move to new hooks.
	if ( isset( $args['override'] ) ) {
		return $args['override'];
	}

	$placement = is_a( $placement_id, Placement::class ) ? $placement_id : wp_advads_get_placement( $placement_id, $new_type );
	if ( ! $placement || 0 === $placement->get_id() ) {
		return '';
	}

	$args = wp_advads_default_entity_arguments( 'placement', $placement->get_id(), $args );
	wp_advads_set_additional_args( $placement, $args );

	if ( isset( $args['override'] ) ) {
		return $args['override'];
	}

	return $placement->output();
}

/**
 * Return content of an ad placement
 *
 * @since 1.1.0
 *
 * @param Placement|WP_Post|int|bool $placement_id Placement instance, post instance, numeric or false to use global $post.
 * @param array                      $args         Additional arguments.
 *
 * @return void
 */
function the_ad_placement( $placement_id = '', $args = [] ): void {
	echo get_the_placement( $placement_id, '', $args ); // phpcs:ignore
}

/* 2. Repositories ------------------- */

/**
 * Get Placement Factory
 *
 * @return Placement_Factory
 */
function wp_advads_get_placement_factory(): Placement_Factory {
	return wp_advads()->placements->factory;
}

/**
 * Get Placement Repository
 *
 * @return Placement_Repository
 */
function wp_advads_get_placement_repository(): Placement_Repository {
	return wp_advads()->placements->repository;
}

/**
 * Get Placement Types
 *
 * @return Placement_Types
 */
function wp_advads_get_placement_type_manager(): Placement_Types {
	return wp_advads()->placements->types;
}

/* 3. CRUD ------------------- */

/**
 * Create an empty placement object
 *
 * @param string $type Type of placement to create.
 *
 * @return Placement|bool Placement object or false if the placement type not found.
 */
function wp_advads_create_new_placement( $type = 'default' ) {
	return wp_advads_get_placement_factory()->create_placement( $type );
}

/**
 * Delete an placement from the database.
 *
 * @param int|Placement $placement    Placement object or id.
 * @param bool          $force_delete Whether to bypass Trash and force deletion. Default false.
 *
 * @return void
 */
function wp_advads_delete_placement( &$placement, $force_delete = false ): void {
	if ( ! $placement instanceof Placement ) {
		$placement = wp_advads_get_placement( $placement );
	}

	$placement->delete( $force_delete );
}

/**
 * Create missing placement type.
 *
 * @param string $type Missing type.
 *
 * @return void
 */
function wp_advads_create_placement_type( $type ): void {
	wp_advads_get_placement_type_manager()->create_missing( $type );
}

/**
 * Register custom placement type.
 *
 * @param string $classname Type class name.
 *
 * @return void
 */
function wp_advads_register_placement_type( $classname ): void {
	wp_advads_get_placement_type_manager()->register_type( $classname );
}

/* 4. Conditional ------------------- */

/**
 * Has placement type.
 *
 * @param string $type Type to check.
 *
 * @return bool
 */
function wp_advads_has_placement_type( $type ): bool {
	return wp_advads_get_placement_type_manager()->has_type( $type );
}

/**
 * Checks whether the given variable is a placement.
 *
 * @param mixed $thing The variable to check.
 *
 * @return bool
 */
function is_a_placement( $thing ): bool {
	return $thing instanceof Placement;
}

/* 5. Getter ------------------- */

/**
 * Get array of placements.
 *
 * @return Placement[]
 */
function wp_advads_get_placements(): array {
	$placements = is_admin()
		? wp_advads_get_all_placements()
		: wp_advads_get_published_placements();

	return $placements;
}

/**
 * Get array of all placements.
 *
 * @return Placement[]
 */
function wp_advads_get_all_placements(): array {
	return wp_advads_get_placement_repository()->get_all_placements();
}

/**
 * Get array of all published placements.
 *
 * @return Placement[]
 */
function wp_advads_get_published_placements(): array {
	return wp_advads_get_placement_repository()->get_all_published();
}

/**
 * Get all placement as ID => Post Title pair.
 *
 * @return array<int, string>
 */
function wp_advads_get_placements_dropdown(): array {
	return wp_advads_get_placement_repository()->get_placements_dropdown();
}

/**
 * Get the registered placement type.
 *
 * @param string $type Type to get.
 *
 * @return Placement_Type|bool
 */
function wp_advads_get_placement_type( $type ) {
	return wp_advads_get_placement_type_manager()->get_type( $type );
}

/**
 * Get the registered placement types.
 *
 * @param bool $with_unknown Include unknown type placements.
 *
 * @return Placement_Type[]
 */
function wp_advads_get_placement_types( $with_unknown = true ): array {
	return wp_advads_get_placement_type_manager()->get_types( $with_unknown );
}

/* 6. Finder ------------------- */

/**
 * Get the placement object.
 *
 * @param Placement|WP_Post|int|bool $placement_id Placement instance, post instance, numeric or false to use global $post.
 * @param string                     $new_type     Change type of placement.
 *
 * @return Placement|bool Placement object or false if the placement cannot be loaded.
 */
function wp_advads_get_placement( $placement_id = false, $new_type = '' ) {
	$int_placement_id = intval( $placement_id );

	if ( is_int( $placement_id ) && $int_placement_id < 0 ) {
		return false;
	}

	return is_int( $placement_id ) && $int_placement_id > 0
		? wp_advads_get_placement_by_id( $int_placement_id, $new_type )
		: wp_advads_get_placement_by_slug( $placement_id, $new_type );
}

/**
 * Get an placement by ID.
 *
 * @param int    $id       The ID of the placement to retrieve.
 * @param string $new_type Change type of placement.
 *
 * @return Placement|bool
 */
function wp_advads_get_placement_by_id( $id, $new_type = '' ) {
	return wp_advads_get_placement_factory()->get_placement( $id, $new_type );
}

/**
 * Get an placement by slug.
 *
 * @param string $slug     The slug the placement to retrieve.
 * @param string $new_type Change type of placement.
 *
 * @return Placement|bool
 */
function wp_advads_get_placement_by_slug( $slug, $new_type = '' ) {
	global $wpdb;

	$post_id = $wpdb->get_var( // phpcs:ignore WordPress.DB.DirectDatabaseQuery.DirectQuery, WordPress.DB.DirectDatabaseQuery.NoCaching
		$wpdb->prepare(
			"SELECT ID FROM {$wpdb->posts} WHERE post_name = %s and post_type = %s",
			$slug,
			Constants::POST_TYPE_PLACEMENT
		)
	);

	if ( $post_id ) {
		return wp_advads_get_placement_by_id( absint( $post_id ), $new_type );
	}

	return false;
}

/**
 * Find placement by item id.
 *
 * Example: Find all placements that are connected to a specific ad.
 *          In this case $item_id = "ad_1234"
 *
 * Example: Find all placements that are connected to a specific group.
 *          In this case $item_id = "group_1234"
 *
 * @param string $item_id Item id to search for.
 *
 * @return array
 */
function wp_advads_placements_by_item_id( $item_id ): array {
	return wp_advads_get_placement_repository()->find_by_item_id( $item_id );
}

/**
 * Retrieves placements by type.
 *
 * This method queries the database to retrieve placements based on their type.
 *
 * @param string|array $types  Placement types to query.
 * @param string       $output The required return type. One of OBJECT or ids,
 *                             which correspond to an Placement object or an array containing post ids respectively.
 *
 * @return array An associative array of placement IDs as keys and their corresponding placement objects as values.
 */
function wp_advads_get_placements_by_types( $types, $output = OBJECT ): array {
	return wp_advads_get_placement_repository()->find_by_types( $types, $output );
}