-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathintro.html
189 lines (181 loc) · 7.87 KB
/
intro.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
<html>
<head>
<title>Introduction</title>
<link rel="stylesheet" href="/css/style.css">
<link rel="stylesheet" href="https://maxcdn.bootstrapcdn.com/bootstrap/3.3.5/css/bootstrap.min.css">
</head>
<body>
<header>
<div class="container">
<div class="row">
<div class="prev col-md-3">
<label for="">Prev</label>
<a href="/">Radar for PHP</a> </div>
<div class="current col-md-6">
<h3 class="title">
1. Introduction </h3>
<small class="parent">Radar for PHP</small>
</div>
<div class="next col-md-3">
<label for="">Next</label>
<a href="/domain.html">Domain Design</a> </div>
<div class="clearfix"></div>
</div>
</div>
</header>
<section id="content">
<div class="container">
<div class="row">
<div class="col-md-12">
<h1 id="1">1. Introduction</h1>
<h2 id="1-1">1.1. What is Action-Domain-Responder?</h2>
<p>You are probably used to separating concerns in terms of Model-View-Controller
(MVC). <a href="http://pmjones.io/adr">Action-Domain-Responder</a> (ADR) represents a
refinement of MVC, and should not be difficult to understand if you are already
familiar with MVC.</p>
<p>With ADR, concerns are separated like this:</p>
<ul>
<li>
<p>the Domain is the logic to manipulate the domain, session, application, and
environment data, modifying state and persistence as needed. This is the real
core of the application, where all the interesting work happens; think in terms
of "Domain Model" or "Domain Driven Design" here.</p>
</li>
<li>
<p>the Responder is the logic to build an HTTP response. It deals with body
content, templates and views, headers and cookies, status codes, and so on.
Think in terms of "Presentation" or "View" here, where the View represents the
entirety of the HTTP response, including both the headers and the body.</p>
</li>
<li>
<p>the Action is the logic that connects the Domain and Responder. It passes the
user input to the Domain, and passes the Domain output to the Responder. It
would be tempting to think in terms of "Controller" here, but the Action is
intentionally very simple, even trivial. It should contain no logic aside from
connecting the Domain and Responder.</p>
</li>
</ul>
<h2 id="1-2">1.2. How Does Radar Work?</h2>
<p>Radar is superficially similar to a micro-framework. It has a routing system to
point URLs to actions, a wrapper- or chain-style middleware system to modify the
incoming HTTP request and outgoing HTTP response, and a dependency injection
container and configuration system to wire everything together.</p>
<p>However, with Radar, you don't specify "controllers" or "closures" for your
routes. Instead, you specify up to three callables per route, all of which are
optional:</p>
<ol>
<li>
<p>A <em>Domain</em> callable to be invoked with the user input. (If you don't specify
a Domain callable, the <em>Responder</em> will be invoked directly; this is unusual but
sometimes convenient.)</p>
</li>
<li>
<p>An <em>Input</em> callable to extract user input from the incoming HTTP
<em>ServerRequest</em>. The default Radar <em>Input</em> callable will naively merge the
route path attributes (path-info parameters), the query parameters (<code>$_GET</code>),
the parsed body parameters (<code>$_POST</code>), and the uploaded files array (<code>$_FILES</code>)
into a single associative array of user input.</p>
</li>
<li>
<p>A <em>Responder</em> callable to convert the <em>Domain</em> output to an HTTP response.
The default Radar <em>Responder</em> expects a
<a href="https://github.com/auraphp/Aura.Payload"><em>Payload</em></a> object from the <em>Domain</em>;
it delivers JSON output and sets proper HTTP status codes for a wide range of
scenarios.</p>
</li>
</ol>
<p>These three callables are invoked within a standardized <em>ActionHandler</em>. As a
result, the Action logic in Radar is always the same for every route. The only
variations are in how input is collected, how output is presented, and of course
in how your core application domain operates.</p>
<p>So, don't think of Radar as a micro-framework. Think of it more like a wrapper
around the core of your real application domain. Its only purpose is to guide
input from the user into the domain, and to present output from the domain back
to the user.</p>
<h2 id="1-3">1.3. Installing Radar</h2>
<p>You will need <a href="https://getcomposer.org">Composer</a> to install Radar.</p>
<p>Pick a project name, and use Composer to create it with Radar; here we create
one called <code>example-project</code>:</p>
<pre><code>composer create-project -s dev radar/project example-project
</code></pre>
<p>Confirm the installation by changing into the project directory and starting the
built-in PHP web server:</p>
<pre><code>cd example-project
php -S localhost:8080 -t web/
</code></pre>
<p>You can then browse to <a href="http://localhost:8080/">http://localhost:8080/</a> and see JSON output:</p>
<pre><code>{"phrase":"Hello world"}
</code></pre>
<p>You can also browse to <a href="http://localhost:8080/your-name">http://localhost:8080/your-name</a> and see modified JSON output:</p>
<pre><code>{"phrase":"Hello your-name"}
</code></pre>
<h2 id="1-4">1.4. Project Structure</h2>
<p>A Radar project looks like this:</p>
<pre><code>project/ # The Radar project directory
├── .env # Environment variable definitions
├── composer.json # Project composer file
├── src/ # Project class files
│ ├── ...
│ ├── ...
│ └── ...
├── vendor/ # Composer-loaded packages
│ ├── ...
│ ├── ...
│ └── ...
└── web/ # Web document root
└── index.php # Bootstrap script
</code></pre>
<p>Of note, the <code>web/index.php</code> file is where you will:</p>
<ul>
<li>Boostrap the Radar <code>$adr</code> instance</li>
<li>Define routes</li>
<li>Define the middleware queue</li>
</ul>
<h2 id="1-5">1.5. Setting A Project Namespace</h2>
<p>In a Radar project, by default, Composer autoloads any unknown PSR-4 namespace
name from the <code>src/</code> directory. This means that you can create any PSR-4 style
class structure in the <code>src/</code> directory for your Radar project.</p>
<p>If you want to define a specific namespace for your project, modify
<code>composer.json</code> so that namespace points to the <code>src/</code> directory ...</p>
<pre><code>"autoload": {
"psr-4": {
"ProjectName\\": "src/"
}
},
</code></pre>
<p>... then regenerate the Composer autoloader by calling <code>composer dump-autoload</code>.</p>
</div>
</div>
</div>
</section>
<footer>
<section id="links">
<div class="container">
<div class="row">
<div class="prev col-md-3">
<label for="">Prev</label>
<a href="/">Radar for PHP</a> </div>
<div class="parent col-md-6">
<label for="">Up</label>
<a href="/">Radar for PHP</a> </div>
<div class="next col-md-3">
<label for="">Next</label>
<a href="/domain.html">2. Domain Design</a> </div>
<div class="clearfix"></div>
</div>
</div>
</section>
<section id="copyright">
<div class="container">
<div class="row">
<div class="col-md-12">
<span>
Powered by <a href="">Bookdown.io</a> | Designed by <a href="">yuripertamax</a>
</span>
</div>
</div>
</div>
</section>
</footer>
</body>
</html>