10

I'm looking for some method of converting a PHP Docblock (as used for generating documentation by tools like Doxygen) into a structure I can inspect in PHP.

For example, I want to parse

/**
 * Multiply two values
 * @CHECKME
 *
 * @author someone
 * @created eons ago
 *
 * @param integer $x
 * @param integer $x
 *
 * @return integer
 */
function multiply($x, $y)
{
    return $x * $y;
}

into something similar to:

array(
     'author'  => 'someone'
    ,'created' => 'eons ago'
    ,'param'   => array(
                      'integer $x'
                     ,'integer $y'
                  )
    ,'_flags'  => array(
                     '@CHECKME'
                  )
);

I explicitly cannot use PEAR or any such library, it has to be relatively standalone. Any given solution that is better than using a bunch of regular expressions after stripping away comment outline would be awesome.

Peter Mortensen
  • 30,738
  • 21
  • 105
  • 131
Kris
  • 40,604
  • 9
  • 72
  • 101
  • 1
    possible duplicate of [Are there any php docblock parser tools available?](http://stackoverflow.com/questions/2531085/are-there-any-php-docblock-parser-tools-available) – Gordon Jan 30 '11 at 21:43
  • 1
    @Gordon. Not a duplicate, I was not looking to merely generate a bunch of static documentation files but to provide enhanced reflection at runtime. Generating documentation is an extra benefit. – Kris May 02 '12 at 10:46
  • possible duplicate of [Parsing PHP Doc comments into a data structure](http://stackoverflow.com/questions/4702356/parsing-php-doc-comments-into-a-data-structure) – Gordon May 02 '12 at 11:04
  • and a couple more in the Related section to the right. – Gordon May 02 '12 at 11:04
  • @Gordon, Look again, that's a newer question. As are the ones to the right that are actually similar that I just checked. I _did_ actually use search before I posted. – Kris May 02 '12 at 11:54
  • I didnt say you didnt search. Also, even if they are newer they have answers you might want to look at. However, I still fail to see why my answer in the first dup (which is an older one) doesnt answer your question anyway since it recommends using the Reflection API which can reflect on Docblocks at runtime, which is what you are asking for, isnt it? – Gordon May 02 '12 at 13:07
  • The reflection API only gives me the entire docblock as a string, i needed to "punchcard" certain details out of that string. the Reflection API has nothing (documented at least) that can do that. Which I believe to be clearly stated in the question. – Kris May 02 '12 at 14:20
  • so something like https://code.google.com/p/addendum/ ? – Gordon May 02 '12 at 14:33
  • let us [continue this discussion in chat](http://chat.stackoverflow.com/rooms/10827/discussion-between-kris-and-gordon) – Kris May 03 '12 at 07:43
  • Hi, man. Did you found the way to parse those docblocks? – Jazi Sep 19 '13 at 13:07
  • @KrzysztofTrzos: yes, but unfortunately by parsing it manually with a handful of regular expressions. – Kris Sep 19 '13 at 13:23
  • Can You share it somehow? I'm searching a solution for this problem for more than a few hours... – Jazi Sep 19 '13 at 13:26
  • @KrzysztofTrzos: Sorry, I legally cannot at this time. – Kris Sep 19 '13 at 18:53
  • In 2022 there is maintainer and working AST PHP doc parser: https://github.com/phpstan/phpdoc-parser It makes PHPStan running. State of the art – Tomas Votruba Jun 10 '22 at 18:55

4 Answers4

0

I wonder if you couldn't just use the phpdocumentor classes. They already parse the data. I suspect you could write your own interim parser to process a file but then handle the raw objects in any way you want.

allnightgrocery
  • 1,370
  • 1
  • 8
  • 15
  • I've been unable to get into any source for phpDocumentor for the last couple hours, but my assumptions based on the website/faq are that it is php4 code that depends on PEAR (need PEAR to install it). Using it would not be less work than writing it myself by the look of things. (I could be wrong, unable to verify atm) – Kris Jun 09 '10 at 22:30
  • The classes are available as *.inc files within the phpDocumentor directory upon download. I'm not sure if you saw that or not. – allnightgrocery Jun 09 '10 at 23:19
  • Yes I did but by the time I have familiarized mysql with the old fashioned style and structure I can have written my own implementation that follows my actual spec and i'd still have to re-qrite the php4 code by that time. Standalone != complete project – Kris Jun 10 '10 at 04:53
0

Look at using the Reflection class [1] as a starting point, particularly its getDocComment() method [2]. Also, Matthew's blog post about his foray into using it [3] may provide further insights.

[1] -- http://www.php.net/manual/en/class.reflectionclass.php

[2] -- http://www.php.net/manual/en/reflectionclass.getdoccomment.php

[3] -- http://mwop.net/blog/125-PHP-5s-Reflection-API

ashnazg
  • 6,558
  • 2
  • 32
  • 39
  • That's always been how I got the doccomment, I was looking for some way to parse annotations from it that would fit in with my existing codebase. – Kris Feb 23 '12 at 23:07
  • Unfortunately it requires you to actually include the file where the docblocks are contained. – Szczepan Hołyszewski Sep 02 '15 at 11:21
-1

PHPDocumentor IS a standalone docblock parser.

powtac
  • 40,542
  • 28
  • 115
  • 170
  • I just downloaded a zip and looked at the source, but phpDocumentors code is terrible for my use case. It will take days to rework that instead of hours to roll my own. I need one or two classes, not an intermingled project with dependencies all over the place, and certainly no php4 code. I might be able to glean something from it if i run something through it in an xdebug session, but after seeing the code I still think its unusable. – Kris Jun 09 '10 at 22:42
-1

I have written a runtime PHP documentation utility that contains a PHPDoc parser class (Doqumentor). I would think this will do what you want if you want to take a look. It is also available on github if you have any improvements or bug fixes.