====== phptidy README ======
=== Description ===
This is a little tool for formatting PHP code. It aims to make the code better
readable and thus better understandable.
Unlike other beautifiers, phptidy does not completely reformat the code and
remove formatting, which was intended by the author. It only touches things
which are usually not intended. In case of doubt, phptidy will not touch
anything. Because of this strategy it is also very unlikely, that phptidy by
fault changes the functionality of the code.
phptidy is useful in many situations:
You can use it on your own code during development to keep the code tidy,
wasting no time on indenting and formatting by hand.
In a project with more than one person coding you have less trouble with
people who do not confirm to the style guide.
If you use a version control system you can require all participating people
to run phptidy before committing changes. Then you won’t have anymore trouble
with unintended changes due to code formatting or with the trailing
whitespace or wrong line breaks of some brain dead editors (or their users).
If you have to maintain some ultimately ugly code of someone else. After
running phptidy the code will be much better readable. Well, the code will
not be perfect, but it’s a big help anyway.
The used coding standard is mainly inspired by the PEAR Coding Standards:
http://pear.php.net/manual/en/standards.php
phptidy is released under the GPL and can be used for free.
=== System Requirements ===
PHP 5 or 7
phptidy does not work on PHP 4, because some functions introduced in PHP 5
are used, and there are also some differences in the tokens. But it should
be not too difficult to port it to PHP 4.
PHP CLI SAPI
http://php.net/manual/en/features.commandline.php
PHP extension: Tokenizer
http://php.net/manual/en/book.tokenizer.php
Optional:
diff
The standard Unix diff utility or similar
Default is to use colordiff.
Only required if you want to use phptidy’s “diff” command.
PHP extension: mbstring
http://php.net/manual/en/book.tokenizer.php
Only required if you want to use the configration variable $encoding to
check the encoding of your PHP files.
phptidy should work on most operation systems where PHP works. I use it in
Linux and MacOS X. Some people use it also on Windows.
=== Installation ===
phptidy consists of only one file, phptidy.php. Execute this file on command
line to use it.
$ ./phptidy.php
There is actually no need to install phptidy, you can run it also with the path
to the file on command line.
$ ~/src/phptidy/phptidy.php
To be able to call phptidy without having to supply the path, you can copy
phptidy.php to a directory in your PATH, e.g. ~/bin (only for you)
$ cp phptidy.php ~/bin
or /usr/local/bin (for all users).
In the following examples I assume you have installed phptidy in your PATH.
=== Basic usage ===
The most simple case: You have a PHP script example.php and you want to tidy it
up.
$ phptidy.php suffix example.php
phptidy will create a file “example.php.phptidy.php” with the tidy version of
your script.
To see what changes phptidy would make to your script, you can use phptidy’s
“diff” command:
$ phptidy.php diff example.php
If you are happy with the displayed changes, you can now overwrite the original
file with the tidy version by using the “replace” command:
$ phptidy.php replace example.php
You will find a backup of the original version of the file in the hidden file
“.example.php.phptidybak~”.
If you have a project consisting of multiple files, you can supply all these
files as arguments:
$ phptidy.php replace .php inc/.php
=== Using config files ===
If you have a project with many files, you can write the list of files in a
config file. Then you do not have to supply the list on the command line
anymore. The config file has to be named “.phptidy-config.php” and has to be in
the project’s top level directory. To have the same effect as in the last
example the config file would have to have the following content: