Missing a set of ()
[hoplite.git] / README
1 hoplite                                              A lightweight MVC framework
2 ================================================================================
3
4 Hoplite is the successor framework to phalanx. While many of the ideas in
5 phalanx were good starting point explorations, it was ultimately over-
6 engineered. Hoplite aims to be a no-frills web framework--a starting point for
7 applications that can incorporate other technologies.
8
9 --------------------------------------------------------------------------------
10
11 Basic flow:
12
13 1. HTTP request is made.
14 2. Web server (Apache, Lighty, etc.) receive the request and route it, via
15    mod_rewrite or something similar to the entrypoint, which is typically
16    index.php.
17 3. RootController is initialized and Run with the $GLOBALS (_GET, _POST, etc.).
18 4. A HttpRequest object is created with the initializing data.
19 5. A UrlMap matches a URL prefix (with pathc component extraction) to an Action.
20 6. The Action produces a HttpResponse to the Request.
21 7. An OutputFilter examines the Request and Response to create the body of the
22    HTTP response.
23
24 --------------------------------------------------------------------------------
25
26 Actions:
27
28 The base Action class is abstract and has three states: before, acting, and
29 after:
30
31 Action {
32   __construct(RootController)
33
34   controller() -> RootController
35
36   FilterRequest(HttpRequest, HttpResponse)
37
38   Invoke(HttpRequest, HttpResponse)
39
40   FilterResponse(HttpResponse, HttpResponse)
41 }
42
43 The filter methods are available for two reasons:
44   1. To validate data in the request
45   2. To format data in the response
46
47 These hook points can also be used to implement interceptors, with the aid of
48 the RootController interface.
49
50 RootController {
51   __construct($GLOBALS)
52
53   Run()
54   Stop()
55
56   RouteRequest(string)
57   InvokeAction(Action)
58
59   LookupAction(string)
60 }
61
62 In the entrypoint, the RootController is Run(). This creates and owns the
63 Request and Response objects. At any point when an Action is executing, it can
64 invoke control-flow changing methods on the controller. Stop() will force the
65 OutputFilter to run and will terminate the program. InvokeAction() will replace
66 the current Action with the parameter. This will move the Action between its
67 states.
68
69 RouteRequest() is called by Run() to perform the evaluation and lookup of the
70 UrlMap. This may also be called to perform an internal redirect. Note that this
71 will reuse the existing Request and Response objects.
72
73 Finally LookupAction() performs a reverse-lookup of class name to URL patterns.
74
75 --------------------------------------------------------------------------------
76
77 Advanced actions:
78
79 The basic Action is abstract. For creating individual pages, this merely
80 overriding Invoke() can be used to fill the HttpResponse's body for simple HTML
81 output.
82
83 RestActions are a special kind of action, where Invoke() will further dispatch
84 the request based on the HTTP method. This makes creating RESTful web services
85 and AJAX applications easy:
86
87 RestAction : Action {
88   DoGet(HttpRequest, HttpResponse)
89   DoPost(...)
90   DoDelete(...)
91   DoPut(...)
92 }
93
94 Another type of action is an ActionController, which maps a URL path component
95 to a method in the typical MVC style. The ActionController will look at the
96 'action' key in the HttpRequest's data dictionary to determine which method to
97 invoke. For example, if you had this entry in the UrlMap:
98
99   'user/{action}/{id}' => 'UserActionController'
100
101 Then the UrlMap would extract the 'action' and 'id' paramters and add them to
102 the HttpRequest object. If 'action' were 'view', then it would invoke
103 ActionView().
104
105 --------------------------------------------------------------------------------
106
107 Output filtering:
108
109 The last stage of the request pipeline is output filtering. At this stage, the
110 HttpResponse is transformed into the body of the HTTP response.
111
112 If the HttpRequest has the X-Requested-With header, for example, the output
113 filter would know to respond with JSON. It could also look for other parameters
114 in the request (like ?format=xml) to determine the response encoding.
115
116 Template systems can hook in here, too. Actions can store arbitrary data in the
117 HttpResponse, including the name of a template in which to render the response
118 data. A simple templating system is included with Hoplite, but because the
119 model is represented entirely within the HttpResponse, other templating systems
120 can also be used freely.
121
122 --------------------------------------------------------------------------------
123
124 URL mapping:
125
126 There are two ways to map URLs to Actions. The first is prefix matching, which
127 assumes that all paths are relative to the URL of the RootController and do not
128 need to start with a slash. In this form, any substrings within {curly braces}
129 will be extracted as a variable by that name. The value will be placed in the
130 HttpRequest's data dictionary.
131
132 If the application were at:
133
134   https://example.com/webapp/index.php
135
136 Requests will be in the rewritten form of:
137
138   https://example.comm/webapp/user/view/42
139
140 The UrlMap could be any of the following:
141
142   ID paramter extracted manually from the URL or through GET or POST variables
143   'user/view'
144
145   Using path parameter extraction
146   'user/view/{id}'
147
148   Using an ActionController (see previous section)
149   'user/{action}'
150   Or,
151   'user/{action}/{id}'
152
153 In the above forms, the matcher does prefix matching. Combined with the fact
154 that rules are evaluated linearly, this can lead to a potentially unexpected
155 result. When you have a more general rule before a specific one, the general
156 will always be the one matched. For example:
157
158   'document/edit'
159   'document/edit/{id}'
160
161 The second rule will never be matched, because the evaluator will find and
162 invoke the first rule and then stop. This isn't always the desired behavior and
163 can be altered by adding two slashes to the end of a rule. These two slashes
164 make the parser matching strict equality, rather than prefix.
165
166 The second type of matching is done by regular expressions. These patterns both
167 start and end with a slash. They are evaluated every time a request is routed
168 and any pattern groups are saved in the url_pattern key of the HttpRequest data.
169
170 For example, the following could be used to match the above routes:
171
172   '/user\/([a-z]+)(\/([0-9]*))?/'