view release on metacpan or  search on metacpan

lib/CGI/Session.pm  view on Meta::CPAN

    {
        Directory => Value 1,
        NoFlock   => Value 2,
        UMask     => Value 3
    }

If your $dsn uses db-based storage, then this hashref contains (up to) 3 keys, and looks like:

    {
        DataSource => Value 1,
        User       => Value 2,
        Password   => Value 3
    }

These 3 form the DSN, username and password used by DBI to control access to your database server,
and hence are only relevant when using db-based sessions.

The default value of this hashref is undef.

=back

B<Note:> find() is meant to be convenient, not necessarily efficient. It's best suited in cron scripts.

=head2 name($new_name)

The $new_name parameter is optional. If supplied it sets the query or cookie parameter name to be used.

It defaults to I<$CGI::Session::NAME>, which defaults to I<CGISESSID>.

You are strongly discouraged from using the global variable I<$CGI::Session::NAME>, since it is
deprecated (as are all global variables) and will be removed in a future version of this module.

Return value: The current query or cookie parameter name.

=head1 MISCELLANEOUS METHODS

=head2 remote_addr()

Returns the remote address of the user who created the session for the first time. Returns undef if variable REMOTE_ADDR wasn't present in the environment when the session was created.

=cut

sub remote_addr {   return $_[0]->{_DATA}->{_SESSION_REMOTE_ADDR}   }

=pod

=head2 errstr()

Class method. Returns last error message from the library.

=head2 dump()

Returns a dump of the session object. Useful for debugging purposes only.

=head2 header()

A wrapper for C<CGI>'s header() method. Calling this method
is equivalent to something like this:

    $cookie = CGI::Cookie->new(-name=>$session->name, -value=>$session->id);
    print $cgi->header(-cookie=>$cookie, @_);

You can minimize the above into:

    print $session->header();

It will retrieve the name of the session cookie from C<$session->name()> which defaults to C<$CGI::Session::NAME>. If you want to use a different name for your session cookie, do something like this before creating session object:

    CGI::Session->name("MY_SID");
    $session = CGI::Session->new(undef, $cgi, \%attrs);

Now, $session->header() uses "MY_SID" as the name for the session cookie. For all additional options that can
be passed, see the C<header()> docs in C<CGI>.

=head2 query()

Returns query object associated with current session object. Default query object class is C<CGI>.

=head2 DEPRECATED METHODS

These methods exist solely for for compatibility with CGI::Session 3.x.

=head3 close()

Closes the session. Using flush() is recommended instead, since that's exactly what a call
to close() does now.

=head1 DISTRIBUTION

CGI::Session consists of several components such as L<drivers|"DRIVERS">, L<serializers|"SERIALIZERS"> and L<id generators|"ID GENERATORS">. This section lists what is available.

=head2 DRIVERS

The following drivers are included in the standard distribution:

=over 4

=item *

L<file|CGI::Session::Driver::file> - default driver for storing session data in plain files. Full name: B<CGI::Session::Driver::file>

=item *

L<db_file|CGI::Session::Driver::db_file> - for storing session data in BerkelyDB. Requires: L<DB_File>.
Full name: B<CGI::Session::Driver::db_file>

=item *

L<mysql|CGI::Session::Driver::mysql> - for storing session data in MySQL tables. Requires L<DBI|DBI> and L<DBD::mysql|DBD::mysql>.
Full name: B<CGI::Session::Driver::mysql>

=item *

L<sqlite|CGI::Session::Driver::sqlite> - for storing session data in SQLite. Requires L<DBI|DBI> and L<DBD::SQLite|DBD::SQLite>.
Full name: B<CGI::Session::Driver::sqlite>

=back

Other drivers are available from CPAN.

lib/CGI/Session.pm  view on Meta::CPAN

=back

=head1 A Warning about UTF8

You are strongly encouraged to refer to, at least, the first of these articles, for help with UTF8.

L<http://en.wikibooks.org/wiki/Perl_Programming/Unicode_UTF-8>

L<http://perl.bristolbath.org/blog/lyle/2008/12/giving-cgiapplication-internationalization-i18n.html>

L<http://metsankulma.homelinux.net/cgi-bin/l10n_example_4/main.cgi>

L<http://rassie.org/archives/247>

L<http://www.di-mgt.com.au/cryptoInternational2.html>

Briefly, these are the issues:

=over 4

=item The file containing the source code of your program

Consider "use utf8;" or "use encoding 'utf8';".

=item Influencing the encoding of the program's input

Use:

    binmode STDIN, ":encoding(utf8)";.

    Of course, the program can get input from other sources, e.g. HTML template files, not just STDIN.

=item Influencing the encoding of the program's output

Use:

    binmode STDOUT, ":encoding(utf8)";

    When using CGI.pm, you can use $q->charset('UTF-8'). This is the same as passing 'UTF-8' to CGI's C<header()> method.

    Alternately, when using CGI::Session, you can use $session->header(charset => 'utf-8'), which will be
    passed to the query object's C<header()> method. Clearly this is preferable when the query object might not be
    of type CGI.

    See L</header()> for a fuller discussion of the use of the C<header()> method in conjunction with cookies.

=back

=head1 TRANSLATIONS

This document is also available in Japanese.

=over 4

=item o

Translation based on 4.14: http://digit.que.ne.jp/work/index.cgi?Perldoc/ja

=item o

Translation based on 3.11, including Cookbook and Tutorial: http://perldoc.jp/docs/modules/CGI-Session-3.11/

=back

=head1 CREDITS

CGI::Session evolved to what it is today with the help of following developers. The list doesn't follow any strict order, but somewhat chronological. Specifics can be found in F<Changes> file

=over 4

=item Andy Lester

=item Brian King E<lt>mrbbking@mac.comE<gt>

=item Olivier Dragon E<lt>dragon@shadnet.shad.caE<gt>

=item Adam Jacob E<lt>adam@sysadminsith.orgE<gt>

=item Igor Plisco E<lt>igor@plisco.ruE<gt>

=item Mark Stosberg

=item Matt LeBlanc E<lt>mleblanc@cpan.orgE<gt>

=item Shawn Sorichetti

=item Ron Savage

=item Rhesa Rozendaal

He suggested Devel::Cycle to help debugging.

=back

Also, many people on the CGI::Application and CGI::Session mailing lists have contributed ideas and
suggestions, and battled publicly with bugs, all of which has helped.

=head1 COPYRIGHT

Copyright (C) 2001-2005 Sherzod Ruzmetov E<lt>sherzodr@cpan.orgE<gt>. All rights reserved.
This library is free software. You can modify and or distribute it under the same terms as Perl itself.

=head1 PUBLIC CODE REPOSITORY

You can see what the developers have been up to since the last release by
checking out the code repository. You can browse the git repository from here:

 http://github.com/cromedome/cgi-session/tree/master

Or check out the code with:

 git clone git://github.com/cromedome/cgi-session.git

=head1 SUPPORT

If you need help using CGI::Session, ask on the mailing list. You can ask the
list by sending your questions to cgi-session-user@lists.sourceforge.net .

You can subscribe to the mailing list at https://lists.sourceforge.net/lists/listinfo/cgi-session-user .

Bug reports can be submitted at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=CGI-Session

=head1 AUTHOR

Sherzod Ruzmetov C<sherzodr@cpan.org>

Mark Stosberg became a co-maintainer during the development of 4.0. C<markstos@cpan.org>.

Ron Savage became a co-maintainer during the development of 4.30. C<rsavage@cpan.org>.

If you would like support, ask on the mailing list as describe above. The
maintainers and other users are subscribed to it. 

=head1 SEE ALSO 

To learn more both about the philosophy and CGI::Session programming style,
consider the following:

=over 4

=item *

L<CGI::Session::Tutorial|CGI::Session::Tutorial> - extended CGI::Session manual. Also includes library architecture and driver specifications.

=item *

We also provide mailing lists for CGI::Session users. To subscribe to the list
or browse the archives visit
https://lists.sourceforge.net/lists/listinfo/cgi-session-user

=item * B<RFC 2109> - The primary spec for cookie handing in use, defining the  "Cookie:" and "Set-Cookie:" HTTP headers.
Available at L<http://www.ietf.org/rfc/rfc2109.txt>. A newer spec, RFC 2965 is meant to obsolete it with "Set-Cookie2" 
and "Cookie2" headers, but even of 2008, the newer spec is not widely supported. See L<http://www.ietf.org/rfc/rfc2965.txt>

=item *

L<Apache::Session|Apache::Session> - an alternative to CGI::Session.

=back

=cut

1;