parsing PHP Doc Commenti in una struttura dati

Question

sto utilizzando l'API Reflection in PHP per tirare un (PHPDoc) stringa DocComment da un metodo

$r = new ReflectionMethod($object); 
$comment = $r->getDocComment(); 

Ciò restituirà una stringa che sembra qualcosa di simile (a seconda sul modo in cui il metodo è stato documentato)

/** 
* Does this great things 
* 
* @param string $thing 
* @return Some_Great_Thing 
*/ 

ci sono metodi o funzioni built-in che può analizzare un commento di stringa PHP Doc in una struttura di dati?

$object = some_magic_function_or_method($comment_string); 

echo 'Returns a: ', $object->return; 

In mancanza di questo, quale parte del PHPDoc source code dovrei esaminare al fare da solo.

Mancanza e/o in aggiunta a ciò, c'è codice di terze parti che è considerato "migliore" a questo che il codice PHPDoc?

Mi rendo conto che l'analisi di queste stringhe non è scienza missilistica, o addirittura informatica, ma preferirei una libreria/routine/metodo ben collaudata che è stata costruita per gestire un sacco di janky, semi-non corretto Codice PHP che potrebbe esistere in natura.

Answer 1

Sono sorpreso che questo non è stato ancora menzionato: per quanto riguarda l'utilizzo di Zend_Reflection di Zend Framework? Questo può tornare utile specialmente se si lavora con un software basato su Zend Framework come Magento.

Vedere lo Zend Framework Manual per alcuni esempi di codice e lo API Documentation per i metodi disponibili.

Ci sono diversi modi per farlo:

• passare un nome di file per Zend_Reflection_File.
• Passa un oggetto a Zend_Reflection_Class.
• Passa un oggetto e un nome di metodo a Zend_Reflection_Method.
• Se si dispone solo della stringa di commenti, è anche possibile riunire il codice per una piccola classe dummy, salvarlo in un file temporaneo e passare tale file in Zend_Reflection_File.

Andiamo per il caso semplice e assumiamo che tu abbia una classe esistente che vuoi ispezionare.

Il codice dovrebbe essere simile a questo (non testato, ti prego perdonami):

$method = new Zend_Reflection_Method($class, 'yourMethod'); 
$docblock = $method->getDocBlock(); 

if ($docBlock->hasTag('return')) { 
    $tagReturn = $docBlock->getTag('return'); // $tagReturn is an instance of Zend_Reflection_Docblock_Tag_Return 
    echo "Returns a: " . $tagReturn->getType() . "<br>"; 
    echo "Comment for return type: " . $tagReturn->getDescription(); 
} 

Answer 2

Dalla tua descrizione Posso solo sospettare ciò che stai cercando di fare (documentazione del codice PHP). Dato che non dichiari perché stai cercando di farlo, posso solo speculare.

Forse dovresti provare un altro approccio. Per documentare il codice PHP (se è quello che stai provando) userei Doxygen e dall'aspetto del tuo commento sul codice, è già formattato per doxygen.

Con Graphviz, Doxygen esegue anche rendering di diagrammi di classe e alberi di chiamata.

Answer 3

È sempre possibile visualizzare la sorgente da phpDoc. Il codice è sotto LGPL, quindi se decidi di copiarlo dovrai concedere in licenza il tuo software con la stessa licenza E aggiungere correttamente le notifiche corrette.

MODIFICA: a meno che, come @ Samuel Herzog, abbia notato che lo si utilizza come libreria.

Grazie a @ Samuel Herzog per il chiarimento.

Answer 4

Partenza

http://pecl.php.net/package/docblock

La funzione docblock_tokenize() si arriva part-strada lì, credo.

Answer 5

È possibile utilizzare DocBlox (http://github.com/mvriel/docblox) per generare una struttura di dati XML per l'utente; è possibile installare DocBlox utilizzando PEAR e quindi eseguire il comando:

docblox parse -d [FOLDER] -t [TARGET_LOCATION] 

Questo genererà un file chiamato structure.xml che contiene tutti i meta-dati circa il vostro codice sorgente, tra cui docblocks analizzati.

O

Offriamo le DocBlox_Reflection_DocBlock* classi per analizzare direttamente un pezzo di testo DocBlock.

Questo si può fare per fare in modo che avete caricamento automatico abilitato (o includere tutti DocBlox_Reflection_DocBlock * file) ed eseguire il seguente:

$parsed = new DocBlox_Reflection_DocBlock($docblock); 

In seguito è possibile utilizzare la getters per estrarre le informazioni che si desidera.

Nota: non è necessario rimuovere gli asterischi; la classe Reflection si prende cura di questo.

Answer 6

Se stai cercando di leggere i tag @ e i loro valori, usare preg_match sarebbe la soluzione migliore.

Answer 7

È possibile utilizzare il "DocBlockParser" classe dalla Fabien PotencierSami ("Yet Another PHP API Generatore di documentazione") progetto open-source.
Prima di tutto, prendi Sami dal GitHub.
Questo è un esempio di come usarlo:

<?php 

require_once 'Sami/Parser/DocBlockParser.php'; 
require_once 'Sami/Parser/Node/DocBlockNode.php'; 

class TestClass { 
    /** 
    * This is the short description. 
    * 
    * This is the 1st line of the long description 
    * This is the 2nd line of the long description 
    * This is the 3rd line of the long description 
    * 
    * @param bool|string $foo sometimes a boolean, sometimes a string (or, could have just used "mixed") 
    * @param bool|int $bar sometimes a boolean, sometimes an int (again, could have just used "mixed") 
    * @return string de-html_entitied string (no entities at all) 
    */ 
    public function another_test($foo, $bar) { 
     return strtr($foo,array_flip(get_html_translation_table(HTML_ENTITIES))); 
    } 
} 

use Sami\Parser\DocBlockParser; 
use Sami\Parser\Node\DocBlockNode; 

try { 
    $method = new ReflectionMethod('TestClass', 'another_test'); 
    $comment = $method->getDocComment(); 
    if ($comment !== FALSE) { 
     $dbp = new DocBlockParser(); 
     $doc = $dbp->parse($comment); 
     echo "\n** getDesc:\n"; 
     print_r($doc->getDesc()); 
     echo "\n** getTags:\n"; 
     print_r($doc->getTags()); 
     echo "\n** getTag('param'):\n"; 
     print_r($doc->getTag('param')); 
     echo "\n** getErrors:\n"; 
     print_r($doc->getErrors()); 
     echo "\n** getOtherTags:\n"; 
     print_r($doc->getOtherTags()); 
     echo "\n** getShortDesc:\n"; 
     print_r($doc->getShortDesc()); 
     echo "\n** getLongDesc:\n"; 
     print_r($doc->getLongDesc()); 
    } 
} catch (Exception $e) { 
    print_r($e); 
} 

?> 

Ed ecco l'output della pagina di prova:

** getDesc: 
This is the short description. 

This is the 1st line of the long description 
This is the 2nd line of the long description 
This is the 3rd line of the long description 
** getTags: 
Array 
(
    [param] => Array 
     (
      [0] => Array 
       (
        [0] => Array 
         (
          [0] => Array 
           (
            [0] => bool 
            [1] => 
           ) 

          [1] => Array 
           (
            [0] => string 
            [1] => 
           ) 

         ) 

        [1] => foo 
        [2] => sometimes a boolean, sometimes a string (or, could have just used "mixed") 
       ) 

      [1] => Array 
       (
        [0] => Array 
         (
          [0] => Array 
           (
            [0] => bool 
            [1] => 
           ) 

          [1] => Array 
           (
            [0] => int 
            [1] => 
           ) 

         ) 

        [1] => bar 
        [2] => sometimes a boolean, sometimes an int (again, could have just used "mixed") 
       ) 

     ) 

    [return] => Array 
     (
      [0] => Array 
       (
        [0] => Array 
         (
          [0] => Array 
           (
            [0] => string 
            [1] => 
           ) 

         ) 

        [1] => de-html_entitied string (no entities at all) 
       ) 

     ) 

) 

** getTag('param'): 
Array 
(
    [0] => Array 
     (
      [0] => Array 
       (
        [0] => Array 
         (
          [0] => bool 
          [1] => 
         ) 

        [1] => Array 
         (
          [0] => string 
          [1] => 
         ) 

       ) 

      [1] => foo 
      [2] => sometimes a boolean, sometimes a string (or, could have just used "mixed") 
     ) 

    [1] => Array 
     (
      [0] => Array 
       (
        [0] => Array 
         (
          [0] => bool 
          [1] => 
         ) 

        [1] => Array 
         (
          [0] => int 
          [1] => 
         ) 

       ) 

      [1] => bar 
      [2] => sometimes a boolean, sometimes an int (again, could have just used "mixed") 
     ) 

) 

** getErrors: 
Array 
(
) 

** getOtherTags: 
Array 
(
) 

** getShortDesc: 
This is the short description. 
** getLongDesc: 
This is the 1st line of the long description 
This is the 2nd line of the long description 
This is the 3rd line of the long description 

Answer 8

suggerisco addendum, la sua piuttosto fresco e ben vivo e utilizzato in molti framework PHP5 ...

http://code.google.com/p/addendum/

Controllare i test per gli esempi

http://code.google.com/p/addendum/source/browse/trunk#trunk%2Fannotations%2Ftests

Answer 9

vi consiglio di dare un'occhiata a http://code.google.com/p/php-annotations/

Il codice è abbastanza semplice da modificare/compresa, se necessario.

Answer 10

Come sottolineato in una delle risposte di cui sopra, è possibile utilizzare phpDocumentor. Se si utilizza il compositore, è sufficiente aggiungere "phpdocumentor/reflection-docblock": "~ 2.0" al blocco "richiesta".

Vedere questo per un esempio: https://github.com/abdulla16/decoupled-app/blob/master/composer.json

Per esempi di utilizzo, vedi: https://github.com/abdulla16/decoupled-app/blob/master/Container/Container.php