PHP Beautifier Notes
I've just spent quite a few hours looking into the PHP Beautifier. From the blogs out there it seems most people think it doesn't really do the job out of the box. But it is fairly simple to modify it once you understand the basics of how it works. Hopefully this blog will help get over that initial learning hump.
Normal installation
Try this:
pear install PHP_Beautifier
Will probably fail with a warning to use the 0.1.15 version) so run this instead:
pear install PHP_Beautifier-0.1.15
Fix a bug if running PHP < 5.3
First, installation files have a bug in them if you are running PHP 5.2 or less, this is what stopped me last time, but it is easy to patch, so once you have installed it you need to patch it, do that as follows.
The install of 0.1.15 has a bug for PHP versions under 5.3 and I had to apply a patch manually to stop it from throwing a notice warning, the correct code is here:
https://github.com/clbustos/PHP_Beautifier/blob/master/Beautifier.php
Basically PHP version < 5.3 throws a notice around line 377 of the 0.1.15 version, make the changes as shown below in /usr/share/php/PHP/Beautifier.php.
'T_END_SUFFIX',
T_ENDIF => 'T_END_SUFFIX',
);
if (version_compare(PHP_VERSION, '5.3.0', '>=')) {
$aTokensToChange[T_NAMESPACE] = 'T_INCLUDE';
$aTokensToChange[T_USE] = 'T_INCLUDE';
}
?>
Understanding the Filters
So now I fixed that I tried to figure out what the examples meant, there was no note saying to examine the source code for filters to figure out what the parameters are and how they might work. All the filters on Ubuntu live here:
/usr/share/php/PHP/Beautifier/Filter
Just open up the php files and you can see what they do.
You can use a line like the one below to run the program. This is the most basic usage and will use only the default filter.
php_beautifier -s4
To add filters, just add the filename (without .filter.php) and add brackets where you can specify extra settings. Here is an example:
php_beautifier -s4 -l "ArrayNested() IndentStyles(style=k&r) NewLines(before=comment:return:break:T_COMMENT,after=T_COMMENT)"
So you see where it says ArrayNested, IndentStyles, Newlines, these are all files in the filter directory.
Modifying to suit your style
So I wanted to add a line above the "/**" comments. Now I didn't know this, but they are called DOC_COMMENTs, and are referenced as T_DOC_COMMENT by PHP. But this took me a few hours to figure out, I traced though the code and after a few dead ends eventually found that the system is based on PHP tokens, at the heart of the program is the PHP function token_get_all (see http://php.net/manual/en/function.token-get-all.php). That really helped understanding what all the "T_" defs were doing.
So basically all I wanted to do was add a line before my "DOC_COMMENTS" which are "/**" style comments, which I have all though my code. So, bottom line is, if you want to add a line before your long comments (T_DOC_COMMENT), then modify /usr/share/php/PHP/Beautifier/Filter/Default.filter.php as follows:
oBeaut->removeWhiteSpace();
$this->oBeaut->addNewLineIndent();
$this->oBeaut->addNewLineIndent(); // Added a second new line so there is a blank line above the long comment.
?>
Another one that I find useful is to add a newline after a string concat. I often need to create long query strings which look awful if it is all on one line. I've left the debug output that I used to figure out the numbers to use. These are magic numbers which I assume match some PHP token, didn't have time to track that down, but seems to work pretty well. Note that I put in an exception so the newline is not applied to my include files. Might just be my formatting though, I guess I'll probably have to revisit this at some point for other exceptions, but doesn't hurt to have the newline, just looks crappy.
oBeaut->getPreviousTokenContent(3) . "] -3S[" . $this->oBeaut->getPreviousTokenConstant(3)
. "] -2C[" . $this->oBeaut->getPreviousTokenContent(2) . "] -2S[" . $this->oBeaut->getPreviousTokenConstant(2) . "]"
. "] -1C[" . $this->oBeaut->getPreviousTokenContent(1) . "] -1S[" . $this->oBeaut->getPreviousTokenConstant(1) . "]"
. "] +1C[" . $this->oBeaut->getNextTokenContent(1) . "] +1S[" . $this->oBeaut->getNextTokenConstant(1) . "]"
. "] +2C[" . $this->oBeaut->getNextTokenContent(2) . "] +2S[" . $this->oBeaut->getNextTokenConstant(2) . "]"
. "] +3C[" . $this->oBeaut->getNextTokenContent(3) . "] +3S[" . $this->oBeaut->getNextTokenConstant(3) . "]"
. "] +4C[" . $this->oBeaut->getNextTokenContent(4) . "] +4S[" . $this->oBeaut->getNextTokenConstant(4) . "]\n";
*/
$this->oBeaut->removeWhitespace();
if ($this->oBeaut->getPreviousTokenConstant(2) == 364|
$this->oBeaut->getNextTokenConstant(3) == ';'|
$this->oBeaut->getNextTokenContent(1) == '"\'"') {
// Do not add a new line if
// 1) the 2nd last is __FILE__
// 2) the 3rd next is a semi colon.
// 3) the next is a single quote.
$this->oBeaut->add(' ' . $sTag . ' ');
} else if ($this->oBeaut->getNextTokenConstant(1) == 315) {
// Add a newline if the next is a string.
$this->oBeaut->addNewLineIndent();
$this->oBeaut->add(' ' . $sTag . ' ');
} else {
$this->oBeaut->add(' ' . $sTag . ' ');
}
}
?>
Integrate with gEdit
Sometimes the simplest things can be so frustrating. The short version is this, install the External Tools plugin for gedit and then create a new task and add these two lines:
#!/bin/sh
php_beautifier -s4
Then configure the options below that to:
Input = Current Document
Output = Replace current document (don't worry, you can undo).
I also added a short cut function, and you could set it to run this on save too.
Long version, I didn't see the Output option right away and tried to use the --input and --output and got caught up with some issue that strings have %20 inserted, very frustrating. Anyway, never solved that, but ended up find the above solution after pretty much starting again on the problem.
References:
The code:
http://pear.php.net/package/PHP_Beautifier/
Guy having similar problems:
http://old.nabble.com/PHP_Beautifier%3A--strange-behaviour-with-newlines-and-comments-td27811969.html
Comment from the Author:
http://stackoverflow.com/questions/1265564/fixing-php-beautifiers-empty-lines-problem
PHP Tokens:
http://www.php.net/manual/en/tokens.php
Comments