RecentChange: Use constants for the $noudp parameter of save()

It is a boolean parameter that is confusing for three reasons:

* It's a boolean parameter, given parameters are unnamed in PHP,
  these are always poor UX for call sites.

* It's negated ("noudp"). save(true) means no feeds events,
  save(false) [default] means sending events to feeds.

* To overcome this problem, typical use was to pass a free-form
  string that self-documents the intended behaviour,
  e.g. `save('pleasenoudp')`, any string casts to true.

Fix this by moving the booleans to constants and use those
instead. For compatiblity, keep the negation internally,
although it's hidden from regular usage. Also document
the string hack, deprecate it, and update callers.

Change-Id: Ia57c86b38bf50cb4ec580f42a6b1ca798fcf781a

diff --git a/includes/changes/RecentChange.php b/includes/changes/RecentChange.php
index b051120..ebfb16b 100644 (file)
--- a/includes/changes/RecentChange.php
+++ b/includes/changes/RecentChange.php
@@ -78,6 +78,16 @@ class RecentChange {
        const PRC_PATROLLED = 1;
        const PRC_AUTOPATROLLED = 2;
 
+       /**
+        * @var bool For save() - save to the database only, without any events.
+        */
+       const SEND_NONE = true;
+
+       /**
+        * @var bool For save() - do emit the change to RCFeeds (usually public).
+        */
+       const SEND_FEED = false;
+
        public $mAttribs = [];
        public $mExtra = [];
 
@@ -347,11 +357,23 @@ class RecentChange {
 
        /**
         * Writes the data in this object to the database
-        * @param bool $noudp
+        *
+        * For compatibility reasons, the SEND_ constants internally reference a value
+        * that may seem negated from their purpose (none=true, feed=false). This is
+        * because the parameter used to be called "$noudp", defaulting to false.
+        *
+        * @param bool $send self::SEND_FEED or self::SEND_NONE
         */
-       public function save( $noudp = false ) {
+       public function save( $send = self::SEND_FEED ) {
                global $wgPutIPinRC, $wgUseEnotif, $wgShowUpdatedMarker;
 
+               if ( is_string( $send ) ) {
+                       // Callers used to pass undocumented strings like 'noudp'
+                       // or 'pleasedontudp' instead of self::SEND_NONE (true).
+                       // @deprecated since 1.31 Use SEND_NONE instead.
+                       $send = self::SEND_NONE;
+               }
+
                $dbw = wfGetDB( DB_MASTER );
                if ( !is_array( $this->mExtra ) ) {
                        $this->mExtra = [];
@@ -425,8 +447,8 @@ class RecentChange {
                                $this->mAttribs['rc_this_oldid'], $this->mAttribs['rc_logid'], null, $this );
                }
 
-               # Notify external application via UDP
-               if ( !$noudp ) {
+               if ( $send === self::SEND_FEED ) {
+                       // Emit the change to external applications via RCFeeds.
                        $this->notifyRCFeeds();
                }
 

diff --git a/includes/logging/LogEntry.php b/includes/logging/LogEntry.php
index c672ef7..91231e3 100644 (file)
--- a/includes/logging/LogEntry.php
+++ b/includes/logging/LogEntry.php
@@ -776,7 +776,7 @@ class ManualLogEntry extends LogEntryBase {
                                                        $tags = [];
                                                }
                                                $rc->addTags( $tags );
-                                               $rc->save( 'pleasedontudp' );
+                                               $rc->save( $rc::SEND_NONE );
                                        }
 
                                        if ( $to === 'udp' || $to === 'rcandudp' ) {