Choose a common phpdoc tag on classes to indicate all class methods have no side effects

[TysonAndre]

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.

[TysonAndre]

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.

cc @muglug - what do you think about @x-pure on class docblock tags (Alternate name idea: @pure-class)

psalm-immutable(already exists):

Used to annotate a class where every property is treated by consumers as @psalm-readonly and every instance method is treated as @psalm-mutation-free.

psalm-pure/x-pure (suggestion for extending that to classes)

Used to annotate a class where every property is treated by consumers as @psalm-readonly and every instance method is treated as @psalm-pure.