Skip to content

fix: fully-qualify item types in Api/Data SearchResults docblocks - #50

Merged
rhoerr merged 1 commit into
mage-os:mainfrom
Hawksama:main
Jul 24, 2026
Merged

fix: fully-qualify item types in Api/Data SearchResults docblocks#50
rhoerr merged 1 commit into
mage-os:mainfrom
Hawksama:main

Conversation

@Hawksama

Copy link
Copy Markdown
Contributor

Summary

Every REST list endpoint the module ships (V1/rma, V1/rma/*/comments, V1/rma/*/attachments, V1/rma/*/items, V1/rma/reasons, V1/rma/statuses, V1/rma/resolution-types, V1/rma/item-conditions) currently fails with a 500:

{"message":"Class \"CommentInterface\" does not exist", ...
  #0 …/MethodsMap.php(166): ReflectionClass->__construct('CommentInterface')
  #3 …/DataObjectProcessor->buildOutputDataArray(MageOS\RMA\Model\Comment, 'CommentInterface')
  #4 …/ServiceOutputProcessor->convertValue(
        MageOS\RMA\Model\Data\CommentSearchResults,
        '\\MageOS\\RMA\\Api\\Data\\CommentSearchResultsInterface')
}

Each Api/Data/*SearchResultsInterface.php in the module declares its item type in PHPDoc using the short class name:

namespace MageOS\RMA\Api\Data;

use Magento\Framework\Api\SearchResultsInterface;

interface CommentSearchResultsInterface extends SearchResultsInterface
{
    /**
     * @return CommentInterface[]
     */
    public function getItems(): array;
}

\Magento\Framework\Reflection\TypeProcessor resolves PHPDoc short names against the interface's own use block only — it does not fall back to the file's own namespace — so the string CommentInterface reaches new ReflectionClass() unqualified and throws.

Reproduced against Magento 2.4.8-p5 (PHP 8.3.16) with mage-os/module-rma at dev-main (9a0ae70).

Change

Fully qualify item types in @return and @param on getItems() / setItems() across all 8 Api/Data/*SearchResultsInterface.php files:

-     * @return CommentInterface[]
+     * @return \MageOS\RMA\Api\Data\CommentInterface[]

This matches Magento core convention — e.g. Magento\Customer\Api\Data\CustomerSearchResultsInterface and Magento\Sales\Api\Data\OrderSearchResultInterface both FQ their item types in PHPDoc for the same reason.

Only the interface docblocks are touched; the concrete Model\Data\*SearchResults.php classes already have a matching use for the item interface, so they never hit this path.

Test plan

  • V1/rma/1/comments?searchCriteria[pageSize]=1 reproduces the 500 without the patch.
  • Same request returns a valid CommentSearchResultsInterface payload after the patch (Magento 2.4.8-p5, PHP 8.3.16).
  • CI green.

Updated all RMA `*SearchResultsInterface` service contracts to use fully qualified interface names in `getItems()` and `setItems()` docblocks. This removes namespace ambiguity and improves API documentation consistency and static analysis for typed item arrays.
@Hawksama
Hawksama requested review from a team and SamueleMartini as code owners July 23, 2026 19:20

@rhoerr rhoerr left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thank you

@rhoerr
rhoerr merged commit 333c62c into mage-os:main Jul 24, 2026
1 check failed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants