1PERLFAQ9(1) Perl Programmers Reference Guide PERLFAQ9(1)
2
3
4
6 perlfaq9 - Web, Email and Networking
7
9 This section deals with questions related to running web sites, sending
10 and receiving email as well as general networking.
11
12 Should I use a web framework?
13 Yes. If you are building a web site with any level of interactivity
14 (forms / users / databases), you will want to use a framework to make
15 handling requests and responses easier.
16
17 If there is no interactivity then you may still want to look at using
18 something like Template Toolkit <https://metacpan.org/module/Template>
19 or Plack::Middleware::TemplateToolkit so maintenance of your HTML files
20 (and other assets) is easier.
21
22 Which web framework should I use?
23 There is no simple answer to this question. Perl frameworks can run
24 everything from basic file servers and small scale intranets to massive
25 multinational multilingual websites that are the core to international
26 businesses.
27
28 Below is a list of a few frameworks with comments which might help you
29 in making a decision, depending on your specific requirements. Start by
30 reading the docs, then ask questions on the relevant mailing list or
31 IRC channel.
32
33 Catalyst
34 Strongly object-oriented and fully-featured with a long development
35 history and a large community and addon ecosystem. It is excellent
36 for large and complex applications, where you have full control
37 over the server.
38
39 Dancer
40 Young and free of legacy weight, providing a lightweight and easy
41 to learn API. Has a growing addon ecosystem. It is best used for
42 smaller projects and very easy to learn for beginners.
43
44 Mojolicious
45 Fairly young with a focus on HTML5 and real-time web technologies
46 such as WebSockets.
47
48 Web::Simple
49 Currently experimental, strongly object-oriented, built for speed
50 and intended as a toolkit for building micro web apps, custom
51 frameworks or for tieing together existing Plack-compatible web
52 applications with one central dispatcher.
53
54 All of these interact with or use Plack which is worth understanding
55 the basics of when building a website in Perl (there is a lot of useful
56 Plack::Middleware
57 <https://metacpan.org/search?q=plack%3A%3Amiddleware>).
58
59 What is Plack and PSGI?
60 PSGI is the Perl Web Server Gateway Interface Specification, it is a
61 standard that many Perl web frameworks use, you should not need to
62 understand it to build a web site, the part you might want to use is
63 Plack.
64
65 Plack is a set of tools for using the PSGI stack. It contains
66 middleware <https://metacpan.org/search?q=plack%3A%3Amiddleware>
67 components, a reference server and utilities for Web application
68 frameworks. Plack is like Ruby's Rack or Python's Paste for WSGI.
69
70 You could build a web site using Plack and your own code, but for
71 anything other than a very basic web site, using a web framework (that
72 uses Plack) is a better option.
73
74 How do I remove HTML from a string?
75 Use HTML::Strip, or HTML::FormatText which not only removes HTML but
76 also attempts to do a little simple formatting of the resulting plain
77 text.
78
79 How do I extract URLs?
80 HTML::SimpleLinkExtor will extract URLs from HTML, it handles anchors,
81 images, objects, frames, and many other tags that can contain a URL.
82 If you need anything more complex, you can create your own subclass of
83 HTML::LinkExtor or HTML::Parser. You might even use
84 HTML::SimpleLinkExtor as an example for something specifically suited
85 to your needs.
86
87 You can use URI::Find to extract URLs from an arbitrary text document.
88
89 How do I fetch an HTML file?
90 (contributed by brian d foy)
91
92 Use the libwww-perl distribution. The LWP::Simple module can fetch web
93 resources and give their content back to you as a string:
94
95 use LWP::Simple qw(get);
96
97 my $html = get( "http://www.example.com/index.html" );
98
99 It can also store the resource directly in a file:
100
101 use LWP::Simple qw(getstore);
102
103 getstore( "http://www.example.com/index.html", "foo.html" );
104
105 If you need to do something more complicated, you can use
106 LWP::UserAgent module to create your own user-agent (e.g. browser) to
107 get the job done. If you want to simulate an interactive web browser,
108 you can use the WWW::Mechanize module.
109
110 How do I automate an HTML form submission?
111 If you are doing something complex, such as moving through many pages
112 and forms or a web site, you can use WWW::Mechanize. See its
113 documentation for all the details.
114
115 If you're submitting values using the GET method, create a URL and
116 encode the form using the "query_form" method:
117
118 use LWP::Simple;
119 use URI::URL;
120
121 my $url = url('L<http://www.perl.com/cgi-bin/cpan_mod')>;
122 $url->query_form(module => 'DB_File', readme => 1);
123 $content = get($url);
124
125 If you're using the POST method, create your own user agent and encode
126 the content appropriately.
127
128 use HTTP::Request::Common qw(POST);
129 use LWP::UserAgent;
130
131 my $ua = LWP::UserAgent->new();
132 my $req = POST 'L<http://www.perl.com/cgi-bin/cpan_mod'>,
133 [ module => 'DB_File', readme => 1 ];
134 my $content = $ua->request($req)->as_string;
135
136 How do I decode or create those %-encodings on the web?
137 Most of the time you should not need to do this as your web framework,
138 or if you are making a request, the LWP or other module would handle it
139 for you.
140
141 To encode a string yourself, use the URI::Escape module. The
142 "uri_escape" function returns the escaped string:
143
144 my $original = "Colon : Hash # Percent %";
145
146 my $escaped = uri_escape( $original );
147
148 print "$escaped\n"; # 'Colon%20%3A%20Hash%20%23%20Percent%20%25'
149
150 To decode the string, use the "uri_unescape" function:
151
152 my $unescaped = uri_unescape( $escaped );
153
154 print $unescaped; # back to original
155
156 Remember not to encode a full URI, you need to escape each component
157 separately and then join them together.
158
159 How do I redirect to another page?
160 Most Perl Web Frameworks will have a mechanism for doing this, using
161 the Catalyst framework it would be:
162
163 $c->res->redirect($url);
164 $c->detach();
165
166 If you are using Plack (which most frameworks do), then
167 Plack::Middleware::Rewrite is worth looking at if you are migrating
168 from Apache or have URL's you want to always redirect.
169
170 How do I put a password on my web pages?
171 See if the web framework you are using has an authentication system and
172 if that fits your needs.
173
174 Alternativly look at Plack::Middleware::Auth::Basic, or one of the
175 other Plack authentication <https://metacpan.org/search?q=plack+auth>
176 options.
177
178 How do I make sure users can't enter values into a form that causes my CGI
179 script to do bad things?
180 (contributed by brian d foy)
181
182 You can't prevent people from sending your script bad data. Even if you
183 add some client-side checks, people may disable them or bypass them
184 completely. For instance, someone might use a module such as LWP to
185 submit to your web site. If you want to prevent data that try to use
186 SQL injection or other sorts of attacks (and you should want to), you
187 have to not trust any data that enter your program.
188
189 The perlsec documentation has general advice about data security. If
190 you are using the DBI module, use placeholder to fill in data. If you
191 are running external programs with "system" or "exec", use the list
192 forms. There are many other precautions that you should take, too many
193 to list here, and most of them fall under the category of not using any
194 data that you don't intend to use. Trust no one.
195
196 How do I parse a mail header?
197 Use the Email::MIME module. It's well-tested and supports all the
198 craziness that you'll see in the real world (comment-folding
199 whitespace, encodings, comments, etc.).
200
201 use Email::MIME;
202
203 my $message = Email::MIME->new($rfc2822);
204 my $subject = $message->header('Subject');
205 my $from = $message->header('From');
206
207 If you've already got some other kind of email object, consider passing
208 it to Email::Abstract and then using its cast method to get an
209 Email::MIME object:
210
211 my $mail_message_object = read_message();
212 my $abstract = Email::Abstract->new($mail_message_object);
213 my $email_mime_object = $abstract->cast('Email::MIME');
214
215 How do I check a valid mail address?
216 (partly contributed by Aaron Sherman)
217
218 This isn't as simple a question as it sounds. There are two parts:
219
220 a) How do I verify that an email address is correctly formatted?
221
222 b) How do I verify that an email address targets a valid recipient?
223
224 Without sending mail to the address and seeing whether there's a human
225 on the other end to answer you, you cannot fully answer part b, but the
226 Email::Valid module will do both part a and part b as far as you can in
227 real-time.
228
229 Our best advice for verifying a person's mail address is to have them
230 enter their address twice, just as you normally do to change a
231 password. This usually weeds out typos. If both versions match, send
232 mail to that address with a personal message. If you get the message
233 back and they've followed your directions, you can be reasonably
234 assured that it's real.
235
236 A related strategy that's less open to forgery is to give them a PIN
237 (personal ID number). Record the address and PIN (best that it be a
238 random one) for later processing. In the mail you send, include a link
239 to your site with the PIN included. If the mail bounces, you know it's
240 not valid. If they don't click on the link, either they forged the
241 address or (assuming they got the message) following through wasn't
242 important so you don't need to worry about it.
243
244 How do I decode a MIME/BASE64 string?
245 The MIME::Base64 package handles this as well as the MIME/QP encoding.
246 Decoding base 64 becomes as simple as:
247
248 use MIME::Base64;
249 my $decoded = decode_base64($encoded);
250
251 The Email::MIME module can decode base 64-encoded email message parts
252 transparently so the developer doesn't need to worry about it.
253
254 How do I find the user's mail address?
255 Ask them for it. There are so many email providers available that it's
256 unlikely the local system has any idea how to determine a user's email
257 address.
258
259 The exception is for organization-specific email (e.g.
260 foo@yourcompany.com) where policy can be codified in your program. In
261 that case, you could look at $ENV{USER}, $ENV{LOGNAME}, and
262 getpwuid($<) in scalar context, like so:
263
264 my $user_name = getpwuid($<)
265
266 But you still cannot make assumptions about whether this is correct,
267 unless your policy says it is. You really are best off asking the user.
268
269 How do I send email?
270 Use the Email::MIME and Email::Sender::Simple modules, like so:
271
272 # first, create your message
273 my $message = Email::MIME->create(
274 header_str => [
275 From => 'you@example.com',
276 To => 'friend@example.com',
277 Subject => 'Happy birthday!',
278 ],
279 attributes => {
280 encoding => 'quoted-printable',
281 charset => 'ISO-8859-1',
282 },
283 body_str => "Happy birthday to you!\n",
284 );
285
286 use Email::Sender::Simple qw(sendmail);
287 sendmail($message);
288
289 By default, Email::Sender::Simple will try `sendmail` first, if it
290 exists in your $PATH. This generally isn't the case. If there's a
291 remote mail server you use to send mail, consider investigating one of
292 the Transport classes. At time of writing, the available transports
293 include:
294
295 Email::Sender::Transport::Sendmail
296 This is the default. If you can use the mail(1) or mailx(1) program
297 to send mail from the machine where your code runs, you should be
298 able to use this.
299
300 Email::Sender::Transport::SMTP
301 This transport contacts a remote SMTP server over TCP. It
302 optionally uses SSL and can authenticate to the server via SASL.
303
304 Email::Sender::Transport::SMTP::TLS
305 This is like the SMTP transport, but uses TLS security. You can
306 authenticate with this module as well, using any mechanisms your
307 server supports after STARTTLS.
308
309 Telling Email::Sender::Simple to use your transport is straightforward.
310
311 sendmail(
312 $message,
313 {
314 transport => $email_sender_transport_object,
315 }
316 );
317
318 How do I use MIME to make an attachment to a mail message?
319 Email::MIME directly supports multipart messages. Email::MIME objects
320 themselves are parts and can be attached to other Email::MIME objects.
321 Consult the Email::MIME documentation for more information, including
322 all of the supported methods and examples of their use.
323
324 How do I read email?
325 Use the Email::Folder module, like so:
326
327 use Email::Folder;
328
329 my $folder = Email::Folder->new('/path/to/email/folder');
330 while(my $message = $folder->next_message) {
331 # next_message returns Email::Simple objects, but we want
332 # Email::MIME objects as they're more robust
333 my $mime = Email::MIME->new($message->as_string);
334 }
335
336 There are different classes in the Email::Folder namespace for
337 supporting various mailbox types. Note that these modules are generally
338 rather limited and only support reading rather than writing.
339
340 How do I find out my hostname, domainname, or IP address?
341 gethostbyname, Socket, Net::Domain, Sys::Hostname" (contributed by
342 brian d foy)
343
344 The Net::Domain module, which is part of the Standard Library starting
345 in Perl 5.7.3, can get you the fully qualified domain name (FQDN), the
346 host name, or the domain name.
347
348 use Net::Domain qw(hostname hostfqdn hostdomain);
349
350 my $host = hostfqdn();
351
352 The Sys::Hostname module, part of the Standard Library, can also get
353 the hostname:
354
355 use Sys::Hostname;
356
357 $host = hostname();
358
359 The Sys::Hostname::Long module takes a different approach and tries
360 harder to return the fully qualified hostname:
361
362 use Sys::Hostname::Long 'hostname_long';
363
364 my $hostname = hostname_long();
365
366 To get the IP address, you can use the "gethostbyname" built-in
367 function to turn the name into a number. To turn that number into the
368 dotted octet form (a.b.c.d) that most people expect, use the
369 "inet_ntoa" function from the Socket module, which also comes with
370 perl.
371
372 use Socket;
373
374 my $address = inet_ntoa(
375 scalar gethostbyname( $host || 'localhost' )
376 );
377
378 How do I fetch/put an (S)FTP file?
379 Net::FTP, and Net::SFTP allow you to interact with FTP and SFTP (Secure
380 FTP) servers.
381
382 How can I do RPC in Perl?
383 Use one of the RPC modules( <https://metacpan.org/search?q=RPC> ).
384
386 Copyright (c) 1997-2010 Tom Christiansen, Nathan Torkington, and other
387 authors as noted. All rights reserved.
388
389 This documentation is free; you can redistribute it and/or modify it
390 under the same terms as Perl itself.
391
392 Irrespective of its distribution, all code examples in this file are
393 hereby placed into the public domain. You are permitted and encouraged
394 to use this code in your own programs for fun or for profit as you see
395 fit. A simple comment in the code giving credit would be courteous but
396 is not required.
397
398
399
400perl v5.16.3 2013-03-04 PERLFAQ9(1)