wikimedia/mediawiki-extensions-VisualEditor
1
0
Fork 0
mirror of https://gerrit.wikimedia.org/r/mediawiki/extensions/VisualEditor synced 2024-11-23 14:06:52 +00:00
Code Issues Packages Projects Releases Wiki Activity

doc: Document all public and protected PHP functions

Browse source 
Also move the maintenane script to a name that makes
MediaWiki.Files.ClassMatchesFilename.NotMatch not error,
and use the more restrictive licence tag usage for
MediaWiki.Commenting.LicenseComment.InvalidLicenseTag.

Change-Id: Ifa5518cd590ae83c6fd76f1dbb5a2ce40de4b119
This commit is contained in:
James D. Forrester 2018-03-28 12:47:04 -07:00
parent 0c6e488c2f
commit 31f667ccf7
10 changed files with 244 additions and 13 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

4
.phpcs.xml
View file

@ -1,10 +1,6 @@
<?xml version="1.0"?>
<ruleset>
<rule ref="./vendor/mediawiki/mediawiki-codesniffer/MediaWiki">
<exclude name="MediaWiki.Commenting.FunctionComment.MissingDocumentationProtected" />
<exclude name="MediaWiki.Commenting.FunctionComment.MissingDocumentationPublic" />
<exclude name="MediaWiki.Commenting.LicenseComment.InvalidLicenseTag" />
<exclude name="MediaWiki.Files.ClassMatchesFilename.NotMatch" />
<exclude name="MediaWiki.VariableAnalysis.ForbiddenGlobalVariables.ForbiddenGlobal$wgTitle" />
</rule>
<file>.</file>

2
VisualEditor.i18n.alias.php
View file

@ -4,6 +4,8 @@
*
* @file
* @ingroup Extensions
* @copyright 2011-2018 VisualEditor Team and others; see AUTHORS.txt
* @license MIT
*/
$specialPageAliases = [];

2
VisualEditor.php
View file

@ -9,7 +9,7 @@
* @file
* @ingroup Extensions
* @copyright 2011-2018 VisualEditor Team and others; see AUTHORS.txt
* @license The MIT License (MIT); see LICENSE.txt
* @license MIT
*/
if ( function_exists( 'wfLoadExtension' ) ) {

62
includes/ApiVisualEditor.php
View file

@ -5,7 +5,7 @@
* @file
* @ingroup Extensions
* @copyright 2011-2018 VisualEditor Team and others; see AUTHORS.txt
* @license The MIT License (MIT); see LICENSE.txt
* @license MIT
*/
use MediaWiki\MediaWikiServices;
@ -21,6 +21,9 @@ class ApiVisualEditor extends ApiBase {
*/
protected $serviceClient;
/**
* @inheritDoc
*/
public function __construct( ApiMain $main, $name, Config $config ) {
parent::__construct( $main, $name );
$this->veConfig = $config;
@ -73,6 +76,15 @@ class ApiVisualEditor extends ApiBase {
return new $class( $params );
}
/**
* Accessor function for all RESTbase requests
*
* @param string $method The HTTP method, either 'GET' or 'POST'
* @param string $path The RESTbase api path
* @param Array $params Request parameters
* @param Array $reqheaders Request headers
* @return string Body of the RESTbase server's response
*/
protected function requestRestbase( $method, $path, $params, $reqheaders = [] ) {
global $wgVersion;
$request = [
@ -117,6 +129,13 @@ class ApiVisualEditor extends ApiBase {
return $response['body'];
}
/**
* Run wikitext through the parser's Pre-Save-Transform
*
* @param string $title The title of the page to use as the parsing context
* @param string $wikitext The wikitext to transform
* @return string The transformed wikitext
*/
protected function pstWikitext( $title, $wikitext ) {
return ContentHandler::makeContent( $wikitext, $title, CONTENT_MODEL_WIKITEXT )
->preSaveTransform(
@ -127,6 +146,14 @@ class ApiVisualEditor extends ApiBase {
->serialize( 'text/x-wiki' );
}
/**
* Provide the RESTbase-parsed HTML of a given fragment of wikitext
*
* @param string $title The title of the page to use as the parsing context
* @param string $wikitext The wikitext fragment to parse
* @param bool $bodyOnly Whether to provide only the contents of the `<body>` tag
* @return string The parsed content HTML
*/
protected function parseWikitextFragment( $title, $wikitext, $bodyOnly ) {
return $this->requestRestbase(
'POST',
@ -138,6 +165,15 @@ class ApiVisualEditor extends ApiBase {
);
}
/**
* Provide the preload content for a page being created from another page
*
* @param string $preload The title of the page to use as the preload content
* @param string[] $params The preloadTransform parameters to pass in, if any
* @param string $contextTitle The contextual page title against which to parse the preload
* @param bool $parse Whether to parse the preload content
* @return string The parsed content
*/
protected function getPreloadContent( $preload, $params, $contextTitle, $parse = false ) {
$content = '';
$preloadTitle = Title::newFromText( $preload );
@ -169,6 +205,12 @@ class ApiVisualEditor extends ApiBase {
return $content;
}
/**
* Provide the current language links for a given page title
*
* @param string $title The page title for which to get the current language links
* @return string[] The language links
*/
protected function getLangLinks( $title ) {
$apiParams = [
'action' => 'query',
@ -204,6 +246,9 @@ class ApiVisualEditor extends ApiBase {
return $langlinks;
}
/**
* @inheritDoc
*/
public function execute() {
$this->serviceClient->mount( '/restbase/', $this->getVRSObject() );
@ -703,6 +748,9 @@ class ApiVisualEditor extends ApiBase {
);
}
/**
* @inheritDoc
*/
public function getAllowedParams() {
return [
'page' => [
@ -735,18 +783,30 @@ class ApiVisualEditor extends ApiBase {
];
}
/**
* @inheritDoc
*/
public function needsToken() {
return false;
}
/**
* @inheritDoc
*/
public function mustBePosted() {
return false;
}
/**
* @inheritDoc
*/
public function isInternal() {
return true;
}
/**
* @inheritDoc
*/
public function isWriteMode() {
return false;
}

97
includes/ApiVisualEditorEdit.php
View file

@ -5,7 +5,7 @@
* @file
* @ingroup Extensions
* @copyright 2011-2018 VisualEditor Team and others; see AUTHORS.txt
* @license The MIT License (MIT); see LICENSE.txt
* @license MIT
*/
use \MediaWiki\Logger\LoggerFactory;
@ -13,10 +13,21 @@ use MediaWiki\MediaWikiServices;
class ApiVisualEditorEdit extends ApiVisualEditor {
/**
* @inheritDoc
*/
public function __construct( ApiMain $main, $name, Config $config ) {
parent::__construct( $main, $name, $config );
}
/**
* Attempt to save a given page's wikitext to MediaWiki's storage layer via its API
*
* @param string $title The title of the page to write
* @param string $wikitext The wikitext to write
* @param array $params The edit parameters
* @return Status The result of the save attempt
*/
protected function saveWikitext( $title, $wikitext, $params ) {
$apiParams = [
'action' => 'edit',
@ -60,6 +71,12 @@ class ApiVisualEditorEdit extends ApiVisualEditor {
return $api->getResult()->getResultData();
}
/**
* Load into an array the output of MediaWiki's parser for a given revision
*
* @param int $newRevId The revision to load
* @return array The parsed of the save attempt
*/
protected function parseWikitext( $newRevId ) {
$apiParams = [
'action' => 'parse',
@ -118,6 +135,12 @@ class ApiVisualEditorEdit extends ApiVisualEditor {
];
}
/**
* Attempt to compress a given text string via deflate
*
* @param string $content The string to compress
* @return string The compressed string, or the original if deflating failed
*/
public static function tryDeflate( $content ) {
if ( substr( $content, 0, 11 ) === 'rawdeflate,' ) {
$deflated = base64_decode( substr( $content, 11 ) );
@ -137,6 +160,14 @@ class ApiVisualEditorEdit extends ApiVisualEditor {
return $content;
}
/**
* Create and load the parsed wikitext of an edit, or from the serialisation cache if available.
*
* @param string $title The title of the page
* @param array $params The edit parameters
* @param array $parserParams The parser parameters
* @return string The wikitext of the edit
*/
protected function getWikitext( $title, $params, $parserParams ) {
if ( $params['cachekey'] !== null ) {
$wikitext = $this->trySerializationCache( $params['cachekey'] );
@ -149,6 +180,14 @@ class ApiVisualEditorEdit extends ApiVisualEditor {
return $wikitext;
}
/**
* Create and load the parsed wikitext of an edit, ignoring the serialisation cache.
*
* @param string $title The title of the page
* @param array $params The edit parameters
* @param array $parserParams The parser parameters
* @return string The wikitext of the edit
*/
protected function getWikitextNoCache( $title, $params, $parserParams ) {
$this->requireOnlyOneParameter( $params, 'html' );
$wikitext = $this->postHTML(
@ -160,6 +199,13 @@ class ApiVisualEditorEdit extends ApiVisualEditor {
return $wikitext;
}
/**
* Load the parsed wikitext of an edit into the serialisation cache.
*
* @param string $title The title of the page
* @param string $wikitext The wikitext of the edit
* @return string The key of the wikitext in the serialisation cache
*/
protected function storeInSerializationCache( $title, $wikitext ) {
global $wgMemc;
@ -189,12 +235,28 @@ class ApiVisualEditorEdit extends ApiVisualEditor {
return $hash;
}
/**
* Load some parsed wikitext of an edit from the serialisation cache.
*
* @param string $hash The key of the wikitext in the serialisation cache
* @return string|null The wikitext
*/
protected function trySerializationCache( $hash ) {
global $wgMemc;
$key = wfMemcKey( 'visualeditor', 'serialization', $hash );
return $wgMemc->get( $key );
}
/**
* Transform HTML to wikitext via Parsoid through RESTbase.
*
* @param string $path The RESTbase path of the transform endpoint
* @param string $title The title of the page
* @param array $data An array of the HTML and the 'scrub_wikitext' option
* @param array $parserParams Parsoid parser paramters to pass in
* @param string $etag The ETag to set in the HTTP request header
* @return string Body of the RESTbase server's response
*/
protected function postData( $path, $title, $data, $parserParams, $etag ) {
$path .= urlencode( $title->getPrefixedDBkey() );
if ( isset( $parserParams['oldid'] ) && $parserParams['oldid'] ) {
@ -206,6 +268,15 @@ class ApiVisualEditorEdit extends ApiVisualEditor {
);
}
/**
* Transform HTML to wikitext via Parsoid through RESTbase. Wrapper for ::postData().
*
* @param string $title The title of the page
* @param string $html The HTML of the page to be transformed
* @param array $parserParams Parsoid parser paramters to pass in
* @param string $etag The ETag to set in the HTTP request header
* @return string Body of the RESTbase server's response
*/
protected function postHTML( $title, $html, $parserParams, $etag ) {
return $this->postData(
'transform/html/to/wikitext/', $title,
@ -213,6 +284,15 @@ class ApiVisualEditorEdit extends ApiVisualEditor {
);
}
/**
* Calculate the different between the wikitext of an edit and an existing revision.
*
* @param string $title The title of the page
* @param int $fromId The existing revision of the page to compare with
* @param string $wikitext The wikitext to compare against
* @param int|null $section Whether the wikitext refers to a given section or the whole page
* @return array The comparison, or `[ 'result' => 'nochanges' ]` if there are none
*/
protected function diffWikitext( $title, $fromId, $wikitext, $section = null ) {
$apiParams = [
'action' => 'compare',
@ -259,6 +339,9 @@ class ApiVisualEditorEdit extends ApiVisualEditor {
}
}
/**
* @inheritDoc
*/
public function execute() {
$this->serviceClient->mount( '/restbase/', $this->getVRSObject() );
@ -399,6 +482,9 @@ class ApiVisualEditorEdit extends ApiVisualEditor {
$this->getResult()->addValue( null, $this->getModuleName(), $result );
}
/**
* @inheritDoc
*/
public function getAllowedParams() {
return [
'paction' => [
@ -433,14 +519,23 @@ class ApiVisualEditorEdit extends ApiVisualEditor {
];
}
/**
* @inheritDoc
*/
public function needsToken() {
return 'csrf';
}
/**
* @inheritDoc
*/
public function mustBePosted() {
return true;
}
/**
* @inheritDoc
*/
public function isWriteMode() {
return true;
}

21
includes/SpecialCollabPad.php
View file

@ -1,4 +1,13 @@
<?php
/**
* CollabPad special page
*
* @file
* @ingroup Extensions
* @copyright 2011-2018 VisualEditor Team and others; see AUTHORS.txt
* @license MIT
*/
class SpecialCollabPad extends SpecialPage {
private $prefixes = [];
@ -16,20 +25,32 @@ class SpecialCollabPad extends SpecialPage {
parent::__construct( 'CollabPad' );
}
/**
* @inheritDoc
*/
protected function getGroupName() {
return 'wiki';
}
/**
* @inheritDoc
*/
public function userCanExecute( User $user ) {
global $wgVisualEditorRebaserURL;
return !!$wgVisualEditorRebaserURL && parent::userCanExecute( $user );
}
/**
* @inheritDoc
*/
public function isListed() {
global $wgVisualEditorRebaserURL;
return !!$wgVisualEditorRebaserURL;
}
/**
* @inheritDoc
*/
public function execute( $par ) {
$this->setHeaders();
$this->checkPermissions();

15
includes/VisualEditorDataModule.php
View file

@ -5,7 +5,7 @@
* @file
* @ingroup Extensions
* @copyright 2011-2018 VisualEditor Team and others; see AUTHORS.txt
* @license The MIT License (MIT); see LICENSE.txt
* @license MIT
*/
class VisualEditorDataModule extends ResourceLoaderModule {
@ -43,6 +43,11 @@ class VisualEditorDataModule extends ResourceLoaderModule {
) . ');';
}
/**
* @param ResourceLoaderContext $context Object containing information about the state of this
* specific loader request.
* @return string[] Messages in various states of parsing
*/
protected function getMessageInfo( ResourceLoaderContext $context ) {
$editSubmitButtonLabelPublish = $context->getResourceLoader()->getConfig()
->get( 'EditSubmitButtonLabelPublish' );
@ -85,10 +90,18 @@ class VisualEditorDataModule extends ResourceLoaderModule {
];
}
/**
* @inheritDoc
*
* Always true.
*/
public function enableModuleContentVersion() {
return true;
}
/**
* @inheritDoc
*/
public function getDependencies( ResourceLoaderContext $context = null ) {
return [
'ext.visualEditor.base',

5
includes/VisualEditorDesktopArticleTargetInitModule.php
View file

@ -7,11 +7,14 @@
* @file
* @ingroup Extensions
* @copyright 2011-2018 VisualEditor Team and others; see AUTHORS.txt
* @license The MIT License (MIT); see LICENSE.txt
* @license MIT
*/
class VisualEditorDesktopArticleTargetInitModule extends ResourceLoaderFileModule {
/**
* @inheritDoc
*/
public function __construct(
$options = [],
$localBasePath = null,

37
includes/VisualEditorHooks.php
View file

@ -5,7 +5,7 @@
* @file
* @ingroup Extensions
* @copyright 2011-2018 VisualEditor Team and others; see AUTHORS.txt
* @license The MIT License (MIT); see LICENSE.txt
* @license MIT
*/
use MediaWiki\MediaWikiServices;
@ -36,6 +36,13 @@ class VisualEditorHooks {
}
}
/**
* Factory to return the relevant API class
*
* @param ApiMain $main The ApiMain instance
* @param string $name The api request name
* @return ApiVisualEditor|ApiVisualEditorEdit API class
*/
public static function getVisualEditorApiFactory( $main, $name ) {
$config = ConfigFactory::getDefaultInstance()->makeConfig( 'visualeditor' );
$class = $name === 'visualeditor' ? 'ApiVisualEditor' : 'ApiVisualEditorEdit';
@ -75,6 +82,14 @@ class VisualEditorHooks {
return true;
}
/**
* Handler for the DiffViewHeader hook, to add visual diffs code as configured
*
* @param DifferenceEngine $diff The difference engine
* @param Revision $oldRev The old revision
* @param Revision $newRev The new revision
* @return bool Always true
*/
public static function onDiffViewHeader(
DifferenceEngine $diff,
Revision $oldRev = null,
@ -631,6 +646,13 @@ class VisualEditorHooks {
}
}
/**
* Handler for the GetPreferences hook, to add and hide user preferences as configured
*
* @param User $user The user object
* @param array &$preferences Their preferences object
* @return bool Always true
*/
public static function onGetPreferences( User $user, array &$preferences ) {
global $wgLang;
$veConfig = ConfigFactory::getDefaultInstance()->makeConfig( 'visualeditor' );
@ -717,6 +739,12 @@ class VisualEditorHooks {
return true;
}
/**
* Handler for the GetBetaPreferences hook, to add and hide user beta preferences as configured
*
* @param User $user The user object
* @param array &$preferences Their preferences object
*/
public static function onGetBetaPreferences( User $user, array &$preferences ) {
$coreConfig = RequestContext::getMain()->getConfig();
$iconpath = $coreConfig->get( 'ExtensionAssetsPath' ) . "/VisualEditor/images";
@ -971,6 +999,13 @@ class VisualEditorHooks {
return true;
}
/**
* Handler for the ResourceLoaderTestModules hook given we can't do this statically yet.
*
* @param array &$testModules The ResourceLoader test modules array
* @param ResourceLoader &$resourceLoader The ResourceLoader controller
* @return bool Always true
*/
public static function onResourceLoaderTestModules(
array &$testModules,
ResourceLoader &$resourceLoader

12
maintenance/autodisablePref.php → maintenance/AutodisableVisualEditorPref.php
View file

@ -3,7 +3,7 @@
* Sets the VisualEditor autodisable preference on appropriate users.
*
* @copyright 2011-2018 VisualEditor Team and others; see AUTHORS.txt
* @license The MIT License (MIT); see LICENSE.txt
* @license MIT
* @author Alex Monk <amonk@wikimedia.org>
* @file
* @ingroup Extensions
@ -16,7 +16,10 @@ $maintenancePath = getenv( 'MW_INSTALL_PATH' ) !== false
require_once $maintenancePath;
class VEAutodisablePref extends Maintenance {
class AutodisableVisualEditorPref extends Maintenance {
/**
* @inheritDoc
*/
public function __construct() {
parent::__construct();
$this->requireExtension( 'VisualEditor' );
@ -24,6 +27,9 @@ class VEAutodisablePref extends Maintenance {
$this->setBatchSize( 500 );
}
/**
* @inheritDoc
*/
public function execute() {
$dbr = wfGetDB( DB_REPLICA );
@ -64,5 +70,5 @@ class VEAutodisablePref extends Maintenance {
}
}
$maintClass = "VEAutodisablePref";
$maintClass = "AutodisableVisualEditorPref";
require_once RUN_MAINTENANCE_IF_MAIN;