Configuring File Access

The definitions for Laravel’s file manager live in config/filesystems.php. Each connection is called a “disk,” and Example 14-1 lists the disks that are available out of the box.

...
'disks' => [
    'local' => [
        'driver' => 'local',
        'root' => storage_path('app'),
    ],

    'public' => [
        'driver' => 'local',
        'root' => storage_path('app/public'),
        'url' => env('APP_URL').'/storage',
        'visibility' => 'public',
    ],

    's3' => [
        'driver' => 's3',
        'key' => env('AWS_ACCESS_KEY_ID'),
        'secret' => env('AWS_SECRET_ACCESS_KEY'),
        'region' => env('AWS_DEFAULT_REGION'),
        'bucket' => env('AWS_BUCKET'),
        'url' => env('AWS_URL'),
    ],
],

The local disk connects to your local storage system and presumes it will be interacting with the app directory of the storage path, which is storage/app.

The public disk is also a local disk (although you can change it if you’d like), which is intended for use with any files you intend to be served by your application. It defaults to the storage/app/public directory, and if you want to use this directory to serve files to the public, you’ll need to add a symbolic link (symlink) to somewhere within the public/ directory. Thankfully, there’s an Artisan command that maps public/storage to serve the files from storage/app/public:

php artisan storage:link

The s3 disk shows how Laravel connects to cloud-based file storage systems. If you’ve ever connected to S3 or any other cloud storage provider, this will be familiar; pass it your key and secret and some information defining the “folder” you’re working with, which in S3 is the region and the bucket.

Using the Storage Facade

In config/filesystem.php you can set the default disk, which is what will be used any time you call the Storage facade without specifying a disk. To specify a disk, call disk('diskname') on the facade:

Storage::disk('s3')->get('file.jpg');

The filesystems each provide the following methods:

get('file.jpg')

Retrieves the file at file.jpg

put('file.jpg', $contentsOrStream)

Puts the given file contents to file.jpg

putFile('myDir', $file)

Puts the contents of a provided file (in the form of an instance of either IlluminateHttpFile or IlluminateHttpUploadedFile) to the myDir directory, but with Laravel managing the entire streaming process and naming the file

exists('file.jpg')

Returns a Boolean indicating whether file.jpg exists

getVisibility('myPath')

Gets the visibility for the given path (“public” or “private”)

setVisibility('myPath')

Sets the visibility for the given path (“public” or “private”)

copy('file.jpg', 'newfile.jpg')

Copies file.jpg to newfile.jpg

move('file.jpg', 'newfile.jpg')

Moves file.jpg to newfile.jpg

prepend('my.log', 'log text')

Adds content at the beginning of my.log

append('my.log', 'log text')

Adds content to the end of my.log

delete('file.jpg')

Deletes file.jpg

size('file.jpg')

Returns the size in bytes of file.jpg

lastModified('file.jpg')

Returns the Unix timestamp when file.jpg was last modified

files('myDir')

Returns an array of filenames in the directory myDir

allFiles('myDir')

Returns an array of filenames in the directory myDir and all subdirectories

directories('myDir')

Returns an array of directory names in the directory myDir

allDirectories('myDir')

Returns an array of directory names in the directory myDir and all subdirectories

makeDirectory('myDir')

Creates a new directory

deleteDirectory('myDir')

Deletes myDir

Adding Additional Flysystem Providers

If you want to add an additional Flysystem provider, you’ll need to “extend” Laravel’s native storage system. In a service provider somewhere—it could be the boot() method of AppServiceProvider, but it’d be more appropriate to create a unique service provider for each new binding—use the Storage facade to add new storage systems, as seen in Example 14-2.

// Some service provider
public function boot()
{
    Storage::extend('dropbox', function ($app, $config) {
        $client = new DropboxClient(
            $config['accessToken'], $config['clientIdentifier']
        );

        return new Filesystem(new DropboxAdapter($client));
    });
}

Methods Available on Session Instances

The two most common methods are get() and put(), but let’s take a look at each of the available methods and their parameters:

session()->get($key, $fallbackValue)

get() pulls the value of the provided key out of the session. If there is no value attached to that key, it will return the fallback value instead (and if you don’t provide a fallback, it will return null). The fallback value can be a string or a closure, as you can see in the following examples:

$points = session()->get('points');

$points = session()->get('points', 0);

$points = session()->get('points', function () {
    return (new PointGetterService)->getPoints();
});

session()->put($key, $value)

put() stores the provided value in the session at the provided key:

session()->put('points', 45);

$points = session()->get('points');

session()->push($key, $value)

If any of your session values are arrays, you can use push() to add a value to the array:

session()->put('friends', ['Saúl', 'Quang', 'Mechteld']);

session()->push('friends', 'Javier');

session()->has($key)

has() checks whether there’s a value set at the provided key:

if (session()->has('points')) {
    // Do something
}

You can also pass an array of keys, and it only returns true if all of the keys exist.

session()->has() and Null Values

If a session value is set but the value is null, session()->has() will return false.

session()->exists($key)

exists() checks whether there’s a value set at the provided key, like has(), but unlike has(), it will return true even if the set value is null:

if (session()->exists('points')) {
    // returns true even if 'points' is set to null
}

session()->all()

all() returns an array of everything that’s in the session, including those values set by the framework. You’ll likely see values under keys like _token (CSRF tokens), _previous (previous page, for back() redirects), and flash (for flash storage).

session()->only()

only() returns an array of only the specified values in the session (introduced in 5.8.28).

session()->forget($key) and session()->flush()

forget() removes a previously set session value. flush() removes every session value, even those set by the framework:

session()->put('a', 'awesome');
session()->put('b', 'bodacious');

session()->forget('a');
// a is no longer set; b is still set
session()->flush();
// Session is now empty

session()->pull($key, $fallbackValue)

pull() is the same as get(), except that it deletes the value from the session after pulling it.

session()->regenerate()

It’s not common, but if you need to regenerate your session ID, regenerate() is there for you.

Flash Session Storage

There are three more methods we haven’t covered yet, and they all have to do with something called “flash” session storage.

One very common pattern for session storage is to set a value that you only want available for the next page load. For example, you might want to store a message like “Updated post successfully.” You could manually get that message and then wipe it on the next page load, but if you use this pattern a lot it can get wasteful. Enter flash session storage: keys that are expected to only last for a single page request.

Laravel handles the work for you, and all you need to do is use flash() instead of put(). These are the useful methods here:

session()->flash($key, $value)

flash() sets the session key to the provided value for just the next page request.

session()->reflash() and session()->keep($key)

If you need the previous page’s flash session data to stick around for one more request, you can use reflash() to restore all of it for the next request or keep($key) to just restore a single flash value for the next request. keep() can also accept an array of keys to reflash.

Accessing the Cache

Just like with sessions, there are a few different ways to access a cache. You can use the facade:

$users = Cache::get('users');

Or you can get an instance from the container, as in Example 14-9.

Route::get('users', function (IlluminateContractsCacheRepository $cache) {
    return $cache->get('users');
});

You can also use the global cache() helper (introduced in Laravel 5.3), as in Example 14-10.

// Get from cache
$users = cache('key', 'default value');
$users = cache()->get('key', 'default value');
// Put for $seconds duration
$users = cache(['key' => 'value'], $seconds);
$users = cache()->put('key', 'value', $seconds);

If you’re new to Laravel and not sure which to use, I’d recommend using the global helper.

Methods Available on Cache Instances

Let’s take a look at the methods you can call on a Cache instance:

cache()->get($key, $fallbackValue) and
cache()->pull($key, $fallbackValue)

get() makes it easy to retrieve the value for any given key. pull() is the same as get() except it removes the cached value after retrieving it.

cache()->put($key, $value, $secondsOrExpiration)

put() sets the value of the specified key for a given number of seconds. If you’d prefer setting an expiration date/time instead of a number of seconds, you can pass a Carbon object as the third parameter:

cache()->put('key', 'value', now()->addDay());

cache()->add($key, $value)

add() is similar to put(), except if the value already exists, it won’t set it. Also, the method returns a Boolean indicating whether or not the value was actually added:

$someDate = now();
cache()->add('someDate', $someDate); // returns true
$someOtherDate = now()->addHour();
cache()->add('someDate', $someOtherDate); // returns false

cache()->forever($key, $value)

forever() saves a value to the cache for a specific key; it’s the same as put(), except the values will never expire (until they’re removed with forget()).

cache()->has($key)

has() returns a Boolean indicating whether or not there’s a value at the provided key.

cache()->remember($key, $seconds, $closure) and
cache()->rememberForever($key, $closure)

remember() provides a single method to handle a very common flow: look up whether a value exists in the cache for a certain key, and if it doesn’t, get that value somehow, save it to the cache, and return it.

remember() lets you provide a key to look up, the number of seconds it should be saved for, and a closure to define how to look it up, in case the key has no value set. rememberForever() is the same, except it doesn’t need you to set the number of seconds it should expire after. Take a look at the following example to see a common user scenario for remember():

// Either returns the value cached at "users" or gets "User::all()",
// caches it at "users", and returns it
$users = cache()->remember('users', 7200, function () {
    return User::all();
});

cache()->increment($key, $amount) and cache()->decrement($key, $amount)

increment() and decrement() allow you to increment and decrement integer values in the cache. If there is no value at the given key, it’ll be treated as if it were 0, and if you pass a second parameter to increment or decrement, it’ll increment or decrement by that amount instead of by 1.

cache()->forget($key) and cache()->flush()

forget() works just like Session’s forget() method: pass it a key and it’ll wipe that key’s value. flush() wipes the entire cache.

Cookies in Laravel

Cookies can exist in three places in Laravel. They can come in via the request, which means the user had the cookie when they visited the page. You can read that with the Cookie facade, or you can read it off of the request object.

They can also be sent out with a response, which means the response will instruct the user’s browser to save the cookie for future visits. You can do this by adding the cookie to your response object before returning it.

And lastly, a cookie can be queued. If you use the Cookie facade to set a cookie, you have put it into a “CookieJar” queue, and it will be removed and added to the response object by the AddQueuedCookiesToResponse middleware.

Accessing the Cookie Tools

You can get and set cookies in three places: the Cookie facade, the cookie() global helper, and the request and response objects.

$cookie = cookie('dismissed-popup', true, 15);

Route::get('dashboard', function (IlluminateHttpRequest $request) {
    $userDismissedPopup = $request->cookie('dismissed-popup', false);
});

Route::get('dashboard', function () {
    $cookie = cookie('saw-dashboard', true);

    return Response::view('dashboard')
        ->cookie($cookie);
});

When and Why to Use Logs

The most common use case for logs is to act as a semidisposable record of things that have happened that you may care about later, but to which you don’t definitively need programmatic access. The logs are more about learning what’s going on in the app and less about creating structured data your app can consume.

For example, if you want to have code that consumes a record of every user login and does something interesting with it, that’s a use case for a logins database table. However, if you have a casual interest in those logins but you’re not entirely certain whether you care or whether you need that information programmatically, you may just throw a debug- or info-level log on it and forget about it.

Logs are also common when you need to see the value of something at the moment it goes wrong, or at a certain time of day, or something else that means you want the data at a time when you’re not around. Throw a log statement in the code, get the data you need out of the logs, and either keep it in the code for later usage or just delete it again.

Writing to the Logs

The simplest way to write a log entry in Laravel is to use the Log facade, and use the method on that facade that matches the severity level you’d like to record. The levels are the same as those defined in RFC 5424:

Log::emergency($message);
Log::alert($message);
Log::critical($message);
Log::error($message);
Log::warning($message);
Log::notice($message);
Log::info($message);
Log::debug($message);

You can also, optionally, pass a second parameter that’s an array of connected data:

Log::error('Failed to upload user image.', ['user' => $user]);

This additional information may be captured differently by different log destinations, but here’s how this looks in the default local log (although it will be just a single line in the log):

[2018-09-27 20:53:31] local.ERROR: Failed to upload user image. {
    "user":"[object] (App\User: {
        "id":1,
        "name":"Matt",
        "email":"[email protected]",
        "email_verified_at":null,
        "api_token":"long-token-here",
        "created_at":"2018-09-22 21:39:55",
        "updated_at":"2018-09-22 21:40:08"
    })"
}

Log Channels

In Laravel 5.6, the way we configure and capture logs was changed pretty significantly to introduce the idea of multiple channels and drivers. If you’re working in 5.5 or earlier, you can skip on to “Full-Text Search with Laravel Scout”.

Like many other aspects of Laravel (file storage, database, mail, etc.), you can configure your logs to use one or more predefined log types, which you define in the config file. Using each type involves passing various configuration details to a specific log driver.

These log types are called channels, and out of the box you’ll have options for stack, single, daily, slack, stderr, syslog, and errorlog. Each channel is connected to a single driver; the available drivers are single, daily, slack, syslog, errorlog, monolog, custom, or stack.

We’ll cover the most common channels, here: stack, single, daily, and slack. To learn more about the drivers and the full list of channels available, take a look at the logging docs.

'single' => [
    'driver' => 'single',
    'path' => storage_path('logs/laravel.log'),
    'level' => 'debug',
],

'daily' => [
    'driver' => 'daily',
    'path' => storage_path('logs/laravel.log'),
    'level' => 'debug',
    'days' => 7,
],

'slack' => [
    'driver' => 'slack',
    'url' => env('LOG_SLACK_WEBHOOK_URL'),
    'username' => 'Laravel Log',
    'emoji' => ':boom:',
    'level' => 'critical',
],

'stack' => [
    'driver' => 'stack',
    'channels' => ['daily'],
    'ignore_exceptions' => false,
],

'channels' => [
    'stack' => [
        'driver' => 'stack',
        'channels' => ['daily', 'slack'],
    ],

    'daily' => [
        'driver' => 'daily',
        'path' => storage_path('logs/laravel.log'),
        'level' => 'info',
        'days' => 14,
    ],

    'slack' => [
        'driver' => 'slack',
        'url' => env('LOG_SLACK_WEBHOOK_URL'),
        'username' => 'Laravel Log',
        'emoji' => ':boom:',
        'level' => 'critical',
    ],

Log::channel('slack')->info("This message will go to Slack.");

Installing Scout

First, pull in the package in any Laravel 5.3+ app:

composer require laravel/scout

Next you’ll want to set up your Scout configuration. Run this command:

php artisan vendor:publish --provider="LaravelScoutScoutServiceProvider"

and paste your Algolia credentials in config/scout.php.

Finally, install the Algolia SDK:

composer require algolia/algoliasearch-client-php

Marking Your Model for Indexing

In your model (we’ll use Review, for a book review, for this example), import the LaravelScoutSearchable trait.

You can define which properties are searchable using the toSearchableArray() method (it defaults to mirroring toArray()), and define the name of the model’s index using the searchableAs() method (it defaults to the table name).

Scout subscribes to the create/delete/update events on your marked models. When you create, update, or delete any rows, Scout will sync those changes up to Algolia. It’ll either make those changes synchronously with your updates or, if you configure Scout to use a queue, queue the updates.

Searching Your Index

Scout’s syntax is simple. For example, to find any Review with the word Llew in it:

Review::search('Llew')->get();

You can also modify your queries as you would with regular Eloquent calls:

// Get all records from the Review that match the term "Llew",
// limited to 20 per page and reading the page query parameter,
// just like Eloquent pagination
Review::search('Llew')->paginate(20);

// Get all records from the Review that match the term "Llew"
// and have the account_id field set to 2
Review::search('Llew')->where('account_id', 2)->get();

What comes back from these searches? A collection of Eloquent models, rehydrated from your database. The IDs are stored in Algolia, which returns a list of matched IDs; Scout then pulls the database records for those and returns them as Eloquent objects.

You don’t have full access to the complexity of SQL WHERE commands, but it provides a basic framework for comparison checks like you can see in the code samples here.

Queues and Scout

At this point your app will be making HTTP requests to Algolia on every request that modifies any database records. This can slow down your application quickly, which is why Scout makes it easy to push all of its actions onto a queue.

In config/scout.php, set queue to true so that these updates are set to be indexed asynchronously. Your full-text index is now operating under “eventual consistency”; your database records will receive the updates immediately, and the updates to your search indexes will be queued and updated as fast as your queue worker allows.

Performing Operations Without Indexing

If you need to perform a set of operations and avoid triggering the indexing in response, wrap the operations in the withoutSyncingToSearch() method on your model:

Review::withoutSyncingToSearch(function () {
    // Make a bunch of reviews, e.g.
    factory(Review::class, 10)->create();
});

Conditionally Indexing Models

Sometimes you might only want to index records if they meet a certain condition. You may use the shouldBeSearchable() method on the model class to achieve this:

public function shouldBeSearchable()
{
    return $this->isApproved();
}

Manually Triggering Indexing via Code

If you want to manually trigger indexing your model, you can do it using code in your app or via the command line.

To manually trigger indexing from your code, add searchable() to the end of any Eloquent query and it will index all of the records that were found in that query:

Review::all()->searchable();

You can also choose to scope the query to only those records you want to index. However, Scout is smart enough to insert new records and update old records, so you may choose to just reindex the entire contents of the model’s database table.

You can also run searchable() on relationship methods:

$user->reviews()->searchable();

If you want to unindex any records with the same sort of query chaining, just use unsearchable() instead:

Review::where('sucky', true)->unsearchable();

Manually Triggering Indexing via the CLI

You can also trigger indexing with an Artisan command:

php artisan scout:import "AppReview"

This will chunk all of the Review models and index them all.

File Storage

Testing file uploads can be a bit of a pain, but follow these steps and it will be clear.

public function test_file_should_be_stored()
{
    Storage::fake('public');

    $file = UploadedFile::fake()->image('avatar.jpg');

    $response = $this->postJson('/avatar', [
        'avatar' => $file,
    ]);

    // Assert the file was stored
    Storage::disk('public')->assertExists("avatars/{$file->hashName()}");

    // Assert a file does not exist
    Storage::disk('public')->assertMissing('missing.jpg');
}

$factory->define(User::class, function (FakerGenerator $faker) {
    return [
        'picture' => $faker->file(
            storage_path('tests'), // Source directory
            storage_path('app'), // Target directory
            false // Return just filename, not full path
        ),
        'name' => $faker->name,
    ];
});

public function test_user_profile_picture_echoes_correctly()
{
    $user = factory(User::class)->create();

    $response = $this->get(route('users.show', $user->id));

    $response->assertSee($user->picture);
}

Session

If you need to assert something has been set in the session, you can use some convenience methods Laravel makes available in every test. All of these methods are available in your tests on the IlluminateFoundationTestingTestResponse object:

assertSessionHas($key, $value = null)

Asserts that the session has a value for a particular key, and, if the second parameter is passed, that that key is a particular value:

public function test_some_thing()
{
    // Do stuff that ends up with a $response object...
    $response->assertSessionHas('key', 'value');
}

assertSessionHasAll(array $bindings)

If passed an array of key/value pairs, asserts that all of the keys are equal to all of the values. If one or more of the array entries is just a value (with PHP’s default numeric key), it will just be checked for existence in the session:

$check = [
    'has',
    'hasWithThisValue' => 'thisValue',
];

$response->assertSessionHasAll($check);

assertSessionMissing($key)

Asserts that the session does not have a value for a particular key.

assertSessionHasErrors($bindings = [], $format = null)

Asserts that the session has an errors value. This is the key Laravel uses to send errors back from validation failures.

If the array contains just keys, it will check that errors are set with those keys:

$response = $this->post('test-route', ['failing' => 'data']);
$response->assertSessionHasErrors(['name', 'email']);

You can also pass values for those keys, and optionally a $format, to check that the messages for those errors came back the way you expected:

$response = $this->post('test-route', ['failing' => 'data']);
$response->assertSessionHasErrors([
    'email' => '<strong>The email field is required.</strong>',
], '<strong>:message</strong>');

Cache

There’s nothing special about testing your features that use the cache—just do it:

Cache::put('key', 'value', 900);

$this->assertEquals('value', Cache::get('key'));

Laravel uses the array cache driver by default in your testing environment, which just stores your cache values in memory.

Cookies

What if you need to set a cookie before testing a route in your application tests? You can manually pass cookies to one of the parameters of the call() method. To learn more about call(), check out Chapter 12.

use IlluminateCookieMiddlewareEncryptCookies;
...

$this->app->resolving(
    EncryptCookies::class,
    function ($object) {
        $object->disableFor('cookie-name');
    }
);

// ...run test

That means you can set and check against a cookie with something like Example 14-21.

public function test_cookie()
{
    $this->app->resolving(EncryptCookies::class, function ($object) {
        $object->disableFor('my-cookie');
    });

    $response = $this->call(
        'get',
        'route-echoing-my-cookie-value',
        [],
        ['my-cookie' => 'baz']
    );
    $response->assertSee('baz');
}

If you want to test that a response has a cookie set, you can use assertCookie() to test for the cookie:

$response = $this->get('cookie-setting-route');
$response->assertCookie('cookie-name');

Or you could use assertPlainCookie() to test for the cookie and to assert that it’s not encrypted.

Log

The simplest way to test that a certain log was written is by making assertions against the Log facade (learn more in “Faking Other Facades”). Example 14-22 shows how this works.

// Test file
public function test_new_accounts_generate_log_entries()
{
    Log::shouldReceive('info')
        ->once()
        ->with('New account created!');

    // Create a new account
    $this->post(route('accounts.store'), ['email' => '[email protected]']);
}

// AccountController
public function store()
{
    // Create account

    Log::info('New account created!');
}

There’s also a package called Log Fake that expands on what you can do with the facade testing shown here and allows you to write more customized assertions against your logs.

Scout

If you need to test code that uses Scout data, you’re probably not going to want your tests triggering indexing actions or reading from Scout. Simply add an environment variable to your phpunit.xml to disable Scout’s connection to Algolia:

<env name="SCOUT_DRIVER" value="null"/>