Laravel Valet

If you want to use PHP’s built-in web server, your simplest option is to serve every site from a localhost URL. If you run php -S localhost:8000 -t public from your Laravel site’s root folder, PHP’s built-in web server will serve your site at http://localhost:8000/. You can also run php artisan serve once you have your application set up to easily spin up an equivalent server.

But if you’re interested in tying each of your sites to a specific development domain, you’ll need to get comfortable with your operating system’s hosts file and use a tool like dnsmasq. Let’s instead try something simpler.

If you’re a Mac user (there are also unofficial forks for Windows and Linux), Laravel Valet takes away the need to connect your domains to your application folders. Valet installs dnsmasq and a series of PHP scripts that make it possible to type laravel new myapp && open myapp.test and for it to just work. You’ll need to install a few tools using Homebrew, which the documentation will walk you through, but the steps from initial installation to serving your apps are few and simple.

Install Valet (see the docs for the latest installation instructions), and point it at one or more directories where your sites will live. I ran valet park from my ~/Sites directory, which is where I put all of my under-development apps. Now, you can just add .test to the end of the directory name and visit it in your browser.

Valet makes it easy to serve all folders in a given folder as “FOLDERNAME.test” using valet park, to serve just a single folder using valet link, to open the Valet-served domain for a folder using valet open, to serve the Valet site with HTTPS using valet secure, and to open an ngrok tunnel so you can share your site with others with valet share.

Laravel Homestead

Homestead is another tool you might want to use to set up your local development environment. It’s a configuration tool that sits on top of Vagrant (which is a tool for managing for virtual machines) and provides a pre-configured virtual machine image that is perfectly set up for Laravel development, and mirrors the most common production environment that many Laravel sites run on. Homestead is also likely the best local development environment for developers running Windows machines.

The Homestead docs are robust and kept constantly up-to-date, so I’ll just refer you to them if you want to learn how it works and how to get it set up.

Installing Laravel with the Laravel Installer Tool

If you have Composer installed globally, installing the Laravel installer tool is as simple as running the following command:

composer global require "laravel/installer"

Once you have the Laravel installer tool installed, spinning up a new Laravel project is simple. Just run this command from your command line:

laravel new projectName

This will create a new subdirectory of your current directory named projectName and install a bare Laravel project in it.

Installing Laravel with Composer’s create-project Feature

Composer also offers a feature called create-project for creating new projects with a particular skeleton. To use this tool to create a new Laravel project, issue the following command:

composer create-project laravel/laravel projectName

Just like the installer tool, this will create a subdirectory of your current directory named projectName that contains a skeleton Laravel install, ready for you to develop.

Lambo: Super-powered “Laravel New”

Because I often take the same series of steps after creating a new Laravel project, I made a simple script called Lambo that automates those steps every time I create a new project.

Lambo runs laravel new, and then commits your code to Git, sets up your .env credentials with reasonable defaults, opens the project in a browser, and (optionally) opens it in your editor and takes a few other helpful build steps.

You can install Lambo using Composer’s global require:

composer global require tightenco/lambo

And you can use it just like laravel new:

cd Sites
lambo my-new-project

The Folders

The root directory contains the following folders by default:

• app is where the bulk of your actual application will go. Models, controllers, commands, and your PHP domain code all go in here.

• bootstrap contains the files that the Laravel framework uses to boot every time it runs.

• config is where all the configuration files live.

• database is where database migrations, seeds, and factories live.

• public is the directory the server points to when it’s serving the website. This contains index.php, which is the front controller that kicks off the bootstrapping process and routes all requests appropriately. It’s also where any public-facing files like images, stylesheets, scripts, or downloads go.

• resources is where files that are needed for other scripts live. Views, language files, and (optionally) Sass/Less/source CSS and source JavaScript files live here.

• routes is where all of the route definitions live, both for HTTP routes and “console routes,” or Artisan commands.

• storage is where caches, logs, and compiled system files live.

• tests is where unit and integration tests live.

• vendor is where Composer installs its dependencies. It’s Git-ignored (marked to be excluded from your version control system), as Composer is expected to run as a part of your deploy process on any remote servers.

The Loose Files

The root directory also contains the following files:

• .editorconfig gives your IDE/text editor instructions about Laravel’s coding standars (e.g. the size of indents, the charset, and whether to trim trailing whitespace). You’ll see in this in all versions of Laravel but only in projects created more recently.

• .env and .env.example are the files that dictate the environment variables (variables that are expected to be different in each environment and are therefore not committed to version control). .env.example is a template that each environment should duplicate to create its own .env file, which is Git-ignored.

• .gitignore and .gitattributes are Git configuration files.

• artisan is the file that allows you to run Artisan commands (see Chapter 8) from the command line.

• composer.json and composer.lock are the configuration files for Composer; composer.json is user-editable and composer.lock is not. These files share some basic information about this project and also define its PHP dependencies.

• package.json is like composer.json but for frontend assets and dependencies of the build system; it instructs NPM on which JavaScript-based dependencies to pull in.

• phpunit.xml is a configuration file for PHPUnit, the tool Laravel uses for testing out of the box.

• readme.md is a Markdown file giving a basic introduction to Laravel. You won’t see this file if you use the Laravel installer.

• server.php is a backup server that tries to allow less-capable servers to still preview the Laravel application.

• webpack.mix.js or gulpfile.js is the (optional) configuration file for Mix (webpack.mix.js) or Elixir (gulpfile.js). These files are for giving your build system directions on how to compile and process your frontend assets.

The .env file

Let’s take a quick look at the default contents of the .env file. The exact keys will vary depending on which version of Laravel you’re using, but take a look at Example 2-1 to see what they look like in 5.7.

APP_NAME=Laravel
APP_ENV=local
APP_KEY=
APP_DEBUG=true
APP_URL=http://localhost

LOG_CHANNEL=stack

DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=homestead
DB_USERNAME=homestead
DB_PASSWORD=secret

BROADCAST_DRIVER=log
CACHE_DRIVER=file
QUEUE_CONNECTION=sync
SESSION_DRIVER=file
SESSION_LIFETIME=120

REDIS_HOST=127.0.0.1
REDIS_PASSWORD=null
REDIS_PORT=6379

MAIL_DRIVER=smtp
MAIL_HOST=smtp.mailtrap.io
MAIL_PORT=2525
MAIL_USERNAME=null
MAIL_PASSWORD=null
MAIL_ENCRYPTION=null

PUSHER_APP_ID=
PUSHER_APP_KEY=
PUSHER_APP_SECRET=
PUSHER_APP_CLUSTER=mt1

MIX_PUSHER_APP_KEY="${PUSHER_APP_KEY}"
MIX_PUSHER_APP_CLUSTER="${PUSHER_APP_CLUSTER}"

I won’t go into all of them, because quite a few (Pusher, Redis, DB, Mail) are just groups of authentication information for various services. Here are two important environment variables you should know, though:

• APP_KEY is a randomly-generated string that’s used to encrypt data. If this is ever empty, you may run into the error “No application encryption key has been specified”. If so, just run php artisan key:generate and Laravel will generate one for you.

• APP_DEBUG is a boolean determining whether the users of this instance of your application should see debug errors. Great for local and staging; terrible for production.

The rest of the non-authentication settings (BROADCAST_DRIVER, QUEUE_CONNECTION, etc.) are given default values that work with as little reliance on external services as possible, which is perfect for when you’re getting started.

When you start your first Laravel app, the only change you’ll likely want to make on most projects is to the database configuration settings. Since I use Laravel Valet, I change DB_DATABASE to the name of my project, DB_USERNAME to root, and DB_PASSWORD to an empty string. And then, I go create a database with the same name as my project in my favorite MySQL client. Ready to go.

DB_DATABASE=myProject
DB_USERNAME=root
DB_PASSWORD=

What is MVC?

In MVC, you have three primary concepts: Model, View, and Controller.

• The model represents an individual database table (or a record from that table)--think “Company” or “Dog”.

• The view represents the template that outputs your data to the end user—think “the login page template with this given set of HTML and CSS and JavaScript”.

• The controller is like a traffic cop, taking HTTP requests from the browser, getting the right data out of the database and other storage mechanisms, validating user input, and eventually sending a response back to the user.

In Figure 3-1, you can see that our end user will first interact with the controller by sending an HTTP request using their browser. The controller, in response to that request, may write data to and/or pull data from the model (database). The controller will then likely send data to a view, and then the view will be returned to the end user to display in their browser.

Figure 3-1. A basic illustration of MVC

We’ll cover some use cases for Laravel that don’t fit this relatively simplistic way of looking at application architecture, so don’t get hung up on MVC, but this will at least get you ready to approach the rest of this chapter as we talk about views and controllers.

The HTTP Verbs

The most common HTTP verbs are GET and POST, followed by PUT and DELETE. There’s also HEAD, OPTIONS, PATCH, and two others that are pretty much never used in normal web development, TRACE and CONNECT.

Here’s the quick rundown:

• GET requests a resource (or a list of resources)

• HEAD asks for a headers-only version of the GET

• POST creates a resource

• PUT overwrites a resource

• PATCH modifies a resource

• DELETE deletes a resource

• OPTIONS asks the server which verbs are allowed at this URL

In Table 3-1 you can see a diagram generated by Laravel to show the actions available on a “resource controller” (more on that in “Resource Controllers”). Each action expects you to call a specific URL pattern using a specific verb, so you can get a sense for what each verb is used for.

What is REST?

We’ll cover REST in greater detail in “The Basics of REST-Like JSON APIs”, but as a brief introduction, it’s an architectural sstyle for building APIs. When we talk about REST in this book we’ll mainly be referencing a few characteristics:

• Structured around one primary resource at a time (e.g. tasks)

• Consisting of interactions using HTTP verbs to predictable URL structures (as seen in Table 3-1)

• Returning JSON and often requested with JSON

There’s more to it, but usually “RESTful” as it’ll be used in this book will mean “patterned after these URL-based structures so we can predict to make calls like GET /tasks/14/edit for the edit page”. This is relevant because much of Laravel’s routing structures are based around a REST-like structure, even when not building APIs—as you can see in Table 3-1.

REST-based APIs follow mainly this same structure , except they don’t have a create route or an edit route, since APIs just represent actions, not pages the prep for the actions.

Route Verbs

You might’ve noticed that we’ve been using Route::get in our route definitions. This means we’re telling Laravel to only match for these routes when the HTTP request uses the GET action. But what if it’s a form POST, or maybe some JavaScript sending PUT or DELETE requests? There are a few other options for methods to call on a route definition, as illustrated in Example 3-3.

Route::get('/', function () {
    return 'Hello, World!';
});

Route::post('/', function () {
    // Handle someone sending a POST request to this route
});

Route::put('/', function () {
    // Handle someone sending a PUT request to this route
});

Route::delete('/', function () {
    // Handle someone sending a DELETE request to this route
});

Route::any('/', function () {
    // Handle any verb request to this route
});

Route::match(['get', 'post'], '/', function () {
    // Handle GET or POST requests to this route
});

Route Handling

As you’ve probably guessed, passing a closure to the route definition is not the only way to teach it how to resolve a route. Closures are quick and simple, but the larger your application gets, the clumsier it becomes to put all of your routing logic in one file. Additionally, applications using route closures can’t take advantage of Laravel’s route caching (more on that later), which can shave up to hundreds of milliseconds off of each request.

The other common option is to pass a controller name and method as a string in place of the closure, as in Example 3-4.

Route::get('/', 'WelcomeController@index');

This is telling Laravel to pass requests to that path to the index() method of the App\Http\Controllers\WelcomeController controller. This method will be passed the same parameters and treated the same way as a closure you might’ve alternatively put in its place.

Route Parameters

If the route you’re defining has parameters—segments in the URL structure that are variable—it’s simple to define them in your route and pass them to your closure (see Example 3-5).

Route::get('users/{id}/friends', function ($id) {
    //
});

You can also make your route parameters optional by including a question mark (?) after the parameter name, as illustrated in Example 3-6. In this case, you should also provide a default value for the route’s corresponding variable.

Route::get('users/{id?}', function ($id = 'fallbackId') {
    //
});

And you can use regular expressions (regexes) to define that a route should only match if a parameter meets particular requirements, as in Example 3-7.

Route::get('users/{id}', function ($id) {
    //
})->where('id', '[0-9]+');

Route::get('users/{username}', function ($username) {
    //
})->where('username', '[A-Za-z]+');

Route::get('posts/{id}/{slug}', function ($id, $slug) {
    //
})->where(['id' => '[0-9]+', 'slug' => '[A-Za-z]+']);

As you’ve probably guessed, if you visit a path that matches a route string, but the regex doesn’t match the parameter, it won’t be matched. Since routes are matched top to bottom, users/abc would skip the first closure in Example 3-7, but it would be matched by the second closure, so it would get routed there. On the other hand, posts/abc/123 wouldn’t match any of the closures, so it would return a 404 Not Found error.

Route Names

The simplest way to refer to these routes elsewhere in your application is just by their path. There’s a url() global helper to simplify that linking in your views, if you need it; see Example 3-8 for an example. The helper will prefix your route with the full domain of your site.

<a href="<?php echo url('/'); ?>">
// outputs <a href="http://myapp.com/">

However, Laravel also allows you to name each route, which enables you to refer to it without explicitly referencing the URL. This is helpful because it means you can give simple nicknames to complex routes, and also because linking them by name means you don’t have to rewrite your frontend links if the paths change (see Example 3-9).

// Defining a route with name() in routes/web.php:
Route::get('members/{id}', 'MembersController@show')->name('members.show');

// Linking the route in a view using the route() helper
<a href="<?php echo route('members.show', ['id' => 14]); ?>">

This example illustrates a few new concepts. First, we’re using fluent route definition to add the name, by chaining the name() method after the get() method. This method allows us to name the route, giving it a short alias to make it easier to reference elsewhere.

Route::get('members/{id}', [
    'as' => 'members.show',
    'uses' => 'MembersController@show',
]);

In our example, we’ve named this route members.show; resourcePlural.action is a common convention within Laravel for route and view names.

We also introduced the route() helper. Just like url(), it’s intended to be used in views to simplify linking to a named route. If the route has no parameters, you can simply pass the route name: (route('members.index')) and receive a route string (http://myapp.com/members). If it has parameters, pass them in as an array as the second parameter like we did in this example.

In general, I recommend using route names instead of paths to refer to your routes, and therefore using the route() helper instead of the url() helper. Sometimes it can get a bit clumsy—for example, if you’re working with multiple subdomains—but it provides an incredible level of flexibility to later change the application’s routing structure without major penalty.

Middleware

Probably the most common use for route groups is to apply middleware to a group of routes. You’ll learn more about middleware in Chapter 10, but, among other things, they’re what Laravel uses for authenticating users and restricting guest users from using certain parts of a site.

In Example 3-11, we’re creating a route group around the dashboard and account views and applying the auth middleware to both. In this example, it means users have to be logged in to the application to view the dashboard or the account page.

Route::middleware('auth')->group(function() {
    Route::get('dashboard', function () {
        return view('dashboard');
    });
    Route::get('account', function () {
        return view('account');
    });
});

Route::group(['middleware' => 'auth'], function () {
    Route::get('dashboard', function () {
        return view('dashboard');
    });
    Route::get('account', function () {
        return view('account');
    });
});

class DashboardController extends Controller
{
    public function __construct()
    {
        $this->middleware('auth');

        $this->middleware('admin-auth')
            ->only('editUsers');

        $this->middleware('team-member')
            ->except('editUsers');
    }
}

Route::middleware('auth:api', 'throttle:60,1')->group(function () {
    Route::get('/profile', function () {
        //
    });
});

Path Prefixes

If you have a group of routes that share a segment of their path—for example, if your site’s dashboard is prefixed with /dashboard—you can use route groups to simplify this structure (see Example 3-13).

Route::prefix('dashboard')->group(function () {
    Route::get('/', function () {
        // Handles the path /dashboard
    });
    Route::get('users', function () {
        // Handles the path /dashboard/users
    });
});

Note that each prefixed group also has a / route that represents the root of the prefix—in Example 3-13 that’s /dashboard.

Fallback Routes

In Laravel prior to 5.6, you could define a “fallback route” (which you need to define at the end of your routes file) to catch all un-matched paths:

Route::any('{anything}', 'CatchAllController')->where('anything', '*');

In Laravel 5.6+, you can use the Route::fallback() method instead:

Route::fallback(function () {
    //
});

Subdomain Routing

Subdomain routing is the same as route prefixing, but it’s scoped by subdomain instead of route prefix. There are two primary uses for this. First, you may want to present different sections of the application (or entirely different applications) to different subdomains. Example 3-14 shows how you can achieve this.

Route::domain('api.myapp.com')->group(function () {
    Route::get('/', function () {
        //
    });
});

Second, you might want to set part of the subdomain as a parameter, as illustrated in Example 3-15. This is most often done in cases of multitenancy (think Slack or Harvest, where each company gets its own subdomain, like tighten.slack.co).

Route::domain('{account}.myapp.com')->group(function () {
    Route::get('/', function ($account) {
        //
    });
    Route::get('users/{id}', function ($account, $id) {
        //
    });
});

Note that any parameters for the group get passed into the grouped routes’ methods as the first parameter(s).

Namespace Prefixes

When you’re grouping routes by subdomain or route prefix, it’s likely their controllers have a similar PHP namespace. In the dashboard example, all of the dashboard routes’ controllers might be under an Dashboard namespace. By using the route group namespace prefix, as shown in Example 3-16, you can avoid long controller references in groups like "Dashboard/UsersController@index" and "Dashboard/PurchasesController@index".

// App\Http\Controllers\UsersController
Route::get('/', 'UsersController@index');

Route::namespace('Dashboard')->group(function () {
    // App\Http\Controllers\Dashboard\PurchasesController
    Route::get('dashboard/purchases', 'PurchasesController@index');
});

Name Prefixes

The prefixes don’t stop there. It’s common that route names will reflect the inheritance chain of path elements, so users/comments/5 will be served by a route named users.comments.show. In this case, it’s common to use a route group around all of the routes that are beneath the users.comments resource.

Just like we can prefix URL segments and controller namespaces, we can also prefix strings to the route name. With route group name prefixes, we can define that every route within this group should have a given string prefixed to its name. In this context, we’re prefixing "users. to each route name, then "comments." (see Example 3-17).

Route::name('users.')->prefix('users')->group(function () {
    Route::name('comments.')->prefix('comments')->group(function () {
        Route::get('{id}', function () {

        })->name('show');
    });
});

Signing a Route

In order to build a signed URL to access a given route, the route must have a name:

Route::get('invitations/{invitation}/{answer}', 'InvitationController')
    ->name('invitations');

To generate a normal link to this route, you would use the route() helper, as we’ve already covered, but you could also use the URL facade to do the same thing: URL::route('invitations', ['invitation' => 12345, 'answer' => 'yes']). To generate a signed link to this route, simply use the signedRoute() method instead. And if you want to generate a signed route with an expiration, used temporarySignedRoute():

// Generate normal link
URL::route('invitations', ['invitation' => 12345, 'answer' => 'yes']);

// Generate a signed link
URL::signedRoute('invitations', ['invitation' => 12345, 'answer' => 'yes']);

// Generate an expiring (temporary) signed link
URL::temporarySignedRoute(
    'invitations',
    now()->addHours(4),
    ['invitation' => 12345, 'answer' => 'yes']
);

Modifying Routes to Allow Signed Links

Now that we’ve generated a link to our signed route, we need to protect against any non-signed access. The easiest option is to apply the signed middleware (which, if it’s not in your $routeMiddleware array in app/Http/Kernel.php, should be, backed by Illuminate\Routing\Middleware\ValidateSignature).

Route::get('invitations/{invitation}/{answer}', 'InvitationController')
    ->name('invitations')
    ->middleware('signed');

If you’d prefer, you can manually validate using the hasValidSignature() method on the request object instead of using the signed middleware:

class InvitationController
{
    public function __invoke(Invitation $invitation, $answer, Request $request)
    {
        if (! $request->hasValidSignature()) {
            abort(403);
        }

        //
    }
}

Returning Simple Routes Directly with Route::view()

Because it’s so common for a route to just return a view with no custom data, Laravel 5.5+ allows you to define a route as a “view” route without even passing the route definition a closure or a controller/method reference, as you can see in Example 3-20.

// Returns resources/views/welcome.blade.php
Route::view('/', 'welcome');

// Passing simple data to Route::view
Route::view('/', 'welcome', ['User' => 'Michael']);

Using View Composers to Share Variables with Every View

Sometimes it can become a hassle to pass the same variables over and over. There may be a variable that you want accessible to every view in the site, or to a certain class of views or a certain included subview—for example, all views related to tasks, or the header partial.

It’s possible to share certain variables with every template or just certain templates, like in the following code:

view()->share('variableName', 'variableValue');

To learn more, check out “View Composers and Service Injection”.

Getting User Input

The second most common action to perform in a controller method is to take input from the user and act on it. That introduces a few new concepts, so let’s take a look at a bit of sample code and walk through the new pieces.

First, let’s bind our route quickly; see Example 3-25.

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

Notice that we’re binding the GET action of tasks/create (which shows a form for creating a new task) and the POST action of tasks/ (which is where our form will POST to when we’re creating a new task). We can assume the create() method in our controller just shows a form, so let’s look at the store() method in Example 3-26.

// TasksController.php
...
public function store()
{
    Task::create(request()->only(['title', 'description']));

    return redirect('tasks');
}

This example makes use of Eloquent models and the redirect() functionality, and we’ll talk about them more later, but let’s talk quickly about how you’re getting your data here.

We’re using the request() helper to represent the HTTP request (more on that later) and using its only() method to pull just the title and description fields the user submitted.

We’re then passing that data into the create method of our Task model, which creates a new instance of the Task with “title” set to the passed-in title and “description” set to the passed-in description. Finally, we redirect back to the page that shows all tasks.

There are a few layers of abstraction at work here, which we’ll cover in a second, but know that the data coming from the only() method comes from the same pool of data as would come from the all() method or the get() method, all common methods used on the request objects. The set of data each of these methods is pulling from represents all user-provided data, whether from query parameters or POST values. So our user filled out two fields on the “add task” page: “title” and “description.”

To break down the abstraction a bit, request()->only() takes an associative array of input names and returns them:

request()->only(['title', 'description']);
// returns:
[
    'title' => 'Whatever title the user typed on the previous page',
    'description' => 'Whatever description the user typed on the previous page',
]

And Task::create() takes an associative array and creates a new task from it:

Task::create([
    'title' => 'Buy milk',
    'description' => 'Remember to check the expiration date this time, Norbert!',
]);

Combining them together creates a task with just the user-provided “title” and “description” fields.

Injecting Dependencies into Controllers

Laravel’s facades and global helpers present a simple interface to the most useful classes in Laravel’s codebase. You can get information about the current request and user input, the session, caches, and much more.

But if you prefer to inject your dependencies, or if you want to use a service that doesn’t have a facade or a helper, you’ll need to find some way to bring instances of these classes into your controller.

This is our first exposure to Laravel’s service container. For now, if this is unfamiliar, you can think about it as a little bit of Laravel magic; or, if you want to know more about how it’s actually functioning, you can skip ahead to Chapter 11.

All controller methods (including the constructors) are resolved out of Laravel’s container, which means anything you typehint that the container knows how to resolve will be automatically injected.

public function __construct(Logger $logger) {}

As a nice example, what if you’d prefer having an instance of the Request object instead of using the global helper? Just typehint Illuminate\Http\Request in your method parameters, like in Example 3-27.

// TasksController.php
...
public function store(\Illuminate\Http\Request $request)
{
    Task::create($request->only(['title', 'description']));

    return redirect('tasks');
}

So, you’ve defined a parameter that must be passed into the store() method. And since you typehinted it, and since Laravel knows how to resolve that class name, you’re going to have the Request object ready for you to use in your method with no work on your part. No explicit binding, no anything else—it’s just there as the $request variable.

And, as you can tell from comparing Example 3-26 and Example 3-27, the request() helper and the Request object behave exactly the same.

Resource Controllers

Sometimes naming the methods in your controllers can be the hardest part of writing a controller. Thankfully, Laravel has some conventions for all of the routes of a traditional REST/CRUD controller (called a “resource controller” in Laravel); additionally, it comes with a generator out of the box and a convenience route definition that allows you to bind an entire resource controller at once.

To see the methods that Laravel expects for a resource controller, let’s generate a new controller from the command line:

php artisan make:controller MySampleResourceController --resource

Now open app/Http/Controllers/MySampleResourceController.php. You’ll see it comes prefilled with quite a few methods. Let’s walk over what each represents. We’ll use a Task as an example.

Binding a resource controller

So, we’ve seen that these are the conventional route names to use in Laravel, and also that it’s easy to generate a resource controller with methods for each of these default routes. Thankfully, you don’t have to generate routes for each of these controller methods by hand, if you don’t want to. Instead, there’s a trick for that, and it’s called “resource controller binding.” Take a look at Example 3-28.

Example 3-28. Resource controller binding

// routes/web.php
Route::resource('tasks', 'TasksController');

This will automatically bind all of the routes listed in Table 3-1 for this resource to the appropriate method names on the specified controller. It’ll also name these routes appropriately; for example, the index() method on the tasks resource controller will be named tasks.index.

artisan route:list

If you ever find yourself in a situation where you’re wondering what routes your current application has available, there’s a tool for that: from the command line, run php artisan route:list and you’ll get a listing of all of the available routes (see Figure 3-2).

Figure 3-2. php artisan route:list example

API resource controllers

When you’re working with RESTful APIs, the list of potential actions on a resource is not the same as it is with an HTML resource controller. For example, you can send a POST request to an API to create a resource, but you can’t really “show a create form” in an API.

Laravel 5.6 introduced a new way to generate an “API resource controller”, which has the same structure as a resource controller except it excludes the create and edit actions. We can generate API resource controllers by passing the --api flag when creating a controller.

php artisan make:controller MySampleResourceController --api

// routes/web.php
Route::apiResource('tasks', 'TasksController');

Single Action Controllers

There will be times in your applications that a controller appropriately should only service a single route. You may likely find yourself wondering how to name the controller method for that route. Thankfully, you can point a single route at a single controller without concerning yourself with naming the one method.

As you may already know, the __invoke method is a PHP magic method that allows you to “invoke” an instance of a class, treating it like a function and calling it. This is the tool Laravel’s Single Action Controllers use to allow you to point a route to a single controller, as you can see in Example 3-30.

// \App\Http\Controllers\UpdateUserAvatar.php
public function __invoke(User $user)
{
    // Update the user's avatar image
}

// routes/web.php
Route::post('users/{user}/update-avatar', 'UpdateUserAvatar');

Implicit Route Model Binding

The simplest way to use route model binding is to name your route parameter something unique to that model (e.g., name it $conference instead of $id), then typehint that parameter in the closure/controller method and use the same variable name there. It’s easier to show than to describe, so take a look at Example 3-32.

Route::get('conferences/{conference}', function (Conference $conference) {
    return view('conferences.show')->with('conference', $conference);
});

Because the route parameter ({conference}) is the same as the method parameter ($conference), and the method parameter is typehinted with a Conference model (Conference $conference), Laravel sees this as a route model binding. Every time this route is visited, the application will assume that whatever is passed into the URL in place of {conference} is an ID that should be used to look up a Conference, and then that resulting model instance will be passed in to your closure or controller method.

public function getRouteKeyName()
{
    return 'slug';
}

Implicit route model binding was added in Laravel 5.2, so you won’t have access to it in 5.1.

Custom Route Model Binding

To manually configure route model bindings, add a line like the one in Example 3-30 to the boot() method in App\Providers\RouteServiceProvider.

    public function boot()
    {
        // Just allows the parent's boot() method to still run
        parent::boot();

        // Perform the binding
        Route::model('event', Conference::class);
    }

You’ve now defined that whenever a route has a parameter in its definition named {event}, as demonstrated in Example 3-31, the route resolver will return an instance of the Conference class with the ID of that URL parameter.

Route::get('events/{event}', function (Conference $event) {
    return view('events.show')->with('event', $event);
});

HTTP Verbs in Laravel

As we’ve shown already, you can define which verbs a route will match in the route definition using Route::get(), Route::post(), Route::any(), or Route::match(). You can also match with Route::patch(), Route::put(), and Route::delete().

But how does one send a request other than GET with a web browser? First, the method attribute in an HTML form determines its HTTP verb: if your form has a method of "GET", it will submit via query parameters and a GET method; if the form has a method of "POST", it will submit via the post body and a POST method.

JavaScript frameworks make it easy to send other requests, like DELETE and PATCH. But if you find yourself needing to submit HTML forms in Laravel with verbs other than GET or POST, you’ll need to use form method spoofing, which is spoofing the HTTP method in an HTML form.

HTTP Method Spoofing in HTML Forms

To inform Laravel that the form you’re currently submitting should be treated as something other than POST, add a hidden variable named _method with the value of either "PUT", "PATCH", or "DELETE", and Laravel will match and route that form submission as if it were actually a request with that verb.

The form in Example 3-35, since it’s passing Laravel the method of "DELETE", will match routes defined with Route::delete() but not those with Route::post().

<form action="/tasks/5" method="POST">
    <input type="hidden" name="_method" value="DELETE">
    <!-- or: -->
    @method('DELETE')
</form>

redirect()->to()

The method signature for the to() method for redirects looks like this:

function to($to = null, $status = 302, $headers = [], $secure = null)

$to is a valid internal path; $status is the HTTP status (defaulting to 302 FOUND); $headers allows you to define which HTTP headers to send along with your redirect; and $secure allows you to override the default choice of http versus https (which is normally set based on your current request URL). Example 3-39 shows an example of its use.

Route::get('redirect', function () {
    return redirect()->to('home');

    // or same, using the shortcut:

    return redirect('home');
});

redirect()->route()

The route() method is the same as the to() method, but rather than pointing to a particular path, it points to a particular route name (see Example 3-40).

Route::get('redirect', function () {
    return redirect()->route('conferences.index');
});

Note that, since some route names require parameters, its parameter order is a little different. route() has an optional second parameter for the route parameters:

function route($to = null, $parameters = [], $status = 302, $headers = [])

So, using it might look a little like Example 3-40.

Route::get('redirect', function () {
    return redirect()->route('conferences.show', ['conference' => 99]);
});

redirect()->back()

Because of some of the built-in conveniences of Laravel’s session implementation, your application will always have knowledge of what the user’s previously visited page was. That opens up the opportunity for a redirect()->back() redirect, which simply redirects the user to whatever page she came from. There’s also a global shortcut for this: back().

Other Redirect Methods

The redirect service provides other methods that are less commonly used, but still available:

• home() redirects to a route named home.

• refresh() redirects to the same page the user is currently on.

• away() allows for redirecting to an external URL without the default URL validation.

• secure() is like to() with the secure parameter set to "true".

• action() allows you to link to a controller and method in one of two ways: first, as a string: redirect()->action('MyController@myMethod'), or second, as a tuple: redirect()->action([MyController::class, 'myMethod’])

• guest() is used internally by the auth system (discussed in Chapter 9); when a user visits a route he’s not authenticated for, this captures the “intended” route and then redirects the user (usually to a login page).

• intended() is also used internally by the auth system; after a successful authentication, this grabs the “intended” URL stored by the guest() method and redirects the user there.

redirect()->with()

When you’re redirecting users to different pages, you often want to pass certain data along with them. You could manually flash the data to the session, but Laravel has some convenience methods to help you with that.

Most commonly, you can pass along either an array of keys and values or a single key and value using with(), like in Example 3-42. This saves your with() data to the session just for the next page load.

Route::get('redirect-with-key-value', function () {
    return redirect('dashboard')
        ->with('error', true);
});

Route::get('redirect-with-array', function () {
    return redirect('dashboard')
        ->with(['error' => true, 'message' => 'Whoops!']);
});

You can also use withInput(), as in Example 3-43, to redirect with the user’s form input flashed; this is most common in the case of a validation error, where you want to send the user back to the form she just came from.

Route::get('form', function () {
    return view('form');
});

Route::post('form', function () {
    return redirect('form')
        ->withInput()
        ->with(['error' => true, 'message' => 'Whoops!']);
});

The easiest way to get the flashed input that was passed with withInput() is using the old() helper, which can be used to get all old input (old()) or just the value for a particular key (old('username'), with the second parameter as the default if there is no old value). You’ll commonly see this in views, which allows this HTML to be used both on the “create” and the “edit” view for this form:

<input name="username" value="<?=
    old('username', 'Default username instructions here');
?>">

Speaking of validation, there is also a useful method for passing errors along with a redirect response: withErrors(). You can pass it any “provider” of errors, which may be an error string, an array of errors, or, most commonly, an instance of the Illuminate Validator, which we’ll cover in Chapter 10. Example 3-44 shows an example of its use.

Route::post('form', function () {
    $validator = Validator::make($request->all()), $this->validationRules);

    if ($validator->fails()) {
        return back()
            ->withErrors($validator)
            ->withInput();
    }
});

withErrors() automatically shares an $errors variable with the views of the page it’s redirecting to, for you to handle however you’d like.

response()->make()

If you want to create an HTTP response manually, just pass your data into the first parameter of response()->make(): e.g., return response()->make('Hello, World!'). Once again, the second parameter is the HTTP status code and the third is your headers.

response()->json() and ->jsonp()

To create a JSON-encoded HTTP response manually, pass your JSON-able content (arrays, collections, or whatever else) to the json() method: e.g., return response()->json(User::all());. It’s just like make(), except it json_encodes your content and sets the appropriate headers.

response()->download(), ->streamDownload(), and ->file()

To send a file for the end user to download, pass either an SplFileInfo instance or a string filename to download(), with an optional second parameter of the download filename: e.g., return response()->download('file501751.pdf', 'myFile.pdf'), which would send a file that’s at file501751.pdf and name it, as it’s sent, as myFile.pdf.

To display the same file in the browser (if it’s a PDF or an image or something else the browser can handle), use response()->file() instead, which takes the same parameters as response->download().

If you want to make some content from an external service available as a download without having to write it directly to your server’s disk, you can stream the download using response()->streamDownload(). This method expects parameters of a closure which echoes a string, a filename, and an optional third parameter of an array of headers. Take at look at Example 3-46:

return response()->streamDownload(function () {
    echo DocumentService::file('myFile')->getContent();
}, 'myFile.pdf');

Defining Sections with @section/@show and @yield

Let’s start with a top-level Blade layout, like in Example 4-8. This is the definition of a generic page wrapper that we’ll later place page-specific content into.

<!-- resources/views/layouts/master.blade.php -->
<html>
    <head>
        <title>My Site | @yield('title', 'Home Page')</title>
    </head>
    <body>
        <div class="container">
            @yield('content')
        </div>
        @section('footerScripts')
            <script src="app.js"></script>
        @show
    </body>
</html>

This looks a bit like a normal HTML page, but you can see we’ve yielded in two places (title and content), and we’ve defined a section in a third (footerScripts).

We have three Blade directives here that each look a little different: @yield('content') alone, @yield('title', 'Home Page') with a defined default, and @section ... @show with actual content in it.

All three function essentially the same. All three are defining that there’s a section with a given name (which is the first parameter). All three are defining that the section can be extended later. And all three are defining what to do if the section isn’t extended, either by providing a string fallback ('Home Page'), no fallback (which will just not show anything if it’s not extended), or an entire block fallback (in this case, <script src="app.js"></script>).

What’s different? Well, clearly, @yield('content') has no default content. But additionally, the default content in @yield('title') only will be shown if it’s never extended. If it is extended, its child sections will not have programmatic access to the default value. @section ... @show, on the other hand, is both defining a default and doing so in a way that its default contents will be available to its children, through @parent.

Once you have a parent layout like this, you can extend it in a new template file like in Example 4-9.

<!-- resources/views/dashboard.blade.php -->
@extends('layouts.master')

@section('title', 'Dashboard')

@section('content')
    Welcome to your application dashboard!
@endsection

@section('footerScripts')
    @parent

    <script src="dashboard.js"></script>
@endsection

This child view will actually allow us to cover a few new concepts in Blade inheritance.

@parent

Fourth, with @section('footerScripts') and on, we use the normal syntax to define the contents of the footerScripts section.

But remember, we actually defined that content (or, at least, its “default”) already in the master layout. So this time, we have two options: we can either overwrite the content from the parent view, or we can add to it.

You can see that we have the option to include the content from the parent by using the @parent directive within the section. If we didn’t, the content of this section would entirely overwrite anything defined in the parent for this section.

@include

Now that we’ve established the basics of inheritance, there are a few more tricks we can perform.

What if we’re in a view and want to pull in another view? Maybe we have a call-to-action “Sign up” button that we want to re-use around the site. And maybe we want to customize its button text every time we use it. Take a look at Example 4-10.

<!-- resources/views/home.blade.php -->
<div class="content" data-page-name="{{ $pageName }}">
    <p>Here's why you should sign up for our app: <strong>It's Great.</strong></p>

    @include('sign-up-button', ['text' => 'See just how great it is'])
</div>

<!-- resources/views/sign-up-button.blade.php -->
<a class="button button--callout" data-page-name="{{ $pageName }}">
    <i class="exclamation-icon"></i> {{ $text }}
</a>

@include pulls in the partial and, optionally, passes data into it. Note that not only can you explicitly pass data to an include via the second parameter of @include, but you can also reference any variables within the included file that are available to the including view ($pageName, in this example). Once again, you can do whatever you want, but I would recommend you consider always explicitly passing every variable that you intend to use, just for clarity.

You also use the @includeIf, includeWhen and includeFirst directives.

{{-- Include a view if it exists --}}
@includeIf('sidebars.admin', ['some' => 'data'])

{{-- Include a view if a passed variable is truth-y --}}
@includeWhen($user->isAdmin(), 'sidebars.admin', ['some' => 'data'])

{{-- Include the first view that exists from a given array of views --}}
@includeFirst(['customs.header', 'header'], ['some' => 'data'])

@each

You can probably imagine some circumstances in which you’d need to loop over an array or collection and @include a partial for each item. There’s a directive for that: @each.

Let’s say we have a sidebar composed of modules, and we want to include multiple modules, each with a different title. Take a look at Example 4-12.

<!-- resources/views/sidebar.blade.php -->
<div class="sidebar">
    @each('partials.module', $modules, 'module', 'partials.empty-module')
</div>

<!-- resources/views/partials/module.blade.php -->
<div class="sidebar-module">
    <h1>{{ $module->title }}</h1>
</div>

<!-- resources/views/partials/empty-module.blade.php -->
<div class="sidebar-module">
    No modules :(
</div>

Consider that @each syntax. The first parameter is the name of the view partial. The second is the array or collection to iterate over. The third is the variable name that each item (in this case, each element in the $modules array) will be passed to the view as. And the optional fourth parameter is the view to show if the array or collection is empty (or, optionally, you can pass a string in here that will be used as your template).

Stacks

One common pattern that can be difficult to manage using basic Blade includes is when each view in a Blade include hierarchy needs to add something to a certain section—almost like adding an entry onto an array.

The most common situation for this is when certain pages (and sometimes, more broadly, certain sections of a website) have specific unique CSS and JavaScript files they need to load. Imagine you have a site-wide “global” CSS file, a “jobs section” CSS file, and an “apply for a job” page CSS file.

Blade’s “stacks” are built for exactly this situation. In your parent template, you’ll define a “stack”, which is just a placeholder; then in each child template you can “push” entries onto that stack with @push/@endpush, which just add them to the bottom of the stack in the final render. You can also use @prepend/@endprepend to add them to the top of the stack.

<!-- resources/views/layouts/app.blade.php -->
<html>
<head><!-- the head --></head>
<body>
    <!-- the rest of the page.. -->
    <script src="/css/global.css"></script>
    <!-- the placeholder where stack content will be placed -->
    @stack('scripts')
</body>
</html>

<!-- resources/views/jobs.blade.php -->
@extends('layouts.app')

@push('scripts')
    <!-- push something to the bottom of the stack -->
    <script src="/css/jobs.css"></script>
@endpush

<!-- resources/views/jobs/apply.blade.php -->
@extends('jobs')

@prepend('scripts')
    <!-- push something to the top of the stack -->
    <script src="/css/jobs--apply.css"></script>
@endprepend

These would generate this:

<html>
<head><!-- the head --></head>
<body>
    <!-- the rest of the page.. -->
    <script src="/css/global.css"></script>
    <!-- the placeholder where stack content will be placed -->
    <script src="/css/jobs--apply.css"></script>
    <script src="/css/jobs.css"></script>
</body>
</html>

Components and Slots

Laravel offers another pattern for including content between views, which was introduced in 5.4: components and slots. Components make the most sense in contexts when you find yourself using view partials and passing large chunks of content into the partial as variables. Take a look at Example 4-14 for an example.

<!-- resources/views/partials/modal.blade.php -->
<div class="modal">
    <div>{{ $content }}</div>
    <div class="close button etc">...</div>
</div>

<!-- in another template -->
@include('partials.modal', [
    'body' => '<p>The password you have provided is not valid. Here are the rules
    for valid passwords: [...]</p><p><a href="#">...</a></p>'
])

This is too much for this variable, and it’s the perfect fit for a component.

Components with slots are view partials that are explicitly designed to have big chunks (“slots”) that are meant to get content from the including template. Take a look at Example 4-15 to see how to refactor Example 4-14 with components and slots.

<!-- resources/views/partials/modal.blade.php -->
<div class="modal">
    <div>{{ $slot }}</div>
    <div class="close button etc">...</div>
</div>

<!-- in another template -->
@component('partials.modal')
    <p>The password you have provided is not valid.
    Here are the rulesfor valid passwords: [...]</p>

    <p><a href="#">...</a></p>
@endcomponent

As you can see in Example 4-15, the @component directive allows us to pull our HTML out of a cramped variable string and back into the template space. The $slot variable in our component template receives whatever content is passed between the @component and @endcomponent directives.

<!-- resources/views/partials/modal.blade.php -->
<div class="modal">
    <div class="modal-header">{{ $title }}</div>
    <div>{{ $slot }}</div>
    <div class="close button etc">...</div>
</div>

@component('partials.modal')
    @slot('title')
        Password validation failure
    @endslot

    <p>The password you have provided is not valid. Here are the rules for valid passwords: [...]</p>

    <p><a href="#">...</a></p>
@endcomponent

@component('partials.modal', ['class' => 'danger'])
    <!-- ... -->
@endcomponent

// AppServiceProvider@boot
Blade::component('partials.modal', 'modal')

<!-- in a template -->
@modal
    Modal content here
@endmodal

Binding Data to Views Using View Composers

Thankfully, there’s a simpler way. The solution is called a view composer, and it allows you to define that any time a particular view loads, it should have certain data passed to it—without the route definition having to pass that data in explicitly.

Let’s say you have a sidebar on every page, which is defined in a partial named partials.sidebar (resources/views/partials/sidebar.blade.php) and then included on every page. This sidebar shows a list of the last seven posts that were published on your site. If it’s on every page, every route definition would normally have to grab that list and pass it in, like in Example 4-21.

Route::get('home', function () {
    return view('home')
        ->with('posts', Post::recent());
});

Route::get('about', function () {
    return view('about')
        ->with('posts', Post::recent());
});

That could get annoying quickly. Instead, we’re going to use view composers to “share” that variable with a prescribed set of views. We can do this a few ways, so let’s start simple and move up.

// Some service provider
public function boot()
{
    ...
    view()->share('recentPosts', Post::recent());
}

view()->composer('partials.sidebar', function ($view) {
    $view->with('recentPosts', Post::recent());
});

view()->composer(
    ['partials.header', 'partials.footer'],
    function () {
        $view->with('recentPosts', Post::recent());
    }
);

view()->composer('partials.*', function () {
    $view->with('recentPosts', Post::recent());
});

<?php

namespace App\Http\ViewComposers;

use App\Post;
use Illuminate\Contracts\View\View;

class RecentPostsComposer
{
    public function compose(View $view)
    {
        $view->with('recentPosts', Post::recent());
    }
}

public function boot()
{
    view()->composer(
        'partials.sidebar',
        \App\Http\ViewComposers\RecentPostsComposer::class
    );
}

Blade Service Injection

There are three primary types of data we’re most likely to inject into a view: collections of data to iterate over, single objects that we’re displaying on the page, and services that generate data or views.

With a service, the pattern will most likely look like Example 4-26, where we inject an instance of our analytics service into the route definition by typehinting it in the route’s method signature, and then pass it into the view.

Route::get('backend/sales', function (AnalyticsService $analytics) {
    return view('backend.sales-graphs')
        ->with('analytics', $analytics);
});

Just as with view composers, Blade’s service injection offers a convenient shortcut to reduce duplication in your route definitions. Normally, the content of a view using our analytics service might look like Example 4-27.

<div class="finances-display">
     {{ $analytics->getBalance() }} / {{ $analytics->getBudget() }}
</div>

Blade service injection makes it easy to inject an instance of a class from the container directly from the view, like in Example 4-28.

@inject('analytics', 'App\Services\Analytics')

<div class="finances-display">
     {{ $analytics->getBalance() }} / {{ $analytics->getBudget() }}
</div>

As you can see, this @inject directive has actually made an $analytics variable available, which we’re using later in our view.

The first parameter of @inject is the name of the variable you’re injecting, and the second parameter is the class or interface that you want to inject an instance of. This is resolved just like when you type hint a dependency in a constructor elsewhere in Laravel; if you’re unfamiliar with how that works, check out Chapter 11 to learn more.

Just like view composers, Blade service injection makes it easy to make certain data or functionality available to every instance of a view, without having to inject it via the route definition every time.

Parameters in Custom Blade Directives

What if you want to accept parameters in your custom logic? Check out Example 4-30.

// Binding
Blade::directive('newlinesToBr', function ($expression) {
    return "<?php echo nl2br({$expression}); ?>";
});

// In use
<p>@newlinesToBr($message->body)</p>

The $expression parameter received by the closure represents whatever’s within the parentheses. As you can see, we then generate a valid PHP code snippet and return it.

If you find yourself constantly writing the same conditional logic over and over, you should consider a Blade directive.

Example: Using Custom Blade Directives for a Multitenant App

So, let’s imagine we’re building an application that supports multitenancy, which means users might be visiting the site from www.myapp.com, client1.myapp.com, client2.myapp.com, or elsewhere.

Suppose we have written a class to encapsulate some of our multitenancy logic and named it Context. This class will capture information and logic about the context of the current visit, such as who the authenticated user is and whether the user is visiting the public website or a client subdomain.

We’ll probably frequently resolve that Context class in our views and perform conditionals on it, like in Example 4-31. The app('context') is a shortcut to get an instance of a class from the container, which we’ll learn more about in Chapter 11.

@if (app('context')->isPublic())
    © Copyright MyApp LLC
@else
    © Copyright {{ app('context')->client->name }}
@endif

What if we could simplify @if (app('context')->isPublic()) to just @ifPublic? Let’s do it. Check out Example 4-32.

// Binding
Blade::directive('ifPublic', function () {
    return "<?php if (app('context')->isPublic()): ?>";
});

// In use
@ifPublic
    &copy; Copyright MyApp LLC
@else
    &copy; Copyright {{ app('context')->client->name }}
@endif

Since this resolves to a simple if statement, we can still rely on the native @else and @endif conditionals. But if we wanted, we could also create a custom @elseIfClient directive, or a separate @ifClient directive, or really whatever else we want.

Easier custom directives for “if” statements

While custom Blade directives are powerful, the most common use for them are if statements. So there’s a simpler way to create custom “if” directives: Blade::if. Let’s take a look at refactoring Example 4-32 using the Blade::if method:

// Binding
Blade::if('ifPublic', function () {
    return (app('context'))->isPublic();
});

You’ll use the directives exactly the same, but as you can see, defining them is just a bit simpler. Instead of having to manually type out PHP braces, you can just write a closure that returns a boolean.

Database Connections

By default, there’s one connection for each of the drivers, as you can see in Example 5-1.

   'connections' => [

        'sqlite' => [
            'driver' => 'sqlite',
            'database' => env('DB_DATABASE', database_path('database.sqlite')),
            'prefix' => '',
        ],

        'mysql' => [
            'driver' => 'mysql',
            'host' => env('DB_HOST', '127.0.0.1'),
            'port' => env('DB_PORT', '3306'),
            'database' => env('DB_DATABASE', 'forge'),
            'username' => env('DB_USERNAME', 'forge'),
            'password' => env('DB_PASSWORD', ''),
            'unix_socket' => env('DB_SOCKET', ''),
            'charset' => 'utf8',
            'collation' => 'utf8_unicode_ci',
            'prefix' => '',
            'strict' => false,
            'engine' => null,
        ],

        'pgsql' => [
            'driver' => 'pgsql',
            'host' => env('DB_HOST', '127.0.0.1'),
            'port' => env('DB_PORT', '5432'),
            'database' => env('DB_DATABASE', 'forge'),
            'username' => env('DB_USERNAME', 'forge'),
            'password' => env('DB_PASSWORD', ''),
            'charset' => 'utf8',
            'prefix' => '',
            'schema' => 'public',
            'sslmode' => 'prefer',
        ],

        'sqlsrv' => [
            'driver' => 'sqlsrv',
            'host' => env('DB_HOST', 'localhost'),
            'port' => env('DB_PORT', '1433'),
            'database' => env('DB_DATABASE', 'forge'),
            'username' => env('DB_USERNAME', 'forge'),
            'password' => env('DB_PASSWORD', ''),
            'charset' => 'utf8',
            'prefix' => '',
        ],

    ]

You could create new named connections, and still be able to set the drivers (MySQL, Postgres, etc.) in those new named connections. So, while there’s one connection per driver by default, that’s not a constraint.

Nothing is stopping you from deleting or modifying these named connections or creating your own. You could have five different connections, all with the mysql driver, if you want.

Each connection allows you to define the properties necessary for connecting to and customizing each connection type.

There are a few reasons for the idea of multiple drivers. To start with, the “connections” section as it comes out of the box is a simple template that makes it easy to start apps that use any of the supported database connection types. In many apps, you can pick the database connection you’ll be using, fill out its information, and even delete the others if you’d like. I usually just keep them all there, in case I might eventually use them.

But there are also some cases where you might need multiple connections within the same application. For example, you might use different database connections for two different types of data, or you might read from one and write to another. Support for multiple connections makes this possible.

Other Database Configuration Options

The config/database.php configuration section has quite a few other configuration settings. You can configure Redis access, customize the table name used for migrations, determine the default connection, and toggle whether non-Eloquent calls return stdClass or array instances.

With any service in Laravel that allows multiple “connections”—sessions can be backed by the database or file storage, the cache can use Redis or Memcached, databases can use MySQL or PostgreSQL—you can define multiple connections and also choose that a particular connection will be the “default,” meaning it will be used any time you don’t explicitly ask for a particular connection. Here’s how you ask for a specific connection, if you want to:

$users = DB::connection('secondary')->select('select * from users');

Defining Migrations

A migration is a single file that defines two things: the modifications desired when running this migration up and, optionally, the modifications desired when running this migration down.

Example 5-2 shows what the default “create users table” migration that comes with Laravel looks like.

<?php

use Illuminate\Database\Schema\Blueprint;
use Illuminate\Database\Migrations\Migration;

class CreateUsersTable extends Migration
{
    /**
     * Run the migrations.
     *
     * @return void
     */
    public function up()
    {
        Schema::create('users', function (Blueprint $table) {
            $table->increments('id');
            $table->string('name');
            $table->string('email')->unique();
            $table->timestamp('email_verified_at')->nullable();
            $table->string('password');
            $table->rememberToken();
            $table->timestamps();
        });
    }

    /**
     * Reverse the migrations.
     *
     * @return void
     */
    public function down()
    {
        Schema::dropIfExists('users');
    }
}

As you can see, we have an up() method and a down() method. up() tells the migration to create a new table named users with a few fields, and down() tells it to drop the users table.

php artisan make:migration create_users_table
php artisan make:migration add_votes_to_users_table --table=users
php artisan make:migration create_users_table --create=users

Schema::create('users', function (Blueprint $table) {
    // Create columns here
});

Schema::create('users', function (Blueprint $table) {
    $table->string('name');
});

Schema::table('users', function (Blueprint $table) {
    $table->string('email')->nullable()->after('last_name');
});

Schema::dropIfExists('contacts');

Schema::table('users', function (Blueprint $table) {
    $table->string('name', 100)->change();
});

Schema::table('contacts', function (Blueprint $table) {
    $table->string('deleted_at')->nullable()->change();
});

Schema::table('contacts', function (Blueprint $table)
{
    $table->renameColumn('promoted', 'is_promoted');
});

Schema::table('contacts', function (Blueprint $table)
{
    $table->dropColumn('votes');
});

public function up()
{
    Schema::table('contacts', function (Blueprint $table)
    {
        $table->dropColumn('is_promoted');
    });

    Schema::table('contacts', function (Blueprint $table)
    {
        $table->dropColumn('alternate_email');
    });
}

// after columns are created...
$table->primary('primary_id'); // Primary key; unnecessary if used increments()
$table->primary(['first_name', 'last_name']); // Composite keys
$table->unique('email'); // Unique index
$table->unique('email', 'optional_custom_index_name'); // Unique index
$table->index('amount'); // Basic index
$table->index('amount', 'optional_custom_index_name'); // Basic index

$table->dropPrimary('contacts_id_primary');
$table->dropUnique('contacts_email_unique');
$table->dropIndex('optional_custom_index_name');

// If you pass an array of column names to dropIndex, it will
// guess the index names for you based on the generation rules
$table->dropIndex(['email', 'amount']);

$table->foreign('user_id')->references('id')->on('users');

$table->foreign('user_id')
    ->references('id')
    ->on('users')
    ->onDelete('cascade');

$table->dropForeign('contacts_user_id_foreign');

$table->dropForeign(['user_id']);

Running Migrations

Once you have your migrations defined, how do you run them? There’s an Artisan command for that:

php artisan migrate

This command runs all “outstanding” migrations (by running the up() method on each). Laravel keeps track of which migrations you have run and which you haven’t. Every time you run this command, it checks whether you’ve run all available migrations, and if you haven’t, it’ll run any that remain.

There are a few options in this namespace that you can work with. First, you can run your migrations and your seeds (which we’ll cover next):

php artisan migrate --seed

You can also run any of the following commands:

• migrate:install creates the database table that keeps track of which migrations you have and haven’t run; this is run automatically when you run your migrations, so you can basically ignore it.

• migrate:reset rolls back every database migration you’ve run on this instance.

• migrate:refresh rolls back every database migration you’ve run on this instance, and then runs every migration available. It’s the same as running migrate:reset and then migrate, one after the other.

• migrate:fresh drops all of your tables and runs every migration again. It’s the same as refresh but doesn’t bother with the “down” migrations—it just deletes the tables and then runs the “up” migrations again.

• migrate:rollback rolls back just the migrations that ran the last time you ran migrate, or, with the added option --step=1, rolls back the number of migrations you specify.

• migrate:status shows a table listing every migration, with a Y or N next to each showing whether or not it has run yet in this environment.

Creating a Seeder

To create a seeder, use the make:seeder Artisan command:

php artisan make:seeder ContactsTableSeeder

You’ll now see a ContactsTableSeeder class show up in the database/seeds directory. Before we edit it, let’s add it to the DatabaseSeeder class so it will run when we run our seeders:

// database/seeds/DatabaseSeeder.php
...
    public function run()
    {
        $this->call(ContactsTableSeeder::class);
    }

Now let’s edit the seeder itself. The simplest thing we can do there is manually insert a record using the DB facade:

<?php

use Illuminate\Database\Seeder;
use Illuminate\Database\Eloquent\Model;

class ContactsTableSeeder extends Seeder
{
    public function run()
    {
        DB::table('contacts')->insert([
            'name' => 'Lupita Smith',
            'email' => 'lupita@gmail.com',
        ]);
    }
}

This will get us a single record, which is a good start. But for truly functional seeds, you’ll likely want to loop over some sort of random generator and run this insert() many times, right? Laravel has a feature for that.

Model Factories

Model factories define one (or more) patterns for creating fake entries for your database tables. By default each factory is named after an Eloquent class, but you can also just name them after the table if you’re not going to work with Eloquent. Here’s the same factory set up both ways:

$factory->define(User::class, function (Faker\Generator $faker) {
    return [
        'name' => $faker->name,
    ];
});

$factory->define('users', function (Faker\Generator $faker) {
    return [
        'name' => $faker->name,
    ];
});

Theoretically you can name these factories anything you like, but naming the factory after your Eloquent class is the most idiomatic approach.

php artisan make:factory ContactFactory

$factory->define(Contact::class, function (Faker\Generator $faker) {
    return [
        'name' => 'Lupita Smith',
        'email' => 'lupita@gmail.com',
    ];
});

// Create one
$contact = factory(Contact::class)->create();

// Create many
factory(Contact::class, 20)->create();

$factory->define(Contact::class, function (Faker\Generator $faker) {
    return [
        'name' => $faker->name,
        'email' => $faker->email,
    ];
});

return ['email' => $faker->unique()->email];

factory(Post::class)->create([
    'title' => 'My greatest post ever'
]);

// Pro-level factory; but don't get overwhelmed!
factory(User::class, 20)->create()->each(function ($u) use ($post) {
    $post->comments()->save(factory(Comment::class)->make([
        'user_id' => $u->id
    ]));
});

$factory->define(Contact::class, function (Faker\Generator $faker) {
    return [
        'name' => 'Lupita Smith',
        'email' => 'lupita@gmail.com',
        'company_id' => function () {
            return factory(App\Company::class)->create()->id;
        }
    ];
});

$factory->define(Contact::class, function (Faker\Generator $faker) {
    return [
        'name' => 'Lupita Smith',
        'email' => 'lupita@gmail.com',
        'company_id' => function () {
            return factory(App\Company::class)->create()->id;
        },
        'company_size' => function ($contact) {
            // Uses the "company_id" property generated above
            return App\Company::find($contact['company_id'])->size;
        }
    ];
});

$factory->define(Contact::class, function (Faker\Generator $faker) {
    return [
        'name' => $faker->name,
        'email' => $faker->email,
    ];
});

$factory->define(Contact::class, function (Faker\Generator $faker) {
    return [
        'name' => $faker->name,
        'email' => $faker->email,
    ];
});

$factory->state(Contact::class, 'vip', [
    'vip' => true,
]);

$factory->state(Contact::class, 'vip', function (Faker\Generator $faker) {
    return [
        'vip' => true,
        'company' => $faker->company,
    ];
});

$vip = factory(Contact::class, 'vip')->create();

$vips = factory(Contact::class, 'vip', 3)->create();

Basic Usage of the DB Facade

Before we get into building complex queries with fluent method chaining, let’s take a look at a few sample query builder commands. The DB facade is used both for query builder chaining and for simpler raw queries, as illustrated in Example 5-10.

// basic statement
DB::statement('drop table users');

// raw select, and parameter binding
DB::select('select * from contacts where validated = ?', [true]);

// select using the fluent builder
$users = DB::table('users')->get();

// joins and other complex calls
DB::table('users')
    ->join('contacts', function ($join) {
        $join->on('users.id', '=', 'contacts.user_id')
             ->where('contacts.type', 'donor');
    })
    ->get();

Raw SQL

As you saw in Example 5-10, it’s possible to make any raw call to the database using the DB facade and the statement() method: DB::statement('SQL statement here').

But there are also specific methods for various common actions: select(), insert(), update(), and delete(). These are still raw calls, but there are differences. First, using update() and delete() will return the number of rows affected, whereas statement() won’t; second, with these methods it’s clearer to future developers exactly what sort of statement you’re making.

$users = DB::select('select * from users');

$usersOfType = DB::select(
    'select * from users where type = ?',
    [$type]
);

$usersOfType = DB::select(
    'select * from users where type = :type',
    ['type' => $userType]
);

DB::insert(
    'insert into contacts (name, email) values (?, ?)',
    ['sally', 'sally@me.com']
);

$countUpdated = DB::update(
    'update contacts set status = ? where id = ?',
    ['donor', $id]
);

$countDeleted = DB::delete(
    'delete from contacts where archived = ?',
    [true]
);

Chaining with the Query Builder

Up until now, we haven’t actually used the query builder, per se. We’ve just used simple method calls on the DB facade. Let’s actually build some queries.

The query builder makes it possible to chain methods together to, you guessed it, build a query. At the end of your chain you’ll use some method—likely get()—to trigger the actual execution of the query you’ve just built.

Let’s take a look at a quick example:

$usersOfType = DB::table('users')
    ->where('type', $type)
    ->get();

Here, we built our query—users table, $type type—and then we executed the query and got our result.

Let’s take a look at what methods the query builder allows you to chain. The methods can be split up into what I’ll call constraining methods, modifying methods, conditional methods, and ending/returning methods.

$emails = DB::table('contacts')
    ->select('email', 'email2 as second_email')
    ->get();
// Or
$emails = DB::table('contacts')
    ->select('email')
    ->addSelect('email2 as second_email')
    ->get();

$newContacts = DB::table('contact')
    ->where('created_at', '>', now()->subDay())
    ->get();

$newVips = DB::table('contacts')
    ->where('vip', true)
    ->where('created_at', '>', now()->subDay());
// Or
$newVips = DB::table('contacts')->where([
    ['vip', true],
    ['created_at', '>', now()->subDay()],
]);