FR: Handle the values passed via CLI arguments in a case-insensitive manner

[jrfnl]

Feature request

When providing CLI arguments, it is common for tools to allow passing those in a case-insensitive manner.

At this moment, this is not the case in phpDocumentor and I would like to suggest changing this to treat all values passed to CLI arguments in a case-insensitive manner.

Precedent

PHPUnit

Given a test class called MyArbitraryTest, I can run just that test by calling:

phpunit --filter=myarbitrarytest

I.e. the value of the command line argument is handled in a case-insensitive manner.

PHP_CodeSniffer

If I'd want to run the PHPCompatibility standard over a codebase (provided the standard is installed), I can do this by calling:

phpcs . --standard=phpcompatibility
phpcs . --standard=PHPCompatibility
phpcs . --standard=PHPCOMPATIBILITY

I.e. the value of the command line argument is handled in a case-insensitive manner.

Current behaviour in phpDocumentor - example 1

Given a simple test file saved as ./src/Issue2434.php containing the following:

<?php
class Issue2434 {}

Running phpDocumentor 3 with the following command:

phpdoc -f ./src/issue2434.php

Results in:

phpDocumentor v3.0.x-dev@d15f2d6                                              
                                                                              
23:50:14 WARNING   [app] Your project seems to be empty!                      
Parsing files                                                                 
                                                                              
Applying transformations (can take a while)                                   
 19/19 [============================] 100%                                    
All done in 1 seconds!                                                        

And no docs being generated:

Running phpDocumentor 3 with the following command (correct case):

phpdoc -f ./src/Issue2434.php

... works fine as expected:

phpDocumentor v3.0.x-dev@d15f2d6                                              
                                                                              
Parsing files                                                                 
 1/1 [============================] 100%                                      
Applying transformations (can take a while)                                   
 19/19 [============================] 100%                                    
All done in 1 seconds!                                                        

Current behaviour in phpDocumentor - example 2

# phpdoc --visibility=PRIVATE
PHP 7.4.6 (cli) (built: May 12 2020 11:41:06) ( ZTS Visual C++ 2017 x86 )
Copyright (c) The PHP Group
Zend Engine v3.4.0, Copyright (c) Zend Technologies

phpDocumentor v3.0.x-dev@d15f2d6

23:43:35 ERROR     [console] Error thrown while running command "--visibility=PRIVATE". Message: "PRIVATE is not a type of visibility, supported is: api, public, protected, private or internal" ["exception" => RuntimeException { …},"command" => "--visibility=PRIVATE","message" => "PRIVATE is not a type of visibility, supported is: api, public, protected, private or internal"]
23:43:35 ERROR     [console] Error thrown while running command "--visibility=PRIVATE". Message: "PRIVATE is not a type of visibility, supported is: api, public, protected, private or internal" ["exception" => RuntimeException { …},"command" => "--visibility=PRIVATE","message" => "PRIVATE is not a type of visibility, supported is: api, public, protected, private or internal"]

In ProjectDescriptorBuilder.php line 207:

  PRIVATE is not a type of visibility, supported is: api, public, protected, private or internal

[mvriel]

For quite a few things I agree, but file and folders handling needs to be case sensitive because some filesystems are case sensitive, and files with the same name but a different case can co-exist. (let's not debate whether this is a good idea; that would be a short debate 😆 )

I see you also mention visibility, and that can very well be case insensitive. Sounds like a good improvement :)

[jrfnl]

I understand your point of view regarding file/folder names, though that could possibly be solved by doing a case-sensitive check to find the file first and if not found, falling back to a case-insensitive one.

If you like, I could look into how other tools do this as I'm fairly confident that both tools I mentioned before, do support it.

Glad to hear though that, at a minimum, for everything else this is accepted as a viable feature request.
Not a priority, but a nice feature for the future to look forward to! ❤️

[mvriel]

Those checks can be bad for performance, especially when working with remote filesystems. We try to follow the rules for glob (although these are not in a proper specification). Although I am interested in how other tools deal with this; I do think that changing this specific part may have edge cases that can be problematic.

[jaapio]

I made the visibility case insensitive. For now that will be the only change.

[jrfnl]

Thanks @jaapio !