Merge pull request #5778 from gijsmartens/ticket/15233

[ticket/15233] Standardize avatar output variables

phpBB/phpbb/avatar/helper.php

@@ -0,0 +1,267 @@
+<?php
+/**
+ *
+ * This file is part of the phpBB Forum Software package.
+ *
+ * @copyright (c) phpBB Limited <https://www.phpbb.com>
+ * @license GNU General Public License, version 2 (GPL-2.0)
+ *
+ * For full copyright and license information, please see
+ * the docs/CREDITS.txt file.
+ *
+ */
+
+namespace phpbb\avatar;
+
+use phpbb\avatar\driver\driver_interface;
+use phpbb\config\config;
+use phpbb\event\dispatcher;
+use phpbb\language\language;
+use phpbb\path_helper;
+use phpbb\user;
+
+/**
+ * Avatar helper object.
+ *
+ * Generates avatars and their variables for display.
+ */
+class helper
+{
+	/** @var config */
+	protected $config;
+
+	/** @var dispatcher */
+	protected $dispatcher;
+
+	/** @var language */
+	protected $language;
+
+	/** @var manager */
+	protected $manager;
+
+	/** @var path_helper */
+	protected $path_helper;
+
+	/** @var user */
+	protected $user;
+
+	/**
+	 * Constructor.
+	 *
+	 * @param config		$config			Config object
+	 * @param dispatcher	$dispatcher		Event dispatcher object
+	 * @param language		$language		Language object
+	 * @param manager		$manager		Avatar manager object
+	 * @param path_helper	$path_helper	Path helper object
+	 * @param user			$user			User object
+	 */
+	public function __construct(
+		config $config,
+		dispatcher $dispatcher,
+		language $language,
+		manager $manager,
+		path_helper $path_helper,
+		user $user
+	)
+	{
+		$this->config		= $config;
+		$this->dispatcher	= $dispatcher;
+		$this->language		= $language;
+		$this->manager		= $manager;
+		$this->path_helper	= $path_helper;
+		$this->user			= $user;
+	}
+
+	/**
+	 * Get an avatar's template variables.
+	 *
+	 * @param array		$avatar			The avatar's data
+	 * @param string	$prefix			The variables' prefix
+	 * @return array					The avatar's template variables
+	 */
+	public function get_template_vars(array $avatar, string $prefix = ''): array
+	{
+		$prefix = $prefix && substr($prefix, -1) !== '_' ? "{$prefix}_" : $prefix;
+
+		return [
+			"{$prefix}AVATAR"			=> $avatar,
+
+			"{$prefix}AVATAR_SOURCE"	=> $avatar['src'],
+			"{$prefix}AVATAR_TITLE"		=> $avatar['title'],
+			"{$prefix}AVATAR_TYPE"		=> $avatar['type'],
+
+			"{$prefix}AVATAR_WIDTH"		=> $avatar['width'],
+			"{$prefix}AVATAR_HEIGHT"	=> $avatar['height'],
+
+			"{$prefix}AVATAR_LAZY"		=> $avatar['lazy'],
+			"{$prefix}AVATAR_HTML"		=> $avatar['html'],
+		];
+	}
+
+	/**
+	 * Get user avatar data.
+	 *
+	 * @param array		$row			The user's table row
+	 * @param string	$title			Optional language string/key for the title
+	 * @param bool		$ignore_config	Ignores the config setting, to still be able to view the avatar in the UCP
+	 * @param bool		$lazy			Indicator whether the avatar should be lazy loaded (requires JS) or not
+	 * @return array					The avatar data array
+	 */
+	public function get_user_avatar(array $row, string $title = 'USER_AVATAR', bool $ignore_config = false, bool $lazy = false): array
+	{
+		$row = manager::clean_row($row, 'user');
+
+		return $this->get_avatar($row, $title, $ignore_config, $lazy);
+	}
+
+	/**
+	 * Get group avatar data.
+	 *
+	 * @param array		$row			The group's table row
+	 * @param string	$title			Optional language string/key for the title
+	 * @param bool		$ignore_config	Ignores the config setting, to still be able to view the avatar in the UCP
+	 * @param bool		$lazy			Indicator whether the avatar should be lazy loaded (requires JS) or not
+	 * @return array					The avatar data array
+	 */
+	public function get_group_avatar(array $row, string $title = 'GROUP_AVATAR', bool $ignore_config = false, bool $lazy = false): array
+	{
+		$row = manager::clean_row($row, 'group');
+
+		return $this->get_avatar($row, $title, $ignore_config, $lazy);
+	}
+
+	/**
+	 * Get avatar data.
+	 *
+	 * @param array		$row			The cleaned table row
+	 * @param string	$title			Optional language string/key for the title
+	 * @param bool		$ignore_config	Ignores the config setting, to still be able to view the avatar in the UCP
+	 * @param bool		$lazy			Indicator whether the avatar should be lazy loaded (requires JS) or not
+	 * @return array					The avatar data array
+	 */
+	public function get_avatar(array $row, string $title, bool $ignore_config = false, bool $lazy = false): array
+	{
+		if (!$this->config['allow_avatar'] && !$ignore_config)
+		{
+			return [
+				'html'		=> '',
+				'lazy'		=> false,
+				'src'		=> '',
+				'title'		=> '',
+				'type'		=> '',
+				'width'		=> 0,
+				'height'	=> 0,
+			];
+		}
+
+		$data = [
+			'src'		=> $row['avatar'],
+			'width'		=> $row['avatar_width'],
+			'height'	=> $row['avatar_height'],
+			'title'		=> $this->language->lang($title),
+			'lazy'		=> $lazy,
+			'type'		=> '',
+			'html'		=> '',
+		];
+
+		/** @var driver_interface $driver */
+		$driver = $this->manager->get_driver($row['avatar_type'], !$ignore_config);
+
+		if ($driver !== null)
+		{
+			$data = array_merge($data, $driver->get_data($row), [
+				'type'	=> $driver->get_name(),
+				'html'	=> $driver->get_custom_html($this->user, $row, $title),
+			]);
+
+			/**
+			 * The type is used in the template to determine what driver is used,
+			 * and potentially to add an additional class to the avatar <img> element.
+			 *
+			 * While it's possible to str_replace('avatar.driver.', '', $data['type'])
+			 * for all the core drivers, this will be awkward for extensions' avatar drivers.
+			 * As they will most likely want to adjust the type in the event below,
+			 * and then have to search for a different definition than they used in their services.yml
+			 *
+			 * For example, 'ext.vendor.avatar.driver.custom_driver'
+			 * They will then have to look for: 'ext.vendor.custom_driver'
+			 *
+			 * So only remove 'avatar.driver.' if it is at the beginning of the driver's name.
+			 */
+			if (strpos($data['type'], 'avatar.driver.') === 0)
+			{
+				$data['type'] = substr($data['type'], strlen('avatar.driver.'));
+			}
+		}
+		else
+		{
+			$data['src'] = '';
+		}
+
+		if (empty($data['html']) && !empty($data['src']))
+		{
+			$data['html'] = $this->get_avatar_html($data);
+		}
+
+		/**
+		 * Event to modify avatar data array
+		 *
+		 * @event core.avatar_helper_get_avatar
+		 * @var	array	row				The cleaned table row
+		 * @var	string	title			The language string/key for the title
+		 * @var	bool	ignore_config	Ignores the config setting, to still be able to view the avatar in the UCP
+		 * @var bool	lazy			Indicator whether the avatar should be lazy loaded (requires JS) or not
+		 * @var	array	data			The avatar data array
+		 * @since 4.0.0
+		 */
+		$vars = ['row', 'title', 'ignore_config', 'lazy', 'data'];
+		extract($this->dispatcher->trigger_event('core.avatar_helper_get_avatar', compact($vars)));
+
+		return $data;
+	}
+
+	/**
+	 * Get the "no avatar" source string.
+	 *
+	 * @return string					The "no avatar" source string
+	 */
+	public function get_no_avatar_source(): string
+	{
+		/**
+		 * We need to correct the phpBB root path in case this is called from a controller,
+		 * because the web path will be incorrect otherwise.
+		 */
+		$board_url	= defined('PHPBB_USE_BOARD_URL_PATH') && PHPBB_USE_BOARD_URL_PATH;
+		$web_path	= $board_url ? generate_board_url() . '/' : $this->path_helper->get_web_root_path();
+		$style_path	= rawurlencode($this->user->style['style_path']);
+
+		return "{$web_path}styles/{$style_path}/theme/images/no_avatar.gif";
+	}
+
+	/**
+	 * Get an avatar's HTML <img> element.
+	 *
+	 * Created for Backwards Compatibility (BC).
+	 * Styles should generate their own HTML element instead.
+	 *
+	 * @deprecated 4.1.0				After admin style is reworked aswell
+	 *
+	 * @param array		$data			The avatar data array
+	 * @return string					The avatar's HTML <img> element
+	 */
+	private function get_avatar_html(array $data): string
+	{
+		if ($data['lazy'])
+		{
+			$data['src'] = $this->get_no_avatar_source() . ' data-src="' . $data['src'];
+		}
+
+		$src = ' src="' . $data['src'] . '"';
+		$alt = ' alt="' . $data['title'] . '"';
+
+		$width = $data['width'] ? ' width="' . $data['width'] . '"' : '';
+		$height = $data['height'] ? ' height="' . $data['height'] . '"' : '';
+
+		return '<img class="avatar"' . $src . $width . $height . $alt . ' />';
+	}
+}

phpBB/phpbb/group/helper.php

@@ -14,6 +14,7 @@
 namespace phpbb\group;
 
 use phpbb\auth\auth;
+use phpbb\avatar\helper as avatar_helper;
 use phpbb\cache\service as cache;
 use phpbb\config\config;
 use phpbb\language\language;
@@ -26,6 +27,9 @@ class helper
 	/** @var auth */
 	protected $auth;
 
+	/** @var avatar_helper */
+	protected $avatar_helper;
+
 	/** @var cache */
 	protected $cache;
 
@@ -54,6 +58,7 @@ class helper
 	 * Constructor
 	 *
 	 * @param auth					$auth			Authentication object
+	 * @param avatar_helper			$avatar_helper	Avatar helper object
 	 * @param cache					$cache			Cache service object
 	 * @param config				$config			Configuration object
 	 * @param language				$language		Language object
@@ -61,9 +66,10 @@ class helper
 	 * @param path_helper			$path_helper	Path helper object
 	 * @param user					$user			User object
 	 */
-	public function __construct(auth $auth, cache $cache, config $config, language $language, dispatcher_interface $dispatcher, path_helper $path_helper, user $user)
+	public function __construct(auth $auth, avatar_helper $avatar_helper, cache $cache, config $config, language $language, dispatcher_interface $dispatcher, path_helper $path_helper, user $user)
 	{
 		$this->auth = $auth;
+		$this->avatar_helper = $avatar_helper;
 		$this->cache = $cache;
 		$this->config = $config;
 		$this->language = $language;
@@ -278,17 +284,17 @@ class helper
 
 	/**
 	 * Get group avatar.
-	 * Wrapper function for phpbb_get_group_avatar()
+	 * Wrapper function for \phpbb\avatar\helper::get_group_avatar()
 	 *
 	 * @param array		$group_row		Row from the groups table
 	 * @param string	$alt			Optional language string for alt tag within image, can be a language key or text
 	 * @param bool		$ignore_config	Ignores the config-setting, to be still able to view the avatar in the UCP
 	 * @param bool		$lazy			If true, will be lazy loaded (requires JS)
 	 *
-	 * @return string 					Avatar html
+	 * @return array 					Avatar data
 	 */
 	function get_avatar($group_row, $alt = 'GROUP_AVATAR', $ignore_config = false, $lazy = false)
 	{
-		return phpbb_get_group_avatar($group_row, $alt, $ignore_config, $lazy);
+		return $this->avatar_helper->get_group_avatar($group_row, $alt, $ignore_config, $lazy);
 	}
 }

phpBB/phpbb/notification/type/base.php

@@ -284,10 +284,11 @@ abstract class base implements \phpbb\notification\type\type_interface
 			$u_mark_read = append_sid($this->phpbb_root_path . 'index.' . $this->php_ext, 'mark_notification=' . $this->notification_id . '&hash=' . $mark_hash . '&redirect=' . urlencode($redirect));
 		}
 
-		return array(
+		$avatar = $this->get_avatar();
+
+		return [
 			'NOTIFICATION_ID'	=> $this->notification_id,
 			'STYLING'			=> $this->get_style_class(),
-			'AVATAR'			=> $this->get_avatar(),
 			'FORMATTED_TITLE'	=> $this->get_title(),
 			'REFERENCE'			=> $this->get_reference(),
 			'FORUM'				=> $this->get_forum(),
@@ -295,8 +296,19 @@ abstract class base implements \phpbb\notification\type\type_interface
 			'URL'				=> $this->get_url(),
 			'TIME'	   			=> $this->user->format_date($this->notification_time),
 			'UNREAD'			=> !$this->notification_read,
+
+			'AVATAR_SOURCE'		=> $avatar ? $avatar['src'] : '',
+			'AVATAR_TITLE'		=> $avatar ? $avatar['title'] : '',
+			'AVATAR_TYPE'		=> $avatar ? $avatar['type'] : '',
+
+			'AVATAR_WIDTH'		=> $avatar ? $avatar['width'] : 0,
+			'AVATAR_HEIGHT'		=> $avatar ? $avatar['height'] : 0,
+
+			'AVATAR_HTML'		=> $avatar ? $avatar['html'] : '',
+			'AVATAR_LAZY'		=> $avatar ? $avatar['lazy'] : true,
+
 			'U_MARK_READ'		=> (!$this->notification_read) ? $u_mark_read : '',
-		);
+		];
 	}
 
 	/**
@@ -327,11 +339,11 @@ abstract class base implements \phpbb\notification\type\type_interface
 	/**
 	* Get the user's avatar (fall back)
 	*
-	* @return string
+	* @return array
 	*/
 	public function get_avatar()
 	{
-		return '';
+		return [];
 	}
 
 	/**

phpBB/phpbb/user_loader.php

@@ -23,6 +23,9 @@ namespace phpbb;
 */
 class user_loader
 {
+	/** @var \phpbb\avatar\helper */
+	protected $avatar_helper;
+
 	/** @var \phpbb\db\driver\driver_interface */
 	protected $db = null;
 
@@ -45,13 +48,15 @@ class user_loader
 	/**
 	* User loader constructor
 	*
+	* @param \phpbb\avatar\helper $avatar_helper Avatar helper object
 	* @param \phpbb\db\driver\driver_interface $db A database connection
 	* @param string $phpbb_root_path Path to the phpbb includes directory.
 	* @param string $php_ext php file extension
 	* @param string $users_table The name of the database table (phpbb_users)
 	*/
-	public function __construct(\phpbb\db\driver\driver_interface $db, $phpbb_root_path, $php_ext, $users_table)
+	public function __construct(\phpbb\avatar\helper $avatar_helper, \phpbb\db\driver\driver_interface $db, $phpbb_root_path, $php_ext, $users_table)
 	{
+		$this->avatar_helper = $avatar_helper;
 		$this->db = $db;
 
 		$this->phpbb_root_path = $phpbb_root_path;
@@ -182,23 +187,23 @@ class user_loader
 	* 						Typically this should be left as false and you should make sure
 	* 						you load users ahead of time with load_users()
 	* @param bool @lazy If true, will be lazy loaded (requires JS)
-	* @return string
+	* @return array
 	*/
 	public function get_avatar($user_id, $query = false, $lazy = false)
 	{
 		if (!($user = $this->get_user($user_id, $query)))
 		{
-			return '';
+			return [];
 		}
 
-		$row = array(
+		$row = [
 			'avatar'		=> $user['user_avatar'],
 			'avatar_type'	=> $user['user_avatar_type'],
 			'avatar_width'	=> $user['user_avatar_width'],
 			'avatar_height'	=> $user['user_avatar_height'],
-		);
+		];
 
-		return phpbb_get_avatar($row, 'USER_AVATAR', false, $lazy);
+		return $this->avatar_helper->get_avatar($row, 'USER_AVATAR', false, $lazy);
 	}
 
 	/**