From 3ed94e8b3e4644317fa4a37fdb494821cc25fb02 Mon Sep 17 00:00:00 2001 From: Brad Jorsch Date: Fri, 8 Aug 2014 11:00:22 +0100 Subject: [PATCH] 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 --- RELEASE-NOTES-1.24 | 1 + includes/api/ApiFormatBase.php | 12 ++++++++++++ includes/api/ApiFormatDbg.php | 3 ++- includes/api/ApiFormatDump.php | 3 ++- includes/api/ApiFormatTxt.php | 3 ++- includes/api/ApiFormatWddx.php | 4 +++- includes/api/ApiFormatYaml.php | 7 ++++++- 7 files changed, 28 insertions(+), 5 deletions(-) diff --git a/RELEASE-NOTES-1.24 b/RELEASE-NOTES-1.24 index 5e440e3971..4344bea249 100644 --- 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 3a0ed46642..2e3fc11014 100644 --- a/includes/api/ApiFormatBase.php +++ b/includes/api/ApiFormatBase.php @@ -338,6 +338,18 @@ See the complete documentation, 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 1b2e02c9ad..61ed18f464 100644 --- 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 62253e1466..7d3224604a 100644 --- 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 4130e70cf2..3de2943d46 100644 --- 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 2e58c720fa..a08c3abc12 100644 --- 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 700d4a5e9d..9f9b0577dd 100644 --- 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(); } } -- 2.20.1