From fd24be4fc537497531f1b1dad9c8bb7b6fb81ff0 Mon Sep 17 00:00:00 2001
From: Piotr Miazga <piotr@polishdeveloper.pl>
Date: Thu, 28 Feb 2019 18:24:10 +0100
Subject: [PATCH] Provide a Taggable interface

The Taggable interface defines how to tag objects in MediaWiki.
For now there are only two Taggable objects:
 - RecentChange
 - ManualLogEntries

This interface should be used in places where we want to optionally
tag things, for example:
 We want to tag all mobile web actions with 'web mobile edit'.

With that interface, we will be able to expect a Taggable object,
and call `addTags()` when we need to, without having a special check
to verify is it RecentChange, or is it ManualLogEntry. We will only
expect a Taggable object.

Additionally, added @deprecated note to ManualLogEntries::setTags()
as each call to this method will override all previous tags. This
action can be harmfull to parts of code that conditionally add tags.
If object was tagged in some way, we should preserve those tags.

If there are any special cases, where we want to override all tags,
we should provide `resetTags()` method.

Bug: T215675
Change-Id: Ia4c019db8ca6f37ce0f86bf7d134d6f1713daf56
---
 RELEASE-NOTES-1.33                |  4 +++
 autoload.php                      |  1 +
 includes/changes/RecentChange.php |  5 ++--
 includes/changetags/Taggable.php  | 42 +++++++++++++++++++++++++++++++
 includes/logging/LogEntry.php     | 28 +++++++++++++++++----
 5 files changed, 73 insertions(+), 7 deletions(-)
 create mode 100644 includes/changetags/Taggable.php

diff --git a/RELEASE-NOTES-1.33 b/RELEASE-NOTES-1.33
index 405d5a75a1..625aa56f1b 100644
--- a/RELEASE-NOTES-1.33
+++ b/RELEASE-NOTES-1.33
@@ -90,6 +90,7 @@ For notes on 1.32.x and older releases, see HISTORY.
   language where available.
 * Special:ActiveUsers will no longer filter out users who became inactive since
   the last time the active users query cache was updated.
+* (T215675) RecentChange and ManualLogEntry implement new Taggable interface.
 
 === New developer features in 1.33 ===
 * The AuthManagerLoginAuthenticateAudit hook has a new parameter for
@@ -386,6 +387,9 @@ because of Phabricator reports.
   deprecated and will be removed in the future.
 * The FileBasedSiteLookup class has been deprecated. For a cacheable SiteLookup
   implementation, use CachingSiteStore instead.
+* ManualLogEntry::setTags() is deprecated, use ManualLogEntry::addTags()
+  instead. The setTags() method was overriding the tags, addTags() doesn't
+  override, only adds new tags.
 
 === Other changes in 1.33 ===
 * (T201747) Html::openElement() warns if given an element name with a space
diff --git a/autoload.php b/autoload.php
index 1c7c34e098..8e771a3939 100644
--- a/autoload.php
+++ b/autoload.php
@@ -870,6 +870,7 @@ $wgAutoloadLocalClasses = [
 	'MediaWikiSite' => __DIR__ . '/includes/site/MediaWikiSite.php',
 	'MediaWikiTitleCodec' => __DIR__ . '/includes/title/MediaWikiTitleCodec.php',
 	'MediaWikiVersionFetcher' => __DIR__ . '/includes/MediaWikiVersionFetcher.php',
+	'MediaWiki\\ChangeTags\\Taggable' => __DIR__ . '/includes/changetags/Taggable.php',
 	'MediaWiki\\Config\\ConfigRepository' => __DIR__ . '/includes/config/ConfigRepository.php',
 	'MediaWiki\\DB\\PatchFileLocation' => __DIR__ . '/includes/db/PatchFileLocation.php',
 	'MediaWiki\\Diff\\ComplexityException' => __DIR__ . '/includes/diff/ComplexityException.php',
diff --git a/includes/changes/RecentChange.php b/includes/changes/RecentChange.php
index 7f7d77d947..2d37eacdc0 100644
--- a/includes/changes/RecentChange.php
+++ b/includes/changes/RecentChange.php
@@ -19,6 +19,7 @@
  *
  * @file
  */
+use MediaWiki\ChangeTags\Taggable;
 
 /**
  * Utility class for creating new RC entries
@@ -65,7 +66,7 @@
  *  we're having to include both rc_comment and rc_comment_text/rc_comment_data
  *  so random crap works right.
  */
-class RecentChange {
+class RecentChange implements Taggable {
 	// Constants for the rc_source field.  Extensions may also have
 	// their own source constants.
 	const SRC_EDIT = 'mw.edit';
@@ -1198,7 +1199,7 @@ class RecentChange {
 	 *
 	 * @since 1.28
 	 *
-	 * @param string|array $tags
+	 * @param string|string[] $tags
 	 */
 	public function addTags( $tags ) {
 		if ( is_string( $tags ) ) {
diff --git a/includes/changetags/Taggable.php b/includes/changetags/Taggable.php
new file mode 100644
index 0000000000..f6245552fb
--- /dev/null
+++ b/includes/changetags/Taggable.php
@@ -0,0 +1,42 @@
+<?php
+/**
+ * Interface that defines how to tag objects
+ *
+ * This program is free software; you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation; either version 2 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License along
+ * with this program; if not, write to the Free Software Foundation, Inc.,
+ * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
+ * http://www.gnu.org/copyleft/gpl.html
+ *
+ * @file
+ * @ingroup Change tagging
+ * @author Piotr Miazga
+ * @license GPL-2.0-or-later
+ */
+namespace MediaWiki\ChangeTags;
+
+/**
+ * Interface that defines how to tag objects
+ *
+ * @since 1.33
+ */
+interface Taggable {
+
+	/**
+	 * Append tags to the tagged object
+	 *
+	 * @since 1.33
+	 * @param string|string[] $tags Tags to apply
+	 */
+	public function addTags( $tags );
+
+}
diff --git a/includes/logging/LogEntry.php b/includes/logging/LogEntry.php
index a154f642e3..19dcf0d811 100644
--- a/includes/logging/LogEntry.php
+++ b/includes/logging/LogEntry.php
@@ -28,9 +28,11 @@
  * @since 1.19
  */
 
+use MediaWiki\ChangeTags\Taggable;
 use MediaWiki\Linker\LinkTarget;
 use MediaWiki\User\UserIdentity;
 use Wikimedia\Rdbms\IDatabase;
+use Wikimedia\Assert\Assert;
 
 /**
  * Interface for log entries. Every log entry has these methods.
@@ -436,7 +438,7 @@ class RCDatabaseLogEntry extends DatabaseLogEntry {
  *
  * @since 1.19
  */
-class ManualLogEntry extends LogEntryBase {
+class ManualLogEntry extends LogEntryBase implements Taggable {
 	/** @var string Type of log entry */
 	protected $type;
 
@@ -586,14 +588,30 @@ class ManualLogEntry extends LogEntryBase {
 	 *
 	 * @since 1.27
 	 * @param string|string[]|null $tags
+	 * @deprecated since 1.33 Please use addTags() instead
 	 */
 	public function setTags( $tags ) {
-		if ( $tags === null ) {
-			$tags = [];
-		} elseif ( is_string( $tags ) ) {
+		if ( $this->tags ) {
+			wfDebug( 'Overwriting existing ManualLogEntry tags' );
+		}
+		$this->tags = [];
+		if ( $tags !== null ) {
+			$this->addTags( $tags );
+		}
+	}
+
+	/**
+	 * Add change tags for the log entry
+	 *
+	 * @since 1.33
+	 * @param string|string[] $tags Tags to apply
+	 */
+	public function addTags( $tags ) {
+		if ( is_string( $tags ) ) {
 			$tags = [ $tags ];
 		}
-		$this->tags = $tags;
+		Assert::parameterElementType( 'string', $tags, 'tags' );
+		$this->tags = array_unique( array_merge( $this->tags, $tags ) );
 	}
 
 	/**
-- 
2.20.1