feat: add inspection for missing ActivityMethod attribute, consolidate code and improve documentation

xepozz · xepozz · commit 196124aa088b · 2025-12-22T10:47:09.000+04:00
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -83,6 +83,7 @@ When implementing a feature that should work across multiple languages (e.g., Ac
 
 - **Kotlin First**: All new code should be written in Kotlin.
 - **Performance**: Use `CachedValue` and `DumbService.isDumb()` checks where appropriate. Use `lazyDumbAwareExtensions(project)` instead of `extensionList` when accessing Extension Points to ensure better performance and compatibility with dumb mode.
+- **PHP Utils**: For PHP support, use utility methods from `com.github.xepozz.temporal.languages.php.MixinKt` such as `isActivity()` and `isWorkflow()` on `PhpClass` and `Method` instead of manually checking attributes. Note that `Method.isActivity()` and `Method.isWorkflow()` are tolerant and return `true` for public methods even without explicit attributes if the containing class is an Activity or Workflow.
 - **Consistency**: Follow the existing package structure. For example, if a feature is implemented for PHP in `languages.php.navigation`, any future language implementations should follow the same sub-package structure (e.g., `languages.go.navigation`).
 - **Naming**:
     - Extension Points should **not** end with `EP`. They should represent the entity or feature (e.g., `ActivityCompletion`, `Workflow`).
diff --git a/src/main/kotlin/com/github/xepozz/temporal/languages/php/TemporalTypeProvider.kt b/src/main/kotlin/com/github/xepozz/temporal/languages/php/TemporalTypeProvider.kt
@@ -30,11 +30,9 @@ class TemporalTypeProvider : PhpTypeProvider4 {
                 element.resolveGlobal(true)
                     .mapNotNull { it as? Method }
                     .mapNotNull {
-                        val containingClass = it.containingClass ?: return@mapNotNull null
-
                         return@mapNotNull when {
-                            containingClass.hasAttribute(TemporalClasses.ACTIVITY) -> it
-                            containingClass.hasAttribute(TemporalClasses.WORKFLOW) -> it
+                            it.isActivity() -> it
+                            it.isWorkflow() -> it
                             else -> null
                         }
                     },
diff --git a/src/main/kotlin/com/github/xepozz/temporal/languages/php/endpoints/PhpActivity.kt b/src/main/kotlin/com/github/xepozz/temporal/languages/php/endpoints/PhpActivity.kt
@@ -3,6 +3,7 @@ package com.github.xepozz.temporal.languages.php.endpoints
 import com.github.xepozz.temporal.common.extensionPoints.Activity
 import com.github.xepozz.temporal.languages.php.index.PhpActivityClassIndex
 import com.github.xepozz.temporal.languages.php.index.PhpActivityMethodIndex
+import com.github.xepozz.temporal.languages.php.isActivity
 import com.intellij.openapi.project.Project
 import com.intellij.psi.SmartPointerManager
 import com.intellij.util.indexing.FileBasedIndex
@@ -22,7 +23,7 @@ class PhpActivity : Activity {
         }, project)
 
         classFqns.forEach { fqn ->
-            phpIndex.getClassesByFQN(fqn).forEach { phpClass ->
+            phpIndex.getClassesByFQN(fqn).filter { it.isActivity() }.forEach { phpClass ->
                 results.add(
                     ActivityModel(
                         id = phpClass.name,
@@ -46,7 +47,7 @@ class PhpActivity : Activity {
                 val classFqn = parts[0]
                 val methodName = parts[1]
                 phpIndex.getClassesByFQN(classFqn).forEach { phpClass ->
-                    phpClass.methods.find { it.name == methodName }?.let { method ->
+                    phpClass.methods.find { it.name == methodName && it.isActivity() }?.let { method ->
                         results.add(
                             ActivityModel(
                                 id = "$methodName (${phpClass.name})",
diff --git a/src/main/kotlin/com/github/xepozz/temporal/languages/php/endpoints/PhpWorkflow.kt b/src/main/kotlin/com/github/xepozz/temporal/languages/php/endpoints/PhpWorkflow.kt
@@ -3,6 +3,7 @@ package com.github.xepozz.temporal.languages.php.endpoints
 import com.github.xepozz.temporal.common.extensionPoints.Workflow
 import com.github.xepozz.temporal.languages.php.index.PhpWorkflowClassIndex
 import com.github.xepozz.temporal.languages.php.index.PhpWorkflowMethodIndex
+import com.github.xepozz.temporal.languages.php.isWorkflow
 import com.intellij.openapi.project.Project
 import com.intellij.psi.SmartPointerManager
 import com.intellij.util.indexing.FileBasedIndex
@@ -22,7 +23,7 @@ class PhpWorkflow : Workflow {
         }, project)
 
         classFqns.forEach { fqn ->
-            phpIndex.getClassesByFQN(fqn).forEach { phpClass ->
+            phpIndex.getClassesByFQN(fqn).filter { it.isWorkflow() }.forEach { phpClass ->
                 results.add(
                     WorkflowModel(
                         id = phpClass.name,
@@ -46,7 +47,7 @@ class PhpWorkflow : Workflow {
                 val classFqn = parts[0]
                 val methodName = parts[1]
                 phpIndex.getClassesByFQN(classFqn).forEach { phpClass ->
-                    phpClass.methods.find { it.name == methodName }?.let { method ->
+                    phpClass.methods.find { it.name == methodName && it.isWorkflow() }?.let { method ->
                         results.add(
                             WorkflowModel(
                                 id = "$methodName (${phpClass.name})",
diff --git a/src/main/kotlin/com/github/xepozz/temporal/languages/php/index/PhpActivityClassIndex.kt b/src/main/kotlin/com/github/xepozz/temporal/languages/php/index/PhpActivityClassIndex.kt
@@ -1,8 +1,7 @@
 package com.github.xepozz.temporal.languages.php.index
 
 import com.github.xepozz.temporal.common.index.AbstractIndex
-import com.github.xepozz.temporal.languages.php.TemporalClasses
-import com.github.xepozz.temporal.languages.php.hasAttribute
+import com.github.xepozz.temporal.languages.php.isActivity
 import com.intellij.psi.util.PsiTreeUtil
 import com.intellij.util.indexing.DataIndexer
 import com.intellij.util.indexing.FileBasedIndex
@@ -27,7 +26,7 @@ class PhpActivityClassIndex : AbstractIndex<String>() {
             val result = mutableMapOf<String, String>()
             val classes = PsiTreeUtil.findChildrenOfType(phpFile, PhpClass::class.java)
             for (phpClass in classes) {
-                if (phpClass.hasAttribute(TemporalClasses.ACTIVITY)) {
+                if (phpClass.isActivity()) {
                     val fqn = phpClass.fqn
                     result[fqn] = fqn
                 }
diff --git a/src/main/kotlin/com/github/xepozz/temporal/languages/php/index/PhpActivityMethodIndex.kt b/src/main/kotlin/com/github/xepozz/temporal/languages/php/index/PhpActivityMethodIndex.kt
@@ -1,8 +1,7 @@
 package com.github.xepozz.temporal.languages.php.index
 
 import com.github.xepozz.temporal.common.index.AbstractIndex
-import com.github.xepozz.temporal.languages.php.TemporalClasses
-import com.github.xepozz.temporal.languages.php.hasAttribute
+import com.github.xepozz.temporal.languages.php.isActivity
 import com.intellij.psi.util.PsiTreeUtil
 import com.intellij.util.indexing.DataIndexer
 import com.intellij.util.indexing.FileBasedIndex
@@ -28,9 +27,9 @@ class PhpActivityMethodIndex : AbstractIndex<String>() {
             val classes = PsiTreeUtil.findChildrenOfType(phpFile, PhpClass::class.java)
             for (phpClass in classes) {
                 val classFqn = phpClass.fqn
-                for (method in phpClass.methods) {
-                    if (method.hasAttribute(TemporalClasses.ACTIVITY_METHOD)) {
-                        result["$classFqn::${method.name}"] = TemporalClasses.ACTIVITY_METHOD
+                for (method in phpClass.ownMethods) {
+                    if (method.isActivity()) {
+                        result["$classFqn::${method.name}"] = ""
                     }
                 }
             }
diff --git a/src/main/kotlin/com/github/xepozz/temporal/languages/php/index/PhpWorkflowClassIndex.kt b/src/main/kotlin/com/github/xepozz/temporal/languages/php/index/PhpWorkflowClassIndex.kt
@@ -1,8 +1,7 @@
 package com.github.xepozz.temporal.languages.php.index
 
 import com.github.xepozz.temporal.common.index.AbstractIndex
-import com.github.xepozz.temporal.languages.php.TemporalClasses
-import com.github.xepozz.temporal.languages.php.hasAttribute
+import com.github.xepozz.temporal.languages.php.isWorkflow
 import com.intellij.psi.util.PsiTreeUtil
 import com.intellij.util.indexing.DataIndexer
 import com.intellij.util.indexing.FileBasedIndex
@@ -27,7 +26,7 @@ class PhpWorkflowClassIndex : AbstractIndex<String>() {
             val result = mutableMapOf<String, String>()
             val classes = PsiTreeUtil.findChildrenOfType(phpFile, PhpClass::class.java)
             for (phpClass in classes) {
-                if (phpClass.hasAttribute(TemporalClasses.WORKFLOW)) {
+                if (phpClass.isWorkflow()) {
                     val fqn = phpClass.fqn
                     result[fqn] = fqn
                 }
diff --git a/src/main/kotlin/com/github/xepozz/temporal/languages/php/index/PhpWorkflowMethodIndex.kt b/src/main/kotlin/com/github/xepozz/temporal/languages/php/index/PhpWorkflowMethodIndex.kt
@@ -1,8 +1,7 @@
 package com.github.xepozz.temporal.languages.php.index
 
 import com.github.xepozz.temporal.common.index.AbstractIndex
-import com.github.xepozz.temporal.languages.php.TemporalClasses
-import com.github.xepozz.temporal.languages.php.hasAttribute
+import com.github.xepozz.temporal.languages.php.isWorkflow
 import com.intellij.psi.util.PsiTreeUtil
 import com.intellij.util.indexing.DataIndexer
 import com.intellij.util.indexing.FileBasedIndex
@@ -17,14 +16,6 @@ import com.jetbrains.php.lang.psi.elements.PhpClass
 class PhpWorkflowMethodIndex : AbstractIndex<String>() {
     companion object {
         val NAME = ID.create<String, String>("temporal.workflow.methods")
-        val ATTRIBUTES = listOf(
-            TemporalClasses.WORKFLOW_METHOD,
-            TemporalClasses.WORKFLOW_INIT,
-            TemporalClasses.UPDATE_VALIDATOR_METHOD,
-            TemporalClasses.UPDATE_METHOD,
-            TemporalClasses.SIGNAL_METHOD,
-            TemporalClasses.QUERY_METHOD
-        )
     }
 
     override fun getName(): ID<String, String> = NAME
@@ -36,12 +27,9 @@ class PhpWorkflowMethodIndex : AbstractIndex<String>() {
             val classes = PsiTreeUtil.findChildrenOfType(phpFile, PhpClass::class.java)
             for (phpClass in classes) {
                 val classFqn = phpClass.fqn
-                for (method in phpClass.methods) {
-                    for (attribute in ATTRIBUTES) {
-                        if (method.hasAttribute(attribute)) {
-                            result["$classFqn::${method.name}"] = attribute
-                            break
-                        }
+                for (method in phpClass.ownMethods) {
+                    if (method.isWorkflow()) {
+                        result["$classFqn::${method.name}"] = ""
                     }
                 }
             }
diff --git a/src/main/kotlin/com/github/xepozz/temporal/languages/php/inspections/PhpActivityMethodInspection.kt b/src/main/kotlin/com/github/xepozz/temporal/languages/php/inspections/PhpActivityMethodInspection.kt
@@ -0,0 +1,50 @@
+package com.github.xepozz.temporal.languages.php.inspections
+
+import com.github.xepozz.temporal.TemporalBundle
+import com.github.xepozz.temporal.languages.php.TemporalClasses
+import com.github.xepozz.temporal.languages.php.hasAttribute
+import com.github.xepozz.temporal.languages.php.isActivity
+import com.intellij.codeInspection.LocalQuickFix
+import com.intellij.codeInspection.ProblemDescriptor
+import com.intellij.codeInspection.ProblemsHolder
+import com.intellij.openapi.project.Project
+import com.intellij.psi.PsiElementVisitor
+import com.intellij.psi.codeStyle.CodeStyleManager
+import com.jetbrains.php.lang.inspections.PhpInspection
+import com.jetbrains.php.lang.psi.PhpPsiElementFactory
+import com.jetbrains.php.lang.psi.elements.Method
+import com.jetbrains.php.lang.psi.visitors.PhpElementVisitor
+
+class PhpActivityMethodInspection : PhpInspection() {
+    override fun buildVisitor(holder: ProblemsHolder, isOnTheFly: Boolean): PsiElementVisitor {
+        return object : PhpElementVisitor() {
+            override fun visitPhpMethod(method: Method) {
+                if (!method.isActivity()) return
+                if (method.hasAttribute(TemporalClasses.ACTIVITY_METHOD)) return
+
+                holder.registerProblem(
+                    method.nameIdentifier ?: method,
+                    TemporalBundle.message("inspection.php.activity.method.attribute.missing.problem.description"),
+                    AddActivityMethodAttributeQuickFix()
+                )
+            }
+        }
+    }
+
+    private class AddActivityMethodAttributeQuickFix : LocalQuickFix {
+        override fun getFamilyName(): String {
+            return TemporalBundle.message("inspection.php.activity.method.attribute.missing.quick.fix")
+        }
+
+        override fun applyFix(project: Project, descriptor: ProblemDescriptor) {
+            val element = descriptor.psiElement
+            val method = (element as? Method ?: element.parent) as? Method ?: return
+
+            val newAttributesList = PhpPsiElementFactory.createAttributesList(project, TemporalClasses.ACTIVITY_METHOD)
+            val anchor = method.firstChild
+            method.addBefore(newAttributesList, anchor)
+
+            CodeStyleManager.getInstance(project).reformat(method)
+        }
+    }
+}
diff --git a/src/main/kotlin/com/github/xepozz/temporal/languages/php/mixin.kt b/src/main/kotlin/com/github/xepozz/temporal/languages/php/mixin.kt
@@ -3,6 +3,7 @@ package com.github.xepozz.temporal.languages.php
 import com.intellij.openapi.util.TextRange
 import com.intellij.psi.ElementManipulators
 import com.intellij.psi.PsiLanguageInjectionHost
+import com.jetbrains.php.lang.psi.elements.Method
 import com.jetbrains.php.lang.psi.elements.PhpAttributesOwner
 import com.jetbrains.php.lang.psi.elements.PhpClass
 
@@ -15,3 +16,24 @@ val PsiLanguageInjectionHost.contentRange: TextRange
 
 //fun PhpReference.getSignatures(): Collection<String> = signature.split('|')
 //fun PhpReference.hasSignature(signatureToFind: String): Boolean = getSignatures().any { it==signatureToFind }
+
+fun PhpClass.isActivity(): Boolean = hasAttribute(TemporalClasses.ACTIVITY)
+fun PhpClass.isWorkflow(): Boolean = hasAttribute(TemporalClasses.WORKFLOW)
+
+fun Method.isActivity(): Boolean = when {
+    isStatic -> false
+    modifier.isAbstract -> false
+    !modifier.isPublic -> false
+    name.startsWith("__") -> false
+    containingClass?.isActivity() != true -> false
+    else -> true
+}
+
+fun Method.isWorkflow(): Boolean = when {
+    isStatic -> false
+    modifier.isAbstract -> false
+    !modifier.isPublic -> false
+    name.startsWith("__") -> false
+    containingClass?.isWorkflow() != true -> false
+    else -> true
+}
diff --git a/src/main/resources/META-INF/language-php.xml b/src/main/resources/META-INF/language-php.xml
@@ -10,6 +10,16 @@
         <fileBasedIndex implementation="com.github.xepozz.temporal.languages.php.index.PhpWorkflowMethodIndex"/>
         <fileBasedIndex implementation="com.github.xepozz.temporal.languages.php.index.PhpActivityClassIndex"/>
         <fileBasedIndex implementation="com.github.xepozz.temporal.languages.php.index.PhpActivityMethodIndex"/>
+        <localInspection
+                language="PHP"
+                groupPath="Temporal"
+                groupName="PHP"
+                shortName="PhpActivityMethodInspection"
+                key="inspection.php.activity.method.attribute.missing.display.name"
+                bundle="messages.TemporalBundle"
+                enabledByDefault="true"
+                level="WARNING"
+                implementationClass="com.github.xepozz.temporal.languages.php.inspections.PhpActivityMethodInspection"/>
     </extensions>
 
     <extensions defaultExtensionNs="com.github.xepozz.temporal">
diff --git a/src/main/resources/inspectionDescriptions/PhpActivityMethodInspection.html b/src/main/resources/inspectionDescriptions/PhpActivityMethodInspection.html
@@ -0,0 +1,8 @@
+<html>
+<body>
+Reports methods in classes or interfaces marked with <code>#[ActivityInterface]</code> that do not have the <code>#[ActivityMethod]</code> attribute.
+<p>
+    In Temporal PHP SDK, while not strictly required for all methods, it is recommended to explicitly mark activity methods with the <code>#[ActivityMethod]</code> attribute to ensure clarity and allow for custom activity naming.
+</p>
+</body>
+</html>
diff --git a/src/main/resources/messages/TemporalBundle.properties b/src/main/resources/messages/TemporalBundle.properties
@@ -0,0 +1,3 @@
+inspection.php.activity.method.attribute.missing.display.name=Missing ActivityMethod attribute
+inspection.php.activity.method.attribute.missing.problem.description=Activity method should be marked with #[ActivityMethod] attribute.
+inspection.php.activity.method.attribute.missing.quick.fix=Add #[ActivityMethod] attribute
