1: <?php
  2: /**
  3:  * Mockery
  4:  *
  5:  * LICENSE
  6:  *
  7:  * This source file is subject to the new BSD license that is bundled
  8:  * with this package in the file LICENSE.txt.
  9:  * It is also available through the world-wide-web at this URL:
 10:  * http://github.com/padraic/mockery/blob/master/LICENSE
 11:  * If you did not receive a copy of the license and are unable to
 12:  * obtain it through the world-wide-web, please send an email
 13:  * to padraic@php.net so we can send you a copy immediately.
 14:  *
 15:  * @category   Mockery
 16:  * @package    Mockery
 17:  * @copyright  Copyright (c) 2010-2014 Pádraic Brady (http://blog.astrumfutura.com)
 18:  * @license    http://github.com/padraic/mockery/blob/master/LICENSE New BSD License
 19:  */
 20: 
 21: namespace Mockery;
 22: 
 23: class Expectation implements ExpectationInterface
 24: {
 25: 
 26:     /**
 27:      * Mock object to which this expectation belongs
 28:      *
 29:      * @var object
 30:      */
 31:     protected $_mock = null;
 32: 
 33:     /**
 34:      * Method name
 35:      *
 36:      * @var string
 37:      */
 38:     protected $_name = null;
 39: 
 40:     /**
 41:      * Arguments expected by this expectation
 42:      *
 43:      * @var array
 44:      */
 45:     protected $_expectedArgs = array();
 46: 
 47:     /**
 48:      * Count validator store
 49:      *
 50:      * @var array
 51:      */
 52:     protected $_countValidators = array();
 53: 
 54:     /**
 55:      * The count validator class to use
 56:      *
 57:      * @var string
 58:      */
 59:     protected $_countValidatorClass = 'Mockery\CountValidator\Exact';
 60: 
 61:     /**
 62:      * Actual count of calls to this expectation
 63:      *
 64:      * @var int
 65:      */
 66:     protected $_actualCount = 0;
 67: 
 68:     /**
 69:      * Value to return from this expectation
 70:      *
 71:      * @var mixed
 72:      */
 73:     protected $_returnValue = null;
 74: 
 75:     /**
 76:      * Array of return values as a queue for multiple return sequence
 77:      *
 78:      * @var array
 79:      */
 80:     protected $_returnQueue = array();
 81: 
 82:     /**
 83:      * Array of closures executed with given arguments to generate a result
 84:      * to be returned
 85:      *
 86:      * @var array
 87:      */
 88:     protected $_closureQueue = array();
 89: 
 90:     /**
 91:      * Array of values to be set when this expectation matches
 92:      *
 93:      * @var array
 94:      */
 95:     protected $_setQueue = array();
 96: 
 97:     /**
 98:      * Integer representing the call order of this expectation
 99:      *
100:      * @var int
101:      */
102:     protected $_orderNumber = null;
103: 
104:     /**
105:      * Integer representing the call order of this expectation on a global basis
106:      *
107:      * @var int
108:      */
109:     protected $_globalOrderNumber = null;
110: 
111:     /**
112:      * Flag indicating that an exception is expected to be throw (not returned)
113:      *
114:      * @var bool
115:      */
116:     protected $_throw = false;
117: 
118:     /**
119:      * Flag indicating whether the order of calling is determined locally or
120:      * globally
121:      *
122:      * @var bool
123:      */
124:     protected $_globally = false;
125: 
126:     /**
127:      * Flag indicating we expect no arguments
128:      *
129:      * @var bool
130:      */
131:     protected $_noArgsExpectation = false;
132: 
133:     /**
134:      * Flag indicating if the return value should be obtained from the original
135:      * class method instead of returning predefined values from the return queue
136:      *
137:      * @var bool
138:      */
139:     protected $_passthru = false;
140: 
141:     /**
142:      * Constructor
143:      *
144:      * @param \Mockery\MockInterface $mock
145:      * @param string $name
146:      */
147:     public function __construct(\Mockery\MockInterface $mock, $name)
148:     {
149:         $this->_mock = $mock;
150:         $this->_name = $name;
151:     }
152: 
153:     /**
154:      * Return a string with the method name and arguments formatted
155:      *
156:      * @param string $name Name of the expected method
157:      * @param array $args List of arguments to the method
158:      * @return string
159:      */
160:     public function __toString()
161:     {
162:         return \Mockery::formatArgs($this->_name, $this->_expectedArgs);
163:     }
164: 
165:     /**
166:      * Verify the current call, i.e. that the given arguments match those
167:      * of this expectation
168:      *
169:      * @param array $args
170:      * @return mixed
171:      */
172:     public function verifyCall(array $args)
173:     {
174:         $this->validateOrder();
175:         $this->_actualCount++;
176:         if (true === $this->_passthru) {
177:             return $this->_mock->mockery_callSubjectMethod($this->_name, $args);
178:         }
179:         $return = $this->_getReturnValue($args);
180:         if ($return instanceof \Exception && $this->_throw === true) {
181:             throw $return;
182:         }
183:         $this->_setValues();
184:         return $return;
185:     }
186: 
187:     /**
188:      * Sets public properties with queued values to the mock object
189:      *
190:      * @param array $args
191:      * @return mixed
192:      */
193:     protected function _setValues()
194:     {
195:         foreach ($this->_setQueue as $name => &$values) {
196:             if (count($values) > 0) {
197:                 $value = array_shift($values);
198:                 $this->_mock->{$name} = $value;
199:             }
200:         }
201:     }
202: 
203:     /**
204:      * Fetch the return value for the matching args
205:      *
206:      * @param array $args
207:      * @return mixed
208:      */
209:     protected function _getReturnValue(array $args)
210:     {
211:         if (count($this->_closureQueue) > 1) {
212:             return call_user_func_array(array_shift($this->_closureQueue), $args);
213:         } elseif (count($this->_closureQueue) > 0) {
214:             return call_user_func_array(current($this->_closureQueue), $args);
215:         } elseif (count($this->_returnQueue) > 1) {
216:             return array_shift($this->_returnQueue);
217:         } elseif (count($this->_returnQueue) > 0) {
218:             return current($this->_returnQueue);
219:         }
220:     }
221: 
222:     /**
223:      * Checks if this expectation is eligible for additional calls
224:      *
225:      * @return bool
226:      */
227:     public function isEligible()
228:     {
229:         foreach ($this->_countValidators as $validator) {
230:             if (!$validator->isEligible($this->_actualCount)) {
231:                 return false;
232:             }
233:         }
234:         return true;
235:     }
236: 
237:     /**
238:      * Check if there is a constraint on call count
239:      *
240:      * @return bool
241:      */
242:     public function isCallCountConstrained()
243:     {
244:         return (count($this->_countValidators) > 0);
245:     }
246: 
247:     /**
248:      * Verify call order
249:      *
250:      * @return void
251:      */
252:     public function validateOrder()
253:     {
254:         if ($this->_orderNumber) {
255:             $this->_mock->mockery_validateOrder((string) $this, $this->_orderNumber, $this->_mock);
256:         }
257:         if ($this->_globalOrderNumber) {
258:             $this->_mock->mockery_getContainer()
259:                 ->mockery_validateOrder((string) $this, $this->_globalOrderNumber, $this->_mock);
260:         }
261:     }
262: 
263:     /**
264:      * Verify this expectation
265:      *
266:      * @return bool
267:      */
268:     public function verify()
269:     {
270:         foreach ($this->_countValidators as $validator) {
271:             $validator->validate($this->_actualCount);
272:         }
273:     }
274: 
275:     /**
276:      * Check if passed arguments match an argument expectation
277:      *
278:      * @param array $args
279:      * @return bool
280:      */
281:     public function matchArgs(array $args)
282:     {
283:         if(empty($this->_expectedArgs) && !$this->_noArgsExpectation) {
284:             return true;
285:         }
286:         if(count($args) !== count($this->_expectedArgs)) {
287:             return false;
288:         }
289:         $argCount = count($args);
290:         for ($i=0; $i<$argCount; $i++) {
291:             $param =& $args[$i];
292:             if (!$this->_matchArg($this->_expectedArgs[$i], $param)) {
293:                 return false;
294:             }
295:         }
296: 
297:         return true;
298:     }
299: 
300:     /**
301:      * Check if passed argument matches an argument expectation
302:      *
303:      * @param array $args
304:      * @return bool
305:      */
306:     protected function _matchArg($expected, &$actual)
307:     {
308:         if ($expected === $actual) {
309:             return true;
310:         }
311:         if (!is_object($expected) && !is_object($actual) && $expected == $actual) {
312:             return true;
313:         }
314:         if (is_string($expected) && !is_array($actual) && !is_object($actual)) {
315:             # push/pop an error handler here to to make sure no error/exception thrown if $expected is not a regex
316:             set_error_handler(function () {});
317:             $result = preg_match($expected, (string) $actual);
318:             restore_error_handler();
319: 
320:             if($result) {
321:                 return true;
322:             }
323:         }
324:         if (is_string($expected) && is_object($actual)) {
325:             $result = $actual instanceof $expected;
326:             if($result) {
327:                 return true;
328:             }
329:         }
330:         if ($expected instanceof \Mockery\Matcher\MatcherAbstract) {
331:             return $expected->match($actual);
332:         }
333:         if (is_a($expected, '\Hamcrest\Matcher') || is_a($expected, '\Hamcrest_Matcher')) {
334:             return $expected->matches($actual);
335:         }
336:         return false;
337:     }
338: 
339:     /**
340:      * Expected argument setter for the expectation
341:      *
342:      * @param mixed
343:      * @return self
344:      */
345:     public function with()
346:     {
347:         return $this->withArgs(func_get_args());
348:     }
349: 
350:     /**
351:      * Expected arguments for the expectation passed as an array
352:      *
353:      * @param array $args
354:      * @return self
355:      */
356:     public function withArgs(array $args)
357:     {
358:         if (empty($args)) {
359:             return $this->withNoArgs();
360:         }
361:         $this->_expectedArgs = $args;
362:         $this->_noArgsExpectation = false;
363:         return $this;
364:     }
365: 
366:     /**
367:      * Set with() as no arguments expected
368:      *
369:      * @return self
370:      */
371:     public function withNoArgs()
372:     {
373:         $this->_noArgsExpectation = true;
374:         $this->_expectedArgs = null;
375:         return $this;
376:     }
377: 
378:     /**
379:      * Set expectation that any arguments are acceptable
380:      *
381:      * @return self
382:      */
383:     public function withAnyArgs()
384:     {
385:         $this->_expectedArgs = array();
386:         return $this;
387:     }
388: 
389:     /**
390:      * Set a return value, or sequential queue of return values
391:      *
392:      * @return self
393:      */
394:     public function andReturn()
395:     {
396:         $this->_returnQueue = func_get_args();
397:         return $this;
398:     }
399: 
400:     /**
401:      * Return this mock, like a fluent interface
402:      *
403:      * @return self
404:      */
405:     public function andReturnSelf()
406:     {
407:         return $this->andReturn($this->_mock);
408:     }
409: 
410:     /**
411:      * Set a sequential queue of return values with an array
412:      *
413:      * @param array $values
414:      * @return self
415:      */
416:     public function andReturnValues(array $values)
417:     {
418:         call_user_func_array(array($this, 'andReturn'), $values);
419:         return $this;
420:     }
421: 
422:     /**
423:      * Set a closure or sequence of closures with which to generate return
424:      * values. The arguments passed to the expected method are passed to the
425:      * closures as parameters.
426:      *
427:      * @return self
428:      */
429:     public function andReturnUsing()
430:     {
431:         $this->_closureQueue = func_get_args();
432:         return $this;
433:     }
434: 
435:     /**
436:      * Return a self-returning black hole object.
437:      *
438:      * @return self
439:      */
440:     public function andReturnUndefined()
441:     {
442:         $this->andReturn(new \Mockery\Undefined);
443:         return $this;
444:     }
445: 
446:     /**
447:      * Return null. This is merely a language construct for Mock describing.
448:      *
449:      * @return self
450:      */
451:     public function andReturnNull()
452:     {
453:         return $this;
454:     }
455: 
456:     /**
457:      * Set Exception class and arguments to that class to be thrown
458:      *
459:      * @param string $exception
460:      * @param string $message
461:      * @param int $code
462:      * @param Exception $previous
463:      * @return self
464:      */
465:     public function andThrow($exception, $message = '', $code = 0, \Exception $previous = null)
466:     {
467:         $this->_throw = true;
468:         if (is_object($exception)) {
469:             $this->andReturn($exception);
470:         } else {
471:             $this->andReturn(new $exception($message, $code, $previous));
472:         }
473:         return $this;
474:     }
475: 
476:     /**
477:      * Set Exception classes to be thrown
478:      *
479:      * @param array $exceptions
480:      * @return self
481:      */
482:     public function andThrowExceptions(array $exceptions)
483:     {
484:         $this->_throw = true;
485:         foreach ($exceptions as $exception) {
486:             if (!is_object($exception)) {
487:                 throw new Exception('You must pass an array of exception objects to andThrowExceptions');
488:             }
489:         }
490:         return $this->andReturnValues($exceptions);
491:     }
492: 
493:     /**
494:      * Register values to be set to a public property each time this expectation occurs
495:      *
496:      * @param string $name
497:      * @param mixed $value
498:      * @return self
499:      */
500:     public function andSet($name, $value)
501:     {
502:         $values = func_get_args();
503:         array_shift($values);
504:         $this->_setQueue[$name] = $values;
505:         return $this;
506:     }
507: 
508:     /**
509:      * Alias to andSet(). Allows the natural English construct
510:      * - set('foo', 'bar')->andReturn('bar')
511:      *
512:      * @param string $name
513:      * @param mixed $value
514:      * @return self
515:      */
516:     public function set($name, $value)
517:     {
518:         return call_user_func_array(array($this, 'andSet'), func_get_args());
519:     }
520: 
521:     /**
522:      * Indicates this expectation should occur zero or more times
523:      *
524:      * @return self
525:      */
526:     public function zeroOrMoreTimes()
527:     {
528:         $this->atLeast()->never();
529:     }
530: 
531:     /**
532:      * Indicates the number of times this expectation should occur
533:      *
534:      * @param int $limit
535:      */
536:     public function times($limit = null)
537:     {
538:         if (is_null($limit)) return $this;
539:         $this->_countValidators[] = new $this->_countValidatorClass($this, $limit);
540:         $this->_countValidatorClass = 'Mockery\CountValidator\Exact';
541:         return $this;
542:     }
543: 
544:     /**
545:      * Indicates that this expectation is never expected to be called
546:      *
547:      * @return self
548:      */
549:     public function never()
550:     {
551:         return $this->times(0);
552:     }
553: 
554:     /**
555:      * Indicates that this expectation is expected exactly once
556:      *
557:      * @return self
558:      */
559:     public function once()
560:     {
561:         return $this->times(1);
562:     }
563: 
564:     /**
565:      * Indicates that this expectation is expected exactly twice
566:      *
567:      * @return self
568:      */
569:     public function twice()
570:     {
571:         return $this->times(2);
572:     }
573: 
574:     /**
575:      * Sets next count validator to the AtLeast instance
576:      *
577:      * @return self
578:      */
579:     public function atLeast()
580:     {
581:         $this->_countValidatorClass = 'Mockery\CountValidator\AtLeast';
582:         return $this;
583:     }
584: 
585:     /**
586:      * Sets next count validator to the AtMost instance
587:      *
588:      * @return self
589:      */
590:     public function atMost()
591:     {
592:         $this->_countValidatorClass = 'Mockery\CountValidator\AtMost';
593:         return $this;
594:     }
595: 
596:     /**
597:      * Shorthand for setting minimum and maximum constraints on call counts
598:      *
599:      * @param int $minimum
600:      * @param int $maximum
601:      */
602:     public function between($minimum, $maximum)
603:     {
604:         return $this->atLeast()->times($minimum)->atMost()->times($maximum);
605:     }
606: 
607:     /**
608:      * Indicates that this expectation must be called in a specific given order
609:      *
610:      * @param string $group Name of the ordered group
611:      * @return self
612:      */
613:     public function ordered($group = null)
614:     {
615:         if ($this->_globally) {
616:             $this->_globalOrderNumber = $this->_defineOrdered($group, $this->_mock->mockery_getContainer());
617:         } else {
618:             $this->_orderNumber = $this->_defineOrdered($group, $this->_mock);
619:         }
620:         $this->_globally = false;
621:         return $this;
622:     }
623: 
624:     /**
625:      * Indicates call order should apply globally
626:      *
627:      * @return self
628:      */
629:     public function globally()
630:     {
631:         $this->_globally = true;
632:         return $this;
633:     }
634: 
635:     /**
636:      * Setup the ordering tracking on the mock or mock container
637:      *
638:      * @param string $group
639:      * @param object $ordering
640:      * @return int
641:      */
642:     protected function _defineOrdered($group, $ordering)
643:     {
644:         $groups = $ordering->mockery_getGroups();
645:         if (is_null($group)) {
646:             $result = $ordering->mockery_allocateOrder();
647:         } elseif (isset($groups[$group])) {
648:             $result = $groups[$group];
649:         } else {
650:             $result = $ordering->mockery_allocateOrder();
651:             $ordering->mockery_setGroup($group, $result);
652:         }
653:         return $result;
654:     }
655: 
656:     /**
657:      * Return order number
658:      *
659:      * @return int
660:      */
661:     public function getOrderNumber()
662:     {
663:         return $this->_orderNumber;
664:     }
665: 
666:     /**
667:      * Mark this expectation as being a default
668:      *
669:      * @return self
670:      */
671:     public function byDefault()
672:     {
673:         $director = $this->_mock->mockery_getExpectationsFor($this->_name);
674:         if(!empty($director)) {
675:             $director->makeExpectationDefault($this);
676:         }
677:         return $this;
678:     }
679: 
680:     /**
681:      * Return the parent mock of the expectation
682:      *
683:      * @return \Mockery\MockInterface
684:      */
685:     public function getMock()
686:     {
687:         return $this->_mock;
688:     }
689: 
690:     /**
691:      * Flag this expectation as calling the original class method with the
692:      * any provided arguments instead of using a return value queue.
693:      *
694:      * @return self
695:      */
696:     public function passthru()
697:     {
698:         if ($this->_mock instanceof Mock) {
699:             throw new Exception(
700:                 'Mock Objects not created from a loaded/existing class are '
701:                 . 'incapable of passing method calls through to a parent class'
702:             );
703:         }
704:         $this->_passthru = true;
705:         return $this;
706:     }
707: 
708:     /**
709:      * Cloning logic
710:      *
711:      */
712:     public function __clone()
713:     {
714:         $newValidators = array();
715:         $countValidators = $this->_countValidators;
716:         foreach ($countValidators as $validator) {
717:             $newValidators[] = clone $validator;
718:         }
719:         $this->_countValidators = $newValidators;
720:     }
721: 
722:     public function getName()
723:     {
724:         return $this->_name;
725:     }
726: 
727: }
728: