I used to use a fantastic Chrome extension called Sprout for entering transactions, but unfortunately the developer took the extension off the Chrome store and stopped development. I wanted something that could be equally as fast and easy to use.

Over this blog series, we'll utilize the PHP Laravel framework and its built-in tools to build a robust CLI application and interface with YNAB's API.

The CLI functionality will not replace the excellent web UI but only introduce faster ways to alleviate everyday tasks to go about our day. It's a perfect fit since I'm usually in my terminal during the day.

Before we begin, if you aren't a YNAB user, please sign up. Using my referral link will give you a 34 day trial and if you decide to purchase a subscription, YNAB will give us both a free month!

Set up Laravel

To get started, install Laravel from the docs. I usually use the Laravel installer, but do whatever works best for you. At the time of writing, this will install a new Laravel 11 application.

laravel new ynab
cd ynab

Because we want an easy to use interface within the CLI, we'll also want to install Laravel Prompts.

composer require laravel/prompts

Next, we'll want to add config values for our YNAB API key and the default budget ID that we'll want to utilize. Right now, I'm only setting this up as a single budget, but in the future we could make this more configurable, or you can do this on your own in your own application.

Within .env and .env.example, add

YNAB_TOKEN=
YNAB_BUDGET_ID=

Within config/services.php, add

    'ynab' => [
        'token' => env('YNAB_TOKEN'),
        'budget_id' => env('YNAB_BUDGET_ID'),
    ],

To get a YNAB API key, go into your Account Settings, scroll toward the bottom and within the Developer Settings click the Developer Settings button. On the next page, under Personal Access Tokens, click the New Token button. This will reveal your API token that you can paste into your .env file.

The budget id is the UUID in the URL when viewing your budget in the YNAB web UI, so you can copy/paste if from there, or get it from the API (/budgets).

Create Transaction Command

Next, we'll want to set up our initial artisan command, so we'll run php artisan make:command CreateTransaction, which will create app/Console/Commands/CreateTransaction.php. Then, we'll stub out the initial command class.

class CreateTransaction extends Command
{
    protected $signature = 'ynab:transaction';
    protected $description = 'Creates a new transaction in YNAB';

    public function handle(): int
    {
        return self::SUCCESS;
    }

Before we get too far, let's set up a shared trait for the HTTP client to be shared across all commands, since we'll be creating more commands in the next blog posts. Create app/Console/Commands/Concerns/Ynab.php with the following code

<?php
declare(strict_types=1);

namespace App\Console\Commands\Concerns;

use Illuminate\Http\Client\PendingRequest;
use Illuminate\Support\Facades\Http;

trait Ynab
{
    protected function getClient(): PendingRequest
    {
        return Http::baseUrl('https://api.ynab.com/v1/')
            ->acceptJson()
            ->asJson()
            ->throw()
            ->withToken(config('services.ynab.token'));
    }
}

This helper method will allow us to remove the boilerplate of setting up the YNAB client and set up JSON handling, throw an exception if there's an API error, and use the token from the config file for authentication.

Then, we'll include that in the transaction command class

class CreateTransaction extends Command
{
+    use Concerns\Ynab;
+
    protected $signature = 'ynab:transaction';
    protected $description = 'Creates a new transaction in YNAB';

Similar to the Sprout UI, we'll want to build a CLI to handle:

• Amount

• Account

• Payee

• Category

• Optional memo

• Optional flag

• Optional cleared/uncleared

For now, we'll skip date (we'll assume today's date), approval (default to true), split transactions, and other options found in the Sprout and YNAB UIs. For reference, here is the Sprout UI.

Gathering Budget Data

Before we start building our CLI UI, we'll need to get initial budget data from YNAB. You can find the API docs here. For now, we'll want to gather

• Accounts

• Payees

• Categories

So, we'll stub those out in our command

class CreateTransaction extends Command
{
    use Concerns\Ynab;

    protected $signature = 'ynab:transaction';
    protected $description = 'Creates a new transaction in YNAB';

    public function handle(): int
    {
+        $accounts = $this->getAccounts();
+        $payees = $this->getPayees();
+        $categories = $this->getCategories();
+
        return self::SUCCESS;
    }

Getting Budget Accounts

    public function getAccounts(): Collection
    {
        $response = $this->getClient()->get('budgets/' . config('services.ynab.budget_id') . '/accounts');

        return collect($response->json('data.accounts'))
            ->filter(fn($account) => $account['on_budget'] && !$account['closed'])
            ->mapWithKeys(fn($account) => [$account['id'] => $account['name']]);
    }

In this step, we're

1. Getting the raw response from the /accounts endpoint from the API

2. Grabbing the data from the response under data.accounts

3. Filtering for only accounts "on budget" and not closed. On budget means that the money is used for specific budgeting purposes. Alternatively, there are "tracking" accounts that don't impact your budget positively or negatively.

4. Creating a new collection of account IDs matching their name

Getting Budget Payees

    public function getPayees(): Collection
    {
        $response = $this->getClient()->get('budgets/' . config('services.ynab.budget_id') . '/payees');

        return collect($response->json('data.payees'))
            ->reject(fn($payee) => $payee['deleted'])
            ->mapWithKeys(fn($payee) => [$payee['id'] => $payee['name']]);
    }

In this step, we're

1. Getting the raw response from the /payees endpoint from the API

2. Grabbing the data from the response under data.payees

3. Removing any deleted payees

4. Creating a new collection of payee IDs matching their name

Getting Budget Categories

This step is a little more involved because the /categories endpoint has top-level Category Groups, then includes the categories data within each group. You can see the schema for CategoryGroupWithCategories here.

    public function getCategories(): Collection
    {
        $response = $this->getClient()->get('budgets/' . config('services.ynab.budget_id') . '/categories');

        return collect($response->json('data.category_groups'))
            ->reject(fn($categoryGroup) => $categoryGroup['hidden'] || $categoryGroup['deleted'])
            ->pluck('categories')
            ->flatten(1)
            ->reject(fn($category) => $category['hidden'] || $category['deleted'] || $category['category_group_name'] === 'Credit Card Payments' || $category['category_group_name'] === 'Internal Master Category')
            ->mapWithKeys(fn($category) => [$category['id'] => $category['category_group_name'].': '.$category['name']]);
    }

In this step, we're

1. Getting the raw response from the /categories endpoint from the API

2. Grabbing the data from the response under data.category_groups

3. Removing hidden and deleted category groups

4. Grabbing the categories array from each group

5. Flattening the collection so all of the categories are in the same root of the collection

6. Removing any categories that are hidden, deleted, or match specific YNAB-generate categories we don't need

7. Creating a new collection of category IDs matching the category group name with the category name

Whew, we did it! Now, we'll move on to the Laravel Prompts UI.

Leveraging Laravel Prompts for the CLI UI

Prompts has numerous options for CLI inputs. These can either be one-off or chained together into a form. A form enables us to have multiple questions and inputs while collecting the responses to be used later. Since we'll have a number of questions to ask, we'll be using a form.

        $responses = form()
            ->text('Amount', required: true, name: 'amount')
            ->select('Account', options: $accounts, required: true, name: 'account')
            ->search(
                label: 'Payee',
                options: fn (string $value) => strlen($value) > 0
                    ? $payees->filter(fn ($payee) => Str::contains($payee, $value, true))->all()
                    : [],
                name: 'payee'
            )
            ->search(
                label: 'Category',
                options: fn (string $value) => strlen($value) > 0
                    ? $categories->filter(fn ($category) => Str::contains($category, $value, true))->all()
                    : [],
                name: 'category'
            )
            ->text('Memo (optional)', name: 'memo')
            ->select('Flag color (optional)', options: ['none', 'red', 'orange', 'yellow', 'green', 'blue', 'purple'], name: 'flag_color')
            ->select('Cleared', options: ['cleared', 'uncleared'], default: 'uncleared', name: 'cleared')
            ->submit();

There's a lot to unpack here, but it should be straight forward

1. We'll ask for the amount of the transaction - either positive (income) or negative (expense)

2. Select the account from a select prompt loaded with our accounts from the API

3. A search box for the payee loaded from the API. As new characters are added, the search suggest auto-updates and allows you to arrow up/down to select the payee. The options function searches and returns the values the match the input given.

4. Similar to the payees, the categories work the same way with a search suggest

5. Memo is a simple text field and also optional

6. Flag color is also optional using a select, like accounts. YNAB allows you to use their default flags, or change them in the UI. I only use these occasionally.

7. Cleared or uncleared transaction using another select. If I already know the transaction has cleared the bank/card, then I'll change to cleared but otherwise most transactions are new and haven't hit the account yet, so we'll default to uncleared

8. Finally, submit the responses

Creating the new transaction via the API

The Laravel Prompts form will return an array of $responses that will contain the key/value from what's provided in each input's name. We'll use the /transactions endpoint to combine our data and use some sensible defaults for other transaction-related data points.

        $response = $this->getClient()->post('budgets/' . config('services.ynab.budget_id') . '/transactions', [
            'transaction' => [
                'account_id' => $responses['account'],
                'payee_id' => $responses['payee'],
                'category_id' => $responses['category'],
                'amount' => $responses['amount'] * 1000,
                'memo' => $responses['memo'],
                'flag_color' => $responses['flag_color'] === 'none' ? null : $responses['flag_color'],
                'cleared' => $responses['cleared'],
                'date' => now()->toDateString(),
                'approved' => true,
            ],
        ]);

1. The account will be the account's uuid from YNAB

2. The payee will be the payee's uuid

3. The category will be the category's uuid

4. The amount (positive or negative) needs to be converted to what YNAB calls milliunits or 3 decimal places, so we'll multiply our amount by 1,000 (docs)

5. Optional memo text

6. Optional flag color, or converting none to null in case a color isn't specified

7. Cleared value

8. Current date - I usually add transactions as they happen, so we'll default to the current date. We might make this configurable in the future.

9. Approved defaulted to true - YNAB will highlight any new transactions via their auto-import process which you can either approve or delete. However, for the CLI's purposes, I'm entering the transaction manually, I'm approving at the same time.

Handling API responses

At this point, I'm not too worried about responses and everything has been working smoothly so far. We'll expand on this in the future, but again, we'll keep things simple right now.

        if ($response->successful()) {
            $this->info('Expense created successfully');
        } else {
            $this->error('Failed to create expense - ' . $response->json('error.detail'));
        }

        return self::SUCCESS;

Wrapping Up

I hope you enjoyed this quick journey through setting up a fresh, new, Laravel application with Prompts and the YNAB API. As stated earlier, I'll be adding more blog posts to this series as I work through other command and refactorings along the way. I'm sure you can already see some areas that could use improvement. Further, the YNAB API offers some interesting options like Delta Requests, Rate Limiting, and better error handling that we can explore later as well.

Live Demo

Check out the repo on GitHub

• laravel-ynab-cli

• PR #1 for the CreateTransaction command

Listen to the podcast episode

Subscribe

Please subscribe to my newsletter, RSS feed, podcast, or the GH repo to follow along for more content!

Join the YNAB Family

Signing up using my referral link will give you a 34 day trial and if you decide to purchase a subscription, YNAB will give us both a free month!

Let's look at the typical structure with minimal application code and tests.

.
├── app/
│   ├── Http/
│   │   └── Controllers/
│   │       └── MyUserController.php
│   └── Models/
│       └── User.php
└── tests/
    ├── TestCase.php
    ├── Features/
    │   └── Http/
    │       └── Controllers/
    │           └── MyUserControllerTest.php
    └── Unit/
        └── Models/
            └── UserTest.php

This issue gets exacerbated in larger applications with additional sub-directories. For example,

.
├── app/
│   ├── Http/
│   │   └── Controllers/
│   │       └── Admin/
│   │           └── Users/
│   │               └── MyUserController.php
│   └── Models/
│       └── User.php
└── tests/
    ├── TestCase.php
    ├── Features/
    │   └── Http/
    │       └── Controllers/
    │           └── Admin/
    │               └── Users/
    │                   └── MyUserControllerTest.php
    └── Unit/
        └── Models/
            └── UserTest.php

This structure further breaks down if you've chosen to break up your application within modules or domains but don't include the tests within the directories. The application and test structures could easily be five or more directories deep.

Discoverability of application files with their test partners is challenging, and it is unclear if a given application file has a partnering test.

The solution

Colocating tests is an ideal structure. The test files are elevated to the same "status" and layer as application files. This makes it very easy to notice, at a glance, whether a file has a partnering test. Further, this simplifies pull requests for reviewers since the two files are next to each other.

The structure of our application now looks like this.

.
├── app/
│   ├── Http/
│   │   └── Controllers/
│   │       ├── MyUserController.php
│   │       └── MyUserControllerTest.php
│   └── Models/
│       ├── User.php
│       └── UserTest.php
└── tests/
    └── TestCase.php

or

.
├── app/
│   ├── Http/
│   │   └── Controllers/
│   │       └── Admin/
│   │           └── Users/
│   │               ├── MyUserController.php
│   │               └── MyUserControllerTest.php
│   └── Models/
│       ├── User.php
│       └── UserTest.php
└── tests/
    └── TestCase.php

Now imagine if this app contains hundreds of different directories and files. Can you easily see if MyUserController has a test? Yes! How about the User model? Yes again!

The mechanics

Unfortunately, we cannot just move our tests into this new structure. We'll have to make some small adjustments, but they are small and straightforward.

composer.json

Add autoload.exclude-from-classmap

{
    "autoload": {
        "psr-4": {
            "App\\": "app/",
            "Database\\Factories\\": "database/factories/",
            "Database\\Seeders\\": "database/seeders/"
-        }
+        },
+        "exclude-from-classmap": [
+            "app/**/*Test"
+        ]
    }
}

phpunit.xml

Add or adjust source and testsuites.

    <source>  
        <include>  
            <directory suffix=".php">./app</directory>
        </include>  
+        <exclude>  
+            <directory suffix="Test.php">./app</directory>
+        </exclude>  
    </source>
    <testsuites>
-        <testsuite name="Unit">
-            <directory>tests/Unit</directory>
-        </testsuite>
-        <testsuite name="Feature">
-            <directory>tests/Feature</directory>
-        </testsuite>
+        <testsuite name="Application Test Suite">
+            <directory>./app</directory>
+        </testsuite>
    </testsuites>

tests/Pest.php

Ensure all tests have the TestCase and other uses classes available.

uses(  
    Tests\TestCase::class,  
    // Illuminate\Foundation\Testing\RefreshDatabase::class,  
-)->in('Feature');
+)->in('../');

app/Console/Kernel.php (< v11)

Add or adjust the load() method.

protected function load($paths)
{
    $paths = Arr::wrap($paths);
    $namespace = $this->app->getNamespace();

    foreach ((new Finder)->in($paths)->files() as $command) {
        $command = $namespace.str_replace(
            ['/', '.php'],
            ['\\', ''],
            Str::after($command->getPathname(), realpath(app_path()).DIRECTORY_SEPARATOR)
        );

+        $isTestClass = Str::endsWith($command, 'Test');

        if (
+            !$isTestClass &&
            is_subclass_of($command, Command::class) &&
            !(new ReflectionClass($command))->isAbstract()
        ) {
            Artisan::starting(function ($artisan) use ($command) {
                $artisan->resolve($command);
            });
        }
    }
}

External Tooling

If your application uses a tool like Code Climate, you might need to make additional config changes. For example, within the .codeclimate.yml, add **/*Test.php within the exclude_patterns.

exclude_patterns:
+  - '**/*Test.php'

Quality of life

If you like the idea of colocating tests, but don't want the additional mess of looking at test files all the time you can enable File Nesting in PHPStorm, and other JetBrains IDEs. Once you add the .php -> Test.php mapping your files will be collapsed.

Thanks to Enzo Innocenzi for bringing that to my attention.

If you use VSCode, please check out Liam Hammett's extension.

Wrapping up

Even though colocating your tests within the app/ directory in your Laravel application is currently atypical, I highly recommend you try it out. By colocating tests alongside application code, the direct mapping of the two will become stronger, minimizing the cognitive load in your app. You will also have a simplified structure and ease of refactoring if you happen to move your modules or domains within your app or to a new one.

Please comment below or reach out via X/Twitter about what you think about colocating tests and if you've implemented it within your application.

Listen to the Podcast

The Laravel docs show this as an example

Queue::assertPushed(function (ShipOrder $job) use ($order) {
    return $job->order->id === $order->id;
});

Straightforward, right? We're trying to ensure that the ShipOrder job was pushed to the queue and the order IDs matched.

What happens when the IDs do not match, or something else happens? We get the following error

Failed asserting that false is true.

Which is not that helpful. We know that the job wasn't pushed, but was it an error with the IDs matching, or something else? This issue gets exacerbated when you have multiple conditions that need to pass.

Queue::assertPushed(function (ShipOrder $job) use ($order) {
    return $job->order->id === $order->id
        && $job->order->second === $order->second
        && $job->order->third === $order->third
        && $job->order->fourth === $order->fourth;
});

Now, if any of those conditions fail, then we'll still get the same PHPUnit error message.

Failed asserting that false is true.

There is no way to know which condition failed easily. You can remove one condition at a time, but that's a time-consuming process. There's a better way.

Instead of using chained conditions, we can use assertions for each of the comparisons. Then we can manually return true if all of the conditions are true.

Queue::assertPushed(function (ShipOrder $job) use ($order) {
    $this->assertSame($job->order->id, $order->id);
    $this->assertSame($job->order->second, $order->second);
    $this->assertSame($job->order->third, $order->third);
    $this->assertSame($job->order->fourth, $order->fourth);

    return true;
});

Now, if any of these assertions fail, PHPUnit will be able to narrow in on the exact line number that failed - making it quicker to debug and getting you on your way.

Failed asserting that X is identical to Y

# ---

Failed asserting that 456 is identical to 123.
 /tests/PathToFileTest.php:62

In conclusion, by using assertions for each comparison, you can quickly pinpoint and resolve issues in your code. Leveraging Laravel mocks effectively can significantly improve your productivity as a developer.

Don't forget to share this article with your fellow developers to help them optimize their Laravel testing experience!

Tips, Tricks, and Good Practices

with

Laravel's Eloquent

Presented by Chris Gmyr

What is Laravel?

Laravel is a modern PHP framework that helps you create applications using simple, expressive syntax as well as offers powerful features like an ORM, routing, queues, events, notifications, simple authentication...

...and so much more!

What is Eloquent?

The Eloquent ORM included with Laravel provides a beautiful, simple ActiveRecord implementation for working with your database. Each database table has a corresponding "Model" which is used to interact with that table. Models allow you to query for data in your tables, as well as insert new records into the table.

https://laravel.com/docs/5.6/eloquent

The Basics

A Model

class Post extends Model
{
    // look Ma, no code!
}

- id
- title
- created_at
- updated_at

$post = Post::find(1);

Artisan Goodies

php artisan make:model Product

Artisan Goodies

php artisan make:model Product -mcr

-m will create a migration file -c will create a controller -r will indicate that controller should be resourceful

Cruddy

Creating

$user = new User();
$user->first_name = 'Chris';
$user->email = 'cmgmyr@gmail.com';
$user->save();

Creating

$user = User::create([
    'first_name' => 'Chris',
    'email' => 'cmgmyr@gmail.com',
]);

Note: $fillable/$guarded properties

Updating

$user = User::find(1);
$user->email = 'me@chrisgmyr.com';
$user->save();

Updating

$user = User::find(1);
$user->update([
    'email' => 'me@chrisgmyr.com',
]);

Note: $fillable/$guarded properties

Updating

$user = User::find(1);
$user->fill([
    'email' => 'me@chrisgmyr.com',
]);
$user->save();

Note: $fillable/$guarded properties

Deleting

$user = User::find(1);
$user->delete();

Deleting

User::destroy(1);
User::destroy([1, 2, 3]);
User::destroy(1, 2, 3);

"or" helper methods

User::findOrFail(1);

$user->saveOrFail(); // same as save(), but uses transaction

User::firstOrCreate([ /* attributes */]);

User::updateOrInsert([/* attributes to search */], [/* attributes to update */]);

Querying

Querying

$users = User::get(); // User::all()
$user  = User::where('id', 1)->first();
$user  = User::find(1);
$user  = User::findOrFail(1);
$users = User::find([1, 2, 3]);
$users = User::whereIn('id', [1, 2, 3])->get();

$users = User::where('is_admin', true)
    ->where('id', '!=', Auth::id())
    ->take(10)
    ->orderBy('last_name', 'ASC')
    ->get();

Chunking

User::chunk(50, function ($users) {
    foreach ($users as $user) {
        //
    }
});

Collections

For Eloquent methods like all() and get() which retrieve multiple results, an instance of Illuminate\Database\Eloquent\Collection will be returned.

$admins = $users->filter(function ($user) {
    return $user->is_admin;
});

Raw query methods

Product::whereRaw('price > IF(state = "NC", ?, 100)', [200])
    ->get();

Post::groupBy('category_id')
    ->havingRaw('COUNT(*) > 1')
    ->get();

Customer::where('created_at', '>', '2016-01-01')
    ->orderByRaw('(updated_at - created_at) desc')
    ->get();

Relationships

Relationships

hasOne() // User has one Address
belongsTo() // Address belongs to User
hasMany() // Post has many Comment
belongsToMany() // Role belongs to many User
hasManyThrough() // Country has many Post through User

// Use single table
morphTo() // Comment can be on Post, Video, Album
morphMany() // Post has many Comment

// Use pivot table
morphToMany() // Post has many Tag
morphedByMany() // Tag has many Post

Relationships

class Video extends Model
{
    public function comments()
    {
        return $this->hasMany(Comment::class);
    }
}

$video = Video::find(1);
foreach ($video->comments as $comment) {
    // $comment->body
}

Relationships

class Video extends Model
{
    public function comments()
    {
        return $this->hasMany(Comment::class);
    }
}

$video = Video::find(1);
foreach ($video->comments()->where('approved', true)->get() as $comment) {
    // $comment->body
}

Default conditions and ordering

class Video extends Model
{
    public function comments()
    {
        return $this->hasMany(Comment::class)
        ->where('approved', true)
        ->latest();
    }
}

Default conditions and ordering

class Video extends Model
{
    public function comments()
    {
        return $this->hasMany(Comment::class);
    }

    public function publicComments()
    {
        return $this->comments()
        ->where('approved', true)
        ->latest();
    }
}

Default Models

Default models can be used with belongsTo(), hasOne(), and morphOne() relationships.

Default Models

{{ $post->author->name }} // error if author not found

class Post extends Model
{
    public function author()
    {
        return $this->belongsTo(User::class);
    }
}

Default Models

{{ $post->author->name ?? '' }} // meh

class Post extends Model
{
    public function author()
    {
        return $this->belongsTo(User::class);
    }
}

Default Models

{{ $post->author->name }} // better!

class Post extends Model
{
    public function author()
    {
        return $this->belongsTo(User::class)->withDefault();
    }
}

Default Models

class Post extends Model
{
    public function author()
    {
        return $this->belongsTo(User::class)->withDefault([
            'name' => 'Guest Author',
        ]);
    }
}

Events

The retrieved event will fire when an existing model is retrieved from the database. When a new model is saved for the first time, the creating and created events will fire. If a model already existed in the database and the save() method is called, the updating / updated events will fire. However, in both cases, the saving / saved events will fire.

https://laravel.com/docs/5.6/eloquent#events

Events

class User extends Model
{
    protected $dispatchesEvents = [
        'saved' => UserSaved::class,
        'deleted' => UserDeleted::class,
    ];
}

Observers

php artisan make:observer UserObserver --model=User

class ModelObserverServiceProvider extends ServiceProvider
{
    public function boot()
    {
        User::observe(UserObserver::class);
    }
}

Observers

class UserObserver
{
    public function created(User $user)
    {
    }

    public function updated(User $user)
    {
    }

    public function deleted(User $user)
    {
    }
}

boot() method

class Post extends Model
{
    public static function boot()
    {
        parent::boot();

        self::creating(function ($model) {
            $model->uuid = (string) Uuid::generate();
        });
    }
}

Bootable Trait

class Post extends Model
{
    use HasUuid;
}

trait HasUuid
{
    public static function bootHasUuid()
    {
        self::creating(function ($model) {
            $model->uuid = (string) Uuid::generate();
        });
    }

    // more uuid related methods
}

Helper Methods

Increments and Decrements

$post = Post::find(1);
$post->stars++;
$post->save();

$post->stars--;
$post->save();

Increments and Decrements

$post = Post::find(1);
$post->increment('stars'); // add 1
$post->increment('stars', 15); // add 15

$post->decrement('stars'); // subtract 1
$post->decrement('stars', 15); // subtract 15

Aggregates

$count = Product::where('active', 1)->count();
$min   = Product::where('active', 1)->min('price');
$max   = Product::where('active', 1)->max('price');
$avg   = Product::where('active', 1)->avg('price');
$sum   = Product::where('active', 1)->sum('price');

Check if Records Exist

Instead of count(), you could use...

User::where('username', 'cmgmyr')->exists();

User::where('username', 'cmgmyr')->doesntExist();

Model State

$model->isDirty($attributes = null);
$model->isClean($attributes = null);
$model->wasChanged($attributes = null);
$model->hasChanges($changes, $attributes = null);
$model->getDirty();
$model->getChanges();

//Indicates if the model exists.
$model->exists;

//Indicates if the model was inserted during the current request lifecycle.
$model->wasRecentlyCreated;

"Magic" where()

$users = User::where('approved', 1)->get();
$users = User::whereApproved(1)->get();

$user = User::where('username', 'cmgmyr')->get();
$user = User::whereUsername('cmgmyr')->get();

$admins = User::where('is_admin', true)->get();
$admins = User::whereIsAdmin(true)->get();

Super "Magic" where()

User::whereTypeAndStatus('admin', 'active')->get();
User::whereTypeOrStatus('admin', 'active')->get();

https://twitter.com/themsaid/status/1029731544942952448

Dates

User::whereDate('created_at', date('Y-m-d'));
User::whereDay('created_at', date('d'));
User::whereMonth('created_at', date('m'));
User::whereYear('created_at', date('Y'));

when() to eliminate conditionals

$query = Author::query();

if (request('filter_by') == 'likes') {
    $query->where('likes', '>', request('likes_amount', 0));
}

if (request('filter_by') == 'date') {
    $query->orderBy('created_at', request('ordering_rule', 'desc'));
}

when() to eliminate conditionals

$query = Author::query();

$query->when(request('filter_by') == 'likes', function ($q) {
    return $q->where('likes', '>', request('likes_amount', 0));
});

$query->when(request('filter_by') == 'date', function ($q) {
    return $q->orderBy('created_at', request('ordering_rule', 'desc'));
});

replicate() a Model

$invoice = Invoice::find(1);
$newInvoice = $invoice->replicate();
$newInvoice->save();

Pagination

// 1, 2, 3, 4, 5...
$users = User::where('active', true)->paginate(15);

// Previous/Next
$users = User::where('active', true)->simplePaginate(15);

// In Blade
{{ $users->links() }}

Pagination to Json

{
   "total": 50,
   "per_page": 15,
   "current_page": 1,
   "last_page": 4,
   "first_page_url": "https://my.app?page=1",
   "last_page_url": "https://my.app?page=4",
   "next_page_url": "https://my.app?page=2",
   "prev_page_url": null,
   "path": "https://my.app",
   "from": 1,
   "to": 15,
   "data":[
        {
            // Result Object
        },
        {
            // Result Object
        }
   ]
}

Model Properties

protected $table = 'users';
protected $fillable = ['first_name', 'email', 'password']; // create()/update()
protected $dates = ['created', 'deleted_at']; // Carbon
protected $appends = ['full_name', 'company']; // additional JSON values
protected $casts = ['is_admin' => 'boolean', 'options' => 'array'];

protected $primaryKey = 'uuid';
public $incrementing = false;
protected $perPage = 25;
const CREATED_AT = 'created';
const UPDATED_AT = 'updated';
public $timestamps = false;

...and more!

Overriding updated_at

$product = Product::find(1);
$product->updated_at = '2020-01-01 10:00:00';
$product->save(['timestamps' => false]);

Primary Key Methods

$video = Video::find(1);
$video->getKeyName(); // 'id'
$video->getKeyType(); // 'int'
$video->getKey(); // 1

Accessors/Mutators

class User extends Model
{
    public function setFirstNameAttribute($value)
    {
        $this->attributes['first_name'] = strtolower($value);
    }
    public function setLastNameAttribute($value)
    {
        $this->attributes['last_name'] = strtolower($value);
    }
}

Accessors/Mutators

class User extends Model
{
    public function getFirstNameAttribute($value)
    {
        return ucfirst($value);
    }
    public function getLastNameAttribute($value)
    {
        return ucfirst($value);
    }
    public function getEmailAttribute($value)
    {
        return new Email($value);
    }
    public function getFullNameAttribute()
    {
        return "{$this->first_name} {$this->last_name}";
    }
}

Accessors/Mutators

$user = User::create([
    'first_name' => 'Chris', // chris
    'last_name' => 'Gmyr', // gmyr
    'email' => 'cmgmyr@gmail.com',
]);

$user->first_name; // Chris
$user->last_name; // Gmyr
$user->email; // instance of Email
$user->full_name; // 'Chris Gmyr'

To Array/Json

$user = User::find(1);
return $user->toArray();
return $user->toJson();

You can also return $user from a controller method and it will automatically return JSON.

Appending Values to JSON

class User extends Model
{
    protected $appends = ['full_name']; // adds to toArray()

    public function getFullNameAttribute()
    {
        return "{$this->first_name} {$this->last_name}";
    }
}

// or...
return $user->append('full_name')->toArray();
return $user->setAppends(['full_name'])->toArray();

Local Scopes

$posts = Post::whereNotNull('published_at')
    ->where('published_at', '<=', Carbon::now())
    ->latest('published_at')
    ->get();

Local Scopes

class Post extends Model
{
    public function scopePublished($query)
    {
        return $query->whereNotNull('published_at')
            ->where('published_at', '<=', Carbon::now())
            ->latest('published_at');
    }
}

Local Scopes

$posts = Post::published()->get();

Single Table Inheritance

Single Table Inheritance

$admins = User::where('is_admin', true)->get();
$customers = User::where('is_admin', false)->get();

Single Table Inheritance

class User extends Model
{
    public function scopeAdmin($query)
    {
        return $query->where('is_admin', true);
    }
    public function scopeCustomer($query)
    {
        return $query->where('is_admin', false);
    }
}

$admins = User::admin()->get();
$customers = User::customer()->get();

Single Table Inheritance

class Admin extends User
{
    protected static function boot()
    {
        parent::boot();
        static::addGlobalScope(function ($query) {
            $query->where('is_admin', true);
        });
    }
}

Single Table Inheritance

class Customer extends User
{
    protected static function boot()
    {
        parent::boot();
        static::addGlobalScope(function ($query) {
            $query->where('is_admin', false);
        });
    }
}

Single Table Inheritance

$admins = Admin::get();
$customers = Customer::get();

Single Table Inheritance

Read more:

• https://twitter.com/cmgmyr/status/885204646498893824

• https://tighten.co/blog/extending-models-in-eloquent

Default Model Data

Default Model Data

Schema::create('users', function (Blueprint $table) {
    $table->increments('id');
    $table->string('name');
    $table->string('email')->unique();
    $table->string('password');
    $table->string('role')->default('user'); // moderator, admin, etc
    $table->rememberToken();
    $table->timestamps();
});

Default Model Data

class User extends Model
{
    protected $fillable = [
        'name', 'email', 'password', 'role'
    ];
}

Default Model Data

$user = new User();
$user->name = 'Chris';
$user->email = 'cmgmyr@gmail.com';
$user->password = Hash::make('p@ssw0rd');

// $user->role is currently NULL

$user->save();

$user->role; // 'user'

Default Model Data

Remove ->default('user');

Schema::create('users', function (Blueprint $table) {
    $table->increments('id');
    $table->string('name');
    $table->string('email')->unique();
    $table->string('password');
    $table->string('role'); // moderator, admin, etc
    $table->rememberToken();
    $table->timestamps();
});

Default Model Data

Set $attributes

class User extends Model
{
    protected $fillable = [
        'name', 'email', 'password', 'role'
    ];

    protected $attributes = [
        'role' => 'user',
    ];
}

Default Model Data

$user = new User();
$user->name = 'Chris';
$user->email = 'cmgmyr@gmail.com';
$user->password = Hash::make('p@ssw0rd');

// $user->role is currently 'user'!

$user->save();

$user->role; // 'user'

Default Model Data

$user = new User();
$user->name = 'Chris';
$user->email = 'cmgmyr@gmail.com';
$user->password = Hash::make('p@ssw0rd');
$user->role = 'admin'; // can override default
$user->save();

$user->role; // 'admin'

Default Models

Remember our previous example?

class Post extends Model
{
    public function author()
    {
        return $this->belongsTo(User::class)->withDefault([
            'name' => 'Guest Author',
        ]);
    }
}

Default Models

We no longer need to provide a name, use the User $attributes property!

class Post extends Model
{
    public function author()
    {
        return $this->belongsTo(User::class)->withDefault();
    }
}

Default Model Data

class User extends Model
{
    protected $fillable = [
        'name', 'email', 'password', 'role'
    ];

    protected $attributes = [
        'name' => 'Guest Author',
        'role' => 'user',
    ];
}

Default Model Data

Watch Colin DeCarlo's - Keeping Eloquent Eloquent from Laracon US 2016

https://streamacon.com/video/laracon-us-2016/colin-decarlo-keeping-eloquent-eloquent

Sub-Queries

$customers = Customer::with('company')
    ->orderByName()
    ->paginate();

Get latest interactions?

<p>{{ $customer
    ->interactions()
    ->latest()
    ->first()
    ->created_at
    ->diffForHumans() }}</p>

Sub-Queries

public function scopeWithLastInteractionDate($query)
{
    $subQuery = \DB::table('interactions')
        ->select('created_at')
        ->whereRaw('customer_id = customers.id')
        ->latest()
        ->limit(1);

    return $query->select('customers.*')->selectSub($subQuery, 'last_interaction_date');
}

$customers = Customer::with('company')
    ->withLastInteractionDate()
    ->orderByName()
    ->paginate();

<p>{{ $customer->last_interaction_date->diffForHumans() }}</p>

Sub-Queries

Jonathan Reinink's Laracon 2018 Online Talk - Advanced Querying with Eloquent

https://github.com/reinink/laracon2018

Resources

• https://laravel.com/docs/5.6/eloquent

• https://laravel-news.com/eloquent-tips-tricks

• https://twitter.com/themsaid/status/1029731544942952448

• https://twitter.com/cmgmyr/status/885204646498893824

• https://tighten.co/blog/extending-models-in-eloquent

• https://streamacon.com/video/laracon-us-2016/colin-decarlo-keeping-eloquent-eloquent

• https://github.com/reinink/laracon2018

• https://eloquentbyexample.com

Thank you!

Please say "hi"

twitter.com/cmgmyr

github.com/cmgmyr

chrisgmyr.com

My project has two main branches: develop and master. In Envoyer I have two projects, one for dev.project.com which uses the develop branch and the other for project.com which uses the master branch.

Here is the final result of the circle.yml file. Let's work through each of the sections below.

Section 1: Defaults

By leveraging YAML anchors we can set a group of defaults that will be used for all of our later jobs. For now, this includes our

• working directory

• chosen CircleCI docker image

Section 2: Jobs

In this file we have three jobs: build (and test), deploy_develop, and deploy_master.

Our build job

1. Imports the defaults

2. Sets environment variables

3. Checks out the repo's code

4. Restores composer cache, if available

5. Runs composer install

6. Saves a new composer cache

7. Runs the test suite with PHPUnit

Our "deploy" jobs:

1. Imports the defaults

2. Pings Envoyer to deploy the project

Section 3: Workflows

Now that we have our jobs set up, we need to implement workflows to pull everything together. Workflows are optional, but they can come in handy depending on what you'd like to do with your project.

In this example, we only need one workflow notify_deploy which will notify Envoyer that we want to deploy a specific branch.

Within the workflow, you'll notice that we are listing all of our jobs: build, deploy_develop, and deploy_master.

We start off running our build job, and if that is successful, we'll move forward with our deploy jobs. Each deploy job requires the build to run first; then we'll check if the version branch matches the filter on the workflow. So deploy_develop is only run on the develop branch and deploy_master is only run on the master branch.

By limiting the filters to only the develop and master branches we can guarantee that we're only deploying those specific branches, but the build job will run on all branches (bug, hotfix, and feature branches), which is needed for pull requests.

Wrapping Up

Once we merge a branch into either develop or master CircleCI will build and notify Envoyer to deploy if successful. In our CircleCI dashboard, you'll now see a workflow similar to this.

You'll also need to make sure you turn off the "Deploy When Code Is Pushed" option in your Enoyer project.

Learn More

This is only scratching the surface of what you can do with CircleCI builds and workflows. I encourage you to look through the documentation and example projects to see what you can implement in your projects.

• 2.0 Documentation

• Sample Projects

• Workflow Documentation

• YAML 1.2 Spec

Please note - CircleCI nor Envoyer/Laravel paid me to write this article, I'm just a happy customer.

“I read through the entire codebase of Basecamp 3 and try to make things better that I don’t think are good enough, or revisit decisions that we’ve made earlier that I think now I have a better idea of how to do”

There’s a lot in that statement, so let’s unpack it.

First, he reads through the entire codebase! The fact that he does this shows great care for what he does and believes in.

Second, he makes changes where he doesn’t feel like the code is good enough. While many of us have ideas about what is “good” or not, I’m sure we’ve all gone back through older code and just known when we’ve seen it.

Lastly, he revisits past decisions that can be better handled now. Programming is an ever-changing space and developers are enhancing their skills and knowledge on a daily basis. So why shouldn’t our code reflect our most up-to-date understandings?

DHH isn’t the only one who does this though. Taylor Otwell (creator of Laravel) does something similar.

Going through code and documentation that you’ve already worked on isn’t the most glamorous job, even quite tedious, but necessary. It’s silly to think that something that was done years, weeks, or even days ago is still “good enough” for today.

I know I’ve fallen into the habit of not revisiting what I’ve worked on long ago — and maybe some projects don’t need it. However, if the public is using it — like in a current site, app, or package it might be time to take a look through for improvements.

Next Steps

I’m going to take a hard look at my messenger package (which needs some love) as well as a few side projects that I haven’t worked on in a while. What projects are you going to look at? Let’s share some successes. Send me a tweet or screenshot on Twitter, or leave a comment below.

$users = User::all();

But what happens when you want to sort your users?

As newcomers to the framework, I feel like most are too excited to “jump in and build something” instead of learning more about it. (But who can blame them, right?!?) So something like this would happen:

$users = User::all()->orderBy('name', 'ASC');

# BadMethodCallException with message 'Method orderBy does not exist.'

// or

$users = User::orderBy('name', 'ASC')->all();

# BadMethodCallException with message 'Call to undefined method Illuminate\Database\Query\Builder::all()'

Forget about all()

In my experience, I’ve never needed an unordered dump of data in an application.

Note that all() is a convenience method for get() but does not allow you to chain additional methods. Take a look:

public static function all($columns = ['*'])
{
    return (new static)->newQuery()->get
        (is_array($columns) ? $columns : func_get_args()
    );
}

By using get() you’ll be able to achieve the desired results.

$users = User::orderBy('name', 'ASC')->get();

// and

$users = User::where('email', 'LIKE', '%@gmail.com')  
    ->orderBy('name', 'ASC')->get();

So any time you reach for the all() method, I highly recommend using get() instead.

On a current project, I had to figure out how to grab a ton of data from an API (Facebook) that had dependent data — meaning the script cannot proceed to get new data before it’s done with the current data set. This typically ended up being an ID that was needed for the next call as well as some data that needed to be processed.

In pseudo-code, this would look something similar to:

$a = $get->a();  
$b = $get->b($a);   
$c = $get->c($b);   
$this->doSomethingWith($c);

As you can see, the code should not move ahead without processing the previous data. In my situation, I had to process all of the “A” jobs, then all of the “B” jobs, and so on, before continuing.

The data that I needed was quite large and each round needed a good amount of processing before continuing to the next step. Luckily this is where Laravel and its queue system stepped in to help!

Laravel lets you specify a dynamic queue name along with a job, like so:

dispatch((new JobA($data))->onQueue('a'));

In my application in each “JobA” a “JobB” would be called. For each “JobB” a “JobC” would be called. At the end of “JobC”, we’d do some additional work on the whole data collection. So you’d get something like this:

// In Controller  
dispatch((new JobA($data))->onQueue('a'));

// In JobA  
dispatch((new JobB($data))->onQueue('b'));

// In JobB  
dispatch((new JobC($data))->onQueue('c'));

// In JobC  
dispatch((new JobFinish($data))->onQueue('finish'));

I wanted to make sure we ran all of the jobs in order, and only continued onto the next set of jobs once the current batch was finished. This was very important since the application could easily have 20, or so, JobAs, 50 JobBs, and hundreds of JobCs.

In my supervisor config file, I added something similar to this:

[program:artisan-queue]  
command = php artisan queue:work --queue=a,b,c,finish

Now all of the jobs on the “a” queue would have to finish before the “b” jobs would start, and “c” would wait for “b”, and so on.

So there you have it — a prioritized queuing system in only a few lines of code!

The Laravel Queue system is very robust, and if you haven’t used it, I’d highly recommend trying it in your next project. You can read more about the queue system and queue priorities here.

Image manipulation is hard. Handling images in the long term is even harder. Here at Dose we have a lot of images and a number of ways to serve them. We have Android and iOS apps, as well as completely responsive websites, so each image has the potential of getting manipulated multiple times depending on the device, orientation, and how we optimize an image for a certain platform.

Handling this ourselves

We used to have an internal image service that took an author’s uploaded image and handled some pre-processing. On upload, we’d make sure it’s within a max width and encoded correctly. Animated GIF? We’d have to convert the file to MP4 and WEBM also. This would end up adding extra load on our servers and more space taken in our S3 account.

When an asset was requested with a certain height/width combination we’d check to see if we had it in our S3 bucket. If not we’d return the master asset and kick off a queue job to create it then add it to the bucket for the next request. As you can imagine, the usage was huge. Want to change the article promo image from 500px width to 475px width? That would invalidate all previous images and we’d need to recreate all new images the next time they were requested. What a mess!

If your product is not image manipulation, then don’t do this yourself. Services like Cloudinary do this much more efficiently and much better than you will, so use them. And if you’re worried about the cost, think about how much it’ll cost you in development and upkeep, as well as hosting, storage, and delivery costs. More on that later.

Getting Started with Cloudinary

Cloudinary is the market leader in providing a comprehensive cloud-based image management solution. Cloudinary is being used by tens of thousands of web and mobile application developers all around the world, from small startups to large enterprises. We are here to cover your every image-related need.

Source

Cloudinary has taken the massive task of handling and manipulating images and broke it down to something very simple — URL manipulation.

Take the following image url:

http://res.cloudinary.com/demo/image/upload/sample.jpg

Let’s say we’d like to resize this to a max width of 300px, you’d get

http://res.cloudinary.com/demo/image/upload/w_300/sample.jpg

How about we restrict the height to 150px

http://res.cloudinary.com/demo/image/upload/w_300,h_150/sample.jpg

Well, we got the size that we wanted, but it looks pretty bad right now. We’ll need to make some adjustments. Let’s crop it to fit the space that we need

http://res.cloudinary.com/demo/image/upload/w_300,h_150,c_fit/sample.jpg

Yeah, this looks a lot better!

Combining Transformations

Combining transformations is just as straightforward as single transformations, all you have to do is add another segment to the URL

http://res.cloudinary.com/demo/image/upload/w_300,h_150/c_crop,w_50,h_50,x_100,y_75/sample.jpg

So with this example we are:

1. Resizing the image to 300px X 150px then

2. Cropping the image to be 50px X 50px and moving the X, Y point to 100, 75 in order to focus in on the yellow part of one of the flowers.

Learn more

File Type Transformations

This is by far one of the most powerful features of Cloudinary. Say we are uploading a GIF, but want to optimize it and change it to a MP4.

http://res.cloudinary.com/demo/image/upload/kitten_fighting.gif

would turn into

http://res.cloudinary.com/demo/image/upload/kitten_fighting.mp4

Just by changing the extension of the file in the URL will make this conversion for you. No more keeping track of different file references or different hashes. Only ask for a different file extension!

Learn more

Programmatic SDKs

It’s all well and good that we can convert any file asset via a URL, but if you want to make these changes more programmatically, you can use one of their many SDKs. For this example, we’ll be using their PHP SDK

In my initial example, we ended with the final URL of

http://res.cloudinary.com/demo/image/upload/w_300,h_150,c_fit/sample.jpg

for our image. In the PHP SDK, we’d be able to do

$transformations = ['width' => 100, 'height' => 150, 'crop' => 'fill'];  
$url = cloudinary_url('sample.jpg', $transformations);

and multiple transformations, like our second example, would look like

$transformations = ['transformation' => [  
   ['width' => 300, 'height' => 150],  
   ['width' => 50, 'height' => 50, 'crop' => 'crop', 'x' => 100, 'y' => 75]  
]];  
$url = cloudinary_url('sample.jpg', $transformations);

Migrating to Cloudinary

Cloudinary has taken the hard work out of migrating assets over to their platform. There are currently a few options to choose from.

1. Add a full URL to your current image and Cloudinary will automatically pull this in for you.

2. Set up an auto upload mapping to your S3 bucket. When this “virtual” directory is requested, it will pull the asset from your bucket into your Cloudinary account.

Learn more

Why We Chose Cloudinary

Before moving forward with anything new, we went through a diligent research period where we were looking at a handful of SaaS options as well as possibly redesigning our current in-house system. As we worked through the options one thought became very clear — handling our own system didn’t make sense. There are a good handful of services that are more cost-effective and feature-rich than something that we could ever make. Our business is not handling images. Just the cost of AWS instances, storage, and CDN fees were tens of thousands of dollars per month. Now take developer costs to maintain and add to the system, and it adds up quickly. But even more importantly, each time something would break or need to be added to our image service, it would take attention away from more important tasks or services.

After evaluating a number of image and CDN services, we moved forward with Cloudinary for a number of reasons:

1. They were very attentive. They set up multiple meetings with their sales and tech teams to answer all of our questions and to help get us the best price for the resources we need. Even now, after the “sale”, they continue to reach out personally to share new features that haven’t been published yet and check in on analytics and our performance.

2. Price. Their price is a LOT cheaper than running all of our instances, storage, and CDN through AWS.

3. Features. The flexibility and amount of features they have for image handling is impressive and there would be no realistic way that we’d have the bandwidth in order to make similar features ourselves. Their system makes it very easy to make adjustments on the fly to see what combinations perform, and look better.

4. Uptime. Since the majority of our content is showing images, if the images aren’t available we aren’t able to provide the value to our users that we need to. Since moving to Cloudinary, our image uptime has been spectacular and image responsiveness has been significantly faster too.

Summary

We have simplified our image handling process over the last 6 months since starting to work with Cloudinary. They can easily handle our 4.5 Million images (and counting) and over 1.4 Billion requests per month. They also provide insight to help us further improve our performance on our sites. Site performance and user experience are not taken lightly, so we are very happy with our decision to utilize their services. Some other helpful points are

• Great documentation

• A bunch of add-on plugins like JPEGmini and Imagga

• Tons of transformation options like watermarks, custom pixelation, and even PDF to image conversion

• Automatic responsive image handling

• Video management and transformations

• Automatic backups to S3

• Newly introduced “Auto Everything”

As an aside, we’re just sharing this article and information as happy customers. Cloudinary did not commission this article nor give us any incentive for writing it. We just want to share our experience.