*/
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.
}
/**
- * 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(),
* 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
* 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
/**
* 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() {
<?php
+use MediaWiki\Linker\LinkTarget;
use MediaWiki\MediaWikiServices;
/**
$this->assertEquals( $value->getFragment(), $title->getFragment() );
}
+ /**
+ * @covers Title::newFromLinkTarget
+ * @dataProvider provideNewFromTitleValue
+ */
+ public function testNewFromLinkTarget( LinkTarget $value ) {
+ $title = Title::newFromLinkTarget( $value );
+
+ $dbkey = str_replace( ' ', '_', $value->getText() );
+ $this->assertEquals( $dbkey, $title->getDBkey() );
+ $this->assertEquals( $value->getNamespace(), $title->getNamespace() );
+ $this->assertEquals( $value->getFragment(), $title->getFragment() );
+ }
+
+ /**
+ * @covers Title::newFromLinkTarget
+ */
+ public function testNewFromLinkTarget_clone() {
+ $title = Title::newFromText( __METHOD__ );
+ $this->assertSame( $title, Title::newFromLinkTarget( $title ) );
+
+ // The Title::NEW_CLONE flag should ensure that a fresh instance is returned.
+ $clone = Title::newFromLinkTarget( $title, Title::NEW_CLONE );
+ $this->assertNotSame( $title, $clone );
+ $this->assertTrue( $clone->equals( $title ) );
+ }
+
public static function provideGetTitleValue() {
return [
[ 'Foo' ],