1: <?php
  2: namespace Pharborist;
  3: 
  4: use Pharborist\Namespaces\NameNode;
  5: use Pharborist\Namespaces\NamespaceNode;
  6: use phpDocumentor\Reflection\DocBlock;
  7: 
  8: /**
  9:  * A doc comment.
 10:  */
 11: class DocCommentNode extends CommentNode {
 12:   /**
 13:    * Parsed doc block.
 14:    *
 15:    * @var DocBlock
 16:    */
 17:   private $docBlock;
 18: 
 19:   /**
 20:    * Creates a PHPDoc comment.
 21:    *
 22:    * @param string $comment
 23:    *   The comment body without asterisks, but formatted into lines.
 24:    *
 25:    * @return DocCommentNode
 26:    */
 27:   public static function create($comment) {
 28:     $comment = trim($comment);
 29:     $lines = array_map('trim', explode("\n", $comment));
 30:     $text = "/**\n";
 31:     foreach ($lines as $i => $line) {
 32:       $text .= ' * ' . $line . "\n";
 33:     }
 34:     $text .= ' */';
 35:     return new DocCommentNode(T_DOC_COMMENT, $text);
 36:   }
 37: 
 38:   /**
 39:    * Set indent for document comment.
 40:    *
 41:    * @param string $indent
 42:    *   Whitespace to use as indent.
 43:    * @return $this
 44:    */
 45:   public function setIndent($indent) {
 46:     $lines = explode("\n", $this->text);
 47:     if (count($lines) === 1) {
 48:       return $this;
 49:     }
 50:     $comment = '';
 51:     $last_index = count($lines) - 1;
 52:     foreach ($lines as $i => $line) {
 53:       if ($i === 0) {
 54:         $comment .= trim($line) . "\n";
 55:       }
 56:       elseif ($i === $last_index) {
 57:         $comment .= $indent . ' ' . trim($line);
 58:       }
 59:       else {
 60:         $comment .= $indent . ' ' . trim($line) . "\n";
 61:       }
 62:     }
 63:     $this->setText($comment);
 64:     return $this;
 65:   }
 66: 
 67:   public function setText($text) {
 68:     parent::setText($text);
 69:     $this->docBlock = NULL;
 70:   }
 71: 
 72:   /**
 73:    * Return the parsed doc comment.
 74:    *
 75:    * @return DocBlock
 76:    *   Parsed doc comment.
 77:    */
 78:   public function getDocBlock() {
 79:     if ($this->docBlock === NULL) {
 80:       $namespace = '\\';
 81:       $aliases = array();
 82:       /** @var NamespaceNode $namespace_node */
 83:       $namespace_node = $this->closest(Filter::isInstanceOf('\Pharborist\Namespaces\NamespaceNode'));
 84:       if ($namespace_node !== NULL) {
 85:         $namespace = $namespace_node->getName()->getAbsolutePath();
 86:         $aliases = $namespace_node->getClassAliases();
 87:       } else {
 88:         /** @var RootNode $root_node */
 89:         $root_node = $this->closest(Filter::isInstanceOf('\Pharborist\RootNode'));
 90:         if ($root_node !== NULL) {
 91:           $aliases = $root_node->getClassAliases();
 92:         }
 93:       }
 94:       $context = new DocBlock\Context($namespace, $aliases);
 95:       $this->docBlock = new DocBlock($this->text, $context);
 96:     }
 97:     return $this->docBlock;
 98:   }
 99: 
100:   /**
101:    * Get the opening line or also known as short description.
102:    *
103:    * @return string
104:    *   Short description.
105:    */
106:   public function getShortDescription() {
107:     return $this->getDocBlock()->getShortDescription();
108:   }
109: 
110:   /**
111:    * Get the full description or also known as long description.
112:    *
113:    * @return string.
114:    *   Long description.
115:    */
116:   public function getLongDescription() {
117:     return (string) $this->getDocBlock()->getLongDescription();
118:   }
119: 
120:   /**
121:    * Get the return tag.
122:    *
123:    * @return DocBlock\Tag\ReturnTag
124:    *   Return tag.
125:    */
126:   public function getReturn() {
127:     $return_tags = $this->getDocBlock()->getTagsByName('return');
128:     return end($return_tags);
129:   }
130: 
131:   /**
132:    * Get the parameter tags.
133:    *
134:    * @return DocBlock\Tag\ParamTag[]
135:    *   Array of parameter tags.
136:    */
137:   public function getParameters() {
138:     return $this->getDocBlock()->getTagsByName('param');
139:   }
140: 
141:   /**
142:    * Get the parameter tags by name.
143:    *
144:    * @return DocBlock\Tag\ParamTag[]
145:    *   Associative array of parameter names to parameters.
146:    */
147:   public function getParametersByName() {
148:     $param_tags = $this->getDocBlock()->getTagsByName('param');
149:     $parameters = array();
150:     /** @var \phpDocumentor\Reflection\DocBlock\Tag\ParamTag $param_tag */
151:     foreach ($param_tags as $param_tag) {
152:       $name = $param_tag->getVariableName();
153:       $parameters[$name] = $param_tag;
154:     }
155:     return $parameters;
156:   }
157: 
158:   /**
159:    * Get a parameter tag.
160:    *
161:    * @param $parameterName
162:    *   Name of parameter to get tag for.
163:    *
164:    * @return null|DocBlock\Tag\ParamTag
165:    *   The tag for parameter.
166:    */
167:   public function getParameter($parameterName) {
168:     $param_tags = $this->getDocBlock()->getTagsByName('param');
169:     /** @var \phpDocumentor\Reflection\DocBlock\Tag\ParamTag $param_tag */
170:     foreach ($param_tags as $param_tag) {
171:       if ($param_tag->getVariableName() === $parameterName) {
172:         return $param_tag;
173:       }
174:     }
175:     return NULL;
176:   }
177: }
178: