README.md
1[](https://travis-ci.org/tokuhirom/Amon)
2# NAME
3
4Amon2 - lightweight web application framework
5
6# SYNOPSIS
7
8 package MyApp;
9 use parent qw/Amon2/;
10 use Amon2::Config::Simple;
11 sub load_config { Amon2::Config::Simple->load(shift) }
12
13# DESCRIPTION
14
15Amon2 is simple, readable, extensible, **STABLE**, **FAST** web application framework based on [Plack](https://metacpan.org/pod/Plack).
16
17# METHODS
18
19## CLASS METHODS for `Amon2` class
20
21- my $c = MyApp->context();
22
23 Get the context object.
24
25- MyApp->set\_context($c)
26
27 Set your context object(INTERNAL USE ONLY).
28
29# CLASS METHODS for inherited class
30
31- `MyApp->config()`
32
33 This method returns configuration information. It is generated by `MyApp->load_config()`.
34
35- `MyApp->mode_name()`
36
37 This is a mode name for Amon2. The default implementation of this method is:
38
39 sub mode_name { $ENV{PLACK_ENV} }
40
41 You can override this method if you want to determine the mode by other method.
42
43- `MyApp->new()`
44
45 Create new context object.
46
47- `MyApp->bootstrap()`
48
49 my $c = MyApp->bootstrap();
50
51 Create new context object and set it to global context. When you are writing CLI script, setup the global context object by this method.
52
53- `MyApp->base_dir()`
54
55 This method returns the application base directory.
56
57- `MyApp->load_plugin($module_name[, \%config])`
58
59 This method loads the plugin for the application.
60
61 _$module\_name_ package name of the plugin. You can write it as two form like [DBIx::Class](https://metacpan.org/pod/DBIx::Class):
62
63 __PACKAGE__->load_plugin("Web::CSRFDefender"); # => loads Amon2::Plugin::Web::CSRFDefender
64
65 If you want to load a plugin in your own name space, use the '+' character before a package name, like following:
66 \_\_PACKAGE\_\_->load\_plugin("+MyApp::Plugin::Foo"); # => loads MyApp::Plugin::Foo
67
68- `MyApp->load_plugins($module_name[, \%config ], ...)`
69
70 Load multiple plugins at one time.
71
72 If you want to load a plugin in your own name space, use the '+' character before a package name like following:
73
74 __PACKAGE__->load_plugins("+MyApp::Plugin::Foo"); # => loads MyApp::Plugin::Foo
75
76- `MyApp->load_config()`
77
78 You can get a configuration hashref from `config/$ENV{PLACK_ENV}.pl`. You can override this method for customizing configuration loading method.
79
80- `MyApp->add_config()`
81
82 DEPRECATED.
83
84- `MyApp->debug_mode()`
85
86 **((EXPERIMENTAL))**
87
88 This method returns a boolean value. It returns true when $ENV{AMON2\_DEBUG} is true value, false otherwise.
89
90 You can override this method if you need.
91
92# PROJECT LOCAL MODE
93
94**THIS MODE IS HIGHLY EXPERIMENTAL**
95
96Normally, Amon2's context is stored in a global variable.
97
98This module makes the context to project local.
99
100It means, normally context class using Amon2 use `$Amon2::CONTEXT` in each project, but context class using ["PROJECT LOCAL MODE"](#project-local-mode) use `$MyApp::CONTEXT`.
101
102**It means you can't use code depend `<Amon2-`context>> and `<Amon2-`context>> under this mode.**>
103
104## NOTES ABOUT create\_request
105
106Older [Amon2::Web::Request](https://metacpan.org/pod/Amon2::Web::Request) has only 1 argument like following, it uses `Amon2->context` to get encoding:
107
108 sub create_request {
109 my ($class, $env) = @_;
110 Amon2::Web::Request->new($env);
111 }
112
113If you want to use ["PROJECT LOCAL MODE"](#project-local-mode), you need to pass class name of context class, as following:
114
115 sub create_request {
116 my ($class, $env) = @_;
117 Amon2::Web::Request->new($env, $class);
118 }
119
120## HOW DO I ENABLE PROJECT LOCAL MODE?
121
122` MyApp-`make\_local\_context() > turns on the project local mode.
123
124There is no way to revert it, thanks.
125
126## METHODS
127
128This module inserts 3 methods to your context class.
129
130- MyApp->context()
131
132 Shorthand for $MyApp::CONTEXT
133
134- MyApp->set\_context($context)
135
136 It's the same as:
137
138 $MyApp::CONTEXT = $context
139
140- my $guard = MyApp->context\_guard()
141
142 Create new context guard class.
143
144 It's the same as:
145
146 Amon2::ContextGuard->new(shift, \$MyApp::CONTEXT);
147
148# DOCUMENTS
149
150More complicated documents are available on [http://amon.64p.org/](http://amon.64p.org/)
151
152# SUPPORTS
153
154\#amon at irc.perl.org is also available.
155
156# AUTHOR
157
158Tokuhiro Matsuno <tokuhirom@gmail.com>
159
160# CONTRIBUTORS
161
162- noblejasper
163- hiratara
164- s-aska
165- Kentaro Kuribayashi
166- Yuki Ibe
167- mattn
168- Masahiro Nagano
169- rightgo09
170- karupanerura
171- hatyuki
172- Keiji, Yoshimi
173- Nishibayashi Takuji
174- dragon3
175- Fuji, Goro
176- issm
177- hisaichi5518
178- Adrian
179- Fuji, Goro
180- ITO Nobuaki
181- Geraud CONTINSOUZAS
182- Syohei YOSHIDA
183- magnolia
184- Katsuhiro Konishi
185
186# LICENSE
187
188This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
189
README.mkdn
1Amon2 - Yet another web application framework
2============================================
3
4- Supports PSGI/Plack.
5- Thin layer.
6- Lightweight.
7
8Full document available on http://amon.64p.org/
9
){kind=link}