Paths for --filename and <file> are not resolved correctly

[fi5er]

The --filename command line argument cannot be given absolute paths or relative paths that start at the current directory or a parent directory. The same goes for the -f alias and for <file> in a config file.

Given the following directory structure:

├── CURRENT_DIR
│   ├── subdir
│   │   └── Test.php
│   └── Test.php
└── other
    └── Test.php

Actual Behavior

Running phpdoc from CURRENT_DIR may or may not find the file "Test.php" using the command line phpdoc parse --filename path --force -vvv. I get the following results for different paths:

• Test.php - found
• ./Test.php - not found
• ../CURRENT_DIR/Test.php - not found
• subdir/Test.php - found
• subdir/../Test.php - not found
• ./subdir/Test.php - not found
• ../other/Test.php - not found
• /abs/path/to/other/Test.php - not found

The debug output is

[2018-12-23 17:19:32] app.INFO: One of the project's settings have changed, forcing a complete rebuild [] []
[2018-12-23 17:19:32] app.INFO: Elapsed time to parse all files: 0s [] []
[2018-12-23 17:19:32] app.INFO: Peak memory usage: 10M [] []

Expected Behavior

A "Test.php" file should be found in all of these paths.

Steps to Reproduce the Problem

• $ mkdir -p dirtest/CURRENT_DIR/subdir dirtest/other
• $ cd dirtest/CURRENT_DIR
• $ touch Test.php
• $ cp Test.php subdir
• $ cp Test.php ../other
• $ phpdoc parse --filename ../other/Test.php --force -vvv

Your environment

• Version used: v3.0.x-dev@ee92b8f
• Install method: cloned "develop" branch
• php version: 7.2.10
• Operating system and version: Kubuntu 18.04

[jaapio]

Thanks for your report and test cases. It took some time to investigate this but hopefully you are still able to respond when you think we are doing something wrong here.

First of all, it is good to notice that phpdocumentor v3 is using FlySystem under the hood to be able to support new features planned in future releases. So file discovery will not fully work like every other commandline tool.

We have introduced a new configuration format to make it more clear what is done. The snippet below shows the defaults. We are searching for files relative to the current working directory. Which is defined as dsn. The paths, but also the legacy command line arguments are relative to that dsn.

        <api format="php">
            <source dsn="file://.">
                <path>src</path>
            </source>
            <ignore hidden="true" symlinks="true">
                <path>src/ServiceDefinitions</path>
            </ignore>
            <extensions>
                <extension>php</extension>
            </extensions>

So if you are in the CURRENT_DIR we will only be able to find subdir/Test.php and Test.php
I need to investigate why the notation of relative paths like ./Test.php are not working because they should. Other notations that do go one level up ../ will never work with phpdoc 3. Also, single files with an absolute path will most likely not work in the future anymore. To be onest I don't see why that should be a use case. Since the purpose of phpdoc is to generate documentation for your project, a file that is defined outside the project is not part of the project and will therefore never be included.

The new config format needs documentation.

[mvriel]

I will need to re-test this soon; this mechanism has seen a lot of improvements in the past month.