Home / Section index

 PHPLint - FAQ

Page updated: 2020-03-14


About the features of PHPLint

Is PHPLint a sources style validator?

No. The PHPLint validator performs a static code analysis on a PHP source program; the only thing that cares to the PHPLint validator is safety and security.

Could a third-party package be used along with the PHPLint validator?

No. Or at least no in the 99.99% of the cases because random PHP source code you may find around is not even close to pass static analysis as it relies on very dynamic features of the language like: variable-named variables $$var, mixed-content associative arrays, missing error detection, missing exceptions handling, poor or missing signature declarations, uninitialized variables, mixing of incompatible types, improper source code inclusion, and more.

Could the PHPLint Stdlib be used along with third-parties libraries?

Yes, but with some caution. The classes you may found under the stdlib/ directory all require the errors.php package that raises the error level to the maximum level and then maps errors into exceptions. This means the mean "normal" PHP source code you may found around will bomb like crazy everywhere :-) Why? Because it did not passed validation!
Not to mention that source code that candidly cheats by turning off error detection and errors-to-exception mapping to hide its sloppy behavior, defeating the safety and the security of all the system.

Is PHPLint compatible with the Composer class autoloader?

Since the release 4.2 PHPLint is now aware of the Composer autoloader. In order to validate your source code the --composer-project DIR command line option must be indicated, where DIR is the directory of your project. In this way PHPLint will parse any composer.json file he found in the project and can then resolve any class name just as the Composer autoload does.
Moreover, PHPLint and its library can now be installed and used as a Composer package by following the instructions you may found in the download page.

Downloading, installing and updating PHPLint

Where PHPLint can be downloaded from?

The latest stable release is available from the download page.

Where the PHPLint directory should be saved on my HD?

Once uncompressed, save the PHPLint package anywhere you want. I recommend to name that directory simply "phplint" so paths referring to it never change as the package gets updated later. If you plan to use PHPLint and its library along with your web server, save the PHPLint directory above the document root of the web server, as no PHPLint file needs public visibility. For example, once installed the WAMP Server under Windows under the C:\wamp directory, put the phplint directory just inside it.

How can I start the php and the phpl scripts from any terminal?

Under Linux: edit the file $HOME/.bash_profile and add this last line:
export PATH=$PATH:/path/to/phplint
where /path/to/phplint is the path to the PHPLint directory; logout and login again to make this change effective.

Under Windows: edit the value of the user's environment variable named Path by adding this string to its very end:
where C:\path\to\phplint is the path to the PHPLint directory; the change will be effective for any new open terminal from now on.

How can I know which version of PHPLint I'm using right now?

Start the phpl program from the command line with the --version option. The GUI program phplint.tcl also displays the current version of PHPLint used after each parsing of a source. Under each PHPLint directory there is also a file named VERSION.txt you may inspect.

How can I know if a new release of PHPLint is available? How can I update?

Periodically check the download page and check the displayed version available. For example, 3.1_20180416 means: major version 3, minor version 1, release date 2018-04-16. It is safe to save your current PHPLint directory with some name, for example "phplint_OLD", then replace that directory with the new one. Typically you will need to copy these files from the old directory


as these files should have been already customized by you during the installation process; and do not forget to copy also your custom files you may have added to the stdlib tree.
You may also consider to use CVS to keep in synch with the development version of PHPLint; the download page explains how to do that.

Issues validating my source code

Why hundredths of errors signaled in my otherwise perfectly working program?

It's normal, but “working” does not implies it's also safe, secure, fully documented and easy to understand and to maintain. As an experiment, try to consider each complain of PHPLint one by one, fix it, and once you program passes validation compare the resulting source code with the original one, then take your conclusions. The article Worth the effort shows an experience of porting an existing source code to PHPLint and contains useful suggestions.

Can I turn off some boring error PHPLint signals?

No. A program either passes validation or does not. There are only two exceptions to this rule: checking for control characters in literal strings, and checking for non-ASCII characters in literal strings; these exceptions to the rule above are still here because I still don't know how exactly handle these cases, but in general it's better to leave these checks on, especially while parsing library files .

PHPLint complains it doesn't even know trim(), fopen() and other very common functions!

Typical message:

        $f = fopen("mydata.txt", "rb");
                  \_ HERE
==== 3: ERROR: unresolved function fopen

You must indicate which modules (that is, PHP extensions) your program depends on, as explained in the reference manual, chapter Importing modules. In this case you will need the core and the file modules:

    require_module 'core';
    require_module 'file';

Or, you may want to require the standard module which in turn requires most of the common functions typically available under PHP.

Cannot include anything, PHPLint complains the path is relative!

Typical message:

	require_once "MyLib.php";
	                         \_ HERE
==== 4: ERROR: invalid file "MyLib.php": cannot resolve relative
        path: "MyLib.php"
        Hint: expected absolute path (PHPLint safety restriction).
        The magic constant __DIR__ gives the directory of the
        current source.

==== 4: ERROR: invalid file "MyLib.php": missing drive or remote
        host in path: "MyLib.php"
        Hint: expected absolute path (PHPLint safety restriction).
        The magic constant __DIR__ gives the directory of the
        current source.

PHP applies a quite articulated and hardly predictable heuristic to find included files with relative path, so as a safety measure PHPLint requires all paths be absolute. You may build an absolute path starting from the directory of the current file by using the __DIR__ constant, for example:

require_once __DIR__ . "/MyLib.php";

PHPLint does not recognize my functions defined in the same file!

PHPLint is a single-pass parser, so it needs to see the definition of a function first, then its invocation. This implies all the functions must be defined in bottom-up order: if function b() invokes function a() then you must define a() first and b() next. This also implies the "main" function, or the program body, must be located at the very end of the source, for example:


function a() { ... }

function b() {  a();  }

function main()


The same holds for any other item: constants, variables, classes and class members. The general rule then is: definitions first, usage next.

PHPLint does not recognize my functions defined in another file!

Every PHP file must explicitly include any other file it depends on, and these files must be included using the require_once statement. Class autoloading is very handy and efficient: consider to use it instead, see Class autoloading.

The other inclusion statements include, include_once and require are allowed, but these files are not parsed recursively by PHPLint; only files included with require_once are; these statements can be used to include chunks of HTML code, for example, or other PHP code that does not defines functions or classes or other items.

I can't do anything with $_GET and $_POST values because are "mixed"!

Those superglobal variables may contain several types of data not predictable by the program, so a value-typecast operator must be applied to get the expected type of value, for example:

$n = (int) $_GET['n'];
$name = (string) $_GET['name'];

See the Tutorial for more. The standard library also contains utilities to acquire and sanitize untrusted data coming from the browser, see the Input class. For more specific types and data structures, consider using the magic cast() function.

Cannot not use arrays: it keeps complaining I'm mixing elements of different types!

Under PHPLint arrays are intended to collect elements all of the same type; avoid arrays to store heterogeneous collections of data, use classed for that purpose. If you really need to build an array of mixed types, first declare an empty array of type mixed[] then add the elements one by one:

$a = /*. (mixed[]) .*/ array();
$a[0] = 1234;
$a[1] = "some string";

But again, avoid doing that because accessing those element will require a type-cast each time.

It complains “unhandled error E_WARNING” for EVERY single I/O function!

PHPLint does its best to ensure the programmer and the program he writes are fully aware of which errors could be generated and from where these errors could come from, so errors must be either handled locally or declared to be triggered by functions. Please read the Errors handling chapter of the reference manual for more. The standard library normally maps errors into ErrorException because exceptions are safer and simpler to handle.

Still stuck. What else can I do?

Try with this troubleshooting check-list:

How to contribute

Module xyz is outdated / missing a function / constant / class / whatever. Now what?

You may fix the module yourself according to the official PHP manual and send the result to me.
Or, you may report a bug to the PHPLint Issues Tracking System. Non-registered users may only browse the issues tracking system, though, so a basic registration is required where you provide a login name and a password. Once registered you may submit your bug report by opening a new issue, possibly also adding the corrected file as an attachment to the message.

How to report bugs? How to ask for new features?

Bugs, requests for new features or feature changes can be reported in the PHPLint Issues Tracking System. Non-registered users may only browse the issues tracking system, though. To file new messages a basic registration is required where you provide a login name and a password. Once registered you may open new issues and add comments to the existing issues. It is recommended to provide your email address in the preferences mask and then go back to the PHPLint project to press the Subscribe button in order to get feedback about new messages added to the project.

Umberto Salsi
Site map
Home / Section index
Still no comments to this page. Use the Comments link above to add your contribute.