Forem: Robson Tenório

Livewire: The best of both worlds

Robson Tenório — Wed, 22 Nov 2023 00:42:32 +0000

One project

During the first web wave, you have heard about the MVC pattern. There was some technical limitations at that time to deliver a better user experience (UX): slow page transitions, "poor" interfaces and awful usability.

Ah, and we had the spaghetti style with some database queries inside views. But this was the programmers' fault, not a fault from the MVC pattern itself.

But... it worked out at the end of the day! It was one project.

Two projects

After the condemnation of the MVC pattern, modern frontend frameworks such as Vue, React and Angular rapidly emerged... now the application loads faster, full page reloads are not required anymore and users experience a better UX. You know it as SPA (Single Page Application).

By nature, a SPA imposes the concept of separation between frontend and backend. Now, you have two projects.

Then, every single time that the frontend needs some new data the backend needs to be improved. And now you get:

Two repositories to manage.
Two deploy pipelines to manage.
Two teams to manage.

Not to mention that it is necessary to duplicate:

Authentication.
Authorization.
Some parts of business rules.

Because, well... they are two different projects.

The pieces are separated but intimately linked. In the end, this is just one product splitted in two projects.

One project (again)

What if it was possible to make things simple again?

One deploy pipeline to manage.
One team to manage.
One project (again).

Now enters Livewire: a full-stack framework for Laravel that takes the pain out of building dynamic UIs.

You can go right away to the docs and find out by yourself how productive you can be.

If you have previously worked with Vue/React/Angular you will quickly notice something: where are the UI components libraries?

Well, there are not that many libraries available for Livewire. But, now you have MaryUI: great DX and UX with minimal effort.

Conclusion

A puzzle becomes easier to put together when the pieces are close enough to each other. Keep things simple and avoid complexity at all costs.

Remember that using Livewire will not stop people from making the same mistakes as they did in the past.

Our way: Enums

Robson Tenório — Thu, 19 Oct 2023 22:38:35 +0000

👉 Go to Summary

.
.
.

Why not Enums?

Don't get me wrong: Enums are useful, but it is pretty "hardcoded".

We can do it better!

Better approach: use Models

Consider this migrations.

Schema::create('status', function (Blueprint $table) {
   $table->id();
   $table->string('name');
   $table->string('description');
   $table->string('color');
}

Schema::create('orders', function (Blueprint $table) {
   $table->id();
   $table->foreignId('status_id')->constrained();
   $table->decimal('amount');
}

Consider this Models.

class Status extends Model 
{
   public const PENDING = 1;
   public const APPROVED = 2;
   public const DONE = 3;
}

class Order extends Model 
{
   public function status() 
   {
      return $this->belongsTo(Status::class);
   }
}

It is done!

$orders = Order::with('status')->get();

@foreach($orders as $order)

   <div>
       Order: {{ $order->id }} , {{ $order->amount }} 

       <!-- No needed `IF` to define a color ou print a human name -->
       <span class="{{ $order->status->color }}">
           {{ $order->status->name }}
       </span>

       <div class="text-sm">
           {{ $order->status->description }}
       </div>
   </div>

@endforeach

Benefits

Making status as a Model:

Dynamic config.
No extra helpers or IFs to show status details.
It is easy to query.

Our way: Tests

Robson Tenório — Thu, 19 Oct 2023 20:43:38 +0000

👉 Go to Summary

.
.
.

The coverage test trap

The 100% coverage does not mean anything by itself.
You have to be confident.
You have to be confident.
You have to be confident.
Yes, 3 times.
Are you really testing what matters? Double check it.

Test what matters

Test only your business rule.
You don't need to test what is backed by Laravel.
Rule of thumb: if you mutated data you need to test it!

// You have a business rule here to test
// You must assure that aged people need assistance, by default!


public function save(Request $request) 
{    

    $data = $request->validate(...);


    if ($data['age'] > 60) {
        $data['need_assistance'] = true;
    }

    User::create($data);

}

// You have a business rule here to test
// After creating an user, you have insert data in another table


public function save(Request $request) 
{    

    $data = $request->validate(...);

    User::create($data);

    Invite::create([something will be created here])

}

Basics

Get green is not enough, get confident.
Test behavior (input/output), not implementation details (mocks).
Test’s name is important.
Write comments before writing test (GIVEN, WHEN, THEN).
Complex features can have more than one test class.


// I don't give a shit how avatar was generated!
// I just wanna see the avatar !

class CreateAvatarTest extends TestCase {

    public function test_create_online_user_avatar()
    {
        // GIVEN there is a user
        $user = UserFactory::new()->create();

        // WHEN I request to make an avatar
        $response = $this->get("/avatar-maker?for={$user->id}")

        // THEN I get avatar's URL
        $response->assertJsonFragment(['url' => 'https://...']);

    }    
}

Our way: Classes and Methods

Robson Tenório — Thu, 19 Oct 2023 20:43:23 +0000

👉 Go to Summary

.
.
.

Class attributes types

WTF!?

class Customer
{
    public $points;
    public $available;
}

Nice!

class Customer
{
    public int $points;
    public bool $available;
}

.
.
.

Constructor property promotion

WTF!?

class Customer
{
    public string $name;
    public string $email;
    public Date $birth_date;

    public function __construct(
        string $name, 
        string $email, 
        Date $birth_date
    ) {
        $this->name = $name;
        $this->email = $email;
        $this->birth_date = $birth_date;
    }
}

Nice!

class Customer
{
    public function __construct(
        public string $name, 
        public string $email, 
        public Date $birth_date,
    ) { }
}

.
.
.

Methods types

WTF!?

public function calculate($points, $available)
{
   ...

   return $score;
}

Nice!

public function calculate(int $points, bool $available): float
{
   ...

   return $score;
}

.
.
.

Fluent sintaxe

WTF!?

$mary = User::first();

$payment = new Payment(12.98, '2023-01-09', $mary, 4.76);
$payment->process();

Nice!

$mary = User::first();

(new Payment)
   ->for($mary)
   ->amount(12.98)
   ->discount(4.78)
   ->due('2023-01-09')
   ->process();

.
.
.

Encapsulate contexts

WTF!?


public function makeAvatar(string $gender, int $age, string $hairColor)
{
   ...   
   return 'https://...';
}

$user = User::first();

makeAvatar($user->gender, $user->age, $user->hairColor);

Nice!

public function makeAvatarFor(User $user): string
{
   ...
   return 'https://...';
}

$user = User::first();

makeAvatarFor($user);

Our way: Actions vs Services

Robson Tenório — Thu, 19 Oct 2023 20:42:58 +0000

👉 Go to Summary

.
.
.

Actions

It represents an internal app use case.
Each action must contain one use case.
Naming is important.
An action can call another action or service in complex scenarios.


class MakeUserAvatarAction {

    function __construct(){ 
        // ... 
    }

    function execute(){
        // It does only 1 thing
    }    
}

Services

It represents external integrations, commonly through API.
You can have many methods.

class KeycloakService{

    function __construct(){ 
        // ... 
    }

    function createUser() { }

    function syncRoles() { }

    ...
}

Actions vs Services

An action has one method, that solves one internal use case.
An service can have more methods, that represents an external integration.

app/
    |
    |__ Actions/    
    |   |   
    |   |__ post/
    |   |   |
    |   |   |__ DeletePostAction.php
    |   |   |__ PromotePostAction.php
    |   |
    |   |__ users/
    |       |
    |       |__ MakeAvatarAction.php
    |
    |__ Services/
        |
        |__ PaymentService.php
        |__ KeycloackService.php

Our way: Naming

Robson Tenório — Thu, 19 Oct 2023 20:42:53 +0000

👉 Go to Summary

.
.
.

Naming is hard #1

WTF!?


$value = $this->getLoggedUser();

// ... after 50 lines of code you forget what `$value` is.

Nice!

$user = $this->getLoggedUser();

// Ok, got it. It is `$user`

.
.
.

Naming is hard #2

WTF!?

$user1 = User::where('name', 'Mary')->first();
$user2 = User::where('name', 'Joe')->first();

// 50 lines of code here ...

if ($user1->age > $user2->age) {

    // WTF are $user1 and $user2 ?
}

Nice!

$mary = User::where('name', 'Mary')->first();
$joe = User::where('name', 'Joe')->first();

... // 50 lines of code here

if ($mary->age > $joe->age) {

    // Ok, Mary is older than Joe
}

Our way: Constants

Robson Tenório — Thu, 19 Oct 2023 20:42:48 +0000

👉 Go to Summary

.
.
.

Magic number

WTF!?

class Costumer 
{
   public float $amount;

   public function something() 
   {
       // Ok, and WTF means 98.45 ?
       if ($this->amount > 98.45) {
          ...
       }

   }

}

Nice!

class Costumer 
{
   public float $amount;

   public const LIMIT = 98.45

   public function something() 
   {
       if ($this->amount > self::LIMIT) {
          ...
       }

   }

}

Nice!

// If LIMIT is used across codebase put it on `.env`
LIMIT = 98.45


public function something() 
{
    if ($this->amount > config("app.limit")) {
          ...
    }
}

Our way: Models, Migrations, Factories and Seeders.

Robson Tenório — Thu, 19 Oct 2023 20:42:24 +0000

👉 Go to Summary

.
.
.

Models

It should represent primarily ORM mapping.
It does not contain use cases, see actions.
It can have small helper methods, computed properties, or scopes to make it easy to query data.

class User extends Model{

    // Relationships
    function country(): BelongsTo { ... }

    // Helper method
    function isAdmin(): bool { ... }    

    // Query scope
    function scopeActive(Builder $query) { ... }

    // Computed attribute
    function getShortNameAttribute(): string { ... }
}

Migrations

Use normalized modeling.
Stick with convention xxxx_id for FKs.
Comment edge case columns.
Rememberindexes (performance).


Schema::create('users', function (Blueprint $table) {
   $table->id();
   $table->foreignId('country_id')->constrained();
   $table->string('name')->index();
   $table->string('cpf')->comment('Brazilian social number');

});

Seeders

Must contain all default values to bootstrap app first time.
Mostly it represents domain business value that should be mapped into model constants.
Remember seeders can run many times, so put a IF.

class PaymentTypesSeeder extends Seeder
{   
    public function run()
    {
        // Avoid run twice
        if (PaymentType::count()) {
            return;
        }

        // Insert initial data when app bootstraps
        PaymentType::insert([...])
    }
}

Factories

If it matters use a pre-seeded value.
If it does not matter call a factory.

class UserFactory extends Factory
{
   public function definition()
   {       
      return [            
            // It is a well known value, should be one from seeder 
            'prefered_payment_type_id' => PaymentType::inRandomOrder()->first(),
            // does not matter who is the parent user
            'parent_id' => User::factory(), 
            'name' => $this->faker->name(),
             // ....
        ];
    }

Our way: Let the code breath

Robson Tenório — Thu, 19 Oct 2023 20:42:08 +0000

👉 Go to Summary

.
.
.

Separate contexts

WTF!?

$post = Helper::sanitize($post);
$post = Helper::validation($post);
$post->notify($user);
$comments = Helper::crazy('hello');
$comments->gosh();

Nice!

$post = Helper::sanitize($post);
$post = Helper::validation($post);
$post->notify($user);

$comments = Helper::crazy('hello');
$comments->gosh();

.
.
.

Please, line breaks!

WTF!?

$hello = 'Mary';
if(...) {

}
foreach(...) {

}
if(...) {

}
$go = 'Paul';

Nice!

$hello = 'Mary'; 
// <---here
if (...) {

}
// <---here
foreach(...) {

}
// <---here
if(...) {

}
// <---here
$go = 'Paul';

.
.
.

Cleaner `IF`

WTF!?

if (User::where('name', 'Joe')->first() && 
   Product::where('name', 'xbox')->count() == 0) {
   throw new Exception("I'm sorry Joe. We don't have Xbox");
}

Nice!

$isJoe = User::where('name', 'Joe')->first();
$hasXbox = Product::where('name', 'xbox')->count() == 0;

if ($isJoe && ! $hasXbox) {
   throw new Exception("I'm sorry Joe. We don't have Xbox");
}

.
.
.

Early return

WTF!?

// You can buy a toy ONLY:
//  - If you have money 
//  - If it is weekend
//  - If it is NOT snowing

if($haveMoney) {
   if(! $isWeekend) {
       throw new Exception("It is not weekend!")
   } else {
      if($isSnowing) {
          throw new Exception("It is snowing!")
      } else {
          return 'Yes! I can buy!';
      }
   }
} else {
   throw new Exception("I don't have money!")
}

// Oh my... who did this!?

Nice!

// No need to read rules, I can read the code.

if (! $haveMoney) {
   throw new Exception("I don't have money!")   
}

if (! $isWeekend) {
    throw new Exception("It is not weekend!")
}

if ($isSnowing) {
    throw new Exception("It is snowing!")
} 

return 'Yes! I can buy!';

Our way: Laravel Code Guidelines

Robson Tenório — Thu, 19 Oct 2023 20:39:44 +0000

Summary

Livewire: Custom error page done right

Robson Tenório — Thu, 19 Oct 2023 12:42:11 +0000

When something goes wrong with Livewire you see a modal. As a developer you know you have to click outside to close it. Users don't!

In this example I have used components from MaryUI.

When you click a button that fires a 403 you see this modal.


public function delete()
{
   abort(403, 'You can`t do that ....');
}

When you navigate to a page does not exist you see this full page.

http://localhost:8019/noooooooo

1: Create an empty layout

File: views/components/layouts/empty.blade

<html>
<head>
    ...
</head>
<body class="[...] bg-base-200">
   {{ $slot }}
</body>
</html>

2 : Create a error page

File: views/errors/error.blade.php

This will override default Laravel error page. Notice we rely on $isLivewire to decide what to do with buttons.

If it is a modal show close button.
If it is not a modal show reload button.

Same page works for a modal or full page errors.

<x-layouts.empty>
    <div class="flex">
        <div class="mx-auto text-center">
            <img src="/error.png" width="300" class="mx-auto" />

            <div class="text-xl font-bold">Oops!</div>
            <div class="text-lg mx-auto max-w-4xl">{{ $message }}</div>

            <div class="flex mt-10">
                <div class="mx-auto grid md:grid-cols-2 gap-3">

                    <x-button :label="$isLivewire ? 'Close' : 'Reload'"
                              :icon="$isLivewire ? 'o-x-mark' : 'o-arrow-path'"
                              :onclick="$isLivewire
                                        ? 'window.parent.document.getElementById(\'livewire-error\').remove()'
                                        : 'window.location.reload()'"
                              class="btn-primary" />

                    <x-button label="Home"
                              icon="o-home"
                              onclick="window.parent.location.href = '/'"
                              class="btn-outline" />
                </div>
            </div>
        </div>
    </div>
</x-layouts.empty>

3: Exception Handler `render()`

File: app/Exceptions/Handler.php

This overrides Laravel error rendering. See more at https://laravel.com/docs/10.x/errors

When APP_ENV=local we display default Laravel error page. For any other value like production we display our custom error page describe above.

public function render($request, Throwable $e)
{
   // Uses native error page while developing
   if (app()->environment() == 'local') {
      return parent::render($request, $e);
   } 

   // Allow redirect if auth exception
   if ($e instanceof AuthenticationException) {
      return parent::render($request, $e);
   }


   $status = parent::render($request, $e)->getStatusCode();
   $isLivewire = $request->hasHeader('X-Livewire');

   // Call error page        
   return response()->view('errors.error', [
         'isLivewire' => $isLivewire,
         'message' => $e->getMessage()
      ], $status);
}

Better!


public function delete()
{
   abort(403, 'You can`t do that ....');
}

http://localhost:8019/noooooooo

Can we do it better? Yes!

You probably want to have a default message error based on status here instead to use raw error message.

[...]
403 - Go away!
404 - I can't find this page.
500 - Something is wrong our side.
[...]

[
   ...
   'message' => $e->getMessage()
]

Thank you!

Our way: Eloquent

Robson Tenório — Thu, 12 Oct 2023 03:05:02 +0000

👉 Go to Summary

.
.
.

One method per line

WTF!?

User::with('some')->whereHas('thing')->where(...)->orderBy(...)->get()

Nice!

User::query()
  ->with('some')
  ->whereHas('thing')
  ->where(...)
  ->orderBy(...)
  ->get()

Nice!

// No problem if it is short
User::where('age', 18)->first();

.
.
.

The `scopeXXXX()`

WTF!?

$activeUsers = User::where('active', true)->get()

// Same `active` logic
$activeAgedUsers =  User::query()
   ->where('active', true)
   ->where('age', '>=', 60)
   ->get();

// Same `active` and `age` logic
$activeAgedMaleUsers =  User::query()
   ->where('active', true)
   ->where('age', '>=', 60)
   ->where('gender', 'male')
   ->get();

Nice!

$activeUsers = User::active()->get();
$activeAndAgedUsers = User::active()->aged()->get();
$activeAgedMaleUsers = User::active()->aged()->male()->get();


public function scopeAged(Builder $query): Builder
{
   return $query->where('age', '>=', 60);
}

public function scopeMale(Builder $query): Builder
{
   return $query->where('gender', 'male');
}

public function scopeActive(Builder $query): Builder
{
   return $query->where('active', true);
}

.
.
.

The `count()`

WTF!?

// It loads ALL rows in memory, then count.
User::get()->count();

Nice!

// Count inside database
User::count();

.
.
.

The `lazy()`

WTF!?

// It loads ALL rows in memory, then starts loop
User::query()
   ->get()  // <-- here
   ->foreach(...);

Nice!

// Do it only if you really need to check ALL rows
// It loads chunked results and start loop immediately 
User::query()
   ->lazy()   // <-- here
   ->foreach(...);

Nice!

// 99% of time you need this
User::query()->paginate(50);

.
.
.

The `when()`

WTF!?

$results = User::where(...);

if($condition1){
   $results = $results->where('active', true);
}

if($condition2){
   $results = $results->where('age', '>=', 18);
}


return $results->get();

Nice!

return User::query()
      ->when($condition1, fn($query) => $query->where('active', true))
      ->when($condition2, fn($query) => $query->where('age', '>=' 18))
      ->get();

Forem: Robson Tenório

Livewire: The best of both worlds

One project

Two projects

One project (again)

Conclusion

Our way: Enums

Why not Enums?

Better approach: use Models

Benefits

Our way: Tests

The coverage test trap

Test what matters

Basics

Our way: Classes and Methods

Class attributes types

Constructor property promotion

Methods types

Fluent sintaxe

Encapsulate contexts

Our way: Actions vs Services

Actions

Services

Actions vs Services

Our way: Naming

Naming is hard #1

Naming is hard #2

Our way: Constants

Magic number

Our way: Models, Migrations, Factories and Seeders.

Models

Migrations

Seeders

Factories

Our way: Let the code breath

Separate contexts

Please, line breaks!

Cleaner IF

Early return

Our way: Laravel Code Guidelines

Summary

Livewire: Custom error page done right

1: Create an empty layout

2 : Create a error page

3: Exception Handler render()

Better!

Can we do it better? Yes!

Our way: Eloquent

One method per line

The scopeXXXX()

The count()

The lazy()

The when()

Cleaner `IF`

3: Exception Handler `render()`

The `scopeXXXX()`

The `count()`

The `lazy()`

The `when()`