The first solution that comes to mind is to have a bunch of `if/else` sentences in the controller, and based on that, we do different things, render different views, etc. Or maybe create some services that are dynamically injected into the controller based on certain conditions. But this doesn't sound like the Laravel way.

I always thought that controllers are kind of static entities; we just load them in the route as an entry point, and that's it. But what if I told you we could load them dynamically based on certain conditions, while maintaining the same route?

This is what we are going to talk about in this article.

Let's bind controllers dynamically.

It occurred to me that maybe we can set a contract instead of the controller in the route, something like this:

Route::get('this-route/{resource}', ThisControllerContract::class)->name('this.route');

It turns out this is possible! We need to do a couple of things to make it work. Let me explain it with an example from my previous article, "How to Extend MustVerifyEmail.".

In that article, I extended the email verification feature to add my own phone verification. For the verification page, I wanted to keep the same route, but change the way I handle it depending on whether your email or phone number is not verified.

So, I created a new interface and used it on the route like this:

 Route::get('verify', UserVerificationPromptControllerContract::class)
        ->name('verification.notice');

And I defined the interface like this:

interface UserVerificationPromptController
{
    public function __invoke(): mixed;
}

In this case, I don't want to bind any route item to a model, so I don't add any parameter to the `__invoke` method. But, if you have any route model binding in your case, you need to add them as parameters; this is only the case for route model binding.

Then, in a service provider, we bind the controllers like this:

public function register(): void
{
  $this->app->bind(UserVerificationPromptController::class, function (Application $app) {
      /** @var ?User $user */
      $user = request()->user();

      if ($user && ! $user->hasVerifiedPhoneNumber()) {
          return $this->app
                      ->make(PhoneVerificationPromptController::class);
      }

      return $this->app->make(EmailVerificationPromptController::class);
  });
}

See how I can get the request data, in this case the user, to define what controller I want to inject into the route.

And it's that simple! Now you can have multiple controllers that handle the same route. And I just have to say... This is the way.

Every time I start a new project in Laravel with a starter kit, I enable the `MustVerifyEmail` feature. And I always take for granted that it works. The Laravel team does a great job making sure it works. But, recently, I asked myself, how does it actually work? That's what I'm going to explain in this article.

I'm going to explain to you by doing my own `MustVerifyPhoneNumber` feature. Let's get started.

The first thing is to create an interface called `MustVerifyPhone`. It is pretty similar to `MustVerifyEmail`. Below, you'll find the content of it:

interface MustVerifyPhoneNumber

{

    /**

     * Determine if the user has verified their phone number.

     */

    public function hasVerifiedPhoneNumber(): bool;

    /**

     * Mark the given user's phone number as verified.

     */

    public function markPhoneNumberAsVerified(): bool;

    /**

     * Send the phone number verification notification.

     */

    public function sendPhoneNumberVerificationNotification(): void;

    /**

     * Get the phone number that should be used for verification.

     */

    public function getPhoneNumberForVerification(): string;
}

Now, we need to implement this interface in your model, in this case, the `User` model:

class User extends Authenticatable implements MustVerifyEmail, MustVerifyPhoneNumber

{

	...

}

`MustVerifyEmail` actually implements the required methods in a trait. But wait, no trait implements the interface in the `User` model, right? Well, the trait is on the `Authenticatable` base class. If you go to the base class, you'll see a `MustVerifyEmail` trait. Let's do something similar.

I created a `MustVerifyPhoneNumber` trait with the following content:

trait MustVerifyPhoneNumber

{

    public function hasVerifiedPhoneNumber(): bool

    {

        return ! is_null($this->phone_verified_at);

    }

    public function markPhoneNumberAsVerified(): bool

    {

        return $this->forceFill([

            'phone_verified_at' => $this->freshTimestamp(),

        ])->save();

    }

    public function sendPhoneNumberVerificationNotification(): void

    {

        $this->notify(new VerifyPhoneNumberNotification);

    }

    public function getPhoneNumberForVerification(): string

    {

        return $this->phone_number;

    }

}

As you can see, there are two new columns we need to add to the `users` table: `phone_number` and `phone_verified_at`. We also need to create `VerifyPhoneNumberNotification`. Here is an example of the notification. Of course, you can create your own version:

class VerifyPhoneNumberNotification extends Notification implements ShouldQueue

{

    use Queueable;

    public function __construct() {}

    /**

     * @return string[]

     */

    public function via(User $notifiable): array

    {

        return [WhatsappChannel::class];

    }

    public function toWhatsapp(User $notifiable): TemplateMessage

    {

        $url = $this->verificationUrl($notifiable);

        return (new TemplateMessage)

            ->name('verify_phone_number_v1')

            ->addUrlButton($url);

    }

    protected function verificationUrl(User $notifiable): string

    {

        return URL::temporarySignedRoute(

            'verification.verify_phone',

            Carbon::now()->addMinutes(Config::get('auth.verification.expire', 60)),

            [

                'id' => $notifiable->getKey(),

                'hash' => sha1($notifiable->getPhoneNumberForVerification()),

            ]

        );

    }

}

You can create your own custom channel to send the notification if you want. However, the part I want you to examine is the `verificationUrl` method. See how we generate a temporary signed route that we are going to send to the user. I took this from the `Illuminate\Auth\Notifications\VerifyEmail` notification. You can send the user to a controller to verify the phone number and finally redirect to your dashboard.

The next step is to override the `verified` middleware. This middleware ensures that the user is redirected to the verification page if the user is not verified. Let's create our own version of the middleware.

class EnsureUserIsValidatedMiddleware

{

    /**

     * Handle an incoming request.

     */

    public function handle(Request $request, Closure $next, ?string $redirectToRoute = null): Response|RedirectResponse

    {

        if (

	        $this->emailNotVerified(request()->user()) 

	        || $this->phoneNumberNotVerified(request()->user())

        ) {

            return Redirect::guest(URL::route($redirectToRoute ?: 'verification.notice'));

        }

        return $next($request);

    }

    private function emailNotVerified(?User $user): bool

    {

        return ! $user?->hasVerifiedEmail();

    }

    private function phoneNumberNotVerified(?User $user): bool

    {

        return ! $user?->hasVerifiedPhoneNumber();

    }

}

In my case, I verify that both the email and phone number are verified; if not, we redirect to the `verification.notice` route. You can find this route in the `auth.php` routes file. Also, you can check the default `verified` middleware in `Illuminate\Auth\Middleware\EnsureEmailIsVerified`.

Finally, we just need to override the `verified` middleware in `bootstrap/app.php` like this:

return Application::configure(basePath: dirname(__DIR__))

    ->withMiddleware(function (Middleware $middleware) {

        $middleware->alias([

            'verified' => EnsureUserIsValidatedMiddleware::class,

        ]);

		...

    })->create();

And this is how you can implement your own verification feature based on the `MustVerifyEmail` feature from Laravel.

Today, I learned that Laravel collections have a “wrap” method, which performs a similar function to the “collect” method. So, let me explain what the key differences are.

collect method

The “collect()” function creates an instance of a Collection from the value provided. If the input is already a collection, it simply returns the collection untouched.

php

$collection = collect([1, 2, 3]); // Returns Collection([1, 2, 3])

$existing = collect([4, 5, 6]);
$collection = collect($existing); // Returns original Collection([4, 5, 6])

wrap Method

The “Collection::wrap()” method always guarantees a Collection output, regardless of the input type or existing structure. If the input is not an array or a Collection, it wraps it in an array before creating a Collection.

php

Collection::wrap('Alice'); // Returns Collection(['Alice'])
Collection::wrap(['Alice', 'Bob']); // Returns Collection(['Alice', 'Bob'])
Collection::wrap(collect(['Alice', 'Bob'])); // Returns Collection(['Alice', 'Bob'])

There is now a helper function for “Collection::wrap”. Should we have one?

However, I then had the idea of creating a Laravel package to make it easier. So, I created NodeGraph.

NodeGraph is a compact state-graph runtime designed for Laravel, making it easy to create controlled flows. In these flows, nodes can be AI agents or custom code that executes when the flow reaches a particular state, much like LangGraph.

You would ask, Why don't you just use LangGraph? And the reason is that they built it for Python and JavaScript, and I really like to work with PHP and Laravel.

Also, the key difference is that NodeGraph is fully integrated with Laravel. We store the State and Checkpoints in the database, which allows us to have more flexibility on when and how to run our flows, while keeping track of everything that's happening. This package can be helpful when building complex state machines, and we need to keep track of what’s happening on each run.

How NodeGraph Works

The first thing you need to create is a State, which is a PHP enum that holds all the possible states:

use Taecontrol\NodeGraph\Contracts\HasNode;

enum OrderState: string implements HasNode
{
    case Start = 'start';
    case Charge = 'charge';
    case Done = 'done';

    public function node(): string
    {
        return match ($this) {
            self::Start => \App\Nodes\StartNode::class,
            self::Charge => \App\Nodes\ChargeNode::class,
            self::Done => \App\Nodes\DoneNode::class,
        };
    }
}

Notice that there is a node() method where you map each State to a Node. The Nodes look like this:

namespace App\Nodes;

use App\Decisions\SimpleDecision;
use App\Enums\OrderState;
use App\Events\OrderEvent; // extends Taecontrol\NodeGraph\Event
use Taecontrol\NodeGraph\Node;

class StartNode extends Node
{
    public function handle($context): SimpleDecision
    {
        $d = new SimpleDecision(OrderState::Charge);
        $d->addMetadata('from', 'start');
        $d->addEvent(new OrderEvent('start'));
        return $d;
    }
}

class ChargeNode extends Node
{
    public function handle($context): SimpleDecision
    {
        // ... charge logic ...
        $d = new SimpleDecision(OrderState::Done);
        $d->addMetadata('from', 'charge');
        $d->addEvent(new OrderEvent('charged'));
        return $d;
    }
}

class DoneNode extends Node
{
    public function handle($context): SimpleDecision
    {
        $d = new SimpleDecision(null); // stay in terminal state
        $d->addMetadata('from', 'done');
        $d->addEvent(new OrderEvent('done'));
        return $d;
    }
}

Each Node has a centralized Context:

use Taecontrol\NodeGraph\Context;
use Taecontrol\NodeGraph\Models\Thread;

class OrderContext extends Context
{
    public function __construct(protected Thread $thread) {}

    public function thread(): Thread
    {
        return $this->thread;
    }
}

We can use Context to pass whatever we need to our Nodes. But, it is required that you pass a Thread as a parameter. Nodes return a Decision:

namespace App\Decisions;

use Taecontrol\NodeGraph\Decision;

class SimpleDecision extends Decision {}

As you saw in the Node definitions’ code, you can add events, set a new state, or update some metadata in a Decision. When the flow runs in that Node, the Thread's current State is updated to what you specified, the events are dispatched, metadata is stored in the Thread, and a new checkpoint is created.

The next step is to put everything together in a Graph.

use Taecontrol\NodeGraph\Graph;
use App\Enums\OrderState;

class OrderGraph extends Graph
{
    public function define(): void
    {
        $this->addEdge(OrderState::Start, OrderState::Charge);
        $this->addEdge(OrderState::Charge, OrderState::Done);
        // Done has no outgoing edges, so it's terminal
    }

    public function initialState(): OrderState
    {
        return OrderState::Start;
    }
}

Finally, you can run it like this:

use Taecontrol\NodeGraph\Models\Thread;

$thread = Thread::create([
    'threadable_type' => \App\Models\Order::class, // anything morphable
    'threadable_id' => (string) \Illuminate\Support\Str::ulid(),
    'metadata' => [],
]);

$context = new \App\Contexts\OrderContext($thread);
$graph = app(\App\Graphs\OrderGraph::class);

$graph->run($context); // Start -> Charge
$graph->run($context); // Charge -> Done
$graph->run($context); // Done is terminal; finished_at will be set on this run

See how we first create a Thread, which is a model with a polymorphic relation to the model we want to connect it to. We make a Context and pass the Thread as a parameter. Then, we instantiate the Graph. Finally, we run the Graph.

And it’s that simple. The package is pretty much in beta for now, and you can get more information about how to install and use it in the NodeGraph repository. Let me know what you think!

Paga Fácil

The idea is that users can make payments in Venezuela without ever leaving the WhatsApp app. Compared to the current method, it should be easier and faster.

The user should simply write in natural language that they want to make a new payment, and the service will guide them through the payment step by step without leaving WhatsApp.

Under the hood, we use Cobra Fácil API, which allows us to make transfers from one account to another.

We use passwordless login; every time users log in to the platform, they receive a 6-digit code via email. Users must be authenticated on the platform to perform actions such as creating a payment method or updating their profile.

For now, we only support mobile payment, which is the allowed option by Cobra Fácil.

So, let’s start designing this app.

General Architecture

From the graph, this is the basic flow:

1. Users send a message to WhatsApp, and WhatsApp sends that message to our Laravel app via a webhook call.

2. We process the inbound message and send it out to a “Routing System”. The routing system defines to which “Agent” the message is sent.

3. The “Agent” processes the message; it may interact with other agents in the process. Then, it sends a response back to the WhatsApp service and the users.

We need a way to store the application’s state. For this, we are going to create a “conversations” and “conversation_messages” tables. Let’s see the data architecture now.

Data Architecture

1. User: This is the basic user, defined by Laravel.

2. Conversation: The conversation model has

   • User ID: Because it belongs to a user.

   • State: This is the current state of the conversation. A determined agent handles the conversation based on this state.

   • Is Active: To know if the conversation is active. Given we have only one chat, there should be only one active conversation.

   • Expires At: If the conversation has been active for more than a particular time, we should expire it.

   • Metadata: This column stores all relevant data in JSON format.

3. Conversation Message: This model has

   • Conversation ID: Because it belongs to a conversation.

   • Role: This is to define whether it is a message from the user or the assistant.

   • Direction: This defines whether the message is inbound or outbound.

   • Content: Content of the message.

4. Payment Method: This model specifies the bank account from which the user transfers the money.

Now, let’s take a closer look at the conversation’s flow.

Conversation Flow

When users start a new conversation, we direct them to Intent Detection, and the Intent Detection Agent manages this state.

Intent Detection Agent

This agent ensures we understand the user’s intent, and based on that, we route them to either Payment Data Collection or Customer Service state.

Here, we get the inbound message, and we pass it to an LLM to decipher the user intent. When the LLM knows what the user wants, it calls a function to transition to one of the allowed states mentioned earlier.

How does the LLM know what the allowed states are?

We create the StateGraph class to define all relations between the states. We call those “edges”. In this class, we can determine things like what the initial state of a conversation is, what state is terminal, what the neighbors of a specific state are, and if a state can transition to another state.

In this case, we pass the neighbor states Intent Detection state (Payment Data Collection and Customer Service).

If one of the intents is detected, we transition to the corresponding state. Since we want the next agent to respond to the user, we call the next agent directly.

Otherwise, the LLM will continue asking questions to understand the user’s intent.

Let’s say the user wants to make a payment. We’ll call the Payment Data Collection Agent then.

Payment Data Collection Agent

This agent gathers all the necessary information to make a payment. It asks questions like What amount is, Recipient name, Recipient phone number, Document ID, among other things.

Once it has all the information, it calls a function to store it in the conversation metadata and calls the next agent.

OTP Capture Agent

This agent retrieves the data from the previous agent and makes the first API call to Cobra Fácil, allowing the user’s bank to send a verification code to the user, ensuring they actually want to initiate a transfer from their bank account. Additionally, it sends a message to the user requesting that they provide this code. Then, we update the conversation state, but we don’t call the next agent. We need to wait for the user to give the OTP code so we can call the next agent.

Payment Execution Agent

With the OTP code and the payment information, this agent makes a second API call to Cobra Fácil to execute the payment. We update the conversation state and tell the user that the payment is in progress.

Payment Status Monitoring

We don’t handle this state like the others. In this case, we monitor the pending payment transaction from Cobra Fácil in a Laravel command. Once the transaction is processed, we update the conversation state and send back a message to the user with the successful payment details. Hence, the last two states are ‘Payment Failed’ and ‘Payment Success’.

Customer Service Agent

On the other hand, if the user asks questions about the service, this agent handles them. It simply responds to any questions the user has about the service.

The conversation automatically expires once the user completes a payment or a specified amount of time has passed without any interaction with the user.

And that’s it! As you can see, we can handle flows by designing a “state machine” where each node is an agent. This approach allows us to create highly flexible conversation flows.

Should I create a package to make these types of applications easier to build?