1: <?php
  2: /**
  3:  * PHP Token Reflection
  4:  *
  5:  * Version 1.3.1
  6:  *
  7:  * LICENSE
  8:  *
  9:  * This source file is subject to the new BSD license that is bundled
 10:  * with this library in the file LICENSE.
 11:  *
 12:  * @author Ondřej Nešpor
 13:  * @author Jaroslav Hanslík
 14:  */
 15: 
 16: namespace TokenReflection;
 17: 
 18: use TokenReflection\Exception, TokenReflection\Stream\StreamBase as Stream;
 19: 
 20: /**
 21:  * Basic class for reflection elements.
 22:  *
 23:  * Defines a variety of common methods. All reflections are descendants of this class.
 24:  */
 25: abstract class ReflectionElement extends ReflectionBase
 26: {
 27:     /**
 28:      * Docblock template start.
 29:      *
 30:      * @var string
 31:      */
 32:     const DOCBLOCK_TEMPLATE_START = '/**#@+';
 33: 
 34:     /**
 35:      * Docblock template end.
 36:      *
 37:      * @var string
 38:      */
 39:     const DOCBLOCK_TEMPLATE_END = '/**#@-*/';
 40: 
 41:     /**
 42:      * Class method cache.
 43:      *
 44:      * @var array
 45:      */
 46:     private static $methodCache = array();
 47: 
 48:     /**
 49:      * Filename with reflection subject definition.
 50:      *
 51:      * @var string
 52:      */
 53:     private $fileName;
 54: 
 55:     /**
 56:      * Start line in the file.
 57:      *
 58:      * @var integer
 59:      */
 60:     private $startLine;
 61: 
 62:     /**
 63:      * End line in the file.
 64:      *
 65:      * @var integer
 66:      */
 67:     private $endLine;
 68: 
 69:     /**
 70:      * Start position in the file token stream.
 71:      *
 72:      * @var integer
 73:      */
 74:     protected $startPosition;
 75: 
 76:     /**
 77:      * End position in the file token stream.
 78:      *
 79:      * @var integer
 80:      */
 81:     private $endPosition;
 82: 
 83:     /**
 84:      * Stack of actual docblock templates.
 85:      *
 86:      * @var array
 87:      */
 88:     protected $docblockTemplates = array();
 89: 
 90:     /**
 91:      * Constructor.
 92:      *
 93:      * @param \TokenReflection\Stream\StreamBase $tokenStream Token substream
 94:      * @param \TokenReflection\Broker $broker Reflection broker
 95:      * @param \TokenReflection\IReflection $parent Parent reflection object
 96:      * @throws \TokenReflection\Exception\ParseException If an empty token stream was provided
 97:      */
 98:     final public function __construct(Stream $tokenStream, Broker $broker, IReflection $parent = null)
 99:     {
100:         if (0 === $tokenStream->count()) {
101:             throw new Exception\ParseException($this, $tokenStream, 'Reflection token stream must not be empty.', Exception\ParseException::INVALID_ARGUMENT);
102:         }
103: 
104:         parent::__construct($tokenStream, $broker, $parent);
105:     }
106: 
107:     /**
108:      * Parses the token substream.
109:      *
110:      * @param \TokenReflection\Stream\StreamBase $tokenStream Token substream
111:      * @param \TokenReflection\IReflection $parent Parent reflection object
112:      */
113:     final protected function parseStream(Stream $tokenStream, IReflection $parent = null)
114:     {
115:         $this->fileName = $tokenStream->getFileName();
116: 
117:         $this
118:             ->processParent($parent, $tokenStream)
119:             ->parseStartLine($tokenStream)
120:             ->parseDocComment($tokenStream, $parent)
121:             ->parse($tokenStream, $parent)
122:             ->parseChildren($tokenStream, $parent)
123:             ->parseEndLine($tokenStream);
124:     }
125: 
126:     /**
127:      * Returns the file name the reflection object is defined in.
128:      *
129:      * @return string
130:      */
131:     public function getFileName()
132:     {
133:         return $this->fileName;
134:     }
135: 
136:     /**
137:      * Returns a file reflection.
138:      *
139:      * @return \TokenReflection\ReflectionFile
140:      * @throws \TokenReflection\Exception\RuntimeException If the file is not stored inside the broker
141:      */
142:     public function getFileReflection()
143:     {
144:         return $this->getBroker()->getFile($this->fileName);
145:     }
146: 
147:     /**
148:      * Returns the definition start line number in the file.
149:      *
150:      * @return integer
151:      */
152:     public function getStartLine()
153:     {
154:         return $this->startLine;
155:     }
156: 
157:     /**
158:      * Returns the definition end line number in the file.
159:      *
160:      * @return integer
161:      */
162:     public function getEndLine()
163:     {
164:         return $this->endLine;
165:     }
166: 
167:     /**
168:      * Returns the PHP extension reflection.
169:      *
170:      * Alwyas returns null - everything is user defined.
171:      *
172:      * @return null
173:      */
174:     public function getExtension()
175:     {
176:         return null;
177:     }
178: 
179:     /**
180:      * Returns the PHP extension name.
181:      *
182:      * Alwyas returns false - everything is user defined.
183:      *
184:      * @return boolean
185:      */
186:     public function getExtensionName()
187:     {
188:         return false;
189:     }
190: 
191:     /**
192:      * Returns the appropriate source code part.
193:      *
194:      * @return string
195:      */
196:     public function getSource()
197:     {
198:         return $this->broker->getFileTokens($this->getFileName())->getSourcePart($this->startPosition, $this->endPosition);
199:     }
200: 
201:     /**
202:      * Returns the start position in the file token stream.
203:      *
204:      * @return integer
205:      */
206:     public function getStartPosition()
207:     {
208:         return $this->startPosition;
209:     }
210: 
211:     /**
212:      * Returns the end position in the file token stream.
213:      *
214:      * @return integer
215:      */
216:     public function getEndPosition()
217:     {
218:         return $this->endPosition;
219:     }
220: 
221:     /**
222:      * Returns the stack of docblock templates.
223:      *
224:      * @return array
225:      */
226:     protected function getDocblockTemplates()
227:     {
228:         return $this->docblockTemplates;
229:     }
230: 
231:     /**
232:      * Processes the parent reflection object.
233:      *
234:      * @param \TokenReflection\Reflection $parent Parent reflection object
235:      * @param \TokenReflection\Stream\StreamBase $tokenStream Token substream
236:      * @return \TokenReflection\ReflectionElement
237:      */
238:     protected function processParent(IReflection $parent, Stream $tokenStream)
239:     {
240:         // To be defined in child classes
241:         return $this;
242:     }
243: 
244:     /**
245:      * Find the appropriate docblock.
246:      *
247:      * @param \TokenReflection\Stream\StreamBase $tokenStream Token substream
248:      * @param \TokenReflection\IReflection $parent Parent reflection
249:      * @return \TokenReflection\ReflectionElement
250:      */
251:     protected function parseDocComment(Stream $tokenStream, IReflection $parent)
252:     {
253:         if ($this instanceof ReflectionParameter) {
254:             $this->docComment = new ReflectionAnnotation($this);
255:             return $this;
256:         }
257: 
258:         $position = $tokenStream->key();
259: 
260:         if ($tokenStream->is(T_DOC_COMMENT, $position - 1)) {
261:             $value = $tokenStream->getTokenValue($position - 1);
262:             if (self::DOCBLOCK_TEMPLATE_END !== $value) {
263:                 $this->docComment = new ReflectionAnnotation($this, $value);
264:                 $this->startPosition--;
265:             }
266:         } elseif ($tokenStream->is(T_DOC_COMMENT, $position - 2)) {
267:             $value = $tokenStream->getTokenValue($position - 2);
268:             if (self::DOCBLOCK_TEMPLATE_END !== $value) {
269:                 $this->docComment = new ReflectionAnnotation($this, $value);
270:                 $this->startPosition -= 2;
271:             }
272:         } elseif ($tokenStream->is(T_COMMENT, $position - 1) && preg_match('~^' . preg_quote(self::DOCBLOCK_TEMPLATE_START, '~') . '~', $tokenStream->getTokenValue($position - 1))) {
273:             $this->docComment = new ReflectionAnnotation($this, $tokenStream->getTokenValue($position - 1));
274:             $this->startPosition--;
275:         } elseif ($tokenStream->is(T_COMMENT, $position - 2) && preg_match('~^' . preg_quote(self::DOCBLOCK_TEMPLATE_START, '~') . '~', $tokenStream->getTokenValue($position - 2))) {
276:             $this->docComment = new ReflectionAnnotation($this, $tokenStream->getTokenValue($position - 2));
277:             $this->startPosition -= 2;
278:         }
279: 
280:         if (null === $this->docComment) {
281:             $this->docComment = new ReflectionAnnotation($this);
282:         }
283: 
284:         if ($parent instanceof ReflectionElement) {
285:             $this->docComment->setTemplates($parent->getDocblockTemplates());
286:         }
287: 
288:         return $this;
289:     }
290: 
291:     /**
292:      * Saves the start line number.
293:      *
294:      * @param \TokenReflection\Stream\StreamBase $tokenStream Token susbtream
295:      * @return \TokenReflection\ReflectionElement
296:      */
297:     private final function parseStartLine(Stream $tokenStream)
298:     {
299:         $token = $tokenStream->current();
300:         $this->startLine = $token[2];
301: 
302:         $this->startPosition = $tokenStream->key();
303: 
304:         return $this;
305:     }
306: 
307:     /**
308:      * Saves the end line number.
309:      *
310:      * @param \TokenReflection\Stream\StreamBase $tokenStream Token susbtream
311:      * @return \TokenReflection\ReflectionElement
312:      */
313:     private final function parseEndLine(Stream $tokenStream)
314:     {
315:         $token = $tokenStream->current();
316:         $this->endLine = $token[2];
317: 
318:         $this->endPosition = $tokenStream->key();
319: 
320:         return $this;
321:     }
322: 
323:     /**
324:      * Parses reflected element metadata from the token stream.
325:      *
326:      * @param \TokenReflection\Stream\StreamBase $tokenStream Token substream
327:      * @param \TokenReflection\IReflection $parent Parent reflection object
328:      * @return \TokenReflection\ReflectionElement
329:      */
330:     abstract protected function parse(Stream $tokenStream, IReflection $parent);
331: 
332:     /**
333:      * Parses the reflection object name.
334:      *
335:      * @param \TokenReflection\Stream\StreamBase $tokenStream Token substream
336:      * @return \TokenReflection\ReflectionElement
337:      */
338:     abstract protected function parseName(Stream $tokenStream);
339: 
340:     /**
341:      * Parses child reflection objects from the token stream.
342:      *
343:      * @param \TokenReflection\Stream\StreamBase $tokenStream Token substream
344:      * @param \TokenReflection\Reflection $parent Parent reflection object
345:      * @return \TokenReflection\ReflectionElement
346:      */
347:     protected function parseChildren(Stream $tokenStream, IReflection $parent)
348:     {
349:         // To be defined in child classes
350:         return $this;
351:     }
352: }
353: