Add the capability for filters to "ignore" events

If a filter returns NULL, it indicates that it wishes to ignore (pass-through)
the event passed.

In terms of boolean filter logic:
* allow  AND ignore == allow
* allow  OR  ignore == allow
* ignore AND ignore == ignore
* ignore OR  ignore == ignore
* reject AND ignore == reject
* reject OR  ignore == reject
*        NOT ignore == ignore

Built-in filters that now return NULL for specific events:
* ChannelFilter:  event is not a UserEvent
* ChannelFilter:  event is not a channel event
* UserFilter:     event is not a UserEvent
* UserFilter:     event did not originate from a user
* UserModeFilter: event is not a UserEvent
* UserModeFilter: event is not a channel event
* UserModeFilter: event did not originate from a user

Author: Renegade334

README.md

@@ -257,8 +257,10 @@ Filters are merely classes that implement
 [`FilterInterface`](https://github.com/phergie/phergie-irc-plugin-react-eventfilter/blob/master/src/FilterInterface.php).
 This interface has a single method, `filter()`, which accepts an event object
 that implements [`EventInterface`](https://github.com/phergie/phergie-irc-event/blob/master/src/EventInterface.php)
-as its only parameter and returns `true` if the event should be allowed or
-`false` if it should not.
+as its only parameter and returns one of the following values:
+* `true` if the event should be allowed
+* `false` if the event should be denied
+* `null` if the event should be ignored by the filter ("pass-through")
 
 ## Tests
 

src/AndFilter.php

@@ -24,16 +24,21 @@ class AndFilter extends CompositeFilter
      * Filters events that pass all contained filters.
      *
      * @param \Phergie\Irc\Event\EventInterface $event
-     * @return boolean TRUE if the event passes all contained filters, FALSE
-     *         otherwise
+     * @return boolean|null TRUE if the event passes all contained filters, FALSE
+     *         if it fails any filter, or NULL if all filters return NULL.
      */
     public function filter(EventInterface $event)
     {
+        $output = null;
         foreach ($this->filters as $filter) {
-            if (!$filter->filter($event)) {
+            $result = $filter->filter($event);
+            if ($result === false) {
                 return false;
             }
+            if ($result === true) {
+                $output = true;
+            }
         }
-        return true;
+        return $output;
     }
 }

src/ChannelFilter.php

@@ -88,17 +88,21 @@ function($value) {
      * channels.
      *
      * @param \Phergie\Irc\Event\EventInterface $event
-     * @return boolean TRUE if the event is not channel-specific or originated
-     *         from a matching channel associated with this filter, FALSE
-     *         otherwise
+     * @return boolean|null TRUE if the event originated from a matching channel
+     *         associated with this filter, FALSE if it originated from a non-matching
+     *         channel, or NULL if it is not associated with a channel.
      */
     public function filter(EventInterface $event)
     {
         if (!$event instanceof UserEventInterface) {
-            return true;
+            return null;
         }
 
         $channels = $this->getChannels($event);
+        if (empty($channels)) {
+            return null;
+        }
+
         $commonChannels = array_intersect($channels, $this->channels);
         if ($commonChannels) {
             return true;

src/FilterInterface.php

@@ -24,7 +24,9 @@ interface FilterInterface
      * Evaluates an event for forwarding.
      *
      * @param \Phergie\Irc\Event\EventInterface $event
-     * @return boolean TRUE if the event should be forwarded, FALSE otherwise
+     * @return boolean|null TRUE if the event should be allowed, FALSE if it should be rejected,
+     *         or NULL if it should be ignored (ie. the event does not fall under the scope of
+     *         this filter)
      */
     public function filter(EventInterface $event);
 }

src/NotFilter.php

@@ -41,10 +41,15 @@ public function __construct(FilterInterface $filter)
      * Filters events that do not pass the contained filter.
      *
      * @param \Phergie\Irc\Event\EventInterface $event
-     * @return boolean TRUE if the contained filter fails, FALSE if it passes
+     * @return boolean|null TRUE if the contained filter fails, FALSE if it passes,
+     *         or NULL if it returns NULL.
      */
     public function filter(EventInterface $event)
     {
-        return !$this->filter->filter($event);
+        $result = $this->filter->filter($event);
+        if ($result === null) {
+            return null;
+        }
+        return !$result;
     }
 }

src/OrFilter.php

@@ -24,16 +24,21 @@ class OrFilter extends CompositeFilter
      * Filters events that pass any contained filters.
      *
      * @param \Phergie\Irc\Event\EventInterface $event
-     * @return boolean TRUE if the event passes any contained filters, FALSE
-     *         otherwise
+     * @return boolean|null TRUE if the event passes any contained filters, FALSE
+     *         if it fails all filters, or NULL if all filters return NULL.
      */
     public function filter(EventInterface $event)
     {
+        $output = null;
         foreach ($this->filters as $filter) {
-            if ($filter->filter($event)) {
+            $result = $filter->filter($event);
+            if ($result === true) {
                 return true;
             }
+            if ($result === false) {
+                $output = false;
+            }
         }
-        return false;
+        return $output;
     }
 }

src/Plugin.php

@@ -165,7 +165,7 @@ public function handleEvent($event, array $args)
             ));
         } else {
             $eventObject = reset($eventObjects);
-            if (!$this->filter->filter($eventObject)) {
+            if ($this->filter->filter($eventObject) === false) {
                 $logger->info('Event did not pass filter, skipping', array(
                     'event' => $event,
                     'args' => $args,

src/UserFilter.php

@@ -45,18 +45,23 @@ public function __construct(array $masks)
      * Filters events that are not user-specific or are from the specified users.
      *
      * @param \Phergie\Irc\Event\EventInterface $event
-     * @return boolean TRUE if the event is not user-specific or originated
-     *         from a user with a matching mask associated with this filter,
-     *         FALSE otherwise
+     * @return boolean|null TRUE if the event originated from a user with a matching mask
+     *         associated with this filter, FALSE if it originated from a user without a
+     *         matching mask, or NULL if it did not originate from a user.
      */
     public function filter(EventInterface $event)
     {
         if (!$event instanceof UserEventInterface) {
-            return true;
+            return null;
+        }
+
+        $nick = $event->getNick();
+        if ($nick === null) {
+            return null;
         }
 
         $userMask = sprintf('%s!%s@%s',
-            $event->getNick(),
+            $nick,
             $event->getUsername(),
             $event->getHost()
         );

src/UserModeFilter.php

@@ -57,19 +57,23 @@ public function __construct(UserModePlugin $userMode, array $modes)
      * specified modes.
      *
      * @param \Phergie\Irc\Event\EventInterface $event
-     * @return boolean TRUE if the event is not user-specific or originated
-     *         from a user with a matching mode associated with this filter,
-     *         FALSE otherwise
+     * @return boolean|null TRUE if the event originated from a user with a matching mode
+     *         associated with this filter, FALSE if the event originated from a user
+     *         without a matching mode, or NULL if the event did not originate from a user.
      */
     public function filter(EventInterface $event)
     {
         if (!$event instanceof UserEventInterface) {
-            return true;
+            return null;
         }
 
-        $connection = $event->getConnection();
         $channels = $this->getChannels($event);
         $nick = $event->getNick();
+        if (empty($channels) || $nick === null) {
+            return null;
+        }
+
+        $connection = $event->getConnection();
 
         foreach ($channels as $channel) {
             $userModes = $this->userMode->getUserModes($connection, $channel, $nick);

tests/AndFilterTest.php

@@ -35,6 +35,9 @@ public function dataProviderFilter()
             array(true, false, false),
             array(false, true, false),
             array(true, true, true),
+            array(true, null, true),
+            array(false, null, false),
+            array(null, null, null),
         );
 
         foreach ($returns as $return) {