com.jetbrains.php.lang.documentation.phpdoc.psi.tags.PhpDocTag Java Examples

public static boolean hasReference(@Nullable PhpDocComment docComment, String... className) {
    if(docComment == null) return false;

    Map<String, String> uses = AnnotationBackportUtil.getUseImportMap(docComment);

    for(PhpDocTag phpDocTag: PsiTreeUtil.findChildrenOfAnyType(docComment, PhpDocTag.class)) {
        if(!AnnotationBackportUtil.NON_ANNOTATION_TAGS.contains(phpDocTag.getName())) {
            PhpClass annotationReference = AnnotationBackportUtil.getAnnotationReference(phpDocTag, uses);
            if(annotationReference != null && PhpElementsUtil.isEqualClassName(annotationReference, className)) {
                return true;
            }
        }

    }

    return false;
}
 

@NotNull
@Override
public PsiElementVisitor buildVisitor(final @NotNull ProblemsHolder holder, boolean isOnTheFly) {
    if(!DoctrineUtil.isDoctrineOrmInVendor(holder.getProject())) {
        return super.buildVisitor(holder, isOnTheFly);
    }

    return new MyAnnotationPropertyPsiElementVisitor("Doctrine\\ORM\\Mapping\\Entity") {
        @Override
        protected void visitAnnotationProperty(@NotNull PhpDocTag phpDocTag) {
            StringLiteralExpression repositoryClass = AnnotationUtil.getPropertyValueAsPsiElement(phpDocTag, "repositoryClass");
            if (repositoryClass == null) {
                return;
            }

            if(!DoctrineUtil.repositoryClassExists(phpDocTag)) {
                holder.registerProblem(
                    repositoryClass,
                    MESSAGE,
                    new DoctrineOrmRepositoryIntention()
                );
            }
        }
    };
}
 

private void visitPhpDocTag(@NotNull PhpDocTag phpDocTag) {

        // "@var" and user non related tags dont need an action
        if(AnnotationBackportUtil.NON_ANNOTATION_TAGS.contains(phpDocTag.getName())) {
            return;
        }

        Map<String, String> fileImports = AnnotationBackportUtil.getUseImportMap(phpDocTag);
        if(fileImports.size() == 0) {
            return;
        }

        String annotationFqnName = AnnotationBackportUtil.getClassNameReference(phpDocTag, fileImports);
        for (String annotation : annotations) {
            if(annotation.equals(annotationFqnName)) {
                this.phpDocTagProcessor.process(phpDocTag);
            }
        }
    }
 

public void testNavigationForPropertyInsideAnnotationAttributes() {
    assertNavigationMatch(PhpFileType.INSTANCE, "<?php\n" +
            "namespace Bar;\n" +
            "\n" +
            "use Foo\\Bar;\n" +
            "\n" +
            "class Foo\n" +
            "{\n" +
            "  /** @Bar(fo<caret>o=\"test\") */" +
            "}\n",
        PlatformPatterns.psiElement(Field.class).withName("foo")
    );

    assertNavigationMatch(PhpFileType.INSTANCE, "<?php\n" +
            "namespace Bar;\n" +
            "\n" +
            "use Foo\\Bar;\n" +
            "\n" +
            "class Foo\n" +
            "{\n" +
            "  /** @Bar(access<caret>Control=\"test\") */" +
            "}\n",
        PlatformPatterns.psiElement(PhpDocTag.class)
    );
}
 

@Nullable
public static PhpClass getAnnotationReference(@Nullable PhpDocTag phpDocTag) {
    if(phpDocTag == null) return null;

    // check annoation in current namespace
    String tagName = phpDocTag.getName();
    if(tagName.startsWith("@")) {
        tagName = tagName.substring(1);
    }

    PhpNamespace phpNamespace = PsiTreeUtil.getParentOfType(phpDocTag, PhpNamespace.class);
    if(phpNamespace != null) {
        String currentNsClass = phpNamespace.getFQN() + "\\" + tagName;
        PhpClass phpClass = PhpElementsUtil.getClass(phpDocTag.getProject(), currentNsClass);
        if(phpClass != null) {
            return phpClass;
        }
    }

    return getAnnotationReference(phpDocTag, getUseImportMap((PsiElement) phpDocTag));

}
 

/**
 * Get templates on "@Template()" and on method attached to given PhpDocTag
 */
@NotNull
public static Map<String, Collection<PsiElement>> getTemplateAnnotationFilesWithSiblingMethod(@NotNull PhpDocTag phpDocTag) {
    Map<String, Collection<PsiElement>> targets = new HashMap<>();

    // template on direct PhpDocTag
    Pair<String, Collection<PsiElement>> templateAnnotationFiles = TwigUtil.getTemplateAnnotationFiles(phpDocTag);
    if(templateAnnotationFiles != null) {
        targets.put(templateAnnotationFiles.getFirst(), templateAnnotationFiles.getSecond());
    }

    // templates on "Method" of PhpDocTag
    PhpDocComment phpDocComment = PsiTreeUtil.getParentOfType(phpDocTag, PhpDocComment.class);
    if(phpDocComment != null) {
        PsiElement method = phpDocComment.getNextPsiSibling();
        if(method instanceof Method) {
            for (String name : TwigUtil.getControllerMethodShortcut((Method) method)) {
                targets.put(name, new HashSet<>(getTemplatePsiElements(method.getProject(), name)));
            }
        }
    }

    return targets;
}
 

@Override
protected void addCompletions(@NotNull CompletionParameters parameters, ProcessingContext context, @NotNull CompletionResultSet result) {
    PsiElement psiElement = parameters.getOriginalPosition();
    if(psiElement == null) {
        return;
    }

    PhpDocTag phpDocTag = PsiTreeUtil.getParentOfType(parameters.getOriginalPosition(), PhpDocTag.class);
    PhpClass phpClass = AnnotationUtil.getAnnotationReference(phpDocTag);
    if(phpClass == null) {
        return;
    }

    AnnotationPropertyParameter annotationPropertyParameter = new AnnotationPropertyParameter(parameters.getOriginalPosition(), phpClass, AnnotationPropertyParameter.Type.DEFAULT);
    providerWalker(parameters, context, result, annotationPropertyParameter);

}
 

/**
 * Get the property value as string by given name
 *
 * "@Template(template="foobar.html.twig")"
 */
@Nullable
public static StringLiteralExpression getPropertyValueAsPsiElement(@NotNull PhpDocTag phpDocTag, @NotNull String property) {
    PhpPsiElement attributeList = phpDocTag.getFirstPsiChild();
    if(attributeList == null || attributeList.getNode().getElementType() != PhpDocElementTypes.phpDocAttributeList) {
        return null;
    }

    PsiElement lParen = attributeList.getFirstChild();
    if(lParen == null) {
        return null;
    }

    PsiElement psiProperty = Arrays.stream(attributeList.getChildren())
        .filter(psiElement1 -> getPropertyIdentifierValue(property).accepts(psiElement1))
        .findFirst()
        .orElse(null);

    return psiProperty instanceof StringLiteralExpression ?
        (StringLiteralExpression) psiProperty :
        null;
}
 

/**
 * Extract text: @Entity(repositoryClass="foo")
 */
@Nullable
public static String getAnnotationRepositoryClass(@NotNull PhpDocTag phpDocTag, @NotNull PhpClass phpClass) {
    PsiElement phpDocAttributeList = PsiElementUtils.getChildrenOfType(phpDocTag, PlatformPatterns.psiElement(PhpDocElementTypes.phpDocAttributeList));
    if(phpDocAttributeList == null) {
        return null;
    }

    // @TODO: use annotation plugin
    // repositoryClass="Foobar"
    String text = phpDocAttributeList.getText();

    String repositoryClass = EntityHelper.resolveDoctrineLikePropertyClass(
        phpClass,
        text,
        "repositoryClass",
        aVoid -> AnnotationUtil.getUseImportMap(phpDocTag)
    );

    if (repositoryClass == null) {
        return null;
    }

    return StringUtils.stripStart(repositoryClass, "\\");
}
 

@Nullable
public static String getClassDeprecatedMessage(@NotNull PhpClass phpClass) {
    if (phpClass.isDeprecated()) {
        PhpDocComment docComment = phpClass.getDocComment();
        if (docComment != null) {
            for (PhpDocTag deprecatedTag : docComment.getTagElementsByName("@deprecated")) {
                String tagValue = deprecatedTag.getTagValue();
                if (StringUtils.isNotBlank(tagValue)) {
                    return StringUtils.abbreviate("Deprecated: " + tagValue, 100);
                }
            }
        }
    }

    return null;
}
 

/**
 * FooController::fooAction
 */
@Nullable
private String getController(@NotNull PhpDocTag phpDocTag) {
    Method method = AnnotationBackportUtil.getMethodScope(phpDocTag);
    if(method == null) {
        return null;
    }

    PhpClass containingClass = method.getContainingClass();
    if(containingClass == null) {
        return null;
    }

    return String.format("%s::%s",
        StringUtils.stripStart(containingClass.getFQN(), "\\"),
        method.getName()
    );
}
 

@Nullable
public static PhpClass getAnnotationReference(PhpDocTag phpDocTag, final Map<String, String> useImports) {

    String tagName = phpDocTag.getName();
    if(tagName.startsWith("@")) {
        tagName = tagName.substring(1);
    }

    String className = tagName;
    String subNamespaceName = "";
    if(className.contains("\\")) {
        className = className.substring(0, className.indexOf("\\"));
        subNamespaceName = tagName.substring(className.length());
    }

    if(!useImports.containsKey(className)) {
        return null;
    }

    return PhpElementsUtil.getClass(phpDocTag.getProject(), useImports.get(className) + subNamespaceName);

}
 

/**
 * Get the property value as PsiElement by given name
 *
 * "@Template(template=Foobar::class)"
 */
@Nullable
public static PsiElement getPropertyValueAsElement(@NotNull PhpDocTag phpDocTag, @NotNull String property) {
    PhpPsiElement attributeList = phpDocTag.getFirstPsiChild();
    if(attributeList == null || attributeList.getNode().getElementType() != PhpDocElementTypes.phpDocAttributeList) {
        return null;
    }

    PsiElement lParen = attributeList.getFirstChild();
    if(lParen == null) {
        return null;
    }

    return Arrays.stream(attributeList.getChildren())
        .filter(psiElement1 -> getPropertyIdentifierValueAsPsiElement(property).accepts(psiElement1))
        .findFirst()
        .orElse(null);
}
 

@Nullable
public static PhpDocCommentAnnotation getPhpDocCommentAnnotationContainer(@Nullable PhpDocComment phpDocComment) {
    if(phpDocComment == null) {
        return null;
    }

    Map<String, String> uses = AnnotationUtil.getUseImportMap((PsiElement) phpDocComment);

    Map<String, PhpDocTagAnnotation> annotationRefsMap = new HashMap<>();
    for(PhpDocTag phpDocTag: PsiTreeUtil.findChildrenOfType(phpDocComment, PhpDocTag.class)) {
        if(!AnnotationUtil.isBlockedAnnotationTag(phpDocTag.getName())) {
            PhpClass annotationClass = AnnotationUtil.getAnnotationReference(phpDocTag, uses);
            if(annotationClass != null) {
                annotationRefsMap.put(annotationClass.getPresentableFQN(), new PhpDocTagAnnotation(annotationClass, phpDocTag));
            }
        }

    }

    return new PhpDocCommentAnnotation(annotationRefsMap, phpDocComment);
}
 

@Nullable
public static PhpDocTagAnnotation getPhpDocAnnotationContainer(@NotNull PhpDocTag phpDocTag) {

    PhpClass annotationReference = getAnnotationReference(phpDocTag);
    if(annotationReference == null) {
        return null;
    }

    return new PhpDocTagAnnotation(annotationReference, phpDocTag);
}
 

@Override
public void visitElement(PsiElement element) {
    if ((element instanceof PhpDocTag)) {
        visitPhpDocTag((PhpDocTag) element);
    }

    super.visitElement(element);
}
 

private void visitPhpDocTag(@NotNull PhpDocTag phpDocTag) {
    // "@var" and user non related tags dont need an action
    if(AnnotationUtil.isBlockedAnnotationTag(phpDocTag.getName())) {
        return;
    }

    String annotationFqnName = StringUtils.stripStart(getClassNameReference(phpDocTag, AnnotationUtil.getUseImportMap((PsiElement) phpDocTag)), "\\");

    if(annotationFqnName != null && StringUtils.isNotBlank(annotationFqnName)) {
        this.processor.process(Pair.create(annotationFqnName, phpDocTag));
    }
}
 

@NotNull
@Override
public PsiElementVisitor buildVisitor(final @NotNull ProblemsHolder holder, boolean isOnTheFly) {
    return new PsiElementVisitor() {
        @Override
        public void visitElement(PsiElement element) {
            if (element instanceof PhpDocTag && AnnotationUtil.isAnnotationPhpDocTag((PhpDocTag) element)) {
                visitAnnotationDocTag((PhpDocTag) element, holder);
            }

            super.visitElement(element);
        }
    };
}
 

private void visitAnnotationDocTag(PhpDocTag phpDocTag, @NotNull ProblemsHolder holder) {
    PhpClass phpClass = AnnotationUtil.getAnnotationReference(phpDocTag);
    if (phpClass == null || !phpClass.isDeprecated()) {
        return;
    }

    PsiElement firstChild = phpDocTag.getFirstChild();
    if (firstChild == null || firstChild.getNode().getElementType() != PhpDocElementTypes.DOC_TAG_NAME) {
        return;
    }

    holder.registerProblem(firstChild, MESSAGE, ProblemHighlightType.LIKE_DEPRECATED);
}
 

private void visitAnnotationDocTag(@NotNull PhpDocTag phpDocTag, @NotNull ProblemsHolder holder, @NotNull AnnotationInspectionUtil.LazyNamespaceImportResolver lazyUseImporterCollector) {
    // Target for our inspection is DocTag name: @Foobar() => Foobar
    // This prevent highlighting the complete DocTag
    PsiElement firstChild = phpDocTag.getFirstChild();
    if (firstChild == null || firstChild.getNode().getElementType() != PhpDocElementTypes.DOC_TAG_NAME) {
        return;
    }

    String name = phpDocTag.getName();
    String tagName = StringUtils.stripStart(name, "@");

    // ignore "@test", but allow "@\test" to go through
    if (!tagName.startsWith("\\") && !Character.isUpperCase(tagName.codePointAt(0))) {
        return;
    }

    String clazz = AnnotationInspectionUtil.getClassFqnString(tagName, lazyUseImporterCollector);
    if (clazz == null) {
        return;
    }

    PhpClass classInterface = PhpElementsUtil.getClassInterface(phpDocTag.getProject(), clazz);
    if (classInterface == null) {
        holder.registerProblem(
            firstChild,
            MESSAGE,
            ProblemHighlightType.GENERIC_ERROR_OR_WARNING
        );
    }
}
 

private void visitAnnotationDocTag(@NotNull PhpDocTag phpDocTag, @NotNull ProblemsHolder holder, @NotNull AnnotationInspectionUtil.LazyNamespaceImportResolver lazyUseImporterCollector) {
    for (PsiElement element : PsiTreeUtil.collectElements(phpDocTag, psiElement -> psiElement.getNode().getElementType() == PhpDocTokenTypes.DOC_STATIC)) {
        PsiElement nextSibling = element.getNextSibling();
        if (nextSibling == null || nextSibling.getNode().getElementType() != PhpDocTokenTypes.DOC_IDENTIFIER || !"class".equals(nextSibling.getText())) {
            continue;
        }

        PsiElement prevSibling = element.getPrevSibling();
        if (prevSibling == null) {
            return;
        }

        String namespaceForDocIdentifier = PhpDocUtil.getNamespaceForDocIdentifier(prevSibling);
        if (namespaceForDocIdentifier == null) {
            return;
        }

        String clazz = AnnotationInspectionUtil.getClassFqnString(namespaceForDocIdentifier, lazyUseImporterCollector);
        if (clazz == null) {
            return;
        }

        PhpClass classInterface = PhpElementsUtil.getClassInterface(phpDocTag.getProject(), clazz);
        if (classInterface == null) {
            holder.registerProblem(
                nextSibling,
                MESSAGE,
                ProblemHighlightType.GENERIC_ERROR_OR_WARNING
            );
        }
    }
}
 

public static boolean isAnnotationClass(@NotNull PhpClass phpClass) {
    PhpDocComment phpDocComment = phpClass.getDocComment();
    if(phpDocComment != null) {
        PhpDocTag[] annotationDocTags = phpDocComment.getTagElementsByName("@Annotation");
        return annotationDocTags.length > 0;
    }

    return false;
}
 

@Nullable
private PhpClass getValidAnnotationClass(PsiElement psiElement) {
    PhpDocTag phpDocTag = PsiTreeUtil.getParentOfType(psiElement, PhpDocTag.class);
    if(phpDocTag == null) {
        return null;
    }

    return AnnotationUtil.getAnnotationReference(phpDocTag);
}
 

public void testThatAlreadyFqnNameMustNotSuggestAnyImport() {
    myFixture.copyFileToProject("doctrine.php");

    PhpDocTag phpDocTag = PhpPsiElementFactory.createFromText(getProject(), PhpDocTag.class, "<?php\n" +
        "/**\n" +
        "* @\\ORM\\Entity()\n" +
        "*/\n" +
        "class Foo {}\n"
    );

    Map<String, String> possibleImportClasses = AnnotationUtil.getPossibleImportClasses(phpDocTag);
    assertEquals(0, possibleImportClasses.size());
}
 

@Override
public boolean matches(@NotNull LanguageMatcherParameter parameter) {

    List<JsonSignature> filter = ContainerUtil.filter(parameter.getSignatures(), jsonSignature -> "annotation".equals(jsonSignature.getType()) && StringUtils.isNotBlank(jsonSignature.getClassName()));

    if(filter.size() == 0) {
        return false;
    }

    PsiElement parent = parameter.getElement().getParent();
    if(!(parent instanceof StringLiteralExpression)) {
        return false;
    }

    boolean accepts = AnnotationPattern.getDefaultPropertyValueString().accepts(parent);
    if(!accepts) {
        return false;
    }

    PhpDocTag phpDocTag = PsiTreeUtil.getParentOfType(parent, PhpDocTag.class);
    PhpClass phpClass = AnnotationUtil.getAnnotationReference(phpDocTag);
    if(phpClass == null) {
        return false;
    }

    for (JsonSignature signature : filter) {
        if(StringUtils.stripStart(phpClass.getFQN(), "\\").equals(StringUtils.stripStart(signature.getClassName(), "\\"))) {
            return true;
        }
    }

    return false;
}
 

@Nullable
private static String getClassNameReference(@NotNull PhpDocTag phpDocTag, @NotNull Map<String, String> useImports) {

    if(useImports.size() == 0) {
        return null;
    }

    String annotationName = phpDocTag.getName();
    if(StringUtils.isBlank(annotationName)) {
        return null;
    }

    if(annotationName.startsWith("@")) {
        annotationName = annotationName.substring(1);
    }

    String className = annotationName;
    String subNamespaceName = "";
    if(className.contains("\\")) {
        className = className.substring(0, className.indexOf("\\"));
        subNamespaceName = annotationName.substring(className.length());
    }

    if(!useImports.containsKey(className)) {
        return null;
    }

    // normalize name
    String annotationFqnName = useImports.get(className) + subNamespaceName;
    if(!annotationFqnName.startsWith("\\")) {
        annotationFqnName = "\\" + annotationFqnName;
    }

    return annotationFqnName;
}
 

public void testThatImportForClassIsSuggestedForImportedClass() {
    myFixture.copyFileToProject("doctrine.php");

    PhpDocTag phpDocTag = PhpPsiElementFactory.createFromText(getProject(), PhpDocTag.class, "<?php\n" +
        "/**\n" +
        "* @Entity()\n" +
        "*/\n" +
        "class Foo {}\n"
    );

    Map<String, String> possibleImportClasses = AnnotationUtil.getPossibleImportClasses(phpDocTag);
    assertNull(possibleImportClasses.get("\\Doctrine\\ORM\\Mapping"));
}
 

@Nullable
public static String getClassNameReference(PhpDocTag phpDocTag, Map<String, String> useImports) {

    if(useImports.size() == 0) {
        return null;
    }

    String annotationName = phpDocTag.getName();
    if(StringUtils.isBlank(annotationName)) {
        return null;
    }

    if(annotationName.startsWith("@")) {
        annotationName = annotationName.substring(1);
    }

    String className = annotationName;
    String subNamespaceName = "";
    if(className.contains("\\")) {
        className = className.substring(0, className.indexOf("\\"));
        subNamespaceName = annotationName.substring(className.length());
    }

    if(!useImports.containsKey(className)) {
        return null;
    }

    // normalize name
    String annotationFqnName = useImports.get(className) + subNamespaceName;
    if(!annotationFqnName.startsWith("\\")) {
        annotationFqnName = "\\" + annotationFqnName;
    }

    return annotationFqnName;
}
 

/**
 * @see TemplateAnnotationAnnotator#annotate
 */
public void testThatTemplateCreationAnnotationProvidesQuickfix() {
    PsiFile psiFile = myFixture.configureByText("foobar.php", "<?php\n" +
        "use Sensio\\Bundle\\FrameworkExtraBundle\\Configuration\\Template;\n" +
        "\n" +
        "class Foobar\n" +
        "{\n" +
        "   /**\n" +
        "   * @Temp<caret>late(\"foobar.html.twig\")\n" +
        "   */\n" +
        "   public function fooAction()\n" +
        "   {\n" +
        "   }\n" +
        "}\n" +
        ""
    );

    PsiElement psiElement = myFixture.getFile().findElementAt(myFixture.getCaretOffset());
    PsiElement phpDocTag = psiElement.getParent();

    AnnotationHolderImpl annotations = new AnnotationHolderImpl(new AnnotationSession(psiFile));

    new TemplateAnnotationAnnotator().annotate(new PhpAnnotationDocTagAnnotatorParameter(
        PhpIndex.getInstance(getProject()).getAnyByFQN(TwigUtil.TEMPLATE_ANNOTATION_CLASS).iterator().next(),
        (PhpDocTag) phpDocTag,
        annotations
    ));

    assertNotNull(
        annotations.stream().findFirst().filter(annotation -> annotation.getMessage().contains("Create Template"))
    );
}
 

public void testGetTemplateAnnotationFiles() {
    PhpDocTag phpPsiFromText = PhpPsiElementFactory.createPhpPsiFromText(getProject(), PhpDocTag.class, "/** @Template(\"foo.html.twig\") */");
    assertEquals("foo.html.twig", TwigUtil.getTemplateAnnotationFiles(phpPsiFromText).getFirst());

    phpPsiFromText = PhpPsiElementFactory.createPhpPsiFromText(getProject(), PhpDocTag.class, "/** @Template(template=\"foo.html.twig\") */");
    assertEquals("foo.html.twig", TwigUtil.getTemplateAnnotationFiles(phpPsiFromText).getFirst());

    phpPsiFromText = PhpPsiElementFactory.createPhpPsiFromText(getProject(), PhpDocTag.class, "/** @Template(template=\"foo\\foo.html.twig\") */");
    assertEquals("foo/foo.html.twig", TwigUtil.getTemplateAnnotationFiles(phpPsiFromText).getFirst());
}