A few good "best-practices" instilled by my Senior Developer for a more maintainable codebase

After a few code reviews, I learned a few good "rule of thumb" from my senior developer to make a codebase more maintainable - for us to be kind for Charlie The Future Dev.

## Use named routes!
When creating endpoints that don't follow the usual Laravel's Resource (i.e. 'create', 'index', 'show', etc.), it is a good idea to name the route. This will help during debugging process, when devs use `artisan route:list` to see the list of routes. It's more organised!

For example, an `CustomController` with `__invokable()` function for `/customs/` route.

If we only do this:
```php
// in routes/api.php
Route::get('/customs`, CustomController::class);
```
The output of `artisan route:list` will be:
``` 
/customs ... CustomController
```

If we add a named route,
```php
// in routes/api.php
Route::get('/customs', CustomController::class)->named('customs.user-customs.index');
```
The output of `artisan route:list` will be:
```
/customs ... customs.user-customs.index > CustomController
```

In this isolated example, it might not make a huge difference. However, if you are using different Controllers for the same _group_ of resource, it would make more sense for Charlie The Future Dev to understand how the different Controllers relate to one another.


```php
Route::resource('keyboards', KeyboardController::class);
Route::get('keyboards/{id}/keycap-options', KeyboardKeycapController::class)->named('keyboards.keycaps.index');
```
In the `artisan route:list`, the correlation between the Controllers can be seen in the route names implicitly.
```
/keyboards ..... keyboards.index > KeyboardController@index
/keyboards/{keyboard}/keycap-options ..... keyboards.keycaps.index > KeyboardKeycaps
```

## Use Eloquent if possible!
In Laravel, you can get data from the database in 2 possible ways:
1. Eloquent, the built-in ORM
2. Database queries
Because we have access to Eloquent, it will be more robust to access data using the Eloquent models compared to raw database queries. The primary reason is that Eloquent models contains _relationship data_, while database queries do not.

The existence of relationship data in Eloquent models allow devs to access relational data in a more error prone way, especially compared to a database query.

For example, let's say we have a `Keyboard` model, with a many-to-many relationship with `KeycapOptions`

```php
// Eloquent way
$keyboard = Keyboard::find(1);
$keycap_options = $keyboard->keycap_options;

// vs. DB queries
$keyboard_options = 
	DB::table('keyboard_keycap_options')
		->where('keyboard_id', '=', 1)
		->get();
```
What if you made a migration change: field name change or table name change? Instead of updating it in one place (the model), you have to go through every database query referencing the changed migration.

Of course, this is a very contrived scenario. However, the general rule of thumb still stands - use Eloquent (i.e. the model instance itself) to retrieve data where possible.

This does not mean that database queries are useless! It is still useful if you want to do your own RAW SQL statements, or complex database-specific queries where Eloquent does not support it.

Laravel Best Practices

I learned how to use keyBy collection method, in my case to not use a nested loop.

The collection method `keyBy` keys a collection by a given key. Copied straight from the docs:
```php
$collection = collect([
    ['product_id' => 'prod-100', 'name' => 'Desk'],
    ['product_id' => 'prod-200', 'name' => 'Chair'],
]);
$keyed = $collection->keyBy('product_id');
$keyed->all();

/*
    [
        'prod-100' => ['product_id' => 'prod-100', 'name' => 'Desk'],
        'prod-200' => ['product_id' => 'prod-200', 'name' => 'Chair'],
    ]
*/
```

I found this very useful if you have to search for a given value in a nested associative array.
```php
// this function returns a collection of users with its corresponding greeting
function user_greeting()
    {
        // Collection of user info
        $users = collect([
            [
                'id' => 1,
                'name' => 'Shawn',
            ],
            [
                'id' => 2,
                'name' => 'Sam',
            ]
        ]);

        // Collection of greetings
        $greetings = collect([
            [
                'greeting' => 'hello',
                'user_id' => 1,
            ],
            [
                'greeting' => 'hi',
                'user_id' => 2,
            ]
        ]);

        $keyed_greeting = $greetings->keyBy('user_id');

        // because $greetings is now keyed, we can have an efficient lookup
        // only 1 loop, O(n)
        $users_greetings = $users->map(function ($user) use ($keyed_greeting) {
            $user['greeting'] = $keyed_greeting->get($user['id'])['greeting'];
            return $user;
        });

        return $users_greetings;
    }
		
		
// it's better than doing this:
	$user_greetings = [];

	// Nested loop, O(n^2)
	foreach ($users as $user) {
			// Loop through the greetings collection to find the corresponding greeting
			foreach ($greetings as $greeting) {
					if ($greeting['user_id'] === $user['id']) {
							// If the user_id matches, assign the greeting to the user
							$user['greeting'] = $greeting['greeting'];
							break;  // Exit the inner loop as we've found the corresponding greeting
					}
			}

			$user_greetings[] = $user;
	}
	return $user_greetings
```

Using keyBy Collection Method in Laravel

I learned how to effectively use the Query Builder directly from a Model instance in Laravel.

When you have different database queries based on different query parameters in a request, you can split out the query into different parts, instead of using multiple different queries for different outcomes.

For example, let's say you want to have one endpoint, `/model-a` with optional query parameters `model_b_id: numeric`, and `sort_by: 'asc' | 'desc'`

`/model-a` returns a list of the User's related `modelA`\
`/model-a/?model_b_id=1` returns a list of the User's related `modelA` that is related to `modelB` with id of 1.\
`/model-a/?sort_by='asc'` returns a list of the User's related `modelA' in ascending order

Using Query Builder, you can (in my opinion, quite elegantly) split the query into multiple parts, and build the query according to the incoming requests' parameters.

```php
/**
* instead of using different queries in different conditions, can just use 
* one query for multiple use cases
*
* Relationships:
* User hasMany ModelA
* ModelA hasMany ModelB
*/

// in SortBy.php
enum SortBy: string
{
    case Ascending = 'asc';
    case Descending = 'desc';
}

// in MyController.php
// return ModelA of a user, based on ModelB's id
public function __invoke(Request $request)
{
// Validate the model_b_id and sortBy
$validated = $request->validate([
    'model_b_id' => ['sometimes', 'numeric', 'exists:model_b_table_name,id'],
    'sort_by' => [Rule::enum(SortBy::class), 'nullable'],
]);

/**  @var User */
$user = $request->user();

// Get modelA and sortBy; default to null
$model_b_id = Arr::get($validated, 'model_b_id');
$sort_by = Arr::get($validated, 'sort_by');

// Initialize Query Builder
$query = $user->modelA();

/**
 * if $model_b is NOT NULL,
 * return user's modelA filtered by model_b_id from the query param.
 */
if ($model_b) {
	$query->where('model_b_id', $model_b_id);
}

// sort in DB query
$model_a_collection = $query->orderBy('updated_at', $sort_by ?? 'desc')->get();

return ModelAResource::collection($model_a_collection);
}
```

Notice how I can just add `$query->where(...)` in a separate condition, rather than building a whole new query when `$model_b` exists (i.e. when `model_b_id` is passed in the request parameter)!

Using the Query Builder from a Model in Laravel

Authorization with Policies and Gate in Laravel.

When authorizing access to different users, I found out that instead of doing this:
```php
// in Controller.php
public function items(Request $request, MyModel $model)
{
    $request_user_id = $request->user()->id;
    $model_user_id = $model->user_id;

    abort_if(
        $model_user_id != $request_user_id,
        403,
        "Forbidden."
    );

    return ModelResource::collection($model->items);
}
```
I found out that you can create Policies by using `artisan make:policy`, and it'll look like this:
```php
// App/Policies/ModelPolicy.php
use Illuminate\Auth\Access\Response;
// ..snip
public function view(User $user, Model $model): Response
{
    return $user->id === $model->user_id
        ? Response::allow()
        : Response::deny('You are forbidden to access this resource.');
}
```
In the `Controller.php`, it will be implemented like this:
```php
// in Controller.php
public function show(Model $model)
{
    // Uses ModelPolicy, the 'view' function
    Gate::authorize('view', $model);

    return new ModelResource($model);
}
```

Today I Learned

Laravel Best Practices

Using keyBy Collection Method in Laravel

Using the Query Builder from a Model in Laravel

Gates and Policies (Laravel)