Bugfix: "TypeDoesNotContainNull: on return value from dom_import_simplexml"

.circleci/config.yml

@@ -68,6 +68,10 @@ jobs:
       - run:
           name: Analyse PHPUnit
           command: bin/test-with-real-projects.sh phpunit
+      # PSL requires its own plugin that is not yet compatible with Psalm 5
+      # - run:
+          # name: Analyse Psl
+          # command: bin/test-with-real-projects.sh psl
       - run:
           name: Analyse Collections
           command: bin/test-with-real-projects.sh collections

.github/workflows/ci.yml

@@ -9,7 +9,7 @@ jobs:
       - name: Set up PHP
         uses: shivammathur/setup-php@v2
         with:
-          php-version: '7.1'
+          php-version: '7.4'
           tools: composer:v2
           coverage: none
 

.github/workflows/pr-labels.yml

@@ -10,4 +10,4 @@ jobs:
         with:
           mode: minimum
           count: 1
-          labels: "release:typo, release:fix, release:feature, release:deprecation, release:internal, release:docs"
+          labels: "release:typo, release:fix, release:feature, release:deprecation, release:internal, release:docs, release:removed"

UPGRADING.md

@@ -0,0 +1,166 @@
+# Upgrading from Psalm 4 to Psalm 5
+## Changed
+- [BC] TPositiveInt has been removed and replaced by TIntRange
+
+- [BC] The parameter `$php_version` of `Psalm\Type\Atomic::create()` renamed
+  to `$analysis_php_version_id` and changed from `array|null` to `int|null`.
+  Previously it accepted PHP version as `array{major_version, minor_version}`
+  while now it accepts version ID, similar to how [`PHP_VERSION_ID` is
+  calculated](https://www.php.net/manual/en/reserved.constants.php#constant.php-version-id).
+
+- [BC] The parameter `$php_version` of `Psalm\Type::parseString()` renamed to
+  `$analysis_php_version_id` and changed from `array|null` to `int|null`.
+  Previously it accepted PHP version as `array{major_version, minor_version}`
+  while now it accepts version ID.
+
+- [BC] Parameter 0 of `canBeFullyExpressedInPhp()` of the classes listed below
+  changed name from `php_major_version` to `analysis_php_version_id`.
+  Previously it accepted major PHP version as int (e.g. `7`), while now it
+  accepts version ID. Classes affected:
+   - `Psalm\Type\Atomic`
+   - `Psalm\Type\Atomic\Scalar`
+   - `Psalm\Type\Atomic\TArray`
+   - `Psalm\Type\Atomic\TArrayKey`
+   - `Psalm\Type\Atomic\TCallable`
+   - `Psalm\Type\Atomic\TCallableObject`
+   - `Psalm\Type\Atomic\TCallableString`
+   - `Psalm\Type\Atomic\TClassConstant`
+   - `Psalm\Type\Atomic\TClassString`
+   - `Psalm\Type\Atomic\TClassStringMap`
+   - `Psalm\Type\Atomic\TClosedResource`
+   - `Psalm\Type\Atomic\TClosure`
+   - `Psalm\Type\Atomic\TConditional`
+   - `Psalm\Type\Atomic\TDependentGetClass`
+   - `Psalm\Type\Atomic\TDependentGetDebugType`
+   - `Psalm\Type\Atomic\TDependentGetType`
+   - `Psalm\Type\Atomic\TDependentListKey`
+   - `Psalm\Type\Atomic\TEnumCase`
+   - `Psalm\Type\Atomic\TFalse`
+   - `Psalm\Type\Atomic\TGenericObject`
+   - `Psalm\Type\Atomic\TIntMask`
+   - `Psalm\Type\Atomic\TIntMaskOf`
+   - `Psalm\Type\Atomic\TIntRange`
+   - `Psalm\Type\Atomic\TIterable`
+   - `Psalm\Type\Atomic\TKeyedArray`
+   - `Psalm\Type\Atomic\TKeyOfClassConstant`
+   - `Psalm\Type\Atomic\TList`
+   - `Psalm\Type\Atomic\TLiteralClassString`
+   - `Psalm\Type\Atomic\TLowercaseString`
+   - `Psalm\Type\Atomic\TMixed`
+   - `Psalm\Type\Atomic\TNamedObject`
+   - `Psalm\Type\Atomic\TNever`
+   - `Psalm\Type\Atomic\TNonEmptyLowercaseString`
+   - `Psalm\Type\Atomic\TNonspecificLiteralInt`
+   - `Psalm\Type\Atomic\TNonspecificLiteralString`
+   - `Psalm\Type\Atomic\TNull`
+   - `Psalm\Type\Atomic\TNumeric`
+   - `Psalm\Type\Atomic\TNumericString`
+   - `Psalm\Type\Atomic\TObject`
+   - `Psalm\Type\Atomic\TObjectWithProperties`
+   - `Psalm\Type\Atomic\TResource`
+   - `Psalm\Type\Atomic\TScalar`
+   - `Psalm\Type\Atomic\TTemplateIndexedAccess`
+   - `Psalm\Type\Atomic\TTemplateParam`
+   - `Psalm\Type\Atomic\TTraitString`
+   - `Psalm\Type\Atomic\TTrue`
+   - `Psalm\Type\Atomic\TTypeAlias`
+   - `Psalm\Type\Atomic\TValueOfClassConstant`
+   - `Psalm\Type\Atomic\TVoid`
+   - `Psalm\Type\Union`
+
+- [BC] Parameter 3 of `toPhpString()` of methods listed below changed name
+  from `php_major_version` to `analysis_php_version_id`. Previously it
+  accepted major PHP version as int (e.g. `7`), while now it accepts version
+  ID. Classes affected:
+   - `Psalm\Type\Atomic`
+   - `Psalm\Type\Atomic\CallableTrait`
+   - `Psalm\Type\Atomic\TAnonymousClassInstance`
+   - `Psalm\Type\Atomic\TArray`
+   - `Psalm\Type\Atomic\TArrayKey`
+   - `Psalm\Type\Atomic\TBool`
+   - `Psalm\Type\Atomic\TCallable`
+   - `Psalm\Type\Atomic\TCallableObject`
+   - `Psalm\Type\Atomic\TClassConstant`
+   - `Psalm\Type\Atomic\TClassString`
+   - `Psalm\Type\Atomic\TClassStringMap`
+   - `Psalm\Type\Atomic\TClosedResource`
+   - `Psalm\Type\Atomic\TConditional`
+   - `Psalm\Type\Atomic\TEmpty`
+   - `Psalm\Type\Atomic\TEnumCase`
+   - `Psalm\Type\Atomic\TFloat`
+   - `Psalm\Type\Atomic\TGenericObject`
+   - `Psalm\Type\Atomic\TInt`
+   - `Psalm\Type\Atomic\TIterable`
+   - `Psalm\Type\Atomic\TKeyedArray`
+   - `Psalm\Type\Atomic\TKeyOfClassConstant`
+   - `Psalm\Type\Atomic\TList`
+   - `Psalm\Type\Atomic\TLiteralClassString`
+   - `Psalm\Type\Atomic\TMixed`
+   - `Psalm\Type\Atomic\TNamedObject`
+   - `Psalm\Type\Atomic\TNever`
+   - `Psalm\Type\Atomic\TNull`
+   - `Psalm\Type\Atomic\TNumeric`
+   - `Psalm\Type\Atomic\TObject`
+   - `Psalm\Type\Atomic\TObjectWithProperties`
+   - `Psalm\Type\Atomic\TResource`
+   - `Psalm\Type\Atomic\TScalar`
+   - `Psalm\Type\Atomic\TString`
+   - `Psalm\Type\Atomic\TTemplateIndexedAccess`
+   - `Psalm\Type\Atomic\TTemplateParam`
+   - `Psalm\Type\Atomic\TTraitString`
+   - `Psalm\Type\Atomic\TTypeAlias`
+   - `Psalm\Type\Atomic\TValueOfClassConstant`
+   - `Psalm\Type\Atomic\TVoid`
+   - `Psalm\Type\Union`
+- While not a BC break per se, all classes / interfaces / traits / enums under
+  `Psalm\Internal` namespace are now marked `@internal`.
+- [BC] Parameter 1 of `Psalm\Type\Atomic\TNamedObject::__construct()` changed name from `was_static` to `is_static`
+- [BC] Parameter 1 of `Psalm\Type\Atomic\TAnonymousClassInstance::__construct()` changed name from `was_static` to `is_static`
+- [BC] Parameter 5 of `Psalm\Type::getStringFromFQCLN()` changed name from `was_static` to `is_static`
+- [BC] Property `Psalm\Type\Atomic\TNamedObject::$was_static` was renamed to `$is_static`
+- [BC] Method `Psalm\Type\Union::isFormerStaticObject()` was renamed to `isStaticObject()`
+- [BC] Method `Psalm\Type\Union::hasFormerStaticObject()` was renamed to `hasStaticObject()`
+- [BC] Function assertions (from `@psalm-assert Foo $bar`) have been converted from strings to specific `Assertion` objects.
+- [BC] Property `Psalm\Storage\ClassLikeStorage::$invalid_dependencies` changed from `array<string>` to `array<string, true>`.
+
+## Removed
+ - [BC] Property `Psalm\Codebase::$php_major_version` was removed, use
+   `Psalm\Codebase::$analysis_php_version_id`.
+ - [BC] Property `Psalm\Codebase::$php_minor_version` was removed, use
+   `Psalm\Codebase::$analysis_php_version_id`.
+ - [BC] Class `Psalm\Type\Atomic\TEmpty` was removed
+ - [BC] Method `Psalm\Type\Union::isEmpty()` was removed
+ - [BC] Property `Psalm\Config::$allow_phpstorm_generics` was removed
+ - [BC] Property `Psalm\Config::$exit_functions` was removed
+ - [BC] Property `Psalm\Config::$forbid_echo` was removed
+ - [BC] Method `Psalm\Type::getEmpty()` was removed
+ - [BC] Legacy hook interfaces have been removed:
+   -  `Psalm\Plugin\Hook\MethodReturnTypeProviderInterface`
+   -  `Psalm\Plugin\Hook\BeforeFileAnalysisInterface`
+   -  `Psalm\Plugin\Hook\AfterFileAnalysisInterface`
+   -  `Psalm\Plugin\Hook\AfterMethodCallAnalysisInterface`
+   -  `Psalm\Plugin\Hook\AfterClassLikeVisitInterface`
+   -  `Psalm\Plugin\Hook\StringInterpreterInterface`
+   -  `Psalm\Plugin\Hook\AfterExpressionAnalysisInterface`
+   -  `Psalm\Plugin\Hook\AfterEveryFunctionCallAnalysisInterface`
+   -  `Psalm\Plugin\Hook\PropertyExistenceProviderInterface`
+   -  `Psalm\Plugin\Hook\AfterFunctionLikeAnalysisInterface`
+   -  `Psalm\Plugin\Hook\FunctionParamsProviderInterface`
+   -  `Psalm\Plugin\Hook\FunctionReturnTypeProviderInterface`
+   -  `Psalm\Plugin\Hook\FunctionExistenceProviderInterface`
+   -  `Psalm\Plugin\Hook\AfterAnalysisInterface`
+   -  `Psalm\Plugin\Hook\MethodVisibilityProviderInterface`
+   -  `Psalm\Plugin\Hook\MethodParamsProviderInterface`
+   -  `Psalm\Plugin\Hook\AfterClassLikeExistenceCheckInterface`
+   -  `Psalm\Plugin\Hook\PropertyTypeProviderInterface`
+   -  `Psalm\Plugin\Hook\AfterFunctionCallAnalysisInterface`
+   -  `Psalm\Plugin\Hook\MethodExistenceProviderInterface`
+   -  `Psalm\Plugin\Hook\AfterCodebasePopulatedInterface`
+   -  `Psalm\Plugin\Hook\AfterClassLikeAnalysisInterface`
+   -  `Psalm\Plugin\Hook\PropertyVisibilityProviderInterface`
+   -  `Psalm\Plugin\Hook\AfterStatementAnalysisInterface`
+ - [BC] Method `Psalm\Issue\CodeIssue::getLocation()` was removed
+ - [BC] Method `Psalm\Issue\CodeIssue::getFileName()` was removed
+ - [BC] Method `Psalm\Issue\CodeIssue::getMessage()` was removed
+ - [BC] Method `Psalm\DocComment::parse()` was removed
+ - [BC] Class `Psalm\Type\Atomic\THtmlEscapedString` has been removed

composer.json

@@ -14,7 +14,7 @@
         }
     ],
     "require": {
-        "php": "^7.1|^8",
+        "php": "^7.4 || ~8.0.0 || ~8.1.0",
         "ext-SimpleXML": "*",
         "ext-ctype": "*",
         "ext-dom": "*",
@@ -28,30 +28,30 @@
         "composer/semver": "^1.4 || ^2.0 || ^3.0",
         "composer/xdebug-handler": "^1.1 || ^2.0 || ^3.0",
         "dnoegel/php-xdg-base-dir": "^0.1.1",
-        "felixfbecker/advanced-json-rpc": "^3.0.3",
+        "felixfbecker/advanced-json-rpc": "^3.1",
         "felixfbecker/language-server-protocol": "^1.5",
         "netresearch/jsonmapper": "^1.0 || ^2.0 || ^3.0 || ^4.0",
         "nikic/php-parser": "^4.13",
         "openlss/lib-array2xml": "^1.0",
-        "sebastian/diff": "^3.0 || ^4.0",
+        "sebastian/diff": "^4.0",
         "symfony/console": "^3.4.17 || ^4.1.6 || ^5.0 || ^6.0",
-        "webmozart/path-util": "^2.3"
+        "symfony/filesystem": "^5.4 || ^6.0"
     },
     "provide": {
         "psalm/psalm": "self.version"
     },
     "require-dev": {
         "ext-curl": "*",
-        "bamarni/composer-bin-plugin": "^1.2",
+        "bamarni/composer-bin-plugin": "^1.4",
         "brianium/paratest": "^4.0||^6.0",
         "php-parallel-lint/php-parallel-lint": "^1.2",
         "phpdocumentor/reflection-docblock": "^5",
         "phpmyadmin/sql-parser": "5.1.0||dev-master",
-        "phpspec/prophecy": ">=1.9.0",
+        "phpspec/prophecy": ">=1.10.2",
         "phpunit/phpunit": "^9.0",
         "psalm/plugin-phpunit": "^0.16",
         "slevomat/coding-standard": "^7.0",
-        "squizlabs/php_codesniffer": "^3.5",
+        "squizlabs/php_codesniffer": "^3.6",
         "symfony/process": "^4.3 || ^5.0 || ^6.0",
         "weirdan/prophecy-shim": "^1.0 || ^2.0"
     },
@@ -80,11 +80,7 @@
     "autoload": {
         "psr-4": {
             "Psalm\\": "src/Psalm/"
-        },
-        "files": [
-            "src/functions.php",
-            "src/spl_object_id.php"
-        ]
+        }
     },
     "autoload-dev": {
         "psr-4": {

config.xsd

@@ -16,14 +16,6 @@
             <xs:element name="mockClasses" type="MockClassesType" minOccurs="0" maxOccurs="1" />
             <xs:element name="stubs" type="StubsType" minOccurs="0" maxOccurs="1" />
             <xs:element name="plugins" type="PluginsType" minOccurs="0" maxOccurs="1" />
-            <xs:element name="exitFunctions" type="ExitFunctionsType" minOccurs="0" maxOccurs="1">
-                <xs:annotation>
-                    <!-- note: for PHPStorm to mark the attribute as deprecated the doc entry has to be *single line* and start with the word `deprecated` -->
-                    <xs:documentation xml:lang="en">
-                        Deprecated. Replaced by documenting never as a return type. It is going to be removed in Psalm 5.
-                    </xs:documentation>
-                </xs:annotation>
-            </xs:element>
             <xs:element name="forbiddenFunctions" type="ExitFunctionsType" minOccurs="0" maxOccurs="1" />
             <xs:element name="issueHandlers" type="IssueHandlersType" minOccurs="0" maxOccurs="1" />
             <xs:element name="ignoreExceptions" type="ExceptionsType" minOccurs="0" maxOccurs="1" />
@@ -40,25 +32,7 @@
         <xs:attribute name="serializer" type="xs:string" />
 
         <xs:attribute name="addParamDefaultToDocblockType" type="xs:boolean" default="false" />
-
-        <xs:attribute name="allowCoercionFromStringToClassConst" type="xs:boolean" default="false">
-            <xs:annotation>
-                <!-- note: for PHPStorm to mark the attribute as deprecated the doc entry has to be *single line* and start with the word `deprecated` -->
-                <xs:documentation xml:lang="en">
-                    Deprecated. Has no effect since Psalm 3 and is going to be removed in Psalm 5.
-                </xs:documentation>
-            </xs:annotation>
-        </xs:attribute>
-
         <xs:attribute name="allowFileIncludes" type="xs:boolean" default="true" />
-        <xs:attribute name="allowPhpStormGenerics" type="xs:boolean" default="false">
-            <xs:annotation>
-                <!-- note: for PHPStorm to mark the attribute as deprecated the doc entry has to be *single line* and start with the word `deprecated` -->
-                <xs:documentation xml:lang="en">
-                    Deprecated. PHPStorm now supports generics for the most part and @psalm- annotations can be used
-                </xs:documentation>
-            </xs:annotation>
-        </xs:attribute>
         <xs:attribute name="allowStringToStandInForClass" type="xs:boolean" default="false" />
         <xs:attribute name="checkForThrowsDocblock" type="xs:boolean" default="false" />
         <xs:attribute name="checkForThrowsInGlobalScope" type="xs:boolean" default="false" />
@@ -67,13 +41,6 @@
         <xs:attribute name="findUnusedCode" type="xs:boolean" default="false" />
         <xs:attribute name="findUnusedVariablesAndParams" type="xs:boolean" default="false" />
         <xs:attribute name="findUnusedPsalmSuppress" type="xs:boolean" default="false" />
-        <xs:attribute name="forbidEcho" type="xs:boolean" default="false">
-            <xs:annotation>
-                <xs:documentation xml:lang="en">
-                    Deprecated. Will be replaced by adding echo to forbiddenFunctions in Psalm 5.
-                </xs:documentation>
-            </xs:annotation>
-        </xs:attribute>
         <xs:attribute name="hideExternalErrors" type="xs:boolean" default="false" />
         <xs:attribute name="hoistConstants" type="xs:boolean" default="false" />
         <xs:attribute name="ignoreInternalFunctionFalseReturn" type="xs:boolean" default="true" />
@@ -156,6 +123,7 @@
     <xs:complexType name="ProjectDirectoryAttributeType">
         <xs:attribute name="name" type="xs:string" use="required" />
         <xs:attribute name="ignoreTypeStats" type="xs:string" />
+        <xs:attribute name="resolveSymlinks" type="xs:boolean" />
         <xs:attribute name="useStrictTypes" type="xs:string" />
         <xs:anyAttribute processContents="skip"/>
     </xs:complexType>
@@ -263,7 +231,6 @@
             <xs:element name="FalsableReturnStatement" type="IssueHandlerType" minOccurs="0" />
             <xs:element name="FalseOperand" type="IssueHandlerType" minOccurs="0" />
             <xs:element name="ForbiddenCode" type="IssueHandlerType" minOccurs="0" />
-            <xs:element name="ForbiddenEcho" type="IssueHandlerType" minOccurs="0" />
             <xs:element name="IfThisIsMismatch" type="IssueHandlerType" minOccurs="0" />
             <xs:element name="ImplementationRequirementViolation" type="IssueHandlerType" minOccurs="0" />
             <xs:element name="ImplementedParamTypeMismatch" type="IssueHandlerType" minOccurs="0" />
@@ -293,6 +260,7 @@
             <xs:element name="InvalidCatch" type="ClassIssueHandlerType" minOccurs="0" />
             <xs:element name="InvalidClass" type="ClassIssueHandlerType" minOccurs="0" />
             <xs:element name="InvalidClone" type="IssueHandlerType" minOccurs="0" />
+            <xs:element name="InvalidConstantAssignmentValue" type="ClassConstantIssueHandlerType" minOccurs="0" />
             <xs:element name="InvalidDocblock" type="IssueHandlerType" minOccurs="0" />
             <xs:element name="InvalidDocblockParamName" type="IssueHandlerType" minOccurs="0" />
             <xs:element name="InvalidEnumBackingType" type="ClassIssueHandlerType" minOccurs="0" />
@@ -496,6 +464,7 @@
             <xs:element name="UnnecessaryVarAnnotation" type="IssueHandlerType" minOccurs="0" />
             <xs:element name="UnrecognizedExpression" type="IssueHandlerType" minOccurs="0" />
             <xs:element name="UnrecognizedStatement" type="IssueHandlerType" minOccurs="0" />
+            <xs:element name="UnresolvableConstant" type="IssueHandlerType" minOccurs="0" />
             <xs:element name="UnresolvableInclude" type="IssueHandlerType" minOccurs="0" />
             <xs:element name="UnsafeInstantiation" type="IssueHandlerType" minOccurs="0" />
             <xs:element name="UnsafeGenericInstantiation" type="IssueHandlerType" minOccurs="0" />
@@ -640,6 +609,24 @@
         <xs:attribute name="errorLevel" type="ErrorLevelType" />
     </xs:complexType>
 
+    <xs:complexType name="ClassConstantIssueHandlerType">
+        <xs:sequence>
+            <xs:element name="errorLevel" minOccurs="0" maxOccurs="unbounded">
+                <xs:complexType>
+                    <xs:choice maxOccurs="unbounded">
+                        <xs:element name="directory" minOccurs="0" maxOccurs="unbounded" type="NameAttributeType" />
+                        <xs:element name="file" minOccurs="0" maxOccurs="unbounded" type="NameAttributeType" />
+                        <xs:element name="referencedConstant" minOccurs="0" maxOccurs="unbounded" type="NameAttributeType" />
+                    </xs:choice>
+
+                    <xs:attribute name="type" type="ErrorLevelType" use="required" />
+                </xs:complexType>
+            </xs:element>
+        </xs:sequence>
+
+        <xs:attribute name="errorLevel" type="ErrorLevelType" />
+    </xs:complexType>
+
     <xs:complexType name="VariableIssueHandlerType">
         <xs:sequence>
             <xs:element name="errorLevel" minOccurs="0" maxOccurs="unbounded">