Add LinkRenderer (rewrite of Linker::link())

This is a rewrite of Linker::link() to a non-static, LinkTarget-based
interface. Users of plain Linker::link() with no options can use the
LinkRenderer instance provided by MediaWikiServices. Others that
have specific options should create and configure their own instance,
which can be used to create as many links as necessary.

The main entrypoints for making links are:
* ->makeLink( $target, $text, $attribs, $query );
* ->makeKnownLink( $target, $text, $attribs, $query );
* ->makeBrokenLink( $target, $text, $attribs, $query );

The order of the parameters are the same as Linker::link(), except
$options are now part of the LinkRenderer instance, and
known/broken status requires calling the function explicitly.
Additionally, instead of passing in raw $html for the link text, the
$text parameter will automatically be escaped unless it is specially
marked as safe HTML using the MediaWiki\Linker\HtmlArmor class.

The LinkBegin and LinkEnd hooks are now deprecated, but still function
for backwards-compatability. Clients should migrate to the nearly-
equivalent LinkRendererBegin and LinkRendererEnd hooks.
The main differences between the hooks are:
* Passing HtmlPageLinkRenderer object instead of deprecated DummyLinker
* Using LinkTarget instead of Title
* Begin hook can no longer change known/broken status of link. Use the
TitleIsAlwaysKnown hook for that.
* $options are no longer passed, they can be read (but shouldn't be
modified!) from the LinkRenderer object.

Bug: T469
Change-Id: I057cc86ae6404a080aa3c8e0e956ecbb10a897d5

1 files changed, 56 insertions, 0 deletions

diff --git a/includes/libs/HtmlArmor.php b/includes/libs/HtmlArmor.php
new file mode 100644
index 000000000000..511e1c985a62
--- /dev/null
+++ b/includes/libs/HtmlArmor.php
@@ -0,0 +1,56 @@
+<?php
+/**
+ * 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
+ * @license GPL-2.0+
+ * @author Kunal Mehta <legoktm@member.fsf.org>
+ */
+
+/**
+ * Marks HTML that shouldn't be escaped
+ *
+ * @since 1.28
+ */
+class HtmlArmor {
+
+	/**
+	 * @var string
+	 */
+	private $value;
+
+	/**
+	 * @param string $value
+	 */
+	public function __construct( $value ) {
+		$this->value = $value;
+	}
+
+	/**
+	 * Provide a string or HtmlArmor object
+	 * and get safe HTML back
+	 *
+	 * @param string|HtmlArmor $input
+	 * @return string safe for usage in HTML
+	 */
+	public static function getHtml( $input ) {
+		if ( $input instanceof HtmlArmor ) {
+			return $input->value;
+		} else {
+			return htmlspecialchars( $input );
+		}
+	}
+}