File Name too long error

[jasonwatt]

The Issue
File names can have multiple lines and be too long to write to, causing documentation to be incomplete

What it should do
Parse the first line of the package tag AND truncate the max length OR
remove newlines AND truncate the max length OR
throw an exception to stop the program since the documentation will be incomplete.

Details
I get a warning when a description is below the @Package tag. This is an error with the description. and not the focus of this ticket.

Rather, the file put should be checking for a single line for a filename, and should ensure this dosnt occur by either parsing the filename to a single line, or throwing an exception so the process stops since this is obviously an error that will break the documentation.

Since the file was not written, this package is now missing from the documentation as a detailed page.

Warning Output:

PHP Warning:  file_put_contents(/Users/jason/phpdocs/docs_phalcon/packages/RiccaGroup.Pagination
This class will take a large array of data and calculate if the data needs to be chunked into pages
The data passed in is being used as reference in order to cut down on memory usage
Example Use
$page->setData($records);
if ($page->check(Config::MAX.RETURN.SIZE)) {
 $cache =& .RiccaAPI.Components.Cache::memcache();
 $page->setCache($cache);
 $sendData = $page->paginate(Config::MAX.RETURN.SIZE);
}.html): failed to open stream: File name too long in /Users/jason/phpdocs/phpDocumentor2-develop/src/phpDocumentor/Plugin/Core/Transformer/Writer/Twig.php on line 115
PHP Stack trace:
PHP   1. {main}() /Users/jason/phpdocs/phpDocumentor2-develop/bin/phpdoc.php:0
PHP   2. phpDocumentor\Application->run() /Users/jason/phpdocs/phpDocumentor2-develop/bin/phpdoc.php:32
PHP   3. Symfony\Component\Console\Application->run() /Users/jason/phpdocs/phpDocumentor2-develop/src/phpDocumentor/Application.php:351
PHP   4. Symfony\Component\Console\Application->doRun() /Users/jason/phpdocs/phpDocumentor2-develop/vendor/symfony/console/Symfony/Component/Console/Application.php:121
PHP   5. Symfony\Component\Console\Application->doRunCommand() /Users/jason/phpdocs/phpDocumentor2-develop/vendor/symfony/console/Symfony/Component/Console/Application.php:191
PHP   6. Symfony\Component\Console\Command\Command->run() /Users/jason/phpdocs/phpDocumentor2-develop/vendor/symfony/console/Symfony/Component/Console/Application.php:881
PHP   7. phpDocumentor\Command\Project\RunCommand->execute() /Users/jason/phpdocs/phpDocumentor2-develop/vendor/symfony/console/Symfony/Component/Console/Command/Command.php:241
PHP   8. Symfony\Component\Console\Command\Command->run() /Users/jason/phpdocs/phpDocumentor2-develop/src/phpDocumentor/Command/Project/RunCommand.php:268
PHP   9. phpDocumentor\Transformer\Command\Project\TransformCommand->execute() /Users/jason/phpdocs/phpDocumentor2-develop/vendor/symfony/console/Symfony/Component/Console/Command/Command.php:241
PHP  10. phpDocumentor\Console\Output\Output->writeTimedLog() /Users/jason/phpdocs/phpDocumentor2-develop/src/phpDocumentor/Transformer/Command/Project/TransformCommand.php:197
PHP  11. call_user_func_array() /Users/jason/phpdocs/phpDocumentor2-develop/src/phpDocumentor/Console/Output/Output.php:56
PHP  12. phpDocumentor\Transformer\Transformer->execute() /Users/jason/phpdocs/phpDocumentor2-develop/src/phpDocumentor/Console/Output/Output.php:56
PHP  13. phpDocumentor\Plugin\Core\Transformer\Writer\Twig->transform() /Users/jason/phpdocs/phpDocumentor2-develop/src/phpDocumentor/Transformer/Transformer.php:178
PHP  14. file_put_contents() /Users/jason/phpdocs/phpDocumentor2-develop/src/phpDocumentor/Plugin/Core/Transformer/Writer/Twig.php:115
 16/16 [============================] 100%   1.857s find the `dot` command of the GraphViz package. Is GraphViz correctly installed and present in your path?
Analyze results and write report to log                            ..    0.001s

[mvriel]

Can you show me an example of a DocBlock causing this issue? Due to the description of your issue I get the feeling that the order of the elements in your DocBlocks are incorrect (the expected order is always Summary -> Description -> Tags).

If a long piece of text, such as a description follows the @package tag than that will be seen as part of that tag since all tags support multiple lines.

[jasonwatt]

This is essentially what is happening. the description is below the package tag. I feel like even with that user error there should be some safe fail so that it doesn't kill the file creation if that name is too long. You could get to an issue where the file path of there php is running, + a really long namespace tree could cause this error as well (as unlikely as it is)

/**
* @ package test/test
* 
* some long description here that breaks the file creation
* 
**/

[mvriel]

I have marked this issue as an improvement since I agree with you that it is good form to be defensive and prevent these kind of issues as much as possible.

[jaapio]

This issue is more than 10 years old. phpDocumentor has been changed a lot. If this is still an issue for anyone please open a new issue.