Repository navigation
Mago 1.61.0 adds an opt-in check for overly wide @throws types, a no-legacy-constructor rule, and semantics checks for code PHP rejects. It also fixes the nested-loop slowdown from 1.60.0 and brings about 200 fixes to the analyzer, type system, and stubs.
✨ Features
Analyzer
- Wide throws: adds opt-in
find-overly-wide-throw-typesfor@throwstypes that never escape. (#2501, #2526, f66a97a, 08432a0, 2c55f7a) - False array indexes: reports possibly
falsevalues used as array indexes aspossibly-false-array-index. (2e08ad6)
Codex
- Constants in docblocks: resolves global constants in docblock types, as in
int-mask<E_ERROR, E_WARNING>. (0d40968) - New type names: understands
non-empty-scalar,callable-array,callable-objectandstringable-object. (a1ff0f8) @phpstan-sealed: reads the classes allowed to extend a class from@phpstan-sealed. (c60a9f7)
Linter
no-legacy-constructor: warns about class-named constructors, which PHP 8 runs as plain methods. (#2669, #2744, 2c4ffce)
Semantics
- Redundant union types: reports native unions that repeat a type or hold one another member covers, which PHP rejects. (8bcf464)
Twig Syntax
Reporting
🐛 Bug Fixes
Analyzer
Performance
- Nested loops: removes the slowdown in deeply nested loops that came with 1.60.0. (#2742, 8ee16b4)
- Loops over
mixed: stops nested loops overmixedvalues from taking exponential time. (#2763, #2764, 2e518e8)
Control Flow
- Ternaries and
match: keeps variables assigned in one branch, and an arm condition's narrowing in its branch. (2ac2b07, cb88a2d) switchvariables: gives a case body the variables its condition assigns, and tracks variables a case unsets. (7b41d1e, 19e9c79)switchnarrowing: narrows after aswitchwhose matching cases all leave, and in emptyswitch (true)cases. (7c52b96, a117bdb)elseif: keeps variables anelseifdefines when theifexits, and drops stale negations of reassigned variables. (8d670ab, a185dc6)- Short circuits: keeps variables a skipped operand assigns possibly undefined, and what the left of
&&says. (b3b790e, 4ec0089) - Returns: lets a docblock return type with
voidend withoutreturn, and addsnullto untyped closures that may. (58a5da0, 42e58f6) - Unreachable
else: an unreachableelsestill ends the way its statements do. (a7cfd50) - Possibly false returns: stops reporting them when the declared return type is
bool. (77b63a0)
Loops
- Growing values: widens ints, floats, and string literals that grow between loop passes. (9201857, e97a72c, db640ff)
- Continues: keeps what an always-entered loop's
continuepaths define. (a9e9ea1, 4cd2d96) - Breaks: keeps a loop variable's normal exit type when a
breakalso defines it, and when abreakskips it. (28ccf39, 68b0d6b) - Endless loops: treats a
forloop with no condition or a true last condition as infinite. (c598ca3) - Always-ending loops: an always-entered loop whose body always ends now ends the function. (a2eeee0)
- Loop assignments: counts
foreachtargets,staticdeclarations, and nestedlist()targets. (c416fec) - Loop conditions: keeps a
mixedvariable's pre-loop type, and sees offsets the loop unsets. (5febad0, 285c54c) - Loose
nullloop conditions: builds them from the analyzed operand type. (629bec7) ??conditions: narrows a loop condition that falls back tofalsewith??. (38b58f6)isset()in loops: keeps the loop origin ofisset()values through reads, and types offsets ofmixedasmixed. (1be5986, 258744e)- Inner
continue: acontinuein an inner loop no longer makes a narrowed property possiblynull. (0dda743)
Narrowing
- Nullsafe checks: narrows a nullsafe fetch's receiver on
is_null(), and reuses the plain fetch's narrowing. (#2740, bdc2200, 17455bb) - Truthy checks: removes
0from narrowed ints, and narrows non-empty strings other than'0'to non-falsy. (4898533, 9b11f6d) - Loose equality: keeps
nullwhen a value loosely equals0or'', and__toString()objects against strings. (fcc3234, 37680ec) - Negated checks: narrows
numericand templates correctly, and keeps objects!instanceof staticcannot rule out. (784387b, cbe82ea) - Else branches: narrows the
elsebranch ofcount(),strlen(), and literal variable comparisons. (5f454fd) - String lengths: narrows a string whose length equals a positive number to a non-empty string. (0a437fc)
- Class names: narrows
$var::classcompared withstatic::class, and values compared throughget_debug_type(). (4393c9a, a5ac850) - Increments in conditions: narrows the variable a prefix
++or--in a condition changes. (3f20b6f) array_key_exists(): narrows the array it finds a key in. (63335e9)isset()offsets: narrows a scalar to a string whenisset()finds an offset in it, and keeps strings. (60fc92b, f00c7be)empty()onmixedkeys: keeps their falsy values. (5a1bd94)!isset(): no longer turns the parent of a missing array key into an array. (20e8525)- Type checks:
is_resource(),is_object(), andis_array()narrow themixedpart of a union. (0df29cb) - Empty
count(): an emptycount()onmixedmay be aCountableobject. (a63ffa9) - Built-in assertions: applies them only when a call resolves to the built-in function. (1fe44ff)
assert(): applies the$thisassertions of a method call. (8d02df0)- Offset clauses: keeps clauses about an offset, minus single-variable ones, when
&&orcasenarrows its array. (e87ee99, eae1d4a) - List offsets: an offset found in a list proves that the offsets before it exist. (e158deb)
- Stale offsets: forgets an offset narrowing when its index variable changes, or a call may change its key property. (55dfff8, 10fd41d)
- Array key writes: drops a narrowing that the written value's own expression made. (dbf835a)
- Member narrowing: forgets narrowings a call in a conditional operand clears, and memoized results
unset()removes. (85cea22, 472fcaf)
Variables and References
- Property references: checks a reference to a known object's property as a write, bound to the property type. (a327d43, c65e759, 4bafca0)
- Superglobals by reference: keeps the type a call writes to a superglobal passed by reference. (ef2b735)
globalimports: types aglobalimport of a possibly unset variable as nullable. (255a23e)- Offset writes: writing an offset of an undefined or possibly undefined variable defines it as an array. (7558d81, f264d9b)
- By-reference captures: a closure capturing by reference defines the variable for later arguments. (e36087a)
extract(): no longer reports variables as undefined afterextract(). (1a2216b)- Increments: treats
++and--as assignments of their operand. (f8210a3)
Arrays
array_key_first()andarray_key_last(): know that the key they return exists in the array. (#2735, b2115b6)array_merge(): places list positions only after a known prefix, returns lists for int keys, and mergesmixed. (a48add8, 09bb435)- Nested writes: starts an appended element as
[], and updates every array holding an elementunset()removes. (1adfc48, 0bf5332) - Escaped string keys: narrows a key written with escapes the same as the plain key. (be61a12)
- Array or object indexes: reports an index union that may be an array or an object. (4185425)
- Numeric-string keys: lets a numeric-string key be an
int, and accepts integer strings and overlapping keys. (6475201, d53ef10) - Unsealed shapes: keeps unknown keys of unsealed shapes on their fallback type. (cfd35e8)
- Key coercion: stores the key PHP uses for non-key offsets, and follows the largest int key for the next one. (bfcbb63, 4b4c187)
- Required literal keys: treats an offset read with required literal keys as defined. (94c06d6)
- Impossible keys: reports
array_key_exists()with a string key on an int-keyed array as always false. (ddab607) is_callable()arrays: allows destructuring an array narrowed byis_callable(). (2458c2d)- Class constants in properties:
get_object_vars()andarray_column()resolve them in property types. (03cec3b) ArrayAccess: checksnulloffsets against the key type, and binds open type arguments on the first write. (c9baf14, fcac374)
Strings and Numbers
- Casts: types
(object)casts asstdClass, orobjectformixed, and keeps int ranges through(int). (dd88ff6, 0322b19) - String conversion:
echo,print, andincludeaccept what PHP converts to a string, such asStringable. (#2775, 99d2c3a) filter_var(): types it byFILTER_DEFAULT,FILTER_FLAG_EMPTY_STRING_NULL, and array inputs. (faba6d2)parse_url()and Argon2: a parsed URL path may be empty, andPASSWORD_ARGON2_PROVIDERdepends on the build. (2a78ccb)
Generics
- Int bounds: narrows and compares templates bounded by
int. (9468c98) - Intersections: infers templates from the intersection member that extends the parameter type. (dd8dba7)
- Conditional types: evaluates a conditional type on a class template once the template is bound. (#2752, 60ba88c)
- Conditional returns: narrow their template in the branch that matches. (e5ab459)
- Template comparisons: keeps the template when compared to a float literal, class constant, or enum case. (d77a02d, 98f32a5)
- Callbacks: accepts a callback whose parameter takes every value a template allows. (7c17eec)
- Bounds in
foreach: iterates every part of a template's bound. (1ff13c9) - Template defaults: no longer bind
$thisorstaticin the class's own methods. (0e57103) - Asserted subclasses: an asserted generic subclass takes the type arguments of the narrowed type. (df1c778)
Classes and Members
- Property hooks: reports get hooks that may not return and wrong short set hooks, and resolves
parent::$x::get(). (ba5c086, f099235) - Hooked properties: stops reading back writes to virtual and interface hooked properties, and lets set hook
@paramnarrow. (5201220) - Hook magic constants: types
__FUNCTION__and__METHOD__in a property hook as non-empty strings. (1249900) public(set) readonly: allows initializing such properties from any scope, and rejects a wider set visibility. (8c1ff02)__unserialize(): initializes readonly properties. (c2040e2)SimpleXMLElement: types a missing offset asnull, and treats children as dynamic properties. (#2749, b99343f, 61e8925)new $this(): types it asstatic. (362b4f8)- Instantiating class-strings: keeps their intersections, and no longer calls literal ones unsafe. (16334f2, 4ec5d93)
parent: resolves it in overridden signatures against the declaring class, and in traits to the user's parent. (4c7d13e, f38058f)- Return types: reports a native return type disjoint from the parent's docblock return type. (f5ea779)
- Signature mismatches: reports an inherited mismatch once, not on every subclass. (a281ab3)
- Magic accessors: an inaccessible property goes through
__get()and__set(). (10b1adb) - Deprecated enum cases: reports their use. (a5956b0)
- Closures: resolves
::classon a closure toClosure. (8e2cab7) - Constants: keeps a namespaced read's platform type, and the types of the paths that resolve. (417795f, 28a5d50)
Callables
- Unpacking: checks arguments unpacked into non-variadic callees, and allows temporary arrays for by-reference ones. (78a40d6, 10003d3)
- Unpacked lists: reports one of unknown size only when an element can never fit a parameter. (4ff64e7)
- Unpacked string keys: reports them for a callee that forbids named arguments. (89c967f)
- Empty spreads: spreading an empty array passes no arguments. (f257b0a)
- Nullsafe calls: analyzes arguments of a nullsafe call on a non-null receiver, and short-circuits static access. (a0750bb, eb84e52)
- First-class callables: binds
staticin a first-class method callable to its receiver. (733ea09) - Generators: a function that yields without a return type returns a
Generator. (9b05a91) - Closure parameters: a closure parameter typed
iterabletakes the type the callable expects. (2b90d85) - Thrown intersections: tracks a thrown intersection type as one exception. (1f6a622)
Diagnostics
- Function names: names functions in their original case in return diagnostics. (7bcc539)
Codex
- Generic callables: binds a generic callable's templates before comparing it, so
get_class(...)fitsarray_map(). (#2734, 93fca6b) - Inherited docblocks: prefers derived interfaces, and skips docblocks that interfaces document differently. (#2717, d575f49, 6940ba6)
- Conflicting docblocks: skips inherited types that conflict across parents or don't fit the override's native type. (7d5e799, 3ae8300)
static: resolvesstaticin iterable type arguments and inherited template arguments. (fb3d807, bbebd6e)- Trait
self: resolves a trait'sselfto the using class inside nested types. (5cb5d3e) - Traits in assertions: no longer treats a trait as an instance of a class that uses it. (4dd6018)
- Constant definitions: registers
\define()andDEFINE()constants, and keeps every value of repeated ones. (f39f59c, 44e026a) - Constant expressions: infers a constant expression from the constants declared before it. (7253e9f)
- Int shifts: lets left shifts of int ranges overflow. (bcd49d1)
- Keyed arrays: keeps combined keyed arrays non-empty when every part has a required key. (2189c27)
- Unsealed arrays: folds a key into the fallback type when it adds nothing. (e46d0f3)
properties-of: expands it for classes without typed instance properties. (2fe4703)- Open templates: checks values passed to an open template against its constraint. (32d6d60)
- Closure identity: a closure can only be identical to a value that may be a
Closure. (0f77dca) - Truthy
mixed: a falsy value combined with truthymixedis no longer truthy. (79569d3) class-string<object>: accepts it. (b80c4d1)Stringableequality: aStringableobject can loosely equal a string. (5cdbef1)- Object keys: an iterable with object keys is never an array. (308dbcb)
PHPDoc Syntax
- Angle brackets: an angle bracket that starts a line no longer opens a generic argument list. (76fe072)
- WordPress hashes: parses WordPress hash notation in docblocks. (92db8e2)
- Int strings: understands
decimal-int-stringandnon-decimal-int-string. (aad0f24) - Inline tags: an inline tag after a type no longer opens a shape. (6612bec)
Prelude
curl_multi_info_read(): returns aCurlHandlein its result, orfalse. (#2736, #2737, 203245a, 1fcdc0f)curl_share_init_persistent(): corrects its signature. (4d09352)preg_match_all()keys: allows string keys for named groups in its matches. (#2441, #2706, bb12bb1)- PCRE flags: types the matches of
preg_match()andpreg_match_all()by their flags. (eec3ea6) end()andprev(): keep the array's key types. (#2780, #2781, ba5706c)explode(): may return an empty list for a negative limit. (eb98d37)truereturns: typesArrayObjectandArrayIteratorsort methods andldap_free_result()as returningtrue. (30c67ca, 4078a31)- Paths: file tests that return
truenarrow the path to a non-empty string, andpathinfo()always has adirname. (3492c5b, 0432fcc) - Output parameters:
proc_open()and the scanf functions may write any value;pcntl_waitpid()writes anint. (8f88102, 6e5521f) stream_get_meta_data(): makes the keys PHP may leave out optional. (93dc38b)- Reflection:
ReflectionClass::isInstance()keeps the type of an object it rejects. (4a911da) ResourceBundle: allows reading its offsets. (cb3063e)- DOM and SimpleXML:
DOMNode::$childNodesholds only nodes, andSimpleXMLElement::current()is nevernull. (d2a1f74, 399fc13) - Array arguments: string replacement and key functions accept the arrays PHP accepts. (03473ec)
- RedisCluster: adds
RedisClusterfrom the phpredis stubs. (2dfbcec) - Dates:
DateIntervaldate fields are writable, andgetTimezone()may returnfalse. (ae7d093, a6e37ca) - Database fetches: fetch functions return lists, and counts are numeric. (0c6ebd1)
func_get_args(): returns a list, andclass_exists()and similar checks are not pure, as they may autoload. (1d56e6d)- Signatures: corrects
ob_start(),pcntl_signal_get_handler(), and the file time functions. (7253e69)
Linter
literal-named-argument: checks method calls only with the newcheck-method-callsoption. (#2741, #2758, 30291a7)no-dead-store: a write intryno longer makes an earlier one dead. (#2766, b1b037c)
Semantics
- Imports: reports imports whose name is already in use. (#2732, #2733, 1c3db8d)
#[\Deprecated]: reports it on classes, interfaces, and enums. (#2745, #2746, f84fa17)- Reserved names: reports reserved type names used as class names. (#2750, #2751, ed0cd97)
- Property hooks: reports a
sethook that returns a value, and a typedgethook that returns none. (d9a8c6e) parent: reportsparentin a class-like with no parent. (87f353f)- Magic methods: checks magic method parameters the way PHP does. (#2755, #2756, 89d4723)
callableproperties: reportscallableas a property type. (#2773, #2774, 061da27)- Constant types: reports
callable,void, andneveras class constant types. (#2776, #2777, 01de7f1) $this: reports invalid uses of$this. (#2785, #2786, 4a2aa36)
Twig Formatter
Twig Linter
end-block-name: keeps its fixes parseable for blocks and macros named after operators such asnot. (16c5f5b)
Reporting
Database
- Symlinks: keeps the name of a file passed by path instead of resolving it through symlinks. (#2743, ac77719)
Orchestrator
- Stack size: runs a single worker on the thread pool, so it gets the configured
stack-size. (#2761, #2762, 0af918c)
PHP SDK
- Metadata cache: keeps the entries of concurrent metadata requests. (#2759, #2760, 3dc531f)
- Plugin registration: registers analyzer plugins on the first analyzer request only. (#2753, #2754, ac95e85)
Namespacecases: renamesNodeKind::NamespaceandFunctionTargetKind::NamespacetoNamespace_for PHP 8.6. (#2784, 1fc5946)
🏗️ Internal
Testing
- Generics: expects only the template bound error for a bad
@implements. (bbb9215)
Sponsors
- Sponsor list: refreshes the sponsor list. (e9588b7)
🧩 Extension Protocol
No protocol changes in this release. The PHP SDK renames the Namespace cases of NodeKind and FunctionTargetKind to Namespace_, so update extensions that use them.
🙏 Thank You
Contributors
Thank you to everyone who contributed to this release:
- @amateescu: #2754, #2762
- @AnnaDamm: #2526, #2760
- @Bleksak: #2781
- @klausi: #2717
- @mytskine: #2737
- @okhoshi: #2743
- @roryabraham: #2744
- @thunderer: #2733, #2746, #2751, #2756, #2764, #2774, #2777, #2786
- @zerone0x: #2706
Issue Reporters
Thank you to everyone who reported issues that shaped this release:
- @amateescu: #2753, #2761
- @AnnaDamm: #2501, #2759
- @BafS: #2784
- @bendavies: #2734, #2735
- @Bleksak: #2780
- @devnix: #2752
- @dragosprotung: #2738, #2739
- @evolbug: #2441
- @lavalade: #2740
- @MidnightDesign: #2741
- @mytskine: #2736, #2775
- @phcorp: #2749
- @prismyq: #2758
- @roryabraham: #2669
- @Simbiat: #2768, #2769
- @thunderer: #2732, #2742, #2745, #2750, #2755, #2763, #2773, #2776, #2785
- @wouterrutgers: #2766
Full Changelog: 1.60.2...1.61.0