Home/ Questions/Q 582903
In Process

The Archive Base Latest Questions

Editorial Team
  • 0
Asked: 2026-05-13T14:44:10+00:00

In a PHP project, even when front controller logic is used for the main

  • 0

In a PHP project, even when front controller logic is used for the main application, there can be many stand-alone scripts, ajax snippets and so on.

Is there a standardized way – either PHPDoc or something else – to define in the first comment block of the script what GET and/or POST parameters the script will accept / require and of which type they are?

I usually help myself by just adding @params as if the file were a function, and a @return explanation for what the script does and returns, but maybe there is a more specialized way I do not know of.

Share

Leave an answer

You must login to add an answer.

Need An Account,

1 Answer

  1. Editorial Team

    phpDocumentor won’t like @param and @return tags in the file-level docblock…

    If you choose a separate file to document them in, as per Mr-sk‘s answer, you can use @link to point there, but it won’t be immediately visible in your file’s documentation page… it’ll just be a hyperlink that you’ll have to click to go see the info. If you want any of that file’s contents to be visible on the documentation page for your script file, you could use the inline {@example} tag to point to it, or even just certain lines in it, e.g. {@example /path/to/file 3 5} to show only lines three through five.

    In this scenario, I’d probably choose to just explain things in the long description of the file-level docblock, since there’s not actually a direct way of tagging your parameters to where phpDocumentor will recognize them as code elements anyway. If any of the parameters I used in my descriptions were indeed documented code elements that originate somewhere else in the code, I’d use the inline {@link} tag to point to that code element.

    For example, let’s say there are some constants defined in another code file, and those elements’ own documentation gets generated when that other file is parsed. If my long description that I write in the file-level docblock of a script-only file (like yours) talks about those constants as parameters, then my sentence might be:

    If $POST['foo'] is set, its value should always be either {@link BAR_CONST} or {@link BAZ_CONST}.

    References:

    • 0