Coding standards
Security in ResourceSpace
Developer reference
Database
Action functions
Admin functions
Ajax functions
Annotation functions
API functions
Collections functions
Comment functions
Config functions
CSV export functions
Dash functions
Debug functions
Encryption functions
Facial recognition functions
File functions
General functions
Language functions
Log functions
Login functions
Message functions
Migration functions
Node functions
PDF functions
Plugin functions
Render functions
Reporting functions
Request functions
Research functions
Slideshow functions
Theme permission functions
User functions
Video functions
Database functions
Metadata functions
Resource functions
Search functions
Map functions
Job functions
Tab functions
Test functions

email_collection()

Description

E-mail a collection to users

- Attempt to resolve all users in the string $userlist to user references.
- Add $collection to these user's 'My Collections' page
- Send them an e-mail linking to this collection
- Handle multiple collections (comma separated list)

Parameters

ColumnTypeDefaultDescription
$colrefs mixed
$collectionname string
$fromusername string
$userlist string
$message string
$feedback string
$access integer -1
$expires string ""
$useremail string ""
$from_name string ""
$cc string ""
$themeshare boolean false
$themename string ""
$themeurlsuffix string ""
$list_recipients boolean false
$add_internal_access boolean false
$group string ""
$sharepwd string "": string { global $baseurl
$email_from
$applicationname
$lang
$userref
$usergroup;

Location

include/collections_functions.php lines 1811 to 2088

Definition

 
function email_collection($colrefs, $collectionname, $fromusername, $userlist, $message, $feedback, $access = -1, $expires = "", $useremail = "", $from_name = "", $cc = "", $themeshare = false, $themename = "", $themeurlsuffix = "", $list_recipients = false, $add_internal_access = false, $group = "", $sharepwd = ""): string
{
    global $baseurl,$email_from,$applicationname,$lang,$userref,$usergroup;
    if ($useremail == "") {
        $useremail = $email_from;
    }
    if ($group == "") {
        $group = $usergroup;
    }

    if (trim($userlist) == "") {
        return $lang["mustspecifyoneusername"];
    }
    $userlist = resolve_userlist_groups($userlist);

    if (strpos($userlist, $lang["groupsmart"] . ": ") !== false) {
        $groups_users = resolve_userlist_groups_smart($userlist, true);
        if ($groups_users != '') {
            if ($userlist != "") {
                $userlist = remove_groups_smart_from_userlist($userlist);
                if ($userlist != "") {
                    $userlist .= ",";
                }
            }
            $userlist .= $groups_users;
        }
    }

    $ulist = trim_array(explode(",", $userlist));
    $emails = array();
    $key_required = array();
    if ($feedback) {
        $feedback = 1;
    } else {
        $feedback = 0;
    }

    $reflist = trim_array(explode(",", $colrefs));
    // Take out the FC category from the list as this is more of a dummy record rather than a collection we'll be giving
    // access to users. See generate_collection_access_key() when collection is a featured collection category.
    $fc_category_ref = ($themeshare ? array_shift($reflist) : null);

    $emails_keys = resolve_user_emails($ulist);
    if (0 === count($emails_keys)) {
        return $lang['email_error_user_list_not_valid'];
    }

    # Make an array of all emails, whether internal or external
    $emails = $emails_keys['emails'];
    # Make a corresponding array stating whether keys are necessary for the links
    $key_required = $emails_keys['key_required'];

    # Make an array of internal userids which are unexpired approved with valid emails
    $internal_user_ids = $emails_keys['refs'] ?? array();

    if (count($internal_user_ids) > 0) {
        # Delete any existing collection entries
        ps_query("DELETE FROM user_collection WHERE collection IN (" . ps_param_insert(count($reflist)) . ") 
                AND user IN (" . ps_param_insert(count($internal_user_ids)) . ")", array_merge(ps_param_fill($reflist, "i"), ps_param_fill($internal_user_ids, "i")));

        # Insert new user_collection row(s)
        #loop through the collections
        for ($nx1 = 0; $nx1 < count($reflist); $nx1++) {
            #loop through the users
            for ($nx2 = 0; $nx2 < count($internal_user_ids); $nx2++) {
                ps_query("INSERT INTO user_collection(collection,user,request_feedback) VALUES (?,?,?)", ["i",$reflist[$nx1],"i",$internal_user_ids[$nx2],"i",$feedback ]);
                if ($add_internal_access) {
                    foreach (get_collection_resources($reflist[$nx1]) as $resource) {
                        if (get_edit_access($resource)) {
                            open_access_to_user($internal_user_ids[$nx2], $resource, $expires);
                        }
                    }
                }

                #log this
                clear_query_cache('collection_access' . $internal_user_ids[$nx2]);
                collection_log($reflist[$nx1], LOG_CODE_COLLECTION_SHARED_COLLECTION, 0, ps_value("select username as value from user where ref = ?", array("i", $internal_user_ids[$nx2]), ""));
            }
        }
    }

    # Send an e-mail to each resolved email address

    # htmlbreak is for composing list
    $htmlbreak = "\r\n";
    global $use_phpmailer;
    if ($use_phpmailer) {
        $htmlbreak = "<br/><br/>";
        $htmlbreaksingle = "<br/>";
    }

    if ($fromusername == "") {
        $fromusername = $applicationname;
    } // fromusername is used for describing the sender's name inside the email
    if ($from_name == "") {
        $from_name = $applicationname;
    } // from_name is for the email headers, and needs to match the email address (app name or user name)

    $templatevars['message'] = str_replace(array("\\n","\\r","\\"), array("\n","\r",""), $message);
    if (trim($templatevars['message']) == "") {
        $templatevars['message'] = $lang['nomessage'];
        $message = "lang_nomessage";
    }

    $templatevars['fromusername'] = $fromusername;
    $templatevars['from_name'] = $from_name;

    // Create notification message
    $notifymessage     = new ResourceSpaceUserNotification();
    if (count($reflist) > 1) {
        $notifymessage->set_subject($applicationname . ": ");
        $notifymessage->append_subject("lang_mycollections");
    } else {
        $notifymessage->set_subject($applicationname . ": " . $collectionname);
    }

    if ($fromusername == "") {
        $fromusername = $applicationname;
    }

    $externalmessage = str_replace('[applicationname]', $applicationname, $lang["emailcollectionmessageexternal"]);
    $internalmessage = "lang_emailcollectionmessage";

    $viewlinktext = "lang_clicklinkviewcollection";
    if ($themeshare) { // Change the text if sharing a theme category
        $externalmessage    = str_replace('[applicationname]', $applicationname, $lang["emailthemecollectionmessageexternal"]);
        $internalmessage    = "lang_emailthememessage";
        $viewlinktext       = "lang_clicklinkviewcollections";
    }

    ##  loop through recipients
    for ($nx1 = 0; $nx1 < count($emails); $nx1++) {
        ## loop through collections
        $list = "";
        $list2 = "";
        $origviewlinktext = $viewlinktext; // Save this text as we may change it for internal theme shares for this user
        if ($themeshare && !$key_required[$nx1]) { # don't send a whole list of collections if internal, just send the theme category URL
            $notifymessage->set_subject($applicationname . ": " . $themename);
            $url = $baseurl . "/pages/collections_featured.php" . $themeurlsuffix;
            $viewlinktext = "lang_clicklinkviewthemes";
            $notifymessage->url = $url;
            $emailcollectionmessageexternal = false;
            if ($use_phpmailer) {
                $link = '<a href="' . $url . '">' . $themename . '</a>';
                $list .= $htmlbreak . $link;
                // alternate list style
                $list2 .= $htmlbreak . $themename . ' -' . $htmlbreaksingle . $url;
                $templatevars['list2'] = $list2;
            } else {
                $list .= $htmlbreak . $url;
            }
            for ($nx2 = 0; $nx2 < count($reflist); $nx2++) {
                #log this
                collection_log($reflist[$nx2], LOG_CODE_COLLECTION_EMAILED_COLLECTION, 0, $emails[$nx1]);
            }
        } else {
            // E-mail external share, generate the access key based on the FC category. Each sub-collection will have the same key.
            if ($key_required[$nx1] && $themeshare && !is_null($fc_category_ref)) {
                $k = generate_collection_access_key($fc_category_ref, $feedback, $emails[$nx1], $access, $expires, $group, $sharepwd, $reflist);
                $fc_key = "&k={$k}";
            }

            for ($nx2 = 0; $nx2 < count($reflist); $nx2++) {
                $key = "";
                $emailcollectionmessageexternal = false;

                # Do we need to add an external access key for this user (e-mail specified rather than username)?
                if ($key_required[$nx1] && !$themeshare) {
                    $k = generate_collection_access_key($reflist[$nx2], $feedback, $emails[$nx1], $access, $expires, $group, $sharepwd);
                    $key = "&k=" . $k;
                    $emailcollectionmessageexternal = true;
                }
                // If FC category, the key is valid across all sub-featured collections. See generate_collection_access_key()
                elseif ($key_required[$nx1] && $themeshare && !is_null($fc_category_ref)) {
                    $key = $fc_key;
                    $emailcollectionmessageexternal = true;
                }
                $url = $baseurl .   "/?c=" . $reflist[$nx2] . $key;
                $collection = array();
                $collection = ps_query("SELECT name,savedsearch FROM collection WHERE ref = ?", ["i",$reflist[$nx2]]);
                if ($collection[0]["name"] != "") {
                    $collection_name = i18n_get_collection_name($collection[0]);
                } else {
                    $collection_name = $reflist[$nx2];
                }
                if ($use_phpmailer) {
                    $link = '<a href="' . $url . '">' . escape($collection_name) . '</a>';
                    $list .= $htmlbreak . $link;
                    // alternate list style
                    $list2 .= $htmlbreak . $collection_name . ' -' . $htmlbreaksingle . $url;
                    $templatevars['list2'] = $list2;
                } else {
                    $list .= $htmlbreak . $collection_name . $htmlbreak . $url . $htmlbreak;
                }
                #log this
                collection_log($reflist[$nx2], LOG_CODE_COLLECTION_EMAILED_COLLECTION, 0, $emails[$nx1]);
            }
        }
        $templatevars['list'] = $list;
        $templatevars['from_name'] = $from_name;
        if (isset($k)) {
            if ($expires == "") {
                $templatevars['expires_date'] = $lang["email_link_expires_never"];
                $templatevars['expires_days'] = $lang["email_link_expires_never"];
            } else {
                $day_count = round((strtotime($expires) - strtotime('now')) / (60 * 60 * 24));
                $templatevars['expires_date'] = $lang['email_link_expires_date'] . nicedate($expires);
                $templatevars['expires_days'] = $lang['email_link_expires_days'] . $day_count;
                if ($day_count > 1) {
                    $templatevars['expires_days'] .= " " . $lang['expire_days'] . ".";
                } else {
                    $templatevars['expires_days'] .= " " . $lang['expire_day'] . ".";
                }
            }
        } else {
            # Set empty expiration templatevars
            $templatevars['expires_date'] = '';
            $templatevars['expires_days'] = '';
        }
        $body = "";
        if ($emailcollectionmessageexternal) {
            $template = ($themeshare) ? "emailthemeexternal" : "emailcollectionexternal";
            // External - send email
            if (is_array($emails) && (count($emails) > 1) && $list_recipients === true) {
                $body = $lang["list-recipients"] . "\n" . implode("\n", $emails) . "\n\n";
                $templatevars['list-recipients'] = $lang["list-recipients"] . "\n" . implode("\n", $emails) . "\n\n";
            }
            if (substr($viewlinktext, 0, 5) == "lang_") {
                $langkey = substr($viewlinktext, 5);
                if (isset($lang[$langkey])) {
                    $viewlinktext = $lang[$langkey];
                }
            }
            $body .= $templatevars['fromusername'] . " " . $externalmessage . "\n\n" . $templatevars['message'] . "\n\n" . $viewlinktext . "\n\n" . $templatevars['list'];

            $emailsubject = $notifymessage->get_subject();
            $send_result = send_mail($emails[$nx1], $emailsubject, $body, $fromusername, $useremail, $template, $templatevars, $from_name, $cc);
            if ($send_result !== true) {
                return $send_result;
            }
        } else {
            $template = ($themeshare) ? "emailtheme" : "emailcollection";
        }
        $viewlinktext = $origviewlinktext;
    }

    if (count($internal_user_ids) > 0) {
        // Internal share, send notifications
        $notifymessage->append_text($templatevars['fromusername'] . "&nbsp;");
        $notifymessage->append_text($internalmessage);
        $notifymessage->append_text("<br/><br/>" . $templatevars['message'] . "<br/><br/>");
        $notifymessage->append_text($viewlinktext);
        $notifymessage->url = $url;
        send_user_notification($internal_user_ids, $notifymessage);
    }

    hook("additional_email_collection", "", array($colrefs,$collectionname,$fromusername,$userlist,$message,$feedback,$access,$expires,$useremail,$from_name,$cc,$themeshare,$themename,$themeurlsuffix,$template,$templatevars));

    # Identify user accounts which have been skipped
    $candidate_users = ps_query("SELECT ref, username FROM user 
       WHERE username IN ("  . ps_param_insert(count($ulist)) . ")", ps_param_fill($ulist, "s"));
    $skipped_usernames = array();
    if (count($candidate_users) != count($internal_user_ids)) {
        foreach ($candidate_users as $candidate_user) {
            if (!in_array($candidate_user['ref'], $internal_user_ids)) {
                $skipped_usernames[] = $candidate_user['username'];
            }
        }
    }

    # Report skipped accounts
    if (count($skipped_usernames) > 0) {
        return $lang['email_error_user_list_some_skipped'] . ' ' . implode(', ', $skipped_usernames);
    }

    # Return an empty string (all OK).
    return "";
}

This article was last updated 15th February 2025 20:35 Europe/London time based on the source file dated 13th February 2025 10:30 Europe/London time.