File	Date	Author	Commit
bin	2022-01-23	Sergey Lepenkov	[4e7212] Initial commit
eg	2022-01-23	Sergey Lepenkov	[4e7212] Initial commit
lib	2022-01-23	Sergey Lepenkov	[4e7212] Initial commit
src	2022-10-12	Serz Minus	[b297f2] Added new release for jammy
t	2022-01-23	Sergey Lepenkov	[4e7212] Initial commit
Changes	2022-01-23	Sergey Lepenkov	[4e7212] Initial commit
INSTALL	2022-01-23	Sergey Lepenkov	[4e7212] Initial commit
LICENSE	2022-01-23	Sergey Lepenkov	[4e7212] Initial commit
MANIFEST	2022-01-23	Sergey Lepenkov	[4e7212] Initial commit
Makefile.PL	2022-01-23	Sergey Lepenkov	[4e7212] Initial commit
README	2022-01-23	Sergey Lepenkov	[4e7212] Initial commit
README.HEAD	2022-01-23	Sergey Lepenkov	[4e7212] Initial commit
TODO	2022-01-23	Sergey Lepenkov	[4e7212] Initial commit

Read Me

$Id: README 284 2019-05-18 08:18:32Z minus $
.___  ___. .______   .___  ___.  __  .__   __.  __   __    ____.
|   \/   | |   _  \  |   \/   | |  | |  \ |  | |  | |  |  /    |
|  \  /  | |  |_)  | |  \  /  | |  | |   \|  | |  | |  | |   (-`
|  |\/|  | |   ___/  |  |\/|  | |  | |  . `  | |  | |  |  \   \
|  |  |  | |  |      |  |  |  | |  | |  |\   | |  `-'  | .-)   |
|__|  |__| | _|      |__|  |__| |__| |__| \__|  \_____/  |____/

NAME

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

TERMS

    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.

    m

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

    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 http://perl.apache.org/

    MPM

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

DESCRIPTION

    MPMinus - mod_perl2 Web Application Framework

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

 HOW TO START?

    INSTALL

          cpan install MPMinus

      or

          cpanm MPMinus

    CREATING A NEW PROJECT

          mpminus create Foo -d foo.localhost

      Creates Foo project in ./foo.localhost

      For about switches:

          mpminus -H

    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

    TESTING

          lynx foo.localhost

      Profit!

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
    MPMinus::Configuration

 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
    http://perl.apache.org/docs/2.0/api/Apache2/RequestUtil.html

    For MPMinus projects allowed following directives:

    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

    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

    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

    modperlroot

          PerlSetVar modperlroot /var/www/foo.localhost
      
          my $root = $m->conf("modperlroot");

      Sets alternate of DOCUMENT_ROOT. Optional directive

      Default eq <DOCUMENT_ROOT>

 READ-ONLY MPMINUS PARAMETERS

    Parameters that You can read only

  GENERAL PARAMETERS

    configloadstatus

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

      Return boolean status of loading configuration files

      Default: 0

    hitime

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

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

    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]

    logdir

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

      Returns system log-directory

      Default: /var/log

    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

  PROJECT PARAMETERS

    Parameters describing the current project

    document_root, modperl_root

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

      Returns DOCUMENT_ROOT directory

    prefix

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

      Returns the project name in lowercase

    project

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

      Returns the project name

    server_admin

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

      Returns SERVER_ADMIN

    server_name

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

      Returns SERVER_NAME

    server_port

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

      Returns SERVER_PORT

      Default: 80

    url

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

      Returns URL of this server

  REQUEST PARAMETERS

    Parameters set for each HTTP request

    http_host

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

      Returns hostname from the "Host" header of request

    https

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

      Returns HTTPS flag if current request was make via HTTPS protocol

      Default: 0

    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

    remote_user

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

      Returns current username from request header

    request_method

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

      Returns HTTP current request method

      Default: GET

    request_uri

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

      Returns path-string of current HTTP request

      Default: /

      Example: /mpminfo

    sid

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

      Returns SessionID, 16 hex random characters, session signature

 DEPRECATED PARAMETERS

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

    Flags

          _debug_, _errorsendmail_, _sendmail_, _syslog_

    Files and directories

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

    Misc

          errorlog, debuglog, url_shtml, urls, urls_shtml

    All listed parameters now are prohibited to use.

 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

  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 "EXAMPLE" in
    MPMinus::Store::MultiStore example

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 eg/MPM/MyApp.pm file(s)

    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.

    Handlers.pm

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

      See eg/MPM/MyApp/Handlers.pm file for example

    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

    Info.pm

      Main information file. Contains usually code:

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

    Root.pm

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

      See eg/MPM/MyApp/Root.pm file for example

 MAIN METHODS

    All main methods detailed described in MPMinus

 MVC SKEL TRANSACTION METHODS

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

    All methods of the MST detailed described in MPMinus::Transaction

 LOG METHODS

    All log methods detailed described in MPMinus::Log

APACHE HANDLERS

    All available Apache handlers detailed described in mod_perl man pages
    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
    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 MPMinus::BaseHandlers and
    http://perl.apache.org/docs/2.0/user/handlers/http.html

 FILTERS

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

    See 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 "FILTERS" in MPMinus::BaseHandlers

DISPATCHING

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

    Supported dispatching types:

        Location, Regexp, LocArr и MixArr.

    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!

    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}\/?$/],
                  ...
              )
          }

    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']],
                  ...
              )
          }

    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$/]],
                  ...
              )
          }

 MVC TERMS

    Model

      See MPMinus::Store::MultiStore, MPMinus::Store::MySQL,
      MPMinus::Store::Oracle, MPMinus::Store::DBI

    View

      See Template::Toolkit, Mason, HTML::Template, TemplateM and etc.

    Controller

      All Your MPM::MyApp::XXX classes!

 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

    BOOL

      In array context only!

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

    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

    DUAL

      Compilable with the pair of conditions BOOL and HTTP types

    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 |
                                     +--------+

EXAMPLES

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

APACHE CONSTANTS

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

 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

 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

 HTTP 1.1 STATUS CODES

    Informational 1xx:

          100 HTTP_CONTINUE                        Continue
          101 HTTP_SWITCHING_PROTOCOLS             Switching Protocols

    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

    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

    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

    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

THANKS

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

AUTHOR

    Serż Minus (Sergey Lepenkov) http://www.serzik.com <abalama@cpan.org>

COPYRIGHT

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

LICENSE

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

    See LICENSE file and https://dev.perl.org/licenses/