general/canonicaluri

   1 # Blosxom Plugin: canonicaluri
   2 # Author(s): Frank Hecker <hecker@hecker.org>
   3 # Version: 0.6
   4 # Documentation: See the bottom of this file or type: perldoc canonicaluri
   5
   6 package canonicaluri;
   7
   8 use strict;
   9
  10 use CGI qw/:standard :netscape/;
  11
  12
  13 # --- Configurable variables -----
  14
  15 my $debug = 0;                          # set to 1 to print debug messages
  16
  17 # --------------------------------
  18
  19
  20 use vars qw!$redirecting!;              # 1 if we are redirecting, 0 if not
  21
  22
  23 sub start {
  24     warn "canonicaluri: start\n" if $debug > 1;
  25
  26     $redirecting = 0;
  27
  28     # Activate this plugin only when doing dynamic page generation.
  29     return $blosxom::static_or_dynamic eq 'dynamic' ? 1 : 0;
  30 }
  31
  32
  33 sub filter {
  34     my ($pkg, $files_ref) = @_;
  35
  36     warn "canonicaluri: filter\n" if $debug > 1;
  37
  38     warn "canonicaluri: \$blosxom::path_info: '" . $blosxom::path_info . "'\n"
  39         if $debug > 0;
  40     warn "canonicaluri: path_info(): '" . path_info() . "'\n"
  41         if $debug > 0;
  42
  43     # We need a copy of the original PATH_INFO, prior to Blosxom having
  44     # parsed it, because we need to see the original URI passed into
  45     # Blosxom, including whether the URI had an index.* component, trailing
  46     # slash, or file extension.
  47
  48     my $path = path_info();
  49
  50     # If the requested URI has an explicit "index.*" component where the
  51     # the file extension corresponds to the default flavour (typically
  52     #  "html") then we rewrite the URI to strip the "index.*" component
  53     # (and any spurious slashes after it) and leave a single trailing slash.
  54
  55     $path =~ s!/index\.$blosxom::default_flavour/*$!/!;
  56
  57     warn "canonicaluri: \$path (after index.html check): '" . $path . "'\n"
  58         if $debug > 0;
  59
  60     # If the requested URI has an explicit "index.*" component for any
  61     # flavour other than the default then we rewrite the URI if necessary
  62     # to remove any trailing slashes.
  63
  64     $path =~ s!/(index\.[^./]*)/*$!/$1!;
  65
  66     warn "canonicaluri: \$path (after index.foo check): '" . $path . "'\n"
  67         if $debug > 0;
  68
  69     # If the URI has a trailing slash but corresponds to an individual entry
  70     # then we rewrite the URI to remove the trailing slash. On the other hand
  71     # if the URI does not have a trailing slash but corresponds to a category
  72     # or archive page then we rewrite the URI to add the trailing slash
  73     # unless an "index.*" component is present in the URI.
  74
  75     if ($path =~ m!/$!) {               # trailing slash, remove if need be
  76         $blosxom::path_info =~ m!\.! and $path =~ s!/+$!!;
  77     } else {                            # no trailing slash, add if needed
  78         $blosxom::path_info !~ m!\.!
  79             and $path !~ m!/index.[^./]*$!
  80             and $path =~ s!$!/!;
  81     }
  82
  83     warn "canonicaluri: \$path (after slash check): '" . $path . "'\n"
  84         if $debug > 0;
  85
  86     # If the URI has a flavour extension corresponding to the default flavour
  87     # (typically "html") then we rewrite the URI to remove the extension.
  88
  89     $path =~ s!\.$blosxom::default_flavour!!;
  90
  91     warn "canonicaluri: \$path (after extension check): '" . $path . "'\n"
  92         if $debug > 0;
  93
  94     # If we have rewritten the URI then we force a redirect to the new URI.
  95
  96     $path ne path_info() and redirect($path);
  97
  98     1;
  99 }
 100
 101
 102 sub skip {
 103     warn "canonicaluri: skip\n" if $debug > 1;
 104
 105     return $redirecting;                # skip story generation if redirecting
 106 }
 107
 108
 109 sub redirect {
 110     my ($path) = @_;
 111
 112     my $uri = "$blosxom::url$path";
 113     $uri .= "?" . $ENV{QUERY_STRING} if $ENV{QUERY_STRING};
 114
 115     warn "canonicaluri: redirecting to '$uri'\n"
 116         if $debug > 0;
 117
 118     $blosxom::output = qq!Redirecting to <a href="$uri">$uri</a>.\n!;
 119     print "Status: 301\n";
 120     print "Location: $uri\n";
 121     $redirecting = 1;
 122 }
 123
 124 1;
 125
 126 __END__
 127
 128 =head1 NAME
 129
 130 Blosxom plugin: canonicaluri
 131
 132 =head1 SYNOPSIS
 133
 134 Have Blosxom force a redirect if a URI is not in canonical form with
 135 respect to index.* component, trailing slash, or flavour extension.
 136
 137 =head1 VERSION
 138
 139 0.6
 140
 141 =head1 AUTHOR
 142
 143 Frank Hecker <hecker@hecker.org>, http://www.hecker.org/
 144
 145 This plugin is now maintained by the Blosxom Sourceforge Team,
 146 <blosxom-devel@lists.sourceforge.net>.
 147
 148 =head1 DESCRIPTION
 149
 150 This plugin checks to see whether the requested URI is in the
 151 canonical form for the type of page being requested, and if necessary
 152 does a browser redirect to the canonical form of the URI. The
 153 canonical forms are defined as follows:
 154
 155 =over
 156
 157 =item * URIs for the blog root, categories, and date-based archives
 158 should not have an "index.*" component if the flavour being requested
 159 is the default flavour, and if an "index.*" component is not present
 160 then the URI should have one (and only one) trailing slash.
 161
 162 =item * URIs for individual entry pages should not have a trailing
 163 slash and also should not have a flavour extension if the flavour
 164 being requested is the default flavour (typically "html").
 165
 166 =back
 167
 168 For example, if you request the URIs
 169
 170   http://www.example.com/blog/foo
 171
 172 or
 173
 174   http://www.example.com/blog/foo/index.html
 175
 176 where "foo" is a category and "html" is the default flavour, this
 177 plugin will force a redirect to the canonical URI
 178
 179   http://www.example.com/blog/foo/
 180
 181 Similarly, if you request the URIs
 182
 183   http://www.example.com/blog/foo/
 184
 185 or
 186
 187   http://www.example.com/blog/foo.html
 188
 189 where "foo" is an individual entry and "html" is the default flavour,
 190 this plugin will force a redirect to the canonical URI
 191
 192   http://www.example.com/blog/foo
 193
 194 Note that using this plugin makes the most sense if you are also using
 195 URI rewriting rules to hide use of "/cgi-bin/blosxom.cgi" and support
 196 URIs similar to those traditionally used to access normal directories
 197 and files. This plugin should also be used in conjunction with the
 198 extensionless plugin in order to recognize extensionless URIs for
 199 individual entries. (See also below.)
 200
 201 This plugin was inspired by the redirect plugin by Fletcher T. Penny
 202 http://www.blosxom.com/plugins/general/redirect.htm and adapts a bit
 203 of its code.
 204
 205 =head1 INSTALLATION AND CONFIGURATION
 206
 207 Copy this plugin into your Blosxom plugin directory. You do not
 208 normally need to rename the plugin; however see the discussion below.
 209
 210 You can change the value of the variable C<$debug> to 1 if you need to
 211 debug the plugin's operation; the plugin will print to the web
 212 server's error log the original path component of the URI and the new
 213 URI if redirection is to be done.
 214
 215 This plugin supplies a filter and skip subroutine and can normally
 216 coexist with other plugins with filter subroutines. However this
 217 plugin needs to be run after the extensionless plugin, since it needs
 218 the flavour extension on C<$blosxom::path_info> (provided by
 219 extensionless if not already present) to distinguish between
 220 individual entry pages and other pages.
 221
 222 Finally, note that this plugin is sensitive to the exact URI rewriting
 223 rules you might have configured (e.g., in the Apache httpd.conf
 224 configuration file or in a .htaccess file). In particular, when
 225 rewriting URIs to add the name of the Blosxom CGI script (e.g.,
 226 "/cgi-bin/blosxom.cgi") you need to ensure that such rules preserve
 227 any trailing slash on the end of the URI and pass it on to Blosxom.
 228
 229 =head1 SEE ALSO
 230
 231 Blosxom Home/Docs/Licensing: http://blosxom.sourceforge.net/
 232
 233 Blosxom Plugin Docs: http://blosxom.sourceforge.net/documentation/users/plugins.html
 234
 235 =head1 BUGS
 236
 237 This plugin depends on the Apache URI rewriting rules to enforce the
 238 restriction that a URI should never have more than one trailing
 239 slash. The plugin as presently written can't handle this case properly
 240 because it depends on the C<path_info()> function to get the URI path,
 241 and the C<path_info()> value has already been stripped of any excess
 242 trailing slashes that might have been present in the original URI.
 243
 244 Please send bug reports and feedback to the Blosxom development mailing
 245 list <blosxom-devel@lists.sourceforge.net>.
 246
 247 =head1 LICENSE
 248
 249 canonicaluri Blosxom plugin Copyright 2004 Frank Hecker
 250
 251 Permission is hereby granted, free of charge, to any person obtaining a
 252 copy of this software and associated documentation files (the "Software"),
 253 to deal in the Software without restriction, including without limitation
 254 the rights to use, copy, modify, merge, publish, distribute, sublicense,
 255 and/or sell copies of the Software, and to permit persons to whom the
 256 Software is furnished to do so, subject to the following conditions:
 257
 258 The above copyright notice and this permission notice shall be included
 259 in all copies or substantial portions of the Software.
 260
 261 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
 262 IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
 263 FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
 264 THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR
 265 OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
 266 ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
 267 OTHER DEALINGS IN THE SOFTWARE.