API: Mark seldom-used formats as deprecated

While it doesn't take a lot to maintain most of these, there is some
effort needed (e.g. wddx was breaking with HHVM). None have much if any
usage that seems likely to be actual code of some sort, and humans
should be able to read the jsonfm format as easily as dbgfm, dumpfm, or
txtfm.

Change-Id: I4e3d2ef59d4306756b289a4be46caef7d359ccef

diff --git a/RELEASE-NOTES-1.24 b/RELEASE-NOTES-1.24
index 5e440e3..4344bea 100644 (file)
--- a/RELEASE-NOTES-1.24
+++ b/RELEASE-NOTES-1.24
@@ -228,6 +228,7 @@ production.
   limited use and are generally inaccurate, unmaintained, and impossible to
   properly maintain. Also removed the corresponding methods from ApiBase and
   the 'APIGetPossibleErrors' and 'APIGetResultProperties' hooks.
+* Formats dbg, dump, txt, wddx, and yaml are now deprecated.
 
 === Languages updated in 1.24 ===
 

diff --git a/includes/api/ApiFormatBase.php b/includes/api/ApiFormatBase.php
index 3a0ed46..2e3fc11 100644 (file)
--- a/includes/api/ApiFormatBase.php
+++ b/includes/api/ApiFormatBase.php
@@ -338,6 +338,18 @@ See the <a href='https://www.mediawiki.org/wiki/API'>complete documentation</a>,
        public function getDescription() {
                return $this->getIsHtml() ? ' (pretty-print in HTML)' : '';
        }
+
+       /**
+        * To avoid code duplication with the deprecation of dbg, dump, txt, wddx,
+        * and yaml, this method is added to do the necessary work. It should be
+        * removed when those deprecated formats are removed.
+        */
+       protected function markDeprecated() {
+               $fm = $this->getIsHtml() ? 'fm' : '';
+               $name = $this->getModuleName();
+               $this->logFeatureUsage( "format=$name" );
+               $this->setWarning( "format=$name has been deprecated. Please use format=json$fm instead." );
+       }
 }
 
 /**

diff --git a/includes/api/ApiFormatDbg.php b/includes/api/ApiFormatDbg.php
index 1b2e02c..61ed18f 100644 (file)
--- a/includes/api/ApiFormatDbg.php
+++ b/includes/api/ApiFormatDbg.php
@@ -38,10 +38,11 @@ class ApiFormatDbg extends ApiFormatBase {
        }
 
        public function execute() {
+               $this->markDeprecated();
                $this->printText( var_export( $this->getResultData(), true ) );
        }
 
        public function getDescription() {
-               return 'Output data in PHP\'s var_export() format' . parent::getDescription();
+               return 'DEPRECATED! Output data in PHP\'s var_export() format' . parent::getDescription();
        }
 }

diff --git a/includes/api/ApiFormatDump.php b/includes/api/ApiFormatDump.php
index 62253e1..7d32246 100644 (file)
--- a/includes/api/ApiFormatDump.php
+++ b/includes/api/ApiFormatDump.php
@@ -38,6 +38,7 @@ class ApiFormatDump extends ApiFormatBase {
        }
 
        public function execute() {
+               $this->markDeprecated();
                ob_start();
                var_dump( $this->getResultData() );
                $result = ob_get_contents();
@@ -46,6 +47,6 @@ class ApiFormatDump extends ApiFormatBase {
        }
 
        public function getDescription() {
-               return 'Output data in PHP\'s var_dump() format' . parent::getDescription();
+               return 'DEPRECATED! Output data in PHP\'s var_dump() format' . parent::getDescription();
        }
 }

diff --git a/includes/api/ApiFormatTxt.php b/includes/api/ApiFormatTxt.php
index 4130e70..3de2943 100644 (file)
--- a/includes/api/ApiFormatTxt.php
+++ b/includes/api/ApiFormatTxt.php
@@ -38,10 +38,11 @@ class ApiFormatTxt extends ApiFormatBase {
        }
 
        public function execute() {
+               $this->markDeprecated();
                $this->printText( print_r( $this->getResultData(), true ) );
        }
 
        public function getDescription() {
-               return 'Output data in PHP\'s print_r() format' . parent::getDescription();
+               return 'DEPRECATED! Output data in PHP\'s print_r() format' . parent::getDescription();
        }
 }

diff --git a/includes/api/ApiFormatWddx.php b/includes/api/ApiFormatWddx.php
index 2e58c72..a08c3ab 100644 (file)
--- a/includes/api/ApiFormatWddx.php
+++ b/includes/api/ApiFormatWddx.php
@@ -35,6 +35,8 @@ class ApiFormatWddx extends ApiFormatBase {
        }
 
        public function execute() {
+               $this->markDeprecated();
+
                // Some versions of PHP have a broken wddx_serialize_value, see
                // PHP bug 45314. Test encoding an affected character (U+00A0)
                // to avoid this.
@@ -107,6 +109,6 @@ class ApiFormatWddx extends ApiFormatBase {
        }
 
        public function getDescription() {
-               return 'Output data in WDDX format' . parent::getDescription();
+               return 'DEPRECATED! Output data in WDDX format' . parent::getDescription();
        }
 }

diff --git a/includes/api/ApiFormatYaml.php b/includes/api/ApiFormatYaml.php
index 700d4a5..9f9b057 100644 (file)
--- a/includes/api/ApiFormatYaml.php
+++ b/includes/api/ApiFormatYaml.php
@@ -34,7 +34,12 @@ class ApiFormatYaml extends ApiFormatJson {
                return 'application/yaml';
        }
 
+       public function execute() {
+               $this->markDeprecated();
+               parent::execute();
+       }
+
        public function getDescription() {
-               return 'Output data in YAML format' . ApiFormatBase::getDescription();
+               return 'DEPRECATED! Output data in YAML format' . ApiFormatBase::getDescription();
        }
 }