Server: rename getPlayer() to getPlayerByPrefix()

closes #3910

the existing naming was misleading, and many plugin devs assumed that it returns an exact match. However, this is not guaranteed, and it's possible for two different players to match the same prefix.

- There is no defined behaviour for what happens when multiple players can equally match a prefix (e.g. 'fr' could match 'fred' or 'frog' equally, because the name lengths are the same)
- A prefix might match a different player at a different time (e.g. 'fr' could match 'freddie' before 'fred' joins, after which it will match 'fred' instead)

With these flaws in mind, it's better to break compatibility on this to make the intent more clear, and to make plugin developers reassess their usages of this method. In most non-command use cases, they should likely be using getPlayerExact() instead.

changelogs/4.0-snapshot.md

@@ -681,6 +681,8 @@ This version features substantial changes to the network system, improving coher
   - `getGamemodeFromString()` - replaced by `GameMode::fromString()`
 - The following API methods have changed:
   - `getOfflinePlayerData()` no longer creates data when it doesn't exist.
+- The following API methods have been renamed:
+  - `getPlayer()` -> `getPlayerByPrefix()` (consider using `getPlayerExact()` instead where possible)
 
 ### Level / World
 #### General

src/Server.php

@@ -570,7 +570,7 @@ class Server{
 	 *
 	 * @see Server::getPlayerExact()
 	 */
-	public function getPlayer(string $name) : ?Player{
+	public function getPlayerByPrefix(string $name) : ?Player{
 		$found = null;
 		$name = strtolower($name);
 		$delta = PHP_INT_MAX;

src/command/defaults/BanIpCommand.php

@@ -61,7 +61,7 @@ class BanIpCommand extends VanillaCommand{
 
 			Command::broadcastCommandMessage($sender, new TranslationContainer("commands.banip.success", [$value]));
 		}else{
-			if(($player = $sender->getServer()->getPlayer($value)) instanceof Player){
+			if(($player = $sender->getServer()->getPlayerByPrefix($value)) instanceof Player){
 				$ip = $player->getNetworkSession()->getIp();
 				$this->processIPBan($ip, $sender, $reason);
 

src/command/defaults/EffectCommand.php

@@ -53,7 +53,7 @@ class EffectCommand extends VanillaCommand{
 			throw new InvalidCommandSyntaxException();
 		}
 
-		$player = $sender->getServer()->getPlayer($args[0]);
+		$player = $sender->getServer()->getPlayerByPrefix($args[0]);
 
 		if($player === null){
 			$sender->sendMessage(new TranslationContainer(TextFormat::RED . "%commands.generic.player.notFound"));

src/command/defaults/EnchantCommand.php

@@ -51,7 +51,7 @@ class EnchantCommand extends VanillaCommand{
 			throw new InvalidCommandSyntaxException();
 		}
 
-		$player = $sender->getServer()->getPlayer($args[0]);
+		$player = $sender->getServer()->getPlayerByPrefix($args[0]);
 
 		if($player === null){
 			$sender->sendMessage(new TranslationContainer(TextFormat::RED . "%commands.generic.player.notFound"));

src/command/defaults/GamemodeCommand.php

@@ -60,7 +60,7 @@ class GamemodeCommand extends VanillaCommand{
 		}
 
 		if(isset($args[1])){
-			$target = $sender->getServer()->getPlayer($args[1]);
+			$target = $sender->getServer()->getPlayerByPrefix($args[1]);
 			if($target === null){
 				$sender->sendMessage(new TranslationContainer(TextFormat::RED . "%commands.generic.player.notFound"));
 

src/command/defaults/GiveCommand.php

@@ -55,7 +55,7 @@ class GiveCommand extends VanillaCommand{
 			throw new InvalidCommandSyntaxException();
 		}
 
-		$player = $sender->getServer()->getPlayer($args[0]);
+		$player = $sender->getServer()->getPlayerByPrefix($args[0]);
 		if($player === null){
 			$sender->sendMessage(new TranslationContainer(TextFormat::RED . "%commands.generic.player.notFound"));
 			return true;

src/command/defaults/KickCommand.php

@@ -57,7 +57,7 @@ class KickCommand extends VanillaCommand{
 		$name = array_shift($args);
 		$reason = trim(implode(" ", $args));
 
-		if(($player = $sender->getServer()->getPlayer($name)) instanceof Player){
+		if(($player = $sender->getServer()->getPlayerByPrefix($name)) instanceof Player){
 			$player->kick("Kicked by admin." . ($reason !== "" ? "Reason: " . $reason : ""));
 			if($reason !== ""){
 				Command::broadcastCommandMessage($sender, new TranslationContainer("commands.kick.success.reason", [$player->getName(), $reason]));

src/command/defaults/KillCommand.php

@@ -60,7 +60,7 @@ class KillCommand extends VanillaCommand{
 				return true;
 			}
 
-			$player = $sender->getServer()->getPlayer($args[0]);
+			$player = $sender->getServer()->getPlayerByPrefix($args[0]);
 
 			if($player instanceof Player){
 				$player->attack(new EntityDamageEvent($player, EntityDamageEvent::CAUSE_SUICIDE, 1000));

src/command/defaults/SpawnpointCommand.php

@@ -61,7 +61,7 @@ class SpawnpointCommand extends VanillaCommand{
 				return true;
 			}
 		}else{
-			$target = $sender->getServer()->getPlayer($args[0]);
+			$target = $sender->getServer()->getPlayerByPrefix($args[0]);
 			if($target === null){
 				$sender->sendMessage(new TranslationContainer(TextFormat::RED . "%commands.generic.player.notFound"));
 

src/command/defaults/TeleportCommand.php

@@ -48,7 +48,7 @@ class TeleportCommand extends VanillaCommand{
 	}
 
 	private function findPlayer(CommandSender $sender, string $playerName) : ?Player{
-		$subject = $sender->getServer()->getPlayer($playerName);
+		$subject = $sender->getServer()->getPlayerByPrefix($playerName);
 		if($subject === null){
 			$sender->sendMessage(TextFormat::RED . "Can't find player " . $playerName);
 			return null;

src/command/defaults/TellCommand.php

@@ -54,7 +54,7 @@ class TellCommand extends VanillaCommand{
 			throw new InvalidCommandSyntaxException();
 		}
 
-		$player = $sender->getServer()->getPlayer(array_shift($args));
+		$player = $sender->getServer()->getPlayerByPrefix(array_shift($args));
 
 		if($player === $sender){
 			$sender->sendMessage(new TranslationContainer(TextFormat::RED . "%commands.message.sameTarget"));

src/command/defaults/TitleCommand.php

@@ -50,7 +50,7 @@ class TitleCommand extends VanillaCommand{
 			throw new InvalidCommandSyntaxException();
 		}
 
-		$player = $sender->getServer()->getPlayer($args[0]);
+		$player = $sender->getServer()->getPlayerByPrefix($args[0]);
 		if($player === null){
 			$sender->sendMessage(new TranslationContainer("commands.generic.player.notFound"));
 			return true;