appserver-io / doppelgaenger

src/Entities/Assertions/AssertionFactory.php

<?php

/**
 * \AppserverIo\Doppelgaenger\Entities\Assertions\AssertionFactory
 *
 * NOTICE OF LICENSE
 *
 * This source file is subject to the Open Software License (OSL 3.0)
 * that is available through the world-wide-web at this URL:
 * http://opensource.org/licenses/osl-3.0.php
 *
 * PHP version 5
 *
 * @author    Bernhard Wick <bw@appserver.io>
 * @copyright 2015 TechDivision GmbH - <info@appserver.io>
 * @license   http://opensource.org/licenses/osl-3.0.php Open Software License (OSL 3.0)
 * @link      https://github.com/appserver-io/doppelgaenger
 * @link      http://www.appserver.io/
 */

namespace AppserverIo\Doppelgaenger\Entities\Assertions;

use AppserverIo\Doppelgaenger\Dictionaries\ReservedKeywords;
use AppserverIo\Doppelgaenger\Entities\Lists\AssertionList;
use AppserverIo\Doppelgaenger\Interfaces\StructureDefinitionInterface;
use AppserverIo\Psr\MetaobjectProtocol\Dbc\Assertions\AssertionInterface;
use AppserverIo\Psr\MetaobjectProtocol\Dbc\Annotations\Ensures;
use AppserverIo\Psr\MetaobjectProtocol\Dbc\Annotations\Invariant;
use AppserverIo\Psr\MetaobjectProtocol\Dbc\Annotations\Requires;

/**
 * This class will help instantiating the right assertion class for any given assertion array
 *
 * @author    Bernhard Wick <bw@appserver.io>
 * @copyright 2015 TechDivision GmbH - <info@appserver.io>
 * @license   http://opensource.org/licenses/osl-3.0.php Open Software License (OSL 3.0)
 * @link      https://github.com/appserver-io/doppelgaenger
 * @link      http://www.appserver.io/
 */
class AssertionFactory
{

    /**
     * All simple data types which are known but are aliased without an is_... function.
     *
     * @var string[] $scalarTypeMappings
     */
    protected $scalarTypeMappings = array(
        'boolean' => 'bool',
        'void' => 'null'
    );

    /**
     * All simple data types which are supported by PHP
     * and have a is_... function.
     *
     * @var string[] $validScalarTypes
     */
    protected $validScalarTypes = array(
        'array',
        'bool',
        'callable',
        'double',
        'float',
        'int',
        'integer',
        'long',
        'null',
        'numeric',
        'object',
        'real',
        'resource',
        'scalar',
        'string',
        'boolean',
        'void'
    );

    /**
     * The definition of the structure we are currently iterating through
     *
     * @var StructureDefinitionInterface $currentDefinition
     */
    protected $currentDefinition;

    /**
     * Parse assertions which are a collection of others
     *
     * @param string    $connective How are they combined? E.g. "||"
     * @param \stdClass $annotation The annotation to create chained assertions from
     *
     * @return \AppserverIo\Doppelgaenger\Entities\Assertions\ChainedAssertion
     */
    protected function createChainedAssertion($connective, \stdClass $annotation)
    {
        // Get all the parts of the string
        $assertionArray = explode(' ', $annotation->values['typeHint']);

        // Check all string parts for the | character
        $combinedPart = '';
        $combinedIndex = 0;
        foreach ($assertionArray as $key => $assertionPart) {
            // Check which part contains the | but does not only consist of it
            if ($this->filterOrCombinator($assertionPart) && trim($assertionPart) !== $connective) {
                $combinedPart = trim($assertionPart);
                $combinedIndex = $key;
                break;
            }
        }


        // Now we have to create all the separate assertions for each part of the $combinedPart string
        $assertionList = new AssertionList();
        foreach (explode($connective, $combinedPart) as $partString) {
            // Rebuild the assertion string with one partial string of the combined part
            $tmp = $assertionArray;
            $tmp[$combinedIndex] = $partString;
            $annotation->values['typeHint'] = $partString;
            $assertion = $this->getInstance($annotation);

            if (is_bool($assertion)) {
                continue;

Blank line found at end of control structure

            } else {
                $assertionList->add($assertion);
            }
        }

        // We got everything. Create a ChainedAssertion instance
        return new ChainedAssertion($assertionList, '||');
    }

    /**
     * Will parse assertions from a DocBlock comment piece. If $usedAnnotation is given we will concentrate on that
     * type of assertion only.
     * We might return false on error
     *
     * @param \stdClass $annotation The annotation to create simple assertions from
     *
     * @return boolean|\AppserverIo\Psr\MetaobjectProtocol\Dbc\Assertions\AssertionInterface
     *
     * @throws \AppserverIo\Doppelgaenger\Exceptions\ParserException
     */
    protected function createSimpleAssertion(\stdClass $annotation)
    {
        // Do we have an or connective aka "|"?
        if ($this->filterOrCombinator($annotation->values['typeHint'])) {
            // If we got invalid arguments then we will fail
            try {
                return $this->createChainedAssertion('|', $annotation);

Blank line found at end of control structure

            } catch (\InvalidArgumentException $e) {
                return false;
            }
        }

        // check what we have got
        $variable = $annotation->values['operand'];
        $type = $this->filterScalarType($annotation->values['typeHint']);
        $class = $this->filterType($annotation->values['typeHint']);
        $collectionType = $this->filterTypedCollection($annotation->values['typeHint']);

        // "mixed" is something we cannot work with, special case is a mixed typed collection which basically is an array
        if ($type === 'mixed' || $class === 'mixed') {
            return false;

Blank line found at end of control structure

        } elseif ($collectionType === 'mixed') {
            // we have a collection with mixed content, so basically an array
            $type = 'array';
            $collectionType = false;
        }

        if ($annotation->name === 'return') {
            $variable = ReservedKeywords::RESULT;
        }

        // Now we have to check what we got
        // First of all handle if we got a simple type
        if ($type !== false && !empty($type)) {
            return new TypeAssertion($variable, $type);

Blank line found at end of control structure

        } elseif ($class !== false && !empty($class)) {
            // seems we have an instance assertion here

            return new InstanceAssertion($variable, $class);

Blank line found at end of control structure

        } elseif ($collectionType !== false && !empty($collectionType)) {
            // seems we have a typed collection here

            return new TypedCollectionAssertion($variable, $collectionType);
        } else {
            return false;
        }
    }

    /**
     * Will filter for any referenced structure as a indicated type hinting of complex types
     *
     * @param string $string The string potentially containing a structure name
     *
     * @return boolean
     */
    protected function filterType($string)
    {
        // if the string is neither a scalar type, a typed collection and contains a namespace separator we assume a class

        // check if we know the simple type
        $validScalarTypes = array_flip($this->validScalarTypes);
        if (isset($validScalarTypes[strtolower($string)])) {
            return false;
        }

        // check if it might be a typed collection
        foreach (array('<', '>', '[', ']') as $needle) {
            if (strpos($string, $needle) !== false) {
                return false;
            }
        }

        // check if we have a namespace separator
        if (strpos($string, '\\') !== false) {
            return $string;
        }

        // check if we start with upper case and do only contain valid characters
        if (ctype_upper($string[0]) && preg_match('/^[a-zA-Z_\x7f-\xff][a-zA-Z0-9_\x7f-\xff]*$/', $string)) {
            return $string;
        }

        // We found nothing; tell them.
        return false;
    }

    /**
     * Will filter any combinator defining a logical or-relation
     *
     * @param string $docString The DocBlock piece to search in
     *
     * @return boolean
     */
    protected function filterOrCombinator($docString)
    {
        if (strpos($docString, '|')) {
            return true;
        }

        // We found nothing; tell them.
        return false;
    }

    /**
     * Will filter for any simple type that may be used to indicate type hinting
     *
     * @param string $string The string potentially containing a scalar type hint
     *
     * @return boolean|string
     */
    protected function filterScalarType($string)
    {
        // check if we know the simple type
        $validScalarTypes = array_flip($this->validScalarTypes);
        if (!isset($validScalarTypes[$string])) {
            return false;
        }

        // if we have a mapping we have to return the mapped value instead
        if (isset($this->scalarTypeMappings[$string])) {
            $string = $this->scalarTypeMappings[$string];
        }

        // is it a scalar type we can check for?
        if (function_exists('is_' . $string)) {
            return $string;
        }

        // We found nothing; tell them.
        return false;
    }

    /**
     * Will filter for type safe collections of the form array<Type> or Type[]
     *
     * @param string $string The string potentially containing a type hint for a typed collection
     *
     * @return boolean|string
     */
    protected function filterTypedCollection($string)
    {
        $tmp = strpos($string, 'array<');
        if ($tmp !== false) {
            // we have a Java Generics like syntax

            if (strpos($string, '>') > $tmp) {
                $stringPiece = explode('array<', $string);
                $stringPiece = $stringPiece[1];

                return strstr($stringPiece, '>', true);
            }

Blank line found at end of control structure

        } elseif (strpos($string, '[]')) {
            // we have a common <TYPE>[] syntax

            return strstr($string, '[]', true);
        }

        // We found nothing; tell them.
        return false;
    }

    /**
     * Will return an instance of an assertion fitting the passed annotation object
     *
     * @param \stdClass $annotation Annotation object to generate assertion from
     *
     * @return \AppserverIo\Psr\MetaobjectProtocol\Dbc\Assertions\AssertionInterface
     * @throws \Exception
     */
    public function getInstance(\stdClass $annotation)
    {
        switch ($annotation->name) {
            case Ensures::ANNOTATION:
            case Invariant::ANNOTATION:
            case Requires::ANNOTATION:
                // complex annotations leave us with two possibilities: raw or custom assertions
                if (isset($annotation->values['type'], $annotation->values['constraint'])) {
                    // we need a custom assertion here
                    return $this->createAssertion($annotation->values['type'], $annotation->values['constraint']);
                }
                // RawAssertion is sufficient
                return new RawAssertion(array_pop($annotation->values));
                break;

break is not strictly necessary here and could be removed.

            case 'param':
            case 'return':
                // simple assertions leave with a wide range of type assertions
                return $this->createSimpleAssertion($annotation);

The expression $this->createSimpleAssertion($annotation); of type AppserverIo\Doppelgaenger\Entities\Assertions\ChainedAssertion|false|AppserverIo\Doppelgaenger\Entities\Assertions\TypeAssertion|AppserverIo\Doppelgaenger\Entities\Assertions\InstanceAssertion|AppserverIo\Doppelgaenger\Entities\Assertions\TypedCollectionAssertion adds false to the return on line 335 which is incompatible with the return type documented by AppserverIo\Doppelgaenger\Entities\Assertions\AssertionFactory::getInstance of type AppserverIo\Psr\MetaobjectProtocol\Dbc\Assertions\AssertionInterface|null. It seems like you forgot to handle an error condition.

                break;

break is not strictly necessary here and could be removed.

            default:
                break;
        }
    }

    /**
     * Tries to create assertion of $assertionType
     *
     * @param string $assertionType the assertion type
     * @param string $constraint    the constraint to validate
     *
     * @return null|AssertionInterface
     * @throws \Exception
     */
    protected function createAssertion($assertionType, $constraint)
    {
        $assertionClassPath = $this->getAssertionClassPath($assertionType);
        if (null === $assertionClassPath) {
            throw new \Exception(
                sprintf(
                    'Cannot create complex assertion of type %s',
                    $assertionType
                )
            );
        }

        $potentialAssertion = new $assertionClassPath($constraint);
        if (!$potentialAssertion instanceof AssertionInterface) {
            throw new \Exception(
                sprintf(
                    'Specified assertion of type %s does not implement %s',
                    $potentialAssertion,
                    AssertionInterface::class
                )
            );
        }

        return $potentialAssertion;
    }

    /**
     * Resolves and returns the fully qualified namespace of $assertionType
     * or null if $assertionType cannot be resolved to an accessible class
     *
     * @param string $assertionType the assertion type
     *
     * @return null|string
     */
    protected function getAssertionClassPath($assertionType)
    {
        if (class_exists($assertionType)) {
            return $assertionType;
        }

        $potentialAssertion = $this->resolveUsedAssertionStructure($assertionType);
        if (class_exists($potentialAssertion)) {
            return $potentialAssertion;
        }

        $potentialAssertion = '\AppserverIo\Doppelgaenger\Entities\Assertions\\' . $assertionType;
        if (class_exists($potentialAssertion)) {
            return $potentialAssertion;
        }

        $potentialAssertion .= 'Assertion';
        if (class_exists($potentialAssertion)) {
            return $potentialAssertion;
        }

        return null;
    }

    /**
     * Iterates through the 'use' operators of the current structure and
     * returns the fully qualified namespace to the Assertion or null if none is found
     *
     * @param string $assertionType the assertion type
     *
     * @return null|string
     */
    protected function resolveUsedAssertionStructure($assertionType)
    {
        if (!$this->getCurrentDefinition()) {
            return null;
        }

        foreach ($this->getCurrentDefinition()->getUsedStructures() as $structure) {
            if (preg_match('/\w+$/', $structure, $matches) && $matches[0] === $assertionType) {
                return $structure;
            }
        }

        return null;
    }

    /**
     * Getter for all valid scalar types we can create assertions for
     *
     * @return string[]
     */
    public function getValidScalarTypes()
    {
        return $this->validScalarTypes;
    }

    /**
     * Sets the instance of the current definition
     *
     * @param StructureDefinitionInterface $currentDefinition the definition of the current structure
     *
     * @return void
     */
    public function setCurrentDefinition(StructureDefinitionInterface $currentDefinition)
    {
        $this->currentDefinition = $currentDefinition;
    }

    /**
     * Returns the instance of the current definition
     *
     * @return null|StructureDefinitionInterface
     */
    public function getCurrentDefinition()
    {
        return $this->currentDefinition;
    }
}