ch05_02.htm

用perl编写CGI的好书。本书从解释CGI和底层HTTP协议如何工作开始

<a name="INDEX-986" />HTTPS_ environment
variable. These variables are set by your web server only if you are
receiving a secure request via SSL. When <tt class="function">https</tt>
is called without arguments, it returns the value of the HTTPS
environment variable, which indicates whether the connection is
secure (its values are server-dependent).</p>
</div>



<a name="ch05-6-fm2xml" /><div class="sect3">
<h3 class="sect3">5.2.1.4. query_string</h3>


<p>The <tt class="function">query_string</tt>
<a name="INDEX-987" /> method does not do what you might
think since it does not correspond one-to-one with
<tt class="literal">$ENV{QUERY_STRING}</tt>.
<tt class="literal">$ENV{QUERY_STRING}</tt> holds the query portion of the
URL that called your CGI script. <tt class="function">query_string</tt>,
on the other hand, is dynamic, so if you modify any of the query
parameters in your script (see <a href="ch05_02.htm#ch05-43788">Section 5.2.2.1, "Modifying parameters"</a>
later in this chapter), then the value returned by
<tt class="function">query_string</tt> will include these new values. If
you want to know what the original query string was, then you should
refer to <tt class="literal">$ENV{QUERY_STRING}</tt> instead.</p>


<p>Also, if the request method is<a name="INDEX-988" /> POST, then
<tt class="function">query_string</tt> returns the POST parameters that
were submitted in the content of the request, and ignores any
parameters passed to the CGI script via the query string. This means
that if you create a form that submits its values via POST to a URL
that also contains a query string, you will not be able to access the
parameters on the query string via CGI.pm unless you make a slight
modification to CGI.pm to tell it to include parameters from the
original query string with POST requests. We'll see how to do
this in <a href="ch05_02.htm#ch05-40519">Section 5.2.2.2, "POST and the query string"</a> later in this chapter.</p>
</div>



<a name="ch05-7-fm2xml" /><div class="sect3">
<a name="INDEX-989" /><h3 class="sect3">5.2.1.5. 
self_url</h3>


<p>This method does not correspond to a standard CGI
<a name="INDEX-990" />environment variable, although you could
manually construct it from other environment variables. It provides
you with a <a name="INDEX-991" />URL that can call your CGI with the same
parameters. The path information is maintained and the query string
is set to the value of the <tt class="function">query_string</tt> method.</p>


<p>Note that this URL is not necessarily the same URL that was used to
call your CGI script. Your CGI script may have been called because of
an internal redirection by the web server. Also, because all of the
parameters are moved to the query string, this new URL is built to be
used with a GET request, even if the current request was a POST
request.</p>
</div>



<a name="ch05-8-fm2xml" /><div class="sect3">
<h3 class="sect3">5.2.1.6. url</h3>


<p>The <tt class="function">url </tt>
<a name="INDEX-992" />method functions similarly to the
<tt class="function">self_url</tt> method, except that it returns a URL to
the current CGI script without any parameters, i.e., no path
information and an empty query string.</p>
</div>



<a name="ch05-9-fm2xml" /><div class="sect3">
<h3 class="sect3">5.2.1.7. virtual_host</h3>


<p>The <tt class="function">virtual_host</tt>
<a name="INDEX-993" /> <a name="INDEX-994" />
<a name="INDEX-995" /> method is handy because it returns the
value of the HTTP_HOST environment variable, if set, and SERVER_NAME
otherwise. Remember that HTTP_HOST is the name of the web server as
the browser referred to it, which may differ if multiple domains
share the same IP address. HTTP_HOST is available only if the browser
supplied the Host HTTP header, added for HTTP 1.1.</p>
</div>
</div>




<a name="ch05-10-fm2xml" /><div class="sect2">
<h3 class="sect2">5.2.2. Accessing Parameters</h3>


<p><tt class="function">param</tt>
<a name="INDEX-996" /> is probably the most useful method
CGI.pm provides. It allows you to access the parameters submitted to
your <a name="INDEX-997" />CGI
script, whether these parameters come to you via a GET request or a
POST request. If you call <tt class="function">param</tt> without
arguments, it will return a list of all of the parameter names your
script received. If you provide a single argument to it, it will
return the value for the parameter with that name. If no parameter
with that name was submitted to your script, it returns
<tt class="literal">undef</tt>.</p>


<p>It is possible for your CGI script to receive multiple values for a
parameter with the same name. This happens when you create two form
elements with the same name or you have a select box that allows
multiple selections. In this case, <tt class="function">param</tt> returns
a list of all of the values if it is called in a list context and
just the first value if it is called in a scalar context. This may
sound a little complicated, but in practice it works such that you
should end up with what you expect. If you ask
<tt class="function">param</tt> for one value, you will get one value
(even if other values were also submitted), and if you ask it for a
list, you will always get a list (even if the list contains only one
element).</p>


<p><a href="ch05_02.htm#ch05-79926">Example 5-1</a> is a simple example that displays all
the parameters your script receives.</p>



<a name="ch05-79926" /><div class="example">
<h4 class="objtitle">Example 5-1. param_list.cgi </h4>

<blockquote><pre class="code">#!/usr/bin/perl -wT

use strict;
use CGI;

my $q = new CGI;
print $q-&gt;header( "text/plain" );

print "These are the parameters I received:\n\n";

my( $name, $value );

foreach $name ( $q-&gt;param ) {
    print "$name:\n";
    foreach $value ( $q-&gt;param( $name ) ) {
        print "  $value\n";
    }
}</pre></blockquote>
</div>


<p>If you call this CGI script with multiple parameters, like this:</p>


<blockquote><pre class="code">http://localhost/cgi/param_list.cgi?color=red&amp;color=blue&amp;shade=dark</pre></blockquote>


<p>you will get the following output:</p>


<blockquote><pre class="code">These are the parameters I received:

color:
  red
  blue
shade:
  dark</pre></blockquote>


<a name="ch05-43788" /><div class="sect3">
<h3 class="sect3">5.2.2.1. Modifying parameters</h3>


<p>CGI.pm also lets you add, modify, or delete the value of
<a name="INDEX-998" /> <a name="INDEX-999" />parameters within your script. To add or
modify a parameter, just pass <tt class="function">param</tt> more than
one argument. Using Perl's <tt class="literal">=&gt;</tt> operator
instead of a comma makes the code easier to read and allows you to
omit the quotes around the parameter name, so long as it's a
word (i.e., only contains includes letters, numbers, and underscores)
that does not conflict with a built-in function or keyword:</p>


<blockquote><pre class="code">$q-&gt;param( title =&gt; "Web Developer" );</pre></blockquote>


<p>You can create a parameter with multiple values by passing additional
arguments:</p>


<blockquote><pre class="code">$q-&gt;param( hobbies =&gt; "Biking", "Windsurfing", "Music" );</pre></blockquote>


<p>To <a name="INDEX-1000" />delete a parameter, use the
<tt class="function">delete</tt> method and provide the name of the
parameter:</p>


<blockquote><pre class="code">$q-&gt;delete( "age" );</pre></blockquote>


<p>You can clear all of the parameters with
<tt class="function">delete_all</tt>
<a name="INDEX-1001" />:</p>


<blockquote><pre class="code">$q-&gt;delete_all;</pre></blockquote>


<p>It may seem odd that you would ever want to modify parameters
yourself, since these will typically be coming from the user. Setting
parameters is useful for many reasons, but especially when assigning
default values to fields in forms. We will see how to do this later
in this chapter.</p>
</div>



<a name="ch05-40519" /><div class="sect3">
<h3 class="sect3">5.2.2.2. POST and the query string</h3>


<p><tt class="function">param</tt> automatically determines if the request
method is <a name="INDEX-1002" /> <a name="INDEX-1,003" />
<a name="INDEX-1004" />POST or GET. If it is POST, it reads any
parameters submitted to it from STDIN. If it is GET, it reads them
from the query string. It is possible to POST information to a URL
that already has a query string. In this case, you have two souces of
input data, and because CGI.pm determines what to do by checking the
request method, it will ignore the data in the query string.</p>


<p>You can change this behavior if you are willing to edit CGI.pm. In
fact, CGI.pm includes comments to help you do this. You can find this
block of code in the
<tt class="function">init</tt>
<a name="INDEX-1005" /> subroutine (the line number will
vary depending on the version of CGI.pm you have):</p>


<blockquote><pre class="code">if ($meth eq 'POST') {
    $self-&gt;read_from_client(\*STDIN,\$query_string,$content_length,0)
        if $content_length &gt; 0;
    # Some people want to have their cake and eat it too!
    # Uncomment this line to have the contents of the query string
    # APPENDED to the POST data.
    # $query_string .= (length($query_string) ? '&amp;' : '') . $ENV{'QUERY_STRING'}
             if defined $ENV{'QUERY_STRING'};
    last METHOD;
}</pre></blockquote>


<p>By removing the pound sign from the beginning of the line indicated,
you will be able to use POST and query string data together. Note
that the line you would need to uncomment is too long to display on
one line in this text, so it has been wrapped to the next line, but
it is just one line in CGI.pm.</p>
</div>



<a name="ch05-11-fm2xml" /><div class="sect3">
<h3 class="sect3">5.2.2.3. Index queries</h3>


<p>You may receive a query string that contains words that do not
comprise name-value pairs. The <a name="INDEX-1006" /> <a name="INDEX-1,007" /> <a name="INDEX-1,008" />&lt;ISINDEX&gt; HTML tag, which is not
used much anymore, creates a single text field along with a prompt to
enter search keywords. When a user enters words into this field and
presses Enter, it makes a new request for the same URL, adding the
text the user entered as the query string with keywords separated by
a <a name="INDEX-1009" /> <a name="INDEX-1,010" />plus sign (<tt class="literal">+</tt>), such
as this:</p>


<blockquote><pre class="code">http://www.localhost.com/cgi/lookup.cgi?cgi+perl</pre></blockquote>


<p>You can retrieve the list of keywords that the user entered by
calling <tt class="function">param</tt>
<a name="INDEX-1011" /> with "keywords" as the
name of the parameter or by calling the separate keywords method:</p>


<blockquote><pre class="code">my @words = $q-&gt;keywords;            # these lines do the same thing
my @words = $q-&gt;param( "keywords" );</pre></blockquote>


<p>These methods return index keywords only if CGI.pm finds no
name-value pair parameters, so you don't have to worry about
using "keywords" as the name of an element in your HTML
forms; it will work correctly. On the other hand, if you want to
<a name="INDEX-1012" />POST form data to a URL
with a keyword, CGI.pm cannot return that keyword to you. You must
use <tt class="literal">$ENV{QUERY_STRING}</tt>
<a name="INDEX-1013" /> to get it.</p>
</div>



<a name="ch05-12-fm2xml" /><div class="sect3">
<h3 class="sect3">5.2.2.4. Supporting image buttons as submit buttons</h3>


<p>Whether <a name="INDEX-1014" /> <a name="INDEX-1,015" />you use &lt;INPUT TYPE="IMAGE" &gt; or
&lt;INPUT TYPE="SUBMIT"&gt;, the form is still sent to the CGI
script. However, with the image button, the name is not transmitted
by itself. Instead, the web browser splits an image button name into
two separate variables:
<em class="emphasis">name.x</em>
<a name="INDEX-1016" />
and <em class="emphasis">name.y</em>.</p>


<p>If you want your program to support image and regular submit buttons
interchangeably, it is useful to translate the image button names to
normal submit button names. Thus, the main program code can use logic
based upon which submit button was clicked even if image buttons
later replace them.</p>


<p>To accomplish this, we can use the following code that will set a
form variable without the coordinates in the name for each variable
that ends in ".x":</p>


<blockquote><pre class="code">foreach ( $q-&gt;param ) {
    $q-&gt;param( $1, 1 ) if /(.*)\.x/;
}</pre></blockquote>
</div>
</div>




<a name="ch05-13-fm2xml" /><div class="sect2">
<h3 class="sect2">5.2.3. Exporting Parameters to a Namespace</h3>


<p>One of the problems with using a method to retrieve the value of a
<a name="INDEX-1017" />
<a name="INDEX-1018" />parameter is that it is more work
to embed the value in a string. If you wish to print the value of
someone's input, you can use an intermediate variable:</p>


<blockquote><pre class="code">my $name = $q-&gt;param( 'user' );
print "Hi, $user!";</pre></blockquote>


<p>Another way to do this is via an odd Perl construct that forces the
subroutine to be evaluated as part of an anonymous list:</p>


<blockquote><pre class="code">print "Hi, @{[ $q-&gt;param( 'user' ) ]}!";</pre></blockquote>


<p>The first solution is more work and the second can be hard to read.
Fortunately, there is a better way. If you know that you are going to
need to refer to many output values in a string, you can import all
the parameters as variables to a specified namespace:</p>


<blockquote><pre class="code">$q-&gt;import_names( "Q" );
print "Hi, $Q::user!";</pre></blockquote>


<p>Parameters with multiple values become arrays in the new namespace,
and any
<a name="INDEX-1019" />
<a name="INDEX-1020" />characters in a parameter name
other than a letter or number become underscores. You must provide a
namespace and cannot pass "main", the default namespace,
because that might create security risks.</p>


<p>The price you pay for this convenience is increased memory usage
because Perl must create an alias for each parameter.</p>
</div>




<a name="ch05-67561" /><div class="sect2">
<h3 class="sect2">5.2.4. File Uploads with CGI.pm</h3>


<p>As we mentioned in the last 
<a name="INDEX-1021" /> <a name="INDEX-1,022" />chapter, it is possible to create a
form with a
<em class="emphasis">multipart/form-data</em>
<a name="INDEX-1023" />
media type that permits users to upload files via
<a name="INDEX-1024" />HTTP. We avoided discussing how to handle
this type of input then because handling file uploads properly can be
quite complex. Fortunately, there's no need for us to do this
because, like other form input, CGI.pm provides a very simple