Phpdocumentor: v3-alpha4/phar not working on Windows ?
I'm unsure whether this is a configuration issue, a Windows issue or a PHPDoc 3 issue, but hopefully providing all this info might yield something.
Happy to try and help debug this further.
Config used
File: phpdoc.xml in the project root.
<?xml version="1.0" encoding="UTF-8" ?>
<phpdoc>
<title>PHPCSUtils</title>
<files>
<file>autoload.php</file>
<directory>PHPCSUtils</directory>
</files>
<parser>
<target>build/docs/structure/</target>
</parser>
<transformer>
<target>build/docs/output/</target>
</transformer>
<logging>
<level>debug</level>
</logging>
</phpdoc>
I've tried setting the <transformations> key and tried nearly all possible templates, but the output is no different.
Command used
phpdoc run from the project root
Output on screen
Complete output
# phpdoc run
PHP 7.1.30 (cli) (built: May 28 2019 15:12:11) ( ZTS MSVC14 (Visual C++ 2015) x86 )
Copyright (c) 1997-2018 The PHP Group
Zend Engine v3.1.0, Copyright (c) 1998-2018 Zend Technologies
phpDocumentor v3.0.0-alpha.4-6-gc5f3834c
[2019-11-08 10:55:39] app.NOTICE: Using the configuration file at the default location [] []
[2019-11-08 10:55:39] app.INFO: Collecting files .. [] []
[2019-11-08 10:55:43] app.INFO: OK [] []
[2019-11-08 10:55:43] app.INFO: Loading project from cache [] []
[2019-11-08 10:55:43] app.NOTICE: Parsing files [] []
Parsing files
[2019-11-08 10:55:43] app.INFO: Elapsed time to parse all files: 0.01s [] []
[2019-11-08 10:55:43] app.INFO: Peak memory usage: 12M [] []
[2019-11-08 10:55:43] app.NOTICE: Storing cache .. [] []
[2019-11-08 10:55:43] app.INFO: OK [] []
[2019-11-08 10:55:43] app.INFO: Loading project from cache [] []
[2019-11-08 10:55:43] app.INFO: Applying 17 transformations [] []
Applying transformations (can take a while)
[2019-11-08 10:55:43] app.INFO: Initialize writer "phpDocumentor\Transformer\Writer\FileIo" [] []
[2019-11-08 10:55:43] app.INFO: Initialize writer "phpDocumentor\Transformer\Writer\Twig" [] []
[2019-11-08 10:55:43] app.INFO: Initialize writer "phpDocumentor\Transformer\Writer\Graph" [] []
[2019-11-08 10:55:43] app.NOTICE: Writer FileIo using query "copy" on .htaccess [] []
1/17 [=>--------------------------] 5%[2019-11-08 10:55:43] app.NOTICE: Writer FileIo using query "copy" on images [] []
2/17 [===>------------------------] 11%[2019-11-08 10:55:43] app.NOTICE: Writer FileIo using query "copy" on css [] []
3/17 [====>-----------------------] 17%[2019-11-08 10:55:43] app.NOTICE: Writer FileIo using query "copy" on js [] []
4/17 [======>---------------------] 23%[2019-11-08 10:55:43] app.NOTICE: Writer FileIo using query "copy" on font [] []
5/17 [========>-------------------] 29%[2019-11-08 10:55:43] app.NOTICE: Writer twig using query "namespace" on index.html [] []
6/17 [=========>------------------] 35%[2019-11-08 10:55:43] app.NOTICE: Writer twig using query "indexes.namespaces" on [] []
7/17 [===========>----------------] 41%[2019-11-08 10:55:43] app.NOTICE: Writer twig using query "indexes.classes" on [] []
8/17 [=============>--------------] 47%[2019-11-08 10:55:43] app.NOTICE: Writer twig using query "indexes.interfaces" on [] []
9/17 [==============>-------------] 52%[2019-11-08 10:55:43] app.NOTICE: Writer twig using query "indexes.traits" on [] []
10/17 [================>-----------] 58%[2019-11-08 10:55:43] app.NOTICE: Writer twig using query "files" on [] []
11/17 [==================>---------] 64%[2019-11-08 10:55:43] app.NOTICE: Writer twig using query "files" on files/{{path}}.txt [] []
12/17 [===================>--------] 70%[2019-11-08 10:55:43] app.NOTICE: Writer twig on reports/markers.html [] []
13/17 [=====================>------] 76%[2019-11-08 10:55:43] app.NOTICE: Writer twig on reports/errors.html [] []
14/17 [=======================>----] 82%[2019-11-08 10:55:43] app.NOTICE: Writer twig on reports/deprecated.html [] []
15/17 [========================>---] 88%[2019-11-08 10:55:43] app.NOTICE: Writer twig on graphs/class.html [] []
16/17 [==========================>-] 94%[2019-11-08 10:55:43] app.NOTICE: Writer Graph on graphs/classes.svg [] []
17/17 [============================] 100%[2019-11-08 10:55:44] app.NOTICE: Finished transformation process [] []
All done!
Exit code is 0
Expected Behavior
Docs being generated....
Actual Behavior
Some files are generated and put in the /build/docs/ directory.
Note: not the build/docs/output or build/docs/structure directories which are referenced in the config file...
When I open the build/docs/index.html file in a browser, I get:
Your environment
- Version used: 3.0.0-alpha.4-6-gc5f3834c
- Phar downloaded from GH releases page
- PHP 7.1.30
- Windows 7
- Project is not (yet) available online.
jrfnl
All 96 comments
Windows 7 SP1 64-bit
PHP 7.1.30 64-bit Windows native
Version used: phpDocumentor v3.0.0-alpha.4-6-gc5f3834c (from releases page)
Project: https://github.com/AnrDaemon/library-php
Command: phpDocumentor.phar project:run --directory="src" --target=".output" --cache-folder=".cache" --sourcecode
Logfile: .phpdoc3.log
Output: output.tar.gz
Does not look even remotely usable.
AnrDaemon
on 4 Dec 2019
Thank you for your thorough addition to this bug! I can surely use this to hone in on the problem. In the past week, we have been working on including automated testing on Windows and MacOSX to our build pipeline; with the next PHAR we expect these issues to be resolved
mvriel
on 4 Dec 2019
I did delete the .htaccess file in the output directory, if you are wondering.
It was generated correctly, but produce issues on subsequent launches on my system.
If you take suggestions, I would recommend deleting it instead of trying to just write over.
AnrDaemon
on 4 Dec 2019
@AnrDaemon Thanks for confirming the issue.
@mvriel Sounds awesome! Please let me know if there is anything you'd like me to test.
jrfnl
on 4 Dec 2019
I have not been able to test this personally on my Windows setup but the past two weeks we have been focusing on setting up a build pipeline that tests on windows as well. After various improvements and fixes, our pipeline reports a working version for the PHAR file at https://github.com/phpDocumentor/phpDocumentor/suites/358520704/artifacts/693056 .
I haven't verified this myself locally yet, but if you don't mind trying this out that would be super helpful
mvriel
on 14 Dec 2019
PHP Warning: require(phar://box-auto-generated-alias-cac9f18c022d.phar/.box/bin/check-requirements.php): failed to open stream: phar error: internal corruption of phar "…/phpDocumentor.phar" (actual filesize mismatch on file ".box/bin/check-requirements.php") in …\phpDocumentor.phar on line 12
PHP Fatal error: require(): Failed opening required 'phar://box-auto-generated-alias-cac9f18c022d.phar/.box/bin/check-requirements.php' (include_path='.;C:/usr/sbin/php-libs;C:/usr/sbin/php-tools/pear') in …\phpDocumentor.phar on line 12
That's weird :thinking: I guess I need to boot my windows soon and investigate that then. I don't understand why Github Actions doesn't fail on this.
mvriel
on 14 Dec 2019
@AnrDaemon how do you use PHP on Windows? Did you install it from php.net and run if from powershell? Or another method?
mvriel
on 14 Dec 2019
Adding to that,
* The application requires the version ">=7.2.5" or greater.
Sorry, but 7.2 is not usable under Windows. Extensions coverage is minimal.
AnrDaemon
on 14 Dec 2019
This is something with zip file. Different archivers unpack it differently.
444150b5e9fd3525a1e381861abade8757fad11f *phpDocumentor-7z.phar
a82f2ed27d641323982983375d85fab91589c5ba *phpDocumentor-unzip.phar
444150b5e9fd3525a1e381861abade8757fad11f *phpDocumentor-winrar.phar
Consequently, 7z/winrar log looks like
PHP Warning: include_once(phar://…/phpDocumentor.phar/var/cache/prod/ContainerPUkq3Lu/getStopwatchMiddlewareService.php on line 11
PHP Warning: include_once(): Failed opening 'phar://…/phpDocumentor.phar/var/cache/prod/ContainerPUkq3Lu/getStopwatchMiddlewareService.php on line 11
PHP Warning: include_once(phar://…/phpDocumentor.phar/var/cache/prod/ContainerPUkq3Lu/getFilesService.php on line 9
PHP Warning: include_once(): Failed opening 'phar://…/phpDocumentor.phar/var/cache/prod/ContainerPUkq3Lu/getFilesService.php on line 9
PHP Warning: include_once(phar://…/phpDocumentor.phar/var/cache/prod/ContainerPUkq3Lu/getFilesService.php on line 10
PHP Warning: include_once(): Failed opening 'phar://…/phpDocumentor.phar/var/cache/prod/ContainerPUkq3Lu/getFilesService.php on line 10
PHP Warning: include_once(phar://…/phpDocumentor.phar/var/cache/prod/ContainerPUkq3Lu/getFilesService.php on line 11
PHP Warning: include_once(): Failed opening 'phar://…/phpDocumentor.phar/var/cache/prod/ContainerPUkq3Lu/getFilesService.php on line 11
PHP Warning: include_once(phar://…/phpDocumentor.phar/var/cache/prod/ContainerPUkq3Lu/getFilesService.php on line 12
PHP Warning: include_once(): Failed opening 'phar://…/phpDocumentor.phar/var/cache/prod/ContainerPUkq3Lu/getFilesService.php on line 12
PHP Warning: include_once(phar://…/phpDocumentor.phar/var/cache/prod/ContainerPUkq3Lu/getFilesService.php on line 13
PHP Warning: include_once(): Failed opening 'phar://…/phpDocumentor.phar/var/cache/prod/ContainerPUkq3Lu/getFilesService.php on line 13
PHP Warning: include_once(phar://…/phpDocumentor.phar/var/cache/prod/ContainerPUkq3Lu/getFilesService.php on line 14
PHP Warning: include_once(): Failed opening 'phar://…/phpDocumentor.phar/var/cache/prod/ContainerPUkq3Lu/getFilesService.php on line 14
PHP Warning: include_once(phar://…/phpDocumentor.phar/var/cache/prod/ContainerPUkq3Lu/getFilesService.php on line 15
PHP Warning: include_once(): Failed opening 'phar://…/phpDocumentor.phar/var/cache/prod/ContainerPUkq3Lu/getFilesService.php on line 15
PHP Warning: include_once(phar://…/phpDocumentor.phar/var/cache/prod/ContainerPUkq3Lu/getFilesService.php on line 16
PHP Warning: include_once(): Failed opening 'phar://…/phpDocumentor.phar/var/cache/prod/ContainerPUkq3Lu/getFilesService.php on line 16
PHP Warning: include_once(phar://…/phpDocumentor.phar/var/cache/prod/ContainerPUkq3Lu/getFilesService.php on line 17
PHP Warning: include_once(): Failed opening 'phar://…/phpDocumentor.phar/var/cache/prod/ContainerPUkq3Lu/getFilesService.php on line 17
PHP Warning: include_once(phar://…/phpDocumentor.phar/var/cache/prod/ContainerPUkq3Lu/getFilesService.php on line 18
PHP Warning: include_once(): Failed opening 'phar://…/phpDocumentor.phar/var/cache/prod/ContainerPUkq3Lu/getFilesService.php on line 18
PHP Warning: include_once(phar://…/phpDocumentor.phar/var/cache/prod/ContainerPUkq3Lu/getFilesService.php on line 19
PHP Warning: include_once(): Failed opening 'phar://…/phpDocumentor.phar/var/cache/prod/ContainerPUkq3Lu/getFilesService.php on line 19
PHP Warning: include_once(phar://…/phpDocumentor.phar/var/cache/prod/ContainerPUkq3Lu/getFilesService.php on line 20
PHP Warning: include_once(): Failed opening 'phar://…/phpDocumentor.phar/var/cache/prod/ContainerPUkq3Lu/getFilesService.php on line 20
PHP Warning: include_once(phar://…/phpDocumentor.phar/var/cache/prod/ContainerPUkq3Lu/getFilesService.php on line 21
PHP Warning: include_once(): Failed opening 'phar://…/phpDocumentor.phar/var/cache/prod/ContainerPUkq3Lu/getFilesService.php on line 21
PHP Warning: include_once(phar://…/phpDocumentor.phar/var/cache/prod/ContainerPUkq3Lu/getFilesService.php on line 22
PHP Warning: include_once(): Failed opening 'phar://…/phpDocumentor.phar/var/cache/prod/ContainerPUkq3Lu/getFilesService.php on line 22
PHP Warning: include_once(phar://…/phpDocumentor.phar/var/cache/prod/ContainerPUkq3Lu/getRunCommandService.php on line 9
PHP Warning: include_once(): Failed opening 'phar://…/phpDocumentor.phar/var/cache/prod/ContainerPUkq3Lu/getRunCommandService.php on line 9
PHP Warning: include_once(phar://…/phpDocumentor.phar/var/cache/prod/ContainerPUkq3Lu/getRunCommandService.php on line 11
PHP Warning: include_once(): Failed opening 'phar://…/phpDocumentor.phar/var/cache/prod/ContainerPUkq3Lu/getRunCommandService.php on line 11
PHP Warning: include_once(phar://…/phpDocumentor.phar/var/cache/prod/ContainerPUkq3Lu/getPhpdoc_Configuration_PipelineService.php on line 9
PHP Warning: include_once(): Failed opening 'phar://…/phpDocumentor.phar/var/cache/prod/ContainerPUkq3Lu/getPhpdoc_Configuration_PipelineService.php on line 9
PHP Warning: include_once(phar://…/phpDocumentor.phar/var/cache/prod/ContainerPUkq3Lu/getPhpdoc_Cache_PipelineService.php on line 9
PHP Warning: include_once(): Failed opening 'phar://…/phpDocumentor.phar/var/cache/prod/ContainerPUkq3Lu/getPhpdoc_Cache_PipelineService.php on line 9
PHP Warning: include_once(phar://…/phpDocumentor.phar/var/cache/prod/ContainerPUkq3Lu/getPhpdoc_Transform_PipelineService.php on line 9
PHP Warning: include_once(): Failed opening 'phar://…/phpDocumentor.phar/var/cache/prod/ContainerPUkq3Lu/getPhpdoc_Transform_PipelineService.php on line 9
PHP Warning: include_once(phar://…/phpDocumentor.phar/var/cache/prod/ContainerPUkq3Lu/getTransformCommandService.php on line 9
PHP Warning: include_once(): Failed opening 'phar://…/phpDocumentor.phar/var/cache/prod/ContainerPUkq3Lu/getTransformCommandService.php on line 9
phpDocumentor 8f12095
You can run a phar as an executable. php will just be able to read the phar.
php phpdocumentor.phar is the command you might be able to execute. where php should be in your path or an location that windows is able to discover.
There is no need to extract the phar.
jaapio
on 15 Dec 2019
@AnrDaemon progress! That you get those warnings is odd since we warm the cache before packing the PHAR. But in the bottom I do see the version number opening line of phpDocumentor.
Is this all the output you received? And which command did you use so I can try and reproduce it
mvriel
on 15 Dec 2019
@mvriel I've tested and am not making much progress.
Tested with PHP 7.3.12 with the fileinfo extension enabled.
Same config as above.
Run using the following command:
C:\path\to\php7.3.12\php.exe -f C:\path\to\phars\phpDocumentor-3.0.0-alpha4a.phar run
Output:
```# phpdoc3 run
PHP 7.3.12 (cli) (built: Nov 19 2019 14:00:18) ( ZTS MSVC15 (Visual C++ 2017) x86 )
Copyright (c) 1997-2018 The PHP Group
Zend Engine v3.3.12, Copyright (c) 1998-2018 Zend Technologies
phpDocumentor 8f12095
09:32:11 ERROR [console] Error thrown while running command "run". Message: "Argument 1 passed to phpDocumentor\Parser\SpecificationFactory::inPath() must be of the type string, object given, called in phar://C:/path/to/phars/phpDocumentor-3.0.0-alpha4a.phar/src/phpDocumentor/Parser/SpecificationFactory.php on line 47" ["exception" => TypeError { …},"command" => "run","message" => "Argument 1 passed to phpDocumentor\Parser\SpecificationFactory::inPath() must be of the type string, object given, called in phar://C:/path/to/phars/phpDocumentor-3.0.0-alpha4a.phar/src/phpDocumentor/Parser/SpecificationFactory.php on line 47"]
09:32:11 ERROR [console] Error thrown while running command "run". Message: "Argument 1 passed to phpDocumentor\Parser\SpecificationFactory::inPath() must be of the type string, object given, called in phar://C:/path/to/phars/phpDocumentor-3.0.0-alpha4a.phar/src/phpDocumentor/Parser/SpecificationFactory.php on line 47" ["exception" => TypeError { …},"command" => "run","message" => "Argument 1 passed to phpDocumentor\Parser\SpecificationFactory::inPath() must be of the type string, object given, called in phar://C:/path/to/phars/phpDocumentor-3.0.0-alpha4a.phar/src/phpDocumentor/Parser/SpecificationFactory.php on line 47"]
In SpecificationFactory.php line 77:
Argument 1 passed to phpDocumentor\Parser\SpecificationFactory::inPath() must be of the type string, object given, called in phar://C:/path/to/phars/phpDocumentor-3.0.0-alpha4a.phar/src/phpDocumentor/Parser/SpecificationFactory.php on line 47
project:run [-t|--target [TARGET]] [--cache-folder [CACHE-FOLDER]] [-f|--filename [FILENAME]] [-d|--directory [DIRECTORY]] [--encoding [ENCODING]] [--extensions [EXTENSIONS]] [-i|--ignore [IGNORE]] [--ignore-tags [IGNORE-TAGS]] [--hidden] [--ignore-symlinks] [-m|--markers [MARKERS]] [--title [TITLE]] [--force] [--validate] [--visibility [VISIBILITY]] [--defaultpackagename [DEFAULTPACKAGENAME]] [--sourcecode] [--template [TEMPLATE]] [--parseprivate] [-h|--help] [-q|--quiet] [-v|vv|vvv|--verbose] [-V|--version] [--ansi] [--no-ansi] [-n|--no-interaction] [-c|--config [CONFIG]] [--log [LOG]] [-e|--env ENV] [--no-debug] [--]
Exit code is 255
```
jrfnl
on 15 Dec 2019
@jrfnl we didn't update the phar file you reference to but have a nightly build that we are currently testing at https://github.com/phpDocumentor/phpDocumentor/suites/358520704/artifacts/693056
Though it would seem that there may be a caching issue still there, @jaapio is looking into it
mvriel
on 15 Dec 2019
I was doing something wrong byself... I was able to execute the phar @mvriel linked.
But since I'm on linux, and don't have a windows box available I cannot dive in to the real issue.
It would be much appreciated if you are able to test with the phar that you can download from the link @mvriel provided.
jaapio
on 15 Dec 2019
@jrfnl we didn't update the phar file you reference to but have a nightly build that we are currently testing at https://github.com/phpDocumentor/phpDocumentor/suites/358520704/artifacts/693056
That's where I downloaded the phar I tested with from...
Note the alpha4a instead of alpha4 which was my way of distinguishing between the official alpha 4 and the WIP branch.
jrfnl
on 15 Dec 2019
Ok, I will first try to create the docs from your project on linux. If that succeeds I will come back to you.
Thanks for your help so far.
jaapio
on 15 Dec 2019
@jaapio My project is not yet online unfortunately.
jrfnl
on 15 Dec 2019
Forgot about that :-(
jaapio
on 15 Dec 2019
Hang on, let me try with another project which is online and I'll get back to you in a moment.
jrfnl
on 15 Dec 2019
@jaapio Results with the other repo are exactly the same.
Test branch can be found here: https://github.com/PHPCompatibility/PHPCompatibility/tree/TEST/phpdoc3
jrfnl
on 15 Dec 2019
I have the same issue on linux. I will provide a new phar when this issue is fixed.
jaapio
on 15 Dec 2019
It seems that the current version had an issue with the configuration of 2 paths, in your case
<files>
<file>PHPCompatibility/*</file>
<directory>PHPCompatibility/Sniffs/</directory>
</files>
Removing one of the lines will fix it. A new phar is currently build so should be available within a few minutues. That will revolve the issue with the multiple paths.
when I removed a path from the config I got the expected output. So I'm very curious if the previous reported windows issue is now also revolved
jaapio
on 15 Dec 2019
The new phar can be downloaded here:
https://github.com/phpDocumentor/phpDocumentor/suites/359031437/artifacts/698530
jaapio
on 15 Dec 2019
In ProjectDescriptorBuilder.php line 111: Return value of phpDocumentor\Descriptor\ProjectDescriptorBuilder::filter() must implement interface phpDocumentor\Descriptor\Filter\Filterable, null returned
Still some issues
jaapio
on 15 Dec 2019
All set, at least on linux the phar https://github.com/phpDocumentor/phpDocumentor/suites/359049637/artifacts/698676 is now able to parse the full https://github.com/PHPCompatibility/PHPCompatibility/tree/TEST/phpdoc3 repo.
If somebody with a working windows setup is able to run this phar and provide any feedback that would be very helpfull
jaapio
on 15 Dec 2019
@jaapio Thanks for your efforts.
I have tested this new version against both projects and while the command does finish now, the results are basically back to what I reported above: empty docs.
The output also complains about GraphViz not being found, but there doesn't appear to be a check for GraphViz in the initial system configuration check (which checked the PHP version, fileinfo being available etc).
I'm attaching zips with the output of both runs.
For PHPCompatibility, it basically hasn't generated any docs.
For PHPCSUtils, it says it has recognized the namespace, but clicking on that, results in a _page not found_.
# phpdoc3 run
PHP 7.3.12 (cli) (built: Nov 19 2019 14:00:18) ( ZTS MSVC15 (Visual C++ 2017) x86 )
Copyright (c) 1997-2018 The PHP Group
Zend Engine v3.3.12, Copyright (c) 1998-2018 Zend Technologies
phpDocumentor 5f57962
16:47:04 WARNING [app] Your project seems to be empty!
Parsing files
Applying transformations (can take a while)
6/17 [=========>------------------] 35%Unable to find the `dot` command of the GraphViz package. Is GraphViz correctly installed and present in your path
17/17 [============================] 100%
All done!
Exit code is 0
Thanks a lot for the outputs. I see that the warning we added about the project being empty is triggered. It looks like there's a problem in the file resolving. But that needs to be investigated on a windows box. Since we both executed the same config.
I think you did not directly execute the phar since I see some phpdoc3 command in the output? Do you use some kind of wrapper script around it?
Where did you place the phar?
jaapio
on 15 Dec 2019
It looks like there's a problem in the file resolving. But that needs to be investigated on a windows box. Since we both executed the same config.
@jaapio As you mention file resolving, just some questions to see if it helps debugging. Note: I haven't actually examined the code of the phpDoc 3 branch, so am just troubleshooting by questions here.
- How is the file finding and parsing done ?
If I remember correctly from way long ago, this was done by walking the directories and tokenizing the files.
What has changed there ? - Does the phpDoc presume it has access to the projects autoload file ? Does it need access ?
- Does the project presume that the project being scanned is installed with Composer ?
I think you did not directly execute the phar since I see some phpdoc3 command in the output? Do you use some kind of wrapper script around it?
Where did you place the phar?
I use a windows .bat file for the command and to allow me to easily switch between PHP versions (and between phars) to run things with.
Note: the php directory, the phar directory and the directory where I have those .bat files are all in the Windows PATH, so I can call the commands from anywhere on my system without problems.
The C:\path\to\phars\phpDocumentor-3.0.0-alpha4b.phar file is the latest phar I downloaded from the WIP branch.
This is the content of the phpdoc3.bat file:
@echo off
:: PHP 7.3.12 has fileinfo extension enabled.
:set PHPBIN=C:\wamp\bin\php\php7.2.25\php.exe
:set PHPBIN=C:\wamp\bin\php\php7.3.4\php.exe
set PHPBIN=C:\wamp\bin\php\php7.3.12\php.exe
:set PHPBIN=C:\wamp\bin\php\php7.4.0\php.exe
:set PHPDOC=C:\path\to\phars\phpDocumentor-3.0.0-alpha4.phar
:set PHPDOC=C:\path\to\phars\phpDocumentor-3.0.0-alpha4a.phar
set PHPDOC=C:\path\to\phars\phpDocumentor-3.0.0-alpha4b.phar
:RUN
"%PHPBIN%" -v
ECHO(
"%PHPBIN%" -d include_path="%PHPBIN%" -f "%PHPDOC%" -- %*
ECHO(
ECHO Exit code is %errorlevel%
Oh and regarding this:
I see that the warning we added about the project being empty is triggered.
That happened only for the PHPCompatibility project, not for the PHPCSUtils one.
jrfnl
on 15 Dec 2019
You can run a phar as an executable. php will just be able to read the phar.
php phpdocumentor.pharis the command you might be able to execute. where php should be in your path or an location that windows is able to discover.There is no need to extract the phar.
I was extracting the .phar itself from the downloaded zip file.
Is this all the output you received? And which command did you use so I can try and reproduce it
Yes, I was running php -f phpDocumentor.phar -- -V
AnrDaemon
on 15 Dec 2019
Thank you so much for the outstanding information. This helps a lot.
Phpdocumentor doesn't use composer in any way during the processing of the project files. Each file is a potential input file.
Under the hood we are now using flysystem, because that will allow us to read files directly from a remote source in the future. That means we are a bit more limited to the directory scanning since the location of the config file is considered to be the root of a project. From there all paths are relative, and you can only go deeper into the directory tree.
That's a lot different from what phpdocumentor did in previous versions. But since there are so many cases and setups it will be hard to say without debugging more what is going on.
But at least we have a direction where to look. I will first try to reproduce this again on Linux.
If that doesn't help @mvriel will pick this up since he has a windows laptop available
jaapio
on 15 Dec 2019
@jaapio Just out of curiosity, I've cloned the repo, ran composer install, adjusted the phpdoc3.bat file to point to the I:\path\to\phpDocumentor\bin\phpdoc file and done a test run on both projects again and the results are the same in both cases, so the problem definitely isn't with the Phar file.
jrfnl
on 15 Dec 2019
Further to that, I found an error in my phpdoc.xml file for the PHPCompatibility project (oops... was using the paths from PHPCSUtils, no wonder it didn't find anything).
Rerunning after fixing that, does generate more output, but still nothing useful. Will upload the zip again.
When I run it with info set as logging level, I do see at least some things which are going wrong.
I set the paths to parse based on the information found here: https://docs.phpdoc.org/references/configuration.html
Particularly this section:
The files section allows you to specify where the source code for your project is and what files to ignore.
<files> <file>test.php</file> <file>bin/*</file> <directory>src</directory> <directory>tes??</directory> <ignore>test/*</ignore> </files>It is allowed to use relative paths here; just remember that these are relative from the the location of your configuration file.
It is possible to specify specific files or a specific set of files using the
fileelement. As with the-fparameter it supports wildcards.In addition you can also provide entire directory trees using the element. This also supports the use of wildcards. Please note that, in contrary to the
fileelement, thedirectoryelement is recursive and will tell phpDocumentor to process all files contained in this folder and every subfolder.
So with the config I have in PHPCompatibility:
<files>
<file>PHPCompatibility/*</file>
<directory>PHPCompatibility/Sniffs/</directory>
</files>
I would - based on the last sentence of the quoted docs above - expect the files in the PHPCompatibility/ directory to be scanned (non-recursively) and the whole of the PHPCompatibility/Sniffs/ directory recursively.
In practice, however, it seems that the whole of the PHPCompatibility/ directory is scanned recursively, including the PHPCompatibility/Tests/ directory. This directory includes test case files which definitely shouldn't be scanned and contain (intentional) parse errors about which phpDocumentor is throwing alerts.
The output of the project now looks like this:
Note: it has _correctly_ recognized the PHPCompatibility namespace, but incorrectly added classes from the test case files.
When I click through on the PHPCompatibility namespace link or either or the class links, I still get the same _file not found_ as before.
Complete output again:
20191215-2 PHPCompatibility config and output.zip
Using the info level on the PHPCSUtils project doesn't yield any new information.
jrfnl
on 15 Dec 2019
Oh and this:
Clicking through via the menu on the left side shows me it has scanned all the files:
But clicking on any of the links throws the _file not found_ error and if I look in the file system, that's not surprising as the files directory doesn't contain any html files, just empty txt files.
jrfnl
on 15 Dec 2019
Oh and another thing I noticed:
Even though I did set the <parser configuration:
<parser>
<target>build/docs/structure</target>
</parser>
... no build/docs/structure directory is created or filled.
jrfnl
on 15 Dec 2019
And one more.... though that's more a phpDocumentor project configuration issue:
After running the composer install on the git clone, on Windows I see two new unstaged files bin/var-dump-server.bat (completely new file) and symfony.lock (changed file, addition of symfony/contracts).
Should the first be added to the phpDocumentor project .gitignore ?
And the second maybe committed to the repo ?
jrfnl
on 15 Dec 2019
Ok, enough for now. I think there's at least some solution paths to explore based on the above four comments. :smiley:
jrfnl
on 15 Dec 2019
Thanks again for all your help. We have definitely some work to do to get this right. Some of the issues you are reporting will have nothing to do with windows. But do require some more testing on our side.
Thanks again, I will come back to you when I feel more confident about the parsing process
jaapio
on 15 Dec 2019
@jaapio No problems. let me know if you want me to run more/other tests.
jrfnl
on 15 Dec 2019
MFG!!!!
If phar.readonly = On, it runs just fine.
If phar.readonly = Off, the output is as shown in the logs, and it actually tries to write to the .phar, and damages it!
AnrDaemon
on 15 Dec 2019
Thanks for pointing that out. Needs to be be fixed as well.
jaapio
on 15 Dec 2019
(Though, it still generates empty docs.)
AnrDaemon
on 15 Dec 2019
As you can read in the other comments in this issue, we need to do some more testing to get this part more stable to get it back to an accurate level. Our current test suite is definitely missing multiple use cases
jaapio
on 15 Dec 2019
@AnrDaemon A new phar is currently build. This addresses the issue you had with the warnings. Please report any followup issues with the writable phar to a new issue.
Meanwhile we will start working on adding more tests to cover the empty docs. which are propably caused by invalid file resolving.
jaapio
on 15 Dec 2019
Where I can see the list of these built phar's ? I'm a bit lost.
AnrDaemon
on 16 Dec 2019
Our builds can be found here: https://github.com/phpDocumentor/phpDocumentor/actions?query=branch%3Amaster+workflow%3A%22Qa+workflow%22
Each item has it's own artifacts. which can be downloaded on the right upper corner.
Maybe we can provide a more user friendly list in the future.
jaapio
on 16 Dec 2019
Mainwhile a lot has been changed. One thing that has not changed is me not having a windows machine available :-)
What i just did:
- download this phar https://github.com/phpDocumentor/phpDocumentor/suites/382865525/artifacts/931109
- cloned https://github.com/PHPCompatibility/PHPCompatibility/tree/TEST/phpdoc3
- and just ran the phar without any arguments.
After a while the output was ready. Docs seem to be available.
But I cannot tell you for sure if everything is now working on windows.
What we did, we found out that our current way of handling output could cause issues. So we rewrote the templating part to be able to use flysystem to target the target folder of the docs. This saves us a lot of code and headaches about handling file paths properly,
Thanks to the reports you did we were also able to discover a breaking change in phpdocumentor that was not intended regarding the configuration. We were doing some path matching on flysystem to detect the files. but it worked out way better to have just glob support. So that's in now. meaning that the configuration of the mentioned project is now just working.
Apart from that a lot of internals have been changed and the amount of tests running on windows has been extended a lot.
So I'm very curious if all these efforts would help you :-D
jaapio
on 3 Jan 2020
@jaapio Sounds like a lot of great work has been done! I'll test it with both projects over the next few days.
jrfnl
on 3 Jan 2020
I have some results from a test I did on a virtual machine running windows 10. We still have a small issue that needs to be fixed before you will be able to run phpdocumentor without problems.
So please hold on. no need to test right now.
jaapio
on 4 Jan 2020
https://github.com/phpDocumentor/phpDocumentor/suites/384811452/artifacts/953699
Ok this new phar should work. I was able to generate documentation for the example project.
~I discovered another issue in the templates.~
~The links to other files in the templates are not always generated correctly. So if you try the phar in this comment you will be able to generate the docs. But when you want to view them you will get 404 errors.~
Issue above is also fixed. updated the link to a working phar :-)
jaapio
on 5 Jan 2020
Looks like something isn't quite right still:
λ php phpdoc.phar -d ./ -t docs --ignore node_modules/ --ignore semantic/ --ignore tinymce/ --ignore ./vendor/ --cache-folder ../phpdoc_cache
phpDocumentor 95011a5
Parsing files
65/65 [============================] 100%09:28:51 ERROR [console] Error thrown while running command "-d "./" -t docs --ignore "node_modules/" --ignore "semantic/" --ignore "tinymce/" --ignore "./vendor/" --cache-folder "../phpdoc_cache". Message: "Impossible to create the root directory "/E:/Software/Laragon/www/omnibus/docs". mkdir(): No such file or directory" ["exception" => League\Flysystem\Exception^ { …},"command" => "-d "./" -t docs --ignore "node_modules/" --ignore "semantic/" --ignore "tinymce/" --ignore "./vendor/" --cache-folder "../phpdoc_cache"","message" => "Impossible to create the root directory "/E:/Software/Laragon/www/omnibus/docs". mkdir(): No such file or directory"]
09:28:51 ERROR [console] Error thrown while running command "-d "./" -t docs --ignore "node_modules/" --ignore "semantic/" --ignore "tinymce/" --ignore "./vendor/" --cache-folder "../phpdoc_cache". Message: "Impossible to create the root directory "/E:/Software/Laragon/www/omnibus/docs". mkdir(): No such file or directory" ["exception" => League\Flysystem\Exception^ { …},"command" => "-d "./" -t docs --ignore "node_modules/" --ignore "semantic/" --ignore "tinymce/" --ignore "./vendor/" --cache-folder "../phpdoc_cache"","message" => "Impossible to create the root directory "/E:/Software/Laragon/www/omnibus/docs". mkdir(): No such file or directory"]
In Local.php line 112:
Impossible to create the root directory "/E:/Software/Laragon/www/omnibus/docs". mkdir(): No such file or directo
ry
project:run [-t|--target [TARGET]] [--cache-folder [CACHE-FOLDER]] [-f|--filename [FILENAME]] [-d|--directory [DIRECTORY]] [--encoding [ENCODING]] [--extensions [EXTENSIONS]] [-i|--ignore [IGNORE]] [--ignore-tags [IGNORE-TAGS]] [--hidden] [--ignore-symlinks] [-m|--markers [MARKERS]] [--title [TITLE]] [--force] [--validate] [--visibility [VISIBILITY]] [--defaultpackagename [DEFAULTPACKAGENAME]] [--sourcecode] [--template [TEMPLATE]] [--parseprivate] [-h|--help] [-q|--quiet] [-v|vv|vvv|--verbose] [-V|--version] [--ansi] [--no-ansi] [-n|--no-interaction] [-c|--config [CONFIG]] [--log [LOG]] [-e|--env ENV] [--no-debug] [--] <command>
And when I manually created the folder docs:
php phpdoc.phar -d ./ -t docs --ignore node_modules/ --ignore semantic/ --ignore tinymce/ --ignore ./vendor/ --cache-folder ../phpdoc_cache
phpDocumentor 95011a5
Parsing files
65/65 [============================] 100%09:32:51 ERROR [console] Error thrown while running command "-d "./" -t docs --ignore "node_modules/" --ignore "semantic/" --ignore "tinymce/" --ignore "./vendor/" --cache-folder "../phpdoc_cache". Message: "Impossible to create the root directory "/E:/Software/Laragon/www/omnibus/docs". mkdir(): No such file or directory" ["exception" => League\Flysystem\Exception^ { …},"command" => "-d "./" -t docs --ignore "node_modules/" --ignore "semantic/" --ignore "tinymce/" --ignore "./vendor/" --cache-folder "../phpdoc_cache"","message" => "Impossible to create the root directory "/E:/Software/Laragon/www/omnibus/docs". mkdir(): No such file or directory"]
09:32:51 ERROR [console] Error thrown while running command "-d "./" -t docs --ignore "node_modules/" --ignore "semantic/" --ignore "tinymce/" --ignore "./vendor/" --cache-folder "../phpdoc_cache". Message: "Impossible to create the root directory "/E:/Software/Laragon/www/omnibus/docs". mkdir(): No such file or directory" ["exception" => League\Flysystem\Exception^ { …},"command" => "-d "./" -t docs --ignore "node_modules/" --ignore "semantic/" --ignore "tinymce/" --ignore "./vendor/" --cache-folder "../phpdoc_cache"","message" => "Impossible to create the root directory "/E:/Software/Laragon/www/omnibus/docs". mkdir(): No such file or directory"]
In Local.php line 112:
Impossible to create the root directory "/E:/Software/Laragon/www/omnibus/docs". mkdir(): No such file or directo
ry
project:run [-t|--target [TARGET]] [--cache-folder [CACHE-FOLDER]] [-f|--filename [FILENAME]] [-d|--directory [DIRECTORY]] [--encoding [ENCODING]] [--extensions [EXTENSIONS]] [-i|--ignore [IGNORE]] [--ignore-tags [IGNORE-TAGS]] [--hidden] [--ignore-symlinks] [-m|--markers [MARKERS]] [--title [TITLE]] [--force] [--validate] [--visibility [VISIBILITY]] [--defaultpackagename [DEFAULTPACKAGENAME]] [--sourcecode] [--template [TEMPLATE]] [--parseprivate] [-h|--help] [-q|--quiet] [-v|vv|vvv|--verbose] [-V|--version] [--ansi] [--no-ansi] [-n|--no-interaction] [-c|--config [CONFIG]] [--log [LOG]] [-e|--env ENV] [--no-debug] [--] <command>
Atulin
on 5 Jan 2020
hm, where is this pre-fix / coming from? Seems that the fix I did to get rid of the file:/// in the file path is not working???
if (strpos($root, 'file:///') === 0) {
$root = substr($root, strlen('file:///'));
}
Is this drive a network drive?
jaapio
on 5 Jan 2020
No, it's not a network drive
Atulin
on 5 Jan 2020
As a remark, file:/// shouldn't cause issues to the best of my knowledge.
Testing now.
AnrDaemon
on 5 Jan 2020
mkdir('file:///C:/tmp/phpdoc-behat/cli/test/build/api', 0777, true); will fail. that was the main cause of all the issues you are facing.
jaapio
on 5 Jan 2020
Sounds bugreport-worthy…
AnrDaemon
on 5 Jan 2020
Yeah, this is a weird situation since stuff like file_get_contents does seem to work. Jaap is currently doing a deep dive in phpDocumentor using Windows to catch all path-related oddities
mvriel
on 5 Jan 2020
1/24 [=>--------------------------] 4%
5/24 [=====>----------------------] 20%
8/24 [=========>------------------] 33%
10/24 [===========>----------------] 41%
12/24 [==============>-------------] 50%
17/24 [===================>--------] 70%
20/24 [=======================>----] 83%
24/24 [============================] 100%14:10:52 ERROR [console] Error thrown while running command "project:run --directory src --target ".output" --cache-folder ".cache" --sourcecode". Message: "Impossible to create the root directory "/C:/Users/anrdaemon/Documents/.github/library-php/.output". mkdir(): No such file or directory" ["exception" => League\Flysystem\Exception { …},"command" => "project:run --directory src --target ".output" --cache-folder ".cache" --sourcecode","message" => "Impossible to create the root directory "/C:/Users/anrdaemon/Documents/.github/library-php/.output". mkdir(): No such file or directory"]
14:10:52 ERROR [console] Error thrown while running command "project:run --directory src --target ".output" --cache-folder ".cache" --sourcecode". Message: "Impossible to create the root directory "/C:/Users/anrdaemon/Documents/.github/library-php/.output". mkdir(): No such file or directory" ["exception" => League\Flysystem\Exception { …},"command" => "project:run --directory src --target ".output" --cache-folder ".cache" --sourcecode","message" => "Impossible to create the root directory "/C:/Users/anrdaemon/Documents/.github/library-php/.output". mkdir(): No such file or directory"]
In Local.php line 112:
Impossible to create the root directory "/C:/Users/anrdaemon/Documents/.github/library-php/.output". mkdir(): No such file or
directory
project:run [-t|--target [TARGET]] [--cache-folder [CACHE-FOLDER]] [-f|--filename [FILENAME]] [-d|--directory [DIRECTORY]] [--encoding [ENCODING]] [--extensions [EXTENSIONS]] [-i|--ignore [IGNORE]] [--ignore-tags [IGNORE-TAGS]] [--hidden] [--ignore-symlinks] [-m|--markers [MARKERS]] [--title [TITLE]] [--force] [--validate] [--visibility [VISIBILITY]] [--defaultpackagename [DEFAULTPACKAGENAME]] [--sourcecode] [--template [TEMPLATE]] [--parseprivate] [-h|--help] [-q|--quiet] [-v|vv|vvv|--verbose] [-V|--version] [--ansi] [--no-ansi] [-n|--no-interaction] [-c|--config [CONFIG]] [--log [LOG]] [-e|--env ENV] [--no-debug] [--] <command>
My apologies if I wasn't clear; Jaap is not done yet. We found various path resolving issues and he is working on a solution for all of them
mvriel
on 5 Jan 2020
To give you some insights on what I'm going through now:
just what:
A UNC name of any format, which always start with two backslash characters ("\"). For more information, see the next section.
A disk designator with a backslash, for example "C:\" or "d:\".
A single backslash, for example, "directory" or "file.txt". This is also referred to as an absolute path.
They are converting / to \ internally:
File I/O functions in the Windows API convert "/" to "\" as part of converting the name to an NT-style name, except when using the "\?\" prefix as detailed in the following sections.
I agree with @AnrDaemon that this might need a bug report to php. But I want to make sure that we are not doing something wrong. At the moment the windows filesystem is driving me nuts.
my conclusion this far.
If I just trim the / from the path before we create the flysystem adapter it will work. But that will not work in all cases since a path might start with / and is a valid path on windows.
however, I'm not sure if php supports these paths. I'm not very familiar with the paths you can define on windows. I remember that \\SomeServer\path\to\dir would work on windows using samba mounts? since Microsoft decided to allow / in a path //SomeServer/path/to/dir would work?
jaapio
on 5 Jan 2020
You don't exactly NEED to convert to backslashes. Not even in case of UNC.
Internally, Win32API don't see a difference between them.
<?php
var_dump(glob("\\\\HOSTING64.DARKDRAGON.LAN\\wwwroot\\ccenter\\*.json"));
var_dump(glob("//HOSTING64.DARKDRAGON.LAN/wwwroot/ccenter/*.json"));
array(1) {
[0]=>
string(56) "\\HOSTING64.DARKDRAGON.LAN\wwwroot\ccenter\composer.json"
}
array(1) {
[0]=>
string(56) "//HOSTING64.DARKDRAGON.LAN/wwwroot/ccenter/composer.json"
}
Just throwing it out there, half-understanding what is being discussed here, maybe DIRECTORY_SEPARATOR would be of use?
Atulin
on 5 Jan 2020
As a side note, I'm writing PHP on Windows for over 15 years, and never had a second thought on using forward vs. backslashes in FS interaction.
I MAY prefer to use backslash when I want to pass the Windows path around, or print to the console, but internally, there's not much of a reason to waste time.
AnrDaemon
on 5 Jan 2020
@Atulin DIRECTORY_SEPARATOR is useful, when you want pretty printing, or parsing system output.
That's about it.
AnrDaemon
on 5 Jan 2020
Thank you @AnrDaemon for helping us out with this #notAllContributionsAreInCode
mvriel
on 5 Jan 2020
I'm sorry that I have no time to help with code… Helping where I can.
AnrDaemon
on 5 Jan 2020
No need to feel sorry, you are already helping us with testing and reporting issues. That's appreciated a lot. Since we thought we were safe because of the extended build pipeline
jaapio
on 5 Jan 2020
@jaapio Just reading up on things. Anything I can currently do / test ?
And yes, I can confirm that PHP on Windows doesn't care whether forward or backward slashes are used. Both will work.
jrfnl
on 5 Jan 2020
No there is nothing you can do right now. I think I'm almost there with a solution that works in the situations the people here reported.
I'm fairly sure that there will be more issues regarding windows. Since @mvriel and I do both have a Linux dev system. And all tests that were written are based on expectations.
I found that multiple tests we wrote contained errors just validating wrong behavior. I will report here when a new build is available. But that is gonna take a while since my holidays are over now. So we are back to a evening dev schedule
jaapio
on 5 Jan 2020
I tried running it through WSL. No cigar either, apparently. Here's the output:
root@AngPC:/mnt/e/Software/Laragon/www/omnibus# php phpdoc.phar -d ./ -t docs --ignore node_modules/ --ignore semantic/ --ignore tinymce/ --ignore ./vendor/ --cache-folder ../phpdoc_cache
phpDocumentor 95011a5
Parsing files
65/65 [============================] 100%
Applying transformations (can take a while)
7/17 [===========>----------------] 41%01:19:38 ERROR [console] Error thrown while running command "-d './' -t docs --ignore 'node_modules/' --ignore 'semantic/' --ignore 'tinymce/' --ignore './vendor/' --cache-folder '../phpdoc_cache'". Message: "An exception has been thrown during the rendering of a template (""\Backend\Models\User::$joined;" is not a valid Fqsen.")." ["exception" => Twig\Error\RuntimeError^ { …},"command" => "-d './' -t docs --ignore 'node_modules/' --ignore 'semantic/' --ignore 'tinymce/' --ignore './vendor/' --cache-folder '../phpdoc_cache'","message" => "An exception has been thrown during the rendering of a template (""\Backend\Models\User::$joined;" is not a valid Fqsen.")."]
01:19:38 ERROR [console] Error thrown while running command "-d './' -t docs --ignore 'node_modules/' --ignore 'semantic/' --ignore 'tinymce/' --ignore './vendor/' --cache-folder '../phpdoc_cache'". Message: "An exception has been thrown during the rendering of a template (""\Backend\Models\User::$joined;" is not a valid Fqsen.")." ["exception" =>Twig\Error\RuntimeError^ { …},"command" => "-d './' -t docs --ignore 'node_modules/' --ignore 'semantic/' --ignore 'tinymce/' --ignore './vendor/' --cache-folder '../phpdoc_cache'","message" => "An exception has been thrown during the rendering of a template (""\Backend\Models\User::$joined;" is not a valid Fqsen.")."]
In class.html.twig line 110:
An exception has been thrown during the rendering of a template (""\Backend\Models\User::$joined;" is not a valid
Fqsen.").
In Fqsen.php line 51:
"\Backend\Models\User::$joined;" is not a valid Fqsen.
project:run [-t|--target [TARGET]] [--cache-folder [CACHE-FOLDER]] [-f|--filename [FILENAME]] [-d|--directory [DIRECTORY]] [--encoding [ENCODING]] [--extensions [EXTENSIONS]] [-i|--ignore [IGNORE]] [--ignore-tags [IGNORE-TAGS]] [--hidden] [--ignore-symlinks] [-m|--markers [MARKERS]] [--title [TITLE]] [--force] [--validate] [--visibility [VISIBILITY]] [--defaultpackagename [DEFAULTPACKAGENAME]] [--sourcecode] [--template [TEMPLATE]] [--parseprivate] [-h|--help] [-q|--quiet] [-v|vv|vvv|--verbose] [-V|--version] [--ansi] [--no-ansi] [-n|--no-interaction] [-c|--config [CONFIG]] [--log [LOG]] [-e|--env ENV] [--no-debug] [--] <command>
My WSL is running on
Distributor ID: Ubuntu
Description: Ubuntu 18.04.3 LTS
Release: 18.04
Codename: bionic
@Atulin this error is thrown during the wrong stage but is still true. Your project contains an invalid FQSEN \Backend\Models\User::$joined; should have been \Backend\Models\User::$joined
jaapio
on 6 Jan 2020
Well this is awkward
Atulin
on 6 Jan 2020
Just a small update from our side. A new build is available:
https://github.com/phpDocumentor/phpDocumentor/suites/392896342/artifacts/1036874
The end-2-end test @mvriel wrote are now passing on the windows pipeline step. So that's the good news.
I did some manual tests on a windows 10 box, to parse the project provided by @jrfnl. but also the command provided by @Atulin both cases seem to pass now. So I would love to get your feedback, if some of you do have time to test this new build.
There are still some open discussion points which can be seen in #2202 regarding the implementation. Because I had to do some specific windows only stuff to get the file handling working on linux and windows in all situations I could come up with.
I'm not saying that we are supporting all windows supported paths, but the most common used paths should work in this build.
Possible known issues are:
- windows samba shares will not work properly.
- paths on linux like
/c:/my/windows/like/pathwill most likely not work - network shares are not supported.
Of any of you could confirm that the known issues are not working or can be removed from this list we can add that to the docs of phpdocumentor 3.
Thanks in advance for all your help!
jaapio
on 9 Jan 2020
@jaapio @mvriel Thank you both for all the work you are doing on trying to fix this.
I've just done a test run on PHPCompatibility (which @jaapio also used to test) using both the phar as well as a git clone and, unfortunately, am not yet having much luck, though the errors appear to be quite different this time.
For the phar run:
The end-result is an empty build/docs/output folder.
Before running the command I'd removed everything from the build dir, so at least it confirms that the docs/output folders are being created, even though nothing else is.
I also noticed that the phar file is about 4x as big now. Is that correct ?
Full debug output from run with phar
# phpdoc3 run
PHP 7.3.12 (cli) (built: Nov 19 2019 14:00:18) ( ZTS MSVC15 (Visual C++ 2017) x86 )
Copyright (c) 1997-2018 The PHP Group
Zend Engine v3.3.12, Copyright (c) 1998-2018 Zend Technologies
phpDocumentor 000a321
Parsing files
124/124 [============================] 100%22:57:56 ERROR [console] Error thrown while running command "run". Message: "Impossible to create the root directory "phar://c/path/to/phars/phpDocumentor-3.0.0-alpha4c.phar/src/phpDocumentor/../../data/templates". mkdir(): phar error: cannot create directory "phar://c/path/to/phars/phpDocumentor-3.0.0-alpha4c.phar/src/phpDocumentor/../../data/templates", no phar archive specified" ["exception" => League\Flysystem\Exception^ { …},"command" => "run","message" => "Impossible to create the root directory "phar://c/path/to/phars/phpDocumentor-3.0.0-alpha4c.phar/src/phpDocumentor/../../data/templates". mkdir(): phar error: cannot create directory "phar://c/path/to/phars/phpDocumentor-3.0.0-alpha4c.phar/src/phpDocumentor/../../data/templates", no phar archive specified"]
22:57:56 ERROR [console] Error thrown while running command "run". Message: "Impossible to create the root directory "phar://c/path/to/phars/phpDocumentor-3.0.0-alpha4c.phar/src/phpDocumentor/../../data/templates". mkdir(): phar error: cannot create directory "phar://c/path/to/phars/phpDocumentor-3.0.0-alpha4c.phar/src/phpDocumentor/../../data/templates", no phar archive specified" ["exception" => League\Flysystem\Exception^ { …},"command" => "run","message" => "Impossible to create the root directory "phar://c/path/to/phars/phpDocumentor-3.0.0-alpha4c.phar/src/phpDocumentor/../../data/templates". mkdir(): phar error: cannot create directory "phar://c/path/to/phars/phpDocumentor-3.0.0-alpha4c.phar/src/phpDocumentor/../../data/templates", no phar archive specified"]
In Local.php line 112:
Impossible to create the root directory "phar://c/path/to/phars/phpDocumentor-3.0.0-alpha4c.phar/src/phpDocumentor/../../data/templates"
. mkdir(): phar error: cannot create directory "phar://c/path/to/phars/phpDocumentor-3.0.0-alpha4c.phar/src/phpDocumentor/../../data/templates", no phar archive specified
project:run [-t|--target [TARGET]] [--cache-folder [CACHE-FOLDER]] [-f|--filename [FILENAME]] [-d|--directory [DIRECTORY]] [--encoding [ENCODING]] [--extensions [EXTENSIONS]] [-i|--ignore [IGNORE]] [--ignore-tags [IGNORE-TAGS]] [--hidden] [--ignore-symlinks] [-m|--markers [MARKERS]] [--title [TITLE]] [--force] [--validate] [--visibility [VISIBILITY]] [--defaultpackagename [DEFAULTPACKAGENAME]] [--sourcecode] [--template [TEMPLATE]] [--parseprivate] [-h|--help] [-q|--quiet] [-v|vv|vvv|--verbose] [-V|--version] [--ansi] [--no-ansi] [-n|--no-interaction] [-c|--config [CONFIG]] [--log [LOG]] [-e|--env ENV] [--no-debug] [--] <command>
Exit code is 1
For the git clone run
Next, I've done a run with a git clone of the project using the fix/windows-template-path-resolving branch with a fresh composer install --no-dev.
End result: No files nor directories are created at all.
I've checked some of the paths mentioned in the errors and the files being referred to do not exist, so the warnings are correct, though I do wonder whether include_once is correct. If those files are essentially needed, shouldn't that be require_once ?
I also have a feeling this may have to do with the var/cache/prod directory possibly containing outdated files ?
If so, should the cache automatically be cleared in some way ? And if not automatically, how can I force this manually ?
I presume the cache was created via a composer plugin/script ? Should that clear the cache and/or update it on a new composer install ?
Full debug output from run with git clone
# phpdoc3 run
PHP 7.3.12 (cli) (built: Nov 19 2019 14:00:18) ( ZTS MSVC15 (Visual C++ 2017) x86 )
Copyright (c) 1997-2018 The PHP Group
Zend Engine v3.3.12, Copyright (c) 1998-2018 Zend Technologies
Warning: include_once(I:\path\to\phpDocumentor\src\phpDocumentor\Console\Command\Project\ParseCommand.php): failed to open stream: No such file or directory in I:\path\to\phpDocumentor\var\cache\prod\ContainerJPxx0Ob\getParseCommandService.php on line 10
Warning: include_once(): Failed opening 'I:\path\to\phpDocumentor\src\phpDocumentor\Console\Command\Project\ParseCommand.php' for inclusion (include_path='C:\wamp\bin\php\php7.3.12\php.exe') in I:\path\to\phpDocumentor\var\cache\prod\ContainerJPxx0Ob\getParseCommandService.php on line 10
Warning: include_once(I:\path\to\phpDocumentor\src\phpDocumentor\Application\PipelineFactory.php): failed to open stream: No such file or directory in I:\path\to\phpDocumentor\var\cache\prod\ContainerJPxx0Ob\getRunCommandService.php on line 11
Warning: include_once(): Failed opening 'I:\path\to\phpDocumentor\src\phpDocumentor\Application\PipelineFactory.php' for inclusion (include_path='C:\wamp\bin\php\php7.3.12\php.exe') in I:\path\to\phpDocumentor\var\cache\prod\ContainerJPxx0Ob\getRunCommandService.php on line 11
Warning: include_once(I:\path\to\phpDocumentor\src\phpDocumentor\Console\Command\Project\TransformCommand.php): failed to open stream: No such file or directory in I:\path\to\phpDocumentor\var\cache\prod\ContainerJPxx0Ob\getTransformCommandService.php on line 10
Warning: include_once(): Failed opening 'I:\path\to\phpDocumentor\src\phpDocumentor\Console\Command\Project\TransformCommand.php' for inclusion (include_path='C:\wamp\bin\php\php7.3.12\php.exe') in I:\path\to\phpDocumentor\var\cache\prod\ContainerJPxx0Ob\getTransformCommandService.php on line 10
[WARNING] Some commands could not be registered:
In getParseCommandService.php line 12:
Class 'phpDocumentor\Console\Command\Project\ParseCommand' not found
In getRunCommandService.php line 13:
Class 'phpDocumentor\Application\PipelineFactory' not found
In getTransformCommandService.php line 12:
Class 'phpDocumentor\Console\Command\Project\TransformCommand' not found
There are no commands defined in the "project" namespace.
Exit code is 1
Anyways, that's what I've got for you now. let me know if there's anything else I can do to test this.
jrfnl
on 9 Jan 2020
Yup, same. Tries to write to the .phar.
2.log
AnrDaemon
on 10 Jan 2020
@jrfnl you can clear the cache with ./bin/console cache:clear that will most likely solve the issue of the composer installation
jaapio
on 10 Jan 2020
@jaapio Thanks. Unfortunately that's not working for me/on Windows. Tried and failed.
I first tried to run it just from the command line, thinking it was an executable/bat like the files in vendor/bin:
# ./bin/console cache:clear
'.' is not recognized as an internal or external command,
operable program or batch file.
Right, ok, so I forgot that never works on Windows and you need to wrap the command in quotes:
# "/bin/console" cache:clear
The system cannot find the path specified.
Hmm... maybe without the leading slash ?
# "bin/console" cache:clear
'"bin/console"' is not recognized as an internal or external command,
operable program or batch file.
Then I opened the file realized it was a PHP file ..., so I need to invoke it through PHP (well, I created a little clearcache.bat file containing the command and placed it in the phpDocumentor project root):
php.exe -f "path/to/phpDocumentor/bin/console" cache:clear
Output:
// Clearing the cache for the dev environment with debug true
[OK] Cache for the "dev" environment (debug=true) was successfully cleared.
Then tried to run PHPDoc again for PHPCompatibility: no change in the output. Still getting the same errors as per the above posted logs.
Went back to the directory in which I cloned phpDocumentor and checked the var/cache directory. Looks like nothing has changed. All files are still from Dec 15 when I first tried the git clone run.
Tried to run clearcache again and am now running out of memory and it's still not clearing the clearing:
// Clearing the cache for the dev environment with debug true
VirtualAlloc() failed: [0x00000008] Not enough storage is available to process this command.
VirtualAlloc() failed: [0x00000008] Not enough storage is available to process this command.
<span style='color: #ff0000'>
Fatal error: Out of memory (allocated 350224384) (tried to allocate 327159808 bytes) in I:\path\to\phpDocumentor\vendor\symfony\config\Resource\ReflectionClassResource.php on line 141
</span>[14:35:09]: Fatal Error: Out of memory (allocated 350224384) (tried to allocate 327159808 bytes)
In ReflectionClassResource.php line 141:
Error: Out of memory (allocated 350224384) (tried to allocate 327159808 bytes)
cache:clear [--no-warmup] [--no-optional-warmers] [-h|--help] [-q|--quiet] [-v|vv|vvv|--verbose] [-V|--version] [--ansi] [--no-ansi] [-n|--no-interaction] [-c|--config [CONFIG]] [--log [LOG]] [-e|--env ENV] [--no-debug] [--] <command>
Got any other suggestions ?
jrfnl
on 10 Jan 2020
You could try:
php.exe -f "path/to/phpDocumentor/bin/console" cache:clear --env=prod
jaapio
on 10 Jan 2020
@jaapio Even though the run gave me errors on the screen again, it _does_ appear that the cache has actually been cleared (files now all have today's date).
My current clearcache.bat which is located in the phpDocumentor git clone project root:
@echo off
set PHPBIN=C:\wamp\bin\php\php7.3.12\php.exe
set PHPDOCSCRIPT=I:\path\to\phpDocumentor\bin\console
:RUN
"%PHPBIN%" -v
ECHO(
"%PHPBIN%" -d include_path="%PHPBIN%" -f "%PHPDOCSCRIPT%" cache:clear --env=prod -- %*
Output:
```# clearcache
PHP 7.3.12 (cli) (built: Nov 19 2019 14:00:18) ( ZTS MSVC15 (Visual C++ 2017) x86 )
Copyright (c) 1997-2018 The PHP Group
Zend Engine v3.3.12, Copyright (c) 1998-2018 Zend Technologies
Warning: include_once(I:\path\tophpDocumentorsrcphpDocumentor\Console\Command\Project\ParseCommand.php): failed to open stream: No such file or directory in I:\path\tophpDocumentor\var\cacheprod\ContainerJPxx0Ob\getParseCommandService.php on line 10
Warning: include_once(): Failed opening 'I:\path\tophpDocumentorsrcphpDocumentor\Console\Command\Project\ParseCommand.php' for inclusion (include_path='C:\wamp\binphpphp7.3.12php.exe') in I:\path\tophpDocumentor\var\cacheprod\ContainerJPxx0Ob\getParseCommandService.php on line 10
Warning: include_once(I:\path\tophpDocumentorsrcphpDocumentor\Application\PipelineFactory.php): failed to open stream: No such file or directory in I:\path\tophpDocumentor\var\cacheprod\ContainerJPxx0Ob\getRunCommandService.php on line 11
Warning: include_once(): Failed opening 'I:\path\tophpDocumentorsrcphpDocumentor\Application\PipelineFactory.php' for inclusion (include_path='C:\wamp\binphpphp7.3.12php.exe') in I:\path\tophpDocumentor\var\cacheprod\ContainerJPxx0Ob\getRunCommandService.php on line 11
Warning: include_once(I:\path\tophpDocumentorsrcphpDocumentor\Console\Command\Project\TransformCommand.php): failed to open stream: No such file or directory in I:\path\tophpDocumentor\var\cacheprod\ContainerJPxx0Ob\getTransformCommandService.php on line 10
Warning: include_once(): Failed opening 'I:\path\tophpDocumentorsrcphpDocumentor\Console\Command\Project\TransformCommand.php' for inclusion (include_path='C:\wamp\binphpphp7.3.12php.exe') in I:\path\tophpDocumentor\var\cacheprod\ContainerJPxx0Ob\getTransformCommandService.php on line 10
[WARNING] Some commands could not be registered:
In getParseCommandService.php line 12:
Class 'phpDocumentor\Console\Command\Project\ParseCommand' not found
In getRunCommandService.php line 13:
Class 'phpDocumentor\Application\PipelineFactory' not found
In getTransformCommandService.php line 12:
Class 'phpDocumentor\Console\Command\Project\TransformCommand' not found
[WARNING] Some commands could not be registered:
In getParseCommandService.php line 12:
Class 'phpDocumentor\Console\Command\Project\ParseCommand' not found
In getRunCommandService.php line 13:
Class 'phpDocumentor\Application\PipelineFactory' not found
In getTransformCommandService.php line 12:
Class 'phpDocumentor\Console\Command\Project\TransformCommand' not found
// Clearing the cache for the prod environment with debug false
In Filesystem.php line 176:
Failed to remove directory "I:\path\tophpDocumentor\var\cachepro_": rmdir(I:\path\tophpDocumentor\var\cachepro_): Directory not empty.
cache:clear [--no-warmup] [--no-optional-warmers] [-h|--help] [-q|--quiet] [-v|vv|vvv|--verbose] [-V|--version] [--ansi] [--no-ansi] [-n|--no-interaction] [-c|--config [CONFIG]] [--log [LOG]] [-e|--env ENV] [--no-debug] [--]
```
Running the clearcache command a second time gives me the out of memory error again.
jrfnl
on 10 Jan 2020
Ok, so now the cache was cleared, I've tried to run phpDocumentor again over PHPCompatibility using the git clone.
Screen output:
# phpdoc3 run
PHP 7.3.12 (cli) (built: Nov 19 2019 14:00:18) ( ZTS MSVC15 (Visual C++ 2017) x86 )
Copyright (c) 1997-2018 The PHP Group
Zend Engine v3.3.12, Copyright (c) 1998-2018 Zend Technologies
phpDocumentor v3.0.x-dev@2ab1850
Parsing files
124/124 [============================] 100%
Applying transformations (can take a while)
16/17 [==========================>-] 94%Unable to find the `dot` command of the GraphViz package. Is GraphViz correctly installed and present in your path 17/17 [============================] 100%
All done!
Exit code is 0
The docs appear to be generated correctly at first glance :tada:
The Class Hierachy graph gives an empty screen however.
20200110 PHPCompatibility docs via git clone.zip
So there is definitely progress :+1:
Status summary:
- Generating via git clone on Windows works with the code from #2202
Class hierachy diagramis still problematic.
- Generating via the phar does not yet work.
- Clearing the cache may need some automation and improvements for use on Windows
If you like I'll do a test run with the other project later tonight.
jrfnl
on 10 Jan 2020
Just some notes from a first glance looking at the current output (I should probably open separate issues for these):
- Everything inherited from a parent class is shown in every child class.
For individual elements it will show "Inherited from" in the side bar on the right side, but there is no ordering by child class/ parent class or a way to hide what comes from the parent in the summary. - When something is clicked, the menu on the left folds in again. State doesn't pertain between screens. (usability)
- Multiple class level
@sincetags are not parsed correctly.
Example can be seen in:build/docs/output/classes/PHPCompatibility-Sniffs-FunctionDeclarations-NewParamTypeDeclarationsSniff.html - Class level
@linktags do not show at all.
Example can be seen in the same file as above. - Inline
{@internal .. }tags are shown in plain text.
Example can be seen inbuild/docs/output/classes/PHPCompatibility-Sniffs-FunctionDeclarations-ForbiddenParameterShadowSuperGlobalsSniff.html
There will probably be more, but I should have left half an hour ago already :sweat_smile: , so don't have time at the moment for a more detailed check
jrfnl
on 10 Jan 2020
Some more debugging, turned out that our ci is not correctly testing the phar in all situations.
Having that said, I check it manually to confirm the error you had by executing the phar.
This was a windows only phar related issue. A new phar is available:
https://github.com/phpDocumentor/phpDocumentor/suites/394838886/artifacts/1057266
If any of you can check if their usecase is now working :-D
jaapio
on 10 Jan 2020
@jaapio Just did a test run with the new phar & PHPCompatibility and so far (phar), so good. Output looks the same as the previous successful run with the git clone (so no class hierarchy chart, but HTML files all seem present & working)
Screen output:
# phpdoc3 run
PHP 7.3.12 (cli) (built: Nov 19 2019 14:00:18) ( ZTS MSVC15 (Visual C++ 2017) x86 )
Copyright (c) 1997-2018 The PHP Group
Zend Engine v3.3.12, Copyright (c) 1998-2018 Zend Technologies
phpDocumentor 7632766
Parsing files
124/124 [============================] 100%
Applying transformations (can take a while)
16/17 [==========================>-] 94%Unable to find the `dot` command of the GraphViz package. Is GraphViz correctly installed and present in your path 17/17 [============================] 100%
All done!
Exit code is 0
Next, I've done a test run with the project which is not yet online and unfortunately, I'm running into an error there, but I think that's unrelated to the issue being discussed here:
# phpdoc3 run
PHP 7.3.12 (cli) (built: Nov 19 2019 14:00:18) ( ZTS MSVC15 (Visual C++ 2017) x86 )
Copyright (c) 1997-2018 The PHP Group
Zend Engine v3.3.12, Copyright (c) 1998-2018 Zend Technologies
phpDocumentor 7632766
Parsing files
28/28 [============================] 100%01:13:33 WARNING [php] Warning: vsprintf(): Too few arguments ["exception" => ErrorException { …}]
Fatal error: Method phpDocumentor\Reflection\DocBlock\Description::__toString() must not throw an exception, caught TypeError: Return value of phpDocumentor\Reflection\DocBlock\Description::render() must be of the type string, bool returned in phar://C:/path/to/phars/phpDocumentor-3.0.0-alpha4d.phar/src/phpDocumentor/Descriptor/Builder/Reflector/AssemblerAbstract.php on line 0
01:13:33 CRITICAL [php] Fatal Error: Method phpDocumentor\Reflection\DocBlock\Description::__toString() must not throw an exception, caught TypeError: Return value of phpDocumentor\Reflection\DocBlock\Description::render() must be of the type string, bool returned ["exception" => Symfony\Component\ErrorHandler\Error\FatalError^ { …}]
01:13:33 CRITICAL [php] Fatal Error: Method phpDocumentor\Reflection\DocBlock\Description::__toString() must not throw an exception, caught TypeError: Return value of phpDocumentor\Reflection\DocBlock\Description::render() must be of the type string, bool returned ["exception" => Symfony\Component\ErrorHandler\Error\FatalError^ { …}]
In AssemblerAbstract.php line n/a:
Error: Method phpDocumentor\Reflection\DocBlock\Description::__toString() must not throw an exception, caught TypeError: Return value of phpDocumentor\
Reflection\DocBlock\Description::render() must be of the type string, bool returned
project:run [-t|--target [TARGET]] [--cache-folder [CACHE-FOLDER]] [-f|--filename [FILENAME]] [-d|--directory [DIRECTORY]] [--encoding [ENCODING]] [--extensions [EXTENSIONS]] [-i|--ignore [IGNORE]] [--ignore-tags [IGNORE-TAGS]] [--hidden] [--ignore-symlinks] [-m|--markers [MARKERS]] [--title [TITLE]] [--force] [--validate] [--visibility [VISIBILITY]] [--defaultpackagename [DEFAULTPACKAGENAME]] [--sourcecode] [--template [TEMPLATE]] [--parseprivate] [-h|--help] [-q|--quiet] [-v|vv|vvv|--verbose] [-V|--version] [--ansi] [--no-ansi] [-n|--no-interaction] [-c|--config [CONFIG]] [--log [LOG]] [-e|--env ENV] [--no-debug] [--] <command>
Exit code is 255
Edit: running over the other project with the git clone install gives the same results without any additional debug information.
jrfnl
on 11 Jan 2020
so no class hierarchy chart
This is because phpDocumentor was unable to locate the GraphViz application (indicated by the error Unable to find thedotcommand of the GraphViz package. Is GraphViz correctly installed and present in your path); phpDocumentor does not break on this as it is considered an inconvenience but not breaking to the documentation
mvriel
on 11 Jan 2020
The first reported issue seems to be solved now. That's good news.
I will go through all other reports in this issue and create new issues to make them more traceable. Because there is some very good feedback here I surely want to address. But not in this specific issue.
jaapio
on 11 Jan 2020
I may have said this before but I feel it deserves saying again: I am very grateful for the help that we have received in this issue and all your patience.
Making a project like this truly cross-platform is a difficult task and though we try to automate the verification on all platforms, we clearly have some work left to improve this.
Your tests and knowledge contribute to the stability of this project and I am very grateful for that.
mvriel
on 11 Jan 2020
I added a number of new issues that I extracted from this issue. I think this one is ready to be closed.
Thanks again for all the patience and useful input. Contributing to a project is so much more that just pushing code to a repo!
jaapio
on 11 Jan 2020
This is because phpDocumentor was unable to locate the GraphViz application (indicated by the error
Unable to find thedotcommand of the GraphViz package. Is GraphViz correctly installed and present in your path); phpDocumentor does not break on this as it is considered an inconvenience but not breaking to the documentation
I understand, except I'm not familiar with GraphViz and the Readme/install instructions contain no information on how to get it or what it even is.
Related: https://github.com/phpDocumentor/phpDocumentor/issues/2203
jrfnl
on 11 Jan 2020
The first reported issue seems to be solved now. That's good news.
I will go through all other reports in this issue and create new issues to make them more traceable. Because there is some very good feedback here I surely want to address. But not in this specific issue.
@jaapio Thanks for doing that.
jrfnl
on 11 Jan 2020
I may have said this before but I feel it deserves saying again: I am very grateful for the help that we have received in this issue and all your patience.
Making a project like this truly cross-platform is a difficult task and though we try to automate the verification on all platforms, we clearly have some work left to improve this.
Your tests and knowledge contribute to the stability of this project and I am very grateful for that.
Hear hear! Thank you @jaapio and @mvriel for working with us to get this issue solved and for your great work supporting this project.
Feel free to ping me if you need someone to run some tests on Windows for other issues at some point. Happy to help.
jrfnl
on 11 Jan 2020
The only remaining issue is that it does not create or use cache directory.
Also an interesting side effect, previous versions were creating namespace files with exact case.
I.e. AnrDaemon.html. Now it creating files with lowercase, but if remote FS is case sensitive, it leading to request failures.
I suggest using safe file replacement techniques (write to temp. name then rename) to avoid such issues.
AnrDaemon
on 12 Jan 2020
I rewrote the way caching works and, for now, the caching folder is located at: sys_get_temp_dir() . DIRECTORY_SEPARATOR . 'phpdocumentor' . DIRECTORY_SEPARATOR . 'pools'. I plan on reintroducing configurability there but am running in issues with order of boot sequences
mvriel
on 12 Jan 2020
As for the lowercase Namespaces; this behaviour had been present for some time now. I don't think it is new. As for lookup issues: we have a router in phpDocumentor that guarantees that the whole application uses the same names and case: do you have an example where you think this would go wrong?
mvriel
on 12 Jan 2020
Please create a new issue to continue this discussion. Otherwise it might get lost.
jaapio
on 12 Jan 2020
do you have an example where you think this would go wrong?
Not on new runs, but I was generating to the same directory previous version was using. Hence the issue.
AnrDaemon
on 12 Jan 2020
Related issues
o-alquimista
·
3Comments
h0gar
·
4Comments
juliushaertl
·
5Comments
giovkanata
·
5Comments
ilianiv
·
3Comments