Require opting into receiving cancelled events instead of opting out (#2906)

Warning for plugin developers: This is a silent BC break. It won't raise any errors.

This alters the default behaviour of event handlers to **not** receive cancelled events by default.
It is now required to opt into receiving cancelled events by using the @handleCancelled directive (or the handleCancelled parameter where it's appropriate).

The ambiguous @ignoreCancelled directive is now ignored.

Ramifications:
- The majority of handlers with `if($event->isCancelled()) return;` no longer need such checks.
- Handlers with `@ignoreCancelled true` or `@ignoreCancelled` annotations can have them removed.
- Handlers which want to receive cancelled events need to use `@handleCancelled`.

src/pocketmine/event/Listener.php

@@ -46,7 +46,7 @@ use pocketmine\plugin\PluginManager;
  * - `@softDepend [PluginName]`: Handler WILL NOT be registered if its event doesn't exist. Useful for soft-depending
  *     on plugin events. Plugin name is optional.
  *     Example: `@softDepend SimpleAuth`
- * - `@ignoreCancelled`: Cancelled events WILL NOT be passed to this handler.
+ * - `@handleCancelled`: Cancelled events will STILL invoke this handler.
  * - `@priority <PRIORITY>`: Sets the priority at which this event handler will receive events.
  *     Example: `@priority HIGHEST`
  *     @see EventPriority for a list of possible options.

src/pocketmine/plugin/PluginManager.php

@@ -532,22 +532,21 @@ class PluginManager{
 					throw new PluginException("Event handler " . Utils::getNiceClosureName($handlerClosure) . "() declares invalid/unknown priority \"" . $tags["priority"] . "\"");
 				}
 
-				$ignoreCancelled = false;
+				$handleCancelled = false;
-				if(isset($tags["ignoreCancelled"])){
+				if(isset($tags["handleCancelled"])){
-					switch(strtolower($tags["ignoreCancelled"])){
+					switch(strtolower($tags["handleCancelled"])){
 						case "true":
 						case "":
-							$ignoreCancelled = true;
+							$handleCancelled = true;
 							break;
 						case "false":
-							$ignoreCancelled = false;
 							break;
 						default:
-							throw new PluginException("Event handler " . Utils::getNiceClosureName($handlerClosure) . "() declares invalid @ignoreCancelled value \"" . $tags["ignoreCancelled"] . "\"");
+							throw new PluginException("Event handler " . Utils::getNiceClosureName($handlerClosure) . "() declares invalid @handleCancelled value \"" . $tags["handleCancelled"] . "\"");
 					}
 				}
 
-				$this->registerEvent($eventClass->getName(), $handlerClosure, $priority, $plugin, $ignoreCancelled);
+				$this->registerEvent($eventClass->getName(), $handlerClosure, $priority, $plugin, $handleCancelled);
 			}
 		}
 	}
@@ -557,11 +556,11 @@ class PluginManager{
 	 * @param \Closure $handler
 	 * @param int      $priority
 	 * @param Plugin   $plugin
-	 * @param bool     $ignoreCancelled
+	 * @param bool     $handleCancelled
 	 *
 	 * @throws \ReflectionException
 	 */
-	public function registerEvent(string $event, \Closure $handler, int $priority, Plugin $plugin, bool $ignoreCancelled = false) : void{
+	public function registerEvent(string $event, \Closure $handler, int $priority, Plugin $plugin, bool $handleCancelled = false) : void{
 		if(!is_subclass_of($event, Event::class)){
 			throw new PluginException($event . " is not an Event");
 		}
@@ -584,7 +583,7 @@ class PluginManager{
 
 		$timings = new TimingsHandler("Plugin: " . $plugin->getDescription()->getFullName() . " Event: " . $handlerName . "(" . (new \ReflectionClass($event))->getShortName() . ")");
 
-		$this->getEventListeners($event)->register(new RegisteredListener($handler, $priority, $plugin, $ignoreCancelled, $timings));
+		$this->getEventListeners($event)->register(new RegisteredListener($handler, $priority, $plugin, $handleCancelled, $timings));
 	}
 
 	/**

src/pocketmine/plugin/RegisteredListener.php

@@ -39,7 +39,7 @@ class RegisteredListener{
 	private $plugin;
 
 	/** @var bool */
-	private $ignoreCancelled;
+	private $handleCancelled;
 
 	/** @var TimingsHandler */
 	private $timings;
@@ -49,14 +49,14 @@ class RegisteredListener{
 	 * @param \Closure       $handler
 	 * @param int            $priority
 	 * @param Plugin         $plugin
-	 * @param bool           $ignoreCancelled
+	 * @param bool           $handleCancelled
 	 * @param TimingsHandler $timings
 	 */
-	public function __construct(\Closure $handler, int $priority, Plugin $plugin, bool $ignoreCancelled, TimingsHandler $timings){
+	public function __construct(\Closure $handler, int $priority, Plugin $plugin, bool $handleCancelled, TimingsHandler $timings){
 		$this->handler = $handler;
 		$this->priority = $priority;
 		$this->plugin = $plugin;
-		$this->ignoreCancelled = $ignoreCancelled;
+		$this->handleCancelled = $handleCancelled;
 		$this->timings = $timings;
 	}
 
@@ -82,7 +82,7 @@ class RegisteredListener{
 	 * @param Event $event
 	 */
 	public function callEvent(Event $event) : void{
-		if($event instanceof Cancellable and $event->isCancelled() and $this->isIgnoringCancelled()){
+		if($event instanceof Cancellable and $event->isCancelled() and !$this->isHandlingCancelled()){
 			return;
 		}
 		$this->timings->startTiming();
@@ -97,7 +97,7 @@ class RegisteredListener{
 	/**
 	 * @return bool
 	 */
-	public function isIgnoringCancelled() : bool{
+	public function isHandlingCancelled() : bool{
-		return $this->ignoreCancelled;
+		return $this->handleCancelled;
 	}
 }