92

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?

7

6 Answers 6

167

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>]

6
  • 1
    So what is essentially is short for "variable" we use for documenting something that is "constant"?
    – ankr
    Jan 2, 2017 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, 2017 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: stackoverflow.com/a/50945077/752110
    – Yogarine
    Jul 27, 2020 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, 2021 at 3:46
  • @BradKent Of course. In that case it suffices to just add a docblock without any annotations.
    – Yogarine
    Feb 24, 2021 at 11:41
130

@const is not the right answer.

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.

2
  • 6
    Eventually, @type was dropped in favor of @var.
    – outis
    Aug 20, 2015 at 21:29
  • 1
    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, 2016 at 9:34
7

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.

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;
}
3
  • 1
    Can't you leave the @const out for the class constants in Netbeans?
    – hakre
    Aug 12, 2014 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, 2014 at 18:26
  • 1
    In my case, i added "/** Class constant description */" and it worked.
    – fudu
    Jun 15, 2021 at 7:43
3

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";

}
-22

To get them into phpDoc, use:

@const THING

Usual construct:

@const[ant] label [description]
5
  • 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, 2012 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, 2017 at 19:27
  • 3
    @const is not valid and does not exist in PHPDocumentor. Use @var.
    – Wade
    Mar 26, 2019 at 1:20
  • It was valid at time of writing. Thanks.
    – Brian
    Mar 11, 2022 at 9:48
  • Though Brian is correct that there seems to be evidence 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. Nov 8, 2022 at 16:49

Your Answer

Reminder: Answers generated by Artificial Intelligence tools are not allowed on Stack Overflow. Learn more

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge that you have read and understand our privacy policy and code of conduct.

Not the answer you're looking for? Browse other questions tagged or ask your own question.