Action class usage in my Laravel Apps

Action class usage in my Laravel Apps

What is an action class?

I define an action class as exactly that – a class that performs a single action. Examples include addUser, deleteUser, assignRole etc.

In my applications I typically make these classes invokable. However, there will be the odd case where I choose to add a method to call, it depends on usage and how the code reads.

Action class structure

The structure of my classes very much depends on the structure of the App itself. Is the App a standard app with its own database or does it pass everything off to a REST API and effectively acts as the front-end?

Action class usage in a typical App

In a typical App my action classes return a Boolean. I keep things simple, the action either succeeds or doesn’t. Error handling is either handled by the controller or internally within the action, it depends on how exceptions are being handled and whether actions need to be retried, this is typically a business decision.

Below is a simple example which sets the salesperson for an order.

class AssignSalesPerson
{
    public function __invoke(
        int $customer_id,
        string $order_reference,
        array $input
    ): bool {
        Validator::make($input, [
            'sales_person_code' => [
                'required',
                Rule::exists(User::class, 'sales_person_code')
            ]
        ])->validate();

        $order = (new Order())->getOrder($customer_id, $reference);
        if ($order === null) {
            return false;
        }

        try {
            DB::transaction(function () use ($order, $input) {
                // Update the order
                $order->sales_person_code = $input['sales_person_code'];
                $order->save();
                
                // Log the order change
                // ...   
            });

            return true;
            
        } catch (\Exception $e) {
            // Log the exception the error
            //...
            return false;
        }
    }
}

Action class usage with a REST API

If the App is a frontend for a REST API, the structure of my action classes changes. Instead of returning a Boolean, they return an integer, specifically the http status code returned from the API request. Additionally, these action classes will extend a base class which will contain several helper methods and properties.

Below is an example of the parent for API action classes.

abstract class Action
{
    // The message to return to the user, this is usually the message
    // from the the API when the request didn't succeed
    protected string $message;

    // Store any validation errors from the API
    // Our App can then pass these on as necessary
    protected array $validation_errors = [];

    // Store any parameters that need to be passed to the view
    // For example the id for a new resource 
    protected array $parameters = [];

    public function getMessage(): string
    {
        return $this->message;
    }

    public function getParameters(): array
    {
        return $this->parameters;
    }

    public function getValidationErrors(): array
    {
        return $this->validation_errors;
    }
}

And this is an example of a class which creates a budget item.

class CreateBudgetItem extends Action
{
    public function __invoke(
        Service $api,
        string $resource_type_id,
        string $resource_id,
        array $input
    ): int {
        // Handle any validation which needs to be 
        // done locally before passing the data to the API

        if (count($this->validation_errors) > 0) {
            return 422;
        }

        // Create the payload to send to the API        
        $payload = [
            ...
        ];

        $create_response = $api->budgetItemCreate(
            $resource_type_id,
            $resource_id,
            $payload
        );

        if ($create_response['status'] === 201) {
            return $create_response['status'];
        }

        if ($create_response['status'] === 422) {
            $this->message = $create_response['content'];
            $this->validation_errors = $create_response['fields'];

            return $create_response['status'];
        }

        // Unexpected failure, store the message
        $this->message = $create_response['content'];
        return $create_response['status'];
    }
}

The names of my classes depend on the complexity of the App. The class names shown above are simply examples, typically I try to organise my code by namespace and keep the names simple. If you see \App\Actions\BudgetItem\Create you know exactly what the action class is doing, there is no way to misinterpret the desired action.

Benefits

There are several benefits to using action classes – I’m going to talk about two for now, in the future I might do a full deep dive into all the positives and negatives.

Encapsulation

The class encapsulates all the code for the function, if you are strict in how you use actions this is a massive plus, there is a single class that performs the action, and it is easily testable.

Reusability

Action classes are reusable, it is easy to call an action class in a console command or job, I’ve several actions that need to be called on command as well as based on a user action. If I didn’t use action classes I would have had to create something similar or worse, duplicate the relevant code.

Continue to evolve

My action classes have evolved over time and I’m sure I will make more tweaks in the future. Much of my client work is creating B2B Apps and typically they require event logging, transactions, retrying. My real-life action classes are much more complex than the examples detailed above.

As much as I love action classes, they are not always the best solution. I try to ensure my action classes stay small. In cases where that is not possible and you still want to use the same idea, invokable controllers can help.

This post is part of a series about my development process. Please check out my typical project setup and my Git workflow.

Running at 45

A group of older men running in the park

Started running

I started running when I was forty-two and for the first couple of years I was very much off and on, I managed to run 200km in 2020 and the same again in 2021. In 2022, I decided to take my running more seriously and let’s just say, 2022 was quite different to the previous two years. I ran 1285km.

Progress

So, what does running progress look like at 45? Well, slow and steady. I imagine this is true regardless of your age but as I can’t go back in time, all I can tell you about is what I know.

The Numbers

Below I’ve detailed some of the numbers so you can see my progress and how things have changed.

MetricJan 2022Dec 2022
Average pace across all runs6:15 / km5:19 / km
Average cadence across all runs158 spm168 spm
Average stride length1.05 m1.13 m
VO2 Max4550
Weight85 kg79 kg
Running progress at 45

Disappointed?

I’d like to have gotten faster this year but that wasn’t ever going to happen. One of the most crucial factors for improving your running is sleep. With a 3-year-old who still refuses to sleep through the night, our own sleep has been poor for a while. We appear to be turning a corner, but we aren’t too hopeful just yet. Our other son started sleeping more consistently around the same age so who knows?

Where next?

I haven’t been working on speed, my goal for a while has been distance. I’m aiming to complete one or two ultramarathons this year. Later in the year with the ultramarathons under my belt, I will move to more speed work. In the short term I’d love to get my 5k down to 21mins and my 10km down to 46mins. These times aren’t outrageous, they are both times that my watch thinks I could achieve given the right conditions. I have a stretch goal for under 20mins, that may be pushing it, we will see.