1

In Magento2.1, I see almost all API use the fully qualified namespaces in the function param and PHPDoc, instead of using importing and aliases, like PageRepositoryInterface and BlockRepositoryInterface in the vendor\magento\module-cms\Api directory.

I forgot where I saw it, but I remember someone said Magento2 API must use fully qualified namespaces, is that true? If it is true, what is the reason?

For Example

<?php
namespace Magento\Cms\Api;

interface PageRepositoryInterface
{
    /**
     * Save page.
     *
     * @param \Magento\Cms\Api\Data\PageInterface $page
     * @return \Magento\Cms\Api\Data\PageInterface
     * @throws \Magento\Framework\Exception\LocalizedException
     */
    public function save(\Magento\Cms\Api\Data\PageInterface $page);
}

Can it rewrite to below?

<?php
namespace Magento\Cms\Api;

use Magento\Cms\Api\Data\PageInterface;

interface PageRepositoryInterface
{
    /**
     * Save page.
     *
     * @param PageInterface $page
     * @return PageInterface
     * @throws \Magento\Framework\Exception\LocalizedException
     */
    public function save(PageInterface $page);
}
1

Magento 2 is trying to switch to use importing and aliases, but you may understand there is no out-of-the-box tool to convert the whole Magento 2 code like that...

And it's not true that Magento 2 must use fully qualified namespaces.

For more information: https://github.com/magento/magento2/issues/872

Cheers.

  • Thanks for your answer and link. I remember someone said the api can not use simplified namespace in the PHPDoc, otherwise the web api will produce some error, because PHPDoc doesn't recognize it. Is it OK to use simplified namespace in the PHPDoc? You could see the example I given in the question. – Key Shang Nov 14 '17 at 6:42
  • Hi, I find a official DevDocs about the fully qualified namespaces in PHPDoc, you could have a look. Not sure it is right. Another answer about the doc block – Key Shang Nov 14 '17 at 7:03
3

After a research, finally find the source in my memory, it is in official develop guide Configure services as web APIs.

For SOAP and REST to work correctly, the following rules must be followed by the service interface’s doc block:

Note that even if the class \Magento\Customer\Api\Data\CustomerInterface is in the same namespace (or a sub-namespace) of the current class or a use statement has exists at the top of the class, the fully qualified namespace must be used or the web API throws an exception.

We seems could use simplified namespace in the function param as the answer of @Toan, but we must use fully qualified namespace in service interface’s doc block as the official develop guide said, but it doesn't say the reason, so any more explanation answer is welcome.

  • 2
    The reason is in code generation and smart resolving for input- and return-values for the API. For example, a GET to /V1/products returns a JSON object. The webapi.xml maps this to Magento\Catalog\Api\ProductRepositoryInterface::getList, and it's API makes sure it will return a \Magento\Catalog\Api\Data\ProductSearchResultsInterface. The Magento_Webapi has some complexity (too much to explain here), but basically it converts the data model according to getters in it's interface to a JSON response. If you create proper Service Contracts your API endpoints work out of the box! – Giel Berkers Nov 14 '17 at 7:48

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Not the answer you're looking for? Browse other questions tagged or ask your own question.