Jump to: INI config | Suppression Files | Wildcards

 

Preface

codescrubber is a static analyzer for PHP source code. It spots bugs in PHP programs that are not apparent until the program is run.

Requirements

codescrubber runs on Linux operating systems Ubuntu 14 and Ubuntu 16.

Installation

Use apt to install codescrubber.

Ubuntu 14

sudo apt-key adv --fetch-keys http://apt.codescrubber.com.s3-website-us-east-1.amazonaws.com/codescrubber.key
sudo apt-add-repository 'http://apt.codescrubber.com.s3-website-us-east-1.amazonaws.com trusty main'
sudo apt-get update
sudo apt-get install codescrubber-php

Ubuntu 16

sudo apt-key adv --fetch-keys http://apt.codescrubber.com.s3-website-us-east-1.amazonaws.com/codescrubber.key
sudo apt-add-repository 'http://apt.codescrubber.com.s3-website-us-east-1.amazonaws.com xenial main'
sudo apt-get update
sudo apt-get install codescrubber-php

Setting your license key

codescrubber looks for its license key in an environment variable named CS_KEY. Once you buy a license key, create an environment variable for the license. This can be done in many ways:

• During program invocation CS_KEY=... codescrubber_php --directory=...
• Adding this line to your ~/.bashrc or ~/.bash_profile export CS_KEY=...

Running codescrubber

codescrubber is a command line program. It accepts options via the command line. Once the program starts, it will analyze the given files for errors (bugs) and print out each bug found to the console, one bug per line. If codescrubber encounters at least 1 error that is not suppressed, then codescrubber will exit witn an exit code of 1. If codescrubber finds zero errors, or all errors are suppressed, then codescrubber exits with an exit code of zero (0). codescrubber will not stop checking files if it encounters errors. codescrubber accepts the following arguments:

--file="file_path"

A single file to analyze. This option is useful to run on files that you have recently modified.

--directory="directory_path"

A directory of files to analyze. This is recursive, all files in sub-directories will be analyzed. This option is useful to check an entire project before promoting to production.

--include="wildcards"

Filter of files to analyze. --include is optional, if not given it defaults to *.php. For example, the following wildcard expression includes all files with extensions phtml, php, php3, as well as files prefixed with "class.".

*.phtml;class.*.php;*.php3?

Include wildcards are only used when --directory is specified. See wildcards for more info.

--exclude="wildcards"

Files to exclude from analyzing. Exclude wildcards are useful for ignoring cache files generated by various PHP frameworks. For example, the following wildcard expressions ignores any file inside a tmp directory as well as any file with the extension .cache.php: tmp/*;*.cache.php. Exclude wildcards are only used when --directory is specified. Exclude wildcards are optional. See wildcards for more info.

--source_2_root_directory

Another source directory to analyze. You can analyze more than 1 directory hierarchy in a single program run. 2 is just an example, you can define up to 20 different source directories.

--source_2_include

The include wildcards to use for analyzing --source_2_root_directory.

--source_2_exclude

The exclude wildcards to use for analyzing --source_2_root_directory.

--config="ini_file_path"

Use options from an INI config file instead of the command line. This option is useful to store command line options in a file to make future invocations of codescrubber easier, and to share the options with other developers and your continuous integration environment. When a config file is given, all other command line arguments are ignored. See INI config for example config files.

--check_variables

Enable checks for uninitialized variables.

--check_identifiers

Enable checks for unknown classes, functions, methods, and constants.

--check_function_arguments

Enable checking of function call arguments against the function declaration.

--php_version

The version of PHP that codescrubber will use for checking. One of the following:

• 5.3
• 5.4
• 5.5
• 5.6
• 7.0
• 7.1

--suppression_file

Path to the suppression file to use. A suppression file contains a list of items to ignore. When an analyzer error is encountered, codescrubber will see if the error matches an item in the suppression list. If a suppression match is found, then codescrubber will ignore the error. Suppression files are very powerful because they allow you to ignore any existing errors, but still check that no new errors are found. See suppression files for sample suppression files.

--library_directory

Directory of files to parse, but not analyze. A library directory contains third party code that your project uses but did not write. Examples of this are frameworks, libraries downloaded from github, or packages fetched via composer. Specifying a directory of files as a library instead of a source is useful because it allows you codescrubbe to discover the identifiers from third party code, but at the same time codescrubber will not analyze the third party code for errors. Paths are relative to the current working directory where the command is run from.

--library_include

Wildcard expression to use when recursing library root directory.

--library_exclude

Wildcard expression to use when recursing library root directory.

--library_2_root_directory

Another directory of files to parse but not analyze. You can define more than 1 library directory hierarchy in a single program run. 2 is just an example, you can define up to 20 different library directories.

--library_2_include

The include wildcards to use for parsing --library_2_root_directory.

--library_2_exclude

The exclude wildcards to use for parsing --library_2_root_directory.

INI file options

The INI file that is given to --config can have any option that is accepted in the command line. The only exception is that libraries and sources directories are "grouped" with their include/exclude wilcard pairs. A quirk with this is relative paths. If a source (or library) is a relative path, it is considered relative to the current working directory where the command is run from. See this example:

# This is a sample codescrubber.ini file.  It can be checked into your source
# control repo so that all your team plus your Continuous Integration environment
# uses the same settings.
check_variables=true
check_identifiers=true
php_version=5.3
suppression_file=codescrubber-php/tests/php_fixtures/suppressions.ini

[source_1]
root_directory=codescrubber-php/tests/php_fixtures
include=*.php;*.phtml
exclude=*/tmp/*

[library_1]
root_directory=codescrubber-php/tests/lib
include=*.php;*.phtml
exclude=*/tmp/*
                    

Suppression File

A suppression file is used to skip over errors that codescrubber would otherwise notify you of. This is of great utility when you are working with legacy code; you run codescrubber on an existing project and craft a suppression file that ignores all errors. Then, on future program runs, codescrubber will show only newly introduced errors. This setup gives you the benefit of static analysis without needing to fix all existing errors.

Each supression is in its own line, in comma-separated form. Each line has 3 columns: type, target, location Examples:

# type, target, location
SKIP_UNKNOWN_CLASS,Couchbase,/home/user/www/project
SKIP_ALL,,/home/user/www/project/vendor

Possible types

• SKIP_UNKNOWN_CLASS: Skip unknow class names. This is useful when you use custom PHP extensions that define classes.
• SKIP_UNKNOWN_METHOD: Skip calls to unknown methods. This is useful when you use classes that define methods using the magic methods __get() and __set()
• SKIP_UNKNOWN_PROPERTY: Skip unknown property. This is useful when you use objects that don't explicitly declare class members and class properties are added at runtime.
• SKIP_UNKNOWN_FUNCTION: Skip unknown functions. This is useful when you use PHP extensions that define functions.
• SKIP_UNINITIALIZED_VAR: Skip uninitialized variables.
• SKIP_FUNCTION_ARGUMENT_MISMATCH: Skip errors where the argument count does not match the function signature.
• SKIP_ALL: Skip all errors. This is useful to completely ignore errors files or sub-directories.

target is the name of variable, function, class to ignore. location is the full path or drectory where the error to ignore is located in.

Wildcards

An wilcard expression can contain multiple wildcard expressions; where each expression has only 3 wildcard symbols:

• * = Matches Any number of characters
• ? = Matches zero or 1 character
• ; = OR Separator

For example, the following wildcard expressions ignores any file inside a tmp directory as well as any file with the extension .cache.php: tmp/*;*.cache.php. A wildcard is matched against the entire file path, meaning that the wildcard mechanism can be used to include or exclude entire sub-directories.