The local scope way

In our codebase, we have a model Transaction that stores transactions for our users. If we want to get the transaction for a logged-in user from the database, we could do it like this:

$transactions = Transaction::where('user_id', auth()->id())->get();

Since we would use this a lot throughout the codebase, it would make sense to create a local scope in the Transaction model like this:

namespace App\Models;

use Illuminate\Database\Eloquent\Model;
use Illuminate\Database\Eloquent\Relations\BelongsTo;

class Transaction extends Model
{
    // ...

    public function scopeForLoggedInUser($query): void
    {
        $query->where('user_id', auth()->id());
    }
}

With this local scope, we can make the query like this:

$transactions = Transaction::forLoggedInUser()->get();

This is a nice DRY (Don't Repeat Yourself) refactor that cleans it up a little.

A question you should ask yourself

Local scopes are awesome, I use them where I can to keep the code DRY. But I learned to ask myself this question when I create a local scope: “Will the majority of the queries for this model use this local scope”.

If the answer is no, keep the local scope. It makes a lot of sense to use it.

When the answer is yes

This would be the point when considering a global scope. A global scope is always applied to all queries of a given model. You can create a global scope simply by creating a class that implements Illuminate\Database\Eloquent\Scope.

<?php

namespace App\Models\Scopes;

use Illuminate\Database\Eloquent\Builder;
use Illuminate\Database\Eloquent\Model;
use Illuminate\Database\Eloquent\Scope;

class TransactionsForLoggedInUserScope implements Scope
{

    public function apply(Builder $builder, Model $model)
    {
        $builder->where('user_id', auth()->id());
    }
}

After that, you should let your model be aware of the global scope:

<?php

namespace App\Models;

use App\Models\Scopes\TransactionsForLoggedInUserScope;
use Illuminate\Database\Eloquent\Model;

class Transaction extends Model
{
    // ...

    protected static function booted(): void
    {
        static::addGlobalScope(new TransactionsForLoggedInUserScope());
    }
}

If you would now get all the transactions, it will only return the transactions of the logged-in user.

Transaction::all();

Removing a global scope

There are some scenarios thinkable where you want to create a Transaction query without the global scope applied. For example, in an admin overview or for some global statistic calculations. This can be done by using the withoutGlobalScope method:

Transaction::withoutGlobalScope(TransactionsForLoggedInUserScope::class)->get();

Anonymous Global Scopes

There is also a way to create a global scope without the use of an extra file. Instead of pointing to the TransactionsForLoggedInUserScope class, you can include the query like this:

<?php

namespace App\Models;

use Illuminate\Database\Eloquent\Model;

class Transaction extends Model
{
    // ...

    protected static function booted(): void
    {
        static::addGlobalScope('for_logged_in_users', function (Builder $builder) {
            $builder->where('user_id', auth()->id());
        });
    }
}

Personally, I don't like anonymous global scopes since it can bloat your model if the query is a bit complex. To be consistent throughout the entire codebase, I always tend to use the external file global scopes, even if the query is as simple as in our example.

The downside of global scopes

I won't lie to you, if you're working on a codebase with global scopes and are not aware of them, you might fall into situations where nothing makes sense anymore. It made me question my career choices one (very bad) day 😂. You will get totally unexpected results when tinkering. If this has happened once, you've learned that it is good to have the withoutGlobalScopes method in your tool belt while working in a codebase you're not quite familiar with.

Security

If the security of your app relies on a global scope, it's dangerous when you or a fellow developer will make changes to it in the future. Imagine in our example that someone would remove or change the global scope. Then all results for a user's transactions would be completely faulty! This is why it's really important to implement tests for global scopes, so this can't happen. A typical (PEST) test for our example would look like this:

it("should only get the transactions for the logged-in user", function (){
    $user = User::factory()->create();
    $otherUser = User::factory()->create();

    $transaction_1 = Transaction::factory()->create(['user_id' => $user->id]);
    $transaction_2 = Transaction::factory()->create(['user_id' => $otherUser->id]);

    $this->actingAs($user);
    expect(Transaction::all())->toHaveCount(1)
        ->and($transaction_1->is(Transaction::first()));
});

There is a way to protect your public properties in Livewire 2 in the way it will work in the upcoming Livewire 3. There is a Trait at the end of the article you can use for this.

Why should you protect model ID's in Livewire

Livewire is great! It provides superpowers to your backend code to also create a reactive frontend without relying heavily on JavaScript. But as with everything, with great power comes great responsibility. I’ve been working with Livewire since version 1 with much enthusiasm. In the years of using it, I’ve developed some best practices for performance and security. In this article, I will focus on what I think is the most important thing in Livewire security.

One caveat in Livewire (version 1 and 2) is that only public properties remain state between Livewire interactions. This shouldn’t be a problem, at least not if you’re aware of how a potential hacker would abuse this. Let’s go over this by a simplified example. We’ll create a very simple Livewire component that will publish a draft blog post.

A different best practice that I need to mention is to only store the model ID and not the entire model in a public property. I know we are allowed to do this, but this will impact performance, but that is out of the scope of this article.

Let’s start by creating this component and see how this can be exploited.

<?php

namespace App\Http\Livewire;

use App\Models\Post;
use Livewire\Component;
use Illuminate\Contracts\View\View;
use Illuminate\Auth\Access\AuthorizationException;
use Illuminate\Foundation\Auth\Access\AuthorizesRequests;

class EditPostComponent extends Component
{
    use AuthorizesRequests;

    public int $postId;

    public $state = [
        'title' => '',
        'body' => '',
        'published' => false,
    ];

    public function rules(): array
    {
        return [
            'state.title' => 'required|string|max:255',
            'state.body' => 'required|string|max:5000',
            'state.published' => 'boolean',
        ];
    }

    /**
     * @throws AuthorizationException
     */
    public function mount(Post $post): void
    {
        $this->authorize('update', $post);

        $this->postId = $post->id;
        $this->state = $post->only('title', 'body', 'published');
    }

    public function render(): View
    {
        return view('livewire.edit-post-component');
    }

    /**
     * @throws AuthorizationException
     */
    public function save(): void
    {
        $this->validate();
        $post = Post::findOrFail($this->postId);
        $this->authorize('update', $post);

        $post->title = $this->state['title'];
        $post->body = $this->state['body'];
        $post->save();
    }
}

Let's see what the component does. When the component is loaded:

• We will check if the user is allowed to update this post with $this->authorize('update', $post); (the policy to check this is out of the scope of this article).

• After all checks out, we will hydrate the state and fill the $postId.

When a user makes changes and calls save:

• We'll get the Post model from the database.

• Check again if the user is allowed to edit this Post and save the changes.

For clarity, I've left out all the code for the frontend in this article.

Let's hack this component!

There are a couple of ways how you can change a public Livewire property. Here is a simple one. Firstly, go into the Chrome devtools and search in the source code where you can find wire:id=xxxxxxx and select it. After that, you can go to the console and type $0.__livewire.data, you can see that the result provides you all the public properties. When you type $0.__livewire.$wire.postId = 4 you've successfully changed the $postId. If you would now make changes to any of the fields, it will be saved to the Post id of 4. It's that easy!

How to protect your component

There are multiple ways how we can protect our component. The first one is really easy: Wait until Livewire 3 is released, since we will then get the possibility to protect public properties by adding the /** @locked */ annotation. But at this point, we're unaware when Livewire 3 will be released.

I have to be honest, I used to protect my components by encrypting and decrypting the ID within the component. When someone would try to change the value and the new value was not decryptable, it would throw an error that I would catch. But later on I found a great different approach by Mark Snape in this video: https://www.youtube.com/watch?v=bA1dMbUiwuA. Mark listens in the Livewire component to see if someone would update the PostId and then throw an error. I think this is the best approach possible!

I tried to take this a little further and created a Trait, so we can use it easily in all our components and also use the /** @locked */ annotation, so it will also be compatible with Livewire 3 💪🏻. After upgrading to Livewire 3, we only need to remove the Trait, and we're done.

In our component, we'll just need to add the annotation and import our Trait.

<?php

namespace App\Http\Livewire;

use App\Models\Post;
use Livewire\Component;
use Illuminate\Contracts\View\View;
use App\Traits\WithLockedPublicPropertiesTrait;
use Illuminate\Auth\Access\AuthorizationException;
use Illuminate\Foundation\Auth\Access\AuthorizesRequests;

class EditPostComponent extends Component
{
    use AuthorizesRequests, WithLockedPublicPropertiesTrait;

    /** @locked  */
    public int $postId;

    ...
}

And here is the trait that we can use for this.

<?php

namespace App\Traits\Livewire;

use Str;
use ReflectionException;
use App\Exceptions\LockedPublicPropertyTamperException;

trait WithLockedPublicPropertiesTrait
{
    /**
     * @throws LockedPublicPropertyTamperException|ReflectionException
     */
    public function updatingWithLockedPublicPropertiesTrait($name): void
    {
        $propertyName = Str::of($name)->explode('.')->first();
        $reflectionProperty = new \ReflectionProperty($this, $propertyName);
        if (Str::of($reflectionProperty->getDocComment())->contains('@locked')) {
            throw new LockedPublicPropertyTamperException("You are not allowed to tamper with the protected property {$propertyName}");
        }
    }
}

The Trait uses ReflectionProperty to see if @locked is available on the property that is about to be changed. If so, it will throw an LockedPublicPropertyTamperException exception. You need to create this exception first, of course. Since I always store all the state in a public $state array, the updated Livewire model name will be something like state.title, since we only need the first part of this dot-notation, we strip the unneeded part in the first line of the method.

You can follow me on twitter to stay up to date with Laravel and Livewire articles https://twitter.com/stef_r

Tests are great! They're probably the reason why you're still able to sleep at night after someone decided you had to make some last minute changes. Also, they really speed up your development. Imagine working on a piece of code that has a lot of dynamics based on variables, if we didn't have tests it would be really hard to work on it by having to manually click around in the browser in to check if the code still works after every change. We can do that in milliseconds with tests! Anyway, tests have made me a better and a more confident developer.

Pest

Pest is awesome! It makes the tests so much more readable. It allows you to still use PHPUnit and Pest syntax at the same time, so you can slightly shift over to Pest at your own pace. Pest makes your tests almost read like a nice story. That comes in handy when get back to a codebase after a few months or have to work on tests that someone else created.

Make changes in the background during the pest chain

Livewire Pest tests can look like a nice chain of actions and assertions on the Livewire component, which I fancy a lot. However, sometimes you need to make changes to the database or assert on a model (that is not on the Livewire component) during the chain at some point. There are a few ways how we can handle that.

I'll illustrate this with a very simple example. Imagine if we have an Order model in Laravel and an OrderComponent Livewire component. We have a refresh button that would call our refreshOrderCount() public method, and this would update the $orderCount public property. Simple stuff!

Here is the component:

<?php

namespace App\Http\Livewire;

use App\Models\Order;
use Livewire\Component;

class OrderDashboardComponent extends Component
{
    public int $orderCount = 0;

    public function mount()
    {
        $this->orderCount = Order::count();
    }

    public function render()
    {
        return view('livewire.order-dashboard-component');
    }

    public function refreshOrderCount()
    {
        $this->orderCount = Order::count();
    }
}

If we want to write a test for this behaviour, we would have to add a new order during the Pest Livewire test chain.

it('should update the orderCount', function(){
    livewire(OrderDashboardComponent::class)
        ->assertSet('orderCount', 0)
        ->call('refreshOrderCount')
                // Here we should add an order to the database
        ->assertSet('orderCount', 1);
}); // (This test would fail)

If we started with the test above, we should add the new order right after the ->assertSet('orderCount', 0) assertion. Unfortunately, we can't do this in this Pest chain. So we would have to do something like this:

it('should update the orderCount', function(){
    $component = livewire(OrderDashboardComponent::class);

    $component->assertSet('orderCount', 0);

    Order::factory()->create();

    $component->call('refreshOrderCount')
        ->assertSet('orderCount', 1);
});

The above code will work, but it looks kind of messy to me, so I came up with the idea to use tap() to make this work from within the chain.

it('should update the orderCount', function(){
    livewire(OrderDashboardComponent::class)
        ->assertSet('orderCount', 0)
        ->tap(function(){
            Order::factory()->create();
        })
        ->call('refreshOrderCount')
        ->assertSet('orderCount', 1);
});

Or even better:

it('should update the orderCount')
    ->livewire(OrderDashboardComponent::class)
    ->assertSet('orderCount', 0)
    ->tap(function(){
        Order::factory()->create();
    })
    ->call('refreshOrderCount')
    ->assertSet('orderCount', 1);

Great, this looks so much better to me! What do you think? You can also use tap to make assertions on a model that is not available in the Livewire component as a property.

I recently got a question from a client about disappearing line breaks. It was a valid question since the text came from a textarea input that was echoed out on a page. The type of content was really simple and had no need for markup, so no WYSIWYG or Markdown editor was necessary. However, line breaks were really important in this case.

PHP offers the nl2br() function that has been around since PHP 4. This function will return a string with <br /> or <br> inserted before all newlines (\r\n, \n\r, \n and \r). Just what we need! Let's put it to work with this variable for this example:

$description = 'This is line one\nThis is line 2\nThis is line 3';

<div>
    {{ nl2br($description) }}
</div>

Nope! That will output: This is line one<br /> This is line 2<br />This is line 3 because we've been using the {{ }} statements. Blade {{ }} statements are automatically sent through PHP's htmlspecialchars function to prevent XSS attacks. By using {!! !!} statements, we can completely skip the unescaping and get the result we want, right? No, that is a terrible idea! Our code would then be vulnerable to XSS attacks.

Here is a really simple rule of thumb: if you are in need of using the {!! !!} statement, take a step back and ask yourself: Where does the content come from? If the content comes from some kind of form or other user input, you should NEVER use it to protect yourself against XSS attacks. There are plenty of valid reasons for using {!! !!} statements, but not in our case.

The solution

So what can we do? Well, in my knowledge there are two simple solutions here:

• Make use of CSS
• Make use of PHP

Solve it with CSS

The CSS solution is incredibly simple. We can make use of the white-space CSS property. It is very safe to use since it's supported for a very long time by all major browsers.

<div style="white-space: pre-line">
    {{ $description }}
</div>

Solve it with PHP

If you're not able to use the CSS solution for whatever reason, there’s always the good old PHP to the rescue. Writing PHP makes me happy, so let's get started! We could explode on the line breaks and create an array of single lines. Then we can iterate over them and output them with the safe {{ }} statements. To make sure we explode on the line breaks, we can make use of the PHP_EOL constant.

@foreach(explode(PHP_EOL, $description) as $line )
    {{ $line }} <br>
@endforeach

Bonus: solve it in an anonymous Blade component

I love Blade components, they clean up the view files and make it so much better readable and prevent unneeded repetition.

\\ Blade component
@props(['content'])

@foreach(explode(PHP_EOL, $content) as $line)
    {{ $line }} <br>
@endforeach


\\ Usage
<x-safe-line-breaks :content="$description"/>

TLDR;

This guide will make you install Xdebug on your Mac without the performance downsides, but still being able to use all the Xdebug goodnesses. Most Xdebug setups only allow you to use it through a web browser plugin. This is not helpful when you’re following a TDD approach. So we’ll get it to work right from your tests in PhpStorm, no browser needed!

Having tests is awesome!

I’m a huge fan of tests in Laravel and try to develop as much as possible using the TDD approach. When a project grows over the years, your tests are becoming like a guard that will tell when you messed up functionality by adding or changing some code later on. This gives a peace of mind and has saved my bacon many times already.

PhpStorm has a great GUI for running PHPUnit tests where you’re able to click directly on the links to the scripts where a test fails. I love this workflow and I’ve never used phpunit on the command line since. However, when your tests fail, it can become somewhat cumbersome to figure out what is going on. The first thing I always do is add ->dump() to the request, that will point me in the right direction most of the time. But there are cases where you really need to dig into the code. This is where I previously placed some dd() in the code and then tried to follow the steps. Raise your hand if you’ve been there 🤚!

Xdebug is a wonderful tool that can help you with that, but I previously used it a long time ago with a browser plugin. Since PHPUnit gets really slow when Xdebug is installed and it also impacts the composer performance, I removed it from my system and never used it since. Until I recently discovered “on-demand Xdebug” in PhpStorm! This will not enable Xdebug by default, and will only use it when you need to. It’s really simple to set up and I love using it! You can also use it directly in your tests, so you don’t have to recreate the situation in your browser. I’ll show you how to install and use it in this article.

Install

In our company we only use Mac’s, I have no idea how to set this up on Windows, so you’ll have to google around if that’s your case. For Linux, it will more or less be the same (except for PHP installation) I think.

I’m assuming you’ve been using Homebrew to install the latest version of PHP. It’s as simple as brew install php.

Extensions as Xdebug have recently been removed from Homebrew and need to be installed using PECL. Luckily that is also really easy! pecl install xdebug The install will add a reference to Xdebug in your php.ini file so it will be loaded by default. We don’t want that! So we’ll remove this reference. Here’s how to do it: On your command line enter: php --ini this will give you the path of the php.ini file that is used on your system.

Open the file in an editor of your choice, or use the default editor for this filetype. In the case of our example, we can do this with the command open /usr/local/etc/php/7.2/php.ini. This will open the php.ini file. We can see the reference added by the Xdebug installer on line 1: zend_extension=”xdebug.so”. We need to remove this line so Xdebug is not loaded by default anymore. There, all done 🥳!

PhpStorm setup

I’ll assume you have a setup for your TDD workflow in PhpStorm. The purpose of this guide is only to extend it with Xdebug. If you don’t have it, here is an old but still relevant video from Laracasts.com: Be Awesome in PHPStorm: Testing in PHPStorm.

We will need to tell PhpStorm where Xdebug is located for using it on demand. In the settings navigate to Languages and Frameworks and then PHP. On the CLI Interpreter click on the … button like in the screenshot.

Now we can specify where Xdebug is located on your system. In our example this is in /usr/local/lib/php/pecl/20170718/xdebug.so, but this path depends on the version and can be different on your system. So be sure to click on the folder icon to navigate through your system and find it.

When the path is correct and you hit the refresh button, you will see the Xdebug version that was found by PhpStorm.

Using it

For sake of simplicity, we’ll create a simple test where we assert the content of two routes. The routes we’re about to test will just return some variables, nothing fancy going on here, you’ll get the idea. Laravel makes creating tests really easy with the artisan helper php artisan make:test TwoRoutesTest.

In the image below you can see how the tests are run when you’ll hit the green “play” button, nothing new here. Did you also know about the SHIFT + CTRL + R shortcut? Place your cursor in a test and hit the shortcut and only this single test will run. When you place the cursor outside of a test, all the tests of this test-file will run. I really love this shortcut 😍!

Now, let's use Xdebug!

Go to your code and place some breakpoints on the left side of the lines. They will be marked with red circles when you click them. This time, don’t click the green “play” button, but the red bug on the right side of it.

The test will stop on the first breakpoint. You’ll get a nice overview of all (global) variables in the debug screen. When you press the green “play / pause” button on the left side of the screen you’ll go to the next breakpoint. You can really dig in the code now to figure out where your bugs happen. I won’t go into detail about all the PhpStorm/Xdebug functionality. That might be a completely different blog post.

Happy debugging

I hope this will enhance your debugging workflow as much as it did for me!

But still, there are a few challenges when it comes to localization. Translation is not the only concern. In this post, I will try to explain and also give the solution we’re using at Involved Group (we made this package public available). I’ll try to illustrate with some examples of a dashboard app. Typically these kinds of apps don’t use localization preferences in the URL’s and need some other input to set the Laravel locale settings.

Challenge 1: ‘Country’ !== ‘Language’

Let’s tell you our story how this ball got rolling in our development. In Belgium, there are two spoken languages: French and Dutch (Flemish). We were serving many languages in our app, the Belgium users were able to select either the Dutch or the French flag in the language selector. Problem solved, right? No! Our Belgium users complained that there was a Dutch flag on their account while they were Belgian users. Remember that our goal as developers should be to make our users feel welcome and appreciated? These clients really had a fair point. How could we solve this through out-of-the-box Laravel? We could create two more translation .json files like nl-BE.json and fr-BE.json and then set the Laravel Locale to either _nl-BE_ or fr-BE. The downside of this approach is that we need to have these .json files created and translated while the content will be exactly the same as the nl.json and fr.json files. This is will result in maintenance mess and is not an option for us.

Challenge 2: Date formats are defined by the country, not the language.

We’ve been using the awesome Date package in our apps. It’s always one of the first dependencies we’re adding for almost every new project. It is like a translation wrapper around Carbon, if you’ve never used it, give it a try! One of the problems we encounter is that we now have the ability to translate the date, but not automatically format the date according to the country’s preferences.

Example

We’ve established the Belgian/Dutch differences already, but let’s take this a step further. In The Netherlands, the date will be typically written like d-m-Y, in Belgium the format d/m/Y is more common and in Germany d.m.Y. Small difference, but it’s just the small things that matter to make a user feel comfortable with the app he or she is using. A bigger difference is when we would like to spell out the date in full text. In the Netherlands this would default to l j F Y (dinsdag 24 april 2018) while in the US this would be l F jS Y (Tuesday April 24th 2018).

The solution

We’ve created a package that can help you. We’ll not go too much in detail, you can read the rest on the github page or in the code.

A middleware for all page visits will be set. When no user (with lang_country preference) is detected, we’ll try to make a perfect match between the browser language preferences and the allowed language/countries in the config file. The lang_country variable will be stored in a session.

The user can change the lang_country variable through the language/country selector (the package will provide a nice helper for this).

The lang_country variable will match a .json file in the package which stores all the applicable settings for this lang_country. The middleware will set the right locale for Laravel for the translation and also the right locale for the Date package.

You’ll be responsible for the right language .json files in the /resources/lang directory. But you’re able to create different files for certain language/country combinations if you need this. We’ll make a smart check on that. So if your lang_country variable is es-CO we will check if this file is present: /resources/lang/es-CO.json. If so, we’ll set the Laravel Locale to es-CO so this file is used. If not, we’ll set the Laravel Locale to ‘es’ so the /resources/lang/es.json is used.

When we need nice date format string we can use:

\LangCountry::dateWordsWithDay($blog->post->created_at);

in our code. Now, every user will see a date format which is comfortable for them.

The package does more:

• We’ll store the lang_locale preference in the User record of the database if you want this.
• It provides a helper to make a simple language/country switcher dropdown. The LangCountry Facade has a lot of helpers, check it out!

I’m pretty sure your opinion about this can differ, that’s cool! But if you’re on the same page as us, take a look at our package and save yourself some time!