1: <?php
  2: namespace Pharborist\Functions;
  3: 
  4: use Pharborist\Filter;
  5: use Pharborist\NodeCollection;
  6: use Pharborist\CommaListNode;
  7: 
  8: /**
  9:  * Trait for nodes that have parameters. For example, function declarations.
 10:  */
 11: trait ParameterTrait {
 12:   /**
 13:    * @var CommaListNode
 14:    */
 15:   protected $parameters;
 16: 
 17:   /**
 18:    * @return CommaListNode
 19:    */
 20:   public function getParameterList() {
 21:     return $this->parameters;
 22:   }
 23: 
 24:   /**
 25:    * @return ParameterNodeCollection
 26:    */
 27:   public function getParameters() {
 28:     $parameters = $this->parameters->getItems()->toArray();
 29:     return new ParameterNodeCollection($parameters, FALSE);
 30:   }
 31: 
 32:   /**
 33:    * @return string[]
 34:    */
 35:   public function getParameterNames() {
 36:     return array_map(function(ParameterNode $parameter) {
 37:       return $parameter->getName();
 38:     }, $this->getParameters()->toArray());
 39:   }
 40: 
 41:   /**
 42:    * @param ParameterNode $parameter
 43:    * @return $this
 44:    */
 45:   public function prependParameter(ParameterNode $parameter) {
 46:     $this->parameters->prependItem($parameter);
 47:     return $this;
 48:   }
 49: 
 50:   /**
 51:    * Appends a parameter.
 52:    *
 53:    * @param \Pharborist\Functions\ParameterNode|callable $parameter
 54:    *  Either an existing parameter node, or a callable which will return
 55:    *  the parameter to append. The callable will receive $this as its
 56:    *  only argument.
 57:    *
 58:    * @return $this
 59:    *
 60:    * @throws \InvalidArgumentException
 61:    */
 62:   public function appendParameter($parameter) {
 63:     if (is_callable($parameter)) {
 64:       $parameter = $parameter($this);
 65:     }
 66:     if (!($parameter instanceof ParameterNode)) {
 67:       throw new \InvalidArgumentException();
 68:     }
 69:     $this->parameters->appendItem($parameter);
 70:     return $this;
 71:   }
 72: 
 73:   /**
 74:    * Insert parameter before parameter at index.
 75:    *
 76:    * @param ParameterNode $parameter
 77:    * @param int $index
 78:    * @throws \OutOfBoundsException
 79:    *   Index out of bounds.
 80:    * @return $this
 81:    */
 82:   public function insertParameter(ParameterNode $parameter, $index) {
 83:     $this->parameters->insertItem($parameter, $index);
 84:     return $this;
 85:   }
 86: 
 87:   /**
 88:    * Remove all parameters.
 89:    *
 90:    * @return $this
 91:    */
 92:   public function clearParameters() {
 93:     $this->parameters->clear();
 94:     return $this;
 95:   }
 96: 
 97:   /**
 98:    * Gets a parameter by name or index.
 99:    *
100:    * @param mixed $key
101:    *  The parameter's name (without leading $) or position in the
102:    *  parameter list.
103:    *
104:    * @return ParameterNode
105:    *
106:    * @throws \InvalidArgumentException if the key is not a string or integer.
107:    */
108:   public function getParameter($key) {
109:     if (is_string($key)) {
110:       return $this->getParameterByName($key);
111:     }
112:     elseif (is_integer($key)) {
113:       return $this->getParameterAtIndex($key);
114:     }
115:     else {
116:       throw new \InvalidArgumentException("Illegal parameter index {$key}.");
117:     }
118:   }
119: 
120:   /**
121:    * Gets a parameter by its position in the parameter list.
122:    *
123:    * @param integer $index
124:    *
125:    * @return ParameterNode
126:    */
127:   public function getParameterAtIndex($index) {
128:     return $this->getParameterList()->getItem($index);
129:   }
130: 
131:   /**
132:    * Gets a parameter by its name.
133:    *
134:    * @param string $name
135:    *  The parameter name with or without leading $.
136:    *
137:    * @return ParameterNode
138:    *
139:    * @throws \UnexpectedValueException if the named parameter doesn't exist.
140:    */
141:   public function getParameterByName($name) {
142:     $name = ltrim($name, '$');
143:     /** @var ParameterNode $parameter */
144:     foreach ($this->getParameters()->reverse() as $parameter) {
145:       if ($parameter->getName() === $name) {
146:         return $parameter;
147:       }
148:     }
149:     throw new \UnexpectedValueException("Parameter {$name} does not exist.");
150:   }
151: 
152:   /**
153:    * Checks if the function/method has a certain parameter.
154:    *
155:    * @param mixed $parameter
156:    *  Either the parameter name (with or without the $), or a ParameterNode.
157:    * @param string $type
158:    *  Optional type hint to check as well.
159:    *
160:    * @return boolean
161:    *
162:    * @throws \InvalidArgumentException if $parameter is neither a string or
163:    * a ParameterNode.
164:    */
165:   public function hasParameter($parameter, $type = NULL) {
166:     if (is_string($parameter)) {
167:       try {
168:         $parameter = $this->getParameterByName($parameter);
169:       }
170:       catch (\UnexpectedValueException $e) {
171:         return FALSE;
172:       }
173:     }
174:     if (!($parameter instanceof ParameterNode)) {
175:       throw new \InvalidArgumentException();
176:     }
177:     if ($parameter->parent() !== $this->parameters) {
178:       return FALSE;
179:     }
180:     if ($type === NULL) {
181:       return TRUE;
182:     }
183:     else {
184:       return $parameter->getTypeHint()->getText() === $type;
185:     }
186:   }
187: 
188:   /**
189:    * Checks if the function/method has a specific required parameter.
190:    *
191:    * @param mixed $parameter
192:    *  Either the name of the parameter (with or without leading $), or a
193:    *  ParameterNode.
194:    * @param string $type
195:    *  Optional type hint to check.
196:    *
197:    * @return boolean
198:    */
199:   public function hasRequiredParameter($parameter, $type = NULL) {
200:     return $this->hasParameter($parameter, $type) && $this->getParameterByName($parameter)->isRequired();
201:   }
202: 
203:   /**
204:    * Checks if the function/method has a specific optional parameter.
205:    *
206:    * @param mixed $parameter
207:    *  Either the name of the parameter (with or without leading $), or a
208:    *  ParameterNode.
209:    * @param string $type
210:    *  Optional type hint to check.
211:    *
212:    * @return boolean
213:    */
214:   public function hasOptionalParameter($parameter, $type = NULL) {
215:     return $this->hasParameter($parameter, $type) && $this->getParameterByName($parameter)->isOptional();
216:   }
217: 
218:   /**
219:    * @return boolean
220:    */
221:   public function hasRequiredParameters() {
222:     return ($this->getRequiredParameters()->count() > 0);
223:   }
224: 
225:   /**
226:    * @return NodeCollection
227:    */
228:   public function getRequiredParameters() {
229:     return $this->parameters
230:       ->children(Filter::isInstanceOf('\Pharborist\ParameterNode'))
231:       ->filter(function(ParameterNode $parameter) {
232:         $value = $parameter->getValue();
233:         return !isset($value);
234:       });
235:   }
236: 
237:   /**
238:    * @return NodeCollection
239:    */
240:   public function getOptionalParameters() {
241:     return $this->parameters
242:       ->children(Filter::isInstanceOf('\Pharborist\ParameterNode'))
243:       ->filter(function(ParameterNode $parameter) {
244:         $value = $parameter->getValue();
245:         return isset($value);
246:       });
247:   }
248: 
249:   /**
250:    * Returns if the final parameter is variadic (PHP 5.6+), as in:
251:    * `function foobaz($a, $b, ...$c)`
252:    *
253:    * @return boolean
254:    */
255:   public function isVariadic() {
256:     $parameters = $this->getParameters();
257:     $last_parameter = $parameters[count($parameters) - 1];
258:     // In a variadic function, the last parameter is the only one which is
259:     // allowed to be variadic.
260:     return $last_parameter->getVariadic() !== NULL;
261:   }
262: }
263: