==== PHPStan : Types PHPDoc au format EBNF ====

This documentation is about how to code accurate types in those  PHPDoc types :

<code>
@param Class_With_Generics<int,object>
@return void
@var int<0,max>
</code>

I wanted to have a precise description about how PHP precisely described types may be described into PHPDoc comments. PHPStan, the PHPStorm IDE (partially), and probably other ones, use these information to help the developer with quality tools and completion.

An EBNF description of how PHPDoc should be filled is a way to have a precise documentation for this.

==== PHPStan : PHPDoc Types in EBNF format ====

type = advanced-array | advanced-callable | advanced-int | advanced-string | basic | bottom | class | condition | constant | generic | intersection | iterable | key-of | literal | nullable | parentheses | shape | static | union | value-of | "mixed"

nullable = "?" type

----

basic = "array" | "array-key" | "bool" | "boolean" | "callable" | "double" | "false" | "float" | "int" | "integer" | "iterable" | "null" | "object" | "resource" | "scalar" | "string" | "true" | "void"

class = [ "\" ] label { "\" label }

advanced-int = int-mask | int-mask-of | int-range | signed-int

signed-int = "negative-int" | "non-negative-int" | "non-positive-int" | "non-zero-int" | "positive-int"

int-range = "int<" ( signed | "min" ) "," ( signed | "max" ) ">"

advanced-array = class-array | list | typed-array

class-array = class "[]" { "[]" }

typed-array = [ "non-empty-" ] "array<" [ array-key "," ] type ">"

array-key = advanced-int | advanced-string | "int" | "integer" | "string"

list = [ "non-empty-" ] "list<" type ">"

key-of = "key-of<" class-constant ">"

value-of = "value-of<" [ class "::" ] label ">"

iterable = "iterable<" type ">" | class "<" [ array-key "," ] type ">"

generic = class "<" type { "," type } ">"

union = type "|" type

intersection = type "&" type

parentheses = "(" type ")"

static = "$this" | "parent" | "self" | "static"

condition = "(" [ "$" ] label " is " type "?" type ":" type ")"

class-string = "class-string" [ "<" class ">" ]

advanced-string = class-string | "callable-string" | "literal-string" | "non-empty-string" | "non-falsy-string" | "numeric-string" | "truthy-string"

shape = array-shape | object-shape

array-shape = "array{" shape-element { "," shape-element } "}"

object-shape = "object{" shape-element { "," shape-element } "}"

shape-element = [ shape-key [ "?" ] ":" ] type

shape-key = digit | label | quoted-string

literal = float | int | quoted-string

constant = class-constant-s | global-constant | wildcard-constant

class-constant = class "::" label

class-constant-s = class-constant [ "*" ]

global-constant = constant-letter { constant-letter }

wildcard-constant = class "::*"

advanced-callable = callable-type "(" { callable-parameters } "):" type

callable-type = "callable" | "Closure" | "\Closure"

callable-parameters = callable-parameter { "," callable-parameter } [ callable-optional-parameters ]

callable-optional-parameters = "=" { "," callable-parameter "=" }

callable-parameter = type | type "..." | type " " [ "..." ] [ "&" ] "$" label

bottom = "never" | "never-return" | "never-returns" | "no-return"

int-mask = "int-mask<" int-values ">"

int-values = int-union { "," int-union }

int-union = int { "|" int }

int-mask-of = "int-mask-of<" int-mask-content ">"

int-mask-content = int-union | class-constants

class-constants = class-constant "*"

----

int = digit { digit }

float = { digit } "." digit { digit }

label = letter { letter | digit }

signed = [ "-" ] digit { digit }

----

quoted-string = double-quoted | single-quoted

double-quoted = '"' { escape | no-double-quote } '"'

single-quoted = "'" { escape | no-single-quote } "'"

escape = "\" any

no-double-quote = - ( '"' | "\" )

no-single-quote = - ( "'" | "\" )

----

any = "\x01".."\xff"

constant-letter = "A".."Z" | "_"

digit = "0".."9"

letter = "_" | "a".."z" | "A".."Z" | "\x7f".."\xff"

----

==== Syntax : EBNF Variant ===

Added :
  * **-**     any Ascii character sequence not containing the following pattern
  * **..**    characters range following the UTF-8 character table order
  * **\xff**  UTF-8 character hexadecimal code

Removed :
  * **;**     Terminal character

==== Documentation source ====

  * https://phpstan.org/writing-php-code/phpdoc-types
  * https://en.wikipedia.org/wiki/Extended_Backus%E2%80%93Naur_form
  * https://fr.wikipedia.org/wiki/Extended_Backus-Naur_Form
  * http://www.icosaedro.it/articoli/php-syntax-ebnf.txt
  * https://gist.github.com/juokaz/19d98274b2e1a02e3d3d