$request->all()

Just like the name suggests, $request->all() gives you an array containing all of the input the user has provided, from every source. Let’s say, for some reason, you decided to have a form POST to a URL with a query parameter—for example, sending a POST to http://myapp.com/signup?utm=12345. Take a look at Example 7-1 to see what you’d get from $request->all(). (Note that $request->all() also contains information about any files that were uploaded, but we’ll cover that later in the chapter.)

<!-- GET route form view at /get-route -->
<form method="post" action="/signup?utm=12345">
    @csrf
    <input type="text" name="first_name">
    <input type="submit">
</form>

// routes/web.php
Route::post('signup', function (Request $request) {
    var_dump($request->all());
});

// Outputs:
/**
 * [
 *     '_token' => 'CSRF token here',
 *     'first_name' => 'value',
 *     'utm' => 12345,
 * ]
 */

$request->except() and $request->only()

$request->except() provides the same output as $request->all(), but you can choose one or more fields to exclude—for example, _token. You can pass it either a string or an array of strings.

Example 7-2 shows what it looks like when we use $request->except() on the same form as in Example 7-1.

Route::post('post-route', function (Request $request) {
    var_dump($request->except('_token'));
});

// Outputs:
/**
 * [
 *     'firstName' => 'value',
 *     'utm' => 12345
 * ]
 */

$request->only() is the inverse of $request->except(), as you can see in Example 7-3.

Route::post('post-route', function (Request $request) {
    var_dump($request->only(['firstName', 'utm']));
});

// Outputs:
/**
 * [
 *     'firstName' => 'value',
 *     'utm' => 12345
 * ]
 */

$request->has()

With $request->has() you can detect whether a particular piece of user input is available to you. Check out Example 7-4 for an analytics example with our utm query string parameter from the previous examples.

// POST route at /post-route
if ($request->has('utm')) {
    // Do some analytics work
}

$request->input()

Whereas $request->all(), $request->except(), and $request->only() operate on the full array of input provided by the user, $request->input() allows you to get the value of just a single field. Example 7-5 provides an example. Note that the second parameter is the default value, so if the user hasn’t passed in a value, you can have a sensible (and nonbreaking) fallback.

Route::post('post-route', function (Request $request) {
    $userName = $request->input('name', 'Matt');
});

$request->method() and ->isMethod()

$request->method() returns the HTTP verb for the request, and $request->isMethod() checks whether it matches the specified verb. Example 7-6 illustrates their use.

$method = $request->method();

if ($request->isMethod('patch')) {
    // Do something if request method is PATCH
}

Array Input

Laravel also provides convenience helpers for accessing data from array input. Just use the “dot” notation to indicate the steps of digging into the array structure, like in Example 7-7.

<!-- GET route form view at /employees/create -->
<form method="post" action="/employees/">
    @csrf
    <input type="text" name="employees[0][firstName]">
    <input type="text" name="employees[0][lastName]">
    <input type="text" name="employees[1][firstName]">
    <input type="text" name="employees[1][lastName]">
    <input type="submit">
</form>

// POST route at /employees
Route::post('employees', function (Request $request) {
    $employeeZeroFirstName = $request->input('employees.0.firstName');
    $allLastNames = $request->input('employees.*.lastName');
    $employeeOne = $request->input('employees.1');
    var_dump($employeeZeroFirstname, $allLastNames, $employeeOne);
});

// If forms filled out as "Jim" "Smith" "Bob" "Jones":
// $employeeZeroFirstName = 'Jim';
// $allLastNames = ['Smith', 'Jones'];
// $employeeOne = ['firstName' => 'Bob', 'lastName' => 'Jones'];

JSON Input (and $request->json())

So far we’ve covered input from query strings (GET) and form submissions (POST). But there’s another form of user input that’s becoming more common with the advent of JavaScript SPAs: the JSON request. It’s essentially just a POST request with the body set to JSON instead of a traditional form POST.

Let’s take a look at what it might look like to submit some JSON to a Laravel route, and how to use $request->input() to pull out that data (Example 7-8).

POST /post-route HTTP/1.1
Content-Type: application/json

{
    "firstName": "Joe",
    "lastName": "Schmoe",
    "spouse": {
        "firstName": "Jill",
        "lastName":"Schmoe"
    }
}

// Post-route
Route::post('post-route', function (Request $request) {
    $firstName = $request->input('firstName');
    $spouseFirstname = $request->input('spouse.firstName');
});

Since $request->input() is smart enough to pull user data from GET, POST, or JSON, you may wonder why Laravel even offers $request->json(). There are two reasons you might prefer $request->json(). First, you might want to just be more explicit to other programmers working on your project about where you’re expecting the data to come from. And second, if the POST doesn’t have the correct application/json headers, $request->input() won’t pick it up as JSON, but $request->json() will.

From Request

Injected Request objects (and the Request facade and the request() helper) have several methods available to represent the state of the current page’s URL, but right now let’s focus on at getting information about the URL segments.

If you’re not familiar with the idea, each group of characters after the domain in a URL is called a segment. So, http://www.myapp.com/users/15/ has two segments: users and 15.

As you can probably guess, we have two methods available to us: $request->segments() returns an array of all segments, and $request⁠->​s⁠e⁠g⁠m⁠e⁠n⁠t⁠($segmentId) allows us to get the value of a single segment. Note that segments are returned on a 1-based index, so in the preceding example, $request⁠->​s⁠e⁠g⁠m⁠e⁠n⁠t⁠(1) would return users.

Request objects, the Request facade, and the request() global helper provide quite a few more methods to help us get data out of the URL. To learn more, check out Chapter 10.

From Route Parameters

The other primary way we get data about the URL is from route parameters, which are injected into the controller method or closure that is serving a current route, as shown in Example 7-9.

// routes/web.php
Route::get('users/{id}', function ($id) {
    // If the user visits myapp.com/users/15/, $id will equal 15
});

To learn more about routes and route binding, check out Chapter 3.

validate() on the Request Object

The Request object has a validate() method that provides a convenient shortcut for the most common validation workflow. Take a look at Example 7-13.

// routes/web.php
Route::get('recipes/create', 'RecipeController@create');
Route::post('recipes', 'RecipeController@store');

// app/Http/Controllers/RecipeController.php
class RecipeController extends Controller
{
    public function create()
    {
        return view('recipes.create');
    }

    public function store(Request $request)
    {
        $request->validate([
            'title' => 'required|unique:recipes|max:125',
            'body' => 'required'
        ]);

        // Recipe is valid; proceed to save it
    }
}

We only have four lines of code running our validation here, but they’re doing a lot.

First, we explicitly define the fields we expect and apply rules (here separated by the pipe character, |) to each individually.

Next, the validate() method checks the incoming data from the $request and determines whether or not it is valid.

If the data is valid, the validate() method ends and we can move on with the controller method, saving the data or whatever else.

But if the data isn’t valid, it throws a ValidationException. This contains instructions to the router about how to handle this exception. If the request is from JavaScript (or if it’s requesting JSON as a response), the exception will create a JSON response containing the validation errors. If not, the exception will return a redirect to the previous page, together with all of the user input and the validation errors—perfect for repopulating a failed form and showing some errors.

Manual Validation

If you are not working in a controller, or if for some other reason the previously described flow is not a good fit, you can manually create a Validator instance using the Validator facade and check for success or failure like in Example 7-14.

Route::get('recipes/create', function () {
    return view('recipes.create');
});

Route::post('recipes', function (IlluminateHttpRequest $request) {
    $validator = Validator::make($request->all(), [
        'title' => 'required|unique:recipes|max:125',
        'body' => 'required'
    ]);

    if ($validator->fails()) {
        return redirect('recipes/create')
            ->withErrors($validator)
            ->withInput();
    }

    // Recipe is valid; proceed to save it
});

As you can see, we create an instance of a validator by passing it our input as the first parameter and the validation rules as the second parameter. The validator exposes a fails() method that we can check against and can be passed into the withErrors() method of the redirect.

Custom Rule Objects

If the validation rule you need doesn’t exist in Laravel, you can create your own. To create a custom rule, run php artisan make:rule RuleName and then edit that file in app/Rules/{RuleName}.php.

You’ll get two methods in your rule out of the box: passes() and message(). passes() should accept an attribute name as the first parameter and the user-provided value as the second, and then return a Boolean indicating whether or not this input passes this validation rule. message() should return the validation error message; you can use :attribute as a placeholder in your message for the attribute name.

Take a look at Example 7-15 as an example.

class WhitelistedEmailDomain implements Rule
{
    public function passes($attribute, $value)
    {
        return in_array(Str::after($value, '@'), ['tighten.co']);
    }

    public function message()
    {
        return 'The :attribute field is not from a whitelisted email provider.';
    }
}

To use this rule, just pass an instance of the rule object to your validator:

$request->validate([
    'email' => new WhitelistedEmailDomain,
]);

Displaying Validation Error Messages

We’ve already covered much of this in Chapter 6, but here’s a quick refresher on how to display errors from validation.

The validate() method on requests (and the withErrors() method on redirects that it relies on) flashes any errors to the session. These errors are made available to the view you’re being redirected to in the $errors variable. And remember that as a part of Laravel’s magic, that $errors variable will be available every time you load the view, even if it’s just empty, so you don’t have to check if it exists with isset().

That means you can do something like Example 7-16 on every page.

@if ($errors->any())
    <ul id="errors">
        @foreach ($errors->all() as $error)
            <li>{{ $error }}</li>
        @endforeach
    </ul>
@endif

You can also conditionally echo a single field’s error message. In Laravel 5.8+ you’ll use the @error Blade directive to check for whether there’s an error on a given field; prior to 5.8 you can use $errors->has('fieldName').

// Before Laravel 5.8
@if ($errors->has('first_name'))
    <span>{{ $errors->first('first_name') }}</span>
@endif

// Laravel 5.8+
@error('first_name')
    <span>{{ $message }}</span>
@enderror

Creating a Form Request

You can create a new form request from the command line:

php artisan make:request CreateCommentRequest

You now have a form request object available at app/Http/Requests/CreateCommentRequest.php.

Every form request class provides either one or two public methods. The first is rules(), which needs to return an array of validation rules for this request. The second (optional) method is authorize(); if this returns true, the user is authorized to perform this request, and if false, the user is rejected. Take a look at Example 7-17 to see a sample form request.

<?php

namespace AppHttpRequests;

use AppBlogPost;
use IlluminateFoundationHttpFormRequest;

class CreateCommentRequest extends FormRequest
{
    public function authorize()
    {
        $blogPostId = $this->route('blogPost');

        return auth()->check() && BlogPost::where('id', $blogPostId)
            ->where('user_id', auth()->id())->exists();
    }

    public function rules()
    {
        return [
            'body' => 'required|max:1000',
        ];
    }
}

The rules() section of Example 7-17 is pretty self-explanatory, but let’s look at authorize() briefly.

We’re grabbing the segment from the route named blogPost. That’s implying the route definition for this route probably looks a bit like this: Route::post('blogPosts/blogPost', function () // Do stuff). As you can see, we named the route parameter blogPost, which makes it accessible in our Request using $this->route('blogPost').

We then look at whether the user is logged in and, if so, whether any blog posts exist with that identifier that are owned by the currently logged-in user. You’ve already learned some easier ways to check ownership in Chapter 5, but we’ll keep it more explicit here to keep it clean. We’ll cover what implications this has shortly, but the important thing to know is that returning true means the user is authorized to perform the specified action (in this case, creating a comment), and false means the user is not authorized.

Using a Form Request

Now that we’ve created a form request object, how do we use it? It’s a little bit of Laravel magic. Any route (closure or controller method) that typehints a form request as one of its parameters will benefit from the definition of that form request.

Let’s try it out, in Example 7-18.

Route::post('comments', function (AppHttpRequestsCreateCommentRequest $request) {
    // Store comment
});

You might be wondering where we call the form request, but Laravel does it for us. It validates the user input and authorizes the request. If the input is invalid, it’ll act just like the Request object’s validate() method, redirecting the user to the previous page with their input preserved and with the appropriate error messages passed along. And if the user is not authorized, Laravel will return a 403 Forbidden error and not execute the route code.