Psalm uses an XML config file (by default,
psalm.xml). A barebones example looks like this:
<?xml version="1.0"?> <psalm> <projectFiles> <directory name="src" /> </projectFiles> </psalm>
Configuration file may be split into several files using XInclude tags (c.f. previous example):
<?xml version="1.0"?> <psalm xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="https://getpsalm.org/schema/config" xsi:schemaLocation="https://getpsalm.org/schema/config vendor/vimeo/psalm/config.xsd" xmlns:xi="http://www.w3.org/2001/XInclude" > <xi:include href="files.xml"/> </psalm>
<?xml version="1.0" encoding="UTF-8"?> <projectFiles xmlns="https://getpsalm.org/schema/config"> <file name="Bar.php" /> <file name="Bat.php" /> </projectFiles>
Optional <psalm /> attributes
<psalm errorLevel="[int]" />
This corresponds to Psalm‘s error-detection level.
<psalm reportMixedIssues="[bool]" />
Setting this to
"false" hides all issues with
Mixed types in Psalm’s output. If not given, this defaults to
errorLevel is 3 or higher, and
"true" when the error level is 1 or 2.
<psalm totallyTyped="[bool]" />
"true" is equivalent to setting
"false" is equivalent to setting
<psalm resolveFromConfigFile="[bool]" />
If this is enabled, relative directories mentioned in the config file will be resolved relative to the location of the config file. If it is disabled, or absent they will be resolved relative to the working directory of the Psalm process.
New versions of Psalm enable this option when generating config files. Older versions did not include it.
<psalm useDocblockTypes="[bool]" >
Whether or not to use types as defined in docblocks. Defaults to
<psalm useDocblockPropertyTypes="[bool]" >
If not using all docblock types, you can still use docblock property types. Defaults to
false (though only relevant if
<psalm usePhpDocMethodsWithoutMagicCall="[bool]" >
@method annotation normally only applies to classes with a
__call method. Setting this to
true allows you to use the
@method annotation to override inherited method return types. Defaults to
<psalm usePhpDocPropertiesWithoutMagicCall="[bool]" >
@property-write annotations normally only apply to classes with
__set methods. Setting this to
true allows you to use the
@property-write annotations to override property existence checks and resulting property types. Defaults to
<psalm strictBinaryOperands="[bool]" >
If true we force strict typing on numerical and string operations (see https://github.com/vimeo/psalm/issues/24). Defaults to
<psalm requireVoidReturnType="[bool]" >
false, Psalm will not complain when a function with no return types is missing an explicit
@return annotation. Defaults to
<psalm useAssertForType="[bool]" >
Some like to use
assert for type checks. If
true, Psalm will process assertions inside
assert calls. Defaults to
<psalm rememberPropertyAssignmentsAfterCall="[bool]" >
Setting this to
false means that any function calls will cause Psalm to forget anything it knew about object properties within the scope of the function it's currently analysing. This duplicates functionality that Hack has. Defaults to
<psalm allowPhpStormGenerics="[bool]" >
Allows you to specify whether or not to use the typed iterator docblock format supported by PHP Storm e.g.
ArrayIterator|string, which Psalm transforms to
ArrayIterator<string>. Defaults to
<psalm allowStringToStandInForClass="[bool]" >
true, strings can be used as classes, meaning
$some_string::someMethod() is allowed. If
false, only class constant strings (of the form
Foo\Bar::class) can stand in for classes, otherwise an
InvalidStringClass issue is emitted. Defaults to
<psalm memoizeMethodCallResults="[bool]" >
true, the results of method calls without arguments passed arguments are remembered between repeated calls of that method on a given object. Defaults to
<psalm hoistConstants="[bool]" >
true, constants defined in a function in a file are assumed to be available when requiring that file, and not just when calling that function. Defaults to
false (i.e. constants defined in functions will only be available for use when that function is called)
<psalm addParamDefaultToDocblockType="[bool]" >
Occasionally a param default will not match up with the docblock type. By default, Psalm emits an issue. Setting this flag to
true causes it to expand the param type to include the param default. Defaults to
<psalm checkForThrowsDocblock="[bool]" >
true, Psalm will check that the developer has supplied
@throws docblocks for every exception thrown in a given function or method. Defaults to
<psalm checkForThrowsInGlobalScope="[bool]" >
true, Psalm will check that the developer has caught every exception in global scope. Defaults to
<psalm ignoreInternalFunctionFalseReturn="[bool]" >
true, Psalm ignores possibly-false issues stemming from return values of internal functions (like
preg_split) that may return false, but do so rarely. Defaults to
<psalm ignoreInternalFunctionNullReturn="[bool]" >
true, Psalm ignores possibly-null issues stemming from return values of internal array functions (like
current) that may return null, but do so rarely. Defaults to
<psalm findUnusedVariablesAndParams="[bool]" >
true, Psalm will attempt to find all unused variables, the equivalent of running with
--find-unused-variables. Defaults to
<psalm findUnusedCode="[bool]" >
true, Psalm will attempt to find all unused code (including unused variables), the equivalent of running with
--find-unused-code. Defaults to
<psalm loadXdebugStub="[bool]" >
If not present, Psalm will only load the Xdebug stub if Psalm has unloaded the extension.
true, Psalm will load the Xdebug extension stub (as the extension is unloaded when Psalm runs).
false prevents the stub from loading.
<psalm ensureArrayStringOffsetsExist="[bool]" >
true, Psalm will complain when referencing an explicit string offset on an array e.g.
$arr['foo'] without a user first asserting that it exists (either via an
isset check or via an object-like array). Defaults to
<psalm phpVersion="[string]" >
Set the php version Psalm should assume when checking and/or fixing the project. If this attribute is not set, Psalm uses the declaration in
composer.json if one is present. It will check against the earliest version of PHP that satisfies the declared
This can be overridden on the command-line using the
--php-version= flag which takes the highest precedence over both the
phpVersion setting and the version derived from
<psalm skipChecksOnUnresolvableIncludes="[bool]" >
true, Psalm will skip checking classes, variables and functions after it comes across an
require it cannot resolve. This allows code to reference functions and classes unknown to Psalm.
For backwards compatibility, this defaults to
true, but if you do not rely on dynamically generated includes to cause classes otherwise unknown to Psalm to come into existence, it's recommended you set this to
false in order to reliably detect errors that would be fatal to PHP at runtime.
<psalm sealAllMethods="[bool]" >
true, Psalm will treat all classes as if they had sealed methods, meaning that if you implement the magic method
__call, you also have to add
@method for each magic method. Defaults to false.
<psalm runTaintAnalysis="[bool]" >
true, Psalm will run Taint Analysis on your codebase. This config is the same as if you were running Psalm with
<psalm autoloader="[string]" >
If your application registers one or more custom autoloaders, and/or declares universal constants/functions, this autoloader script will be executed by Psalm before scanning starts. Psalm always registers composer's autoloader by default.
<psalm throwExceptionOnError="[bool]" >
Useful in testing, this makes Psalm throw a regular-old exception when it encounters an error. Defaults to
<psalm hideExternalErrors="[bool]" >
Whether or not to show issues in files that are used by your project files, but which are not included in
<projectFiles>. Defaults to
<psalm cacheDirectory="[string]" >
The directory used to store Psalm's cache data - if you specify one (and it does not already exist), its parent directory must already exist, otherwise Psalm will throw an error.
sys_get_temp_dir() . '/psalm' when not defined.
<psalm allowFileIncludes="[bool]" >
Whether or not to allow
include calls in your PHP. Defaults to
<psalm serializer="['igbinary'|'default']" >
Allows you to hard-code a serializer for Psalm to use when caching data. By default, Psalm uses
ext-igbinary if the version is greater than or equal to 2.0.5, otherwise it defaults to PHP's built-in serializer.
Contains a list of all the directories that Psalm should inspect. You can also specify a set of files and folders to ignore with the
<ignoreFiles> directive, e.g.
<projectFiles> <directory name="src" /> <ignoreFiles> <directory name="src/Stubs" /> </ignoreFiles> </projectFiles>
Optional. Same format as
<projectFiles>. Directories Psalm should load but not inspect.
Optional. A list of extensions to search over. See Checking non-PHP files to understand how to extend this.
Optional. A list of
<plugin filename="path_to_plugin.php" /> entries. See the Plugins section for more information.
Optional. If you don't want Psalm to complain about every single issue it finds, the issueHandler tag allows you to configure that. Dealing with code issues tells you more.
Optional. Do you use mock classes in your tests? If you want Psalm to ignore them when checking files, include a fully-qualified path to the class with
<class name="Your\Namespace\ClassName" />
Optional. If your codebase uses classes and functions that are not visible to Psalm via reflection (e.g. if there are internal packages that your codebase relies on that are not available on the machine running Psalm), you can use stub files. Used by PhpStorm (a popular IDE) and others, stubs provide a description of classes and functions without the implementations. You can find a list of stubs for common classes here. List out each file with
<file name="path/to/file.php" />.
Optional. A list of exceptions to not report for
checkForThrowsInGlobalScope. If an exception has
onlyGlobalScope set to
checkForThrowsInGlobalScope is ignored for that exception, e.g.
<ignoreExceptions> <class name="fully\qualified\path\Exc" onlyGlobalScope="true" /> </ignoreExceptions>
Optional. If your codebase uses global variables that are accessed with the
global keyword, you can declare their type. e.g.
<globals> <var name="globalVariableName" type="type" /> </globals>