Package Scope - Support @internal annotation to raise an issue if a method, etc. is used in a different namespace

[dgafka]

Hey,

Is the there possibility to add package scope like the java one to the static analysis?
I know, that PHP lack of this feature, but this is huge problem in my opinion.
What I was thinking of is usage of @internal docblock.
The description about @internal docblock goes like this:

"The @internal tag is used to denote that associated Structural Elements are elements internal to this application or library. It may also be used inside a long description to insert a piece of text that is only applicable for the developers of this software."  

Whenever the method is marked in docblock as @internal it should be used only within the namespace it exists in, otherwise phan should raise an error.

PHP code example:

namespace \Test\Some;
class PackageClass
{

    /**
     * Doing some publicly accessed action
     */
    public function publicAction()
    {
        echo "doing it public!";
    }

    /**
     * This is only to use within namespace
     * @internal
     */
    public function packageAction()
    {
        echo "doing it package!";
    }
}

namespace \Test\Some;
class SomeClass
{
    /**
     * @var PackageClass
     */
    private $packageClass;

    /**
     * PublicClass constructor.
     *
     * @param PackageClass $packageClass
     */
    public function __construct(PackageClass $packageClass)
    {
        $this->packageClass = $packageClass;
    }

    public function doSomeActionWhichTriggersPackageClasses()
    {
// Phan test will pass
        $this->packageClass->publicAction(); 
// Phan test will pass
        $this->packageClass->packageAction(); 
    }
}

namespace \Test\Some\Other;
class SomeHigherLevelModule
{
    /**
     * @var PackageClass
     */
    private $packageClass;

    /**
     * PublicClass constructor.
     *
     * @param PackageClass $packageClass
     */
    public function __construct(PackageClass $packageClass)
    {
        $this->packageClass = $packageClass;
    }

    public function doSomeActionWhichTriggersPackageClasses()
    {
 // Phan test will pass"
        $this->packageClass->publicAction();
 // Phan test will not pass and THROW EXCEPTION. Since "packageAction()" is marked as @internal and calling it from \Test\Some\Other namespace!";
        $this->packageClass->packageAction();
    }
}

[brzuchal]

👍

[frontowiec]

[KennetPL]

+1

[romanoji]

👍

In addition it'd be nice to have "package scope" with @internal annotation not only for methods, but also for classes.

[morria]

There's a pull request open for comments here: #656

[morria]

Does anyone here who uses any PHP IDEs have any comments on what kinds of expectations there are out in the wild about how @internal works?

• Does your IDE treat @internal as private only within the element's namespace?
• Does your IDE allow access to @internal elements from parent or child namespaces?

[morria]

This feature was merged onto master via a396c27