What does @internal actually mean and how to use it?

Question

What does the @internal tag mean when used in PHPDocs and how does it work? I have read the documentation for this tag and have gotten this definition.

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.

I get the gist of it but what I don't understand is how would I actually use it in a project? I've read the example and my understanding is that a function marked as @internal means that it's meant to be used as part of the software and not to be used by something external. For example, in a PHP library, if a function is marked as @internal it's not part of the public API that the library provides.

My questions:

• Is my understanding of @internal correct? If not, what's the correct usage?
• If my understanding is correct, why does PhpStorm strike out my @internal functions implying they aren't meant to be used? How would I properly use a function marked as @internal?

Answer 1

This is PhpStorm bug. It should not strike @internal methods used inside of library/package.

So yes, your understand of meaning of @internal tag is correct - it is for mark public/protected methods as not a part of public API. You should ignore these warnings for usage inside of library.

Technically there is nothing that will stop you from using such methods even for 3rd party libraries, but you should be aware of consequences - there is no backward compatibility promise for them, so they can be changed, renamed or completely disappear without any warning.

Answer 2

I believe it is the comment for programmer about some specific usages. I mark my recommendations in which cases to use this function or alternative one (e.g. 'use this func in CLI mode only' or 'use this function only if you need row data. Pls consider wrapper in all other cases')

https://docs.phpdoc.org/latest/guide/references/phpdoc/tags/internal.html

@internal 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.

Answer 3

Might be trivial for some but it's a good thing to note that declaring a function private if possible is probably better than using @internal.

Not saying there are no valid uses for this tag but it's always a good choice to review your design if feel like you need to use it.