1perlfaq9(3)           User Contributed Perl Documentation          perlfaq9(3)
2
3
4

NAME

6       perlfaq9 - Web, Email and Networking
7

VERSION

9       version 5.20191102
10

DESCRIPTION

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