From eb8f0c45c5e0f6cbf53ca5ca8c41fee43c9d32e4 Mon Sep 17 00:00:00 2001 From: Peter Borodatyy Date: Tue, 29 Aug 2017 12:48:35 +0300 Subject: [PATCH] Added comments to classes. --- src/Producers/AbstractProducer.php | 11 +++++ src/Producers/Event.php | 50 +++++++++++++++++++++ src/Producers/People.php | 67 ++++++++++++++++++++++++++++- src/Session/Session.php | 17 ++++++++ src/Transport/AbstractTransport.php | 7 ++- 5 files changed, 149 insertions(+), 3 deletions(-) diff --git a/src/Producers/AbstractProducer.php b/src/Producers/AbstractProducer.php index 05e37f7..f95d08d 100644 --- a/src/Producers/AbstractProducer.php +++ b/src/Producers/AbstractProducer.php @@ -4,10 +4,21 @@ use Mintance\Transport\AbstractTransport; +/** + * Class AbstractProducer + * @package Mintance\Producers + */ abstract class AbstractProducer { + /** + * @var \Mintance\Transport\AbstractTransport Transporter object. + */ protected $_transport; + /** + * AbstractProducer constructor. + * @param \Mintance\Transport\AbstractTransport $transport + */ public function __construct(AbstractTransport &$transport) { $this->_transport = $transport; } diff --git a/src/Producers/Event.php b/src/Producers/Event.php index da7db59..592483b 100644 --- a/src/Producers/Event.php +++ b/src/Producers/Event.php @@ -4,8 +4,22 @@ use Mintance\Exceptions\Exception; +/** + * Class Event + * @package Mintance\Producers + */ class Event extends AbstractProducer { + /** + * Tracking custom event function. + * + * @param string $name Event name. + * @param array $params Event params. + * + * @return string Event ID if success. + * + * @throws \Mintance\Exceptions\Exception Throws exception if something goes wrong. + */ public function track($name, array $params = []) { $response = $this->_push($this->_buildEvent($name, 'custom-event', $params)); @@ -16,6 +30,17 @@ public function track($name, array $params = []) { } } + /** + * Tracking Purchase event. + * + * @param float $amount Amount of money. + * @param array $params Purchase params + * Default params are: currency, products + * + * @return string Charge ID if success. + * + * @throws \Mintance\Exceptions\Exception Throws exception if something goes wrong. + */ public function charge($amount, array $params = []) { $response = $this->_push($this->_buildEvent('Charge', 'charge', array_merge($params, [ @@ -29,6 +54,14 @@ public function charge($amount, array $params = []) { } } + /** + * Tracking form submission event. + * + * @param array $data Form fields data. + * + * @return string Event ID if success. + * @throws \Mintance\Exceptions\Exception Throws exception if something goes wrong. + */ public function formSubmit(array $data) { $response = $this->_push(array_merge( @@ -45,6 +78,15 @@ public function formSubmit(array $data) { } } + /** + * Function builds event object by default fields. + * + * @param string $name Event name + * @param string $type Event type + * @param array $params Custom params. + * + * @return array Event Data object (array). + */ protected function _buildEvent($name, $type, array $params = []) { return [ 'event_name' => $name, @@ -53,7 +95,15 @@ protected function _buildEvent($name, $type, array $params = []) { ]; } + /** + * Function send's event to mintance. + * + * @param array $event Event data. + * + * @return \Mintance\Transport\AbstractTransport + */ protected function _push(array $event) { + $this->_transport->setEndpoint('events'); return $this->_transport->execute($event); diff --git a/src/Producers/People.php b/src/Producers/People.php index d2e85e0..12ab091 100644 --- a/src/Producers/People.php +++ b/src/Producers/People.php @@ -2,27 +2,58 @@ namespace Mintance\Producers; -use Mintance\Exceptions\Exception; use Mintance\Transport\AbstractTransport; +/** + * Class People + * @package Mintance\Producers + */ class People extends AbstractProducer { + /** + * @var string Generated Permanent ID. + */ protected $_permanent_id; + /** + * @var string Visitor ID from mintance. + */ protected $_visitor_id; + /** + * @var string People ID from mintance. + */ protected $_people_id; + /** + * @var string Custom people identifier. + */ protected $_identifier; + /** + * @var string People type. + */ protected $_type = 'visitor'; + /** + * @var array People data from mintance. + */ protected $_people = []; + /** + * @var array Default people fields in Mintance. + */ protected $_default_fields = [ - 'name', 'first_name', 'last_name', 'email', 'phone' + 'name', 'first_name', 'last_name', 'middle_name', 'email', 'phone' ]; + /** + * People constructor. + * + * Generates permanent_id on init & subscribe to data transporter. + * + * @param \Mintance\Transport\AbstractTransport $transport + */ public function __construct(AbstractTransport $transport) { parent::__construct($transport); @@ -31,6 +62,12 @@ public function __construct(AbstractTransport $transport) { $this->_subscribe(); } + /** + * Function sets custom people identifier. + * You can identify & merge your visitors using any field, like id in your own system, or email, etc.. + * + * @param string $identifier + */ public function setIdentifier($identifier) { $this->_identifier = $identifier; @@ -42,6 +79,13 @@ public function setIdentifier($identifier) { }); } + /** + * Function merge's your visitor with mintance peoples. + * And returns it's people_id in mintance. + * + * @param string $identifier Any custom identifier. + * @return string People ID. + */ public function identify($identifier) { if(!empty($this->_people_id)) { @@ -67,7 +111,13 @@ public function identify($identifier) { return $this->_people_id = $response['people_id']; } + /** + * Update people data. + * + * @param array $args People fields. + */ public function set(array $args) { + $data = [ 'fields' => [] ]; @@ -91,6 +141,11 @@ public function set(array $args) { $this->_transport->execute($data); } + /** + * Return's array with people data in mintance. + * + * @return array + */ public function get() { return array_replace( $this->_people, [ @@ -99,6 +154,9 @@ public function get() { ]); } + /** + * Subscription to data transporter to recognize & save people id or set it to request otherwise. + */ protected function _subscribe() { $this->_transport->register('execute:before', function (&$args) { if(!empty($this->_people_id)) { @@ -129,6 +187,11 @@ protected function _subscribe() { }); } + /** + * Permanent ID generator. + * + * @return string Permanent ID. + */ protected function _generatePermanentId() { return sprintf( '%04x%04x-%04x-%04x-%04x-%04x%04x%04x', // 32 bits for "time_low" diff --git a/src/Session/Session.php b/src/Session/Session.php index 1883458..24ce71f 100644 --- a/src/Session/Session.php +++ b/src/Session/Session.php @@ -4,18 +4,35 @@ use Mintance\Transport\AbstractTransport; +/** + * Class Session + * @package Mintance\Session + */ class Session { + /** + * @var \Mintance\Transport\AbstractTransport Transporter object. + */ protected $_transport; + /** + * @var string Session ID. + */ protected $_session_id; + /** + * Session constructor. + * @param \Mintance\Transport\AbstractTransport $transport + */ public function __construct(AbstractTransport &$transport) { $this->_transport = $transport; $this->_subscribe(); } + /** + * Subscribes to sending & receiving data to mintance to add or read session_id. + */ protected function _subscribe() { $this->_transport->register('execute:before', function (&$args) { if(!empty($this->_session_id)) { diff --git a/src/Transport/AbstractTransport.php b/src/Transport/AbstractTransport.php index 6322158..46d8489 100644 --- a/src/Transport/AbstractTransport.php +++ b/src/Transport/AbstractTransport.php @@ -4,6 +4,12 @@ use Mintance\Core\DispatcherLoop; +/** + * Class AbstractTransport + * @package Mintance\Transport + * + * @method AbstractTransport execute(mixed $data) + */ abstract class AbstractTransport extends DispatcherLoop { protected $_token; @@ -27,6 +33,5 @@ public function setEndpoint($endpoint) { return $this; } - protected abstract function _execute($args); } \ No newline at end of file