Merge "Introduce 'clone' flag for newFromLinkTarget."

diff --combined includes/Title.php
index 6d86b22,256ddaa..f53a47e
--- 1/includes/Title.php
--- 2/includes/Title.php
+++ b/includes/Title.php
@@@ -53,6 -53,13 +53,13 @@@ class Title implements LinkTarget, IDBA
         */
        const GAID_FOR_UPDATE = 1;
  
+       /**
+        * Flag for use with factory methods like newFromLinkTarget() that have
+        * a $forceClone parameter. If set, the method must return a new instance.
+        * Without this flag, some factory methods may return existing instances.
+        */
+       const NEW_CLONE = 'clone';
+ 
        /**
         * @name Private member variables
         * Please use the accessor functions instead.
@@@ -231,27 -238,39 +238,39 @@@
        }
  
        /**
-        * Create a new Title from a TitleValue
+        * Returns a Title given a TitleValue.
+        * If the given TitleValue is already a Title instance, that instance is returned,
+        * unless $forceClone is "clone". If $forceClone is "clone" and the given TitleValue
+        * is already a Title instance, that instance is copied using the clone operator.
         *
         * @param TitleValue $titleValue Assumed to be safe.
+        * @param string $forceClone set to NEW_CLONE to ensure a fresh instance is returned.
         *
         * @return Title
         */
-       public static function newFromTitleValue( TitleValue $titleValue ) {
-               return self::newFromLinkTarget( $titleValue );
+       public static function newFromTitleValue( TitleValue $titleValue, $forceClone = '' ) {
+               return self::newFromLinkTarget( $titleValue, $forceClone );
        }
  
        /**
-        * Create a new Title from a LinkTarget
+        * Returns a Title given a LinkTarget.
+        * If the given LinkTarget is already a Title instance, that instance is returned,
+        * unless $forceClone is "clone". If $forceClone is "clone" and the given LinkTarget
+        * is already a Title instance, that instance is copied using the clone operator.
         *
         * @param LinkTarget $linkTarget Assumed to be safe.
+        * @param string $forceClone set to NEW_CLONE to ensure a fresh instance is returned.
         *
         * @return Title
         */
-       public static function newFromLinkTarget( LinkTarget $linkTarget ) {
+       public static function newFromLinkTarget( LinkTarget $linkTarget, $forceClone = '' ) {
                if ( $linkTarget instanceof Title ) {
                        // Special case if it's already a Title object
-                       return $linkTarget;
+                       if ( $forceClone === self::NEW_CLONE ) {
+                               return clone $linkTarget;
+                       } else {
+                               return $linkTarget;
+                       }
                }
                return self::makeTitle(
                        $linkTarget->getNamespace(),
@@@ -268,6 -287,10 +287,10 @@@
         * Title objects returned by this method are guaranteed to be valid, and
         * thus return true from the isValid() method.
         *
+        * @note The Title instance returned by this method is not guaranteed to be a fresh instance.
+        * It may instead be a cached instance created previously, with references to it remaining
+        * elsewhere.
+        *
         * @param string|int|null $text The link text; spaces, prefixes, and an
         *   initial ':' indicating the main namespace are accepted.
         * @param int $defaultNamespace The namespace to use if none is specified
@@@ -302,6 -325,10 +325,10 @@@
         * Title objects returned by this method are guaranteed to be valid, and
         * thus return true from the isValid() method.
         *
+        * @note The Title instance returned by this method is not guaranteed to be a fresh instance.
+        * It may instead be a cached instance created previously, with references to it remaining
+        * elsewhere.
+        *
         * @see Title::newFromText
         *
         * @since 1.25
@@@ -593,6 -620,10 +620,10 @@@
        /**
         * Create a new Title for the Main Page
         *
+        * @note The Title instance returned by this method is not guaranteed to be a fresh instance.
+        * It may instead be a cached instance created previously, with references to it remaining
+        * elsewhere.
+        *
         * @return Title The new object
         */
        public static function newMainPage() {
@@@ -3556,8 -3587,10 +3587,8 @@@
                        $linkCache->clearLink( $this );
                        $this->mArticleID = $linkCache->addLinkObj( $this );
                        $linkCache->forUpdate( $oldUpdate );
 -              } else {
 -                      if ( $this->mArticleID == -1 ) {
 -                              $this->mArticleID = $linkCache->addLinkObj( $this );
 -                      }
 +              } elseif ( $this->mArticleID == -1 ) {
 +                      $this->mArticleID = $linkCache->addLinkObj( $this );
                }
                return $this->mArticleID;
        }