This issue was moved to a discussion.
You can continue the conversation there. Go to discussion →
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Support for enumerated options fro properties and method arguments #557
Comments
IMHO, it's a better practice to define (class) constants, and then explicitly clarify in the description that acceptable values are one of said constants. But disregarding that bit... Consider scenarios with multiple arguments, where you have multiple @param tags, followed by one @options. What does @options apply to? The first argument, or the last one specified by @param? I think it would make much more sense to somehow embed enumerations within the type specification. The pair "[]" is already in use for array specifiers, so either "{}" or "()" should be used, e.g.
or
Even assuming you accept this variation, I would bet that this wouldn't be trivial to implement (although I don't know for sure, @mvriel would have to be the one to say that), especially considering that constants and other scalar values should also be valid enumarations... So it would probably be pushed for 2.1. |
I was thinking about this issue and perhaps we should expand the scope and think about that. If you take a step back you'd consider that we have a definition of a boundary; something describing the limits of the given data type. My initial idea would be that we can approach this from two angles:
With boundaries I do not just mean a limited enumeration but also a value range (i.e. [0..3]), array structure or other type of information that limits the possible amount or structure of values contained in the @var or @param. Downsides:
In either case we might need a good way of presenting boundaries and existing standards may help out with that |
p.s. if I were to implement this myself I'd consider it for 2.1+; if this item is contributed then I'd be happy to include it in 2.0 |
In all the cases where I'd be using this (at the moment), the option set would be a series of pre-defined class constants, and I do currently identify the set of options in the description. It was merely a question raised on SO this morning that made me think of an actual tag that would allow them to be defined, and where it would then be easier to link each option to the actual const definition in the docs, or to clarify the description in a structured manner. Logically, (thinking of my suggested @options tag) if there were multiple @params each with their own @options, I'd anticipate alternate @param and @options tags so each @options referred explicitly to the previous @param Equally, @param string{"open", "closed", "pending"} $plotType would work... it provides a precise structural definition. There's also a couple of instances I can think of where a valid value would be a float within a range of -1.0 to 1.0... I hadn't considered using a bounds definition for that, but it is a logical extension from an enumerated set of options. |
There are already array specifiers, right? So there's no need to worry about that bit. It's only a matter of specifiers for scalar types (which should extend to those that are part of array specifiers). The "{}" notation would work fine, even for numerical representations, e.g.
Would define $multiplier as expecting (basically) any integer other than 0. Although this here illustrates a new possible extension - a way to explicitly blacklist values rather then whitelist them... perhaps with "!"? Like
would be interpreted as "any integer other then 0 and 100", while
would be interpreted as "any non-negative integer". Damn, this sounds so cool, yet hard... |
There is a discussion going on in PHP-FIG where some of these aspects are touched; might be interesting for this issue |
and associative array? |
There's a whole other issue (#650) about that, although I guess this here is related as well. |
I have not yet forgotten about this issue but am swamped in other stuff to work on |
+1000 👍 |
I can fully understand being swamped |
Did enum ever make it in? |
Hi @J7mbo, they are not included in phpDocumentor2 yet. The discussion on the exact notation and feature set is still on-going |
Hello. It's been a year or so since the last comment. Are there any plans for incorporating something like this? |
+1 |
why not combine it with the syntax for union types? You can already use
This is how TypeScript does it too (I think JavaScript and PHP are very similar in their dynamic nature) |
Any ideas when this will be implemented? In PHP frameworks dependency injectors use strings for registering modules, relations are also accessed via strings sometimes. There are so many uses, when a simple raw string is used nowadays as a parameter. It's year 2016, should not be really that hard to implement such a feature, when we are able to create very complex systems. It's simple as that, in PHPStorm the following scenario would be handy: |
@mvriel I came across this issue on CodeTriage as this issue was almost over 2 years old. And it seems to me that time has proven the issue to be not that desired that anyone in the OSS community started working on it (or any alternatives) I know there is no native support for enumerations available in PHP (or even planned to be; currently there is an RFC in draft since '15). Alternatively there is the SPL Enum offering a close to native approach. In addition the examples in the opening post could be upgraded to use objects (implementing a enum type using one of the available libraries ) to avoid having a string type as function parameter. Most importantly having an IMHO the issue can be closed, that said the remark of @felixfbecker in 125731809 seems like a more natural approach which is still very close to the current |
Before closing this issue I want to make @ashnazg aware of this question. If this is not added to the psr-5 standard phpdocumentor will not support this. Moving this to our psr-5 project. |
Six years later.. Any progress on this issue? |
Asking is answering the question... |
In PSR-5 it is possible to specify elements types for an Array:
|
PHPDocumentor definitely should support this. PHP apps may become very complex, there are already many things we have to memorize, no need to keep memorizing possible string argument values for tens/hundreds of functions. psr-5 has an abandoned status anyway, so there is no reason to wait for it to be released. |
It doesn't our team is preparing to pick up the discussion on psr-5 again. |
@jaapio that's a good news! I think many people just gave up on this (desired, but not a critical), but they still hoping for it to be implemented. I can speak for myself, I almost switched to node.js/typescript world because of this "little" issue (5 years ago I hated JS for it's messy language, now it's been improved significantly, leaving PHP far behind it) |
I'm very unconvinced on this one. Making a class be your enumerator object seems to me to be the correct approach, both in code and in documenting things. This approach is already supported, and has been back into 1.x. PHP allowing this behavior (without a proper Enum object) is one of its tradeoffs, and I don't think we can make a doc-only construct for every occasion where "I only want to use strings in my code, but I want my docs to look like these are strict typed thingamabobs". |
These type of issues are the reason why I gave up with PHP after 11 years and moved to node.js + Typescript. PHP is moving too slow for 2018 |
wow this is a really long time to not do this feature... Some sort of concept that would potentially be forward compatible with RFC types being added to php when the figure it out? /**
* @var objectConstants|\Path\To\ClassHoldingStrings
*/
public $stringFromConstants; /**
* @param objectConstants|\Path\To\ClassHoldingStrings $param
*/
public function valueSetter($param) {
$this->value = $param;
} |
The thing is not to implement this feature but to maintain al non php constructs in phpdocumentor. We are all looking for a way to fake enum behavior in php. And there are a few good user land implementations on packagist.org following the approach of @ashnazg. You are now talking about class constants. But remember that class constants are not just string types. It can be an array to. And maybe in the future other complex types. It is not the task of phpdocumentor to add new language constructs. I think an library in php should fix this issue. If there is a need to add some documentation part to support that library we are happy to provide support. But for now it isn't on our priority list. As it wasn't the last six years. We already have enough missing features that are added to php. Let us focus on that first before we start making new things in the application. This issue is open for future reference. And at some point we will start implementing a solution. |
yeah I agree there shouldn't be hacks added into phpdoc.. but there must be some sort of concept that can logically solve this concept of needing a param to be a restricted list string, somehow |
So now that it's PSR-19 any chance of something sane being suggested to the FIG by someone who can? I really like the type addendum style, but with
|
Hi guys, any update on this? 🤐 |
The referenced comment is not properly linked by GitHub (from a large PR and not easy to find o/w), the relevant link is MyIntervals/emogrifier#778 (comment) |
Anything on this yet? |
@ashnazg is this currently in PSR-5/PSR-19? Does this require action? |
how does it looks like ? In SF there is something like that: So my 2 cents :) use John\Doe\Foo;
...
/**
* @var string{"bar1", Foo::SPECIAL_BAR, ...Foo:LIST_OF_BARS}
*/
public string $bar; |
This issue was moved to a discussion.
You can continue the conversation there. Go to discussion →
PHPDocumentor doesn't support listing of enumerated values for a property or for a method argument. I suggest that this would be a useful addition to doc blocks;
While @options might not be the best tag to use, or this syntax could be simplified (and might need modification if the list of options was to be a list of valid constant values), it seems to me that it would be a useful addition to the doc block because the alternative is documenting it in the general block comments. A formal syntax of some description would simplify this and provide a standardised display of the valid options
The text was updated successfully, but these errors were encountered: