What is the correct way to write PHPDocs for constants?

Question

I have this code:

/**
 * Days to parse
 * @var int
 */
const DAYS_TO_PARSE = 10;
...

I don't think that using @var is correct for a constant and I don't see any @constant PHPDoc tag. What is the correct way to do this?

As far as `define` is concerned: http://stackoverflow.com/questions/2192751/what-is-the-correct-way-to-document-php-constants-define-with-phpdocumentor — hakre, Jul 15 '11 at 11:08
I saw that one, define is for standalone constants, I am looking for a class constant — Elzo Valugi, Jul 15 '11 at 11:10
possible duplicate of [phpDoc class constants documentation](http://stackoverflow.com/questions/3892063/phpdoc-class-constants-documentation) — hakre, Jul 15 '11 at 11:10
this guy is using @access private http://www.icosaedro.it/phplint/phpdoc.html, but I am not aware of the fact that you can restrict visibility for constants — Elzo Valugi, Jul 15 '11 at 11:16
@Elzo Valugi: There are no private class constants in PHP and I doubt this hardly makes sense to have them. Anyway, that guy most certainly refers to *visibility by documentation* as it was common for public class functions as well in times when visibility was not available in PHP. It's a lint tool, that just is non-conservative to allow such. — hakre, Jul 15 '11 at 11:34
To add to Yogarine's answer, apparently just using a plain docblock works well with Doxygen. If you include the @var part, the resulting documentation won't include the description you keyed in. — David Tran, Jan 07 '20 at 03:19

score 164 · Answer 1 · edited Jul 13 '16 at 11:30

164

The PHP-FIG suggests using @var for constants.

7.22. @var

You may use the @var tag to document the "Type" of the following "Structural Elements":

Constants, both class and global scope

Properties

Variables, both global and local scope

Syntax

@var ["Type"] [element_name] [<description>]

edited Jul 13 '16 at 11:30

aalaap

4,145
5
52
59

answered Jan 05 '15 at 01:13

user2983026

1,639
1
10
3

1

So what is essentially is short for "variable" we use for documenting something that is "constant"? – ankr Jan 02 '17 at 12:34
2

as of 2017 using `@const` will correctly output my description but `@var` will not output anything for a class constant. – Keith Apr 20 '17 at 19:28
This is outdated. The current version of the PSR-5 draft no longer specifically mentions this. I maintain that constants don't need a specific type hint because their type is immutable and can always be deduced: https://stackoverflow.com/a/50945077/752110 – Yogarine Jul 27 '20 at 10:29
@Yogarine constants may not need a type-hint, but it may be desirable to document what the constant is used for – Brad Kent Jan 11 '21 at 03:46
@BradKent Of course. In that case it suffices to just add a docblock without any annotations. – Yogarine Feb 24 '21 at 11:41
This is insufficient if you want to define constants that Traits use from their placement and you can't define the constant on the Trait itself since then it has to be the same on the using class... – jave.web Nov 07 '22 at 08:38

score 129 · Answer 2 · edited Oct 28 '16 at 14:26

@const is not the right answer.

It's not part of the legacy phpDocumentor docs: http://manual.phpdoc.org/HTMLframesConverter/default/
It's not part of the current phpDocumentor docs: http://www.phpdoc.org/docs/latest/index.html
It's not listed in the list of tags on Wikipedia: http://en.wikipedia.org/wiki/PHPDoc#Tags
It's not listed in the PHP-FIG draft PSR: https://github.com/phpDocumentor/fig-standards/blob/master/proposed/phpdoc.md#7-tags

The only "official" place it's listed is phpdoc.de, but the spec there only ever made it to 1.0beta, and the site also includes tags like @brother and @sister, which I've never seen used before, so the overall trust in that site is somewhat diminished ;-) The de facto standard has always been phpDoc.org.

In short, even if some unofficial standard does mention it, if the documentation generators don't support it, then it's not worth using.

@var is correct for now, and once the PSR (last link in the above list) is out of draft, and is the basis for which phpDocumentor, Doxygen, APIGen and others are understanding PHPDoc, then @type would be correct which is the successor to @var.

Eventually, [`@type` was dropped in favor of `@var`](https://github.com/phpDocumentor/fig-standards/commit/61c695c43d1b2c713acbfb3302f284c518421bc5). — outis, Aug 20 '15 at 21:29
In fact it doesn't seem to matter at all for IDEs, PHPStorm for example always takes the actual code value to find out the type (as it must have a value assigned). — mark, Aug 22 '16 at 09:34

Yogarine · Answer 3 · 2020-07-15T15:32:20.153

There is no need to annotate the type of constants, since the type is always:

either a scalar or an array
known at declaration time
immutable

@const is also not part of the PHPDoc standard. PHP-FIG suggests @var but this is not backed by PHPDoc and doesn't add any information you can't already deduce from the declaration itself.

Therefore, for the sake of readability I recommend just using a plain PHPDoc docblock to document your constants:

class Foo
{
    /**
     * This is a constant.
     */
    const BAR = 'bar';
}

It will describe the constant when you generate PHPDocs yet keeps the comments clean and readable.

score 4 · Answer 4 · answered Jun 04 '14 at 16:13

4

I use Netbeans. It will parse phpDoc for global and class constants when this format is used:

/** @const Global constant description */
define('MY_CONST', 10);

class MyClass
{
    /** @const Class constant description */
    const MY_CONST = 10;
}

answered Jun 04 '14 at 16:13

Sonny

8,204
7
63
134

1

Can't you leave the `@const` out for the class constants in Netbeans? – hakre Aug 12 '14 at 18:15
4

I just tested in Netbeans 8, and was able to omit `@const` for the global and class constant declarations. – Sonny Aug 12 '14 at 18:26
1

In my case, i added "/** Class constant description */" and it worked. – fudu Jun 15 '21 at 07:43

score 3 · Answer 5 · answered Sep 07 '17 at 09:38

The following proposition respects the official documentation syntax:

class Foo
{
    const
        /**
         * @var string Should contain a description
         */
        MY_CONST1 = "1",
        /**
         * @var string Should contain a description
         */
        MY_CONST2 = "2";

}

score -22 · Accepted Answer · answered Jul 15 '11 at 11:04

-22

To get them into phpDoc, use:

@const THING

Usual construct:

@const[ant] label [description]

answered Jul 15 '11 at 11:04

Brian

8,418
2
25
32

isn't the a difference between class constants and global constants initiated by define()? I guess @const is for notating the latter. – Jan. Oct 30 '12 at 14:12
2

It's the former. I just documented a class constant and my generated phpdocs correctly contain the description. And as of April 2017 the English docs still don't have `@const`! – Keith Apr 20 '17 at 19:27
3

`@const` is not valid and does not exist in PHPDocumentor. Use `@var`. – Wade Mar 26 '19 at 01:20
It was valid at time of writing. Thanks. – Brian Mar 11 '22 at 09:48
Though Brian is correct that there seems to be [evidence](https://stackoverflow.com/a/3892174/904344) that at the time of writing, there was documentation on using a `@const[ant]` doc-style tag (PHP Doc 1.0 beta), I don't see why you wouldn't update an answer that is now incorrect after 11 years. – NobleUplift Nov 08 '22 at 16:49

What is the correct way to write PHPDocs for constants?

6 Answers6

Linked