TypeProcessor.php

Go to the documentation of this file.

<?php
namespace Magento\Framework\Reflection;

use Magento\Framework\Exception\SerializationException;
use Magento\Framework\Phrase;
use Zend\Code\Reflection\ClassReflection;
use Zend\Code\Reflection\DocBlock\Tag\ParamTag;
use Zend\Code\Reflection\DocBlock\Tag\ReturnTag;
use Zend\Code\Reflection\DocBlockReflection;
use Zend\Code\Reflection\MethodReflection;
use Zend\Code\Reflection\ParameterReflection;

class TypeProcessor
{
    const STRING_TYPE = 'str';
    const INT_TYPE = 'integer';
    const BOOLEAN_TYPE = 'bool';
    const ANY_TYPE = 'mixed';
    const NORMALIZED_STRING_TYPE = 'string';
    const NORMALIZED_INT_TYPE = 'int';
    const NORMALIZED_FLOAT_TYPE = 'float';
    const NORMALIZED_DOUBLE_TYPE = 'double';
    const NORMALIZED_BOOLEAN_TYPE = 'boolean';
    const NORMALIZED_ANY_TYPE = 'anyType';
    protected $_types = [];

    private $nameFinder;

    private function getNameFinder()
    {
        if ($this->nameFinder === null) {
            $this->nameFinder = \Magento\Framework\App\ObjectManager::getInstance()
                ->get(\Magento\Framework\Reflection\NameFinder::class);
        }
        return $this->nameFinder;
    }

    public function getTypesData()
    {
        return $this->_types;
    }

    public function setTypesData($typesData)
    {
        $this->_types = $typesData;
        return $this;
    }

    public function getTypeData($typeName)
    {
        if (!isset($this->_types[$typeName])) {
            throw new \InvalidArgumentException(
                sprintf('The "%s" data type isn\'t declared. Verify the type and try again.', $typeName)
            );
        }
        return $this->_types[$typeName];
    }

    public function setTypeData($typeName, $data)
    {
        if (!isset($this->_types[$typeName])) {
            $this->_types[$typeName] = $data;
        } else {
            $this->_types[$typeName] = array_merge_recursive($this->_types[$typeName], $data);
        }
    }

    public function register($type)
    {
        $typeName = $this->normalizeType($type);
        if (null === $typeName) {
            return null;
        }
        if (!$this->isTypeSimple($typeName) && !$this->isTypeAny($typeName)) {
            $typeSimple = $this->getArrayItemType($type);
            if (!(class_exists($typeSimple) || interface_exists($typeSimple))) {
                throw new \LogicException(
                    sprintf(
                        'The "%s" class doesn\'t exist and the namespace must be specified. Verify and try again.',
                        $type
                    )
                );
            }
            $complexTypeName = $this->translateTypeName($type);
            if (!isset($this->_types[$complexTypeName])) {
                $this->_processComplexType($type);
            }
            $typeName = $complexTypeName;
        }

        return $typeName;
    }

    protected function _processComplexType($class)
    {
        $typeName = $this->translateTypeName($class);
        $this->_types[$typeName] = [];
        if ($this->isArrayType($class)) {
            $this->register($this->getArrayItemType($class));
        } else {
            if (!(class_exists($class) || interface_exists($class))) {
                throw new \InvalidArgumentException(
                    sprintf('The "%s" class couldn\'t load as a parameter type.', $class)
                );
            }
            $reflection = new ClassReflection($class);
            $docBlock = $reflection->getDocBlock();
            $this->_types[$typeName]['documentation'] = $docBlock ? $this->getDescription($docBlock) : '';
            foreach ($reflection->getMethods(\ReflectionMethod::IS_PUBLIC) as $methodReflection) {
                if ($methodReflection->class === \Magento\Framework\Model\AbstractModel::class) {
                    continue;
                }
                $this->_processMethod($methodReflection, $typeName);
            }
        }

        return $this->_types[$typeName];
    }

    protected function _processMethod(MethodReflection $methodReflection, $typeName)
    {
        $isGetter = (strpos($methodReflection->getName(), 'get') === 0)
            || (strpos($methodReflection->getName(), 'is') === 0)
            || (strpos($methodReflection->getName(), 'has') === 0);
        if ($isGetter && !$methodReflection->getNumberOfRequiredParameters()) {
            $returnMetadata = $this->getGetterReturnType($methodReflection);
            $fieldName = $this->getNameFinder()->getFieldNameFromGetterName($methodReflection->getName());
            if ($returnMetadata['description']) {
                $description = $returnMetadata['description'];
            } else {
                $description = $this->getNameFinder()->getFieldDescriptionFromGetterDescription(
                    $methodReflection->getDocBlock()->getShortDescription()
                );
            }
            $this->_types[$typeName]['parameters'][$fieldName] = [
                'type' => $this->register($returnMetadata['type']),
                'required' => $returnMetadata['isRequired'],
                'documentation' => $description,
            ];
        }
    }

    public function getDescription(DocBlockReflection $doc)
    {
        $shortDescription = $doc->getShortDescription();
        $longDescription = $doc->getLongDescription();

        $description = rtrim($shortDescription);
        $longDescription = str_replace(["\n", "\r"], '', $longDescription);
        if (!empty($longDescription) && !empty($description)) {
            $description .= " ";
        }
        $description .= ltrim($longDescription);

        return $description;
    }

    public function dataObjectGetterNameToFieldName($getterName)
    {
        return $this->getNameFinder()->getFieldNameFromGetterName($getterName);
    }

    protected function dataObjectGetterDescriptionToFieldDescription($shortDescription)
    {
        return $this->getNameFinder()->getFieldDescriptionFromGetterDescription($shortDescription);
    }

    public function getGetterReturnType($methodReflection)
    {
        $returnAnnotation = $this->getMethodReturnAnnotation($methodReflection);
        $types = $returnAnnotation->getTypes();
        $returnType = current($types);
        $nullable = in_array('null', $types);

        return [
            'type' => $returnType,
            'isRequired' => !$nullable,
            'description' => $returnAnnotation->getDescription(),
            'parameterCount' => $methodReflection->getNumberOfRequiredParameters()
        ];
    }

    public function getExceptions($methodReflection)
    {
        $exceptions = [];
        $methodDocBlock = $methodReflection->getDocBlock();
        if ($methodDocBlock->hasTag('throws')) {
            $throwsTypes = $methodDocBlock->getTags('throws');
            if (is_array($throwsTypes)) {
                foreach ($throwsTypes as $throwsType) {
                    $exceptions = array_merge($exceptions, $throwsType->getTypes());
                }
            }
        }

        return $exceptions;
    }

    public function normalizeType($type)
    {
        if ($type == 'null') {
            return null;
        }
        $normalizationMap = [
            self::STRING_TYPE => self::NORMALIZED_STRING_TYPE,
            self::INT_TYPE => self::NORMALIZED_INT_TYPE,
            self::BOOLEAN_TYPE => self::NORMALIZED_BOOLEAN_TYPE,
            self::ANY_TYPE => self::NORMALIZED_ANY_TYPE,
        ];

        return is_string($type) && isset($normalizationMap[$type]) ? $normalizationMap[$type] : $type;
    }

    public function isTypeSimple($type)
    {
        return in_array(
            $this->getNormalizedType($type),
            [
                self::NORMALIZED_STRING_TYPE,
                self::NORMALIZED_INT_TYPE,
                self::NORMALIZED_FLOAT_TYPE,
                self::NORMALIZED_DOUBLE_TYPE,
                self::NORMALIZED_BOOLEAN_TYPE,
            ]
        );
    }

    public function isTypeAny($type)
    {
        return ($this->getNormalizedType($type) == self::NORMALIZED_ANY_TYPE);
    }

    public function isArrayType($type)
    {
        return (bool)preg_match('/(\[\]$|^ArrayOf)/', $type);
    }

    public function isValidTypeDeclaration($type)
    {
        return !($this->isTypeSimple($type) || $this->isTypeAny($type) || $this->isArrayType($type));
    }

    public function getArrayItemType($arrayType)
    {
        return $this->normalizeType(str_replace('[]', '', $arrayType));
    }

    public function translateTypeName($class)
    {
        if (preg_match('/\\\\?(.*)\\\\(.*)\\\\(Service|Api)\\\\\2?(.*)/', $class, $matches)) {
            $moduleNamespace = $matches[1] == 'Magento' ? '' : $matches[1];
            $moduleName = $matches[2];
            $typeNameParts = explode('\\', $matches[4]);

            return ucfirst($moduleNamespace . $moduleName . implode('', $typeNameParts));
        }
        throw new \InvalidArgumentException(
            sprintf('The "%s" parameter type is invalid. Verify the parameter and try again.', $class)
        );
    }

    public function translateArrayTypeName($type)
    {
        return 'ArrayOf' . ucfirst($this->getArrayItemType($type));
    }

    public function processSimpleAndAnyType($value, $type)
    {
        $isArrayType = $this->isArrayType($type);
        if ($isArrayType && is_array($value)) {
            $arrayItemType = $this->getArrayItemType($type);
            foreach (array_keys($value) as $key) {
                if ($value !== null && !settype($value[$key], $arrayItemType)) {
                    throw new SerializationException(
                        new Phrase(
                            'The "%value" value\'s type is invalid. The "%type" type was expected. '
                            . 'Verify and try again.',
                            ['value' => $value, 'type' => $type]
                        )
                    );
                }
            }
        } elseif ($isArrayType && $value === null) {
            return null;
        } elseif (!$isArrayType && !is_array($value)) {
            if ($value !== null && !$this->isTypeAny($type) && !$this->setType($value, $type)) {
                throw new SerializationException(
                    new Phrase(
                        'The "%value" value\'s type is invalid. The "%type" type was expected. Verify and try again.',
                        ['value' => (string)$value, 'type' => $type]
                    )
                );
            }
        } elseif (!$this->isTypeAny($type)) {
            throw new SerializationException(
                new Phrase(
                    'The "%value" value\'s type is invalid. The "%type" type was expected. Verify and try again.',
                    ['value' => gettype($value), 'type' => $type]
                )
            );
        }
        return $value;
    }

    public function getParamType(ParameterReflection $param)
    {
        $type = $param->detectType();
        if ($type == 'null') {
            throw new \LogicException(sprintf(
                '@param annotation is incorrect for the parameter "%s" in the method "%s:%s".'
                . ' First declared type should not be null. E.g. string|null',
                $param->getName(),
                $param->getDeclaringClass()->getName(),
                $param->getDeclaringFunction()->name
            ));
        }
        if ($type == 'array') {
            // try to determine class, if it's array of objects
            $paramDocBlock = $this->getParamDocBlockTag($param);
            $paramTypes = $paramDocBlock->getTypes();
            $paramType = array_shift($paramTypes);
            return strpos($paramType, '[]') !== false ? $paramType : "{$paramType}[]";
        }
        return $type;
    }

    public function getParamDescription(ParameterReflection $param)
    {
        $paramDocBlock = $this->getParamDocBlockTag($param);
        return $paramDocBlock->getDescription();
    }

    public function findGetterMethodName(ClassReflection $class, $camelCaseProperty)
    {
        return $this->getNameFinder()->getGetterMethodName($class, $camelCaseProperty);
    }

    protected function setType(&$value, $type)
    {
        // settype doesn't work for boolean string values.
        // ex: custom_attributes passed from SOAP client can have boolean values as string
        $booleanTypes = ['bool', 'boolean'];
        if (in_array($type, $booleanTypes)) {
            $value = filter_var($value, FILTER_VALIDATE_BOOLEAN);
            return true;
        }
        $numType = ['int', 'float'];
        if (in_array($type, $numType) && !is_numeric($value)) {
            return false;
        }
        return settype($value, $type);
    }

    public function findSetterMethodName(ClassReflection $class, $camelCaseProperty)
    {
        return $this->getNameFinder()->getSetterMethodName($class, $camelCaseProperty);
    }

    protected function findAccessorMethodName(
        ClassReflection $class,
        $camelCaseProperty,
        $accessorName,
        $boolAccessorName
    ) {
        return $this->getNameFinder()
            ->findAccessorMethodName($class, $camelCaseProperty, $accessorName, $boolAccessorName);
    }

    protected function classHasMethod(ClassReflection $class, $methodName)
    {
        return $this->getNameFinder()->hasMethod($class, $methodName);
    }

    public function processInterfaceCallInfo($interface, $serviceName, $methodName)
    {
        foreach ($interface as $direction => $interfaceData) {
            $direction = ($direction == 'in') ? 'requiredInput' : 'returned';
            if ($direction == 'returned' && !isset($interfaceData['parameters'])) {
                return $this;
            }
            foreach ($interfaceData['parameters'] as $parameterData) {
                if (!$this->isTypeSimple($parameterData['type']) && !$this->isTypeAny($parameterData['type'])) {
                    $operation = $this->getOperationName($serviceName, $methodName);
                    if ($parameterData['required']) {
                        $condition = ($direction == 'requiredInput') ? 'yes' : 'always';
                    } else {
                        $condition = ($direction == 'requiredInput') ? 'no' : 'conditionally';
                    }
                    $callInfo = [];
                    $callInfo[$direction][$condition]['calls'][] = $operation;
                    $this->setTypeData($parameterData['type'], ['callInfo' => $callInfo]);
                }
            }
        }
        return $this;
    }

    public function getOperationName($serviceName, $methodName)
    {
        return $serviceName . ucfirst($methodName);
    }

    private function getNormalizedType($type)
    {
        $type = $this->normalizeType($type);
        if ($this->isArrayType($type)) {
            $type = $this->getArrayItemType($type);
        }
        return $type;
    }

    private function getMethodReturnAnnotation(MethodReflection $methodReflection)
    {
        $methodName = $methodReflection->getName();
        $returnAnnotations = $this->getReturnFromDocBlock($methodReflection);
        if (empty($returnAnnotations)) {
            // method can inherit doc block from implemented interface, like for interceptors
            $implemented = $methodReflection->getDeclaringClass()->getInterfaces();
            foreach ($implemented as $parentClassReflection) {
                if ($parentClassReflection->hasMethod($methodName)) {
                    $returnAnnotations = $this->getReturnFromDocBlock(
                        $parentClassReflection->getMethod($methodName)
                    );
                    break;
                }
            }
            // throw an exception if even implemented interface doesn't have return annotations
            if (empty($returnAnnotations)) {
                throw new \InvalidArgumentException(
                    "Method's return type must be specified using @return annotation. "
                    . "See {$methodReflection->getDeclaringClass()->getName()}::{$methodName}()"
                );
            }
        }
        return $returnAnnotations;
    }

    private function getReturnFromDocBlock(MethodReflection $methodReflection)
    {
        $methodDocBlock = $methodReflection->getDocBlock();
        if (!$methodDocBlock) {
            throw new \InvalidArgumentException(
                "Each method must have a doc block. "
                . "See {$methodReflection->getDeclaringClass()->getName()}::{$methodReflection->getName()}()"
            );
        }
        return current($methodDocBlock->getTags('return'));
    }

    private function getParamDocBlockTag(ParameterReflection $param): ParamTag
    {
        $docBlock = $param->getDeclaringFunction()
            ->getDocBlock();
        $paramsTag = $docBlock->getTags('param');
        return $paramsTag[$param->getPosition()];
    }
}