Collections functions
General functions
Node functions
Render functions
Theme permission functions
User functions
Resource 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 seperated 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 1984 to 2295

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(
=== 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_COLLECTION0ps_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 19th March 2024 11:05 Europe/London time based on the source file dated 15th March 2024 17:00 Europe/London time.