All routes and controllers should provide back a response
to the user's browser. OstroJS allows you to return replies in a variety of ways. Returning a string from a route or controller is the most basic answer. The framework will transform the string to a complete HTTP response automatically:
Route.get('/', function ({ response }) {
response.send('Hello World');
});
You may now return arrays from your routes and controllers in addition to strings. The framework will transform the array into a JSON response automatically:
Route.get('/', function ({ response }) {
response.send([1, 2, 3]);
});
You may change the response's HTTP status code and headers by returning a complete Response object. The @ostro/http/response
class, which provides a range of methods for generating HTTP replies, is inherited by a Response instance.
Route.get('/home', function ({ response }) {
response.header('Content-Type', 'text/plain')
response.send('Hello World', 200);
});
Keep in mind that most response methods may be chained together to create response instances quickly. For example, before sending the answer back to the user, you might use the header method to add a sequence of headers to it:
return response
.header('Content-Type', $type)
.header('X-Header-One', 'Header Value')
.header('X-Header-Two', 'Header Value')
.send(content);
You can also specify an array of headers to be added to the response using the withHeaders
method:
return response
.withHeaders({
'Content-Type' : $type,
'X-Header-One' : 'Header Value',
'X-Header-Two' : 'Header Value',
}).send(content);
The cookie method may be used to attach a cookie to an outgoing @ostro/http/response
object. This method should be passed the name, value, and amount of minutes the cookie should be deemed valid:
response.cookie(
'name', 'value', $minutes
);
return response.send('Hello World')
There are a couple additional parameters that the cookie method accepts, but they aren't used very often. These parameters serve the same purpose and have the same value as the ones passed to NodeJS's native setcookie
method:
response.cookie(
'name', 'value', $minutes, $path, $domain, $secure, $httpOnly
);
return response.send('Hello World')
You may use the request cookie
expire function to expire a cookie if you don't already have an instance of the outgoing response:
cookie.expire('name');
By default, all cookies produced by OstroJS are encrypted and signed, making them impossible for the client to modify or access. You may utilise the $except
property of the app/http/middleware/encryptCookies
middleware, which is located in the app/http/middleware
directory, to deactivate encryption for a subset of cookies created by your application:
/**
* The names of the cookies that should not be encrypted.
*
* @var array
*/
$except = [
'cookie_name',
];
Redirect replies are @ostro/http/response
objects that include the appropriate headers for redirecting the user to another URL. A RedirectResponse
instance can be created in a variety of ways:
Route.get('/dashboard', function ({ redirect }) {
redirect.to('home/dashboard');
});
When a submitted form is invalid, you may want to return the user back to their prior position. You may accomplish this by use the back
function. Because this functionality makes use of the session, ensure that the route using the back
function uses the web middleware group:
Route.post('/user/profile', function ({ redirect }) {
// Validate the request...
redirect.back().withInput();
});
When you call the redirect without any parameters, you'll get an instance of @ostro/routing/redirector
, which you may use to call any method on. You may use the route method to produce a RedirectResponse
to a specified route, for example:
redirect.route('login');
If your route includes parameters, you may give them to the route
method as the second argument:
// For a route with the following URI: /profile/{id}
redirect.route('profile', {'id' : 1});
It's possible that you'll need to redirect to a domain outside of your application at some point. You may do so by using the away
method, which generates a RedirectResponse
with no further URL encoding, validation, or verification:
redirect.away('https://www.google.com');
Usually, redirecting to a new URL and flashing data to the session happen at the same moment. When you flash a success message to the session after successfully completing an activity, this is often done. Create a RedirectResponse
object and flash data to the session in a single, fluent method chain for convenience:
Route.post('/user/profile', function ({ redirect }) {
// ...
redirect.to('dashboard').with('status', 'Profile updated!');
});
You can show the flashing message from the session
after the user is redirected. For instance, consider the following Blade syntax:
<% if (helpers.session('status')) { %>
<div class="alert alert-success">
<%= helpers.session('status') %>
</div>
<% } %>
Before redirecting the user to a new location, you may use the withInput
function offered by the RedirectResponse
class to save the current request's input data to the session. If the user encounters a validation error, this is usually done. You can simply recover the input once it has been flashed to the session on the next request to repopulate the form:
redirect.back().withInput();
Other sorts of response
instances can be generated using the response object. When the response is invoked without any parameters, an @ostro/contracts/routing/responseFactory
contract implementation is returned. This contract has a number of options for creating replies.
Use the view
method if you require control over the response's status and headers but also need to return a view as the response's content:
response.view('hello', $data, 200).header('Content-Type', $type);
Of course, you may use the response view method if you don't need to pass a custom HTTP status code or custom headers.
The json
method will set the Content-Type
header to application/json
and use the JSON.stringify
NodeJS function to convert the supplied array to JSON:
return response.json({
'name' : 'Abigail',
'state': 'CA',
});
You may use the json method in conjunction with the withCallback
method to generate a JSONP
response:
return response
.jsonp({'name' : 'Abigail', 'state' : 'CA'], request.input('callback'))
The download
method may be used to provide a response that instructs the user's browser to download the file at the specified location. The second input to the download
function is a filename, which will decide the filename that the user sees while downloading the item. Finally, as the method's third argument, you may send an array of HTTP headers:
return response.download($pathToFile);
return response.download($pathToFile, $name, $headers);
You may use the macro
method on the Response
class to construct a custom response that you can reuse in a variety of your routes and controllers. This function is often called from one of your application's service providers' boot
method, such as the app/providers/appServiceProvider
service provider:
const ServiceProvider = require('@ostro/support/serviceProvider')
const Response = require('@ostro/foundation/http/response')
class AppServiceProvider extends ServiceProvider {
/**
* Bootstrap any application services.
*
* @return void
*/
boot() {
Response.macro('caps', function($value) {
return $value.capitalize();
});
}
}
module.exports = AppServiceProvider
The first parameter to the macro function is a name, and the second argument is a closure. When invoking the macro name from a ResponseFactory
implementation or the response helper, the macro's closure will be executed:
response.caps('foo')