Version 5.0.0 beta 1

applications/core/sources/Advertisement/Advertisement.php

@@ -11,16 +11,39 @@
 namespace IPS\core;
 
 /* To prevent PHP errors (extending class does not exist) revealing path */
-if ( !\defined( '\IPS\SUITE_UNIQUE_KEY' ) )
+
+use Exception;
+use IPS\Application;
+use IPS\Db;
+use IPS\Dispatcher;
+use IPS\Email;
+use IPS\Extensions\AdvertisementLocationsAbstract;
+use IPS\File;
+use IPS\Lang;
+use IPS\Member;
+use IPS\Member\Group;
+use IPS\Patterns\ActiveRecord;
+use IPS\Redis;
+use IPS\Request;
+use IPS\Settings;
+use IPS\Theme;
+use function count;
+use function defined;
+use const IPS\CACHE_CONFIG;
+use const IPS\CACHE_METHOD;
+use const IPS\REDIS_CONFIG;
+use const IPS\REDIS_ENABLED;
+
+if ( !defined( '\IPS\SUITE_UNIQUE_KEY' ) )
 {
-	header( ( isset( $_SERVER['SERVER_PROTOCOL'] ) ? $_SERVER['SERVER_PROTOCOL'] : 'HTTP/1.0' ) . ' 403 Forbidden' );
+	header( ( $_SERVER['SERVER_PROTOCOL'] ?? 'HTTP/1.0' ) . ' 403 Forbidden' );
 	exit;
 }
 
 /**
  * Advertisements Model
  */
-class _Advertisement extends \IPS\Patterns\ActiveRecord
+class Advertisement extends ActiveRecord
 {
 	/**
 	 * @brief	HTML ad
@@ -40,50 +63,66 @@ class _Advertisement extends \IPS\Patterns\ActiveRecord
 	/**
 	 * @brief	Database Table
 	 */
-	public static $databaseTable = 'core_advertisements';
+	public static ?string $databaseTable = 'core_advertisements';
 	
 	/**
 	 * @brief	Database Prefix
 	 */
-	public static $databasePrefix = 'ad_';
+	public static string $databasePrefix = 'ad_';
 	
 	/**
 	 * @brief	Multiton Store
 	 */
-	protected static $multitons;
+	protected static array $multitons;
 		
 	/**
 	 * @brief	Advertisements loaded during this request (used to update impression count)
 	 * @see		static::updateImpressions()
 	 */
-	public static $advertisementIds	= array();
+	public static array $advertisementIds	= array();
 
 	/**
 	 * @brief	Advertisements sent via email (used to update impression count)
 	 * @see		static::updateEmailImpressions()
 	 */
-	public static $advertisementIdsEmail = array();
+	public static array $advertisementIdsEmail = array();
 
 	/**
 	 * @brief	Stored advertisements we can display on this page
 	 */
-	protected static $advertisements = NULL;
+	protected static ?array $advertisements = NULL;
 
 	/**
 	 * @brief	Stored advertisements we can send in emails
 	 */
-	protected static $emailAdvertisements = NULL;
+	protected static ?array $emailAdvertisements = NULL;
+
+	/**
+	 * @brief	Stored advertisements for widgets
+	 */
+	protected static ?array $widgetAdvertisements = NULL;
+
+	/**
+	 * @brief	List all default location codes
+	 */
+	public static array $defaultLocations = [
+		'ad_global_header',
+		'ad_global_footer',
+		'ad_sidebar'
+	];
 
 	/**
 	 * Fetch advertisements and return the appropriate one to display
 	 *
-	 * @param	string	$location	Advertisement location
-	 * @return	\IPS\core\Advertisement|NULL
+	 * @param	string		$location	Advertisement location
+	 * @param 	int|null	$position	Position within a list
+	 * @param 	int			$adsShown	Total ads already shown in this list
+	 * @return    Advertisement|NULL
 	 */
-	public static function loadByLocation( $location )
+	public static function loadByLocation( string $location, ?int $position=null, int $adsShown=0 ) : ?static
 	{
 		/* If we know there are no ads, we don't need to bother */
-		if ( !\IPS\Settings::i()->ads_exist )
+		if ( !Settings::i()->ads_exist )
 		{
 			return NULL;
 		}
@@ -98,12 +137,12 @@ class _Advertisement extends \IPS\Patterns\ActiveRecord
 			$where[] = array( "ad_start<?", time() );
 			$where[] = array( "(ad_end=0 OR ad_end>?)", time() );
 
-			if( \IPS\Dispatcher::hasInstance() AND ( !isset( \IPS\Dispatcher::i()->dispatcherController ) OR !\IPS\Dispatcher::i()->dispatcherController->isContentPage ) )
+			if( Dispatcher::hasInstance() AND ( !isset( Dispatcher::i()->dispatcherController ) OR !Dispatcher::i()->dispatcherController->isContentPage ) )
 			{
 				$where[] =array( 'ad_nocontent_page_output=?', 1 );
 			}
 
-			foreach( \IPS\Db::i()->select( '*' ,'core_advertisements', $where ) as $row )
+			foreach( Db::i()->select( '*' ,'core_advertisements', $where ) as $row )
 			{
 				foreach ( explode( ',', $row['ad_location'] ) as $_location )
 				{
@@ -112,43 +151,161 @@ class _Advertisement extends \IPS\Patterns\ActiveRecord
 			}
 		}
 
-		/* Weed out any we don't see due to our group. This is done after loading the advertisements so that the cache can be properly primed regardless of group. Note that $ad->exempt, is, confusingly who to SHOW to, not who is exempt */
 		foreach( static::$advertisements as $adLocation => $ads )
 		{
 			foreach( $ads as $index => $ad )
 			{
+				/* Weed out any we don't see due to our group. This is done after loading the advertisements so that the cache can be properly primed regardless of group. Note that $ad->exempt, is, confusingly who to SHOW to, not who is exempt */
 				if ( ! empty( $ad->exempt ) and $ad->exempt != '*' )
 				{
-					$groupsToHideFrom = array_diff( array_keys(\IPS\Member\Group::groups()), json_decode( $ad->exempt, TRUE ) );
+					$groupsToHideFrom = array_diff( array_keys( Group::groups() ), json_decode( $ad->exempt, TRUE ) );
 
-					if ( \IPS\Member::loggedIn()->inGroup( $groupsToHideFrom ) )
+					if ( Member::loggedIn()->inGroup( $groupsToHideFrom ) )
 					{
 						unset( static::$advertisements[ $adLocation ][ $index ] );
 						continue;
 					}
 				}
+
+				/* Weed out any ads that we don't see due to the application settings */
+				if( in_array( $adLocation, static::$defaultLocations ) AND isset( $ad->_additional_settings['ad_apps'] ) AND is_array( $ad->_additional_settings['ad_apps'] ) AND $ad->_additional_settings != 0 )
+				{
+					if( !in_array( Dispatcher::i()->application->directory, $ad->_additional_settings['ad_apps'] ) )
+					{
+						unset( static::$advertisements[ $adLocation ][ $index ] );
+						continue;
+					}
+				}
+
+				/* Remove advertisements that can't be shown based on settings */
+				if( $extension = static::loadExtension( $location ) )
+				{
+					if( !$extension->canShow( $ad, $location ) )
+					{
+						unset( static::$advertisements[ $adLocation][ $index ] );
+					}
+				}
 			}
 		}
 
 		/* No advertisements? Just return then */
-		if( !\count( static::$advertisements ) OR !isset( static::$advertisements[ $location ] ) OR !\count( static::$advertisements[ $location ] ) )
+		if( !count( static::$advertisements ) OR !isset( static::$advertisements[ $location ] ) OR !count( static::$advertisements[ $location ] ) )
 		{
 			return NULL;
 		}
 
-		return static::selectAdvertisement( static::$advertisements[ $location ] );
+		return static::selectAdvertisement( static::$advertisements[ $location ], $position, $adsShown );
+	}
+
+	/**
+	 * Find the Extension that handles this ad location
+	 *
+	 * @param string $location
+	 * @return AdvertisementLocationsAbstract|null
+	 */
+	protected static function loadExtension( string $location ) : ?AdvertisementLocationsAbstract
+	{
+		foreach( Application::allExtensions( 'core', 'AdvertisementLocations' ) as $ext )
+		{
+			/* @var AdvertisementLocationsAbstract $ext */
+			$extensionSettings = $ext->getSettings( array() );
+			if( array_key_exists( $location, $extensionSettings['locations'] ) )
+			{
+				return $ext;
+			}
+		}
+
+		return null;
+	}
+
+	/**
+	 * Fetch advertisements for a particular widget
+	 *
+	 * @param	array	$additionalWhere
+	 * @param	array|null	$ids	Specify the IDs to choose from
+	 * @param 	int|null	$limit
+	 * @return    array|NULL
+	 */
+	public static function loadForWidget( array $additionalWhere=array(), ?array $ids=null, ?int $limit=null ) : ?array
+	{
+		/* If we know there are no ads, we don't need to bother */
+		if ( !Settings::i()->ads_exist )
+		{
+			return NULL;
+		}
+
+		/* Fetch our advertisements, if we haven't already done so */
+		if( static::$widgetAdvertisements  === NULL )
+		{
+			static::$widgetAdvertisements = array();
+
+			$where = [
+				[ "ad_type!=?", static::AD_EMAIL ],
+				[ "ad_active=?", 1 ],
+				[ "ad_start<?", time() ],
+				[ "(ad_end=0 OR ad_end>?)", time() ]
+			];
+
+			foreach( $additionalWhere as $clause )
+			{
+				$where[] = $clause;
+			}
+
+			foreach( Db::i()->select( '*' ,'core_advertisements', $where ) as $row )
+			{
+				static::$widgetAdvertisements[] = static::constructFromData( $row );
+			}
+		}
+
+		$widgetsToUse = [];
+		foreach( static::$widgetAdvertisements as $index => $ad )
+		{
+			/* Weed out any we don't see due to our group. This is done after loading the advertisements so that the cache can be properly primed regardless of group. Note that $ad->exempt, is, confusingly who to SHOW to, not who is exempt */
+			if ( ! empty( $ad->exempt ) and $ad->exempt != '*' )
+			{
+				$groupsToHideFrom = array_diff( array_keys( Group::groups() ), json_decode( $ad->exempt, TRUE ) );
+
+				if ( Member::loggedIn()->inGroup( $groupsToHideFrom ) )
+				{
+					continue;
+				}
+			}
+
+			/* If the widget is not in our specified list, remove it */
+			if( is_array( $ids ) and count( $ids ) and !in_array( $ad->id, $ids ) )
+			{
+				continue;
+			}
+
+			$widgetsToUse[] = $ad;
+		}
+
+		/* No advertisements? Just return then */
+		if( !count( $widgetsToUse ) )
+		{
+			return NULL;
+		}
+
+		/* Shuffle so we display randomly */
+		$limit = $limit ?? 1;
+		if( count( $widgetsToUse ) > $limit )
+		{
+			shuffle( $widgetsToUse );
+		}
+
+		return array_slice( $widgetsToUse, 0, $limit );
 	}
 
 	/**
 	 * Fetch advertisements for emails and return the appropriate one to display
 	 *
 	 * @param	array|null	$container	The container that spawned the email, or NULL
-	 * @return	\IPS\core\Advertisement|NULL
+	 * @return    Advertisement|NULL
 	 */
-	public static function loadForEmail( $container=NULL )
+	public static function loadForEmail( ?array $container=NULL ) : ?static
 	{
 		/* If we know there are no ads, we don't need to bother */
-		if ( !\IPS\Settings::i()->ads_exist )
+		if ( !Settings::i()->ads_exist )
 		{
 			return NULL;
 		}
@@ -158,7 +315,7 @@ class _Advertisement extends \IPS\Patterns\ActiveRecord
 		{
 			static::$emailAdvertisements = array();
 
-			foreach( \IPS\Db::i()->select( '*' ,'core_advertisements', array( "ad_type=? AND ad_active=1 AND ad_start < ? AND ( ad_end=0 OR ad_end > ? )", static::AD_EMAIL, time(), time() ) ) as $row )
+			foreach( Db::i()->select( '*' ,'core_advertisements', array( "ad_type=? AND ad_active=1 AND ad_start < ? AND ( ad_end=0 OR ad_end > ? )", static::AD_EMAIL, time(), time() ) ) as $row )
 			{
 				foreach ( explode( ',', $row['ad_location'] ) as $_location )
 				{
@@ -188,7 +345,7 @@ class _Advertisement extends \IPS\Patterns\ActiveRecord
 		/* If we didn't find any, then look for generic ones for the node class */
 		if( $container !== NULL )
 		{
-			if( !\count( $adsToCheckFrom ) )
+			if( !count( $adsToCheckFrom ) )
 			{
 				foreach( static::$emailAdvertisements as $advertisement )
 				{
@@ -204,7 +361,7 @@ class _Advertisement extends \IPS\Patterns\ActiveRecord
 		}
 
 		/* If we still don't have any, look for generic ones allowed in all emails */
-		if( !\count( $adsToCheckFrom ) )
+		if( !count( $adsToCheckFrom ) )
 		{
 			foreach( static::$emailAdvertisements as $advertisement )
 			{
@@ -216,7 +373,7 @@ class _Advertisement extends \IPS\Patterns\ActiveRecord
 		}
 
 		/* No advertisements? Just return then */
-		if( !\count( $adsToCheckFrom ) )
+		if( !count( $adsToCheckFrom ) )
 		{
 			return NULL;
 		}
@@ -227,75 +384,107 @@ class _Advertisement extends \IPS\Patterns\ActiveRecord
 	/**
 	 * Select an advertisement from an array and return it
 	 *
-	 * @param	array	$ads	Array of advertisements to select from
-	 * @return	static
+	 * @param	array		$ads	Array of advertisements to select from
+	 * @param int|null $position Position within a list
+	 * @param int $adsShown Total ads already shown in this list
+	 * @return	static|null
 	 */
-	static protected function selectAdvertisement( $ads )
+	static protected function selectAdvertisement( array $ads, ?int $position=null, int $adsShown=0 ) : ?static
 	{
 		/* Reset so we don't throw an error */
 		$ads = array_values( $ads );
 
-		/* If we only have one, that is the one we will show */
-		if( \count( $ads ) === 1 )
-		{
-			$advertisement	= $ads[0];
-		}
-		else
+		/* If we have more than one ad, sort them according to the circulation settings */
+		if( count( $ads ) > 1 )
 		{
 			/* Figure out which one to show you */
-			switch( \IPS\Settings::i()->ads_circulation )
+			switch ( Settings::i()->ads_circulation )
 			{
 				case 'random':
-					$advertisement	= $ads[ array_rand( $ads ) ];
-				break;
+					shuffle( $ads );
+					break;
 
 				case 'newest':
-					usort( $ads, function( $a, $b ){
+					usort( $ads, function ( $a, $b )
+					{
 						return strcmp( $a->start, $b->start );
 					} );
-
-					$advertisement	= $ads[0];
-				break;
+					break;
 
 				case 'oldest':
-					usort( $ads, function( $a, $b ){
+					usort( $ads, function ( $a, $b )
+					{
 						return strcmp( $b->start, $a->start );
 					} );
-
-					$advertisement	= $ads[0];
-				break;
+					break;
 
 				case 'least':
-					usort( $ads, function( $a, $b ){
+					usort( $ads, function ( $a, $b )
+					{
 						if ( $a->impressions == $b->impressions )
 						{
 							return 0;
 						}
-						
+
 						return ( $a->impressions < $b->impressions ) ? -1 : 1;
 					} );
-
-					$advertisement	= $ads[0];
-				break;
+					break;
 			}
 		}
 
-		return $advertisement;
+		/* Loop through the ads and find one that matches, based on positions and other settings */
+		foreach( $ads as $ad )
+		{
+			/* @var Advertisement $ad */
+			/* If we have no position specified, just grab the first one and stop */
+			if( $position === null )
+			{
+				$advertisement = $ad;
+				break;
+			}
+
+			$indexNumber = $ad->_additional_settings[ 'ad_view_number' ] ?? false;
+			$repeat = $ad->_additional_settings[ 'ad_view_repeat' ] ?? false;
+
+			if( $indexNumber !== false )
+			{
+				/* Check the position and see if it's a match */
+				if( $position > $indexNumber AND $position % $indexNumber === 1 )
+				{
+					/* Did we already show it the maximum times? */
+					if( $repeat !== false )
+					{
+						if( $repeat === -1 OR ( isset( $adsShown ) AND $repeat > $adsShown ) )
+						{
+							$advertisement = $ad;
+							break;
+						}
+					}
+					else
+					{
+						$advertisement = $ad;
+						break;
+					}
+				}
+			}
+		}
+
+		return $advertisement ?? null;
 	}
 
 	/**
 	 * Convert the advertisement to an HTML string
 	 *
 	 * @param	string				$emailType	html or plaintext email advertisement
-	 * @param	\IPS\Email|NULL		$email		For an email advertisement, this will be the email object, otherwise NULL
+	 * @param	Email|NULL		$email		For an email advertisement, this will be the email object, otherwise NULL
 	 * @return	string
 	 */
-	public function toString( $emailType='html', $email=NULL )
+	public function toString( string $emailType='html', ?Email $email=NULL ) : string
 	{
 		/* Showing HTML or an image? */
 		if( $this->type == static::AD_HTML )
 		{
-			if( \IPS\Request::i()->isSecure() AND $this->html_https_set )
+			if( Request::i()->isSecure() AND $this->html_https_set )
 			{
 				$result	= $this->html_https;
 			}
@@ -306,11 +495,11 @@ class _Advertisement extends \IPS\Patterns\ActiveRecord
 		}
 		elseif( $this->type == static::AD_IMAGES )
 		{
-			$result	= \IPS\Theme::i()->getTemplate( 'global', 'core', 'global' )->advertisementImage( $this );
+			$result	= Theme::i()->getTemplate( 'global', 'core', 'global' )->advertisementImage( $this );
 		}
 		elseif( $this->type == static::AD_EMAIL )
 		{
-			$result = \IPS\Email::template( 'core', 'advertisement', $emailType, array( $this, $email ) );
+			$result = Email::template( 'core', 'advertisement', $emailType, array( $this, $email ) );
 		}
 
 		/* Did we just hit the maximum impression count? If so, disable and then clear the cache so it will rebuild next time. */
@@ -319,9 +508,9 @@ class _Advertisement extends \IPS\Patterns\ActiveRecord
 			$this->active	= 0;
 			$this->save();
 			
-			if ( !\IPS\Db::i()->select( 'COUNT(*)', 'core_advertisements', 'ad_active=1' )->first() )
+			if ( !Db::i()->select( 'COUNT(*)', 'core_advertisements', 'ad_active=1' )->first() )
 			{
-				\IPS\Settings::i()->changeValues( array( 'ads_exist' => 0 ) );
+				Settings::i()->changeValues( array( 'ads_exist' => 0 ) );
 			}			
 		}
 
@@ -335,7 +524,7 @@ class _Advertisement extends \IPS\Patterns\ActiveRecord
 			static::$advertisementIds[]	= $this->id;
 		}
 		
-		return $result;
+		return $result ?? '';
 	}
 
 	/**
@@ -353,7 +542,7 @@ class _Advertisement extends \IPS\Patterns\ActiveRecord
 	 *
 	 * @return	array
 	 */
-	public function get__images()
+	public function get__images() : array
 	{
 		if( !isset( $this->_data['_images'] ) )
 		{
@@ -368,7 +557,7 @@ class _Advertisement extends \IPS\Patterns\ActiveRecord
 	 *
 	 * @return	array
 	 */
-	public function get__additional_settings()
+	public function get__additional_settings() : array
 	{
 		if( !isset( $this->_data['_additional_settings'] ) )
 		{
@@ -383,7 +572,7 @@ class _Advertisement extends \IPS\Patterns\ActiveRecord
 	 *
 	 * @return string
 	 */
-	public function storageExtension()
+	public function storageExtension() : string
 	{
 		if ( $this->member )
 		{
@@ -398,36 +587,36 @@ class _Advertisement extends \IPS\Patterns\ActiveRecord
 	/**
 	 * [ActiveRecord] Delete Record
 	 *
-	 * @return	void
+	 * @return    void
 	 */
-	public function delete()
+	public function delete(): void
 	{
 		/* If we have images, delete them */
-		if( \count( $this->_images ) )
+		if( count( $this->_images ) )
 		{
-			\IPS\File::get( $this->storageExtension(), $this->_images['large'] )->delete();
+			File::get( $this->storageExtension(), $this->_images['large'] )->delete();
 
 			if( isset( $this->_images['small'] ) )
 			{
-				\IPS\File::get( $this->storageExtension(), $this->_images['small'] )->delete();
+				File::get( $this->storageExtension(), $this->_images['small'] )->delete();
 			}
 
 			if( isset( $this->_images['medium'] ) )
 			{
-				\IPS\File::get( $this->storageExtension(), $this->_images['medium'] )->delete();
+				File::get( $this->storageExtension(), $this->_images['medium'] )->delete();
 			}
 		}
 
 		/* Delete the translatable title */
-		\IPS\Lang::deleteCustom( 'core', "core_advert_{$this->id}" );
+		Lang::deleteCustom( 'core', "core_advert_{$this->id}" );
 		
 		/* Delete */
 		parent::delete();
 		
 		/* Make sure we still have active ads */
-		if ( !\IPS\Db::i()->select( 'COUNT(*)', 'core_advertisements', 'ad_active=1' )->first() )
+		if ( !Db::i()->select( 'COUNT(*)', 'core_advertisements', 'ad_active=1' )->first() )
 		{
-			\IPS\Settings::i()->changeValues( array( 'ads_exist' => 0 ) );
+			Settings::i()->changeValues( array( 'ads_exist' => 0 ) );
 		}
 	}
 
@@ -436,9 +625,9 @@ class _Advertisement extends \IPS\Patterns\ActiveRecord
 	 *
 	 * @return	void
 	 */
-	public static function updateImpressions()
+	public static function updateImpressions() : void
 	{
-		if( \count( static::$advertisementIds ) )
+		if( count( static::$advertisementIds ) )
 		{
 			static::updateCounter( static::$advertisementIds );
 
@@ -453,9 +642,9 @@ class _Advertisement extends \IPS\Patterns\ActiveRecord
 	 * @param	int		$impressions	Number of impressions (may be more than one if mergeAndSend() was called)
 	 * @return	void
 	 */
-	public static function updateEmailImpressions( $impressions=1 )
+	public static function updateEmailImpressions( int $impressions=1 ) : void
 	{
-		if( \count( static::$advertisementIdsEmail ) )
+		if( count( static::$advertisementIdsEmail ) )
 		{
 			static::updateCounter( static::$advertisementIdsEmail, $impressions );
 
@@ -471,19 +660,19 @@ class _Advertisement extends \IPS\Patterns\ActiveRecord
 	 * @param int $by		Number to increment by
 	 * @return void
 	 */
-	protected static function updateCounter( array $ids, $by=1 )
+	protected static function updateCounter( array $ids, int $by=1 ) : void
 	{
 		$countUpdated = false;
-		if ( \IPS\REDIS_ENABLED and \IPS\CACHE_METHOD == 'Redis' and ( \IPS\CACHE_CONFIG or \IPS\REDIS_CONFIG ) )
+		if ( Redis::isEnabled() )
 		{
 			foreach( $ids as $id )
 			{
 				try
 				{
-					\IPS\Redis::i()->zIncrBy( 'advert_impressions', $by, $id );
+					Redis::i()->zIncrBy( 'advert_impressions', $by, $id );
 					$countUpdated = true;
 				}
-				catch ( \Exception $e )
+				catch ( Exception $e )
 				{
 				}
 			}
@@ -491,7 +680,7 @@ class _Advertisement extends \IPS\Patterns\ActiveRecord
 
 		if ( ! $countUpdated )
 		{
-			\IPS\Db::i()->update( 'core_advertisements', "ad_impressions=ad_impressions+" . $by, "ad_id IN(" . implode( ',', $ids ) . ")" );
+			Db::i()->update( 'core_advertisements', "ad_impressions=ad_impressions+" . $by . ", ad_daily_impressions=ad_daily_impressions+" . $by, "ad_id IN(" . implode( ',', $ids ) . ")" );
 		}
 	}
 }