Split parser related files to have one class in one file

[lhc/web/wiklou.git] / includes / Title.php

diff --git a/includes/Title.php b/includes/Title.php
index b05e170..27baeb2 100644 (file)
--- a/includes/Title.php
+++ b/includes/Title.php
@@ -58,6 +58,8 @@ class Title implements LinkTarget, IDBAccessObject {
         * 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.
+        *
+        * @since 1.33
         */
        const NEW_CLONE = 'clone';
 
@@ -244,6 +246,8 @@ class Title implements LinkTarget, IDBAccessObject {
         * 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.
         *
+        * @deprecated since 1.34, use newFromLinkTarget or castFromLinkTarget
+        *
         * @param TitleValue $titleValue Assumed to be safe.
         * @param string $forceClone set to NEW_CLONE to ensure a fresh instance is returned.
         *
@@ -281,6 +285,17 @@ class Title implements LinkTarget, IDBAccessObject {
                );
        }
 
+       /**
+        * Same as newFromLinkTarget, but if passed null, returns null.
+        *
+        * @param LinkTarget|null $linkTarget Assumed to be safe (if not null).
+        *
+        * @return Title|null
+        */
+       public static function castFromLinkTarget( $linkTarget ) {
+               return $linkTarget ? self::newFromLinkTarget( $linkTarget ) : null;
+       }
+
        /**
         * Create a new Title from text, such as what one would find in a link. De-
         * codes any HTML entities in the text.
@@ -621,15 +636,33 @@ class Title implements LinkTarget, IDBAccessObject {
        /**
         * Create a new Title for the Main Page
         *
+        * This uses the 'mainpage' interface message, which could be specified in
+        * `$wgForceUIMsgAsContentMsg`. If that is the case, then calling this method
+        * will use the user language, which would involve initialising the session
+        * via `RequestContext::getMain()->getLanguage()`. For session-less endpoints,
+        * be sure to pass in a MessageLocalizer (such as your own RequestContext,
+        * or ResourceloaderContext) to prevent an error.
+        *
         * @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
+        * @param MessageLocalizer|null $localizer An optional context to use (since 1.34)
+        * @return Title
         */
-       public static function newMainPage() {
-               $title = self::newFromText( wfMessage( 'mainpage' )->inContentLanguage()->text() );
-               // Don't give fatal errors if the message is broken
+       public static function newMainPage( MessageLocalizer $localizer = null ) {
+               if ( $localizer ) {
+                       $msg = $localizer->msg( 'mainpage' );
+               } else {
+                       $msg = wfMessage( 'mainpage' );
+               }
+
+               $title = self::newFromText( $msg->inContentLanguage()->text() );
+
+               // Every page renders at least one link to the Main Page (e.g. sidebar).
+               // If the localised value is invalid, don't produce fatal errors that
+               // would make the wiki inaccessible (and hard to fix the invalid message).
+               // Gracefully fallback...
                if ( !$title ) {
                        $title = self::newFromText( 'Main Page' );
                }
@@ -2063,8 +2096,8 @@ class Title implements LinkTarget, IDBAccessObject {
         * protocol-relative, the URL will be expanded to http://
         *
         * @see self::getLocalURL for the arguments.
-        * @param string $query
-        * @param string|bool $query2
+        * @param string|string[] $query
+        * @param string|bool $query2 Deprecated
         * @return string The URL
         */
        public function getInternalURL( $query = '', $query2 = false ) {
@@ -2086,8 +2119,8 @@ class Title implements LinkTarget, IDBAccessObject {
         * NOTE: Unlike getInternalURL(), the canonical URL includes the fragment
         *
         * @see self::getLocalURL for the arguments.
-        * @param string $query
-        * @param string|bool $query2
+        * @param string|string[] $query
+        * @param string|bool $query2 Deprecated
         * @return string The URL
         * @since 1.18
         */