File Coverage

blib/lib/Email/Sender/Role/CommonSending.pm
Criterion Covered Total %
statement 51 51 100.0
branch 8 10 80.0
condition 5 6 83.3
subroutine 15 15 100.0
pod 3 4 75.0
total 82 86 95.3


line stmt bran cond sub pod time code
1             package Email::Sender::Role::CommonSending 2.500;
2             # ABSTRACT: the common sending tasks most Email::Sender classes will need
3              
4 12     12   7264 use Moo::Role;
  12         30  
  12         75  
5              
6 12     12   3987 use Carp ();
  12         29  
  12         384  
7 12     12   5816 use Email::Abstract 3.006;
  12         309835  
  12         541  
8 12     12   5425 use Email::Sender::Success;
  12         41  
  12         363  
9 12     12   5321 use Email::Sender::Failure::Temporary;
  12         46  
  12         482  
10 12     12   6295 use Email::Sender::Failure::Permanent;
  12         64  
  12         360  
11 12     12   85 use Scalar::Util ();
  12         34  
  12         207  
12 12     12   6889 use Try::Tiny;
  12         17779  
  12         6014  
13              
14             #pod =head1 DESCRIPTION
15             #pod
16             #pod Email::Sender::Role::CommonSending provides a number of features that should
17             #pod ease writing new classes that perform the L role. Instead of
18             #pod writing a C method, implementors will need to write a smaller
19             #pod C method, which will be passed an L object and
20             #pod envelope containing C and C entries. The C entry will be
21             #pod guaranteed to be an array reference.
22             #pod
23             #pod A C method will also be provided as a shortcut for calling:
24             #pod
25             #pod Email::Sender::Success->new(...);
26             #pod
27             #pod A few other minor details are handled by CommonSending; for more information,
28             #pod consult the source.
29             #pod
30             #pod The methods documented here may be overridden to alter the behavior of the
31             #pod CommonSending role.
32             #pod
33             #pod =cut
34              
35             with 'Email::Sender';
36              
37             requires 'send_email';
38              
39             sub send {
40 30     30 0 23494 my ($self, $message, $env, @rest) = @_;
41 30         138 my $email = $self->prepare_email($message);
42 30         5862 my $envelope = $self->prepare_envelope($env);
43              
44             try {
45 30     30   1865 return $self->send_email($email, $envelope, @rest);
46             } catch {
47 11 50   11   390 Carp::confess('unknown error') unless my $err = $_;
48              
49 11 100 66     17698 if (
50 11         401 try { $err->isa('Email::Sender::Failure') }
51             and ! (my @tmp = $err->recipients)
52             ) {
53 6         23 $err->_set_recipients([ @{ $envelope->{to} } ]);
  6         173  
54             }
55              
56 11         448 die $err;
57             }
58 30         321 }
59              
60             #pod =method prepare_email
61             #pod
62             #pod This method is passed a scalar and is expected to return an Email::Abstract
63             #pod object. You probably shouldn't override it in most cases.
64             #pod
65             #pod =cut
66              
67             sub prepare_email {
68 35     35 1 3484 my ($self, $msg) = @_;
69              
70 35 50       113 Carp::confess("no email passed in to sender") unless defined $msg;
71              
72             # We check blessed because if someone would pass in a large message, in some
73             # perls calling isa on the string would create a package with the string as
74             # the name. If the message was (say) two megs, now you'd have a two meg hash
75             # key in the stash. Oops! -- rjbs, 2008-12-04
76 35 100 100     176 return $msg if Scalar::Util::blessed($msg) and eval { $msg->isa('Email::Abstract') };
  8         86  
77              
78 30         234 return Email::Abstract->new($msg);
79             }
80              
81             #pod =method prepare_envelope
82             #pod
83             #pod This method is passed a hashref and returns a new hashref that should be used
84             #pod as the envelope passed to the C method. This method is responsible
85             #pod for ensuring that the F entry is an array.
86             #pod
87             #pod =cut
88              
89             sub prepare_envelope {
90 30     30 1 93 my ($self, $env) = @_;
91              
92 30         59 my %new_env;
93 30 100       139 $new_env{to} = ref $env->{to} ? $env->{to} : [ grep {defined} $env->{to} ];
  12         53  
94 30         76 $new_env{from} = $env->{from};
95              
96 30         93 return \%new_env;
97             }
98              
99             #pod =method success
100             #pod
101             #pod ...
102             #pod return $self->success;
103             #pod
104             #pod This method returns a new Email::Sender::Success object. Arguments passed to
105             #pod this method are passed along to the Success's constructor. This is provided as
106             #pod a convenience for returning success from subclasses' C methods.
107             #pod
108             #pod =cut
109              
110             sub success {
111 13     13 1 51 my $self = shift;
112 13         229 my $success = Email::Sender::Success->new(@_);
113             }
114              
115 12     12   132 no Moo::Role;
  12         33  
  12         148  
116             1;
117              
118             __END__