1: <?php
  2: /**
  3:  * ApiAxle (https://github.com/fillup/apiaxle-module/)
  4:  *
  5:  * @link      https://github.com/fillup/apiaxle-module for the canonical source repository
  6:  * @license   MIT
  7:  */
  8: namespace ApiAxle\Api;
  9: 
 10: use ApiAxle\Shared\Config;
 11: use ApiAxle\Shared\Utilities;
 12: use ApiAxle\Shared\ItemList;
 13: 
 14: /**
 15:  * ApiAxle\Api\Key class
 16:  * 
 17:  * Wraps Key related calls to the ApiAxle API
 18:  * 
 19:  * @author Phillip Shipley <phillip@phillipshipley.com>
 20:  */
 21: class Key
 22: {
 23:     /**
 24:      * Configuration data
 25:      * 
 26:      * @var \ApiAxle\Shared\Config
 27:      */
 28:     protected $config;
 29:     
 30:     /**
 31:      * The actual api key
 32:      * 
 33:      * @var string
 34:      */
 35:     protected $key;
 36:     
 37:     /**
 38:      * Created at timestamp. Set automatically when creating a new key.
 39:      * 
 40:      * @var integer
 41:      */
 42:     protected $createdAt;
 43:     
 44:     /**
 45:      * Updated at timestamp. Set automatically whenever updating a key.
 46:      * 
 47:      * @var integer
 48:      */
 49:     protected $updatedAt;
 50:     
 51:     /**
 52:      * (optional) A shared secret which is used when signing a call to the api.
 53:      * 
 54:      * @var string
 55:      */
 56:     protected $sharedSecret;
 57:     
 58:     /**
 59:      * (default: 172800) Number of queries that can be called per day. Set to `-1` for no limit.
 60:      * 
 61:      * @var integer
 62:      */
 63:     protected $qpd = 172800;
 64:     
 65:     /**
 66:      * (default: 2) Number of queries that can be called per second. Set to `-1` for no limit.
 67:      * 
 68:      * @var integer
 69:      */
 70:     protected $qps = 2;
 71:     
 72:     /**
 73:      * (optional) Names of the Apis that this key belongs to.
 74:      * 
 75:      * @var array
 76:      */
 77:     protected $forApis;
 78:     
 79:     /**
 80:      * (default: false) Disable this API causing errors when it's hit.
 81:      * 
 82:      * @var boolean
 83:      */
 84:     protected $disabled = false;
 85:     
 86:     /**
 87:      * (default: false) If you're the NSA set this flag to true and you'll 
 88:      * activate GOD mode getting you into any API regardless of your being 
 89:      * linked to it or not.
 90:      * 
 91:      * @var string 
 92:      */
 93:     protected $isNSA = 'false';
 94:     
 95:     /**
 96:      * Construct a new Key object
 97:      * 
 98:      * If a $key is provided, it will be fetched from the ApiAxle API and
 99:      * properties will be set accordingly.
100:      * 
101:      * @param array $config
102:      * @param string $key
103:      */
104:     public function __construct($config=false,$key=false) 
105:     {
106:         $this->config = new Config($config);
107:         if($key){
108:             $this->get($key);
109:         }
110:     }
111:     
112:     /**
113:      * Return current key value
114:      * 
115:      * @return string
116:      */
117:     public function getKey()
118:     {
119:         return $this->key;
120:     }
121:     
122:     /**
123:      * Set key value
124:      * 
125:      * @param string $key
126:      */
127:     public function setKey($key)
128:     {
129:         $this->key = $key;
130:     }
131:     
132:     /**
133:      * Set object properties
134:      * 
135:      * @param array $data
136:      * @return \ApiAxle\Api\Key
137:      */
138:     public function setData($data)
139:     {
140:         if(is_array($data)){
141:             $data = json_decode(json_encode($data));
142:         }
143:         
144:         /**
145:          * @todo Refactor to use setters for validation?
146:          */
147:         $this->createdAt = isset($data->createdAt) ? $data->createdAt : null;
148:         $this->updatedAt = isset($data->updatedAt) ? $data->updatedAt : null;
149:         $this->sharedSecret = isset($data->sharedSecret) ? $data->sharedSecret : null;
150:         $this->qpd = isset($data->qpd) ? $data->qpd : $this->qpd;
151:         $this->qps = isset($data->qps) ? $data->qps : $this->qps;
152:         $this->forApis = isset($data->forApis) ? $data->forApis : null;
153:         $this->disabled = isset($data->disabled) ? $data->disabled : $this->disabled;
154:         $this->isNSA = isset($data->isNSA) ? $data->isNSA : $this->isNSA;
155:         
156:         return $this;
157:     }
158:     
159:     /**
160:      * Get API settings as array
161:      * 
162:      * @return array
163:      */
164:     public function getData()
165:     {
166:         $data = array(
167:             'createdAt' => $this->createdAt,
168:             'updatedAt' => $this->updatedAt,
169:             'sharedSecret' => $this->sharedSecret,
170:             'qpd' => $this->qpd,
171:             'qps' => $this->qps,
172:             'forApis' => $this->forApis,
173:             'disabled' => $this->disabled,
174:             'isNSA' => $this->isNSA,
175:         );
176:         
177:         return $data;
178:     }
179:     
180:     /**
181:      * Get an array of only the fields needed for an API call
182:      * (ignore created/updated, etc.)
183:      * 
184:      * @return array
185:      */
186:     public function getDataForApiCall()
187:     {
188:         $data = array(
189:             'qpd' => $this->qpd,
190:             'qps' => $this->qps,
191:             'disabled' => $this->disabled,
192:         );
193:         
194:         if(is_array($this->forApis)){
195:             $data['forApis'] = $this->forApis;
196:         }
197:         if(!is_null($this->sharedSecret)){
198:             $data['sharedSecret'] = $this->sharedSecret;
199:         }
200:         
201:         return $data;
202:     }
203:     
204:     /**
205:      * Fetch key information from ApiAxle API and update object properties
206:      * 
207:      * @param string $key
208:      * @return \ApiAxle\Api\Key
209:      */
210:     public function get($key)
211:     {
212:         if($key){
213:             $apiPath = 'key/'.$key;
214:             $request = Utilities::callApi($apiPath,'GET',null,$this->getConfig());
215:             if($request){
216:                 $this->setKey($key);
217:                 $this->setData($request);
218:             }
219:         }
220:         
221:         return $this;
222:     }
223:     
224:     /**
225:      * Create a new key
226:      * 
227:      * @param string $key
228:      * @param array $data
229:      * @return \ApiAxle\Api\Key
230:      * @throws \ErrorException
231:      */
232:     public function create($key, $data=false)
233:     {
234:         $this->setKey($key);
235:         if($data){
236:             $this->setData($data);
237:         }
238:         if($this->isValid()){
239:             $apiPath = 'key/'.$this->getKey().'?isNSA='.$this->isNSA;
240:             $request = Utilities::callApi($apiPath, 'POST', $this->getDataForApiCall(),$this->getConfig());
241:             if($request){
242:                 $this->get($key);
243:                 return $this;
244:             } else {
245:                 throw new \ErrorException('Unable to create key',251);
246:             }
247:         }
248:         
249:     }
250:     
251:     /**
252:      * Update a key
253:      * 
254:      * @param array $data
255:      * @return \ApiAxle\Api\Key
256:      * @throws \ErrorException
257:      */
258:     public function update($data)
259:     {
260:         if(!is_null($this->getKey()) && $this->isValid()){
261:             $apiPath = 'key/'.$this->getKey();
262:             $request = Utilities::callApi($apiPath,'PUT',$data,$this->getConfig());
263:             if($request){
264:                 $this->get($this->getKey());
265:                 return $this;
266:             } else {
267:                 throw new \ErrorException('Unable to update key',252);
268:             }
269:         } else {
270:             throw new \ErrorException('A key value is required to update.',253);
271:         }
272:         
273:     }
274:     
275:     /**
276:      * Delete a key
277:      * 
278:      * @param string $key
279:      * @return boolean
280:      * @throws \Exception
281:      * @throws \ErrorException
282:      */
283:     public function delete($key=false)
284:     {
285:         if($key){
286:             $this->setKey($key);
287:         }
288:         if(is_null($this->getKey())){
289:             throw new \Exception('A key value is required to delete.',254);
290:         } else {
291:             $apiPath = 'key/'.$this->getKey();
292:             $request = Utilities::callApi($apiPath, 'DELETE', null, $this->getConfig());
293:             if($request){
294:                 return true;
295:             } else {
296:                 throw new \ErrorException('Unable to delete key.', 255);
297:             }
298:         }
299:     }
300:     
301:     /**
302:      * Get a list of all Keys
303:      * 
304:      * Parameters $from and $to are used for pagination of results
305:      * 
306:      * @param integer $from
307:      * @param integer $to
308:      * @param string $resolve
309:      * @return \ApiAxle\Shared\ItemList
310:      */
311:     public function getList($from=0, $to=100, $resolve='true')
312:     {
313:         $apiPath = 'keys';
314:         $params = array(
315:             'from' => $from,
316:             'to' => $to,
317:             'resolve' => $resolve
318:         );
319:         
320:         $keyList = new ItemList();
321:         $request = Utilities::callApi($apiPath, 'GET', $params, $this->getConfig());
322:         if($request){
323:             foreach($request as $name => $data){
324:                 $key = new Key($this->getConfig());
325:                 $key->setKey($name);
326:                 $key->setData($data);
327:                 $keyList->addItem($key);
328:             }
329:         }
330:         
331:         return $keyList;
332:     }
333:     
334:     /**
335:      * Get a list of APIs that this Key has access to
336:      * 
337:      * @param string $resolve Wether or not to also get API details
338:      * @return \ApiAxle\Shared\ItemList
339:      * @throws \Exception
340:      * @throws \ErrorException
341:      */
342:     public function getApiList($resolve='true')
343:     {
344:         if(is_null($this->getKey())){
345:             throw new \Exception('A key value is required to fetch associated apis.',256);
346:         } else {
347:             $apiList = new ItemList();
348:             $data = array('resolve' => $resolve);
349:             $apiPath = 'key/'.$this->getKey().'/apis';
350:             $request = Utilities::callApi($apiPath, 'GET', $data, $this->getConfig());
351:             if($request){
352:                 foreach($request as $name => $value){
353:                     $api = new Api($this->getConfig());
354:                     $api->setName($name);
355:                     $api->setData($value);
356:                     $apiList->addItem($api);
357:                 }
358:                 
359:                 return $apiList;
360:             } else {
361:                 throw new \ErrorException('Unable to get list of APIs for key.', 257);
362:             }
363:         }
364:     }
365:     
366:     /**
367:      * Get most used APIs for this key
368:      * 
369:      * @param string $granularity Options are second, minute, hour, day
370:      * @return \stdClass
371:      * @throws \Exception
372:      * @throws Exception
373:      */
374:     public function getApiCharts($granularity='minute')
375:     {
376:         if(is_null($this->getKey())){
377:             throw new \Exception('A key value is required to fetch api charts.',258);
378:         } else {
379:             $apiPath = 'key/'.$this->getKey().'/apicharts';
380:             $data = array('granularity' => $granularity);
381:             $request = Utilities::callApi($apiPath, 'GET', $data,$this->getConfig());
382:             if($request){
383:                 return $request;
384:             } else {
385:                 throw new Exception('Unable to fetch api charts', 259);
386:             }
387:         }
388:     }
389:     
390:     /**
391:      * Get real time hits for a key
392:      * 
393:      * @param integer $timestart
394:      * @param integer $timeend
395:      * @param string $granularity
396:      * @param string $format_timeseries
397:      * @param string $format_timestamp
398:      * @param \ApiAxle\Api\Api $forapi
399:      * @return type
400:      * @throws \Exception
401:      */
402:     public function getStats($timestart=false, $timeend=false, 
403:             $granularity='minute',$format_timeseries='true',
404:             $format_timestamp='epoch_seconds', $forapi=false)
405:     {
406:         if(is_null($this->getKey())){
407:             throw new \Exception('A key value is required to get stats.',260);
408:         } else {
409:             
410:             $data = array(
411:                 'granularity' => $granularity,
412:                 'format_timeseries' => $format_timeseries,
413:                 'format_timestamp' => $format_timestamp,
414:             );
415:             if($timestart){
416:                 $data['from'] = $timestart;
417:             }
418:             if($timeend){
419:                 $data['to'] = $timeend;
420:             }
421:             
422:             if($forapi && is_string($forapi)){
423:                 $data['forapi'] = $forapi;
424:             } elseif($forapi && $forapi instanceof ApiAxle\Api\Api){
425:                 $data['forapi'] = $forapi->getName();
426:             }
427:             
428:             $apiPath = 'key/'.$this->getKey().'/stats';
429:             $request = Utilities::callApi($apiPath, 'GET', $data,$this->getConfig());
430:             if($request){
431:                 return $request;
432:             } else {
433:                 throw new \Exception('Unable to get stats for key',261);
434:             }
435:         }
436:     }
437:     
438:     /**
439:      * Get most used keys and their stats
440:      * 
441:      * @param string $granularity Options are second, minute, hour, day
442:      * @return \stdClass
443:      * @throws \Exception
444:      */
445:     public function getCharts($granularity='minute')
446:     {
447:         $apiPath = 'keys/charts';
448:         $data = array('granularity' => $granularity);
449:         $request = Utilities::callApi($apiPath, 'GET', $data,$this->getConfig());
450:         if($request){
451:             return $request;
452:         } else {
453:             throw new \Exception('Unable to get charts for key.',262);
454:         }
455:     }
456:     
457:     /**
458:      * Return config object
459:      * 
460:      * @return \ApiAxle\Shared\Config
461:      */
462:     public function getConfig()
463:     {
464:         return $this->config;
465:     }
466:     
467:     /**
468:      * Validate that required fields are set before attempting to provision/update
469:      * 
470:      * @return boolean
471:      * @throws \Exception
472:      */
473:     public function isValid()
474:     {
475:         if(!is_null($this->getKey())){
476:             return true;
477:         } else {
478:             throw new \Exception('A key value is required to interact with keys.',250);
479:         }
480:     }
481:     
482: }
483: