Choose a common phpdoc tag on classes to indicate all class methods have no side effects #5
Description
Related to #4
This is useful when there's an entire class where the methods should be treated as free of side effects (e.g. it'd be an error not to use the return values)
- This should apply to all instance methods, excluding __construct, __wakeup, and __unserialize, and possibly __set/__unset (those set instance properties)
- Static analyzers may have to choose the closest equivalent analysis options if their supported checks differs
Benefits:
- This may eventually be useful in any IDE/tool to warn about calling a function without using the return value
- This helps in recursively analyzing methods to see if their result should be used or if they're free of side effects.
Open questions:
- How this would be inherited
- What constraints would this imply for instance properties
- How to handle void methods
- How should implementations handle non-pure methods in implementations that we want to treat like pure methods (e.g. logging libraries, microtime(), etc.), if the class was marked as immutable.
- Whether it's more broadly useful to have a tag for "must use" or "has no side effects" or both.
@x-must-use-methods or @x-side-effect-free would be my preference for a name- There's a lot of open questions and future standardization might use a slightly different meaning.
A separate tag would be useful for indicating that properties and methods are pure (results should be used and don't modify internal or external state)
- e.g. for
x-pure, an analyzer would additionally warn about setting instance properties on objects of these classes.