Version 0.07

[catagits/Catalyst-Plugin-RequireSSL.git] / README

diff --git a/README b/README
index 72e8620..ec16a7a 100644 (file)
--- a/README
+++ b/README
@@ -3,19 +3,28 @@ NAME
 
 SYNOPSIS
         # in MyApp.pm
-        use Catalyst;
-        MyApp->setup( qw/RequireSSL/ );
-    
-        MyApp->config->{require_ssl} = {
-            https => 'secure.mydomain.com',
-            http => 'www.mydomain.com',
-            remain_in_ssl => 0,
-        };
+        use Catalyst qw/
+            RequireSSL
+        /;
+        __PACKAGE__->config(
+            require_ssl => {
+                https => 'secure.mydomain.com',
+                http => 'www.mydomain.com',
+                remain_in_ssl => 0,
+                no_cache => 0,
+                detach_on_redirect => 1,
+            },
+        );
+        __PACKAGE__->setup;
+
 
         # in any controller methods that should be secured
         $c->require_ssl;
 
 DESCRIPTION
+    Note: This module is considered to be deprecated for most purposes.
+    Consider using Catalyst::ActionRole::RequireSSL instead.
+
     Use this plugin if you wish to selectively force SSL mode on some of
     your web pages, for example a user login form or shopping cart.
 
@@ -37,22 +46,35 @@ CONFIGURATION
     values:
 
         https => $ssl_host
-    
+
     If your SSL domain name is different from your non-SSL domain, set this
     value.
 
         http => $non_ssl_host
-    
+
     If you have set the https value above, you must also set the hostname of
     your non-SSL server.
 
         remain_in_ssl
-    
+
     If you'd like your users to remain in SSL mode after visiting an
     SSL-required page, you can set this option to 1. By default, this option
     is disabled and users will be redirected back to non-SSL mode as soon as
     possible.
 
+        no_cache
+
+    If you have a wildcard certificate you will need to set this option if
+    you are using multiple domains on one instance of Catalyst.
+
+        detach_on_redirect
+
+    By default "$c->require_ssl" only calls "$c->response->redirect" but
+    does not stop request processing (so it returns and subsequent
+    statements are run). This is probably not what you want. If you set this
+    option to a true value "$c->require_ssl" will call "$c->detach" when it
+    redirects.
+
 METHODS
   require_ssl
     Call require_ssl in any controller method you wish to be secured.
@@ -62,6 +84,22 @@ METHODS
     The browser will be redirected to the same path on your SSL server. POST
     requests are never redirected.
 
+  allow_ssl
+    Call allow_ssl in any controller method you wish to access both in SSL
+    and non-SSL mode.
+
+        $c->allow_ssl;
+
+    The browser will not be redirected, independently of whether the request
+    was made to the SSL or non-SSL server.
+
+  setup
+    Disables this plugin if running under an engine which does not support
+    SSL.
+
+  finalize
+    Performs the redirect to SSL url if required.
+
 KNOWN ISSUES
     When viewing an SSL-required page that uses static files served from the
     Static plugin, the static files are redirected to the non-SSL path.
@@ -71,11 +109,15 @@ KNOWN ISSUES
     static files directly from your web server.
 
 SEE ALSO
-    Catalyst, Catalyst::Plugin::Static::Simple
+    Catalyst, Catalyst::ActionRole::RequireSSL,
+    Catalyst::Plugin::Static::Simple
 
 AUTHOR
     Andy Grundman, <andy@hybridized.org>
 
+CONTRIBUTORS
+    Simon Elliott <simon@browsing.co.uk> (support for wildcards)
+
 COPYRIGHT
     This program is free software, you can redistribute it and/or modify it
     under the same terms as Perl itself.