API: Document parameter types

[lhc/web/wiklou.git] / includes / api / ApiMain.php

diff --git a/includes/api/ApiMain.php b/includes/api/ApiMain.php
index 1feb485..7e3dcff 100644 (file)
--- a/includes/api/ApiMain.php
+++ b/includes/api/ApiMain.php
@@ -89,6 +89,7 @@ class ApiMain extends ApiBase {
                'imagerotate' => 'ApiImageRotate',
                'revisiondelete' => 'ApiRevisionDelete',
                'managetags' => 'ApiManageTags',
+               'tag' => 'ApiTag',
        );
 
        /**
@@ -139,7 +140,7 @@ class ApiMain extends ApiBase {
         */
        private $mPrinter;
 
-       private $mModuleMgr, $mResult;
+       private $mModuleMgr, $mResult, $mErrorFormatter, $mContinuationManager;
        private $mAction;
        private $mEnableWrite;
        private $mInternalMode, $mSquidMaxage, $mModule;
@@ -217,7 +218,11 @@ class ApiMain extends ApiBase {
 
                Hooks::run( 'ApiMain::moduleManager', array( $this->mModuleMgr ) );
 
-               $this->mResult = new ApiResult( $this );
+               $this->mResult = new ApiResult( $this->getConfig()->get( 'APIMaxResultSize' ) );
+               $this->mErrorFormatter = new ApiErrorFormatter_BackCompat( $this->mResult );
+               $this->mResult->setErrorFormatter( $this->mErrorFormatter );
+               $this->mResult->setMainForContinuation( $this );
+               $this->mContinuationManager = null;
                $this->mEnableWrite = $enableWrite;
 
                $this->mSquidMaxage = -1; // flag for executeActionWithErrorHandling()
@@ -241,6 +246,43 @@ class ApiMain extends ApiBase {
                return $this->mResult;
        }
 
+       /**
+        * Get the ApiErrorFormatter object associated with current request
+        * @return ApiErrorFormatter
+        */
+       public function getErrorFormatter() {
+               return $this->mErrorFormatter;
+       }
+
+       /**
+        * Get the continuation manager
+        * @return ApiContinuationManager|null
+        */
+       public function getContinuationManager() {
+               return $this->mContinuationManager;
+       }
+
+       /**
+        * Set the continuation manager
+        * @param ApiContinuationManager|null
+        */
+       public function setContinuationManager( $manager ) {
+               if ( $manager !== null ) {
+                       if ( !$manager instanceof ApiContinuationManager ) {
+                               throw new InvalidArgumentException( __METHOD__ . ': Was passed ' .
+                                       is_object( $manager ) ? get_class( $manager ) : gettype( $manager )
+                               );
+                       }
+                       if ( $this->mContinuationManager !== null ) {
+                               throw new UnexpectedValueException(
+                                       __METHOD__ . ': tried to set manager from ' . $manager->getSource() .
+                                       ' when a manager is already set from ' . $this->mContinuationManager->getSource()
+                               );
+                       }
+               }
+               $this->mContinuationManager = $manager;
+       }
+
        /**
         * Get the API module object. Only works after executeAction()
         *
@@ -416,7 +458,13 @@ class ApiMain extends ApiBase {
                // Bug 63145: Rollback any open database transactions
                if ( !( $e instanceof UsageException ) ) {
                        // UsageExceptions are intentional, so don't rollback if that's the case
-                       MWExceptionHandler::rollbackMasterChangesAndLog( $e );
+                       try {
+                               MWExceptionHandler::rollbackMasterChangesAndLog( $e );
+                       } catch ( DBError $e2 ) {
+                               // Rollback threw an exception too. Log it, but don't interrupt
+                               // our regularly scheduled exception handling.
+                               MWExceptionHandler::logException( $e2 );
+                       }
                }
 
                // Allow extra cleanup and logging
@@ -778,7 +826,7 @@ class ApiMain extends ApiBase {
                        // User entered incorrect parameters - generate error response
                        $errMessage = $e->getMessageArray();
                        $link = wfExpandUrl( wfScript( 'api' ) );
-                       ApiResult::setContent( $errMessage, "See $link for API usage" );
+                       ApiResult::setContentValue( $errMessage, 'docref', "See $link for API usage" );
                } else {
                        // Something is seriously wrong
                        if ( ( $e instanceof DBQueryError ) && !$config->get( 'ShowSQLErrors' ) ) {
@@ -792,16 +840,16 @@ class ApiMain extends ApiBase {
                                'info' => '[' . MWExceptionHandler::getLogId( $e ) . '] ' . $info,
                        );
                        if ( $config->get( 'ShowExceptionDetails' ) ) {
-                               ApiResult::setContent(
+                               ApiResult::setContentValue(
                                        $errMessage,
+                                       'trace',
                                        MWExceptionHandler::getRedactedTraceAsString( $e )
                                );
                        }
                }
 
                // Remember all the warnings to re-add them later
-               $oldResult = $result->getData();
-               $warnings = isset( $oldResult['warnings'] ) ? $oldResult['warnings'] : null;
+               $warnings = $result->getResultData( array( 'warnings' ) );
 
                $result->reset();
                // Re-add the id
@@ -1184,9 +1232,7 @@ class ApiMain extends ApiBase {
                        $this->setWarning( 'SECURITY WARNING: $wgDebugAPI is enabled' );
                }
 
-               $this->getResult()->cleanUpUTF8();
                $printer = $this->mPrinter;
-
                $printer->initPrinter( false );
                $printer->execute();
                $printer->closePrinter();
@@ -1259,6 +1305,7 @@ class ApiMain extends ApiBase {
                        }
                        $help[$k] = $v;
                }
+               $help['datatypes'] = '';
                $help['credits'] = '';
 
                // Fill 'permissions'
@@ -1291,10 +1338,18 @@ class ApiMain extends ApiBase {
                $help['permissions'] .= Html::closeElement( 'dl' );
                $help['permissions'] .= Html::closeElement( 'div' );
 
-               // Fill 'credits', if applicable
+               // Fill 'datatypes' and 'credits', if applicable
                if ( empty( $options['nolead'] ) ) {
-                       $help['credits'] .= Html::element( 'h' . min( 6, $options['headerlevel'] + 1 ),
-                               array( 'id' => '+credits', 'class' => 'apihelp-header' ),
+                       $help['datatypes'] .= Html::rawelement( 'h' . min( 6, $options['headerlevel'] + 1 ),
+                               array( 'id' => 'main/datatypes', 'class' => 'apihelp-header' ),
+                               Html::element( 'span', array( 'id' => Sanitizer::escapeId( 'main/datatypes' ) ) ) .
+                               $this->msg( 'api-help-datatypes-header' )->parse()
+                       );
+                       $help['datatypes'] .= $this->msg( 'api-help-datatypes' )->parseAsBlock();
+
+                       $help['credits'] .= Html::rawelement( 'h' . min( 6, $options['headerlevel'] + 1 ),
+                               array( 'id' => 'main/credits', 'class' => 'apihelp-header' ),
+                               Html::element( 'span', array( 'id' => Sanitizer::escapeId( 'main/credits' ) ) ) .
                                $this->msg( 'api-credits-header' )->parse()
                        );
                        $help['credits'] .= $this->msg( 'api-credits' )->useDatabase( false )->parseAsBlock();