Merge pull request vimeo#10866 from kkmuffme/document-psalm-internal-…

…namespace-class
kkmuffme · Mar 28, 2024 · eaeb979 · eaeb979
2 parents 4b01704 + c8f0671
commit eaeb979
Show file tree

Hide file tree

Showing 2 changed files with 158 additions and 5 deletions.
diff --git a/docs/annotating_code/supported_annotations.md b/docs/annotating_code/supported_annotations.md
@@ -252,9 +252,10 @@ $b = $a->bar(); // this call fails
 
 ### `@psalm-internal`
 
-Used to mark a class, property or function as internal to a given namespace. Psalm treats this slightly differently to
-the PHPDoc `@internal` tag. For `@internal`, an issue is raised if the calling code is in a namespace completely
-unrelated to the namespace of the calling code, i.e. not sharing the first element of the namespace.
+Used to mark a class, property or function as internal to a given namespace or class or even method. 
+Psalm treats this slightly differently to the PHPDoc `@internal` tag. For `@internal`,
+an issue is raised if the calling code is in a namespace completely unrelated to the namespace of the calling code,
+i.e. not sharing the first element of the namespace.
 
 In contrast for `@psalm-internal`, the docblock line must specify a namespace. An issue is raised if the calling code
 is not within the given namespace.
@@ -272,15 +273,44 @@ namespace A\B {
 namespace A\B\C {
     class Bat {
         public function batBat(): void {
-            $a = new \A\B\Foo();  // this is fine
+            $a = new \A\B\Foo(); // this is fine
+        }
+    }
+}
+
+namespace A {
+    class B {
+        public function batBat(): void {
+            $a = new \A\B\Foo(); // this is fine
         }
     }
 }
 
 namespace A\C {
     class Bat {
         public function batBat(): void {
-            $a = new \A\B\Foo();  // error
+            $a = new \A\B\Foo(); // error
+        }
+    }
+}
+
+namespace X {
+    class Foo {        
+        /**
+         * @psalm-internal Y\Bat::batBat
+         */
+        public static function barBar(): void {
+        }
+    }
+}
+
+namespace Y {
+    class Bat {
+        public function batBat() : void {
+            \X\Foo::barBar(); // this is fine
+        }
+        public function fooFoo(): void {
+            \X\Foo::barBar(); // error
         }
     }
 }

diff --git a/tests/InternalAnnotationTest.php b/tests/InternalAnnotationTest.php
@@ -606,6 +606,66 @@ public function baz(): void
                     }
                 ',
             ],
+            'psalmInternalClassWithCallClass' => [
+                'code' => '<?php
+                    namespace A {
+                        /**
+                         * @psalm-internal B\Bat
+                         */
+                        class Foo {
+                            public static function barBar(): void {
+                            }
+                        }
+                    }
+
+                    namespace B {
+                        class Bat {
+                            public function batBat() : void {
+                                \A\Foo::barBar();
+                            }
+                        }
+                    }',
+            ],
+            'psalmInternalMethodWithCallClass' => [
+                'code' => '<?php
+                    namespace A {
+                        class Foo {
+                            /**
+                             * @psalm-internal B\Bat
+                             */
+                            public static function barBar(): void {
+                            }
+                        }
+                    }
+
+                    namespace B {
+                        class Bat {
+                            public function batBat() : void {
+                                \A\Foo::barBar();
+                            }
+                        }
+                    }',
+            ],
+            'psalmInternalMethodWithMethod' => [
+                'code' => '<?php
+                    namespace X {
+                        class Foo {
+                            /**
+                             * @psalm-internal Y\Bat::batBat
+                             */
+                            public static function barBar(): void {
+                            }
+                        }
+                    }
+
+                    namespace Y {
+                        class Bat {
+                            public function batBat() : void {
+                                \X\Foo::barBar();
+                            }
+                        }
+                    }',
+            ],
             'callToInternalMethodFromAnonymousClass' => [
                 'code' => <<<'PHP'
                 <?php
@@ -1118,6 +1178,69 @@ public function __construct() {}
                 ',
                 'error_message' => 'InternalMethod',
             ],
+            'psalmInternalClassWithCallClass' => [
+                'code' => '<?php
+                    namespace A {
+                        /**
+                         * @psalm-internal B\Bar
+                         */
+                        class Foo {
+                            public static function barBar(): void {
+                            }
+                        }
+                    }
+
+                    namespace B {
+                        class Bat {
+                            public function batBat() : void {
+                                \A\Foo::barBar();
+                            }
+                        }
+                    }',
+                'error_message' => 'InternalClass',
+            ],
+            'psalmInternalMethodWithCallClass' => [
+                'code' => '<?php
+                    namespace A {
+                        class Foo {
+                            /**
+                             * @psalm-internal B\Bar
+                             */
+                            public static function barBar(): void {
+                            }
+                        }
+                    }
+
+                    namespace B {
+                        class Bat {
+                            public function batBat() : void {
+                                \A\Foo::barBar();
+                            }
+                        }
+                    }',
+                'error_message' => 'InternalMethod',
+            ],
+            'psalmInternalMethodWithMethod' => [
+                'code' => '<?php
+                    namespace X {
+                        class Foo {
+                            /**
+                             * @psalm-internal Y\Bat::batBat
+                             */
+                            public static function barBar(): void {
+                            }
+                        }
+                    }
+
+                    namespace Y {
+                        class Bat {
+                            public function fooFoo(): void {
+                                \X\Foo::barBar();
+                            }
+                        }
+                    }',
+                'error_message' => 'InternalMethod',
+            ],
         ];
     }
 }