From 570cca8e7b8b35aa88d60f8d1400b9387c6b8bfb Mon Sep 17 00:00:00 2001
From: Navarr <navarr.barnier@aeroflowinc.com>
Date: Fri, 11 Jul 2025 17:05:27 -0400
Subject: [PATCH] Add Stubs for Magento's loosey-string behavior

In many cases, Magento typedefs a `string` but truly accepts anything that can be cast to a string. This can be annoying for things like Escaper and Session Messages, which many are inclined to pass Phrase objects into.

Additionally, Escaper has return types of `string|array`, passing an array if the input is an array. However, Magento's documentation blocks don't specify that's when it passes an array - so phpstan thinks that the result of Escaper can be either at any time.  In that way, you cannot echo out the result of an `escapeHtml` in a PHTML file on max level without getting some errors.
---
 src/Magento/Framework/Escaper.php             |  69 ++++++
 .../Framework/Message/ManagerInterface.php    | 212 ++++++++++++++++++
 .../Framework/Message/MessageInterface.php    | 118 ++++++++++
 3 files changed, 399 insertions(+)
 create mode 100644 src/Magento/Framework/Escaper.php
 create mode 100644 src/Magento/Framework/Message/ManagerInterface.php
 create mode 100644 src/Magento/Framework/Message/MessageInterface.php

diff --git a/src/Magento/Framework/Escaper.php b/src/Magento/Framework/Escaper.php
new file mode 100644
index 0000000..bdd7673
--- /dev/null
+++ b/src/Magento/Framework/Escaper.php
@@ -0,0 +1,69 @@
+<?php
+
+namespace Magento\Framework;
+
+use Stringable;
+
+/**
+ * @phpstan-type CastableToString null|scalar|Stringable
+ */
+class Escaper
+{
+    /**
+     * @param CastableToString|array<CastableToString> $data
+     * @param string[]|null $allowedTags
+     * @return ($data is array ? string[] : string)
+     */
+    public function escapeHtml($data, array|null $allowedTags = null) {}
+
+    /**
+     * @param CastableToString $string
+     * @param bool $escapeSingleQuote
+     * @return string
+     */
+    public function escapeHtmlAttr($string, bool $escapeSingleQuote = true) {}
+
+    /**
+     * @param CastableToString $string
+     * @return string
+     */
+    public function escapeUrl($string) {}
+
+    /**
+     * @param CastableToString $string
+     * @return string
+     */
+    public function encodeUrlParam($string) {}
+
+    /**
+     * @param CastableToString $string
+     * @return string
+     */
+    public function escapeJs($string) {}
+
+    /**
+     * @param CastableToString $string
+     * @return string
+     */
+    public function escapeCss($string) {}
+
+    /**
+     * @param CastableToString[]|CastableToString $data
+     * @param string $quote
+     * @return ($data is array ? string[] : string)
+     */
+    public function  escapeJsQuote($data, string $quote = '\'') {}
+
+    /**
+     * @param CastableToString $data
+     * @return string
+     */
+    public function escapeXssInUrl($data) {}
+
+    /**
+     * @param string $data
+     * @param bool $addSlashes
+     * @return string
+     */
+    public function escapeQuote(string $data, bool $addSlashes = false) {}
+}
\ No newline at end of file
diff --git a/src/Magento/Framework/Message/ManagerInterface.php b/src/Magento/Framework/Message/ManagerInterface.php
new file mode 100644
index 0000000..7621b14
--- /dev/null
+++ b/src/Magento/Framework/Message/ManagerInterface.php
@@ -0,0 +1,212 @@
+<?php
+/**
+ * Copyright © Magento, Inc. All rights reserved.
+ * See COPYING.txt for license details.
+ */
+namespace Magento\Framework\Message;
+
+use \Stringable;
+
+/**
+ * Adds different types of messages to the session, and allows access to existing messages.
+ *
+ * @api
+ * @since 100.0.2
+ */
+interface ManagerInterface
+{
+    /**
+     * Retrieve messages
+     *
+     * @param bool $clear
+     * @param string|null $group
+     * @return Collection
+     */
+    public function getMessages($clear = false, $group = null);
+
+    /**
+     * Retrieve default message group
+     *
+     * @return string
+     */
+    public function getDefaultGroup();
+
+    /**
+     * Adds new message to message collection
+     *
+     * @param MessageInterface $message
+     * @param string|null $group
+     * @return ManagerInterface
+     */
+    public function addMessage(MessageInterface $message, $group = null);
+
+    /**
+     * Adds messages array to message collection
+     *
+     * @param MessageInterface[] $messages
+     * @param string|null $group
+     * @return ManagerInterface
+     */
+    public function addMessages(array $messages, $group = null);
+
+    /**
+     * Adds new error message
+     *
+     * @param null|scalar|Stringable $message
+     * @param string|null $group
+     * @return ManagerInterface
+     * @deprecated 100.1.0
+     * @see \Magento\Framework\Message\ManagerInterface::addErrorMessage
+     */
+    public function addError($message, $group = null);
+
+    /**
+     * Adds new warning message
+     *
+     * @param null|scalar|Stringable $message
+     * @param string|null $group
+     * @return ManagerInterface
+     * @deprecated 100.1.0
+     * @see \Magento\Framework\Message\ManagerInterface::addWarningMessage
+     */
+    public function addWarning($message, $group = null);
+
+    /**
+     * Adds new notice message
+     *
+     * @param null|scalar|Stringable $message
+     * @param string|null $group
+     * @return ManagerInterface
+     * @deprecated 100.1.0
+     * @see \Magento\Framework\Message\ManagerInterface::addNoticeMessage
+     */
+    public function addNotice($message, $group = null);
+
+    /**
+     * Adds new success message
+     *
+     * @param null|scalar|Stringable $message
+     * @param string|null $group
+     * @return ManagerInterface
+     * @deprecated 100.1.0
+     * @see \Magento\Framework\Message\ManagerInterface::addSuccessMessage
+     */
+    public function addSuccess($message, $group = null);
+
+    /**
+     * Adds new error message
+     *
+     * @param null|scalar|Stringable $message
+     * @param string|null $group
+     * @return ManagerInterface
+     */
+    public function addErrorMessage($message, $group = null);
+
+    /**
+     * Adds new warning message
+     *
+     * @param null|scalar|Stringable $message
+     * @param string|null $group
+     * @return ManagerInterface
+     */
+    public function addWarningMessage($message, $group = null);
+
+    /**
+     * Adds new notice message
+     *
+     * @param null|scalar|Stringable $message
+     * @param string|null $group
+     * @return ManagerInterface
+     */
+    public function addNoticeMessage($message, $group = null);
+
+    /**
+     * Adds new success message
+     *
+     * @param null|scalar|Stringable $message
+     * @param string|null $group
+     * @return ManagerInterface
+     */
+    public function addSuccessMessage($message, $group = null);
+
+    /**
+     * Adds new complex error message
+     *
+     * @param string $identifier
+     * @param mixed[] $data
+     * @param string|null $group
+     * @return ManagerInterface
+     */
+    public function addComplexErrorMessage($identifier, array $data = [], $group = null);
+
+    /**
+     * Adds new complex warning message
+     *
+     * @param string $identifier
+     * @param mixed[] $data
+     * @param string|null $group
+     * @return ManagerInterface
+     */
+    public function addComplexWarningMessage($identifier, array $data = [], $group = null);
+
+    /**
+     * Adds new complex notice message
+     *
+     * @param string $identifier
+     * @param mixed[] $data
+     * @param string|null $group
+     * @return ManagerInterface
+     */
+    public function addComplexNoticeMessage($identifier, array $data = [], $group = null);
+
+    /**
+     * Adds new complex success message
+     *
+     * @param string $identifier
+     * @param mixed[] $data
+     * @param string|null $group
+     * @return ManagerInterface
+     */
+    public function addComplexSuccessMessage($identifier, array $data = [], $group = null);
+
+    /**
+     * Adds messages array to message collection, without adding duplicate messages
+     *
+     * @param MessageInterface[] $messages
+     * @param string|null $group
+     * @return ManagerInterface
+     */
+    public function addUniqueMessages(array $messages, $group = null);
+
+    /**
+     * Adds a message describing an exception. Does not contain Exception handling logic.
+     *
+     * @param \Exception $exception
+     * @param scalar|Stringable|null $alternativeText
+     * @param string|null $group
+     * @return ManagerInterface
+     * @deprecated 100.1.0
+     * @see \Magento\Framework\Message\ManagerInterface::addExceptionMessage
+     */
+    public function addException(\Exception $exception, $alternativeText = null, $group = null);
+
+    /**
+     * Adds a message describing an exception. Does not contain Exception handling logic.
+     *
+     * @param \Exception $exception
+     * @param scalar|Stringable|null $alternativeText
+     * @param string|null $group
+     * @return ManagerInterface
+     */
+    public function addExceptionMessage(\Exception $exception, $alternativeText = null, $group = null);
+
+    /**
+     * Creates identified message
+     *
+     * @param string $type
+     * @param string|null $identifier
+     * @return MessageInterface
+     * @throws \InvalidArgumentException
+     */
+    public function createMessage($type, $identifier = null);
+}
diff --git a/src/Magento/Framework/Message/MessageInterface.php b/src/Magento/Framework/Message/MessageInterface.php
new file mode 100644
index 0000000..969fa5c
--- /dev/null
+++ b/src/Magento/Framework/Message/MessageInterface.php
@@ -0,0 +1,118 @@
+<?php
+/**
+ * Copyright © Magento, Inc. All rights reserved.
+ * See COPYING.txt for license details.
+ */
+namespace Magento\Framework\Message;
+
+use Stringable;
+
+/**
+ * Represent a message with a type, content text, and an isSticky attribute to prevent message from being cleared.
+ *
+ * @api
+ * @since 100.0.2
+ */
+interface MessageInterface
+{
+    /**
+     * Default identifier
+     */
+    const DEFAULT_IDENTIFIER = 'default_message_identifier';
+
+    /**
+     * Error type
+     */
+    const TYPE_ERROR = 'error';
+
+    /**
+     * Warning type
+     */
+    const TYPE_WARNING = 'warning';
+
+    /**
+     * Notice type
+     */
+    const TYPE_NOTICE = 'notice';
+
+    /**
+     * Success type
+     */
+    const TYPE_SUCCESS = 'success';
+
+    /**
+     * Getter message type
+     *
+     * @return string
+     */
+    public function getType();
+
+    /**
+     * Getter for text of message
+     *
+     * @return string
+     */
+    public function getText();
+
+    /**
+     * Setter message text
+     *
+     * @param null|scalar|Stringable $text
+     * @return $this
+     */
+    public function setText($text);
+
+    /**
+     * Setter message identifier
+     *
+     * @param string $identifier
+     * @return $this
+     */
+    public function setIdentifier($identifier);
+
+    /**
+     * Getter message identifier
+     *
+     * @return string
+     */
+    public function getIdentifier();
+
+    /**
+     * Setter for flag. Whether message is sticky
+     *
+     * @param bool $isSticky
+     * @return $this
+     */
+    public function setIsSticky($isSticky);
+
+    /**
+     * Getter for flag. Whether message is sticky
+     *
+     * @return bool
+     * @SuppressWarnings("PHPMD.BooleanGetMethodName")
+     */
+    public function getIsSticky();
+
+    /**
+     * Retrieve message as a string
+     *
+     * @return string
+     */
+    public function toString();
+
+    /**
+     * Sets message data
+     *
+     * @param mixed[] $data
+     * @return $this
+     * @throws \InvalidArgumentException
+     */
+    public function setData(array $data = []);
+
+    /**
+     * Returns message data
+     *
+     * @return mixed[]
+     */
+    public function getData();
+}