$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 => \®istration_chck,
form => [\®istration_form, \&default_form,],
proc => \®istration_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/