在error_reporting为ON的doc注释中使用@class标记时出现Luracast Restler错误

Question

I have a REST webservice implemented in PHP using Luracast Restler API.

If I add any @class tags to the doc comments in my custom class exposing the public API methods or in the class implementing the iAuthenticate methods performing authentication, restler fails to parse the request if error reporting is ON.

I think the problem is the DocParser class tries to proccess the @class tag as if t where the PHP Class declaration. The method of the class formatClass() generates an undefined index notice. If error reporting is ON this will send headers, so when later Restler tries to send the response it will no be able to change headers to indicate that JSON content is sent and the Cannot modify header information - headers already sent is triggered.

Is there any workaround to this or is just a bug in the Restler Api? (Apart from setting my error reporting level to avoid Notices from being sent).

Answer 1

---

Update: It is fixed in Restler 2.1.5

---

It is a bug that exists in Restler 2.1.4 caused by the DocParser as it expects @class comment in a specific format, as shown below

/**
 * @class ClassName(property=value&property2=value2)
 */

It is used to set a property of another class after initialization. for example, we can use it to tell the XmlFormat to set the root name, define what should be converted as attribute etc., Lets take the known BMI example, adding the PHPDoc comment as shown below,

<?php
class BMI {
    /**
    * @class XmlFormat(root_name=self&attribute_names=height,weight)
    */
    function index($height=162.6, $weight=84) {
        $result = new stdClass();
        $cm = $height;
        $kg = $weight;

        $meter = $cm / 100;
        $inches = $meter * 39.3700787;
        $feet = round($inches/12);
        $inches = $inches % 12; 

        $result->bmi = round($kg/($meter*$meter),2);
        $lb = round($kg/0.45359237,2);

        if($result->bmi<18.5){
            $result->message = 'Underweight';
        }elseif ($result->bmi<=24.9){
            $result->message = 'Normal weight';
        }elseif ($result->bmi<=29.9){
            $result->message = 'Overweight';
        }else{
            $result->message = 'Obesity';
        }
        $result->metric = array('height'=>"$cm centimeter", 'weight'=>"$weight kilograms");
        $result->imperial = array('height'=>"$feet feet $inches inches", 'weight'=>"$lb pounds");
        return $result;
    }
}

returns the following XML

<?xml version="1.0"?>
<self>
    <bmi>31.77</bmi>
    <message>Obesity</message>
    <metric height="162.6 centimeter" weight="84 kilograms"/>
    <imperial height="5 feet 4 inches" weight="185.19 pounds"/>
</self>

Which otherwise will be

<?xml version="1.0"?>
<response>
  <bmi>31.77</bmi>
  <message>Obesity</message>
  <metric>
    <height>162.6 centimeter</height>
    <weight>84 kilograms</weight>
  </metric>
  <imperial>
    <height>5 feet 4 inches</height>
    <weight>185.19 pounds</weight>
  </imperial>
</response>

More use cases and explanations can be found here

It should not throw the error when @class is defined in unexpected format. We will fix it in the next release.