Typehinted block events API

src/pocketmine/event/block/BlockBreakEvent.php

@@ -28,6 +28,9 @@ use pocketmine\event\Cancellable;
 use pocketmine\item\Item;
 use pocketmine\Player;
 
+/**
+ * Called when a player destroys a block somewhere in the world.
+ */
 class BlockBreakEvent extends BlockEvent implements Cancellable{
 	public static $handlerList = null;
 
@@ -42,30 +45,56 @@ class BlockBreakEvent extends BlockEvent implements Cancellable{
 	/** @var Item[] */
 	protected $blockDrops = [];
 
-	public function __construct(Player $player, Block $block, Item $item, $instaBreak = false){
-		$this->block = $block;
+	public function __construct(Player $player, Block $block, Item $item, bool $instaBreak = false){
+		parent::__construct($block);
 		$this->item = $item;
 		$this->player = $player;
-		$this->instaBreak = (bool) $instaBreak;
-		$this->blockDrops = $player->isSurvival() ? $block->getDrops($item) : [];
+
+		$this->instaBreak = $instaBreak;
+
+		if($player->isSurvival()){
+			$this->setDrops($block->getDrops($item));
+		}
 	}
 
-	public function getPlayer(){
+	/**
+	 * Returns the player who is destroying the block.
+	 * @return Player
+	 */
+	public function getPlayer() : Player{
 		return $this->player;
 	}
 
-	public function getItem(){
+	/**
+	 * Returns the item used to destroy the block.
+	 * @return Item
+	 */
+	public function getItem() : Item{
 		return $this->item;
 	}
 
-	public function getInstaBreak(){
+	/**
+	 * Returns whether the block may be broken in less than the amount of time calculated. This is usually true for
+	 * creative players.
+	 *
+	 * @return bool
+	 */
+	public function getInstaBreak() : bool{
 		return $this->instaBreak;
 	}
 
+	/**
+	 * @param bool $instaBreak
+	 */
+	public function setInstaBreak(bool $instaBreak){
+		$this->instaBreak = $instaBreak;
+	}
+
+
 	/**
 	 * @return Item[]
 	 */
-	public function getDrops(){
+	public function getDrops() : array{
 		return $this->blockDrops;
 	}
 
@@ -73,13 +102,15 @@ class BlockBreakEvent extends BlockEvent implements Cancellable{
 	 * @param Item[] $drops
 	 */
 	public function setDrops(array $drops){
-		$this->blockDrops = $drops;
+		$this->setDropsVariadic(...$drops);
 	}
 
 	/**
-	 * @param bool $instaBreak
+	 * Variadic hack for easy array member type enforcement.
+	 *
+	 * @param Item[] ...$drops
 	 */
-	public function setInstaBreak($instaBreak){
-		$this->instaBreak = (bool) $instaBreak;
+	public function setDropsVariadic(Item ...$drops){
+		$this->blockDrops = $drops;
 	}
 }

src/pocketmine/event/block/BlockEvent.php

@@ -43,7 +43,7 @@ abstract class BlockEvent extends Event{
 	/**
 	 * @return Block
 	 */
-	public function getBlock(){
+	public function getBlock() : Block{
 		return $this->block;
 	}
 }

src/pocketmine/event/block/BlockGrowEvent.php

@@ -26,6 +26,9 @@ namespace pocketmine\event\block;
 use pocketmine\block\Block;
 use pocketmine\event\Cancellable;
 
+/**
+ * Called when plants or crops grow.
+ */
 class BlockGrowEvent extends BlockEvent implements Cancellable{
 	public static $handlerList = null;
 
@@ -40,7 +43,7 @@ class BlockGrowEvent extends BlockEvent implements Cancellable{
 	/**
 	 * @return Block
 	 */
-	public function getNewState(){
+	public function getNewState() : Block{
 		return $this->newState;
 	}
 

src/pocketmine/event/block/BlockPlaceEvent.php

@@ -40,36 +40,46 @@ class BlockPlaceEvent extends BlockEvent implements Cancellable{
 	/** @var Item */
 	protected $item;
 
-
+	/** @var Block */
 	protected $blockReplace;
+	/** @var Block */
 	protected $blockAgainst;
 
 	public function __construct(Player $player, Block $blockPlace, Block $blockReplace, Block $blockAgainst, Item $item){
-		$this->block = $blockPlace;
+		parent::__construct($blockPlace);
 		$this->blockReplace = $blockReplace;
 		$this->blockAgainst = $blockAgainst;
 		$this->item = $item;
 		$this->player = $player;
 	}
 
-	public function getPlayer(){
+	/**
+	 * Returns the player who is placing the block.
+	 * @return Player
+	 */
+	public function getPlayer() : Player{
 		return $this->player;
 	}
 
 	/**
 	 * Gets the item in hand
-	 *
-	 * @return mixed
+	 * @return Item
 	 */
-	public function getItem(){
+	public function getItem() : Item{
 		return $this->item;
 	}
 
-	public function getBlockReplaced(){
+	/**
+	 * @return Block
+	 */
+	public function getBlockReplaced() : Block{
 		return $this->blockReplace;
 	}
 
-	public function getBlockAgainst(){
+	/**
+	 * @return Block
+	 */
+	public function getBlockAgainst() : Block{
 		return $this->blockAgainst;
 	}
 }

src/pocketmine/event/block/BlockSpreadEvent.php

@@ -25,6 +25,9 @@ namespace pocketmine\event\block;
 
 use pocketmine\block\Block;
 
+/**
+ * Called when a block spreads to another block, such as grass spreading to nearby dirt blocks.
+ */
 class BlockSpreadEvent extends BlockFormEvent{
 	public static $handlerList = null;
 
@@ -39,7 +42,7 @@ class BlockSpreadEvent extends BlockFormEvent{
 	/**
 	 * @return Block
 	 */
-	public function getSource(){
+	public function getSource() : Block{
 		return $this->source;
 	}
 

src/pocketmine/event/block/LeavesDecayEvent.php

@@ -23,9 +23,11 @@ declare(strict_types=1);
 
 namespace pocketmine\event\block;
 
-use pocketmine\block\Block;
 use pocketmine\event\Cancellable;
 
+/**
+ * Called when leaves decay due to not being attached to wood.
+ */
 class LeavesDecayEvent extends BlockEvent implements Cancellable{
 	public static $handlerList = null;
 

src/pocketmine/event/block/SignChangeEvent.php

@@ -52,14 +52,14 @@ class SignChangeEvent extends BlockEvent implements Cancellable{
 	/**
 	 * @return Player
 	 */
-	public function getPlayer(){
+	public function getPlayer() : Player{
 		return $this->player;
 	}
 
 	/**
 	 * @return string[]
 	 */
-	public function getLines(){
+	public function getLines() : array{
 		return $this->lines;
 	}
 
@@ -67,16 +67,21 @@ class SignChangeEvent extends BlockEvent implements Cancellable{
 	 * @param int $index 0-3
 	 *
 	 * @return string
+	 *
+	 * @throws \InvalidArgumentException if the index is out of bounds
 	 */
-	public function getLine($index){
+	public function getLine(int $index) : string{
 		if($index < 0 or $index > 3){
 			throw new \InvalidArgumentException("Index must be in the range 0-3!");
 		}
+
 		return $this->lines[$index];
 	}
 
 	/**
 	 * @param string[] $lines
+	 *
+	 * @throws \InvalidArgumentException if there are more or less than 4 lines in the passed array
 	 */
 	public function setLines(array $lines){
 		if(count($lines) !== 4){
@@ -88,8 +93,10 @@ class SignChangeEvent extends BlockEvent implements Cancellable{
 	/**
 	 * @param int    $index 0-3
 	 * @param string $line
+	 *
+	 * @throws \InvalidArgumentException if the index is out of bounds
 	 */
-	public function setLine($index, $line){
+	public function setLine(int $index, string $line){
 		if($index < 0 or $index > 3){
 			throw new \InvalidArgumentException("Index must be in the range 0-3!");
 		}