Does PHPCodeSniffer generates HTML Report?
If not? How?
Currently, I can run PHPCodeSniffer but it only produce XML file and displays result in the terminal.
How can I make produce HTML Report like the coverage and unit test report in phpunit.
Currently I use PHPCheckStyle since it produces html report, but i want also to try PHPCodeSniffer to know which is best.
Another solution (but maybe not the simplest one) is to use a continuous integration system that provides PHP code sniffer integration.
For example, phpUnderControl provides a nice interface to see the report.
HTML Reporting is not provided yet. However there is a workaround to get the job done.
You can export the report to XML and read the data with DOM Parser and generate an HTML version on your own. Here is a quick tutorial to get you started.
Writing your own report is pretty trivial actually.
If you are running from CLI you can implement your own report class with a unique method and call it from command ligne. For a report named Xxx :
class PHP_CodeSniffer_Reports_Xxx implements PHP_CodeSniffer_Report
{
/**
* Prints all errors and warnings for each file processed.
*
* Errors and warnings are displayed together, grouped by file.
*
* #param array $report Prepared report.
* #param boolean $showSources Show sources?
* #param int $width Maximum allowed lne width.
* #param boolean $toScreen Is the report being printed to screen?
*
* #return string
*/
public function generate(
$report,
$showSources=false,
$width=80,
$toScreen=true
) {
...
}
}
If your are running from a web server, the PHP_CodeSniffer.getFilesErrors() method gives you a nice array of errors with all you need to produce a report.
HTML Reporting is working for me. Just use according --help:
phpcs src/AppBundle --generator=HTML > index.html
Show the result in index.html
Related
Background: I have installed composer installed zircote/swagger-php and have installed openapi-generator-cli with apt-get.
I am not sure whether or not I am attempting to use these tools correctly, however I've been unable to find documentation pointing me in any direction.
I have a controller file with a whole bunch of code in it. I want to test whether or not I can generate a json file from it using open api annotation.
Here's a sample of my code (I've cut out unrelated chunks of it):
<?php
/**
* #OA\Info(title="My First API", version="0.1")
*/
class Apiv1_LocationController extends App_Controller_API
{
/* Publicly exposed attributes and the field type for filtering */
protected $_exported = array('id','created','modified','name','address','phone','external_id','postcode','country','timezone','date_format','lacps','staff_count');
protected $_schematypes = array(
'string' => ['name','address','phone','external_id','postcode','country','timezone','date_format'],
'int' => ['id','staff_count'],
'timestamp' => ['created','modified'],
'complex'=> ['lacps'],
);
{more unrelated code...}
/**
* #OA\Get(
* path="/api/resource.json",
* #OA\Response(response="200", description="An example resource")
* )
*/
public function getAction()
{
{code inside action...}
}
}
The cli command I use:
openapi-generator-cli generate -g php -i <path_to_LocationController>
I get the following error:
[main] INFO o.o.c.ignore.CodegenIgnoreProcessor - No .openapi-generator-ignore file found.
Exception in thread "main" java.lang.RuntimeException: Issues with the OpenAPI input. Possible causes: invalid/missing spec, malformed JSON/YAML files, etc.
This leads me to believe I am using the openapi-generator-cli tool incorrectly, since I wouldn't be expecting to need a JSON or YAML file, I am trying to generate that file.
I'll keep trying, but if someone could help me realized what I'm doing wrong or how I'm misunderstanding the tool, I'd really appreciate it.
So I realized I'd been going about this in entirely the wrong way.
I used the zircote/swagger-php library to generate the JSON file I required with the following command (In the directory where I wanted the JSON to be generated):
./<path_to_vendor_directory>/vendor/zircote/swagger-php/bin/openapi --pattern "*Controller.php" --output <name_of_file>.json --format json <location_to_search_from_recursively>
I am trying to make the Restful API documentation in PHP swagger, what I did before is that I changed the JSON to work out, now I know we can make the JSON by making PHP files and using swagger notation. I did check the Pet.php example and I get the code but I don't know how to execute the file to get the JSON API documentation which I can link with my Swagger UI. I read the documentation but it is so confusing and I don't know how to get through this problem can anyone help, please? Here is the link I study but to no worth.
https://github.com/zircote/swagger-php
Swagger-PHP for generating JSON file for Swagger-UI
Can anyone tell me step-by-step how to generate the API documentation in JSON? I will be very thankful to him thanks.
There are two way to achieve this in swagger-php 2.0.
I.
The first solution is to create a controller or script which will generate the documentation on each request. This is a good solution in a development environment where you want to see quickly the outcome of your changes.
Here is an example of a controller which does this.
<?php
namespace Controllers;
use Swagger\Annotations as SWG;
use Swagger;
/**
* #SWG\Swagger(
* basePath="/path/to/opration/",
* produces={"application/json"},
* swagger="2.0",
* #SWG\Info(
* version="1.0.0",
* title="My API"
* )
* )
*
*/
class Documentation {
const API_PATH = "path/to/my/documented/files/";
public function show(){
$swagger = Swagger\scan(self::API_PATH);
return json_enconde($swagger); //you can echo this in the calling script.
}
}
Note: The example above assumes you installed Swagger-php with Composer and that the calling script include the composer generated autoload file (usually called: vendor/autoload.php).
II.
The first solution consisting of generating a static json API documentation is described here: https://stackoverflow.com/a/21380432/2853903
This solution recommended for production deployment, where you would not want to regenerate the documentation on every request.
I've installed phpDoc on our server, set up etc. It's producing documentation correctly.
We're using the 'Responsive' template, however this error occurs regardless of the template used.
Under the 'Errors', each file scanned seems to have the following error:
Type Line Description
error 0 No summary was found for this file
I've googled exhaustively for this, and can't find a solution. I've even gone through the effort of tracking down the server error code behind the message PPC:ERR-50000 and attempting to track back the condition which causes the error, but got a bit lost.
My Question:
What does this error mean? Why is it on line 0, and how the hell do I get rid of it?! Even if I have done the docblock correctly, can I hide this error? My error-free ocd is going crazy!
Many thanks
EDIT
Some extra information: Each of my files have the following docblock from line 1 of the file:
<?php
/**
* Short Description
*
* Long Description
*
* #package Some Package
* #subpackage Some Subpackage
* #category Some Category
* #author F Bloggs <gbloggs#email.com>
*/
?>
But does the top of your file have two such docblocks? The first docblock is expected to be the one for the file itself, and a second docblock should pair up with the first documentable code element that appears after it.
However, if you only have one docblock at the top of the file, it will get paired up with the first code element found, thus the "file itself" will seem to be missing its docblock. That is what that error is supposed to indicate.
#ashnazg is right but I want to improve your answer with an example.
A File-level DocBlock should be the first docblock and must have a Summary (in this example the summary is "Class Category | core/Category.class.php").
Then a Class-level DocBlock is placed before a class definition.
<?php
/**
* Class Category | core/Category.class.php
*
* #package MyApp XYZ
* #subpackage Categories
* #author Sandro Miguel Marques <sandromiguel#something.com>
* #version v.1.1 (06/12/2016)
* #copyright Copyright (c) 2016, Sandro
*/
namespace Myapp;
use \PDO;
use \Exception;
use \PDOException;
/**
* Class Category - active record
*
* Recipe categories
*/
class Category {
...
So after a lot of searching on the server, I have a semi-fix for the problem should anyone else be encountering the same issue.
I've found out how to hide the error from the documentation, but not what is causing it.
If the error you are receiving is on Line 0, and is no summary found for this file, then you will need to edit the following file:
phpDocumentor/src/phpDocumentor/Plugin/Core/Transformer/Writer/xml.php
You will then need to search for the protected method: createErrorEntry()
This is what the existing method looks like:
protected function createErrorEntry($error, $parse_errors)
{
$marker_obj = new \DOMElement(strtolower($error->getSeverity()));
$parse_errors->appendChild($marker_obj);
$message = ($this->getTranslator())
? vsprintf($this->getTranslator()->translate($error->getCode()), $error->getContext())
: $error->getCode();
$marker_obj->appendChild(new \DOMText($message));
$marker_obj->setAttribute('line', $error->getLine());
$marker_obj->setAttribute('code', $error->getCode());
}
This method needs to have an IF condition added. Wrap the entire body of the method in the following IF condition:
protected function createErrorEntry($error, $parse_errors)
{
if($error->getCode()!=='PPC:ERR-50000')
{
$marker_obj = new \DOMElement(strtolower($error->getSeverity()));
$parse_errors->appendChild($marker_obj);
$message = ($this->getTranslator())
? vsprintf($this->getTranslator()->translate($error->getCode()), $error->getContext())
: $error->getCode();
$marker_obj->appendChild(new \DOMText($message));
$marker_obj->setAttribute('line', $error->getLine());
$marker_obj->setAttribute('code', $error->getCode());
}
}
This will stop the error being recorded, in effect, it hides the error from the end user, it doesn't fix what I can only assume is a bug in phpDocumentor. So the original error still exists, it just hasn't been recorded.
One thing I did note while debugging, is the vsprintf() function produces an error for on the PPC:ERR-50000 error. The vsprintf() produces the error PHP Warning: vsprintf(): Too few arguments. If i find out how to fix the code to stop the false error (or fix the comments to ensure the error isn't given reason to log), I'll post it here.
For what it's worth, I've found that creating the documentation from the commandline using parameters rather than using parameters in :
phpdoc -d ./ -t ./docs --ignore=vendor/*
vs parameters in a phpdoc.dist.xml configuration file has resolved all of the issues raised in this thread.
I don't think this stops the need for two docblocks at the top of files but it does appear to resolve the "No summary was found for this file" error when building the documentation.
I got the same error because I use PHP > 7 and PHPDocumentor did not recognize the syntax, so this "default error" was provided.
In my code, PHPDocumentor isn't able to parse null returns (?) in functions.
I solved this issue going to this link
https://github.com/phpDocumentor/phpDocumentor/releases
I wgot the "PHP-7 Syntax support" and installed it
wget https://github.com/phpDocumentor/phpDocumentor/releases/download/v2.9.0/phpDocumentor.phar
sudo mv phpDocumentor.phar /usr/local/bin/phpdoc
sudo chmod +x /usr/local/bin/phpdoc
check version:
phpdoc --version
= phpDocumentor version v2.9.0
It works with this phpDocumentor version
I got the exact same error message. I got rid of it..
the solution is very simple. in the file block at the
top, the summary line has a period at the end of it. This indicates
its a summary line.
make sure that no other blocks that follow for attributes or methods or whatever have a summary line with a period at the end. Once I removed those, the error disappeared immediately (PHPDocumentor 2.8.5)
I came accross this issue when my site works with php v7.4 while phpDocumentor.phar is started with php v7.2.5 and there where strong typed properties in my class. Strong typed properties aren't allowed before php v7.4.0.
class Template
{
/**
* #var string The template with some replacement strings
*/
private string $template;
....
I've been working on a project (which I'll keep specific details out of this post with randomized data) that involves integrating our system (PHP 5.3.x+) with an API (they provided a SDK) of a major company. They provided a WSDL and claimed ours needed to match their methods and they provided examples of how output (XML generated by the Soap Server) should look.
Right now, everything has been working as expected. When I send a XML request from SoapUI (an app I'm using to test) it all processes properly and such, but the XML output isn't matching closely with their examples and we believe they said we must be close to their examples.
Basically, we created an agnostic class we initialize with a service name and it initializes into a non-agnostic class which is used via the following:
/**
* The following is used to process Soap Server based on config and any optional settings.
*
* #param string $className
* #param array $options
* #param object $config
* #return Zend_Soap_Server
*/
public static function init($className, Array $options = null, $config = null)
{
// Used to define the class and return object.
$soap_server = new Zend_Soap_Server(null, $options);
$soap_server->setClass($className, null, (isset($config) ? $config : null));
$soap_server->handle();
exit;
}
The problem itself lies within the outputted response. How would you guys suggest we build the XML output if they're very specific about everything?
1.) One of our methods is moneyTransferRequest. When I send the XML over for this, it does find the method and processes it. However, they want it to show the method name, in the response, as moneyTransferResponse but it outputs moneyTransferRequestResponse.
2.) Our output (for variables and such sent back as an object) has multiple variables, we'll say $money for example. The field for this would return as:
<money xsi:type="xsd:string">10.0</money>
They would like it to be:
<ns1:money xsi:type="xsd:string">10.0</money>
in the return.
I appreciate any help and input on the subject.
The key feature of SOAP is that it uses XML, and XML can come in a bunch of different styles but still mean the same.
I think (but I can only guess because you didn't provide details) that your two issues might be non-existing.
1.) The name of the response XML structure should align with the name mentioned in the WSDL. YOU are publishing the WSDL, so you should check if these two match. Note that the important entry point is the SOAP method - everything thereafter is defined in the WSDL itself, any consuming client should be able to figure it out as long as the names mentioned are correctly used.
2.) This is basically the same, but even easier: XML allows to use namespaces, and these can be defined in several locations, with the result being not literally the same, but every XML parser will understand that they are the same. So you should check whether the namespace that is required as "ns1" is mentioned in the XML header of your response. Every XML document has a base namespace, which does not need to be repeated on every element that belongs to it.
This is the case with the <money> element. Your style of writing uses that base namespace, their style of writing uses a namespace shortcut ns1 also introduced in the XML header, but not declared as the base namespace. So as long as there are traces of the correct XML namespace in both responses, I'd assume they are equivalent.
And the bad news would be that you cannot change how the PHP SoapServer generates the XML. You'd need to create your own implementation of a SOAP server, which I'd say is a complete waste of resources.
According to PhpDocumntor each block of comment in order to be converted into a valid piece of documentation requires to be encapsulated like this:
/**
* This function is used blah, blah, blah
* line 2
* line 2
* ...
*/
function MyFunc($string) {...
Do you know if it's possible (maybe by changing some settings) to avoid being forced to place an asterisk in front of each line. I would basically like PhpDocumentor to accept and translate to documentation these type of comments:
/**
This function is used blah, blah, blah
line 2
line 2
...
*/
function MyFunc($string) {...
I'm asking because JsDOC and JavaDoc do not require a damn asterisk in front of each new line anymore, so I thought tat maybe also PhpDocumentor can do this by tricking a bit its settings, but I can't find anything about this on Google.
Maybe you should use an editor which places the asterisks for you, so you don't have to do it manually. Almost all PHP-compatible IDEs do it, as do many programmer's editors with PHP support.
Using the asterisk like that is the standard convention. Unless your code is going to be hidden away in a cave, under a ton of cement, where nobody will ever see it, it might be a good idea to follow the standard conventions.
You have to remember if you change the way PhpDoc creates the documentation / auto complete information, the end user will need to change their settings as well should they wish to view your code with documentation / auto complete information.
I am not aware of this option in PhpDoc however you could try playing with the DocBlock templates.
Here is a link on playing with the doc block templates.
There is no way to do it using PhpDocumentor.
I gave up on PhpDocumentor and started using Doxygen. For anyone who might be interested, Doxygen allows final user to document PHP function in many ways among which also like JavaDoc and JsDoc. And you are NOT forced to place a 'damn' asterisk at the beginning of each line in documentation, so the following comments are ok and will be properly parsed by Doxygen:
/**
... line1 ...
... line2 ...
*/
function MyFunc($string) {...