From 20fe6b31261e9417c4a3c357d78323eef0e3596d Mon Sep 17 00:00:00 2001 From: Shish Date: Sun, 6 Apr 2025 21:16:58 +0100 Subject: [PATCH] specify types for all functions --- phpstan.neon.dist | 4 +- src/microhtml.php | 102 ++++++++++++++++++++++++++++++++++++++++++++++ tests/Types.php | 18 ++++++++ 3 files changed, 121 insertions(+), 3 deletions(-) create mode 100644 tests/Types.php diff --git a/phpstan.neon.dist b/phpstan.neon.dist index 2d6a08e..abaa6b7 100644 --- a/phpstan.neon.dist +++ b/phpstan.neon.dist @@ -2,6 +2,4 @@ parameters: paths: - ./src - ./tests - level: 7 - ignoreErrors: - - '#^Function .* has parameter \$args with no type specified.$#' + level: 9 diff --git a/src/microhtml.php b/src/microhtml.php index c52631f..3fab420 100644 --- a/src/microhtml.php +++ b/src/microhtml.php @@ -127,6 +127,7 @@ public function __toString(): string } } +/** @param \MicroHTML\HTMLElement|string|\Stringable|null|bool|int|float $args */ function emptyHTML(...$args): HTMLElement { return new EmptyHTMLElement($args); @@ -173,6 +174,7 @@ function joinHTML(HTMLElement|string $glue, array $pieces, bool $filterNulls = f } # https://developer.mozilla.org/en-US/docs/Web/HTML/Element +/** @param array|\MicroHTML\HTMLElement|string|\Stringable|null|bool|int|float $args */ function HTML(...$args): HTMLElement { return new HTMLElement("html", $args); @@ -184,6 +186,7 @@ function BASE(array $attrs = []): SelfClosingHTMLElement { return new SelfClosingHTMLElement("base", $attrs); } +/** @param array|\MicroHTML\HTMLElement|string|\Stringable|null|bool|int|float $args - attribute array or children */ function HEAD(...$args): HTMLElement { return new HTMLElement("head", $args); @@ -198,112 +201,138 @@ function META(array $attrs = []): SelfClosingHTMLElement { return new SelfClosingHTMLElement("meta", $attrs); } +/** @param array|\MicroHTML\HTMLElement|string|\Stringable|null|bool|int|float $args - attribute array or children */ function STYLE(...$args): HTMLElement { return new HTMLElement("style", $args); } +/** @param array|\MicroHTML\HTMLElement|string|\Stringable|null|bool|int|float $args - attribute array or children */ function TITLE(...$args): HTMLElement { return new HTMLElement("title", $args); } # Sectioning root +/** @param array|\MicroHTML\HTMLElement|string|\Stringable|null|bool|int|float $args - attribute array or children */ function BODY(...$args): HTMLElement { return new HTMLElement("body", $args); } # Content sectioning +/** @param array|\MicroHTML\HTMLElement|string|\Stringable|null|bool|int|float $args - attribute array or children */ function ADDRESS(...$args): HTMLElement { return new HTMLElement("address", $args); } +/** @param array|\MicroHTML\HTMLElement|string|\Stringable|null|bool|int|float $args - attribute array or children */ function ARTICLE(...$args): HTMLElement { return new HTMLElement("article", $args); } +/** @param array|\MicroHTML\HTMLElement|string|\Stringable|null|bool|int|float $args - attribute array or children */ function ASIDE(...$args): HTMLElement { return new HTMLElement("aside", $args); } +/** @param array|\MicroHTML\HTMLElement|string|\Stringable|null|bool|int|float $args - attribute array or children */ function FOOTER(...$args): HTMLElement { return new HTMLElement("footer", $args); } +/** @param array|\MicroHTML\HTMLElement|string|\Stringable|null|bool|int|float $args - attribute array or children */ function HEADER(...$args): HTMLElement { return new HTMLElement("header", $args); } +/** @param array|\MicroHTML\HTMLElement|string|\Stringable|null|bool|int|float $args - attribute array or children */ function H1(...$args): HTMLElement { return new HTMLElement("h1", $args); } +/** @param array|\MicroHTML\HTMLElement|string|\Stringable|null|bool|int|float $args - attribute array or children */ function H2(...$args): HTMLElement { return new HTMLElement("h2", $args); } +/** @param array|\MicroHTML\HTMLElement|string|\Stringable|null|bool|int|float $args - attribute array or children */ function H3(...$args): HTMLElement { return new HTMLElement("h3", $args); } +/** @param array|\MicroHTML\HTMLElement|string|\Stringable|null|bool|int|float $args - attribute array or children */ function H4(...$args): HTMLElement { return new HTMLElement("h4", $args); } +/** @param array|\MicroHTML\HTMLElement|string|\Stringable|null|bool|int|float $args - attribute array or children */ function H5(...$args): HTMLElement { return new HTMLElement("h5", $args); } +/** @param array|\MicroHTML\HTMLElement|string|\Stringable|null|bool|int|float $args - attribute array or children */ function H6(...$args): HTMLElement { return new HTMLElement("h6", $args); } +/** @param array|\MicroHTML\HTMLElement|string|\Stringable|null|bool|int|float $args - attribute array or children */ function HGROUP(...$args): HTMLElement { return new HTMLElement("hgroup", $args); } +/** @param array|\MicroHTML\HTMLElement|string|\Stringable|null|bool|int|float $args - attribute array or children */ function MAIN(...$args): HTMLElement { return new HTMLElement("main", $args); } +/** @param array|\MicroHTML\HTMLElement|string|\Stringable|null|bool|int|float $args - attribute array or children */ function NAV(...$args): HTMLElement { return new HTMLElement("nav", $args); } +/** @param array|\MicroHTML\HTMLElement|string|\Stringable|null|bool|int|float $args - attribute array or children */ function SECTION(...$args): HTMLElement { return new HTMLElement("section", $args); } # Text content +/** @param array|\MicroHTML\HTMLElement|string|\Stringable|null|bool|int|float $args - attribute array or children */ function BLOCKQUOTE(...$args): HTMLElement { return new HTMLElement("blockquote", $args); } +/** @param array|\MicroHTML\HTMLElement|string|\Stringable|null|bool|int|float $args - attribute array or children */ function DD(...$args): HTMLElement { return new HTMLElement("dd", $args); } +/** @param array|\MicroHTML\HTMLElement|string|\Stringable|null|bool|int|float $args - attribute array or children */ function DIR(...$args): HTMLElement { return new HTMLElement("dir", $args); } +/** @param array|\MicroHTML\HTMLElement|string|\Stringable|null|bool|int|float $args - attribute array or children */ function DIV(...$args): HTMLElement { return new HTMLElement("div", $args); } +/** @param array|\MicroHTML\HTMLElement|string|\Stringable|null|bool|int|float $args - attribute array or children */ function DL(...$args): HTMLElement { return new HTMLElement("dl", $args); } +/** @param array|\MicroHTML\HTMLElement|string|\Stringable|null|bool|int|float $args - attribute array or children */ function DT(...$args): HTMLElement { return new HTMLElement("dt", $args); } +/** @param array|\MicroHTML\HTMLElement|string|\Stringable|null|bool|int|float $args - attribute array or children */ function FIGCAPTION(...$args): HTMLElement { return new HTMLElement("figcaption", $args); } +/** @param array|\MicroHTML\HTMLElement|string|\Stringable|null|bool|int|float $args - attribute array or children */ function FIGURE(...$args): HTMLElement { return new HTMLElement("figure", $args); @@ -313,44 +342,54 @@ function HR(array $attrs = []): SelfClosingHTMLElement { return new SelfClosingHTMLElement("hr", $attrs); } +/** @param array|\MicroHTML\HTMLElement|string|\Stringable|null|bool|int|float $args - attribute array or children */ function LI(...$args): HTMLElement { return new HTMLElement("li", $args); } +/** @param array|\MicroHTML\HTMLElement|string|\Stringable|null|bool|int|float $args - attribute array or children */ function OL(...$args): HTMLElement { return new HTMLElement("ol", $args); } +/** @param array|\MicroHTML\HTMLElement|string|\Stringable|null|bool|int|float $args - attribute array or children */ function P(...$args): HTMLElement { return new HTMLElement("p", $args); } +/** @param array|\MicroHTML\HTMLElement|string|\Stringable|null|bool|int|float $args - attribute array or children */ function PRE(...$args): HTMLElement { return new HTMLElement("pre", $args); } +/** @param array|\MicroHTML\HTMLElement|string|\Stringable|null|bool|int|float $args - attribute array or children */ function UL(...$args): HTMLElement { return new HTMLElement("ul", $args); } # Inline text semantics +/** @param array|\MicroHTML\HTMLElement|string|\Stringable|null|bool|int|float $args - attribute array or children */ function A(...$args): HTMLElement { return new HTMLElement("a", $args); } +/** @param array|\MicroHTML\HTMLElement|string|\Stringable|null|bool|int|float $args - attribute array or children */ function ABBR(...$args): HTMLElement { return new HTMLElement("abbr", $args); } +/** @param array|\MicroHTML\HTMLElement|string|\Stringable|null|bool|int|float $args - attribute array or children */ function B(...$args): HTMLElement { return new HTMLElement("b", $args); } +/** @param array|\MicroHTML\HTMLElement|string|\Stringable|null|bool|int|float $args - attribute array or children */ function BDI(...$args): HTMLElement { return new HTMLElement("bdi", $args); } +/** @param array|\MicroHTML\HTMLElement|string|\Stringable|null|bool|int|float $args - attribute array or children */ function BDO(...$args): HTMLElement { return new HTMLElement("bdo", $args); @@ -360,102 +399,127 @@ function BR(array $attrs = []): SelfClosingHTMLElement { return new SelfClosingHTMLElement("br", $attrs); } +/** @param array|\MicroHTML\HTMLElement|string|\Stringable|null|bool|int|float $args - attribute array or children */ function CITE(...$args): HTMLElement { return new HTMLElement("cite", $args); } +/** @param array|\MicroHTML\HTMLElement|string|\Stringable|null|bool|int|float $args - attribute array or children */ function CODE(...$args): HTMLElement { return new HTMLElement("code", $args); } +/** @param array|\MicroHTML\HTMLElement|string|\Stringable|null|bool|int|float $args - attribute array or children */ function DATA(...$args): HTMLElement { return new HTMLElement("data", $args); } +/** @param array|\MicroHTML\HTMLElement|string|\Stringable|null|bool|int|float $args - attribute array or children */ function DFN(...$args): HTMLElement { return new HTMLElement("dfn", $args); } +/** @param array|\MicroHTML\HTMLElement|string|\Stringable|null|bool|int|float $args - attribute array or children */ function EM(...$args): HTMLElement { return new HTMLElement("em", $args); } +/** @param array|\MicroHTML\HTMLElement|string|\Stringable|null|bool|int|float $args - attribute array or children */ function I(...$args): HTMLElement { return new HTMLElement("i", $args); } +/** @param array|\MicroHTML\HTMLElement|string|\Stringable|null|bool|int|float $args - attribute array or children */ function KBD(...$args): HTMLElement { return new HTMLElement("kbd", $args); } +/** @param array|\MicroHTML\HTMLElement|string|\Stringable|null|bool|int|float $args - attribute array or children */ function MARK(...$args): HTMLElement { return new HTMLElement("mark", $args); } +/** @param array|\MicroHTML\HTMLElement|string|\Stringable|null|bool|int|float $args - attribute array or children */ function Q(...$args): HTMLElement { return new HTMLElement("q", $args); } +/** @param array|\MicroHTML\HTMLElement|string|\Stringable|null|bool|int|float $args - attribute array or children */ function RB(...$args): HTMLElement { return new HTMLElement("rb", $args); } +/** @param array|\MicroHTML\HTMLElement|string|\Stringable|null|bool|int|float $args - attribute array or children */ function RP(...$args): HTMLElement { return new HTMLElement("rp", $args); } +/** @param array|\MicroHTML\HTMLElement|string|\Stringable|null|bool|int|float $args - attribute array or children */ function RT(...$args): HTMLElement { return new HTMLElement("rt", $args); } +/** @param array|\MicroHTML\HTMLElement|string|\Stringable|null|bool|int|float $args - attribute array or children */ function RTC(...$args): HTMLElement { return new HTMLElement("rtc", $args); } +/** @param array|\MicroHTML\HTMLElement|string|\Stringable|null|bool|int|float $args - attribute array or children */ function RUBY(...$args): HTMLElement { return new HTMLElement("ruby", $args); } +/** @param array|\MicroHTML\HTMLElement|string|\Stringable|null|bool|int|float $args - attribute array or children */ function S(...$args): HTMLElement { return new HTMLElement("s", $args); } +/** @param array|\MicroHTML\HTMLElement|string|\Stringable|null|bool|int|float $args - attribute array or children */ function SAMP(...$args): HTMLElement { return new HTMLElement("samp", $args); } +/** @param array|\MicroHTML\HTMLElement|string|\Stringable|null|bool|int|float $args - attribute array or children */ function SMALL(...$args): HTMLElement { return new HTMLElement("small", $args); } +/** @param array|\MicroHTML\HTMLElement|string|\Stringable|null|bool|int|float $args - attribute array or children */ function SPAN(...$args): HTMLElement { return new HTMLElement("span", $args); } +/** @param array|\MicroHTML\HTMLElement|string|\Stringable|null|bool|int|float $args - attribute array or children */ function STRONG(...$args): HTMLElement { return new HTMLElement("strong", $args); } +/** @param array|\MicroHTML\HTMLElement|string|\Stringable|null|bool|int|float $args - attribute array or children */ function SUB(...$args): HTMLElement { return new HTMLElement("sub", $args); } +/** @param array|\MicroHTML\HTMLElement|string|\Stringable|null|bool|int|float $args - attribute array or children */ function SUP(...$args): HTMLElement { return new HTMLElement("sup", $args); } +/** @param array|\MicroHTML\HTMLElement|string|\Stringable|null|bool|int|float $args - attribute array or children */ function TIME(...$args): HTMLElement { return new HTMLElement("time", $args); } +/** @param array|\MicroHTML\HTMLElement|string|\Stringable|null|bool|int|float $args - attribute array or children */ function TT(...$args): HTMLElement { return new HTMLElement("tt", $args); } +/** @param array|\MicroHTML\HTMLElement|string|\Stringable|null|bool|int|float $args - attribute array or children */ function U(...$args): HTMLElement { return new HTMLElement("u", $args); } +/** @param array|\MicroHTML\HTMLElement|string|\Stringable|null|bool|int|float $args - attribute array or children */ function VAR_(...$args): HTMLElement { return new HTMLElement("var", $args); @@ -472,6 +536,7 @@ function AREA(array $attrs = []): SelfClosingHTMLElement { return new SelfClosingHTMLElement("area", $attrs); } +/** @param array|\MicroHTML\HTMLElement|string|\Stringable|null|bool|int|float $args - attribute array or children */ function AUDIO(...$args): HTMLElement { return new HTMLElement("audio", $args); @@ -481,6 +546,7 @@ function IMG(array $attrs = []): SelfClosingHTMLElement { return new SelfClosingHTMLElement("img", $attrs); } +/** @param array|\MicroHTML\HTMLElement|string|\Stringable|null|bool|int|float $args - attribute array or children */ function MAP(...$args): HTMLElement { return new HTMLElement("map", $args); @@ -490,12 +556,14 @@ function TRACK(array $attrs = []): SelfClosingHTMLElement { return new SelfClosingHTMLElement("track", $attrs); } +/** @param array|\MicroHTML\HTMLElement|string|\Stringable|null|bool|int|float $args - attribute array or children */ function VIDEO(...$args): HTMLElement { return new HTMLElement("video", $args); } # Embedded content +/** @param array|\MicroHTML\HTMLElement|string|\Stringable|null|bool|int|float $args - attribute array or children */ function APPLET(...$args): HTMLElement { return new HTMLElement("applet", $args); @@ -505,14 +573,17 @@ function EMBED(array $attrs = []): SelfClosingHTMLElement { return new SelfClosingHTMLElement("embed", $attrs); } +/** @param array|\MicroHTML\HTMLElement|string|\Stringable|null|bool|int|float $args - attribute array or children */ function IFRAME(...$args): HTMLElement { return new HTMLElement("iframe", $args); } +/** @param array|\MicroHTML\HTMLElement|string|\Stringable|null|bool|int|float $args - attribute array or children */ function NOEMBED(...$args): HTMLElement { return new HTMLElement("noembed", $args); } +/** @param array|\MicroHTML\HTMLElement|string|\Stringable|null|bool|int|float $args - attribute array or children */ function OBJECT(...$args): HTMLElement { return new HTMLElement("object", $args); @@ -522,6 +593,7 @@ function PARAM(array $attrs = []): SelfClosingHTMLElement { return new SelfClosingHTMLElement("param", $attrs); } +/** @param array|\MicroHTML\HTMLElement|string|\Stringable|null|bool|int|float $args - attribute array or children */ function PICTURE(...$args): HTMLElement { return new HTMLElement("picture", $args); @@ -533,30 +605,36 @@ function SOURCE(array $attrs = []): SelfClosingHTMLElement } # Scripting +/** @param array|\MicroHTML\HTMLElement|string|\Stringable|null|bool|int|float $args - attribute array or children */ function CANVAS(...$args): HTMLElement { return new HTMLElement("canvas", $args); } +/** @param array|\MicroHTML\HTMLElement|string|\Stringable|null|bool|int|float $args - attribute array or children */ function NOSCRIPT(...$args): HTMLElement { return new HTMLElement("noscript", $args); } +/** @param array|\MicroHTML\HTMLElement|string|\Stringable|null|bool|int|float $args - attribute array or children */ function SCRIPT(...$args): HTMLElement { return new HTMLElement("script", $args); } # Demarcating edits +/** @param array|\MicroHTML\HTMLElement|string|\Stringable|null|bool|int|float $args - attribute array or children */ function DEL(...$args): HTMLElement { return new HTMLElement("del", $args); } +/** @param array|\MicroHTML\HTMLElement|string|\Stringable|null|bool|int|float $args - attribute array or children */ function INS(...$args): HTMLElement { return new HTMLElement("ins", $args); } # Table content +/** @param array|\MicroHTML\HTMLElement|string|\Stringable|null|bool|int|float $args - attribute array or children */ function CAPTION(...$args): HTMLElement { return new HTMLElement("caption", $args); @@ -566,52 +644,64 @@ function COL(array $attrs = []): SelfClosingHTMLElement { return new SelfClosingHTMLElement("col", $attrs); } +/** @param array|\MicroHTML\HTMLElement|string|\Stringable|null|bool|int|float $args - attribute array or children */ function COLGROUP(...$args): HTMLElement { return new HTMLElement("colgroup", $args); } +/** @param array|\MicroHTML\HTMLElement|string|\Stringable|null|bool|int|float $args - attribute array or children */ function TABLE(...$args): HTMLElement { return new HTMLElement("table", $args); } +/** @param array|\MicroHTML\HTMLElement|string|\Stringable|null|bool|int|float $args - attribute array or children */ function TBODY(...$args): HTMLElement { return new HTMLElement("tbody", $args); } +/** @param array|\MicroHTML\HTMLElement|string|\Stringable|null|bool|int|float $args - attribute array or children */ function TD(...$args): HTMLElement { return new HTMLElement("td", $args); } +/** @param array|\MicroHTML\HTMLElement|string|\Stringable|null|bool|int|float $args - attribute array or children */ function TFOOT(...$args): HTMLElement { return new HTMLElement("tfoot", $args); } +/** @param array|\MicroHTML\HTMLElement|string|\Stringable|null|bool|int|float $args - attribute array or children */ function TH(...$args): HTMLElement { return new HTMLElement("th", $args); } +/** @param array|\MicroHTML\HTMLElement|string|\Stringable|null|bool|int|float $args - attribute array or children */ function THEAD(...$args): HTMLElement { return new HTMLElement("thead", $args); } +/** @param array|\MicroHTML\HTMLElement|string|\Stringable|null|bool|int|float $args - attribute array or children */ function TR(...$args): HTMLElement { return new HTMLElement("tr", $args); } # Forms +/** @param array|\MicroHTML\HTMLElement|string|\Stringable|null|bool|int|float $args - attribute array or children */ function BUTTON(...$args): HTMLElement { return new HTMLElement("button", $args); } +/** @param array|\MicroHTML\HTMLElement|string|\Stringable|null|bool|int|float $args - attribute array or children */ function DATALIST(...$args): HTMLElement { return new HTMLElement("datalist", $args); } +/** @param array|\MicroHTML\HTMLElement|string|\Stringable|null|bool|int|float $args - attribute array or children */ function FIELDSET(...$args): HTMLElement { return new HTMLElement("fieldset", $args); } +/** @param array|\MicroHTML\HTMLElement|string|\Stringable|null|bool|int|float $args - attribute array or children */ function FORM(...$args): HTMLElement { return new HTMLElement("form", $args); @@ -621,52 +711,64 @@ function INPUT(array $attrs = []): SelfClosingHTMLElement { return new SelfClosingHTMLElement("input", $attrs); } +/** @param array|\MicroHTML\HTMLElement|string|\Stringable|null|bool|int|float $args - attribute array or children */ function LABEL(...$args): HTMLElement { return new HTMLElement("label", $args); } +/** @param array|\MicroHTML\HTMLElement|string|\Stringable|null|bool|int|float $args - attribute array or children */ function LEGEND(...$args): HTMLElement { return new HTMLElement("legend", $args); } +/** @param array|\MicroHTML\HTMLElement|string|\Stringable|null|bool|int|float $args - attribute array or children */ function METER(...$args): HTMLElement { return new HTMLElement("meter", $args); } +/** @param array|\MicroHTML\HTMLElement|string|\Stringable|null|bool|int|float $args - attribute array or children */ function OPTGROUP(...$args): HTMLElement { return new HTMLElement("optgroup", $args); } +/** @param array|\MicroHTML\HTMLElement|string|\Stringable|null|bool|int|float $args - attribute array or children */ function OPTION(...$args): HTMLElement { return new HTMLElement("option", $args); } +/** @param array|\MicroHTML\HTMLElement|string|\Stringable|null|bool|int|float $args - attribute array or children */ function OUTPUT(...$args): HTMLElement { return new HTMLElement("output", $args); } +/** @param array|\MicroHTML\HTMLElement|string|\Stringable|null|bool|int|float $args - attribute array or children */ function PROGRESS(...$args): HTMLElement { return new HTMLElement("progress", $args); } +/** @param array|\MicroHTML\HTMLElement|string|\Stringable|null|bool|int|float $args - attribute array or children */ function SELECT(...$args): HTMLElement { return new HTMLElement("select", $args); } +/** @param array|\MicroHTML\HTMLElement|string|\Stringable|null|bool|int|float $args - attribute array or children */ function TEXTAREA(...$args): HTMLElement { return new HTMLElement("textarea", $args); } # Interactive elements +/** @param array|\MicroHTML\HTMLElement|string|\Stringable|null|bool|int|float $args - attribute array or children */ function DETAILS(...$args): HTMLElement { return new HTMLElement("details", $args); } +/** @param array|\MicroHTML\HTMLElement|string|\Stringable|null|bool|int|float $args - attribute array or children */ function DIALOG(...$args): HTMLElement { return new HTMLElement("dialog", $args); } +/** @param array|\MicroHTML\HTMLElement|string|\Stringable|null|bool|int|float $args - attribute array or children */ function SUMMARY(...$args): HTMLElement { return new HTMLElement("summary", $args); diff --git a/tests/Types.php b/tests/Types.php new file mode 100644 index 0000000..e1d6efd --- /dev/null +++ b/tests/Types.php @@ -0,0 +1,18 @@ + +P(["class" => "foo"]); // properties allowed +P(["foo", "bar", "baz"]); // @phpstan-ignore-line - no non-property arrays allowed +P(P(), P()); // multiple children allowed +P([P(), P()]); // @phpstan-ignore-line - no arrays-of-children allowed + +// void tags should have no children +IMG(["src" => "foo.jpg"]); // properties allowed +IMG(["foo", "bar"]); // @phpstan-ignore-line - no non-property arrays allowed +IMG(P()); // @phpstan-ignore-line - no children allowed