From 95d9974da664bd760980193e1a6c51196dd78dab Mon Sep 17 00:00:00 2001
From: Marian <42134098+IanDelMar@users.noreply.github.com>
Date: Mon, 24 Aug 2026 14:23:34 +0200
Subject: [PATCH] path_is_absolute: narrow return type and assert param type

---
 functionMap.php                        |  1 +
 tests/data/assert/path-is-absolute.php | 24 ++++++++++++++++++++++++
 tests/data/return/path-is-absolute.php | 13 +++++++++++++
 wordpress-stubs.php                    |  2 ++
 4 files changed, 40 insertions(+)
 create mode 100644 tests/data/assert/path-is-absolute.php
 create mode 100644 tests/data/return/path-is-absolute.php

diff --git a/functionMap.php b/functionMap.php
index 17e19710..7dea65c5 100644
--- a/functionMap.php
+++ b/functionMap.php
@@ -180,6 +180,7 @@
     'newblog_notify_siteadmin' => [null, 'deprecated' => "''"],
     'next_posts' => ['($display is true ? void : string)'],
     'paginate_links' => ["(\$args is array{total: int<min, 1>}&array ? void : (\$args is array{type: 'array'}&array ? list<string> : string))"],
+    'path_is_absolute' => ['($path is non-falsy-string ? bool : false)', '@phpstan-assert-if-true =non-falsy-string $path' => ''],
     'post_type_archive_title' => ['($display is true ? void : string|void)'],
     'prep_atom_text_construct' => ["array{'html'|'text'|'xhtml', string}"],
     'previous_posts' => ['($display is true ? void : string)'],
diff --git a/tests/data/assert/path-is-absolute.php b/tests/data/assert/path-is-absolute.php
new file mode 100644
index 00000000..416d2207
--- /dev/null
+++ b/tests/data/assert/path-is-absolute.php
@@ -0,0 +1,24 @@
+<?php
+
+declare(strict_types=1);
+
+namespace PhpStubs\WordPress\Core\Tests;
+
+use function path_is_absolute;
+use function PHPStan\Testing\assertType;
+
+$path = Faker::string();
+if (path_is_absolute($path)) {
+    assertType('non-falsy-string', $path);
+}
+if (! path_is_absolute($path)) {
+    assertType('string', $path);
+}
+
+$path = Faker::nonFalsyString();
+if (path_is_absolute($path)) {
+    assertType('non-falsy-string', $path);
+}
+if (! path_is_absolute($path)) {
+    assertType('non-falsy-string', $path);
+}
diff --git a/tests/data/return/path-is-absolute.php b/tests/data/return/path-is-absolute.php
new file mode 100644
index 00000000..0b25cbb2
--- /dev/null
+++ b/tests/data/return/path-is-absolute.php
@@ -0,0 +1,13 @@
+<?php
+
+declare(strict_types=1);
+
+namespace PhpStubs\WordPress\Core\Tests;
+
+use function path_is_absolute;
+use function PHPStan\Testing\assertType;
+
+assertType('false', path_is_absolute(''));
+assertType('false', path_is_absolute('0'));
+assertType('bool', path_is_absolute('foo'));
+assertType('bool', path_is_absolute(Faker::string()));
diff --git a/wordpress-stubs.php b/wordpress-stubs.php
index 95c790b8..6111b127 100644
--- a/wordpress-stubs.php
+++ b/wordpress-stubs.php
@@ -130051,6 +130051,8 @@ function wp_mkdir_p($target)
      *
      * @param string $path File path.
      * @return bool True if path is absolute, false is not absolute.
+     * @phpstan-assert-if-true =non-falsy-string $path
+     * @phpstan-return ($path is non-falsy-string ? bool : false)
      */
     function path_is_absolute($path)
     {