DEV Community: Thomas Emad

How AST Powers Modern Frameworks — And a Wild Idea for Blade

Thomas Emad — Fri, 20 Mar 2026 16:50:25 +0000

We talked last time about Blaze and how it makes improvements — and if you think about it, we said it relies on the concept of AST (Abstract Syntax Tree).

This is the same approach that Vue.js, Svelte, and Angular use. So let's dig into it.

Why Frameworks Exist

The whole idea starts from wanting a different way to write code than the traditional approach — just to keep things cleaner and more expressive. That's basically the core purpose of frameworks.

Since the code you write isn't understood directly by the browser, it goes through a compile step, which transforms it into optimized JavaScript. During compilation, the AST is created — a Tree that represents and simplifies the structure of your code.

The AST concept applies to almost everything in the template, even something as simple as a <div>.

The 4 Stages of AST Processing

1. Lexical Analysis (Tokenization)

The code is broken down into an array of tokens — small meaningful units the compiler can walk through one by one.

For example, a function call like isAdmin(1) becomes:

type: function,    value: isAdmin
type: punctuation, value: (
type: int,         value: 1
type: punctuation, value: )

That's it — just a structured array of everything in your code, split apart and labeled.

2. Parsing

The token array is used to build a Tree — this is your AST. Each node in the tree represents a piece of your code with its full context and relationships.

If you want to see what an AST actually looks like, check out AST Explorer — it's a great visual tool.

3. Optimization via AST Traversal

This is where the magic happens. The compiler walks through the tree branch by branch — a process called AST Traversal. Think of it like a journey through the structure of your code.

One common traversal method is Depth-First Search (DFS), which itself has variants:

Pre-order → Root → Left → Right
In-order → Left → Root → Right
Post-order → Left → Right → Root

During traversal, the compiler makes decisions like:

<h2> with no dynamic content? → Mark it as static, skip it in re-renders
Something reactive or data-bound? → Attach a flag so it gets tracked and updated

This is what allows some frameworks to reduce or eliminate their reliance on the Virtual DOM entirely, while others (like Vue) still use it — but in a smarter, more targeted way.

4. Code Generation

Finally, the optimized AST is used to generate the actual JavaScript that runs in the browser. The framework then uses this output to construct the real DOM efficiently.

The Wild Blade Idea

Here's the part I find genuinely interesting — and maybe a little ambitious.

What if we applied this entire pipeline to Blade (Laravel's templating engine), properly — not just as a performance trick, but as a real compilation layer?

At that point, it wouldn't just be about performance. We could build on top of it:

Morph diffing — compare a Virtual Tree against the Real DOM and do surgical updates instead of full replacements
Real-time attributes — tag an element so the browser sends a request to the server, and PHP responds with only the changed data
Potentially a much lighter alternative to pulling in a full JS framework for dynamic UI

Is this basically what HTMX does? Kind of. Is the Morph piece already in Alpine.js? Also yes. But applying it natively at the Blade level, with PHP-aware compilation — that's a different story.

I don't know exactly how to implement it. Maybe it ends up in the bin like most late-night ideas. But I think it's worth writing down.

Exploring an AST-Based Template Engine in PHP — Thoughts?

Thomas Emad — Wed, 18 Mar 2026 15:50:07 +0000

I’ve been exploring an idea and would really like to hear different perspectives on it.

What if a PHP template engine (like Blade) moved from being string-based to an AST-driven pipeline (lexer → parser → AST), so it actually understands the structure of the template instead of just compiling it?

The thought is that this could produce a tree representation of the view (some kind of server-side VDOM). With that, it might be possible to clearly separate static and dynamic parts based on AST analysis.

In theory, instead of re-rendering the full HTML on every request, the server could work at a node level:

identify which parts are dynamic
track them as nodes in a tree
and update only those parts when data changes

Something conceptually similar to how virtual DOM works in frameworks like Vue, but driven from the server side.

For example:

dynamic variables could be detected at compile time
certain values could be marked as “live”
the browser could request only those live parts (e.g. via small, specific requests)
and the response would update only the affected nodes (kind of like DOM morphing instead of full re-render)

I’m not saying this is practical or better — I’m still trying to understand the trade-offs and limitations.

I’d really appreciate your thoughts:

Does this approach make sense in a server-driven (PHP) context?
Are there similar ideas or implementations I should look into?
What challenges do you immediately see (performance, state, complexity, etc.)?

Just looking for an open technical discussion.

DTO Design Pattern: Is It Over-Engineered?

Thomas Emad — Wed, 18 Mar 2026 14:06:00 +0000

Some people, when they try to explain DTOs, make it too simple just to be easy to understand — but they focus only on the explanation itself.

That makes it easy to understand, but anyone will ask:

Why should I use it?
Can't I just use the normal way? Isn't this over-engineering?

Like this:

namespace App\DTO;

class UserDTO
{
    public string $name;
    public string $email;
    public string $password;

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

And when we want to use it:

public function createUser(Request $request)
{
    $userDTO = new UserDTO(
        $request->input('name'),
        $request->input('email'),
        $request->input('password')
    );

    $user = $this->userService->createUser($userDTO);

    return response()->json($user);
}

Anyone will say: Why am I using a DTO? I can just do this:

$user = $this->userService->createUser($request->all()); // $request->validate()

And anyway, $fillable will protect me from mass assignment.

And to be honest with you: You are right.

Real-World Case: Big Data and Layers

Now, let's see a real-world case.

If we have big data and we transfer it across many layers, we usually use arrays. Just look at the $history structure in this example.

I use the same structure for:

HolidayShift
PublicHoliday
Errands
Leaves
OvertimeRequest

Some items may be 0, null, or may not exist at all.

public function getHolidayHistory($timeManagement, $overtime_schedule, $contract, $work_schedule, $publicHolidays, $attend)
{
    $holiday = [];

    foreach ($publicHolidays as $holiday) {
        if (Carbon::parse($attend->date)->between($holiday->start_date, $holiday->end_date)) {
            $latesSignInMinutes = $this->calculator->calculateLateSignIn($attend, $work_schedule->start_time);
            $earlyLeaving = $this->calculator->calculateEarlyLeaving($attend, $work_schedule->end_time);

            $history[] = [
                'absent'      => false,
                'type'        => 'holiday',
                'date'        => $attend->date,
                'item'        => $holiday,
                'attend_item' => $attend,
                'data'        => [
                    'sign_in'                        => $attend->sign_in,
                    'sign_out'                       => $attend->sign_out,
                    'late'                           => $latesSignInMinutes,
                    'late_deducted_percent'          => 0,
                    'early_leaving_deducted_percent' => 0,
                    'early_leaving'                  => $this->calculator->checkFromFingerprintOut($timeManagement, $earlyLeaving),
                    'deducted_percent'               => 0,
                    'overtime'                       => Carbon::parse($attend->duration)->hour,
                    'amount_overtime'                => $this->presentPublicHolidays->getPresentPublicHolidayAmount(
                        $overtime_schedule,
                        $contract,
                        $attend->duration
                    ),
                ],
            ];
        }
    }

    $history[] = [
        'absent'      => true,
        'type'        => 'holiday',
        'date'        => $attend->date,
        'attend_item' => $attend,
    ];

    return $history;
}

Do you see the potential problems here?

From a coding perspective, we can make it work without errors. But realistically, we are never 100% sure.

Of course, for big features we use testing — but in cases like this, TDD is not always realistic. So if some item does not exist, every time we use $history we have to write:

isset($history['x']) ? $history['x'] : 0; // or
$history['x'] ?? 0;

Can We Use DTOs Here?

$history[] = new AttendanceHistoryDTO(
    absent: false,
    type: 'holiday',
    date: $attend->date,
    item: $holiday,
    attend_item: $attend,
    data: new AttendanceDataDTO(
        sign_in: $attend->sign_in,
        sign_out: $attend->sign_out,
        total_late: $latesSignInMinutes,
        early_leaving: $this->calculator->checkFromFingerprintOut($timeManagement, $earlyLeaving),
        deducted_percent: 0,
        overtime: Carbon::parse($attend->duration)->hour,
        amount_overtime: $this->presentPublicHolidays->getPresentPublicHolidayAmount(
            $overtime_schedule,
            $contract,
            $attend->duration
        ),
        late_deducted_percent: 0,
        early_leaving_deducted_percent: 0,
    )
)

Now, any time we use $history, we don't need to worry about:

isset($history['x']) ? $history['x'] : 0;

Because the default values live inside the DTO itself.

Handling Missing Data in Real Use

Now look at this real usage example:

isset($content?->data?->total_late) ? $content?->data?->total_late : 0;

Why am I still doing this even with DTOs?

Because when you use DTOs:

If you write something that does not exist, your editor will warn you.
PHP will throw an exception in development and testing — and that's good.
But throwing exceptions in production is not always a good idea 😅

The Right Approach: Focus on Business Needs

There are many correct ways to use DTOs.

But always focus on your business needs first. Understand the problem, then choose the right tool.

Personally, I prefer to:

Write the code badly → make it normal → then ask: what is the best solution?

What do you think? 😃

Why PHP-FPM Consumes More RAM in Production Than Actual Usage?!

Thomas Emad — Tue, 17 Mar 2026 14:04:06 +0000

Understanding PHP-FPM Memory Behavior

Quick answer: PHP-FPM doesn't release memory back to the OS after allocation because memory allocation is expensive. Instead, it keeps the memory reserved for potential reuse. This isn't a memory leak — the memory remains accessible and reusable by PHP.

Understanding PHP's Memory Lifecycle

PHP has a lifecycle similar to what you might see in frameworks like Laravel. PHP's execution goes through several phases, starting with MINIT() and ending with MSHUTDOWN().

During MINIT(), PHP allocates just enough memory to get started using start_memory_manager. This initializes the allocator with a minimal baseline from the OS — around 45KB as an example.

Then, during RINIT() (request initialization), when your application handles a job, performs a large collection operation, or executes a resource-intensive query, PHP needs to allocate more memory (e.g., 124MB). This is when the Zend Memory Manager (ZMM) springs into action.

How Zend Memory Manager Allocates Memory

The ZMM categorizes memory allocations into three types:

Small allocations: Less than 3KB
Large allocations: Between 3KB and 2MB
Huge allocations: Greater than 2MB (these come directly from the OS)

If there's no pre-allocated memory available, huge allocations use mmap and are handled differently from smaller allocations.

For example, if PHP needs memory, it might request 150MB from the ZMM, which then asks the OS to reserve that space using mmap. But why 150MB when you only needed 124MB?

This is called pre-allocation. PHP requests slightly more memory than immediately needed to reduce the number of expensive mmap and munmap system calls to the OS. This optimization improves performance by batching memory operations.

What Happens After Request Completion

When the request finishes, RSHUTDOWN() is triggered. The garbage collector kicks in, frees up the memory space, and cleans up zvals (PHP's internal value structures).

However — and this is the key point — PHP and ZMM free this memory internally but don't return it to the OS. Why? Because if PHP needs memory again soon, it can reuse what's already allocated instead of requesting more from the OS. Since memory allocation is relatively expensive in terms of system resources, PHP keeps this memory reserved as a performance optimization.

This means whenever PHP needs memory again, it uses what's already available rather than making new system calls. While efficient, it causes PHP to appear to consume more RAM than it's actively using.

What About `unset()`?

You might be thinking: "But doesn't unset() free memory in PHP?"

Yes, unset() removes references to objects and creates free blocks that can be reused — but these are typically small allocations. However, if enough memory is freed to clear an entire page (ranging from 4KB to 2MB) and clear a complete chunk, only then will PHP return that memory to the OS.

Practical Implications and Best Practices

This behavior explains why frameworks like Laravel implement features such as:

Lazy loading: Defers loading resources until needed (though don't overuse it or you'll face performance issues)
Chunking: Processes large datasets in smaller batches
Pipes: Streams data through transformations efficiently

These patterns help manage memory more effectively by working with PHP's memory management behavior rather than against it.

Conclusion

PHP-FPM's higher-than-expected RAM consumption in production isn't a bug or a memory leak — it's an intentional optimization. By keeping allocated memory reserved rather than constantly requesting and releasing it from the OS, PHP reduces expensive system calls and improves overall performance. Understanding this behavior helps you better monitor and optimize your PHP applications in production environments.

How Blaze Could Change Blade Component Rendering in Laravel

Thomas Emad — Sun, 15 Mar 2026 17:42:45 +0000

Recently, there has been an interesting trend in modern tooling: moving work from runtime to compile time to improve performance.

We can see this direction in multiple tools:

Vite 8 now moving toward Rolldown built by Rust
Continuous improvements in Inertia.js
A new idea around Laravel Blade components called Blaze

In this article, we'll explore the idea behind Blaze and why it could improve Blade component rendering.

First: How Blade Works

Before talking about Blaze, we need to remember how Laravel Blade works.

In Laravel, Blade is a templating engine that allows developers to write directives such as:

@if ($condition)
    <p>Hello</p>
@endif

But HTML does not understand @if or @php.

So the first time a page is loaded, Laravel runs the Blade compiler which transforms Blade directives into plain PHP:

<?php if ($condition) { ?>
<p>Hello</p>
<?php } ?>

After compilation, Laravel stores the compiled result inside:

storage/framework/views

So the next time the page is requested, Laravel simply loads the compiled PHP file instead of recompiling the Blade template.

When Blade Files Grow

Imagine your dashboard.blade.php becomes larger and contains multiple UI parts:

Charts
Employee attendance
Calendar
Widgets

You will most likely start using Blade components.

<x-charts :data="$data" />

When Laravel encounters this component, it resolves it internally. A simplified version of the process looks like this:

Request
 → Create Component
 → Render View
 → Return HTML

This process happens during runtime. If your page contains many components, this repeated rendering can introduce some overhead.

Enter Blaze

Blaze is not a replacement for Blade. Instead, it aims to optimize how Blade components are rendered.

The key idea behind Blaze is something similar to folding and compilation. Instead of repeatedly rendering components during runtime, Blaze analyzes the component structure first.

Building an AST

Blaze breaks the component into nodes and constructs something similar to an AST (Abstract Syntax Tree). This is similar to how frameworks like Vue.js analyze templates.

Component
 ├─ HTML Node
 ├─ Attribute Node
 └─ Child Component

Once the structure is analyzed, Blaze can optimize and cache the result.

Generating a Function

Instead of recreating the component logic every request, Blaze generates a function representing the compiled component.

Compile Component
 → Generate Function
 → Cache Function

Then when the page renders:

Call Function
 → Return HTML

Three Possible Component Scenarios

Blaze handles components in three main ways.

First time execution

Call function
 → Execute
 → Return HTML

Repeated component usage

Return cached result

Static components

If the component is fully static (for example, an icon component), Blaze can skip compilation and directly return the HTML.

Simplified Blaze Flow

Compile
 → Generate Function
 → Call Function
 → Return HTML

The core idea is simple: move work from runtime to compile time.

A Broader Trend in Modern Tooling

This idea is not unique to Blaze. Many modern tools are moving in this direction:

Rust-based compilers
Faster bundlers
More aggressive compile-time optimization

For example:

Vite adopting Rolldown
Faster compilation pipelines
Smaller runtime cost

Final Thoughts

Blaze introduces an interesting direction for improving Blade component rendering. By shifting more work into compile time, it may reduce the runtime overhead caused by repeatedly rendering components.

This approach aligns with a broader trend across modern developer tooling.

In the next article, we'll explore Vite and Rolldown and why the ecosystem is increasingly moving toward Rust-based tooling.

Sources

Thinking Out Loud: A Workflow Engine I Built at Work This Week

Thomas Emad — Sat, 21 Feb 2026 17:34:30 +0000

I was thinking about something that excited me at work this week, and I wanted to share it out loud.

Imagine you have a flow covering Sales, Supply Chain, and Pre-Sales, all connected in a monolithic project. The flow might start with a BOQ, then produce a Purchase Request, then check if inventory is available — if yes, create a Quotation; if not, send a Request for Quotation (RFQ), then collect Supplier Quotations, and eventually move to purchasing, warehousing, and delivery to the client, with many branching cases at each step.

Now imagine you want to know: where did this BOQ end up?
You’d want a Stage column on each item in the flow, so when you open a BOQ it tells you “we’re currently at Material Issue stage”, and when you open a Supplier Quotation it tells you the same.

A Live Query for this would be a nightmare given how branched and deep the flow is, so the better approach is storing the stage as a database column — and this wasn’t just the easier choice, the business requirements actually needed it.

But here’s the problem: every time the stage changes, do I have to update the entire flow at once? And in every service, do I have to embed the entire flow logic? Imagine the amount of repetition that creates.

So I asked myself: what if, from any point in the flow, I only need to know what came before me and pass it the update — nothing more?

Inside PurchaseRequestService, I know the step before me is BOQ and I have its ID.
Inside QuotationService, the step before me is Purchase Request.
Inside RequestForQuotationService, the step before me is also Purchase Request.

If every service can say “here’s what came before me” and pass along the update data, that would be elegant.

The solution came to mind from a tutorial I was studying in the morning — a video about Event-Driven Architecture (EDA) and how powerful it is in microservices. If you’re interested, it’s in Arabic, so you might want to enable subtitles or switch to Arabic, whichever works for you 🙂

https://youtube.com/playlist?list=PLpJtaIgvI9k_Kz2x91AtekDdVvqzYfMIm&si=Bvfvn4RkODE4jDUF

EDA is built on a simple concept: Producer + Broker + Consumer.

I basically needed to fire an event from any service, have it directed to the right service that needs updating, pass the data, and let that service update itself.

Losing me? Let me break it down:

When Create Purchase Request 
  -> Fire Event (Producer) 
  -> Listener (Broker) 
  -> Finds the right service 
  -> BoqService (Consumer) 
  -> Updates BOQ with $data

But what if we want it to keep going dynamically and propagate on its own? Simple — we return the previous step as part of the response:

When Create RFQ 
  -> Fire Event (Producer) 
  -> Listener (Broker) 
  -> Finds the right service 
  -> PurchaseRequestService (Consumer) -> {
       Update current PR with $data
       Return previous step (BOQ) + new $data
       Fire new event with new data
     }

This needs to run through a queue because doing it synchronously at runtime would be terrible for performance — and we don’t need the update to happen in the same second anyway. It essentially becomes a recurring event that keeps firing until it hits the zero point, which is the BOQ (where it returns null and stops). The actual zero point in our case is the Purchase Request, for business reasons I helped design 🙂

Let’s now look at how this translates to code.

The Event — SalesProcessEvent:

<?php

namespace Modules\Sales\Events;

use Illuminate\Queue\SerializesModels;
use Modules\Sales\Enums\SalesProcessStepEnum;
use Illuminate\Foundation\Events\Dispatchable;
use Illuminate\Broadcasting\InteractsWithSockets;

class SalesProcessEvent
{
    use Dispatchable, InteractsWithSockets, SerializesModels;

    /**
     * Create a new event instance.
     */
    public function __construct(
      public SalesProcessStepEnum $mainStage, 
      public SalesProcessStepEnum $openStage,
      public array $data
    ) {}
}

The Listener (our Broker) — SalesProcessListener:

<?php

namespace Modules\Sales\Listeners;

use Illuminate\Queue\InteractsWithQueue;
use Illuminate\Contracts\Queue\ShouldQueue;
use Modules\Sales\Events\SalesProcessEvent;
use Modules\Sales\Strategies\Classes\SalesProcessStrategy;

class SalesProcessListener implements ShouldQueue
{
    use InteractsWithQueue;

    public function __construct(
        private SalesProcessStrategy $salesProcessStrategy
    ) {}

    public function handle(SalesProcessEvent $event): void
    {
        $mainStage = $event->mainStage;
        $openStage = $this->salesProcessStrategy
            ->setService($event->openStage)
            ->updateStage($mainStage, $event->openStage, $event->data);

        if ($openStage !== null) {
            SalesProcessEvent::dispatch($mainStage, $openStage['stage'], $openStage['data']);
        }
    }
}

Everything here depends on SalesProcessStrategy. If you're not familiar with the Strategy Pattern, the course above covers it well. The short version:

it takes fixed input, runs different operations depending on context, and can return different output. What changes is the process in the middle — and what controls that is the Strategy, which resolves the right Service based on the type.

We have $mainStage — the latest state that everyone should be updated to — and $openStage — the service we're going to open and update. We set it via setService, then call updateStage. If updateStage returns another step, the listener fires a new event for that step.

The Strategy — SalesProcessStrategy:

<?php

namespace Modules\Sales\Strategies\Classes;

use Modules\PreSales\Services\BoqService;
use Modules\Sales\Enums\SalesProcessStepEnum;
use Modules\PreSales\Services\QuotationService;
use Modules\Sales\Services\MaterialIssueService;
use Modules\Inventory\Services\GoodsReceiptService;
use Modules\Inventory\Services\MaterialReceiptService;
use Modules\SupplyChain\Services\PurchaseOrderService;
use Modules\Inventory\Services\MaterialDispatchService;
use Modules\PreSales\Services\SupplierQuotationService;
use Modules\SupplyChain\Services\PurchaseReceiptService;
use Modules\SupplyChain\Services\PurchaseRequestService;
use Modules\PreSales\Services\RequestForQuotationService;
use Modules\Sales\Strategies\Interface\SalesProccesInterface;

class SalesProcessStrategy
{
    private ?SalesProccesInterface $service = null;

    /**
     * Set the service based on the stage.
     */
    public function setService(SalesProcessStepEnum $stage): static
    {
        $this->service = match ($stage) {
            SalesProcessStepEnum::BOQ                => new BoqService(),
            SalesProcessStepEnum::PURCHASE_REQUEST   => new PurchaseRequestService(),
            SalesProcessStepEnum::RFQ                => new RequestForQuotationService(),
            SalesProcessStepEnum::SUPPLIER_QUOTATION => new SupplierQuotationService(),
            SalesProcessStepEnum::QUOTATION          => new QuotationService(),
            SalesProcessStepEnum::PURCHASE_ORDER     => new PurchaseOrderService(),
            SalesProcessStepEnum::PURCHASE_RECEIPT   => new PurchaseReceiptService(),
            SalesProcessStepEnum::MATERIAL_RECEIPT   => new MaterialReceiptService(),
            SalesProcessStepEnum::MATERIAL_ISSUE     => new MaterialIssueService(),
            SalesProcessStepEnum::MATERIAL_DISPATCH  => new MaterialDispatchService(),
            SalesProcessStepEnum::GOODS_RECEIPT      => new GoodsReceiptService(),
            default => null,
        };

        return $this;
    }

    /**
     * Update the stage.
     */
    public function updateStage(SalesProcessStepEnum $mainStage, SalesProcessStepEnum $openStage, array $data): mixed
    {
        if ($this->service === null) {
            throw new \InvalidArgumentException("No service resolved for stage: {$openStage}, main stage: {$mainStage}");
        }

        return $this->service->updateStage($mainStage, $openStage, $data);
    }
}

setService resolves the right Service based on the type and returns $this, which lets us use Method Chaining — a pattern used heavily in Laravel. Look it up, you'll love it, and it's part of the Builder Pattern.

The reason we typed the property as SalesProccesInterface is to enforce a contract. Think of it like going to a coffee shop and ordering coffee — you shouldn't get plain milk back. It might accidentally become a French coffee, but that's unexpected behavior. We prevent that by setting clear standards through an interface.

The Interface — SalesProccesInterface:


<?php

namespace Modules\Sales\Strategies\Interface;

use Modules\Sales\Enums\SalesProcessStepEnum;

interface SalesProccesInterface
{
    /*
     * Update the stage.
     */
    public function updateStage(SalesProcessStepEnum $mainStage, SalesProcessStepEnum $openStage, array $data): mixed;
    public function dispatchPreviousStage(SalesProcessStepEnum $mainStage, SalesProcessStepEnum $openStage, array $data): void;
}

BoqService:

<?php

namespace Modules\PreSales\Services;

use Modules\PreSales\Models\Boq;
use Modules\Sales\Enums\SalesProcessStepEnum;
use Modules\Inventory\Events\RegistrationItemCreatedEvent;
use Modules\Sales\Strategies\Interface\SalesProccesInterface;

class BoqService implements SalesProccesInterface 
{
    /**
     * Update the stage.
     */
    public function updateStage(SalesProcessStepEnum $mainStage, SalesProcessStepEnum $openStage, array $data): mixed
    {
        $boq = Boq::find($data['id']);
        if ($boq && SalesProcessStepEnum::upThanCurrent($boq->stage, $mainStage)) {
            $boq->update([
                'stage' => $mainStage,
            ]);
        }

        return null;
    }

    /**
     * Dispatch previous stage.
     */
    public function dispatchPreviousStage(SalesProcessStepEnum $mainStage, SalesProcessStepEnum $openStage, array $data): void {}
}

We update the BOQ only if two conditions are met: the BOQ exists, and upThanCurrent confirms the new stage is actually newer and higher. This matters because the BOQ might already be at final delivery stage,

then something goes wrong — a damaged shipment — and the client requests a new Purchase Order. In that case, the BOQ should stay as-is. We'd handle the exception separately in a Log, which is a topic for another day 🙂

dispatchPreviousStage is empty here because nothing comes before BOQ in this flow.

PurchaseRequestService:

<?php

namespace Modules\SupplyChain\Services;

use Modules\PreSales\Models\Boq;
use Modules\Sales\Events\SalesProcessEvent;
use Modules\Sales\Enums\SalesProcessStepEnum;
use Modules\SupplyChain\Models\PurchaseRequest;
use Modules\SupplyChain\Enums\PurchaseRequestTypeEnum;
use Modules\Sales\Strategies\Interface\SalesProccesInterface;

class PurchaseRequestService implements SalesProccesInterface
{


    /**
     * Create a new PurchaseRequest.
     *
     * @param array $data
     * @return \Modules\SupplyChain\Models\PurchaseRequest
     */
    public function store(array $data): PurchaseRequest
    {
        $purchaseRequest = PurchaseRequest::create($data);

        $this->syncPurchaseRequestItem($purchaseRequest, $data);

        $this->dispatchPreviousStage(SalesProcessStepEnum::PURCHASE_REQUEST, SalesProcessStepEnum::BOQ, [
            'id'   => $purchaseRequest->pull_id,
        ]);

        return $purchaseRequest->fresh();
    }

    /**
     * Update the stage.
     */
    public function updateStage(SalesProcessStepEnum $mainStage, SalesProcessStepEnum $openStage, array $data): mixed
    {
        $purchaseRequest = PurchaseRequest::find($data['id']);
        if ($purchaseRequest && SalesProcessStepEnum::upThanCurrent($purchaseRequest->stage, $mainStage)) {
            $purchaseRequest->update([
                'stage' => $mainStage,
            ]);
        }

        if ($purchaseRequest->type == PurchaseRequestTypeEnum::PROJECT) {
            return [
                'stage' => SalesProcessStepEnum::BOQ,
                'data' => [
                    'id'   => $purchaseRequest?->pull_id ?? null,
                ]
            ];
        }
        return null;
    }

    /**
     * Dispatch previous stage.
     */
    public function dispatchPreviousStage(SalesProcessStepEnum $mainStage, SalesProcessStepEnum $openStage, array $data): void
    {
        SalesProcessEvent::dispatch($mainStage, $openStage, $data);
    }
}

In store, dispatchPreviousStage fires immediately when a new record is created — it's the starting fire point. It says: my current stage is PURCHASE_REQUEST, the step before me is BOQ, here's its ID, go update it.

In updateStage, the service acts as a Consumer: it updates itself, then returns the previous step's data so the *Listener *knows there's another step to process and fires a new event for it. That's the recursion.

You might ask: why have both dispatchPreviousStage and updateStage? Because they serve different roles:

dispatchPreviousStage → fires on creation (the trigger point)
updateStage → fires as a consumer when receiving an event, updates itself, then returns the previous step to keep the chain going

This means each Service is simultaneously a Producer for the steps that precede it, and a Consumer for the events coming toward it — and it returns the previous step so the Broker can keep firing until we reach the zero point.

This is the simplified version. You could absolutely add DTOs for stronger type safety and more validation, and at that point you’d essentially have a Workflow Engine. I can’t share the full codebase since this is just a small piece inside an ERP system at my company.

Finally — I’m just your junior self-taught friend who’s trying to figure things out, so feedback is always welcome.

The idea is entirely my own with no AI involvement. I only used AI to fix spelling and grammar in this write-up — not in the workflow engine itself, not in the idea, not in anything else here.

Take care 👋