package MPMinus::Manual; # $Id: Manual.pod 269 2019-04-27 19:15:49Z minus $

=encoding utf-8

=head1 NAME

MPMinus::Manual - What is MPMinus, and how do I use it

=head1 TERMS

=over 8

=item B<Apache>

Apache web server version 2+. This web server is the only server supporting MPMinus.
MPMinus developed on the basis of the mod_perl2 model, as an Apache module.

=item B<m>

It is general MPMinus object that provides most methods for access to MPMinus functionality

=item B<mod_perl>

mod_perl brings together the full power of the Perl programming language and the Apache HTTP server.
You can use Perl to manage Apache, respond to requests for web pages and much more.

See L<http://perl.apache.org/>

=item B<MPM>

Acronym (ModPerl2 Minus), base namespace of all installed MPMinus projects.

=back

=head1 DESCRIPTION

MPMinus - mod_perl2 Web Application Framework

This framework will help You create mod_perl2 sites and REST API services

=head2 HOW TO START?

=over 8

=item B<INSTALL>

    cpan install MPMinus

or

    cpanm MPMinus

=item B<CREATING A NEW PROJECT>

    mpminus create Foo -d foo.localhost

Creates Foo project in ./foo.localhost

For about switches:

    mpminus -H

=item B<INSTALL PROJECT>

    cd ./foo.localhost
    perl Makefile.PL
    make
    make test
    make install
    make clean

Copy configuration file from ./src directory to Apache directory and restart it!

You can distributin your new created project using dist command:

    make dist

Done! Your tar.gz file is already here!

    MPM-Foo-1.00.tar.gz

=item B<TESTING>

    lynx foo.localhost

Profit!

=back

=head1 CONFIGURATION

Configuration parameters are initialized in the MPM::MyApp::Handlers package,
that cals via Apache web server config file.

    sub handler {
        my $r = shift;
        my $m = MPMinus->m;
        $m->conf_init($r, __PACKAGE__);

        ...

        my $project = $m->conf('project');

        ...
    }

For accessing to configuration variables you can use getter methods conf or
get_conf also setter method - set_conf. See L<MPMinus::Configuration>

=head2 APACHE PER-DIRECTORY VARIABLES

Apache per-directory variables is variables that specified by the PerlSetVar
and PerlAddVar directives in Apache config files, eg:

    PerlSetVar ModperlRoot /var/www/foo.localhost

For more information about per-directory variables see
L<http://perl.apache.org/docs/2.0/api/Apache2/RequestUtil.html>

For MPMinus projects allowed following directives:

=over 8

=item B<confdir>

    PerlSetVar confdir /var/www/foo.localhost

    my $confdir = $m->conf("confdir");

This directive sets directory (path) for searching configuration files of current project

Default: <DOCUMENT_ROOT>/conf

=item B<config, configfiles>

    PerlSetVar config /var/www/foo.localhost/foo.conf

    my $config_file = $m->conf("fileconf");
    my $config_file = $m->conf("configfiles")->[0];

In configuration file specifies configuration file.
In handlers the getter method $m->conf("configfiles") returns array of loaded
configuration files; the method $m->conf("fileconf") returns main loaded file

Default: <DOCUMENT_ROOT>/lc(<PROJCET_NAME>).conf

=item B<debug>

    PerlSetVar debug on

    $m->log_eror("Oops!") if $m->conf("debug");

Debug flag. The argument can be: on/off; enable/disable; yes/no; true/false and 1/0
The $m->conf("debug") returns boolean value: 1 -- on, 0 -- off

Default: off

=item B<modperlroot>

    PerlSetVar modperlroot /var/www/foo.localhost

    my $root = $m->conf("modperlroot");

Sets alternate of DOCUMENT_ROOT. Optional directive

Default eq <DOCUMENT_ROOT>

=back

=head2 READ-ONLY MPMINUS PARAMETERS

Parameters that You can read only

=head3 GENERAL PARAMETERS

=over 8

=item B<configloadstatus>

    print "Configuration has been loaded!" if $m->conf("configloadstatus");

Return boolean status of loading configuration files

Default: 0

=item B<hitime>

    print $m->conf("hitime"); # 1556209483.07221

Returns inited High-precision time value in seconds with 5-dig precision

=item B<locked_keys>

    my $array = $m->conf("locked_keys");

Returns reference to list of locked directives (for read only)

Default:

    [confdir, configloadstatus, debug, document_root, fileconf, hitime,
    http_host, https, locked_keys,logdir, modperl_root, package,
    prefix, project, remote_addr, remote_user, request_method,
    request_uri, server_admin, server_name, server_port, sid, url]

=item B<logdir>

    my $dir = $m->conf("logdir");

Returns system log-directory

Default: /var/log

=item B<package>

    my $vals = $m->conf("package"); # [MPM::Foo::Handlers, 0]
    my $package = $vals->[0];
    my $count = $vals->[1];

Returns reference to list. First value is package of initializer;
second value is counter, number of request on child process

=back

=head3 PROJECT PARAMETERS

Parameters describing the current project

=over 8

=item B<document_root, modperl_root>

    my $vals = $m->conf("document_root"); # /var/www/foo.localhost

Returns DOCUMENT_ROOT directory

=item B<prefix>

    my $prefix = $m->conf("prefix"); # foo

Returns the project name in lowercase

=item B<project>

    my $name = $m->conf("project"); # Foo

Returns the project name

=item B<server_admin>

    my $server_admin = $m->conf("server_admin"); # root@localhost

Returns SERVER_ADMIN

=item B<server_name>

    my $server_name = $m->conf("server_name"); # foo.localhost

Returns SERVER_NAME

=item B<server_port>

    my $server_port = $m->conf("server_port"); # 80

Returns SERVER_PORT

Default: 80

=item B<url>

    my $url = $m->conf("url"); # http://foo.localhost

Returns URL of this server

=back

=head3 REQUEST PARAMETERS

Parameters set for each HTTP request

=over 8

=item B<http_host>

    my $http_host = $m->conf("http_host"); # foo.localhost

Returns hostname from the "Host" header of request

=item B<https>

    print "Is HTTPS!" if $m->conf("https");

Returns HTTPS flag if current request was make via HTTPS protocol

Default: 0

=item B<remote_addr>

    my $remote_addr = $m->conf("remote_addr"); # 127.0.0.1

Returns current IP (IPv4 or IPv6) address of client

Default: 127.0.0.1

=item B<remote_user>

    my $remote_user = $m->conf("remote_user");

Returns current username from request header

=item B<request_method>

    my $request_method = $m->conf("request_method");

Returns HTTP current request method

Default: GET

=item B<request_uri>

    my $path_string = $m->conf("request_uri");

Returns path-string of current HTTP request

Default: /

Example: /mpminfo

=item B<sid>

    my $sid = $m->conf("sid"); # 802a28bffa20f4dc

Returns SessionID, 16 hex random characters, session signature

=back

=head2 DEPRECATED PARAMETERS

Following list contains deprecated and actually not existing parameters and directives.

=over 8

=item Flags

    _debug_, _errorsendmail_, _sendmail_, _syslog_

=item Files and directories

    file_connect, file_debug, file_error, file_mail, file_mpminfo,
    dir_cache, dir_conf, dir_db, dir_logs, dir_shtml

=item Misc

    errorlog, debuglog, url_shtml, urls, urls_shtml

=back

All listed parameters now are prohibited to use.

=head2 USER DEFINED MPMINUS PARAMETERS

All .conf files of current project contains only user directives.
The value of each directive of configuration files can be read or
modified using getters and setters

=head3 MULTISTORE CONFIGURATION

The following construction is used to configure the Multistore mechanism:

  <store foo>
    dsn   DBI:mysql:database=TEST;host=192.168.1.1
    user  login
    pass  password
    <Attr>
      mysql_enable_utf8 1
      RaiseError        0
      PrintError        0
    </Attr>
  </store>
  <store bar>
    dsn   DBI:Oracle:FOOSID
    user  login
    pass  password
    <Attr>
      RaiseError        0
      PrintError        0
    </Attr>
  </store>
  <store baz>
    dsn   DBI:Oracle:BARSID
    user  login
    pass  password
    <Attr>
      RaiseError        0
      PrintError        0
    </Attr>
  </store>

The accessor methods detailed described in L<MPMinus::Store::MultiStore/EXAMPLE> example

=head1 API

A classic example of a site created with MPMinus contains 5 mandatory files:

    MPM/MyApp.pm
    MPM/MyApp/Handlers.pm
    MPM/MyApp/Index.pm
    MPM/MyApp/Info.pm
    MPM/MyApp/Root.pm

For example see C<eg/MPM/MyApp.pm> file(s)

=over 8

=item B<MyApp.pm>

Your POD documentation file. Contains also the projects version and any meta-info
of Your project. Usually does not contain any program code.

=item B<Handlers.pm>

The first and very important file of Your project!
The file contains handler-definition for mod_perl2

See C<eg/MPM/MyApp/Handlers.pm> file for example

=item B<Index.pm>

The file contains list of enabled (plugged) modules of Your project.
By default enabled Root and Info modules only. For examle:

    use base qw/
        MPM::MyApp::Root
        MPM::MyApp::Info
    /;

You can extends this list yours modules

=item B<Info.pm>

Main information file. Contains usually code:

    sub record {
        (
            -uri      => '/mpminfo',
            -response => sub { shift->mpminfo },
        )
    }

=item B<Root.pm>

File of root controller ("/" string as path of URL)

See C<eg/MPM/MyApp/Root.pm> file for example

=back

=head2 MAIN METHODS

All main methods detailed described in L<MPMinus>

=head2 MVC SKEL TRANSACTION METHODS

The "MVC SKEL TRANSACTION" or "MST" -- is an ideological concept!

All methods of the MST detailed described in L<MPMinus::Transaction>

=head2 LOG METHODS

All log methods detailed described in L<MPMinus::Log>

=head1 APACHE HANDLERS

All available Apache handlers detailed described in mod_perl man pages L<http://perl.apache.org/>

The MPMinus by default only works with some of the basic HTTP handlers:

    PerlInitHandler
    PerlAccessHandler
    PerlAuthenHandler
    PerlAuthzHandler
    PerlTypeHandler
    PerlFixupHandler
    PerlResponseHandler
    PerlLogHandler
    PerlCleanupHandler

NOTE! MPMinus use modperl handler type only! See L<http://perl.apache.org/docs/2.0/user/config/config.html>

    SetHandler modperl
    PerlOptions +GlobalRequest

...or in Handlers.pm (handler):

    $r->handler('modperl')

See also L<MPMinus::BaseHandlers> and L<http://perl.apache.org/docs/2.0/user/handlers/http.html>

=head2 FILTERS

Filters are supported but not used in the MPMinus base configuration.

See L<http://perl.apache.org/docs/2.0/user/handlers/filters.html>

    sub handler {
        ...
        $r->add_output_filter(\&OutputFilterHandler);
        $r->add_input_filter(\&InputFilterHandler);
        ...
    }

See also L<MPMinus::BaseHandlers/FILTERS>

=head1 DISPATCHING

The MPMinus provides URL-to-Action dispatching using the "MVC SKEL Transaction" pattern

Supported dispatching types:

    Location, Regexp, LocArr и MixArr.

=over 8

=item B<Location>

Simple base dispatching by request URI (path based)

In Apache config file:

    <Location ~ ^/$>
        PerlInitHandler MPM::MyApp::Handlers
    </Location>

In MPM::MyApp::Root:

    sub record {
        (
            -uri => '/',
            ...
        )
    }

Fast and pretty!

=item B<Regexp>

Regexp dispatching

In Apache config file:

    <Location ~ ^\/[a-zA-Z0-9]{16}\/?$>
        PerlInitHandler MPM::MyApp::Handlers
    </Location>

In MPM::MyApp::Root:

    sub record {
        (
            -uri => ['REGEXP', 'root', qr/^\/[a-zA-Z0-9]{16}\/?$/],
            ...
        )
    }

=item B<LocArr>

Multiple path matching

In Apache config file:

    <Location ~ \.[mM][pP][mM]$>
        PerlInitHandler MPM::MyApp::Handlers
    </Location>
    <Location ~ ^/$>
        PerlInitHandler MPM::MyApp::Handlers
    </Location>

In MPM::MyApp::Root:

    sub record {
        (
            -uri => ['LOCARR', 'root', ['/','/root.mpm','/index.mpm']],
            ...
        )
    }

=item B<MixArr>

Mixed dispatching

In Apache config file:

    <Location ~ \.[mM][pP][mM]$>
        PerlInitHandler MPM::MyApp::Handlers
    </Location>
    <Location ~ ^/$>
        PerlInitHandler MPM::MyApp::Handlers
    </Location>

In MPM::MyApp::Root:

    sub record {
        (
            -uri => ['MIXARR', 'root', ['/', qr/^\/(root|index)\.mpm$/]],
            ...
        )
    }

=back

=head2 MVC TERMS

=over 8

=item B<Model>

See L<MPMinus::Store::MultiStore>, L<MPMinus::Store::MySQL>, L<MPMinus::Store::Oracle>,
L<MPMinus::Store::DBI>

=item B<View>

See L<Template::Toolkit>, L<Mason>, L<HTML::Template>, L<TemplateM> and etc.

=item B<Controller>

All Your MPM::MyApp::XXX classes!

=back

=head2 MVC SKEL TRANSACTION

The MVC SKEL Transaction is a pattern, concept of application development

    sub record {(
        ...

        # Обработчики
        -init     => \&hInit,
        -fixup    => \&hFixup,
        -response => \&hResponse,
        -cleanup  => \&hCleanup,

        -meta     => {
            registration => {
                handler => {
                    chck => \&registration_chck,
                    form => [\&registration_form, \&default_form,],
                    proc => \&registration_proc,
                    access => sub { 1 },
                    deny => sub { 1 },
                },
                content_type => 'text/html; charset=UTF-8',
                foo => 'qwe',
                bar => 'rty',
                baz => 123,
                ...
            },
    )}

The "registration" is a name from action QUERY_STRING param, e.g:

    ?action=registration

The "handler" contains MVC SKEL hooks definitions:

    chck, form, proc, access, deny

running phases of the hooks:

    Phase    Type
   --------+------
    access | DUAL
    deny   | HTTP
    chck   | BOOL
    proc   | HTTP
    form   | HTTP

=over 8

=item B<BOOL>

In array context only!

Each defined handler in array is executed until the value "0" (false)
or Apache2::Const::OK returns

=item B<HTTP>

In array context only!

Each defined handler in array is executed until an HTTP status value greater than
or equal to 300 (REDIRECTIONS AND ERRORS) is returned

=item B<DUAL>

Compilable with the pair of conditions BOOL and HTTP types

=back

The "MVC SKEL Transaction" behavior scheme:

                                  +-------+
    04/26/13                      | Start |
                                  +-------+
                                      |
                                ++---------++
                                || caccess ||
                                ++---------++
                                     |
                               status is true?
                                     /\
                      _____yes______/  \____no__
                     |              \  /        |
               status < 300?         \/         |
                     /\                    ++-------++
            ___yes__/  \____no___          || cdeny ||
           |        \  /         |         ++-------++
      event ~ go?    \/          |______________|
           /\                             |
     _no__/  \__yes__                     |
    |     \  /       |                    |
    |      \/   ++--------++              |
    |           || ccheck ||              |
    |           ++--------++              |
    |                |                    |
    |          status is true?            |
    |                /\                   |
    |         __no__/  \___yes_           |
    |        |      \  /       |          |
    |        |       \/   ++-------++     |
    |        |            || mproc ||     |
    |        |            ++-------++     |
    |________|_________________|          |
                               |          |
                         status < 300?    |
                               /\         |
                       __yes__/  \____no__|
                      |       \  /        |
                 ++-------++   \/         |
                 || vform ||              |
                 ++-------++              |
                      |                   |
                      |___________________|
                                     |
                                 +--------+
                                 | Finish |
                                 +--------+

=head1 EXAMPLES

See C<eg> on CPAN web-sites, e.g, L<https://metacpan.org/release/MPMinus>
Or content of a directory in distrib-tarball file

=head1 APACHE CONSTANTS

List of constants specific to Apache features see also
L<http://perl.apache.org/docs/2.0/api/Apache2/Const.html>

=head2 COMMON CONSTANTS

    -2  Apache2::Const::DONE
    -1  Apache2::Const::DECLINED
    0   Apache2::Const::OK
    302 Apache2::Const::REDIRECT
    401 Apache2::Const::AUTH_REQUIRED
    403 Apache2::Const::FORBIDDEN
    404 Apache2::Const::NOT_FOUND
    500 Apache2::Const::SERVER_ERROR

=head2 HTTP 1.1 STATUS CODES ORDERED BY NAMES

    202 Apache2::Const::HTTP_ACCEPTED
    502 Apache2::Const::HTTP_BAD_GATEWAY
    400 Apache2::Const::HTTP_BAD_REQUEST
    409 Apache2::Const::HTTP_CONFLICT
    100 Apache2::Const::HTTP_CONTINUE
    201 Apache2::Const::HTTP_CREATED
    417 Apache2::Const::HTTP_EXPECTATION_FAILED
        Apache2::Const::HTTP_FAILED_DEPENDENCY
    403 Apache2::Const::HTTP_FORBIDDEN
    504 Apache2::Const::HTTP_GATEWAY_TIME_OUT
    410 Apache2::Const::HTTP_GONE
        Apache2::Const::HTTP_INSUFFICIENT_STORAGE
    500 Apache2::Const::HTTP_INTERNAL_SERVER_ERROR
    411 Apache2::Const::HTTP_LENGTH_REQUIRED
        Apache2::Const::HTTP_LOCKED
    405 Apache2::Const::HTTP_METHOD_NOT_ALLOWED
    301 Apache2::Const::HTTP_MOVED_PERMANENTLY
    302 Apache2::Const::HTTP_MOVED_TEMPORARILY
    300 Apache2::Const::HTTP_MULTIPLE_CHOICES
        Apache2::Const::HTTP_MULTI_STATUS
    203 Apache2::Const::HTTP_NON_AUTHORITATIVE
    406 Apache2::Const::HTTP_NOT_ACCEPTABLE
        Apache2::Const::HTTP_NOT_EXTENDED
    404 Apache2::Const::HTTP_NOT_FOUND
    501 Apache2::Const::HTTP_NOT_IMPLEMENTED
    304 Apache2::Const::HTTP_NOT_MODIFIED
    204 Apache2::Const::HTTP_NO_CONTENT
    200 Apache2::Const::HTTP_OK
    206 Apache2::Const::HTTP_PARTIAL_CONTENT
    402 Apache2::Const::HTTP_PAYMENT_REQUIRED
    412 Apache2::Const::HTTP_PRECONDITION_FAILED
        Apache2::Const::HTTP_PROCESSING
    407 Apache2::Const::HTTP_PROXY_AUTHENTICATION_REQUIRED
    416 Apache2::Const::HTTP_RANGE_NOT_SATISFIABLE
    413 Apache2::Const::HTTP_REQUEST_ENTITY_TOO_LARGE
    408 Apache2::Const::HTTP_REQUEST_TIME_OUT
    414 Apache2::Const::HTTP_REQUEST_URI_TOO_LARGE
    205 Apache2::Const::HTTP_RESET_CONTENT
    303 Apache2::Const::HTTP_SEE_OTHER
    503 Apache2::Const::HTTP_SERVICE_UNAVAILABLE
    101 Apache2::Const::HTTP_SWITCHING_PROTOCOLS
    307 Apache2::Const::HTTP_TEMPORARY_REDIRECT
    401 Apache2::Const::HTTP_UNAUTHORIZED
        Apache2::Const::HTTP_UNPROCESSABLE_ENTITY
    415 Apache2::Const::HTTP_UNSUPPORTED_MEDIA_TYPE
        Apache2::Const::HTTP_UPGRADE_REQUIRED
    305 Apache2::Const::HTTP_USE_PROXY
        Apache2::Const::HTTP_VARIANT_ALSO_VARIES

=head2 HTTP 1.1 STATUS CODES

=over 8

=item Informational 1xx:

    100 HTTP_CONTINUE                        Continue
    101 HTTP_SWITCHING_PROTOCOLS             Switching Protocols

=item Successful 2xx:

    200 HTTP_OK                              OK
    201 HTTP_CREATED                         Created
    202 HTTP_ACCEPTED                        Accepted
    203 HTTP_NON_AUTHORITATIVE               Non-Authoritative Information
    204 HTTP_NO_CONTENT                      No Content
    205 HTTP_RESET_CONTENT                   Reset Content
    206 HTTP_PARTIAL_CONTENT                 Partial Content

=item Redirection 3xx:

    300 HTTP_MULTIPLE_CHOICES                Multiple Choices
    301 HTTP_MOVED_PERMANENTLY               Moved Permanently
    302 HTTP_MOVED_TEMPORARILY               Found
    303 HTTP_SEE_OTHER                       See Other
    304 HTTP_NOT_MODIFIED                    Not Modified
    305 HTTP_USE_PROXY                       Use Proxy
    306                                      (Unused)
    307 HTTP_TEMPORARY_REDIRECT              Temporary Redirect

=item Client Error 4xx:

    400 HTTP_BAD_REQUEST                     Bad Request
    401 HTTP_UNAUTHORIZED                    Unauthorized
    402 HTTP_PAYMENT_REQUIRED                Payment Required
    403 HTTP_FORBIDDEN                       Forbidden
    404 HTTP_NOT_FOUND                       Not Found
    405 HTTP_METHOD_NOT_ALLOWED              Method Not Allowed
    406 HTTP_NOT_ACCEPTABLE                  Not Acceptable
    407 HTTP_PROXY_AUTHENTICATION_REQUIRED   Proxy Authentication Required
    408 HTTP_REQUEST_TIMEOUT                 Request Timeout
    409 HTTP_CONFLICT                        Conflict
    410 HTTP_GONE                            Gone
    411 HTTP_LENGTH REQUIRED                 Length Required
    412 HTTP_PRECONDITION_FAILED             Precondition Failed
    413 HTTP_REQUEST_ENTITY_TOO_LARGE        Request Entity Too Large
    414 HTTP_REQUEST_URI_TOO_LARGE           Request-URI Too Long
    415 HTTP_UNSUPPORTED_MEDIA_TYPE          Unsupported Media Type
    416 HTTP_RANGE_NOT_SATISFIABLE           Requested Range Not Satisfiable
    417 HTTP_EXPECTATION_FAILED              Expectation Failed

=item Server Error 5xx:

    500 HTTP_INTERNAL_SERVER_ERROR           Internal Server Error
    501 HTTP_NOT IMPLEMENTED                 Not Implemented
    502 HTTP_BAD_GATEWAY                     Bad Gateway
    503 HTTP_SERVICE_UNAVAILABLE             Service Unavailable
    504 HTTP_GATEWAY_TIME_OUT                Gateway Timeout
    505 HTTP_VERSION_NOT_SUPPORTED           HTTP Version Not Supported

=back

=head1 THANKS

Thanks to Dmitry Klimov for technical translating C<http://fla-master.com>.

=head1 AUTHOR

Serż Minus (Sergey Lepenkov) L<http://www.serzik.com> E<lt>abalama@cpan.orgE<gt>

=head1 COPYRIGHT

Copyright (C) 1998-2019 D&D Corporation. All Rights Reserved

=head1 LICENSE

This program is free software; you can redistribute it and/or
modify it under the same terms as Perl itself.

See C<LICENSE> file and L<https://dev.perl.org/licenses/>

=cut

__END__
