BestIt\Sniffs\Commenting\RequiredDocBlockSniff

Complexity

Total Complexity

11

Size/Duplication

Total Lines	148
Duplicated Lines	0 %

Coupling/Cohesion

Components	1
Dependencies	5

Importance

Changes

0

<?php
 * @author blange <bjoern.lange@bestit-online.de>
 * @package BestIt\Sniffs\Commenting
 */
class RequiredDocBlockSniff extends AbstractSniff
{
    use DocPosProviderTrait;

    /**
     * There MUST be a doc block before a Class, Constant, Interface, Function, Trait, Variable.
     *
     * It will get suffixed like MissingDocBlockClass.
     */
    public const CODE_MISSING_DOC_BLOCK_PREFIX = 'MissingDocBlock';

    /**
     * The doc block before a Class, Constant, Interface, Function, Trait, Variable must be multi-line.
     *
     * It will be suffixed with the name of the structure like NoMultiLineDocBlockClass.
     */
    public const CODE_NO_MULTI_LINE_DOC_BLOCK_PREFIX = 'NoMultiLineDocBlock';

    /**
     * The message for missing doc blocks.
     */
    private const MESSAGE_MISSING_DOC_BLOCK = 'Please provide a doc block for your %s.';

    /**
     * The message for missing doc blocks in variable declarations.
     */
    private const MESSAGE_MISSING_DOC_BLOCK_VAR = 'Please provide a doc block for your %s or define a property type.';

    /**
     * The error message for the inline block.
     */
    private const MESSAGE_NO_MULTI_LINE_DOC_BLOCK_PREFIX = 'Please provide a multi line doc block for your %s.';

    /**
     * Maps the registered tokens to a readable key.
     *
     * @var array
     */
    private array $registeredTokens = [

This code did not parse for me. Apparently, there is an error somewhere around this line:

Syntax error, unexpected T_ARRAY, expecting T_FUNCTION or T_CONST

        T_CLASS => 'Class',
        T_CONST => 'Constant',
        T_INTERFACE => 'Interface',
        T_FUNCTION => 'Function',
        T_PRIVATE => 'MethodOrProperty',
        T_PROTECTED => 'MethodOrProperty',
        T_PUBLIC => 'MethodOrProperty',
        T_TRAIT => 'Trait',
        T_VARIABLE => 'Variable',
    ];

    /**
     * Ignore normal variables for this sniff.
     *
     * @return bool
     */
    protected function areRequirementsMet(): bool
    {
        return ($this->token['code'] !== T_VARIABLE) || (new PropertyHelper($this->file))->isProperty($this->stackPos);
    }

    /**
     * Checks for a missing doc block and throws an error if the doc is missing.
     *
     * @throws CodeWarning
     *
     * @return void
     */
    private function checkAndRegisterMissingDocBlock(): void
    {
        if (!$this->getDocCommentPos()) {
            $tokenIdent = $this->getTokenName();

            throw (new CodeError(
                static::CODE_MISSING_DOC_BLOCK_PREFIX . ucfirst($tokenIdent),
                self::MESSAGE_MISSING_DOC_BLOCK,
                $this->stackPos
            ))->setPayload([lcfirst($tokenIdent)]);
        }
    }

    /**
     * Checks and registers a multi line error.
     *
     * @throws CodeWarning
     *
     * @return void
     */
    private function checkAndRegisterNoMultiLine(): void
    {
        $docCommentPos = $this->getDocCommentPos();
        $openingToken = $this->tokens[$docCommentPos];
        $closingToken = $this->tokens[$openingToken['comment_closer']];

        if ($openingToken['line'] === $closingToken['line']) {
            $tokenIdent = $this->getTokenName();

            $exception = (new CodeError(
                static::CODE_NO_MULTI_LINE_DOC_BLOCK_PREFIX . ucfirst($tokenIdent),
                self::MESSAGE_NO_MULTI_LINE_DOC_BLOCK_PREFIX,
                $docCommentPos
            ))->setPayload([lcfirst($tokenIdent)]);

            throw $exception;
        }
    }

    /**
     * Returns the name for the token.
     *
     * @return string
     */
    private function getTokenName(): string
    {
        return $this->registeredTokens[$this->token['code']];
    }

    /**
     * Processes the token.
     *
     * @return void
     */
    protected function processToken(): void
    {
        try {
            $this->checkAndRegisterMissingDocBlock();
            $this->checkAndRegisterNoMultiLine();
        } catch (CodeWarning $error) {
            $this->getExceptionHandler()->handleException($error);
        }
    }

    /**
     * Register for all tokens which require a php doc block for us.
     *
     * @return array
     */
    public function register(): array
    {
        return array_keys($this->registeredTokens);
    }
}