The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
OpenInteract-1.99_06
River stage zero No dependents
1 ++
/ OpenInteract2::Util

NAME

OpenInteract2::Util - Package of routines that do not really fit anywhere else

SYNOPSIS

 # Send a mail message from anywhere in the system
 eval { OpenInteract2::Util->send_mail({ to      => 'dingdong@nutty.com',
                                        from    => 'whynot@metoo.com',
                                        subject => 'wassup?',
                                        message => 'we must get down' }) };
 if ( $@ ) {
     warn "Mail not sent! Reason: $@";

 }
 
 # Send a mail message with an attachment from anywhere in the system
 
 eval { OpenInteract2::Util->send_mail({ to      => 'dingdong@nutty.com',
                                        from    => 'whynot@metoo.com',
                                        subject => 'wassup?',
                                        message => 'we must get down',
                                        attach  => 'uploads/data/item4.pdf' }) };
 if ( $@ ) {
     warn "Mail not sent! Reason: $@";
 }

DESCRIPTION

This class currently implments utilities for sending email. Note: In the future the mailing methods may move into a separate class (e.g., OpenInteract2::Mailer)

DATE METHODS

now( \%params )

Returns a formatted string representing right now.

Parameters:

  • format: Modifies how the date looks with a strftime format string. Defaults is '%Y-%m-%d %T'.

  • time: An epoch time. to use for the date. Defaults to right now.

today()

Returns today's date in a string formatted '%Y-%m-%d', e.g., '2003-04-01' for April 1, 2003.

time_duration_in_seconds( $time_spec )

Evaluates simple specifications like '3h' or '391m' into seconds. It does not handle complex ones like '3d5h'.

Available specs: m (minutes); h (hours); d (days)

Returns: number of equivalent seconds;

Example:

 OpenInteract2::Util->time_duration_in_seconds( '5m' );
 # returns: 300
 
 OpenInteract2::Util->time_duration_in_seconds( '5h' );
 # returns: 18000
 
 OpenInteract2::Util->time_duration_in_seconds( '2d' );
 # returns: 172800

FILE METHODS

read_file( $filename )

Slurps in $filename to scalar, returns contents.

read_file_lines( $filename )

Returns content of $filename as an arrayref of lines, with blanks and comments skipped.

read_perl_file( $filename )

Returns content of $flename evaluated as a Perl data structure.

is_same_file( $path_a, $path_b )

Returns result of comparing content in $path_a and content in $path_b -- that is, if their file sizes are equal and both have the same MD5 digest value this will return true, otherwise false.

digest_file( $filename )

Returns the hex MD5 digest of $filename contents. (See Digest::MD5 for restrictions, notably regarding unicode.)

digest_content( $content )

Returns the hex MD5 digest of $content. (See Digest::MD5 for restrictions, notably regarding unicode.)

decode_base64_and_store( \$base64_content, [ $output_file ] )

Decodes $base64_content (a scalar ref) and stores the decoded content in either $output_file (if specified) or in a new temp file. Note that while the temp file is marked for deletion once the program exits you should remove it once you're done.

Throws exception if we cannot write to $output_file or generate a temporary file according to File::Temp.

Returns: filename with decoded content

MAIL METHODS

send_email( \% )

Sends an email with the parameters you specify.

On success: returns a true value;

On failure: throws OpenInteract2::Exception with message containing the reason for the failure.

The parameters used are:

  • to ($) (required)

    To whom will the email be sent. Values such as:

     to => 'Mario <mario@donkeykong.com>'

    are fine.

  • from ($) (optional)

    From whom the email will be sent. If not specified we use the value of the mail.admin_email key in your server configuration.

  • message ($) (optional)

    What the email will say. Sending an email without any attachments and without a message is pointless but allowed. If you do not specify a message and you are sending attachments, we use a simple one for you.

  • subject ($) (optional)

    Subject of email. If not specified we use 'Mail sent from OpenInteract'

  • attach ($ or \@) (optional)

    One or more files to send as attachments to the message. (See below.)

Attachments

You can specify any type or size of file.

Example usages

 # Send a christmas list
 
 eval { OpenInteract2::Util->send_mail({
                         to      => 'santa@xmas.com',
                         subject => 'gimme gimme!',
                         message => join "\n", @xmas_list }) };
 if ( $@ ) {
   my $ei = OpenInteract2::Error->get;
   carp "Failed to send an email! Error: $ei->{system_msg}\n",
        "Mail to: $ei->{extra}{to}\nMessage: $ei->{extra}{message}";
 }
 
 # Send a really fancy christmas list
 
 eval { OpenInteract2::Util->send_mail({
                         to      => 'santa@xmas.com',
                         subject => 'Regarding needs for this year',
                         message => 'Attached is my Christmas list. ' .
                                    'Please acknowlege with fax.',
                         attach  => [ 'lists/my_xmas_list-1.39.pdf' ] }) };
 if ( $@ ) {
   my $ei = OpenInteract2::Error->get;
   carp "Failed to send an email! Error: $ei->{system_msg}\n",
        "Mail to: $ei->{extra}{to}\nMessage: $ei->{extra}{message}";
 }
 
 # Send an invoice for a customer; if it fails, throw an error which
 # propogates an alert queue for customer service reps
 
 eval { OpenInteract2::Util->send_mail({
                         to      => $customer->{email},
                         subject => "Order Reciept: #$order->{order_number}",
                         message => $myclass->create_invoice( $order ) }) };

SECURITY LEVELS

verbose_to_level( $verbose_security_level )

Translate a verbose security level (e.g., 'NONE', 'SUMMARY', 'READ', 'WRITE') into the relevant constant value from SPOPS::Secure. If $verbose_security_level doesn't match up to one, undef is returned.

FACTORY SUBCLASSES

find_factory_subclasses( $factory_class, [ @directories ] )

Finds and requires all subclasses of $factory_class using @directories as the list of directories from which to start. (If @directories not given we use @INC.) So to discover all the OpenInteract2::Manage subclasses from all Perl module directories we would do:

 OpenInteract2::Util->find_factory_subclasses(
     'OpenInteract2::Manage',
 );

And to find them from the temporary library directory, we'd do:

 my $temp_lib_dir = CTX->lookup_temp_lib_directory;
 OpenInteract2::Util->find_factory_subclasses(
     'OpenInteract2::Manage', $temp_lib_dir
 );

Returns a list of all the classes included.

TO DO

Spool email option

Instead of sending the email immediately, provide the option for saving the mail information to a spool directory ($CONFIG->{dir}{mail}) for later processing.

Also, have the option for spooling the mail on a sending error as well so someone can go back to the directory, edit it and resubmit it for processing.

Additional options

In the server configuration file, be able to do something like:

[mail] smtp_host = 127.0.0.1 admin_email = admin@mycompany.com content_email = content@mycompany.com max_size = 3000 # in KB header = email_header # template name footer = email_footer # template name

And have emails with a size > 'max_size' get rejected (or spooled), while all outgoing emails (unless otherwise specified) get the header and footer templates around the content.

SEE ALSO

Mail::Sendmail

MIME::Lite

COPYRIGHT

Copyright (c) 2001-2005 Chris Winters. All rights reserved.

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

AUTHORS

Chris Winters <chris@cwinters.com>