Merge pull request #32973 from nextcloud/cleanup/avatar-code

Cleanup avatar related code

4 files changed, 170 insertions, 31 deletions

diff --git a/lib/public/Color.php b/lib/public/Color.php
new file mode 100644
index 00000000000..e2cabd9c2fc
--- /dev/null
+++ b/lib/public/Color.php
@@ -0,0 +1,142 @@
+<?php
+/**
+ * @copyright Copyright (c) 2016, John Molakvoæ <skjnldsv@protonmail.com>
+ *
+ * @author Christoph Wurst <christoph@winzerhof-wurst.at>
+ * @author Morris Jobke <hey@morrisjobke.de>
+ *
+ * @license GNU AGPL version 3 or any later version
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as
+ * published by the Free Software Foundation, either version 3 of the
+ * License, or (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program. If not, see <http://www.gnu.org/licenses/>.
+ *
+ */
+namespace OCP;
+
+/**
+ * Simple RGB color container
+ * @since 25.0.0
+ */
+class Color {
+	private int $r;
+	private int $g;
+	private int $b;
+
+	/**
+	 * @since 25.0.0
+	 */
+	public function __construct($r, $g, $b) {
+		$this->r = $r;
+		$this->g = $g;
+		$this->b = $b;
+	}
+
+	/**
+	 * Returns the red color component of this color as an int from 0 to 255
+	 *
+	 * @since 25.0.0
+	 */
+	public function red(): int {
+		return $this->r;
+	}
+
+	/**
+	 * Returns the red color component of this color as a float from 0 to 1
+	 *
+	 * @since 25.0.0
+	 */
+	public function redF(): float {
+		return $this->r / 255;
+	}
+
+	/**
+	 * Returns the green color component of this color as an int from 0 to 255
+	 *
+	 * @since 25.0.0
+	 */
+	public function green(): int {
+		return $this->g;
+	}
+
+	/**
+	 * Returns the green color component of this color as a float from 0 to 1
+	 *
+	 * @since 25.0.0
+	 */
+	public function greenF(): float {
+		return $this->g / 255;
+	}
+
+	/**
+	 * Returns the green blue component of this color as an int from 0 to 255
+	 *
+	 * @since 25.0.0
+	 */
+	public function blue(): int {
+		return $this->b;
+	}
+
+	/**
+	 * Returns the blue color component of this color as a float from 0 to 1
+	 *
+	 * @since 25.0.0
+	 */
+	public function blueF(): float {
+		return $this->g / 255;
+	}
+
+	/**
+	 * Returns the name of the color in the format "#RRGGBB"; i.e. a "#" character followed by three two-digit hexadecimal numbers.
+	 *
+	 * @since 25.0.0
+	 */
+	public function name(): string {
+		return sprintf("#%02x%02x%02x", $this->r, $this->g, $this->b);
+	}
+
+	/**
+	 * Mix two colors
+	 *
+	 * @param int $steps the number of intermediate colors that should be generated for the palette
+	 * @param Color $color1 the first color
+	 * @param Color $color2 the second color
+	 * @return list<Color>
+	 * @since 25.0.0
+	 */
+	public static function mixPalette(int $steps, Color $color1, Color $color2): array {
+		$palette = [$color1];
+		$step = self::stepCalc($steps, [$color1, $color2]);
+		for ($i = 1; $i < $steps; $i++) {
+			$r = intval($color1->red() + ($step[0] * $i));
+			$g = intval($color1->green() + ($step[1] * $i));
+			$b = intval($color1->blue() + ($step[2] * $i));
+			$palette[] = new Color($r, $g, $b);
+		}
+		return $palette;
+	}
+
+	/**
+	 * Calculate steps between two Colors
+	 * @param int $steps start color
+	 * @param Color[] $ends end color
+	 * @return array{0: int, 1: int, 2: int} [r,g,b] steps for each color to go from $steps to $ends
+	 * @since 25.0.0
+	 */
+	private static function stepCalc(int $steps, array $ends): array {
+		$step = [];
+		$step[0] = ($ends[1]->red() - $ends[0]->red()) / $steps;
+		$step[1] = ($ends[1]->green() - $ends[0]->green()) / $steps;
+		$step[2] = ($ends[1]->blue() - $ends[0]->blue()) / $steps;
+		return $step;
+	}
+}
diff --git a/lib/public/IAvatar.php b/lib/public/IAvatar.php
index 218ef258250..d05a12e1dbf 100644
--- a/lib/public/IAvatar.php
+++ b/lib/public/IAvatar.php
@@ -36,66 +36,70 @@ use OCP\Files\SimpleFS\ISimpleFile;
 interface IAvatar {
 
 	/**
-	 * get the users avatar
+	 * Get the users avatar
+	 *
 	 * @param int $size size in px of the avatar, avatars are square, defaults to 64, -1 can be used to not scale the image
 	 * @return false|\OCP\IImage containing the avatar or false if there's no image
 	 * @since 6.0.0 - size of -1 was added in 9.0.0
 	 */
-	public function get($size = 64);
+	public function get(int $size = 64);
 
 	/**
 	 * Check if an avatar exists for the user
 	 *
-	 * @return bool
 	 * @since 8.1.0
 	 */
-	public function exists();
+	public function exists(): bool;
 
 	/**
 	 * Check if the avatar of a user is a custom uploaded one
 	 *
-	 * @return bool
 	 * @since 14.0.0
 	 */
 	public function isCustomAvatar(): bool;
 
 	/**
-	 * sets the users avatar
+	 * Sets the users avatar
+	 *
 	 * @param \OCP\IImage|resource|string $data An image object, imagedata or path to set a new avatar
 	 * @throws \Exception if the provided file is not a jpg or png image
 	 * @throws \Exception if the provided image is not valid
 	 * @throws \OC\NotSquareException if the image is not square
-	 * @return void
 	 * @since 6.0.0
 	 */
-	public function set($data);
+	public function set($data): void;
 
 	/**
-	 * remove the users avatar
-	 * @return void
+	 * Remove the user's avatar
+	 *
+	 * @param bool $silent Whether removing the avatar should trigger a change
 	 * @since 6.0.0
 	 */
-	public function remove();
+	public function remove(bool $silent = false): void;
 
 	/**
 	 * Get the file of the avatar
-	 * @param int $size -1 can be used to not scale the image
-	 * @return ISimpleFile
+	 *
+	 * @param int $size The desired image size. -1 can be used to not scale the image
 	 * @throws NotFoundException
 	 * @since 9.0.0
 	 */
-	public function getFile($size);
+	public function getFile(int $size): ISimpleFile;
 
 	/**
-	 * @param string $text
-	 * @return Color Object containting r g b int in the range [0, 255]
+	 * Get the avatar background color
+	 *
 	 * @since 14.0.0
 	 */
-	public function avatarBackgroundColor(string $text);
+	public function avatarBackgroundColor(string $hash): Color;
 
 	/**
-	 * Handle a changed user
+	 * Updates the display name if changed.
+	 *
+	 * @param string $feature The changed feature
+	 * @param mixed $oldValue The previous value
+	 * @param mixed $newValue The new value
 	 * @since 13.0.0
 	 */
-	public function userChanged($feature, $oldValue, $newValue);
+	public function userChanged(string $feature, $oldValue, $newValue): void;
 }
diff --git a/lib/public/IAvatarManager.php b/lib/public/IAvatarManager.php
index 573e109f003..15894550d10 100644
--- a/lib/public/IAvatarManager.php
+++ b/lib/public/IAvatarManager.php
@@ -37,15 +37,14 @@ namespace OCP;
 interface IAvatarManager {
 
 	/**
-	 * return a user specific instance of \OCP\IAvatar
+	 * Return a user specific instance of \OCP\IAvatar
 	 * @see IAvatar
-	 * @param string $user the ownCloud user id
-	 * @return IAvatar
+	 * @param string $userId the Nextcloud user id
 	 * @throws \Exception In case the username is potentially dangerous
 	 * @throws \OCP\Files\NotFoundException In case there is no user folder yet
 	 * @since 6.0.0
 	 */
-	public function getAvatar(string $user) : IAvatar;
+	public function getAvatar(string $userId): IAvatar;
 
 	/**
 	 * Returns a guest user avatar instance.
diff --git a/lib/public/User/Events/UserChangedEvent.php b/lib/public/User/Events/UserChangedEvent.php
index 3a40f8c3f11..f48dd3914e6 100644
--- a/lib/public/User/Events/UserChangedEvent.php
+++ b/lib/public/User/Events/UserChangedEvent.php
@@ -32,16 +32,10 @@ use OCP\IUser;
  * @since 18.0.0
  */
 class UserChangedEvent extends Event {
-
-	/** @var IUser */
-	private $user;
-
-	/** @var string */
-	private $feature;
-
+	private IUser $user;
+	private string $feature;
 	/** @var mixed */
 	private $value;
-
 	/** @var mixed */
 	private $oldValue;