/**
* Adds contacts to the system. Fills the "contacts" slot.
* @param {array} $_REQUEST
* @param {string} $_REQUEST.label The label of the contact
* @param {string} $_REQUEST.contactUserId The contactUserId of the contact
* @param {string} [$_REQUEST.nickname] The nickname of the contact
* @param {string} [$_REQUEST.userId=Users::loggedInUser(true)->id] You can override the user id, if another plugin adds a hook that allows you to do this
*/
function Users_contact_post($params = array())
{
$req = array_merge($_REQUEST, $params);
Q_Request::requireFields(array('label', 'contactUserId'), $req, true);
$loggedInUserId = Users::loggedInUser(true)->id;
$userId = Q::ifset($req, 'userId', $loggedInUserId);
$contactUserId = $req['contactUserId'];
$nickname = Q::ifset($req, 'nickname', null);
$contacts = Users_Contact::addContact($userId, $req['label'], $contactUserId, $nickname);
Q_Response::setSlot('contacts', Db::exportArray($contacts));
}
/**
* Adds contacts to the system. Fills the "contacts" slot.
* @param {array} $_REQUEST
* @param {string} $_REQUEST.label The label of the contact
* @param {string} $_REQUEST.contactUserId The contactUserId of the contact
* @param {string} [$_REQUEST.nickname] The nickname of the contact
* @param {string} [$_REQUEST.userId=Users::loggedInUser(true)->id] You can override the user id, if another plugin adds a hook that allows you to do this
*/
function Users_contact_post($params = array())
{
$req = array_merge($_REQUEST, $params);
Q_Request::requireFields(array('label', 'contactUserId'), $req, true);
$loggedInUserId = Users::loggedInUser(true)->id;
$userId = Q::ifset($req, 'userId', $loggedInUserId);
$contactUserId = $req['contactUserId'];
$nickname = Q::ifset($req, 'nickname', null);
$l = $req['label'];
if ($userId !== $loggedInUserId) {
Users_User::fetch($userId, true);
}
Users_User::fetch($contactUserId, true);
Users::canManageContacts($loggedInUserId, $userId, $l, true);
$label = new Users_Label();
$label->userId = $userId;
$label->label = $l;
if (!$label->retrieve()) {
throw new Q_Exception_MissingRow(array('table' => 'Users_Label', 'criteria' => json_encode($label->fields)));
}
$contacts = Users_Contact::addContact($userId, $l, $contactUserId, $nickname);
Q_Response::setSlot('contacts', Db::exportArray($contacts));
}
/**
* @method addContact
* @param {string} $contactUserId
* The id of the user who is the contact
* @param {string|array} $label
* The label of the contact. This can be a string or an array of strings, in which case
* multiple contact rows are saved.
* @param {string} [$nickname='']
* Optional nickname to assign to the contact
* @optional
* @param {string} [$asUserId=null] The user to do this operation as.
* Defaults to the logged-in user. Pass false to skip access checks.
* @throws {Q_Exception_RequiredField}
* if $label is missing
* @return {array} Array of contacts that are saved
*/
function addContact($label, $contactUserId, $nickname = '', $asUserId = null)
{
Users_Contact::addContact($this->id, $label, $contactUserId, $nickname, $asUserId);
}
/**
* @method addContact
* @param {string} $contactUserId
* The id of the user who is the contact
* @param {string|array} $label
* The label of the contact. This can be a string or an array of strings, in which case
* multiple contact rows are saved.
* @param {string} [$nickname='']
* Optional nickname to assign to the contact
* @optional
* @throws {Q_Exception_RequiredField}
* if $label is missing
* @return {array} Array of contacts that are saved
*/
function addContact($label, $contactUserId, $nickname = '')
{
Users_Contact::addContact($this->id, $label, $contactUserId, $nickname);
}
/**
* Invites a user (or a future user) to a stream .
* @method invite
* @static
* @param {string} $publisherId The id of the stream publisher
* @param {string} $streamName The name of the stream the user will be invited to
* @param {array} $who Array that can contain the following keys:
* @param {string|array} [$who.userId] user id or an array of user ids
* @param {string|array} [$who.fb_uid] fb user id or array of fb user ids
* @param {string|array} [$who.label] label or an array of labels, or tab-delimited string
* @param {string|array} [$who.identifier] identifier or an array of identifiers, or tab-delimited string
* @param {integer} [$who.newFutureUsers] the number of new Users_User objects to create via Users::futureUser in order to invite them to this stream. This typically is used in conjunction with passing the "html" option to this function.
* @param {array} [$options=array()]
* @param {string|array} [$options.addLabel] label or an array of labels for adding publisher's contacts
* @param {string|array} [$options.addMyLabel] label or an array of labels for adding asUserId's contacts
* @param {integer} [$options.readLevel] => the read level to grant those who are invited
* @param {integer} [$options.writeLevel] => the write level to grant those who are invited
* @param {integer} [$options.adminLevel] => the admin level to grant those who are invited
* @param {string} [$options.displayName] => the display name to use to represent the inviting user
* @param {string} [$options.appUrl] => Can be used to override the URL to which the invited user will be redirected and receive "Q.Streams.token" in the querystring.
* @param {array} [$options.html] => an array of ($template, $batchName) such as ("MyApp/foo.handlebars", "foo") for generating html snippets which can then be viewed from and printed via the action Streams/invitations?batchName=$batchName&invitingUserId=$asUserId&limit=$limit&offset=$offset
* @param {string} [$options.asUserId=Users::loggedInUser(true)->id] Invite as this user id, defaults to logged-in user
* @param {boolean} [$options.skipAccess] whether to skip access checks when adding labels and contacts
* @see Users::addLink()
* @return {array} returns array with keys "success", "invited", "statuses", "identifierTypes", "alreadyParticipating"
*/
static function invite($publisherId, $streamName, $who, $options = array())
{
if (isset($options['asUserId'])) {
$asUserId = $options['asUserId'];
$asUser = Users_User::fetch($asUserId);
} else {
$asUser = Users::loggedInUser(true);
$asUserId = $asUser->id;
}
// Fetch the stream as the logged-in user
$stream = Streams::fetchOne($asUserId, $publisherId, $streamName);
if (!$stream) {
throw new Q_Exception_MissingRow(array('table' => 'stream', 'criteria' => 'with that name'), 'streamName');
}
// Do we have enough admin rights to invite others to this stream?
if (!$stream->testAdminLevel('invite') || !$stream->testWriteLevel('join')) {
throw new Users_Exception_NotAuthorized();
}
if (isset($options['html'])) {
$html = $options['html'];
if (!is_array($html) or count($html) < 2) {
throw new Q_Exception_WrongType(array('field' => "options.html", 'type' => 'array of 2 strings'));
}
list($template, $batchName) = $html;
// validate these paths
$filename = APP_VIEWS_DIR . DS . $template;
if (!Q::realPath($filename)) {
throw new Q_Exception_MissingFile(compact('filename'));
}
$ext = $pathinfo = pathinfo($template, PATHINFO_EXTENSION);
if ($ext !== 'handlebars') {
throw new Q_Exception_WrongValue(array('field' => 'options.html[0]', 'range' => 'a filename with extension .handlebars'));
}
$path = Streams::invitationsPath($asUserId) . DS . $batchName;
Q_Utils::canWriteToPath($path, true, true);
}
// get user ids if any to array, throw if user not found
$raw_userIds = isset($who['userId']) ? Users_User::verifyUserIds($who['userId'], true) : array();
// merge labels if any
if (isset($who['label'])) {
$label = $who['label'];
if (is_string($label)) {
$label = array_map('trim', explode("\t", $label));
}
$raw_userIds = array_merge($raw_userIds, Users_User::labelsToIds($asUserId, $label));
}
// merge identifiers if any
$identifierType = null;
$statuses = null;
if (isset($who['identifier'])) {
$identifier = $who['identifier'];
if (is_string($identifier)) {
if (Q_Valid::email($who['identifier'])) {
$identifierType = 'email';
} else {
if (Q_Valid::phone($who['identifier'])) {
$identifierType = 'mobile';
}
}
$identifier = array_map('trim', explode("\t", $identifier));
}
$statuses = array();
$identifier_ids = Users_User::idsFromIdentifiers($identifier, $statuses);
$raw_userIds = array_merge($raw_userIds, $identifier_ids);
}
// merge fb uids if any
if (isset($who['fb_uid'])) {
$fb_uids = $who['fb_uid'];
if (is_string($fb_uids)) {
$fb_uids = array_map('trim', explode("\t", $fb_uids));
}
$raw_userIds = array_merge($raw_userIds, Users_User::idsFromFacebook($fb_uids));
}
if (!empty($who['newFutureUsers'])) {
$nfu = $who['newFutureUsers'];
for ($i = 0; $i < $nfu; ++$i) {
$raw_userIds[] = Users::futureUser('none', null)->id;
}
}
// ensure that each userId is included only once
// and remove already participating users
$raw_userIds = array_unique($raw_userIds);
$total = count($raw_userIds);
$userIds = Streams_Participant::filter($raw_userIds, $stream);
$to_invite = count($userIds);
$appUrl = !empty($options['appUrl']) ? $options['appUrl'] : Q_Request::baseUrl() . '/' . Q_Config::get("Streams", "types", $stream->type, "invite", "url", "plugins/Streams/stream");
// now check and define levels for invited user
$readLevel = isset($options['readLevel']) ? $options['readLevel'] : null;
if (isset($readLevel)) {
$readLevel = Streams_Stream::numericReadLevel($readLevel);
if (!$stream->testReadLevel($readLevel)) {
// We can't assign greater read level to other people than we have ourselves!
throw new Users_Exception_NotAuthorized();
}
}
$writeLevel = isset($options['writeLevel']) ? $options['writeLevel'] : null;
if (isset($writeLevel)) {
$writeLevel = Streams_Stream::numericWriteLevel($writeLevel);
if (!$stream->testWriteLevel($writeLevel)) {
// We can't assign greater write level to other people than we have ourselves!
throw new Users_Exception_NotAuthorized();
}
}
$adminLevel = isset($options['adminLevel']) ? $options['adminLevel'] : null;
if (isset($adminLevel)) {
$adminLevel = Streams_Stream::numericAdminLevel($adminLevel);
if (!$stream->testAdminLevel($adminLevel + 1)) {
// We can't assign an admin level greater, or equal, to our own!
// A stream's publisher can assign owners. Owners can assign admins.
// Admins can confer powers to invite others, to some people.
// Those people can confer the privilege to publish a message re this stream.
// But admins can't assign other admins, and even stream owners
// can't assign other owners.
throw new Users_Exception_NotAuthorized();
}
}
// calculate expiry time
$duration = Q_Config::get("Streams", "types", $stream->type, "invite", "duration", false);
$expiry = $duration ? strtotime($duration) : null;
$asUserId2 = empty($options['skipAccess']) ? $asUserId : false;
if ($label = Q::ifset($options, 'addLabel', null)) {
if (is_string($label)) {
$label = explode("\t", $label);
}
Users_Label::addLabel($label, $publisherId, null, null, $asUserId2, true);
}
if ($myLabel = Q::ifset($options, 'addMyLabel', null)) {
if (is_string($myLabel)) {
$myLabel = explode("\t", $myLabel);
}
Users_Label::addLabel($myLabel, $asUserId, null, null, $asUserId2, true);
}
foreach ($raw_userIds as $userId) {
Users_Contact::addContact($asUserId, "Streams/invited", $userId, null, false, true);
Users_Contact::addContact($asUserId, "Streams/invited/{$stream->type}", $userId, null, false, true);
Users_Contact::addContact($userId, "Streams/invitedMe", $asUserId, null, false, true);
Users_Contact::addContact($userId, "Streams/invitedMe/{$stream->type}", $asUserId, null, false, true);
if ($label) {
Users_Contact::addContact($publisherId, $label, $userId, null, $asUserId2, true);
}
if ($myLabel) {
Users_Contact::addContact($asUserId, $label, $userId, null, $asUserId2, true);
}
}
// let node handle the rest, and get the result
$displayName = isset($options['displayName']) ? $options['displayName'] : Streams::displayName($asUser);
$params = array("Q/method" => "Streams/Stream/invite", "invitingUserId" => $asUserId, "username" => $asUser->username, "userIds" => Q::json_encode($userIds), "stream" => Q::json_encode($stream->toArray()), "appUrl" => $appUrl, "label" => $label, "myLabel" => $myLabel, "readLevel" => $readLevel, "writeLevel" => $writeLevel, "adminLevel" => $adminLevel, "displayName" => $displayName, "expiry" => $expiry);
if (!empty($template)) {
$params['template'] = $template;
$params['batchName'] = $batchName;
}
$result = Q_Utils::queryInternal('Q/node', $params);
return array('success' => $result, 'invited' => $userIds, 'statuses' => $statuses, 'identifierType' => $identifierType, 'alreadyParticipating' => $total - $to_invite);
}
