Coder Legion - Recent posts tagged laravel

How to Protect a Laravel App with a WAF Using a Placement Checklist

Thu, 22 Oct 2026 08:02:04 +0000

If you are looking up how to protect a Laravel app with a WAF, split the job before you change DNS. Laravel already owns validation, CSRF, authentication middleware, and authorization. A WAF owns the HTTP path in front of that code. The SafeLine documents used here do not describe a Laravel package, a PHP extension, or a framework connector. This is a go or no-go placement checklist: where the proxy sits, what you leave inside the framework, and which documented controls you enable only after staging. It is not a native integration guide.

What the sources actually support

SafeLine is a self-hosted WAF that protects web apps by filtering and monitoring HTTP traffic between a web application and the Internet. The product overview describes it as a reverse proxy. Clients pass through the WAF before they reach the server. It filters, monitors, and blocks malicious HTTP and HTTPS traffic, and it uses policies to decide what is malicious and what is safe. The same page says this is also meant to prevent unauthorized data from leaving the app. The application guide states that SafeLine is developed based on nginx, receives traffic for the original website, cleans malicious attack traffic, and forwards safe and reliable traffic to the original application. Those statements are general. They can cover a Laravel app because Laravel is served over HTTP, not because a Laravel mode is documented. Product overview: https://docs.waf.chaitin.com/en/home. Application proxy guide: https://docs.waf.chaitin.com/en/GetStarted/AddApplication.

Proxy record, DNS, and upstream

Confirm public names, ports, and the real app address before you cut over. In the SafeLine web console, the documented flow is to open Applications and add an application. Enter the domain, hostname, or IP of the original app. Enter the port SafeLine will listen on, such as 80 or 443, and check the SSL option for HTTPS apps. Enter the upstream, which is the real address SafeLine will use to forward traffic. Then resolve that domain to the IP of the server where SafeLine runs. If the name still points at the Laravel host, the WAF is not on the request path and none of its policies can act.

Keep the console and the application listener separate. The deploy guide uses a management port, with 9443 as the console example at https://<safeline-ip>:9443/, while the application guide uses the site port such as 80 or 443. Pointing public app DNS at the console port is not the documented way to protect the site.

What stays inside Laravel

Form requests, policies, signed URLs, sessions, and CSRF stay in the framework. A reverse proxy does not replace them. What the overview lists as attack coverage includes SQL injection, XSS, code injection, OS command injection, CRLF injection, LDAP injection, XPath injection, RCE, XXE, SSRF, path traversal, backdoor, brute force, HTTP flood, and bot abused, among others. Core capabilities on that page are defenses for web attacks, proactive bot abused defense, HTML and JS code encryption, IP-based rate limiting, and a web access control list.

Map those capabilities to routes only after a staging pass, and do not invent Laravel-specific rules that the sources do not publish. Rate limiting is documented as throttling traffic that exceeds defined limits, to defend against DoS attacks, brute-force attempts, traffic surges, and other abuse. That can matter for login and password-reset routes, but nothing here says the limiter reads Laravel throttle configuration. Captcha challenge is documented to allow human users and to block crawlers and bots. Authentication challenge, when turned on, requires visitors to enter a password, otherwise they are blocked. Dynamic protection, when turned on, dynamically encrypts HTML and JS on each visit. Test Blade responses, front-end assets, JSON API calls, uploads, and inbound webhooks before you enable those options on production. A web access control list is listed, but these sources do not publish a Laravel webhook exception recipe, so test callbacks instead of assuming an allow entry.

Host floor and proof

Check the host against the deploy guide before cutover: https://docs.waf.chaitin.com/en/GetStarted/Deploy. Requirements are Linux, x86_64 or arm64, Docker 20.10.14 or above, Docker Compose 2.0.0 or above, and at least 1 CPU core, 1 GB of memory, and 5 GB of disk. The CPU must support SSSE3. The guide states that SafeLine installed on ARM requires a Pro license to work properly and that the Personal Edition is not supported on ARM. It also states that the LTS version will no longer be maintained starting from 9.1.0-LTS on 14 August 2025, and it strongly recommends upgrading to the latest version. Those are infrastructure facts, not Laravel facts. A proxy you cannot run is not protection.

Prove the path with the tests the application guide already publishes. The sample cases cover SQL injection, XSS, path traversal, code injection, and XXE. Replace the sample host with your staging domain. A blocking page means SafeLine defended that request. Then open the console attack list and click detail. Also send ordinary traffic your app expects: a login, a form post, a static file, and a JSON call. HTTPS apps need the SSL option on the SafeLine listener. How Laravel records the client IP after an extra proxy hop is your application configuration. These sources do not document a Laravel trusted-proxy setting, so do not treat that as a SafeLine feature. If the origin remains reachable on a public address, clients can skip the proxy. Restrict that direct path only after the proxied staging path is proven.

The product page says SafeLine is production-ready, protecting over 1,000,000 websites and handling over 30,000,000,000 HTTP requests daily. Its published evaluation uses 33,669 samples and lists SafeLine Balance at 71.65 percent detection, 0.07 percent false positive, and 99.45 percent accuracy, and SafeLine Strict at 76.17 percent detection, 0.22 percent false positive, and 99.38 percent accuracy. Use those figures as published results from https://docs.waf.chaitin.com/en/home, not as a guarantee for your routes.

FAQ

Does SafeLine ship a Laravel package?

No. The install guide and the application guide describe a reverse proxy and a generic application record with domain, port, and upstream. They do not document an artisan command, a service provider, or a PHP extension. Protection means public traffic reaches SafeLine first and SafeLine forwards cleaned traffic to the Laravel upstream.

Which attack classes can I cite from the docs?

The overview names SQL injection, XSS, code injection, OS command injection, CRLF injection, LDAP injection, XPath injection, RCE, XXE, SSRF, path traversal, backdoor, brute force, HTTP flood, and bot abused, among others. Replay real application requests as well. A detection list is not a passing test suite for your routes.

Will IP rate limiting replace Laravel auth?

No. Rate limiting throttles traffic that exceeds defined limits and is described as a defense against DoS attacks, brute-force attempts, traffic surges, and other abuse. Login checks, authorization, and CSRF remain in Laravel. Captcha challenge and authentication challenge are separate documented options. Authentication challenge blocks visitors who do not enter the password.

What fails the host checklist?

A non-Linux host, an architecture other than x86_64 or arm64, Docker or Docker Compose below the stated versions, less than 1 GB of memory or 5 GB of disk, or a CPU without SSSE3. On ARM, the deploy guide requires a Pro license and states that the Personal Edition is not supported. An x86_64 trial does not prove an ARM host is licensed.

How do I know the WAF is actually in front?

The application domain must resolve to the SafeLine server. Documented attack samples against that domain should show the blocking page, and the console attack detail should record them. Normal logins, form posts, assets, and JSON calls should still succeed. If the Laravel origin is still open on a public address, the proxy can be bypassed.

As of September 30, 2026, SafeLine surpassed 700,000 installations worldwide. SafeLine Pro annual promotional pricing is $650-$880 versus the $1,000 regular price.

You are invited to inspect the project, read the deployment and application guides, and review the promotion before any production DNS change. Stand up a staging hostname, run the published probes, and keep Laravel validation and auth in place while you judge the proxy.

https://github.com/chaitin/SafeLine
https://docs.waf.chaitin.com/en/home
https://cyberserval.tech/landing/lto

How to Protect a Laravel App with a WAF Cutover Checklist

Thu, 22 Oct 2026 08:01:33 +0000

A Laravel app does not become protected just because a firewall product exists. The useful question is where the control sits, what traffic it can see, and how you prove the origin still works after the cutover. This guide is a decision checklist for that cutover. It does not promise a Laravel plugin, because the official SafeLine documents do not describe one.

SafeLine is a self-hosted web application firewall. The home documentation says it protects web apps by filtering and monitoring HTTP traffic between a web application and the Internet, and that a WAF placed in front of an application acts as a reverse-proxy shield: clients pass through the WAF before they reach the server (https://docs.waf.chaitin.com/en/home). The application guide adds that SafeLine is developed based on nginx, receives traffic for the original website, cleans malicious attack traffic, and forwards safe traffic to the original application (https://docs.waf.chaitin.com/en/GetStarted/AddApplication). That is the supported way to put it in front of Laravel. Point the proxy at the existing upstream. Do not look for a framework installer that those pages do not provide.

What belongs in the checklist

Start with the attacks you actually want filtered at the edge. The home page lists SQL injection, XSS, code injection, OS command injection, CRLF injection, LDAP injection, XPath injection, RCE, XXE, SSRF, path traversal, backdoor activity, brute force, HTTP flood, and bot abuse. Laravel routes that read query strings, form bodies, file paths, XML, or user-supplied URLs can meet several of those classes. Keep parameterized queries, authorization, and output encoding in the application. The outer filter does not retire them.

Next, choose controls that the product actually documents. Core capabilities on the home page are defenses for web attacks, proactive bot-abuse defense, HTML and JS code encryption, IP-based rate limiting, and a web access control list. The feature list also describes rate limiting for denial-of-service patterns, brute-force attempts, traffic surges, and other abuse; CAPTCHA challenges that allow human users while blocking crawlers and bots; an authentication challenge that requires a password or blocks the visitor; and dynamic protection that encrypts HTML and JS on each visit (https://docs.waf.chaitin.com/en/home). For a public Laravel site, web-attack blocking and rate limiting are the usual first pass. A password challenge can lock out customers. Dynamic encryption can interact badly with front-end assets, so test it on a copy of the site before you treat it as required.

Then check the machine, not the framework. The install guide requires Linux, x86_64 or arm64, Docker 20.10.14 or above, Docker Compose 2.0.0 or above, SSSE3, and a minimum of 1 CPU core, 1 GB of memory, and 5 GB of disk (https://docs.waf.chaitin.com/en/GetStarted/Deploy). The same guide states that SafeLine on ARM requires a Pro license and that the Personal Edition is not supported on ARM. It also states that the LTS version will no longer be maintained starting from 9.1.0-LTS (14 August 2025), and it strongly recommends that LTS users upgrade to the latest version. If your Laravel host fails any of those checks, fix the host before you edit DNS.

How the proxy record should look

Log into the web console, open Applications, and add an application. The documented fields are domain, port, and upstream. Domain can be a domain name, hostname, or IP address. Port is what SafeLine listens on, such as 80 or 443. For HTTPS apps, check the SSL option. Upstream is the real address of the original app, and SafeLine forwards traffic there (https://docs.waf.chaitin.com/en/GetStarted/AddApplication). After saving, resolve that domain to the SafeLine server. The Laravel process should remain the upstream, not a second copy of the WAF.

The console itself is separate from the site you are protecting. After installation, the guide says to open https://<safeline-ip>:9443/ and to obtain the initial administrator account with docker exec safeline-mgt resetadmin (https://docs.waf.chaitin.com/en/GetStarted/Deploy). Store that password outside the Laravel repository. Automated install is documented as a root-level command, and manual install writes configuration under a directory such as /data/safeline with at least 5 GB free. Those are deployment facts, not Laravel settings.

What to test before you call it protected

The application guide publishes probe URLs for SQL injection, XSS, path traversal, code injection, and XXE, and tells you to replace the example domain with your own. A blocking page means the defense stopped that request. Open the console attack list and click detail to confirm the event was recorded (https://docs.waf.chaitin.com/en/GetStarted/AddApplication). Run those probes only against an application you are allowed to test.

Then test the traffic you intend to allow. Submit a real login, a validation failure, a form that your users already use, and an API call that should succeed. A WAF that blocks a union-select probe but also blocks a legitimate POST is not finished. The documents do not publish a Laravel route map, so you have to supply that test list yourself.

Read published evaluation numbers as published numbers, then repeat the check on your own app. On 33,669 samples, the home page reports SafeLine Balance at 71.65 percent detection, 0.07 percent false positives, and 99.45 percent accuracy, and SafeLine Strict at 76.17 percent detection, 0.22 percent false positives, and 99.38 percent accuracy (https://docs.waf.chaitin.com/en/home). The same section says SafeLine is production-ready, with over 180,000 installations worldwide, protecting over 1,000,000 websites and handling over 30,000,000,000 HTTP requests daily. As of September 30, 2026, SafeLine surpassed 700,000 installations worldwide. SafeLine Pro annual promotional pricing is $650-$880 versus the $1,000 regular price. Neither the sample table nor the price range replaces a cutover test on your Laravel upstream.

If you later remove the proxy, the install guide says to enter the SafeLine directory, run docker compose down, and remove that directory only when you are sure you no longer want the data (https://docs.waf.chaitin.com/en/GetStarted/Deploy). Do that only after DNS no longer points clients at a stopped proxy.

Does SafeLine include a Laravel plugin or middleware?

No. The install and application documents describe a reverse proxy, a console, and an application record with domain, port, and upstream. They do not document a Laravel package. Protection means proxying the existing app, not importing a framework module.

Can application validation be removed after the WAF is live?

No. SafeLine filters and monitors HTTP traffic before the origin sees it. Laravel still needs authorization, validation, and safe database access. Treat the WAF as an outer layer in the checklist, not as a replacement for application controls.

Which documented controls should I enable first?

Use documented web-attack defenses first, and consider IP-based rate limiting if brute force, HTTP floods, or traffic surges are in scope. Add a CAPTCHA challenge when bot abuse is a real problem. Test the authentication challenge and HTML or JS dynamic protection before enabling them on a public Laravel site, because a password wall or encrypted page output can break ordinary visitors.

What proves the cutover worked?

Legitimate users and API clients still reach the upstream, HTTPS works if you checked the SSL option, and the documented attack probes against your own domain produce a block page that appears in the attack detail view. DNS should point at the SafeLine server only after those checks pass.

Is the minimum server size enough for every Laravel app?

The documented minimum is 1 core, 1 GB of memory, and 5 GB of disk, with Docker and SSSE3. That is a floor for installation, not a capacity guarantee. On ARM, the install guide says a Pro license is required and the Personal Edition is not supported.

If this checklist matches the way you want to protect the app, read the project and the official docs, then rehearse the proxy on a non-production name before you move real users. You are invited to compare the documented controls with your own routes and to keep the upstream test list next to the change. Official project: https://github.com/chaitin/SafeLine Official documentation: https://docs.waf.chaitin.com/en/home Install guide: https://docs.waf.chaitin.com/en/GetStarted/Deploy Application guide: https://docs.waf.chaitin.com/en/GetStarted/AddApplication Promotion: https://cyberserval.tech/landing/lto

A Clean Scan Is a Data Point, Not a Verdict: Lessons from PHP2Shell Week

Thu, 22 Oct 2026 05:13:41 +0000

PHP's two critical flaws, CVE-2026-109618 and CVE-2026-109619 (PHP2Shell), were patched in 8.5.12, 8.4.27, 8.3.36 and 8.2.35. The advice everywhere was to update. I want to write about something less covered: how much you can honestly claim afterwards.

The scan that found nothing

I ran Laravel Scalpel, an open source filesystem intrusion scanner, against three Laravel applications after updating. No backdoor files. My first instinct was relief. My second was to ask what that result actually rules out.

Why a negative result is weak evidence

A scan can only report on what it can see, and it can only recognise what it knows how to recognise. Scalpel looks at five things: PHP files in places they should not be, known obfuscation patterns, risky directives in .htaccess and .user.ini, the integrity of .env, and differences from a saved baseline. Each is a question it answers well. Anything outside them is a question it never asks. Coverage and sensitivity multiply, and if either is low, 'found nothing' tells you little.

There are at least two explanations for my result. My applications are small, which lowers the odds that anything needed to hide. Or something sits outside the questions above. A scanner inside the application also shares the web server's user, so a flaw that grants code execution in that process gives an attacker the means to tamper with the tool. I ran Scalpel from inside the application and through an external runner for that reason, which narrows the gap without closing it. My strongest evidence is not the scan but a routine that predates it: since April, a scheduled external diff against my baseline has reported to a Telegram bot. I refreshed the baseline myself after the update, so any unexpected change before that should already have alerted me, and none did. That evidence has conditions too: the runs must actually have happened in the window, and the alert level must cover what an attacker would change. Scalpel's documentation states the first limit plainly, and I would rather state all of them than have a reader discover them. From the output alone I cannot separate these cases.

A ladder of claims

It helped me to treat each check as supporting a different, specific statement:

Version verified: the PHP that serves web traffic is a fixed version, containers included. Supports: 'this flaw can no longer be used against us.'
Logs reviewed from 20 October: no repeated 500s or memory limit errors that look like probing. Supports: 'we saw no sign of attempts in these logs.'
Filesystem scan clean: no known backdoor patterns in the application files. Supports: 'we found no evidence of intrusion in these files.'
Secrets rotated: exposed credentials no longer work. Supports: 'even if memory was read, those secrets are dead.'
Rebuilt from a known good image: supports the only claim close to 'clean.'

Most of us stop at rungs one to three and announce we are fine. Only the last rung justifies that word.

Why the timing makes this sharper

The identifiers leaked about a day before the fix, and a security firm reported exploitation attempts shortly after release. For teams that patched hours or days later, the unprotected window was real, and a patch does nothing about what happened inside it.

What I would write in a post-patch note

Something like: 'Updated PHP on this date. Reviewed logs from 20 October. Scanned the application filesystem. Found no evidence of intrusion in those places. Rotated these secrets.' Each sentence is a claim you can defend, and the places you did not check are visible by omission.

I would be glad to hear what steps other teams include in their own post-patch verification.

Stripe Webhooks in Laravel: Verify, Dedupe and Retry Safely

Wed, 21 Oct 2026 00:02:45 +0000

If you take payments with Stripe, the money moving is only half the story. The other half arrives later as Stripe webhooks: messages that tell your app a payment succeeded, failed, was refunded or disputed. Handle them badly and you get customers who paid but have no access, double-processed orders, or a billing status that quietly drifts away from reality.

I build these integrations as part of API development and integrations work. This guide covers how to receive Stripe webhooks safely in Laravel: verifying them, ignoring duplicates, responding fast and recovering when something fails.

Why webhooks, not just the redirect after checkout

When a customer pays, Stripe sends them back to your site. It is tempting to mark the order paid at that moment. Don't rely on it. The customer can close the tab, lose connection or never reach your success page, and payments can also change state later (failed renewals, refunds, disputes).

Webhooks are the reliable channel. Your app should treat the webhook as the source of truth for payment state and the redirect only as a friendly "thanks" page.

The six rules for a safe webhook endpoint

1. Verify the signature

Anyone can send a request to your public URL. Stripe signs every event with a Stripe-Signature header, and you must verify it against your endpoint's signing secret before trusting the payload. Stripe's webhook documentation explains the scheme. Verification needs the raw request body, so read it before any middleware changes it.

use Stripe\Webhook;
use Stripe\Exception\SignatureVerificationException;

public function handle(Request $request)
{
    $payload = $request->getContent();           // raw body
    $signature = $request->header('Stripe-Signature');

    try {
        $event = Webhook::constructEvent(
            $payload,
            $signature,
            config('services.stripe.webhook_secret')
        );
    } catch (\UnexpectedValueException | SignatureVerificationException $e) {
        return response('Invalid', 400);
    }

    // ...store and queue the event
    return response('OK', 200);
}

Keep the signing secret in configuration, never in code, and use a separate secret per environment.

2. Exempt the route from CSRF, and only that route

Stripe is not a browser, so it cannot send a CSRF token. Exclude the webhook route from CSRF protection (in Laravel 11 and later this is done in bootstrap/app.php with validateCsrfTokens(except: [...])). Signature verification replaces CSRF protection for this one endpoint.

3. Respond fast, process later

Stripe expects a quick success response. If your handler does slow work, such as sending email, calling other APIs or updating several tables, the request may time out and Stripe will treat it as failed and retry. Do the minimum inside the request: verify, store, queue, return 200. Do the real work in a queued job, as described in my guide to Laravel queue architecture.

4. Deduplicate by event ID

Webhooks are delivered at least once, which means duplicates will happen. Every Stripe event has a unique id. Store it in a table with a unique index. If an insert fails because the ID already exists, you have already seen the event, so return 200 and do nothing. The same thinking applies to your own API endpoints, covered in API idempotency keys in Laravel.

5. Don't assume order

Events can arrive out of order. A "payment failed" event might land after a later "payment succeeded" event for the same invoice. Your handler should look at the current state in your database, and where the order matters, fetch the latest object from Stripe's API instead of trusting the sequence of events.

6. Make handlers safe to run twice

Even with deduplication, jobs can be retried. Write each handler so that running it twice leaves the same result: update by a stable key, use updateOrCreate, and check state before sending an email or granting access.

A reliable architecture

This is the shape I use:

Endpoint: verify the signature, insert the event into a stripe_events table (ID unique, payload, status), dispatch a job, return 200.
Job: load the stored event, run the handler for its type, and mark it processed. On failure, let the queue retry with backoff.
Handlers: one small class per event type you care about, such as invoice.paid, invoice.payment_failed, charge.refunded and checkout.session.completed.
Dead-letter view: a simple admin list of events that failed repeatedly, so a human can inspect and replay them.

Storing the raw event gives you an audit trail, and it lets you replay an event after fixing a bug instead of asking Stripe to resend it.

Which events to handle

Don't subscribe to everything. Start with the events that change what the customer can do or what you owe:

A checkout or payment completing successfully
A payment failing, so you can notify the customer and limit access if appropriate
Subscription updates and cancellations
Refunds and disputes

Fewer subscriptions mean less code to get wrong. Add more only when a feature needs them.

When Stripe can't reach you

If your endpoint returns an error or times out, Stripe retries the delivery over a period of time, with increasing gaps between attempts. You can also resend events from the Stripe dashboard. That safety net only helps if your endpoint is idempotent and your stored events show what happened. Add monitoring so you hear about a failing endpoint before customers do. My notes on observability for Laravel SaaS cover the alerts I set up.

Testing webhooks locally

Use the Stripe CLI to forward real test events to your local app and to trigger specific events on demand. Test these cases on purpose:

A valid event, an event with a bad signature and an event with a tampered body
The same event delivered twice
Events arriving out of order
A handler that throws an error halfway through
Your queue worker being stopped while events arrive

If all of these behave well in test mode, production will rarely surprise you.

Should you use Laravel Cashier?

If you are building standard subscriptions, Laravel Cashier already ships a webhook controller that verifies signatures and handles common subscription events. It is a good starting point, and you can extend it for your own events. For more custom flows, such as saving a card now and charging later, a hand-built handler gives you more control. My article on subscription billing architecture covers when each fits.

A real-world example

On the Stripe lead-billing project, I built a payment workflow that lets lead-generation clients save a payment method without an immediate charge, then automatically charges it when qualified leads are delivered. The status of successful and failed payments was kept in sync through webhook-driven updates. That is exactly the situation where trusting the webhook, not the browser, matters. Read the full Stripe lead billing case study.

Common mistakes to avoid

Parsing the JSON body before verifying the signature
Doing heavy work inside the webhook request
Treating the checkout redirect as proof of payment
Using one signing secret for test and live modes
Returning 500 for events you simply don't handle (return 200 and ignore them)
Having no way to see or replay failed events

Key takeaways

Webhooks, not redirects, are the source of truth for payment state.
Verify the signature, respond fast, then process in a queue.
Deduplicate on the event ID and make every handler safe to run twice.
Store raw events so you can audit and replay.
Monitor the endpoint and test failure cases before launch.

If you want a payment integration that stays correct when things go wrong, book a call and we can review your flow together.

Originally published at aqibjavaid.site.

I built a generic multi-step flow engine on top of Laravel controllers

Fri, 09 Oct 2026 11:33:27 +0000

If your mobile app decides which step comes next, your backend is trusting the client.

That's where we were at Zeney Pay. Sign-in, KYC and transfers were multi-step flows, and half of each flow's logic lived in the app. The backend couldn't tell whether a request to "check the PIN" came after 2FA had actually passed, unless someone remembered to write that check.

So we moved the whole state machine to the server:
→ every response tells the app which steps are legal next
→ skipping a step gets a 409, and an expired flow gets a 410
→ going back rewinds the flow and discards what came after
→ the app just renders whatever the backend advertises

I wrote up the original story on dev.to: the design decisions, how we handled authentication, and the trade-offs we accepted:

https://dev.to/na2axl/i-built-a-generic-multi-step-flow-engine-on-top-of-laravel-controllers-5f9k

I'll be happy to ear what you think!

How Much Can You Trust a Filesystem Baseline? Design Notes from Laravel Scalpel

Thu, 08 Oct 2026 04:44:43 +0000

A file hash only means something if you trust the moment it was recorded. That sounds obvious, but it is the part of integrity checking that people most often skip. Here are the design decisions behind the baseline feature in Laravel Scalpel, an open-source intrusion evidence scanner for Laravel. Scalpel is now at v1.11.0, and the trade-offs below came up repeatedly in issues and in an independent review by Laravel News.

What a baseline records

scalpel:baseline stores three things for each included file: its SHA-256 hash, its size, and its modification time. Later, scalpel:diff compares the live files against that record and reports files that were added, modified, or deleted.

php artisan scalpel:baseline
php artisan scalpel:diff

The idea is simple. Content scanners tell you whether a file looks suspicious. A baseline tells you whether a file changed, even if it looks perfectly normal. A backdoor hidden in a legitimate file will not match any pattern, but it will not match the old hash either.

Decision 1: what to leave out

A baseline that reports every log rotation is a baseline you will stop reading. By default, frequently changing paths such as logs, sessions, compiled views, and storage/app are excluded.

vendor/ gets different treatment. It is skipped by the content scanners, because scanning thousands of third-party files produces noise. But it stays in the baseline comparison. If someone drops a file into an installed package, you still see it in the diff.

Decision 2: strict or fast hashing

By default, Scalpel runs in strict mode and re-hashes every file on each comparison. That is the most reliable option and also the slowest.

The --fast option first compares size and modification time, and reuses the old hash when both match. It saves work, but it has a known blind spot: an attacker who edits a file and restores its original size and modification time can slip past the baseline comparison. Other scanners may still catch the file by its content or location, but the baseline alone will not.

A practical rule: use strict mode where the result matters, such as scheduled integrity checks, and --fast only where speed matters more, such as frequent local runs.

Decision 3: sign the baseline

If an attacker can rewrite the baseline, the diff becomes meaningless. Scalpel can HMAC-sign baselines and JSON reports when SCALPEL_SIGNING_ENABLED is true. The key goes in SCALPEL_SIGNING_KEY, and it should be a dedicated key, not your APP_KEY.

When signing is on, scalpel:diff verifies the baseline before using it. A missing or invalid signature is reported as CRITICAL. For saved JSON reports, scalpel:verify checks the signature.

Two details matter in practice. First, turn on signing before you create the first baseline, otherwise you have an unsigned record to start from. Second, signing has a clear limit: it detects a baseline regenerated without the key, but it cannot help if the attacker can read the key or modify the scanner itself.

Decision 4: when to refresh

A baseline is a record of a state you trust, so it has to be refreshed deliberately. The suggested flow after each deployment is to run php artisan optimize, then scalpel:baseline --force to replace the old record. Until a baseline exists, both scan and diff report a MEDIUM finding telling you to create one.

Never create a baseline on a server you suspect is already compromised. You would be recording the attacker's files as normal.

The trust boundary

All of this runs in the same process, with the same permissions, as your application. Anyone who can change your code can also change the scanner. So the strongest setup moves the trust boundary outside the app:

Trigger scans from outside the server, for example from CI or a scheduler on another machine.
Keep code directories read-only where possible.
Send reports and baselines to storage the server cannot write to.

A scanner like this detects evidence of an intrusion. It does not block or contain one.

Try it

composer require hryagstn/laravel-scalpel
php artisan vendor:publish --tag=scalpel-config

Requires PHP 8.2 or later and supports Laravel 10 to 13.

If you have a case where the baseline gives noisy or misleading results, please open an issue. I covered what the individual scanners look for in a separate post on DEV: https://dev.to/harryagustiana/what-a-filesystem-scan-can-and-cannot-tell-you-after-a-laravel-intrusion-1hn5

Source: https://github.com/hryagstn/laravel-scalpel

JSON vs MessagePack in Laravel: A Practical API Benchmark

Thu, 24 Sep 2026 13:39:50 +0000

JSON is the right default for most Laravel APIs. It is readable, supported everywhere, easy to debug, and familiar to every client.

MessagePack is worth considering when payload size, bandwidth, or a controlled client ecosystem matters. It is a compact binary format that keeps a schema-free data model, but it is not automatically faster or smaller for every workload.

This article compares both formats in a Laravel API and shows how to adopt MessagePack without breaking existing JSON clients.

The examples use Laravel Msgpack, an open-source package that adds opt-in MessagePack content negotiation, request decoding, safety limits, and a repeatable benchmark command.

The short answer

Use JSON when:

Your clients include browsers, third-party integrations, or unknown consumers.
Human-readable responses and simple debugging are important.
Your payloads are already small or compressed effectively.
You do not control the client decoder and deployment environment.

Use MessagePack when:

You control the clients and can ship a binary decoder.
Network transfer size is important for mobile, edge, or internal services.
Your payloads are large enough for serialization and decoding trade-offs to matter.
You want to keep JSON compatibility while allowing capable clients to opt in.

For many Laravel applications, the best answer is not choosing one format globally. Keep JSON as the default and negotiate MessagePack per request.

What are we comparing?

JSON is a text representation. It is self-describing, easy to inspect, and supported by the web platform.

MessagePack is a binary representation. It encodes the same basic data model using compact type markers and lengths instead of textual punctuation and names repeated in a text format.

The comparison should use the same data, the same PHP runtime, and the same operation count. Otherwise, the result is a benchmark of different workloads rather than a comparison of formats.

Add MessagePack to Laravel

Install the package:

composer require smmehdisharifi/laravel-msgpack

Apply the middleware to a route or route group:

use Illuminate\Support\Facades\Route;

Route::middleware('msgpack')->get('/api/profile', function () {
    return [
        'id' => 1042,
        'name' => 'Laravel MessagePack',
        'roles' => ['maintainer', 'developer'],
        'features' => [
            'negotiation' => true,
            'fallback' => 'json',
        ],
    ];
});

The route does not need separate JSON and MessagePack controllers. Existing clients continue to receive JSON:

curl -i http://localhost/api/profile

A capable client opts into MessagePack with the Accept header. Save the binary response instead of printing it as terminal text:

curl -sS -D - \
  -H 'Accept: application/msgpack' \
  -o profile.msgpack \
  http://localhost/api/profile

The negotiated response includes:

Content-Type: application/msgpack
Vary: Accept

Vary: Accept is important because a cache must not serve a MessagePack response to a client that asked for JSON, or the other way around.

How content negotiation works

The middleware keeps the migration opt-in:

A client that does not request MessagePack receives JSON.
A client that sends Accept: application/msgpack receives a binary response when the route supports the middleware.
If both formats are accepted, the higher quality factor wins.
Wildcards are evaluated by media-type specificity.
A request that rejects every supported representation receives 406 Not Acceptable.

The same negotiation applies to relevant error responses, including unmatched routes and route exceptions. Incoming requests can use application/msgpack or the legacy application/x-msgpack media type.

Run a repeatable benchmark

Laravel Msgpack includes an Artisan command so the comparison is easy to reproduce:

php artisan msgpack:benchmark --iterations=1000 --json

The command uses a deterministic API-shaped fixture with nested values and Unicode text. It measures:

Raw JSON and MessagePack byte size.
Encode time per iteration.
Decode time per iteration.
Optional gzip size and compression timings when ext-zlib is available.

The command warms each operation once before timing it. It reports per-iteration timings so runs with different iteration counts remain comparable.

Results from this package

The following result was produced by the package benchmark on PHP 8.4 with rybakit/msgpack 0.7.2 and 1,000 iterations:

Measurement	JSON	MessagePack	Difference
Raw payload	591 B	435 B	26.40% smaller
Encode time	0.002 ms	0.009 ms	JSON faster
Decode time	0.003 ms	0.008 ms	JSON faster
Gzip payload	377 B	371 B	1.59% smaller
Gzip compress time	0.009 ms	0.010 ms	Nearly equal
Gzip decompress time	0.004 ms	0.003 ms	Nearly equal

There are three useful conclusions here.

First, MessagePack is noticeably smaller before compression for this fixture. That can matter when transfer size is the bottleneck.

Second, the smallest representation is not automatically the fastest representation. For this small payload, JSON serialization is faster in the measured run.

Third, compression changes the size comparison. Once gzip is applied, the gap is much smaller because gzip already removes a lot of JSON's repetitive syntax.

These are indicative measurements, not universal promises. A real decision should use payloads, client runtimes, compression settings, and network conditions that match your application.

Decode MessagePack requests

MessagePack request bodies are decoded automatically when the middleware is applied:

use Illuminate\Http\Request;

Route::middleware('msgpack')->post('/api/profile', function (Request $request) {
    return [
        'received' => $request->msgpack(),
        'name' => $request->input('name'),
    ];
});

Map payloads are also merged into Laravel's normal request input. The original decoded value remains available through request()->msgpack(), including scalar and list payloads.

The package rejects malformed payloads before they reach the route handler. Configurable request size, nesting-depth, and value-count guards provide additional protection against oversized or unexpectedly deep input.

When a route must always return MessagePack

Negotiation is useful when the same endpoint serves different clients. For a route that should always return MessagePack, use the response macro:

return response()->msgpack([
    'message' => 'Created',
], 201, [
    'X-Request-Id' => $requestId,
]);

Direct serialization is also available through the facade:

use Msgpack;

$packed = Msgpack::encode($data);
$unpacked = Msgpack::decode($packed);

A practical decision guide

Do not change every endpoint to MessagePack because a synthetic benchmark produced a smaller payload. Instead, measure the part of the system that matters.

Choose JSON first when interoperability, browser support, observability, or simple debugging is the priority.

Test MessagePack when bandwidth, payload volume, or mobile transfer cost is important and the clients are controlled.

Keep both formats when you serve a mixed ecosystem. JSON remains the safe default, while clients that understand MessagePack can opt into it without a second controller implementation.

Limitations to keep in mind

MessagePack is not encryption. Sensitive data still needs transport security and application-level authorization.

Binary responses are less convenient to inspect in logs and command-line terminals. Save them to a file or decode them with a client library.

Compression may reduce the practical size advantage. Measure compressed and uncompressed responses for the transport configuration you actually deploy.

The benchmark fixture is intentionally stable, not universal. A list-heavy payload, a text-heavy payload, a large nested object, or a response with repeated keys can produce different results.

Try it in your project

Install Laravel Msgpack, apply the msgpack middleware to one endpoint, and compare both representations with your real data.

The repository contains the full implementation, compatibility matrix, configuration reference, safety limits, and benchmark command:

https://github.com/smmehdisharifi/laravel-msgpack

If the package helps your API, a GitHub star helps other Laravel developers discover it.

Building explainable duplicate detection in Laravel (no ML, no packages)

Mon, 21 Sep 2026 11:53:07 +0000

I built a rental listing platform with Laravel 13, PHP 8.4, PostgreSQL, Redis, and Sanctum.

One problem quickly became obvious:

Agents could post the same property multiple times.

In Nigeria, property listings often don't have precise street addresses. A typical listing might look like:

"2-bedroom flat, Yaba. Near Yaba Tech."

There may be no house number and sometimes no street name.

Instead, people identify properties using a combination of:

Area
Landmark
Property type
Number of bedrooms
Rent

That makes duplicate detection a little different from what you might build for a marketplace with structured addresses.

I wanted a solution that was:

Explainable
Easy to tune
Easy for reviewers to understand
Independent of machine learning
Cheap enough to run whenever a listing changes

So I built a rule-based duplicate detection system using Laravel and PHP.

The Architecture

The basic workflow is:

Property created/updated
        ↓
Find candidate properties
        ↓
Calculate similarity score
        ↓
Store score + explanation
        ↓
Classify match
        ↓
Reviewer confirms/rejects

The important distinction is that I don't compare every property against every other property.

Instead, I first narrow the candidate set using database queries and then perform the more expensive comparison in PHP.

1. Creating a Property Fingerprint

Because Nigerian rental listings don't always have reliable addresses, I needed another way to represent a property's identity.

I started with:

Area + Landmark + Bedrooms + Property Type

These fields are normalized and hashed into a fingerprint.

class PropertyFingerprintService
{
    public static function generate(array $data): string
    {
        $parts = [
            strtolower(trim($data['area'] ?? '')),
            strtolower(trim($data['landmark'] ?? '')),
            (string) ($data['bedrooms'] ?? ''),
            strtolower(trim($data['property_type'] ?? '')),
        ];

        return hash('sha256', implode('|', $parts));
    }
}

For example:

Yaba | Near Yaba Tech | 2 | Flat

becomes a deterministic SHA-256 hash.

This gives us a fast way to identify listings that have the same core identity fields.

An Important Database Lesson

Initially, I made the fingerprint column unique:

$table->string('fingerprint')->unique();

That turned out to be a mistake.

If an agent tried to create the same property again, the database rejected it.

That sounds useful until you remember the purpose of the feature.

I don't want the database to prevent the duplicate.

I want the duplicate to exist so that the platform can surface it for human review.

So I changed the migration to:

$table->dropUnique(['fingerprint']);
$table->index('fingerprint');

Now multiple properties can have the same fingerprint.

The database helps us find duplicates instead of blocking them.

That distinction is important for any system where duplicates are supposed to be reviewed rather than automatically rejected.

2. Candidate Selection

The next problem is scale.

Imagine the platform has 100,000 properties.

Comparing one new property against all 100,000 would obviously be wasteful.

Instead, I narrow the candidates using fields that are already indexed.

The query looks roughly like this:

public function findCandidates(Property $property): EloquentCollection
{
    return Property::query()
        ->where('id', '!=', $property->id)
        ->where(function ($query) use ($property) {
            $query->where('fingerprint', $property->fingerprint)
                ->orWhere(function ($inner) use ($property) {
                    $inner->where('area', $property->area)
                        ->where('bedrooms', $property->bedrooms);
                });

            if ($property->landmark) {
                $query->orWhere('landmark', $property->landmark);
            }
        })
        ->get();
}

The query looks simple, but there is an important Laravel detail here.

Group your `orWhere` clauses

The exclusion:

->where('id', '!=', $property->id)

needs to apply to every branch of the candidate query.

That's why the orWhere conditions are wrapped in a closure:

->where(function ($query) {
    // OR conditions
});

Without that grouping, you can accidentally generate logic equivalent to:

id != ?
AND fingerprint = ?
OR area = ?

The OR can escape the intended grouping and return the current property itself.

For queries with multiple OR conditions, explicit grouping is worth paying attention to.

3. Scoring the Candidates

Once I have a relatively small candidate set, I score each property against the new listing.

The scoring model is intentionally simple.

Signal	Points
Same area	25
Same landmark	20
Same bedrooms	15
Rent within 10%	20
Description similarity	20
Maximum	100

The goal isn't to produce a statistically perfect probability.

The goal is to produce a number that a reviewer can understand.

Keeping the Explanation

Before calculating the score, I create a details structure:

$details = [
    'area_match' => false,
    'landmark_match' => false,
    'bedrooms_match' => false,
    'rent_match' => null,
    'rent_difference_percent' => null,
    'description_similarity' => 0.0,
    'fingerprint_match' => false,
];

This is important because storing only:

confidence_score = 87

doesn't tell us much.

Instead, we can store:

{
    "area_match": true,
    "landmark_match": true,
    "bedrooms_match": true,
    "rent_match": "within_10_percent",
    "rent_difference_percent": 4.2,
    "description_similarity": 87.4,
    "fingerprint_match": false
}

Now the reviewer can understand why the system flagged the properties.

4. Comparing the Area

The area comparison is straightforward:

if (strcasecmp(trim($a->area), trim($b->area)) === 0) {
    $details['area_match'] = true;

    $points += self::WEIGHT_AREA;
}

With:

private const WEIGHT_AREA = 25;

5. Comparing Rent

Rent shouldn't need to be exactly the same.

Different agents might advertise the same property at slightly different prices.

For example:

Agent A: ₦1,500,000
Agent B: ₦1,550,000

These listings could still represent the same property.

So I calculate the percentage difference:

if ((float) $a->rent > 0 && (float) $b->rent > 0) {
    $diff = abs((float) $a->rent - (float) $b->rent)
        / max((float) $a->rent, (float) $b->rent);

    $details['rent_difference_percent'] = round($diff * 100, 2);

    if ($diff <= 0.10) {
        $details['rent_match'] = 'within_10_percent';

        $points += self::WEIGHT_RENT;
    } elseif ($diff <= 0.20) {
        $details['rent_match'] = 'within_20_percent';

        $points += self::WEIGHT_RENT / 2;
    }
}

So:

Within 10% → 20 points
Within 20% → 10 points
More than 20% → 0 points

This gives us a little tolerance without treating every price as equivalent.

6. Comparing Descriptions

For descriptions, I used PHP's built-in similar_text() rather than introducing another package.

similar_text(
    strtolower($a->description),
    strtolower($b->description),
    $sim
);

if ($sim >= 80) {
    $points += self::WEIGHT_DESCRIPTION;
} elseif ($sim >= 60) {
    $points += self::WEIGHT_DESCRIPTION / 2;
}

The thresholds are:

80%+ → 20 points
60–79% → 10 points
<60% → 0 points

This works reasonably well for short rental descriptions.

It is not intended to be a sophisticated natural-language similarity model.

And that's okay for this stage.

7. The Fingerprint Rule

A matching fingerprint is a strong signal:

Area
+
Landmark
+
Bedrooms
+
Property type

If those fields all match, I want the listing to be reviewed even if some other signals differ.

The final score is calculated like this:

$confidenceScore = round(min($points, 100), 2);

if ($details['fingerprint_match']) {
    $confidenceScore = max($confidenceScore, 90.0);
}

So a fingerprint match effectively creates a minimum score of 90.

That means the system classifies it as a very likely duplicate.

This is a deliberate product decision rather than a mathematical requirement.

Later, this should probably become configurable because two properties can theoretically share the same area, landmark, bedrooms and type while still being different properties.

8. Turning the Score Into a Match Level

I use an enum to map the score into a meaningful state:

public static function fromScore(float $score): self
{
    return match (true) {
        $score >= 90 => self::VERY_LIKELY,
        $score >= 70 => self::POSSIBLE,
        default      => self::UNIQUE,
    };
}

The resulting categories are:

Score	Level
90–100	Very likely
70–89	Possible
<70	Unique

The UI doesn't need to know how the score was calculated.

It simply displays the appropriate match level and the underlying explanation.

9. Persisting the Match Details

The score and explanation are stored on a duplicate_matches record.

For example:

property_id
matched_property_id
confidence_score
match_details
status

The match_details column is JSON.

That means I can store the complete scoring breakdown without creating a separate database column for every signal.

For example:

{
    "area_match": true,
    "landmark_match": true,
    "bedrooms_match": true,
    "rent_match": "within_10_percent",
    "rent_difference_percent": 4.2,
    "description_similarity": 87.4,
    "fingerprint_match": true
}

The reviewer UI can then display something like:

Very likely duplicate — 94

✓ Same area
✓ Same landmark
✓ Same bedrooms
✓ Rent within 10%
✓ Similar description
✓ Matching property fingerprint

That's much more useful than simply saying:

Duplicate confidence: 94%

10. Reviewer Decisions Must Survive Edits

There is another problem with running detection every time a property changes.

Suppose a reviewer sees:

Property A ↔ Property B

and decides:

These are different properties.

The reviewer rejects the match.

Then the agent edits the listing.

If detect() simply runs again and recreates the match, the reviewer gets the same warning again.

That's frustrating.

So duplicate matches have state:

pending
rejected
confirmed

When checking an existing match:

$existing = DuplicateMatch::query()
    ->where('property_id', $property->id)
    ->where('matched_property_id', $candidate->id)
    ->first();

if ($existing && $existing->status === 'rejected' && ! $rescan) {
    continue;
}

if ($existing && $existing->status === 'confirmed') {
    continue;
}

A rejected match stays rejected during normal edits.

A manual rescan can explicitly override that decision.

This makes the system behave more like a workflow rather than just a calculation.

11. Avoiding Timeline Noise

Duplicate detection can run frequently.

If every score recalculation creates a timeline event, the property history becomes noisy.

So I only log meaningful changes.

For example:

$scoreChanged = $existing
    && abs(
        (float) $existing->confidence_score
        - $score->confidenceScore
    ) >= 5;

A timeline event is created when:

A new match is detected
A manual rescan happens
The score changes significantly
A reviewer confirms/rejects a match

This keeps the audit trail useful.

12. Where Detection Runs

The detector runs after the property has been saved.

For example:

// PropertyCreator

$this->duplicateDetection->detect(
    $property,
    $user
);

And after an update:

// PropertyController@update

$this->duplicateDetection->detect(
    $property->fresh(),
    $user
);

This is also useful for bulk imports.

My .xlsx importer reuses the same property creation workflow.

That means imported properties automatically go through duplicate detection without implementing another version of the algorithm.

13. Testing the Detector

I didn't just test properties that I expected to be duplicates.

I created test spreadsheets containing both duplicates and controls.

Some examples:

Scenario	Score
Same fingerprint + cosmetic differences	100
Same area + different landmark + similar rent/description	80
Duplicate properties in one import	100
Same area but different size	25
Same area + bedrooms but different rent/description	40

The control cases are extremely important.

Without them, it's easy to keep increasing the number of signals until almost every property gets flagged.

A duplicate detector isn't useful if reviewers don't trust its results.

14. What I'd Fix Next

The current implementation works, but there are several areas I would improve.

Canonical Areas and Landmarks

Exact string matching creates problems:

Yaba

and:

Yaba, Lagos

are treated as different.

Similarly:

Opp. Yaba Tech

and:

Opposite Yaba Tech

are different strings.

A better approach would be a canonical area/landmark system with aliases.

For example:

Yaba
├── Yaba, Lagos
├── Yaba Lagos
└── Yaba Mainland

could all resolve to the same canonical identifier.

Case-Sensitive Candidate Queries

The scoring logic uses:

strcasecmp()

but the candidate query uses normal SQL equality.

That creates an inconsistency.

For example:

Yaba

and:

yaba

may score as a match but never become candidates in the first place.

With PostgreSQL, normalized columns or LOWER() expression indexes would make this more consistent.

Bedroom Type Casting

The database may return:

while another value might be:

"2"

If strict comparisons are used, those can behave differently.

Casting the model attribute is safer:

protected $casts = [
    'bedrooms' => 'integer',
];

Normalizing Match Pairs

Currently:

A → B

and:

B → A

can become separate records.

That means reviewers could potentially see the same duplicate pair twice.

A better approach is to normalize the IDs:

$firstId = min($property->id, $candidate->id);
$secondId = max($property->id, $candidate->id);

Then always store:

first_id
second_id

in a consistent order.

`similar_text()` Performance

PHP's similar_text() is convenient, but it isn't something I'd want to run against large amounts of text indefinitely.

For short rental descriptions, it's acceptable.

If descriptions become long or the candidate set grows significantly, I'd add a cheaper prefilter before running the similarity calculation.

The Fingerprint Floor

Currently:

if ($details['fingerprint_match']) {
    $confidenceScore = max($confidenceScore, 90);
}

This means matching identity fields can result in a duplicate score of 90 even when the rent is very different.

Sometimes that's correct.

Sometimes it isn't.

I'd eventually make the fingerprint floor configurable so product/operations can tune the behavior based on real reviewer decisions.

15. Why I Didn't Start With Machine Learning

There are three main reasons.

1. There wasn't enough training data

A new marketplace doesn't have thousands of confirmed duplicate/non-duplicate examples.

Without good labelled data, an ML model isn't automatically going to solve the problem.

2. Reviewers need explanations

If a reviewer asks:

"Why did you flag these two properties?"

I can answer:

"Same area, same landmark, same bedrooms, rent is 4.2% apart, and the descriptions are 87% similar."

That's actionable.

A black-box prediction isn't as useful for an operational workflow.

3. The weights are easy to change

The scoring weights are centralized:

private const WEIGHT_AREA = 25;
private const WEIGHT_LANDMARK = 20;
private const WEIGHT_BEDROOMS = 15;
private const WEIGHT_RENT = 20;
private const WEIGHT_DESCRIPTION = 20;

If reviewer feedback shows that one signal is too aggressive, I can tune it without introducing a new model-training pipeline.

The Bigger Lesson

The interesting part of this project wasn't really the scoring formula.

It was the workflow around it.

A useful duplicate detection system needs to answer more than:

"Are these two properties similar?"

It also needs to answer:

Why were they flagged?
What happens when a reviewer disagrees?
Does that decision survive future edits?
Can the reviewer rescan?
Can the match be confirmed?
Can the listings eventually be merged?
Can we audit what happened?
Can the scoring rules be changed later?

The detection algorithm is only one part of the feature.

The review workflow is what makes the detection useful in production.

Takeaways

If you're building duplicate detection for a marketplace, especially in a market without clean addresses:

Don't put a unique constraint on something humans are supposed to review.
Narrow candidates in SQL, then perform detailed scoring in application code.
Group your orWhere clauses carefully.
Store the explanation, not just the score.
Treat reviewer decisions as persistent state.
Test controls, not only the duplicates you want to catch.
Start with deterministic rules you can explain.
Use real reviewer decisions to improve the rules over time.

You don't always need machine learning to build useful marketplace intelligence.

Sometimes the best first version is a simple system that understands the signals your market actually has, produces a result people can explain, and gives humans the final say.

How to monitor and maintain Laravel apps for multiple clients

Sun, 06 Sep 2026 07:20:36 +0000

Forge and Vapor keep the stack alive. Front-end Core Web Vitals need a separate URL list, schedule, and alert path across every client app.

Laravel agencies often run a clean ops story and a messy front-end story at the same time. Forge or Vapor shows green deployments, queues drain, and uptime probes stay quiet, while PageSpeed Insights on the same client’s login and checkout routes still reports slow Largest Contentful Paint or sticky Interaction to Next Paint. That split is not a tooling failure. It is two different jobs under one “Laravel monitoring” label.

What follows is a practical playbook for monitoring and maintaining Laravel apps across multiple clients without pretending that application performance monitoring replaces Core Web Vitals coverage. We write from the agency side of that portfolio: shared packages, repeated Livewire patterns, and clients who expect both “the app is up” and “the pages feel fast.” The goal is a stack you can explain in a retainer meeting without collapsing three instruments into one vague promise.

What does monitoring Laravel for multiple clients actually include?

In practice the phrase covers three jobs. Mixing them in one Slack channel is how teams miss regressions for weeks. Naming the jobs in the retainer pack also reduces the chance that sales language oversells whatever tool the team already bought.

Job	Typical tools	Question it answers
Infrastructure and deployments	Laravel Forge, Vapor, server metrics, SSL expiry	Is the host healthy and is the release path working?
Application performance (APM)	Laravel-native APM, exception trackers, queue/job tracing	Which requests, queries, or jobs are slow or failing in production?
Front-end Core Web Vitals	PageSpeed Insights / Lighthouse lab, CrUX where available, scheduled portfolio checks	Do key browser URLs stay within lab and field budgets after deployments and content changes?

Forge and Vapor are built for infrastructure and deployments: hosts, release paths, SSL, and basic health. APM products are built for server timing, queries, and failed jobs. Neither automatically watches Largest Contentful Paint on /login, Cumulative Layout Shift on a marketing landing page that shares the same Blade layout, or Interaction to Next Paint on a Livewire-heavy dashboard. Those are document and interaction metrics measured in the browser, not PHP unit traces.

Agencies that only watch infrastructure and APM still get surprised when a shared Blade layout ships a heavier hero script and every client’s mobile lab score drops on the same Thursday.

How do Forge, Vapor, and APM differ from front-end PageSpeed budgets?

A useful split is by what each tool measures.

Ops checks care about deployment success, worker heartbeat, and HTTP 200 on a health endpoint. APM checks care about server timing, query count, and exception rates. PageSpeed checks care about what Chrome paints and responds to on named URLs, on mobile and desktop, with lab runs you can schedule and field data Google publishes when the URL qualifies for CrUX.

A Vapor environment can be perfectly healthy while a client’s authenticated dashboard still ships a megabyte of JavaScript on first paint. An APM flame graph can look calm while a cookie banner collapses after load and field Cumulative Layout Shift goes amber. Those are not contradictions. They are different instruments.

For a portfolio of Laravel clients, reporting stays clearer when those jobs stay separate:

Ops / APM: “Is the application reliable?”
Front-end budgets: “Are the checkout and login URLs still acceptable for users and Search Console?”

If the monthly pack only covers reliability, clients often hear “we monitor Laravel” and assume Core Web Vitals are covered. They are not. Both answers in the same retainer pack keep the language aligned with the instruments you actually run.

Which URLs belong on a Laravel Core Web Vitals list?

A homepage-only list rarely covers Laravel apps that sell, book, or administer work. A short, stack-agnostic set of route classes tends to survive theme and package churn better; concrete paths can then be filled per client so the schedule still makes sense after a redesign.

Public marketing or landing URL that shares the app’s Blade layout (often the sales site or / on the same domain).
Authentication entry (/login, /register, SSO start) where fonts, Alpine/Livewire boot, and third-party widgets collide.
Primary authenticated shell (dashboard home, “today” view, or first screen after login).
Checkout or conversion URL (checkout, booking confirm, quote submit, subscription upgrade) even if it sits behind auth.
One high-traffic content or catalogue URL if the app mixes editorial or product listing with the Laravel stack.

Ten carefully chosen URLs usually beat fifty forgotten ones. Mobile and desktop often deserve separate entries when the authenticated shell is a different layout on phone.

When discovery and scheduling run across many hosts, that short list works well as the seed set to protect after sitemap crawl adds noise. Utility routes and pagination URLs will dilute the budget list if every discovered path is accepted. We walk through that multi-site setup pattern in How to Set Up Automated PageSpeed Monitoring for Multiple Sites.

Why do shared Laravel components regress every client at once?

Multi-client Laravel work rarely means twenty unrelated codebases. Agencies reuse private packages, a house Blade kit, Livewire components, Spatie packages, Filament resources, or a shared Vite build. That reuse is good for maintenance until a single merge changes paint cost for every client that shares the kit.

Shared pieces that often move together:

Layout Blade that injects analytics, chat, or A/B scripts on every response.
Livewire / Alpine widgets that hydrate large tables on the dashboard home.
Font and CSS pipelines shared through a design package.
Third-party tags added once in a layout and inherited by every client fork.
Image and media helpers that resize differently after a package bump.

When the regression is shared, APM may still look fine (PHP time unchanged) while Largest Contentful Paint and Interaction to Next Paint move together on every client that pulled the package. Front-end checks on the same URL classes across clients make one bad package release read as a portfolio event, not five unrelated tickets. That is how the shared-kit advantage stays useful without turning every package bump into a surprise client call.

When is scheduled PageSpeed enough, and when do you still need APM?

Scheduled PageSpeed (lab) plus field context where CrUX exists fits when the question is user-visible speed on known URLs after deployments, content edits, or tag-manager changes. That coverage answers client questions about Search Console Core Web Vitals and “why does the dashboard feel heavy on mobile.” It is also the evidence pack you can put next to a release note without opening Forge.

APM and exception monitoring still matter when the question is slow endpoints, failing jobs, N+1 queries, or memory spikes. Those bugs do not always show up as Lighthouse Performance score changes, and Lighthouse will not tell you which queue worker stalled overnight. The tools are complementary rather than competing line items on the invoice.

A durable agency stack for Laravel portfolios often has three layers:

Hosting / Forge / Vapor for deployments and basic health.
APM / errors for application internals.
Scheduled multi-site PageSpeed for front-end budgets and client-facing evidence.

Skipping layer three is common when the team’s identity is “Laravel shop.” Skipping layer two is common when the team’s identity is “SEO shop.” Clients feel both gaps.

Where does a multi-tenant PageSpeed tool fit for Laravel agencies?

If you already open five PageSpeed tabs per client after every release, the gap is rarely another lecture on why manual checks fail. It is usually one place to keep organisations separate, attach the URL classes above, run schedules, and see which client site needs attention this week. That is operational maintenance, not a new ideology about Laravel.

That is the job of a multi-tenant PageSpeed portfolio tool, not a replacement for Forge or for Laravel APM. We built Apogee Watcher for that front-end layer: scheduled PageSpeed Insights across many client sites, discovery when routes appear, and a dashboard shaped for agency roles. The product spotlight on managing multiple client sites in one dashboard shows how that dashboard differs from a flat project list.

Honest limits matter on Hashnode as much as on our own blog. Watcher does not replace Telescope, Nightwatch-class APM, or Forge server graphs. It holds front-end evidence so Laravel agencies can maintain many apps without pretending ops green equals Core Web Vitals green.

FAQ

Does Laravel Forge monitoring cover Core Web Vitals?
No. Forge watches servers, deployments, and related ops signals. Core Web Vitals are measured on browser navigations to specific URLs. Lab and field coverage for those URLs still sits outside Forge.

Should every Laravel client get the same URL list?
The same classes work well across clients (login, authenticated shell, checkout or conversion URL, public landing). Concrete paths still differ per app. A Filament admin and a Jetstream consumer app will not share identical routes.

Is Lighthouse CI enough for a multi-client book?
Lighthouse CI is strong in the pipeline for apps you control end to end. Agency portfolios still benefit from scheduled production checks when not every client sits on the same CI project, and when marketing tags change outside your repository.

Can APM replace PageSpeed Insights for client reporting?
Not for Search Console or for “how fast does this page feel in Chrome.” APM explains server work. PageSpeed Insights and CrUX explain what users experience on the document.

What is a sensible first alert set across Laravel clients?
Budget breaches on the authenticated shell and the checkout or conversion URL on mobile usually catch shared layout and script regressions before a homepage-only check does.

CTA

If you maintain several Laravel apps for clients, a useful next step is to sketch the three-layer stack on one page: ops, APM, and front-end URL budgets. Seeding the Core Web Vitals list from the classes above, putting it on a schedule, and treating shared package releases as portfolio events usually closes the gap faster than another round of ad-hoc PageSpeed Insights tabs. When you want that front-end layer in one multi-tenant product, try Apogee Watcher or read how we set up automated PageSpeed monitoring for multiple sites.

References

Laravel Forge documentation (Laravel)
Laravel Vapor documentation (Laravel)
About PageSpeed Insights (Google)
Optimize Largest Contentful Paint (web.dev)
Optimize Interaction to Next Paint (web.dev)
How to Set Up Automated PageSpeed Monitoring for Multiple Sites (Apogee Watcher)
Product Spotlight: Managing Multiple Client Sites in One Dashboard (Apogee Watcher)

Originally published on Hashnode.

The Issues of Deploying Laravel on Dokploy: Database Connection Hell

Mon, 03 Aug 2026 07:41:12 +0000

If you’ve tried deploying a Laravel application on Dokploy (the self-hosted Heroku alternative built on Docker) and immediately ran into a wall of Database connection refused or SQLSTATE[HY000] [2002] errors, you are not alone.

It works perfectly on your local machine, but the moment it hits the server, it falls apart. Here is a real-world breakdown of the database connectivity issues we experienced, why they happened, and how to fix them.

1. The "Localhost" Trap (The `127.0.0.1` Connection Refused)

The Issue

On your local computer, you probably set your .env to:

DB_HOST=127.0.0.1
DB_PORT=3306

When you deploy this to Dokploy, your Laravel application crashes on start because it cannot connect to the database.

The Reason

Dokploy runs everything in isolated Docker Containers.
Inside a container, 127.0.0.1 or localhost refers to the Laravel container itself, not the host machine or your database container. Since there is no database running inside your Laravel code container, it refuses the connection.

The Solution

You must use Docker's internal networking.

If your database is created inside Dokploy, Dokploy assigns it a specific network service name (e.g. dokploy-db-mysql or the service name you typed in the database creation wizard).
Change your host in the Dokploy Environment Variables UI to match that service name:
```
DB_HOST=dokploy-db-mysql  # Use Dokploy's internal container name
```

2. The Config Caching Nightmare (Why changing Env Variables in the UI did nothing)

The Issue

You realized the host was wrong, went to the Dokploy dashboard, updated the DB_HOST environment variable to the correct container hostname, saved, and redeployed.
Yet, the app still threw the old connection error looking for 127.0.0.1. You checked the container logs, confirmed the new environment variables were set, but Laravel simply ignored them.

The Reason

This happens if you run configuration caching in your Dockerfile during the build step:

RUN php artisan config:cache

When Laravel builds your container, it runs config:cache and bakes whatever .env values exist at build-time directly into a static cache file (bootstrap/cache/config.php).
At runtime, Laravel completely ignores your Dokploy UI environment variables and loads the baked-in values instead.

The Solution

Never cache your configuration during the Docker build stage if you plan to change environment variables dynamically.

Remove RUN php artisan config:cache from your build steps.
If you want caching for speed in production, clear it on boot by running php artisan config:clear or php artisan optimize:clear inside your container's startup command / entrypoint script.

3. The Race Condition (Migrations crashing the build)

The Issue

You configured your Docker container to automatically run migrations on deployment:

php artisan migrate --force

But your deployment failed during this step because the database connection timed out or was refused, even though all credentials were 100% correct.

The Reason

When Dokploy restarts or provisions your stack, it starts both the Laravel container and the MySQL/PostgreSQL container simultaneously.
Laravel boots up in milliseconds and immediately tries to run migrations. However, MySQL is still executing its slow initial setup scripts, checking schemas, and opening sockets. The database container isn't ready to receive queries yet, so Laravel's migration command crashes, failing the entire Dokploy deployment.

The Solution

You need to make Laravel "wait" for the database to boot. Add a small bash loop to your entrypoint script (entrypoint.sh) that pings the database port before running migrations:

echo "Waiting for MySQL to boot..."
until nc -z -v -w30 $DB_HOST $DB_PORT; do
  echo "MySQL is not ready yet. Retrying in 2 seconds..."
  sleep 2
done
echo "MySQL is up! Running migrations..."
php artisan migrate --force

4. Port Mapping Confusion (Internal vs. External Ports)

The Issue

Mapping your Dokploy MySQL database port to 3306 (or 3307) externally so you could connect via TablePlus/DBeaver from your laptop, but when configuring your Laravel .env inside Dokploy, you weren't sure which port to use.

The Reason

Docker has two layers of ports:

Internal Port: The port the service listens to inside the Docker private network (always 3306 for MySQL).
External/Exposed Port: The port mapped to the public server IP so you can connect from the outside world (e.g., mapping host 3307 to container 3306).

Inside Dokploy, your Laravel app and your MySQL container share the same private network. Therefore, they communicate internally.

The Solution

For Laravel (.env on Dokploy): Always use the internal port (DB_PORT=3306).
For TablePlus/DBeaver (External laptop): Use the exposed host port (3307) and the public server IP.

Summary Checklist for Dokploy deployments

Set DB_HOST to the internal Docker container/service name, not 127.0.0.1.
Set DB_PORT to the internal port (3306 for MySQL), not the exposed host port.
Avoid running php artisan config:cache during Docker build time.
Implement a wait-for-it check in your startup script so migrations don't run before MySQL is fully booted.

Stop Slow Laravel: Your Next Architectural Leap Is Here!

Wed, 01 Jul 2026 06:34:24 +0000

Stop Slow Laravel: Your Next Architectural Leap Is Here!

Introduction

It’s 2026, and the landscape of web development has evolved dramatically. If your Laravel applications are still relying on traditional PHP-FPM for request handling, you might be leaving significant performance on the table. The conversation around application speed has moved beyond mere query optimization; it’s an architectural paradigm shift. Enter Laravel Octane, a powerful package that integrates your Laravel application with high-performance application servers like RoadRunner or Swoole. This isn’t just about making PHP “faster”; it’s about fundamentally transforming how your application processes requests, ushering in an era of unprecedented throughput, reduced latency, and blazing-fast API responses. Octane transitions your application from a stateless, “boot-on-every-request” model to a persistent, long-running process, eliminating the costly framework bootstrap for each incoming call.

Code Layout and Architectural Walkthrough

Embracing Laravel Octane demands a shift in mindset, particularly regarding application state. Let’s walk through the essential steps and considerations to integrate Octane into your project.

1. Installation and Setup: Getting started with Octane is straightforward. You first install the package via Composer:

composer require laravel/octane

Next, you’ll install Octane into your application, choosing your preferred server driver (RoadRunner or Swoole). RoadRunner is often simpler to get started with due to fewer external dependencies for many environments.

php artisan octane:install

This command publishes the config/octane.php configuration file, which allows you to fine-tune settings like the number of worker processes, maximum requests per worker before restarting, and more.

2. The Persistent Server Model: Unlike FPM, which reboots your entire application for every request, Octane leverages a persistent application server. When you run php artisan octane:start, a dedicated server process (RoadRunner or Swoole) is launched. This server loads your Laravel application once, keeping it in memory. Subsequent requests are then routed to this already-booted application instance. This fundamentally eliminates the overhead of bootstrapping the framework on every single request, leading to dramatic performance improvements.

3. Embracing the Stateful Mindset: This is the most critical aspect of adopting Octane. Because your application remains loaded in memory between requests, global state can persist, leading to unexpected behavior if not managed carefully. Key areas to monitor:

Static Properties & Global Variables: Any data stored in static properties or global variables will persist across requests. This can lead to data leaks or incorrect behavior if not reset.
Service Container Bindings: While Octane intelligently resets many core framework services, custom singleton bindings in your service container might retain state.
Opened Resources: Database connections, file handles, or network sockets that are not properly closed might accumulate or become stale.

Octane’s Mitigation Strategies: Octane provides powerful hooks to manage state:

Octane::onRequest: You can register callbacks to be executed at the beginning of each request. This is ideal for manually resetting any custom global state or re-binding services if necessary.

use Laravel\Octane\Facades\Octane;

Octane::onRequest(function ($request, $app) {
    // Clear any custom static caches
    MyCustomService::$cache = [];
    // Rebind specific service if it holds request-specific state
    $app->bind(SomeService::class, fn () => new SomeService());
});

Octane::onWorkerStopping: This hook can be used for cleanup tasks when a worker process is gracefully shutting down.
Automatic Resetting: Octane intelligently resets many core Laravel components, such as request input, session data, authentication state, and even clears resolved instances from the service container (unless explicitly configured otherwise).

For most well-architected Laravel applications that rely heavily on dependency injection and avoid excessive global state, the transition is smoother than anticipated. Focus on ensuring your services and controllers are stateless or properly reset if they must hold state.

Conclusion

Adopting Laravel Octane is no longer an edge-case optimization for the ultra-high-traffic elite; it’s becoming the baseline for modern, efficient Laravel applications. The architectural shift to a persistent application server, powered by RoadRunner or Swoole, fundamentally redefines performance. By eliminating per-request framework bootstrapping, Octane delivers 10x throughput, significantly reduced latency, and an incredibly responsive user experience. While it demands a careful consideration of application state, the performance gains and competitive advantage it provides are immense. Stop leaving raw performance on the table. Embrace Octane today and position your Laravel applications for peak efficiency and future success.

Your Laravel Isn’t Slow, Your Architecture Is.

Fri, 26 Jun 2026 13:35:52 +0000

Your Laravel Isn’t Slow, Your Architecture Is: Mastering Scale with Advanced Octane & Reactive Caching

Introduction

If your Laravel API is struggling under heavy load, the instinct is often to dive deep into optimizing Eloquent queries or micro-tweaking individual lines of code. While performance profiling remains crucial, this approach often addresses symptoms, not the root cause. The real bottleneck in high-traffic Laravel deployments isn’t typically the framework itself; it’s the architectural paradigm. We need to shift our focus from optimizing individual operations to optimizing the flow and state of our application. This tutorial will guide you through two advanced strategies – leveraging Octane’s asynchronous capabilities and implementing a reactive caching strategy with Redis Streams – to unlock sustained low-latency throughput that transforms your Laravel application into a true high-performance powerhouse.

Code Layout & Architectural Walkthrough

Moving beyond basic Swoole or RoadRunner setups, we’re talking about a paradigm shift that integrates background processing directly into the request flow and introduces real-time cache invalidation.

1. Octane’s Asynchronous Power: Non-Blocking Operations

The key here is to release the HTTP response before non-critical operations complete, leveraging Octane’s persistent application state. Laravel’s dispatchAfterResponse() is the starting point, but we’ll integrate it with custom Octane bootloader hooks to ensure robust, non-blocking execution.

Conceptual Implementation:

Custom Octane Bootloader: Create a service provider that registers Octane worker lifecycle hooks. This allows you to perform setup and teardown tasks for each worker process, ensuring resources are ready.

// app/Providers/OctaneServiceProvider.php
namespace App\Providers;

use Illuminate\Support\Facades\Octane;
use Illuminate\Support\ServiceProvider;

class OctaneServiceProvider extends ServiceProvider
{
    public function boot()
    {
        Octane::onWorkerStart(function () {
            // Perform expensive, one-time worker setup here
            // e.g., warm up a complex service container dependency
        });

        Octane::onWorkerError(function (Throwable $e) {
            // Log or handle worker errors gracefully
        });

        // Consider Octane::onWorkerStop for cleanup if necessary
    }
}

Asynchronous Dispatch in Controllers/Services: In your critical API endpoints, identify operations that don’t strictly need to block the user’s response (e.g., audit logging, sending non-critical notifications, syncing data to a third-party service).

// app/Http/Controllers/OrderController.php
namespace App\Http\Controllers;

use App\Jobs\ProcessAuditLog;
use App\Jobs\SyncOrderToCRM;
use Illuminate\Http\Request;
use Illuminate\Routing\Controller;

class OrderController extends Controller
{
    public function store(Request $request)
    {
        // ... (Validate request, create order, etc.) ...
        $order = Order::create($request->all());

        // Dispatch non-critical jobs to the queue *after* response is sent
        // This leverages Octane's persistent connections without blocking the user.
        ProcessAuditLog::dispatch($order->id, 'Order Created')->afterResponse();
        SyncOrderToCRM::dispatch($order)->afterResponse();

        return response()->json(['message' => 'Order created successfully!', 'order_id' => $order->id], 201);
    }
}

By using ->afterResponse(), Laravel ensures these jobs are pushed to your configured queue (e.g., Redis, database) only after the HTTP response has been fully sent to the client. Octane’s persistent workers ensure that the queue workers are readily available and efficient, minimizing latency overhead for job dispatching.

2. Reactive Caching with Redis Streams for Real-time Invalidation

Simple TTL-based caching often leads to stale data or necessitates aggressive, short TTLs that negate performance benefits. A reactive caching strategy uses Redis Streams to broadcast data changes and trigger real-time invalidation across your data layer.

Conceptual Implementation:

Publisher (Model Event Listener): Whenever a critical data model is updated, deleted, or created, an event is published to a Redis Stream.

// app/Providers/AppServiceProvider.php (or a dedicated EventServiceProvider)
namespace App\Providers;

use App\Models\Product;
use App\Services\CacheInvalidationService;
use Illuminate\Support\ServiceProvider;

class AppServiceProvider extends ServiceProvider
{
    public function boot(CacheInvalidationService $cacheInvalidationService)
    {
        Product::created(fn (Product $product) => $cacheInvalidationService->publish('product_updated', $product->id));
        Product::updated(fn (Product $product) => $cacheInvalidationService->publish('product_updated', $product->id));
        Product::deleted(fn (Product $product) => $cacheInvalidationService->publish('product_deleted', $product->id));
    }
}

// app/Services/CacheInvalidationService.php
namespace App\Services;

use Illuminate\Support\Facades\Redis;

class CacheInvalidationService
{
    protected string $streamKey = 'cache_invalidation_stream';

    public function publish(string $event, int $entityId, array $data = []): void
    {
        Redis::xadd($this->streamKey, '*', [
            'event' => $event,
            'entity_id' => $entityId,
            'timestamp' => now()->timestamp,
            'data' => json_encode($data),
        ]);
    }
}

Consumer (Queue Worker/Octane Worker): A dedicated listener consumes this Redis Stream. Upon receiving an event, it knows exactly which cache keys (for complex objects or query results) need to be invalidated.

// app/Jobs/ProcessCacheInvalidationStream.php (a long-running Octane-aware consumer)
namespace App\Jobs;

use App\Services\CacheManagerService; // Manages complex cache keys
use Illuminate\Bus\Queueable;
use Illuminate\Contracts\Queue\ShouldQueue;
use Illuminate\Foundation\Bus\Dispatchable;
use Illuminate\Queue\InteractsWithQueue;
use Illuminate\Queue\SerializesModels;
use Illuminate\Support\Facades\Redis;
use Illuminate\Support\Facades\Log;

class ProcessCacheInvalidationStream implements ShouldQueue
{
    use Dispatchable, InteractsWithQueue, Queueable, SerializesModels;

    public function handle(CacheManagerService $cacheManagerService): void
    {
        $streamKey = 'cache_invalidation_stream';
        $consumerGroup = 'cache_invalidator_group';
        $consumerName = gethostname() . '-' . uniqid(); // Unique consumer name

        // Create consumer group if it doesn't exist
        try {
            Redis::xgroup('CREATE', $streamKey, $consumerGroup, '$', 'MKSTREAM');
        } catch (\Exception $e) {
            // Group likely already exists
        }

        // Continuously read from the stream
        while (true) {
            $messages = Redis::xreadgroup('GROUP', $consumerGroup, $consumerName, 'BLOCK', 10000, 'COUNT', 10, 'STREAMS', $streamKey, '>');

            if (!empty($messages[$streamKey])) {
                foreach ($messages[$streamKey] as $id => $message) {
                    $event = $message['event'];
                    $entityId = (int<span cl

How to Build a Multi-Department Approval Workflow in Laravel

Mon, 22 Jun 2026 12:50:47 +0000

TL;DR: Step-by-step guide to building a multi-department approval workflow in Laravel with database-driven routing, Events, and role-based access. Code included.

Introduction
One of the most common problems I saw while building VMMS was this: documents get created, emailed to the next department, sit in someone's inbox for days, and when management asks "where's that voucher?" — nobody knows.
In this article I'll walk you through how I built a flexible multi-department approval workflow in Laravel that solves exactly this problem.

The Core Concept
Instead of hardcoding approval steps, I built a pipeline where each document has a current stage, and the next stage is determined by a department configuration stored in the database — not in the code.
This means you can add, remove, or reorder departments without touching a single line of PHP.

Database Structure
Here are the key tables:

// vouchers table
Schema::create('vouchers', function (Blueprint $table) {
    $table->id();
    $table->string('title');
    $table->foreignId('current_department_id')->constrained('departments');
    $table->enum('status', ['ongoing', 'accomplished', 'rejected']);
    $table->timestamps();
});

// departments table
Schema::create('departments', function (Blueprint $table) {
    $table->id();
    $table->string('name');
    $table->integer('order'); // determines routing sequence
    $table->timestamps();
});

Routing Logic
When a staff member approves a voucher, it automatically moves to the next department based on the order column:

public function approve(Voucher $voucher)
{
    $currentOrder = $voucher->department->order;

    $nextDepartment = Department::where('order', '>', $currentOrder)
        ->orderBy('order')
        ->first();

    if ($nextDepartment) {
        $voucher->update([
            'current_department_id' => $nextDepartment->id,
            'status' => 'ongoing'
        ]);
    } else {
        // No more departments — voucher is complete
        $voucher->update(['status' => 'accomplished']);
    }

    // Fire event for email notification
    event(new VoucherAdvanced($voucher));
}

Email Notifications
I used Laravel Events and Listeners to trigger email notifications every time a voucher moves to the next stage:

// VoucherAdvanced Event
class VoucherAdvanced
{
    use Dispatchable, InteractsWithSockets, SerializesModels;

    public function __construct(public Voucher $voucher) {}
}

// Listener
class SendVoucherNotification implements ShouldQueue
{
    public function handle(VoucherAdvanced $event): void
    {
        $voucher = $event->voucher;
        $staff = $voucher->department->staff;

        foreach ($staff as $member) {
            Mail::to($member->email)->send(new VoucherNotification($voucher));
        }
    }
}

Role-Based Access
Each department only sees vouchers assigned to them using Laravel Policies:

public function view(User $user, Voucher $voucher): bool
{
    return $user->department_id === $voucher->current_department_id
        || $user->role === 'admin';
}

Real-Time Pipeline Tracker
To show users where a voucher is in real time, I built a simple status tracker on the Vue 3 frontend that reads the current department and renders it as a progress indicator — no websockets needed, just a clean Inertia.js page refresh on action.

What I Learned

Keep routing logic in the database, not the code — it makes the system far more flexible
Laravel Events are perfect for notifications — clean, queueable, and easy to extend
Policies over middleware for row-level access — much cleaner when you have complex role rules

Conclusion
This pattern works for any multi-step approval system — not just vouchers. You could use it for leave requests, purchase orders, or any document that needs to pass through multiple departments.

Want to see this in action?
I built VMMS — a complete Voucher Management & Monitoring System using everything covered in this article.
Live demo: https://vmms-app-production.up.railway.app/login
Get the full source code: https://getvmms.gumroad.com/l/zeroqz

Happy to answer any questions in the comments!

How I Built a Production-Ready Voucher Management System with Laravel 12 and Vue 3

Mon, 22 Jun 2026 12:50:14 +0000

The Problem

I'm a BS Information Technology student in the Philippines. During my time observing how
offices work, I noticed something that kept bothering me.

Voucher processing is still done manually almost everywhere.
Someone fills out a paper form, hands it to the next office,
that office stamps it and passes it again, and so on — until
it either gets done or gets lost on someone's desk.

No tracking. No visibility. The client has no idea where their
request is. The admin has no data. Staff have no accountability.

I kept thinking — this is exactly the kind of problem software
should solve. So I spent the last few months building it.

What I Built

VMMS stands for Voucher Management & Monitoring System.

It handles the entire voucher request process — from the moment
a client submits a request, all the way through each department
that needs to process it, until it's finally released.

No paper. No manual routing. No "what's the status of my request?"

Tech Stack

I went with what I know best:

Laravel 12 for the backend — routing, queues, and email jobs
Vue 3 (Composition API) for the frontend — reactive and clean
Inertia.js v2 — so I don't have to build a separate API
Tailwind CSS + Vuetify 3 — for UI components and styling
MySQL 8.0 — for the relational data and complex queries
Resend — for transactional emails

What It Can Do

There are three separate panels depending on your role:

Admin
You get full control — manage users, voucher types, and see
everything through an analytics dashboard. There's a staff
performance leaderboard, rejection rate charts, audit logs,
and even custom branding options.

Staff
Each department gets their own queue of requests to process.
You can complete, reject, or flag a request for missing documents.
There's also a personal performance dashboard showing your stats
and ratings from clients.

Client
You submit requests online, track which department is currently
processing your voucher in real time, upload corrected documents
if something gets flagged, and rate the staff after it's done.

Some other things worth mentioning:

Deadlines are holiday-aware — staff don't get penalized for
non-working days
Every action is logged in an audit trail
PDF and Excel exports on all reports
Automated email notifications at every stage

The Parts That Were Actually Hard

Date queries across MySQL and MariaDB
I originally wrote date queries using MySQL-specific functions
like MONTH() and MONTHNAME(). Broke on MariaDB. Had to rewrite
everything to use Carbon instead — which honestly ended up
being cleaner anyway.

The pipeline tracker
Getting the pipeline stepper to accurately show which department
is currently processing a request was trickier than I expected.
Especially edge cases — what if a department is skipped? What if
a request gets returned for missing documents mid-flow? Took a
few rewrites to get right.

Holiday-aware deadlines
I built a DateHelpers service that calculates business days
while excluding weekends and holidays. Sounds simple, took way
longer than expected. Really happy with how it turned out though.

Try It Yourself

Live demo: https://vmms-app-production.up.railway.app/login

Credentials if you want to explore:

It's Available on Gumroad

I'm selling VMMS in two versions:

Obfuscated / Protected — $150
Deploy it as-is. PHP backend is protected, Vue frontend and
config files are fully readable. Good for offices and
institutions that just want to run it.

‍ Full Source Code — $400
Every file is readable and editable. Good for developers who
want to customize it for a specific client or use case.

Both versions come with documentation, a quick start guide,
and deployment configs for Nginx, Apache, and Railway.

https://getvmms.gumroad.com/l/zeroqz

Happy to answer questions in the comments — whether about
the build, the tech stack, or anything else.

Through the Looking Glass: Why Your Server Logs Are a Playground for Cyber-Detectives

Thu, 11 Jun 2026 13:54:28 +0000

When you deploy a custom analytics package or any traffic-monitoring tool, your expectations are usually modest: a few hits from friends, maybe your mom, or an occasional lost translator bot. But after the server runs for a couple of days, the reality often turns out to be significantly more complex.

Recently, while auditing the logs of my Laravel-based analytics package, I discovered that my project had become a focal point for researchers who don't just "scroll the feed," but dissect the internet down to its molecular level.

As a developer, it made me curious: what exactly are these "guests from the future" (like Firefox 140.0) looking for, and why are corporate entities like Palo Alto Networks suddenly keeping such a close eye on a domain that barely existed yesterday?

When "Grey" Traffic Becomes an Object of Study

The first thing that stands out in the logs isn't the usual bot noise, but Power Users. I’m talking about visitors coming via IPv6 tunnels, using Linux, and identifying as DuckDuckGo users. These are individuals who consciously avoid tracking and operate with tools that most of us consider "advanced" or "niche."

They behave like professional auditors:

Protocol Adherence: Checking robots.txt before crawling.

Jurisdictional Assessment: Analyzing Terms of Service within seconds (a classic professional trait: understand the jurisdiction before pulling the trigger).

Intentional Focus: Bypassing general content in favor of direct interaction with security tools (like DNS audits).

This is a vital signal for any engineer: if your software attracts this type of user, you've built something genuinely practical. Simultaneously, it serves as a high-stakes stress test for your entire stack.

DNS Detective: The "Karachi Police" Case

The situation becomes truly fascinating when your tool starts being used as a "proxy scanner" to probe other resources. For instance, I noticed requests hitting karachipolice.gov.pk via my tool. Using an independent auditor to probe a government domain is a perfect example of how borders vanish on the web.

What did the audit reveal, and what should you look for in your own projects?

DMARC: null. An absent protection policy is an open invitation for attackers to perform email spoofing.

SPF ~all. A "soft" lock that exists formally but fails to effectively block unauthorized senders.

IPv6 Facade. A site may correctly resolve via modern AAAA records, but still rely on an outdated, vulnerable mail infrastructure behind the scenes.

This case serves as a sharp reminder: domain security isn't about wall thickness; it's about the precision of a single DNS record. If you haven't audited your own domain's configuration in a while, it is high time to verify those settings — you can run a free DNS audit to ensure your records are as airtight as they need to be.

Corporate "Ghosts" from Palo Alto Networks

While the first group represents human researchers, Palo Alto Networks and their peers represent the world of automated global threat mapping. Once your service begins exhibiting behavior resembling a network scanner, it inevitably ends up on corporate radar.

For a developer, this is a critical turning point:

Your domain reputation is being built automatically.
If your service behaves "professionally" (Laravel 12, clean headers, valid configurations), algorithms flag you as a legitimate research node, which improves your trust rating across the "clean internet."

Final Thoughts: What Should We Learn?

Analytics is more than just traffic charts; it is a powerful tool for code hygiene and security. When you read your logs, you are reading the story of the web in real-time.

If you are interested in the technical implementation details of how I built this package without crashing production, or want to dive deeper into the security of HTTP headers (and why a single forgotten comma in your CSP can "kill" your site for Googlebot), check out these resources:

How I Built My Own Laravel Analytics Package (and Almost Didn't Crash Production) — Technical implementation details.

Your Digital Fortress: Why a Security Headers Audit is Essential — Why headers are the first thing every "pro" checks.

Take care of your HTTP headers, and don't forget to check your logs. They are always more interesting than Google Analytics.

Laravel AI Agents Now Support MCP Servers

Tue, 09 Jun 2026 18:29:18 +0000

Laravel AI SDK now supports MCP (Model Context Protocol) servers through a dedicated MCP client in the laravel/mcp package. Developers can connect Laravel AI agents to any MCP server — local via STDIO or remote via HTTP — and use its tools alongside custom agent tools. Authentication is handled via bearer tokens or full OAuth (including PKCE and client credentials). The integration is designed so MCP tools drop into an agent's existing tools() method without changing the agent loop. Additional features include built-in caching for tool lists and a faking/testing layer that lets you test MCP-powered agents without a live server.

Building a Digital Customs Checkpoint: My 7-Part Journey in Laravel Analytics & Bot Defense

Thu, 04 Jun 2026 09:00:00 +0000

Over the past year, developing laravel-visit-analytics has evolved from a simple experiment into a significant engineering challenge. When standard analytics tools failed to meet my requirements for GDPR/DSGVO compliance and data accuracy, I realized: if you want it done right, do it yourself.

This 7-part series chronicles my transition from naive trust in browser headers to building a system that detects botnets in real-time based on their unique "digital fingerprints."

Project Roadmap:

Phase 1: Architecture & Foundation

Chapter 1: Breaking Free from the Giants. Why I abandoned Google Analytics for a Privacy-First approach — How I Built My Own Laravel Analytics Package (and Almost Didn't Crash Production).
Chapter 2: Refactoring 2.0. Replacing heavy middleware with an elegant Chain of Responsibility and optimizing database performance — Refactoring Laravel Visit Analytics: The Path to Version 2.0.0.

Phase 2: The Logic of Suspicion

Chapter 3: The Lie Detector. Implementing a scoring system, Snowball Effect, and honeypots to filter out "junk" traffic — A Lie Detector for HTTP Requests: Analytics Through Time.
Chapter 4: Through the Looking Glass. How DNS auditing and IPv6 analysis helped uncover true traffic sources — Through the Looking Glass of Logs: Karachi Police, DuckDuckGo, and IPv6 Magic.
Chapter 5: Code with a Human Face. The story of how I almost banned my son's vintage Sony Ericsson and why I implemented a "mercy coefficient" — Human-Centric Bot Detection: Lessons from Sony Ericsson and Win98.

Phase 3: Advanced Defense

Chapter 6: Hunting Digital Chameleons (Part 1). Defeating botnets via Client Hints and implementing real-time anonymization in v2.4.0 — Hunting Digital Chameleons: How We Defeated Botnets in Laravel v2.4.0.
Chapter 7: Hunting Digital Chameleons (Part 2). Why session imitation is a bot's weak point and how I detect anomalies in session stability — Hunting Digital Chameleons: Why Session Imitation Is the Weakest Link for Modern Bots.

What’s Next?
The foundation is set. I am currently focusing on data integrity, but plans are already in motion to visualize these threat patterns directly in the Laravel Filament dashboard. Stay tuned!

How I Built My Own Laravel Analytics Package (and Almost Didn't Crash Production)

Wed, 03 Jun 2026 10:22:39 +0000

Why Not Google Analytics? (Or why I love reinventing the wheel)

To be honest, this wasn't an easy call. I’ve been in development for quite a while and had grown accustomed to GA. What could be simpler: you slap a script with your ID onto the site, and data starts flowing into the analytics console. All that's left is to wait for the traffic to roll in and then analyze it by country, gender, age groups, and so on.

Yes, that’s how it used to be, but in today’s reality, there are objective reasons to rethink this concept. Let’s be real: hooking up Google Analytics in 2026 is like putting a massive deadbolt on your front door but leaving the keys with your neighbor. Everything seems under control, but the neighbor knows exactly when you came home, what you bought, and why you have a long face. And when someone visits you and wants to stay incognito, the neighbor won't give them the keys, and they won't even tell you they stopped by. Their response would be something like: “Nobody came, I never sleep, everything is under control…”. What am I getting at?

Now, for your analytics to work, you must display a cookie consent banner and get the user's permission. And that’s where the problem lies. 90% of users don’t accept all cookies—only the strictly necessary ones. And what does that mean? Google Analytics ends up dead in the water. Besides, everyone is sick and tired of these banners. So, if there’s a legal way to ditch them, why not take it?

(To learn how to avoid legal trouble with data protection laws, check out the article GDPR Without the Headache: A Guide for Web Developers in Germany )

The decision to drop GA was made. When I decided to hit the "Eject" button and catapult myself out of the Google ecosystem, I faced a logical question: what would fill the void? Because I still needed the numbers. I started looking at the heavy artillery.

The first candidate was Matomo (formerly Piwik): Probably the most powerful all-in-one machine. It’s like keeping a pet elephant in your backyard. It does everything, the database grows like crazy, but it requires a separate PHP server, MySQL, and constant babysitting. For my small pet projects, it felt like trying to drive nails with a microscope.

The second tool I looked at was Plausible / Fathom: Sleek, modern, and privacy-respecting. But there’s a catch: you either pay a subscription (a questionable investment for a free tool) or you mess around with self-hosted Docker versions, which also eat up a good chunk of your VPS RAM.

I looked at all of this and thought: “Do I really need to spin up an entire infrastructure just to know that 50 people read my article on German taxes yesterday?”. That’s when it hit me: I don’t need a "combine harvester." I need a tiny, precision scalpel that lives right inside my Laravel application.

I wanted something of my own: lightweight, like a morning espresso, and not asking annoying questions about GDPR. Plus, I was simply curious about who all these people (and bots) were "knocking" on my security tools at oleant.net. Since this blog also needed the same tool, I decided to develop a standalone package that could be easily installed via composer and published openly on Packagist.

For those interested in diving into the code, the package is called oleant/laravel-visit-analytics, compatible with Laravel versions 10/11/12. GitHub link: https://github.com/Oleant-NET/laravel-visit-analytics

The Heart of the System: Middleware and the Magic of the Aftertaste

Which architecture to use? There are various ways to implement this. Fortunately, Laravel has a great Middleware mechanism. I decided to stick with that, but would it slow down the user? They shouldn't have to care about my overhead. And what if the database goes down or something goes wrong? A 500 error page as the face of the site is definitely not what I was aiming for.

That’s why a crucial decision was made — to use the terminate() method. In a Laravel Middleware, it’s like a polite waiter: he brings you the check and smiles (the handle() method), and only after you’ve already left the restaurant does he go back to wipe the table and log the tip (the terminate() method).

The user has already received their page and is happy, while our server quietly and without rush writes the logs to the database in that moment. Even if something goes wrong, the client still leaves satisfied, and the waiter... just doesn't get a tip this time. Just kidding, but here’s how it works in practice:

PHP

public function terminate(Request $request, Response $response): void
{
    try {
        // Logic to exclude non-target clients, like Admin etc.
        // …
        // Next, write our visitors to the database
        $this->logVisit($request);
    } catch (\Throwable $e) {
        // If the DB takes a nap, we won't wake the user with a 500 error
        \Log::error("Analytics failed, but we're keeping our cool: " . $e->getMessage());
    }
}

Lifehack: All analytics code must be wrapped in a try-catch. Believe me, there's nothing sillier than "crashing" an entire project just because the logger didn't have enough room for a long User-Agent or some other non-obvious case.

GDPR on the Fly: How Not to Become Public Enemy No. 1
To avoid slapping a banner the size of half the screen saying “We are watching you, bro,” I implemented IP anonymization. We simply trim the last part of the address before it ever touches the database. This anonymizes the user and fully complies with the law. Yet, we can still tell which country, data center, etc., the visit came from. We’ll talk more about data center bots once there's more data to show.

Back to IP anonymization:

PHP

// Before: 192.168.1.154 -> After: 192.168.1.0

It’s like seeing a crowd in masks: you understand that 5 people showed up, but who among them is your neighbor — you have no clue. The law is satisfied, and so is my conscience.

Payload: Gathering Only the Goodies
Initially, I wanted to write everything that comes in the URL to the database. But then I looked at the Livewire logs, where half the state of the planet is passed in the parameters, and realized — the database would explode. So, I decided to implement filtering based on allowed parameters in the config using array_intersect_key. Now, only what I’ve personally authorized in the config ends up in the logs. Clean, orderly, and zero fluff.

The default set in the package config looks like this:

PHP

'whitelist' => [
    'utm_source',
    'utm_medium',
    'utm_campaign',
    'utm_term',
    'utm_content',
    'ref',
],

But you can, of course, change it by publishing the config in your project first:

Bash

php artisan vendor:publish --tag="visit-analytics-config"

After that, a visit-analytics.php file will appear in your config folder. There, you can not only expand the list of tracked parameters (for example, adding something like page or search) but also specify excluded paths so you don't turn your database into a dump for admin panel or technical endpoint logs.

What's Next?

The package started humming, and the data began to flow. I closed my laptop and went to bed, thinking I’d wake up to some visitor charts from a couple of friends. But reality turned out to be much tougher (and more interesting).

In the next episode, we’ll step through the "looking glass": who are Palo Alto Networks, why do bots read my Terms of Service in 7 seconds, and why Linux + DuckDuckGo is a badge of quality for a visitor?

Building A Production-Ready Laravel Google Sheets Package From Import To Test Suite

Mon, 01 Jun 2026 11:25:30 +0000

Google Sheets is often where business workflows begin.

For Laravel apps, that usually means imports, exports, internal dashboards, user-managed spreadsheets, and the occasional "can we sync this automatically?" request.

olamilekan/laravel-google-sheets v1.1.0 adds several features for those real-world workflows:

Laravel 13 support
Import diff previews
Model, CSV, API, and two-way sync methods
Dry-run sync command
Human-friendly validation error sheets
Retry and exponential backoff for temporary API failures
Better testing fakes
A GitHub Actions test matrix

This is a backward-compatible feature release with 17 commits since v1.0.0.

Install

composer require olamilekan/laravel-google-sheets

Publish the config:

php artisan vendor:publish --tag=google-sheets-config

Laravel 13 support

The package now supports:

Laravel 10
Laravel 11
Laravel 12
Laravel 13

That should make it easier to use the same package across older and newer Laravel applications.

Import diff previews

You can now preview an import before writing anything.

use App\Models\User;
use Olamilekan\GoogleSheets\Facades\GoogleSheets;

$preview = GoogleSheets::connection('users')
    ->diffAgainst(User::query(), key: 'email')
    ->rules([
        'name' => ['required', 'string'],
        'email' => ['required', 'email'],
    ])
    ->preview();

$preview->counts();

The preview separates rows into:

new
changed
deleted
invalid
conflicts

Example:

[
    'new' => 1,
    'changed' => 2,
    'deleted' => 0,
    'invalid' => 1,
    'conflicts' => 0,
]

You can also control which fields are compared:

$preview = GoogleSheets::connection('users')
    ->diffAgainst(User::query(), key: 'email')
    ->only(['name', 'role'])
    ->except(['updated_at'])
    ->preview();

This is useful when building admin import screens or approval flows.

Sync methods

v1.1.0 adds sync helpers for moving data between Google Sheets and common data sources.

Sync from Eloquent to Google Sheets:

use App\Models\User;
use Olamilekan\GoogleSheets\Facades\GoogleSheets;

$report = GoogleSheets::connection('users')
    ->syncFromModel(User::class, keyColumn: 'email', options: [
        'columns' => ['name', 'email', 'role'],
        'conflict' => 'app_wins',
    ]);

Sync from Google Sheets to Eloquent:

$report = GoogleSheets::connection('users')
    ->syncToModel(User::class, keyColumn: 'email');

Import and export CSV files:

$report = GoogleSheets::connection('users')
    ->importCsv(storage_path('app/users.csv'), keyColumn: 'email');

$report = GoogleSheets::connection('users')
    ->exportCsv(storage_path('app/users-export.csv'));

Sync API data into a sheet:

$report = GoogleSheets::connection('orders')
    ->syncFromApi('https://api.example.com/orders', keyColumn: 'order_id', options: [
        'data_key' => 'data',
        'headers' => ['Authorization' => 'Bearer '.$token],
    ]);

Push sheet data to an API:

$report = GoogleSheets::connection('orders')
    ->syncToApi('https://api.example.com/orders/bulk');

Each sync returns a report:

$report->counts();
$report->created();
$report->updated();
$report->conflicts();
$report->errors();

Two-way sync with conflict handling

Two-way sync needs clear conflict behavior.

$report = GoogleSheets::connection('users')
    ->syncTwoWay(User::class, keyColumn: 'email', options: [
        'conflict' => 'fail',
    ]);

Supported strategies:

app_wins
sheet_wins
skip
fail

Dry-run sync command

You can preview command-line imports without writing rows:

php artisan google-sheets:sync "App\\Imports\\UsersImport" users --dry-run

Dry runs compare rows using the import class target and key, then apply validation rules when available.

Validation error sheets

Instead of only throwing validation errors, the package can write row-level issues into an error sheet.

$validRows = GoogleSheets::connection('users')->validateWithErrorSheet([
    'name' => ['required', 'string'],
    'email' => ['required', 'email'],
]);

That gives spreadsheet users a clearer place to fix bad rows.

Queue sync jobs

Longer syncs can be queued:

GoogleSheets::connection('users')
    ->queueSync('syncFromModel', [User::class, 'email'], queue: 'imports');

Audit logs and notifications

Sync activity is logged through Laravel's logger and kept in an in-process audit log:

$records = GoogleSheets::connection('users')->syncAuditLog();

You can also send notifications:

GoogleSheets::connection('users')->syncFromModel(User::class, 'email', [
    'notify' => [
        'slack_webhook' => config('services.slack.sync_webhook'),
        'mail_to' => '*Emails are not allowed*',
    ],
]);

Retry and backoff

Temporary Google Sheets API failures are retried with exponential backoff and jitter.

// config/google-sheets.php
'retry' => [
    'enabled' => true,
    'attempts' => 3,
    'delay' => 250,
    'max_delay' => 5000,
],

Runtime control:

$rows = GoogleSheets::withRetries(attempts: 5, delay: 500)->all();
$rows = GoogleSheets::withoutRetries()->all();

This helps with rate limits, quota throttling, backend errors, and other temporary failures.

Testing fakes

You can test spreadsheet behavior without hitting the real API:

use Olamilekan\GoogleSheets\Facades\GoogleSheets;

$fake = GoogleSheets::fake([
    'users' => [
        ['name' => 'Alice', 'email' => '*Emails are not allowed*'],
    ],
]);

GoogleSheets::connection('users')->appendAssoc([
    ['name' => 'Bob', 'email' => '*Emails are not allowed*'],
]);

$fake->assertAppended('users', [
    'name' => 'Bob',
    'email' => '*Emails are not allowed*',
]);

Upgrade

composer update olamilekan/laravel-google-sheets

If you need the new config options:

php artisan vendor:publish --tag=google-sheets-config

Links

GitHub: github.com/oluwatosinolamilekan/laravel-google-sheets

Package:

composer require olamilekan/laravel-google-sheets

Release:

composer update olamilekan/laravel-google-sheets

I Built a Full POS & Inventory System with Laravel (Shop-Control)

Sat, 30 May 2026 07:27:21 +0000

A few days ago, I decided to go beyond tutorials and build something that reflects how real businesses actually operate.

That’s how Shop-Control was born — a full-stack Point of Sale (POS) and inventory management system built with Laravel.

This project helped me deeply understand how backend systems connect real business workflows like sales, inventory tracking, and customer management.

Why I Built This Project

Most beginner Laravel projects stop at CRUD apps.

I wanted to challenge myself by building something closer to a real production system — something that handles:

Sales processing
Inventory updates in real-time
Role-based access control
Business reporting logic

Instead of isolated features, I focused on how everything connects together as a system.

What Shop-Control Does

Shop-Control simulates a real retail environment where different users interact with the system:

1. Admins & Staff

Manage users and roles
Monitor business performance

2. Products & Inventory

Add, update, and track stock
Organize products by categories

3. Point of Sale (POS)

Add items to cart
Calculate totals dynamically
Process sales transactions

4. Customers

Store customer data
Track purchase history

5. Analytics Dashboard

View sales summaries
Track inventory changes
Monitor business activity

⚙️ Tech Stack

Laravel – Backend framework and business logic
Blade Templates – Server-side rendering
SQLite – Lightweight database for local development
Tailwind CSS / Bootstrap – UI styling

What I Learned Building This

This project taught me more than any tutorial ever did:

Database Design Matters More Than Code

Poor relationships = broken system logic.

I had to carefully design relationships between:

products
sales
customers
cart sessions

2. Business Logic Lives in the Backend

A POS system is not just UI — it’s rules:

stock must update after every sale
carts must calculate totals correctly
users must only access allowed features

3. Real Systems Are About Flow, Not Features

The hardest part wasn’t building features — it was making them work together smoothly.

Preview

Dashboard Overview:

2. POS / Checkout Screen

3. Product & Inventory Management

4. Sales History / Transactions

What’s Next

I plan to improve Shop-Control by adding:

REST API version for mobile apps
PDF invoice generation
Advanced analytics dashboard
Barcode scanning support

Final Thoughts

Building Shop-Control changed how I see Laravel.

It stopped being just a framework for small apps — and became a tool for building real business systems.

If you're learning Laravel, my advice is simple:

Stop only building tutorials. Start building systems.

That’s where real growth happens.

I’d love to hear from other developers:
What was the first project that made Laravel “click” for you?

3 Things Building MediTrack Taught Me About Laravel (and Backend Development)

Thu, 28 May 2026 09:25:53 +0000

A few days ago, I built MediTrack, a Laravel-based hospital management system for managing doctors, patients, appointments, prescriptions, and lab tests.

This was one of the first projects where I moved beyond basic CRUD applications and started thinking in terms of real system design and relationships between features.

While building it, I realized something important:

Laravel starts making real sense when you stop following tutorials and start building complete systems.

MediTrack forced me to think about structure, data flow, and how different parts of a system actually connect together in production-style applications.

Here are 3 key lessons I learned:

1️⃣ Database Design Shapes Everything

At the beginning, I underestimated how important database design really is.

I had entities like:

doctors → appointments
patients → prescriptions
lab tests → patients

But as the project grew, I realized something critical:

If your database structure is wrong, everything built on top of it becomes harder to maintain.

I had to go back multiple times to:

restructure tables
adjust relationships
rethink migrations
fix design decisions that didn’t scale well

This is where Laravel relationships like hasMany and belongsTo started to actually make sense in a practical way.

Key takeaway:

Backend development is mostly about designing data structures correctly before writing logic.

2️⃣ Authentication Is About System Security, Not UI

Before this project, I thought authentication meant:

login
register
logout

But MediTrack introduced role-based access like:

Admin
Doctor
Receptionist

And that changed everything.

Each role needed:

different dashboards
different permissions
restricted routes

protected backend logic

This is where I learned about:

Laravel middleware
route protection
backend authorization logic

One important realization:

Hiding UI elements is not security. Backend rules are what actually protect the system.

Key takeaway:

Authentication is not a feature — it’s a system design decision.

3️⃣ Real Projects Teach What Tutorials Don’t

Tutorials helped me understand Laravel basics.

But MediTrack is where things became real.

I faced issues like:

features breaking after small changes
incorrect database query results
debugging unexpected behavior
spending hours fixing small logic mistakes

Unlike tutorials, there was no step-by-step solution.

I had to:

read documentation
debug systematically
test multiple approaches
learn through failure

And that’s where real growth happened.

Key takeaway:

You don’t learn development by watching — you learn it by building, breaking, and fixing.

Final Thoughts

MediTrack is still evolving, and there’s a lot I want to improve.

But it changed how I approach development.

Laravel feels much clearer now because I’ve used it to build a complete system, not just small examples.

If you’re learning backend development, my advice is simple:

Start building real projects early — even if they’re imperfect.

The learning that comes from debugging your own system is completely different from following tutorials.

That’s where real developer thinking starts.

I’d love to hear from others:
What project taught you the most about development?

Open to feedback, collaboration, and backend engineering opportunities.

How I Built a Hospital Management System with Laravel

Mon, 25 May 2026 12:07:28 +0000

Hey everyone! I'm Ibtisam, a developer from Somaliland learning full-stack web development. Recently, I built MediTrack, a hospital management system with Laravel, and I want to share what I learned along the way.

Why I Built MediTrack

I wanted to understand how real-world applications work beyond simple CRUD projects. Healthcare systems seemed like a perfect challenge because they involve:

Multiple user roles (Admin, Doctor, Receptionist)
Complex data relationships (Doctors → Patients → Appointments)
Real business logic (managing prescriptions, lab tests)

So I built MediTrack to learn and create a solid portfolio project.

What MediTrack Does

It's a role-based hospital management system that helps clinics manage:

Doctors
Patients
Appointments
Prescriptions
Lab Tests

Features:

Secure authentication (login/register)
Real-time dashboard with statistics
Full CRUD operations for all modules
Search functionality
Responsive Bootstrap UI

The Tech Stack (And Why)

Laravel – Powerful yet beginner-friendly framework with great routing and authentication
MySQL – Handles complex database relationships easily
Bootstrap 5 – Build a clean UI without spending time on CSS
Blade Templates – Dynamic templating that feels natural in PHP

The 3 Biggest Challenges (And How I Solved Them)

Database Design

Problem: Connecting Doctors, Patients, Appointments, and Prescriptions without breaking things.

Solution: I learned about Laravel relationships (hasMany, belongsTo) and spent time planning my schema before coding. This saved me from major refactoring later.

Lesson: Plan your database first. It's harder to change later.

Authentication & Authorization

Problem: Different users (Admin, Doctor, Receptionist) need different dashboards and permissions.

Solution: Used Laravel's built-in middleware and route guards to check user roles before showing data.

Lesson: Never trust the frontend for security. Always validate on the backend.

Getting Real-Time Statistics

Problem: The dashboard needed to show live counts of doctors, patients, appointments, etc.

Solution: Used Laravel's query builders and Eloquent to aggregate data efficiently, then displayed it with simple JavaScript.

Lesson: Database queries matter. Bad queries slow down your app fast.

Here's What It Looks Like

Dashboard

Managing Doctors

Patients Overview

Appointments Management

Labs Management

Medication Management

Key Lessons for Beginners

Start with a real problem – Don't build random projects. Build something that solves a real need.
Plan before coding – Spend 30 minutes sketching your database. It saves hours later.
Use the framework's tools – Laravel has authentication, routing, and validation built-in. Use them instead of reinventing the wheel.
Test locally first – Make sure features work before pushing to production.
Document your code – Future you (and contributors) will thank you.

Check It Out

Want to see the full code, contribute, or just browse around?

GitHub: github.com/adventureibtisam111/meditrack

If MediTrack helped you learn something or you find it useful, I'd love your support:

⭐ Star the repo – Shows other developers it's helpful

Drop feedback – Issues and suggestions are welcome

[Sponsor my work] (https://github.com/sponsors/adventureibtisam111) – Helps me build more educational projects like this

That's it! Building MediTrack taught me that full-stack development isn't magic—it's just solving problems step by step.

If you're learning Laravel or building your first full-stack project, I hope MediTrack inspires you. Let me know if you have questions or want to collaborate!

Happy coding!

Building A Laravel Google Sheets Package That Imports, Exports, Caches, Formats, And Tests Cleanly

Wed, 20 May 2026 15:09:00 +0000

Google Sheets often starts as a quick operational tool. A support team tracks users in a sheet, finance exports monthly reports, or an internal dashboard needs a simple spreadsheet backend. The challenge is keeping that workflow Laravel-friendly once it grows beyond a few API calls.

This package wraps the Google Sheets API with a fluent Laravel API for common application tasks: importing rows, exporting reports, managing multiple spreadsheet connections, caching reads, formatting tabs, and testing without hitting Google.

Installation

composer require olamilekan/laravel-google-sheets
php artisan vendor:publish --tag=google-sheets-config

Add your service account credentials path:

GOOGLE_SHEETS_CREDENTIALS_PATH=/path/to/service-account.json

Then configure named spreadsheet connections:

'sheets' => [
    'users' => [
        'spreadsheet_id' => env('GOOGLE_SHEETS_USERS_SPREADSHEET_ID'),
        'sheet' => 'Users',
    ],

    'reports' => [
        'spreadsheet_id' => env('GOOGLE_SHEETS_REPORTS_SPREADSHEET_ID'),
        'sheet' => 'Monthly',
    ],
],

Import Users From Google Sheets

For a simple import, read rows from a named connection:

$rows = GoogleSheets::connection('users')->all();

For a reusable import, create an import class:

use App\Models\User;
use Olamilekan\GoogleSheets\Imports\SheetImport;

class UsersImport extends SheetImport
{
    public function rules(): array
    {
        return ['email' => ['required', 'email']];
    }

    public function model(array $row): User
    {
        return User::updateOrCreate(
            ['email' => $row['email']],
            ['name' => $row['name']]
        );
    }
}

Run it from code:

GoogleSheets::import(new UsersImport(), 'users');

Or from Artisan:

php artisan google-sheets:sync "App\\Imports\\UsersImport" users

Export Reports To Google Sheets

Export classes keep reporting logic out of controllers and commands:

use App\Models\Report;
use Olamilekan\GoogleSheets\Exports\SheetExport;

class ReportsExport extends SheetExport
{
    public bool $replace = true;

    public function headings(): array
    {
        return ['Date', 'Name', 'Total'];
    }

    public function collection()
    {
        return Report::query()
            ->latest()
            ->get()
            ->map(fn (Report $report) => [
                $report->created_at->toDateString(),
                $report->name,
                $report->total,
            ]);
    }
}

Then export:

GoogleSheets::export(new ReportsExport(), 'reports');

Header-Aware Appends And Upserts

Sheets usually have headers. Instead of manually ordering every cell, append associative arrays:

GoogleSheets::connection('users')->appendAssoc([
    ['name' => 'Alice', 'email' => '*Emails are not allowed*', 'role' => 'admin'],
]);

Upsert rows by a key column:

GoogleSheets::connection('users')->upsert('email', [
    ['name' => 'Alice Updated', 'email' => '*Emails are not allowed*', 'role' => 'owner'],
    ['name' => 'Bob', 'email' => '*Emails are not allowed*', 'role' => 'user'],
]);

Validation And Required Headers

Catch bad spreadsheet data before it reaches your app:

GoogleSheets::connection('users')->requireHeaders(['name', 'email', 'role']);

$rows = GoogleSheets::connection('users')->validate([
    'name' => ['required', 'string'],
    'email' => ['required', 'email'],
]);

Multi-Connection Workflows

Named connections make it easy to separate workflows:

$users = GoogleSheets::connection('users')->all();

GoogleSheets::connection('reports')->append([
    ['2026-05-17', 'Monthly Revenue', 15000],
]);

Caching

Enable caching with Laravel's cache system:

GOOGLE_SHEETS_CACHE_ENABLED=true
GOOGLE_SHEETS_CACHE_STORE=redis
GOOGLE_SHEETS_CACHE_TTL=600

Or turn it on per call:

$rows = GoogleSheets::connection('users')->enableCache(300)->all();

When writes happen, the package clears remembered read cache keys for that spreadsheet so later reads can refresh.

Formatting, Formulas, And Named Ranges

Reports often need more than raw data:

GoogleSheets::connection('reports')
    ->sheet('Monthly')
    ->boldHeader()
    ->freezeRows()
    ->autoResizeColumns(1, 4);

GoogleSheets::connection('reports')->append([
    ['Total', GoogleSheets::formula('SUM(C2:C100)')],
]);

$summary = GoogleSheets::connection('reports')
    ->namedRange('MonthlySummary')
    ->get();

Testing

You can fake Google Sheets in tests:

$fake = GoogleSheets::fake([
    'users' => [
        ['name' => 'Alice', 'email' => '*Emails are not allowed*'],
    ],
]);

GoogleSheets::connection('users')->appendAssoc([
    ['name' => 'Bob', 'email' => '*Emails are not allowed*'],
]);

$fake->assertAppended('users', ['name' => 'Bob', 'email' => '*Emails are not allowed*']);

Useful Commands

php artisan google-sheets:list users
php artisan google-sheets:clear reports --sheet=Monthly --range=A2:D100
php artisan google-sheets:sync "App\\Exports\\ReportsExport" reports

Closing

The goal is to make Google Sheets feel like a natural Laravel integration: fluent for simple reads and writes, structured for import and export classes, cache-aware for production use, and fakeable in tests.

Multi-Tenant Security in SaaS: Data Isolation Patterns That Actually Work

Mon, 04 May 2026 11:15:43 +0000

Multi-tenancy is the economic engine of SaaS. Sharing infrastructure across customers reduces cost and simplifies operations. But it introduces a risk that can end your business overnight: tenant data leakage.

When one customer can see another customer's data — even accidentally — the consequences are severe. Regulatory fines, contract termination, public disclosure requirements, and irreparable trust damage. I have worked on multi-tenant platforms serving hundreds of organisations, and I have learned that data isolation is not something you bolt on later. It is a foundational architectural decision that shapes everything from database design to query patterns to testing strategy.

This article covers the three main tenancy models, practical implementation patterns in Laravel and Node.js, and the security controls that prevent data leakage in production.

The Three Tenancy Models

1. Database-per-Tenant

Each tenant gets a completely separate database. Maximum isolation, maximum operational complexity.

Pros: Strongest isolation. Easy compliance with data residency requirements. Independent backup and restore per tenant.

Cons: Connection management overhead. Schema migrations must run across all databases. Does not scale well beyond a few hundred tenants.

Best for: Regulated industries (healthcare, finance), enterprise customers with strict data sovereignty requirements.

2. Schema-per-Tenant

All tenants share a database server, but each gets a separate schema (or namespace). Moderate isolation with lower overhead than separate databases.

Pros: Good isolation without connection management complexity. PostgreSQL handles this natively with schemas.

Cons: Not supported equally across all databases. MySQL schema separation is effectively database separation. Migrations still need to run per schema.

Best for: Mid-market SaaS with tens to low hundreds of tenants.

3. Shared Database with Row-Level Isolation

All tenants share the same tables. Every row includes a tenant_id column. Isolation is enforced at the application and query level.

Pros: Simplest to operate. Migrations run once. Scales to thousands of tenants. Lowest infrastructure cost.

Cons: One missed WHERE clause leaks data. Requires rigorous enforcement at every layer.

Best for: High-volume SaaS, platforms with many small tenants, startups optimising for speed.

For most SaaS applications, shared database with row-level isolation is the right starting point. It is also the hardest to get right, because isolation depends entirely on your code never forgetting to filter by tenant. The rest of this article focuses on making that bulletproof.

Tenant Context Management

The foundation of row-level tenancy is a reliable tenant context — a mechanism that ensures every database query automatically includes the correct tenant filter.

Laravel: Global Scopes and Middleware

namespace App\Http\Middleware;

use App\Services\TenantContext;
use Closure;
use Illuminate\Http\Request;

class ResolveTenant
{
    public function __construct(private TenantContext $tenantContext) {}

    public function handle(Request $request, Closure $next)
    {
        $tenantId = $this->resolveTenantId($request);

        if (!$tenantId) {
            return response()->json(['error' => 'Tenant could not be resolved.'], 403);
        }

        $this->tenantContext->set($tenantId);

        $response = $next($request);

        $this->tenantContext->clear();

        return $response;
    }

    private function resolveTenantId(Request $request): ?string
    {
        if ($request->hasHeader('X-Tenant-ID')) {
            return $this->validateTenantAccess(
                $request->user(),
                $request->header('X-Tenant-ID')
            );
        }

        $host = $request->getHost();
        $subdomain = explode('.', $host)[0] ?? null;

        if ($subdomain) {
            return $this->resolveTenantBySubdomain($subdomain);
        }

        return $request->user()?->default_tenant_id;
    }

    private function validateTenantAccess($user, string $tenantId): ?string
    {
        if (!$user) return null;

        $hasAccess = $user->tenants()->where('tenant_id', $tenantId)->exists();
        return $hasAccess ? $tenantId : null;
    }

    private function resolveTenantBySubdomain(string $subdomain): ?string
    {
        return cache()->remember(
            "tenant:subdomain:{$subdomain}",
            now()->addHours(1),
            fn () => \App\Models\Tenant::where('subdomain', $subdomain)->value('id')
        );
    }
}

namespace App\Services;

class TenantContext
{
    private ?string $tenantId = null;

    public function set(string $tenantId): void
    {
        $this->tenantId = $tenantId;
    }

    public function get(): string
    {
        if ($this->tenantId === null) {
            throw new \RuntimeException('Tenant context not set. This is a critical isolation failure.');
        }

        return $this->tenantId;
    }

    public function clear(): void
    {
        $this->tenantId = null;
    }

    public function isSet(): bool
    {
        return $this->tenantId !== null;
    }
}

Automatic Query Scoping with Eloquent

The most dangerous aspect of row-level tenancy is forgetting to add WHERE tenant_id = ? to a query. Eloquent global scopes eliminate this risk:

namespace App\Models\Traits;

use App\Models\Scopes\TenantScope;
use App\Services\TenantContext;

trait BelongsToTenant
{
    protected static function bootBelongsToTenant(): void
    {
        static::addGlobalScope(new TenantScope());

        static::creating(function ($model) {
            if (!$model->tenant_id) {
                $model->tenant_id = app(TenantContext::class)->get();
            }
        });
    }
}

namespace App\Models\Scopes;

use App\Services\TenantContext;
use Illuminate\Database\Eloquent\Builder;
use Illuminate\Database\Eloquent\Model;
use Illuminate\Database\Eloquent\Scope;

class TenantScope implements Scope
{
    public function apply(Builder $builder, Model $model): void
    {
        $tenantContext = app(TenantContext::class);

        if ($tenantContext->isSet()) {
            $builder->where($model->getTable() . '.tenant_id', $tenantContext->get());
        }
    }
}

Now every model that uses the BelongsToTenant trait automatically filters by tenant:

class Invoice extends Model
{
    use BelongsToTenant;

    protected $fillable = ['tenant_id', 'number', 'amount', 'status'];
}

// These queries automatically include WHERE tenant_id = ?
$invoices = Invoice::where('status', 'pending')->get();
$invoice = Invoice::findOrFail($id);
$count = Invoice::count();

Node.js: Middleware and Query Builder Integration

import { Request, Response, NextFunction } from 'express';
import { AsyncLocalStorage } from 'async_hooks';

interface TenantContextData {
  tenantId: string;
}

export const tenantStorage = new AsyncLocalStorage<TenantContextData>();

export function getTenantId(): string {
  const context = tenantStorage.getStore();
  if (!context?.tenantId) {
    throw new Error('Tenant context not set. This is a critical isolation failure.');
  }
  return context.tenantId;
}

export function tenantMiddleware(
  req: Request,
  res: Response,
  next: NextFunction
): void {
  const tenantId = resolveTenantId(req);

  if (!tenantId) {
    res.status(403).json({ error: 'Tenant could not be resolved.' });
    return;
  }

  tenantStorage.run({ tenantId }, () => next());
}

function resolveTenantId(req: Request): string | null {
  const headerTenant = req.headers['x-tenant-id'] as string;
  if (headerTenant) return headerTenant;

  const host = req.hostname;
  const subdomain = host.split('.')[0];
  if (subdomain) return subdomain;

  return (req as any).user?.defaultTenantId ?? null;
}

Prisma Extension for Automatic Tenant Filtering

import { PrismaClient, Prisma } from '@prisma/client';

function createTenantPrisma() {
  const prisma = new PrismaClient();

  return prisma.$extends({
    query: {
      $allOperations({ model, operation, args, query }) {
        const tenantModels = ['Invoice', 'Payment', 'Project', 'Document'];

        if (!model || !tenantModels.includes(model)) {
          return query(args);
        }

        const tenantId = getTenantId();

        if (['findMany', 'findFirst', 'findUnique', 'count', 'aggregate'].includes(operation)) {
          args.where = { ...args.where, tenantId };
        }

        if (['create', 'createMany'].includes(operation)) {
          if (operation === 'create') {
            args.data = { ...args.data, tenantId };
          }
        }

        if (['update', 'updateMany', 'delete', 'deleteMany'].includes(operation)) {
          args.where = { ...args.where, tenantId };
        }

        return query(args);
      },
    },
  });
}

export const prisma = createTenantPrisma();

Row-Level Security in PostgreSQL

For an additional layer of defence, PostgreSQL's Row-Level Security (RLS) enforces tenant isolation at the database level — even if the application code has a bug:

ALTER TABLE invoices ENABLE ROW LEVEL SECURITY;

CREATE POLICY tenant_isolation ON invoices
  USING (tenant_id = current_setting('app.current_tenant_id')::uuid);

ALTER TABLE invoices FORCE ROW LEVEL SECURITY;

Set the tenant context at the beginning of each database connection:

Laravel with RLS

class SetTenantOnConnection
{
    public function handle(Request $request, Closure $next)
    {
        $tenantId = app(TenantContext::class)->get();

        DB::statement("SET app.current_tenant_id = '{$tenantId}'");

        return $next($request);
    }
}

Node.js with RLS

async function withTenantRLS<T>(
  callback: (tx: PrismaClient) => Promise<T>
): Promise<T> {
  const tenantId = getTenantId();

  return prisma.$transaction(async (tx) => {
    await tx.$executeRawUnsafe(
      `SET LOCAL app.current_tenant_id = '${tenantId}'`
    );
    return callback(tx as any);
  });
}

RLS acts as a safety net. Even if a developer writes a raw query that omits the tenant filter, PostgreSQL rejects rows that do not belong to the current tenant.

Testing for Tenant Leakage

The most critical test you can write for a multi-tenant system verifies that Tenant A cannot access Tenant B's data:

Laravel Test

class TenantIsolationTest extends TestCase
{
    public function test_tenant_cannot_access_other_tenant_data(): void
    {
        $tenantA = Tenant::factory()->create();
        $tenantB = Tenant::factory()->create();

        $invoiceA = Invoice::factory()->create(['tenant_id' => $tenantA->id]);
        $invoiceB = Invoice::factory()->create(['tenant_id' => $tenantB->id]);

        app(TenantContext::class)->set($tenantA->id);

        $visibleInvoices = Invoice::all();

        $this->assertTrue($visibleInvoices->contains($invoiceA));
        $this->assertFalse($visibleInvoices->contains($invoiceB));
    }

    public function test_tenant_cannot_access_other_tenant_by_id(): void
    {
        $tenantA = Tenant::factory()->create();
        $tenantB = Tenant::factory()->create();

        $invoiceB = Invoice::factory()->create(['tenant_id' => $tenantB->id]);

        app(TenantContext::class)->set($tenantA->id);

        $this->expectException(ModelNotFoundException::class);
        Invoice::findOrFail($invoiceB->id);
    }

    public function test_queries_without_tenant_context_throw(): void
    {
        $this->expectException(\RuntimeException::class);
        Invoice::all();
    }
}

Node.js Test

describe('Tenant Isolation', () => {
  it('should not return data from another tenant', async () => {
    const tenantA = await createTenant();
    const tenantB = await createTenant();

    await createInvoice({ tenantId: tenantA.id, amount: 100 });
    await createInvoice({ tenantId: tenantB.id, amount: 200 });

    const invoices = await tenantStorage.run(
      { tenantId: tenantA.id },
      () => prisma.invoice.findMany()
    );

    expect(invoices).toHaveLength(1);
    expect(invoices[0].tenantId).toBe(tenantA.id);
  });

  it('should throw when tenant context is missing', async () => {
    await expect(prisma.invoice.findMany()).rejects.toThrow(
      'Tenant context not set'
    );
  });
});

Run these tests on every deployment. A failing tenant isolation test should block the release.

Common Tenant Leakage Vectors

Even with global scopes and RLS, leakage can happen through:

Raw queries: Any DB::select() or prisma.$queryRaw() bypasses ORM scoping. Audit every raw query for tenant filtering.
Background jobs: Queue workers do not have HTTP request context. Tenant ID must be serialised into the job payload and restored before execution.
Cache keys: If cache keys do not include the tenant ID, one tenant's cached data can be served to another.
File storage paths: Uploaded files must be stored under tenant-specific prefixes. A flat storage structure risks cross-tenant file access.
Admin endpoints: Internal tools that query across tenants must be explicitly authorised and logged.

Laravel: Tenant-Aware Job Example

class ProcessInvoice implements ShouldQueue
{
    use Dispatchable, InteractsWithQueue, Queueable, SerializesModels;

    public function __construct(
        private string $tenantId,
        private int $invoiceId,
    ) {}

    public function handle(TenantContext $tenantContext): void
    {
        $tenantContext->set($this->tenantId);

        $invoice = Invoice::findOrFail($this->invoiceId);
        // Process invoice within correct tenant context
    }
}

Production Results

After implementing comprehensive tenant isolation across multi-tenant platforms:

Metric	Before	After
Tenant data leakage incidents	2–3 per year	0
Security audit findings (critical)	4	0
Time to onboard new tenant	2 days	15 minutes
Cross-tenant query bugs caught in CI	N/A	12 (prevented from reaching production)
Customer trust incidents	1 per year	0

Key Takeaways

Start with shared database + row-level isolation. It scales to thousands of tenants and has the lowest operational overhead. Move to database-per-tenant only when regulation demands it.
Never rely on developers remembering to filter. Use global scopes (Laravel) or Prisma extensions (Node.js) to make tenant filtering automatic and invisible.
Add PostgreSQL RLS as a safety net. Application-level filtering is necessary. Database-level filtering is insurance against application bugs.
Test for leakage explicitly. Write tests that create data in Tenant A, set context to Tenant B, and verify the data is invisible. Run these tests on every deployment.
Audit raw queries, background jobs, cache keys, and file paths. These are the most common vectors for accidental cross-tenant data exposure.
Serialise tenant context into background jobs. Queue workers do not inherit HTTP request context. The tenant ID must travel with the job.

Conclusion

Multi-tenant security is not a feature you add — it is a design constraint that shapes your entire architecture. The patterns in this article are not theoretical. They come from building platforms where a tenant leakage incident would mean regulatory consequences and broken customer relationships.

Whether you build in Laravel or Node.js, the principles are the same: automatic query scoping, database-level enforcement, explicit testing, and paranoid attention to the edge cases where isolation breaks down. Get this right, and your multi-tenant platform can scale with confidence.

Why Startups Are Choosing Laravel Over Other Frameworks in 2026

Fri, 01 May 2026 13:40:51 +0000

Quick Overview

Startups in 2026 are choosing Laravel because it allows small teams
to launch real products quickly.
Its batteries-included ecosystem means less setup and more
construction from day one.
The developer experience is smooth, well-documented, and
beginner-friendly.
Infrastructure costs remain low; PHP hosting is affordable and widely
available.
Laravel's toolset is changing quickly to meet the needs of the AI
era.
In short, it eliminates the obstacles that slow down early-stage
progress.

That's the reality most startup founders and solo developers face today. A deadline that won't budge, a budget that has limits, and a framework decision that influences everything that follows. Choose poorly, and your team spends weeks struggling with setup instead of addressing real user problems. Choose well, and you'll live, making improvements and growing while others are still getting things ready.

In 2026, more startups are coming to the same conclusion: Laravel. Not because it's trendy, but because it reliably produces results. It simplifies complex problems, automates repetitive tasks, and provides developers with the tools to work at the speed that early-stage companies need. And with the future of Laravel pushing deeper into AI-powered tooling, real-time features, and serverless infrastructure, the framework is only getting stronger from here.

Why Choose Laravel

The short answer: Laravel removes friction. The longer answer includes everything from authentication to queues to deployment. Let's explore why this PHP framework has become the favorite for startups that need to move quickly without creating a technical mess they'll regret in six months.

1. Everything You Need Ships With Laravel.

When you start a Laravel project, you are not piecing together parts from five different libraries. Authentication, database migrations, job queues, file storage, email sending, and API routing all come included.

For a startup, this means your first week focuses on your product, not your infrastructure. Here’s how that works in practice:

Eloquent ORM allows you to interact with your database using clean,
readable PHP.
Relationships, scopes, and eager loading are just a single method
call away. You avoid raw SQL confusion.
Laravel Sanctum and Breeze provide token-based API authentication and
full-stack starter kits right out of the box. Your login system takes
hours instead of weeks.
Queues and jobs let you offload slow tasks, like emails, image
processing, and third-party API calls, to background workers with a
single dispatch call.
Testing is built in. PHPUnit and Pest are top-notch tools. You can
write feature tests that access your routes and database without any
configuration issues.

2. The Developer Experience Is Genuinely Good

Frameworks succeed or fail based on how enjoyable they are to use. Laravel's documentation is among the best in any language ecosystem. It is clear, complete, and actively maintained. Tools like Laravel Herd for local development, Forge for server deployment, and Vapor for serverless on AWS mean your entire workflow, from local coding to cloud production, exists within a single cohesive ecosystem. This is important when you are a two-person team trying to ship quickly.

3. It's Cost-Effective for Lean Teams

PHP developers are widely available and generally more affordable than Node.js or Go specialists with the same level of experience. Shared and VPS hosting for Laravel apps is well-documented and inexpensive. And since Laravel handles so much out of the box, you need fewer developers to build the same product. For bootstrapped startups, that math matters a great deal.

4. Scalability Is Built In From the Start.

Many people wrongly believe that Laravel is only for small apps. This is not true in 2026. Laravel Octane, powered by Swoole or RoadRunner, greatly increases throughput. Laravel Vapor manages serverless auto-scaling on AWS. Companies that process millions of requests daily use Laravel. You can start small and grow without needing to rewrite your stack.

5. Laravel Is Already Built for the AI Era.

With Laravel Folio, Volt, and strong Livewire 3 integration, creating reactive UIs without a separate JavaScript framework is now easy. More importantly, the PHP AI ecosystem has quickly developed. Integrations with OpenAI, vector databases, and LLM pipelines are available as first-class packages.

The future of Laravel is clearly linked to the AI-augmented web, and the community is already building in that space. This isn't about catching up; it's about keeping up.

6. Community and Hiring Are a Real Advantage

Laracasts, Laravel's official learning platform, offers over 2,000 video lessons. The communities on Discord, Reddit, and GitHub are large and genuinely helpful. When you're a startup and face a problem at 11 pm, that support is more important than any metric.
When it comes to hiring, there is a large pool of Laravel developers worldwide who can be productive from day one; no complicated onboarding is necessary.

7. One More Reason to Choose Laravel

Beyond features and the ecosystem, there's a cultural fit. Laravel was created with developers in mind, not companies trying to standardize processes. That mindset is reflected in every API choice, every helper function, and every convention the framework establishes. It values your time. For a startup founder who is also the lead developer, that respect leads to delivered features and less burnout.

Laravel vs the Alternatives in 2026

You've probably heard the arguments for Django, Node/Express, or even Next.js as a full-stack choice. Here's how they honestly compare for most startup use cases:

Conclusion

Startups in 2026 are not choosing Laravel because it's the only choice; they prefer it because it's the most straightforward option for their needs. It delivers quickly, scales effectively, costs less, and helps your team stay focused. Whether you're creating a SaaS product, a marketplace, or an API backend, Laravel provides the tools you need to go from idea to launch without unnecessary obstacles.
If you're still uncertain about your stack, the evidence clearly points in one direction.

Frequently Asked Questions

1. Is Laravel good for beginners in 2026?

Yes, more than ever. Great documentation, thousands of lessons on Laracasts, and one-click local setup via Laravel Herd mean that most developers can have a working app up and running on their first day. The framework's conventions also guide beginners toward good habits from the start.

2. Is Laravel faster than Node.js?

Node.js performs better on raw concurrency benchmarks, but with Laravel Octane enabled, the difference shrinks quickly. In most real-world apps, the bottleneck is database queries, not the framework. For the vast majority of startups, Laravel's performance is more than enough.

3. Can Laravel handle large-scale applications?

Yes. Companies like Geocodio and Invoice Ninja serve millions of users using Laravel. With Redis caching, queue workers, horizontal scaling, and serverless deployment via Vapor, enterprise-level workloads are very achievable. The argument that "Laravel doesn't scale" is years out of date.

4. What is Laravel best used for?

SaaS products, REST APIs, e-commerce platforms, CMS systems, and marketplaces. Its built-in authentication, payments through Cashier, file storage, and queues make it ideal for products that need multiple features running together from day one.

5. Is Laravel still relevant in 2026?

Absolutely. Annual major releases, support for AI integration, Livewire for reactive UIs, and performance gains with PHP 8.3+ keep Laravel up to date. Developer satisfaction scores remain high, and Laravel job postings continue to be strong globally, both of which are reliable signs of a healthy, growing ecosystem.

Security by Design in Healthcare Data Platforms

Thu, 30 Apr 2026 12:09:49 +0000

Healthcare data is among the most sensitive information a system can hold. Patient records, diagnostic results, treatment histories, and genomic data are not just private — they are regulated by laws that carry serious penalties for mishandling. HIPAA in the United States, GDPR in Europe, and Nigeria's NDPR all impose strict requirements on how healthcare data must be collected, stored, processed, and shared.

Security in healthcare is not something you add after the product works. It must be woven into every layer of the system from the first line of code. I have built health-tech platforms that handle sensitive patient data collection and clinical workflows, and the lessons from that work apply broadly to any system where data protection is not optional.

This article covers the architecture patterns, implementation strategies, and operational practices for building healthcare data platforms that are secure by design — with examples in both Laravel and Node.js.

Why Healthcare Systems Are Different

Most web applications can tolerate a brief security lapse and recover. Healthcare systems cannot. The consequences of a breach are uniquely severe:

Patient harm: Leaked medical records can affect employment, insurance, and personal relationships. Unlike a leaked password, a disclosed medical condition cannot be reset.
Regulatory penalties: HIPAA violations can result in fines up to $1.5 million per violation category per year. GDPR fines can reach 4% of global annual revenue.
Operational shutdown: A breach in a healthcare system may require shutting down access to patient data while the investigation proceeds — directly affecting care delivery.
Trust destruction: Patients who learn their data was compromised may refuse to use digital health tools, undermining the entire digital health ecosystem.

These consequences demand a security model that assumes breaches will be attempted and builds defences at every layer.

The Security Architecture

Healthcare data security operates on multiple layers:

[Client Layer]
  - End-to-end encryption for data in transit
  - Session management with short TTLs
  - Input validation and sanitisation

[Application Layer]
  - Authentication (MFA required)
  - Role-Based Access Control (RBAC)
  - Audit logging of every data access
  - Field-level encryption for sensitive data

[Data Layer]
  - Encryption at rest (AES-256)
  - Database access controls
  - Backup encryption
  - Data retention and purging policies

[Infrastructure Layer]
  - Network segmentation
  - Intrusion detection
  - Vulnerability scanning
  - Access logging and monitoring

Authentication and Access Control

Healthcare systems require strong authentication and granular access control. Not every user should see every patient's data, and every access must be logged.

Laravel: Role-Based Access Control

namespace App\Models;

use Illuminate\Database\Eloquent\Model;

class Permission extends Model
{
    protected $fillable = ['name', 'resource', 'action', 'conditions'];
    protected $casts = ['conditions' => 'array'];
}

class Role extends Model
{
    protected $fillable = ['name', 'description', 'level'];

    public function permissions()
    {
        return $this->belongsToMany(Permission::class);
    }
}

namespace App\Services;

use App\Models\User;
use Illuminate\Support\Facades\Cache;

class AccessControlService
{
    public function canAccess(User $user, string $resource, string $action, array $context = []): bool
    {
        $permissions = $this->getUserPermissions($user);

        foreach ($permissions as $permission) {
            if ($permission->resource !== $resource) continue;
            if ($permission->action !== $action && $permission->action !== '*') continue;

            if ($permission->conditions) {
                if (!$this->evaluateConditions($permission->conditions, $context, $user)) {
                    continue;
                }
            }

            $this->logAccess($user, $resource, $action, $context, true);
            return true;
        }

        $this->logAccess($user, $resource, $action, $context, false);
        return false;
    }

    private function evaluateConditions(array $conditions, array $context, User $user): bool
    {
        foreach ($conditions as $condition) {
            switch ($condition['type']) {
                case 'own_patients_only':
                    if (($context['patient_id'] ?? null) &&
                        !$user->patients()->where('id', $context['patient_id'])->exists()) {
                        return false;
                    }
                    break;
                case 'department_match':
                    if (($context['department_id'] ?? null) !== $user->department_id) {
                        return false;
                    }
                    break;
                case 'time_restricted':
                    $now = now();
                    if ($now->hour < $condition['start_hour'] || $now->hour > $condition['end_hour']) {
                        return false;
                    }
                    break;
            }
        }
        return true;
    }

    private function getUserPermissions(User $user)
    {
        return Cache::remember(
            "user_permissions:{$user->id}",
            now()->addMinutes(15),
            fn () => $user->roles()->with('permissions')->get()->pluck('permissions')->flatten()
        );
    }

    private function logAccess(User $user, string $resource, string $action, array $context, bool $granted): void
    {
        \App\Models\AccessLog::create([
            'user_id' => $user->id,
            'resource' => $resource,
            'action' => $action,
            'context' => $context,
            'granted' => $granted,
            'ip_address' => request()->ip(),
            'user_agent' => request()->userAgent(),
            'accessed_at' => now(),
        ]);
    }
}

Node.js: Middleware-Based Access Control

import { Request, Response, NextFunction } from 'express';

export function requireAccess(resource: string, action: string) {
  return async (req: Request, res: Response, next: NextFunction) => {
    const user = (req as any).user;
    if (!user) return res.status(401).json({ error: 'Authentication required' });

    const context = {
      patient_id: req.params.patientId,
      department_id: req.params.departmentId,
      ip_address: req.ip,
    };

    const granted = await checkAccess(user, resource, action, context);
    await logAccess({ userId: user.id, resource, action, context, granted,
      ipAddress: req.ip!, userAgent: req.headers['user-agent'] || '', accessedAt: new Date() });

    if (!granted) return res.status(403).json({ error: 'Access denied', resource, action });
    next();
  };
}

async function checkAccess(user: any, resource: string, action: string, context: Record<string, unknown>): Promise<boolean> {
  const permissions = await getUserPermissions(user.id);
  return permissions.some((perm: any) => {
    if (perm.resource !== resource) return false;
    if (perm.action !== action && perm.action !== '*') return false;
    if (perm.conditions) return perm.conditions.every((c: any) => evaluateCondition(c, context, user));
    return true;
  });
}

function evaluateCondition(condition: any, context: Record<string, unknown>, user: any): boolean {
  switch (condition.type) {
    case 'own_patients_only': return user.patientIds?.includes(context.patient_id) ?? false;
    case 'department_match': return user.departmentId === context.department_id;
    default: return false;
  }
}

Apply to routes:

router.get('/patients/:patientId/records', requireAccess('patient_records', 'read'), patientRecordController.list);
router.post('/patients/:patientId/records', requireAccess('patient_records', 'write'), patientRecordController.create);

Field-Level Encryption

Not all data in a patient record is equally sensitive. Field-level encryption encrypts specific fields within a record rather than the entire database.

Laravel: Encrypted Attributes

trait EncryptsHealthData
{
    public function getAttribute($key)
    {
        $value = parent::getAttribute($key);
        if (in_array($key, static::$encryptedFields) && $value !== null) {
            try { return Crypt::decryptString($value); } catch (\Exception) { return $value; }
        }
        return $value;
    }

    public function setAttribute($key, $value)
    {
        if (in_array($key, static::$encryptedFields) && $value !== null) {
            $value = Crypt::encryptString($value);
        }
        return parent::setAttribute($key, $value);
    }
}

class PatientRecord extends Model
{
    use EncryptsHealthData;
    protected static array $encryptedFields = ['diagnosis', 'treatment_notes', 'medication_details', 'lab_results', 'genetic_data'];
}

Node.js: Encryption Service

import crypto from 'crypto';

const ALGORITHM = 'aes-256-gcm';
const KEY = Buffer.from(process.env.ENCRYPTION_KEY!, 'hex');

export function encryptField(plaintext: string): string {
  const iv = crypto.randomBytes(16);
  const cipher = crypto.createCipheriv(ALGORITHM, KEY, iv);
  let encrypted = cipher.update(plaintext, 'utf8', 'hex') + cipher.final('hex');
  return `${iv.toString('hex')}:${cipher.getAuthTag().toString('hex')}:${encrypted}`;
}

export function decryptField(ciphertext: string): string {
  const [ivHex, authTagHex, encrypted] = ciphertext.split(':');
  const decipher = crypto.createDecipheriv(ALGORITHM, KEY, Buffer.from(ivHex, 'hex'));
  decipher.setAuthTag(Buffer.from(authTagHex, 'hex'));
  return decipher.update(encrypted, 'hex', 'utf8') + decipher.final('utf8');
}

Comprehensive Audit Logging

Every access to patient data must be logged — this is a regulatory requirement. The audit log answers: who accessed what data, when, from where, and why.

class AuditPatientAccess
{
    public function handle(Request $request, Closure $next): Response
    {
        $response = $next($request);
        $patientId = $request->route('patientId') ?? $request->input('patient_id');

        if ($patientId) {
            AuditLog::create([
                'user_id' => $request->user()->id,
                'user_role' => $request->user()->primaryRole()->name,
                'action' => $request->method() . ' ' . $request->path(),
                'resource_type' => 'patient_data',
                'resource_id' => $patientId,
                'ip_address' => $request->ip(),
                'response_code' => $response->getStatusCode(),
                'request_params' => $this->sanitiseParams($request->all()),
                'accessed_at' => now(),
            ]);
        }
        return $response;
    }

    private function sanitiseParams(array $params): array
    {
        $sensitive = ['password', 'ssn', 'credit_card', 'diagnosis'];
        return collect($params)
            ->map(fn ($value, $key) => in_array($key, $sensitive) ? '[REDACTED]' : $value)
            ->all();
    }
}

Data Retention and Purging

Healthcare regulations specify minimum and maximum retention periods. Data must be available for the required period and securely destroyed afterward.

class DataRetentionService
{
    private const RETENTION_POLICIES = [
        'patient_records' => ['min_years' => 7, 'max_years' => 10],
        'audit_logs'      => ['min_years' => 6, 'max_years' => 7],
        'session_data'    => ['min_years' => 0, 'max_years' => 1],
        'consent_records' => ['min_years' => 10, 'max_years' => 15],
    ];

    public function enforceRetention(): array
    {
        $results = [];
        foreach (self::RETENTION_POLICIES as $dataType => $policy) {
            $cutoff = now()->subYears($policy['max_years']);
            $count = $this->getModel($dataType)->where('created_at', '<', $cutoff)->count();
            if ($count > 0) {
                $this->archiveAndPurge($dataType, $cutoff);
                $results[$dataType] = ['purged' => $count, 'cutoff' => $cutoff->toDateString()];
            }
        }
        return $results;
    }
}

Patients must give informed consent for data collection and processing. Consent must be tracked, versioned, and revocable.

class ConsentService
{
    public function recordConsent(string $patientId, string $consentType, string $version, bool $granted, ?string $ipAddress = null): ConsentRecord
    {
        return ConsentRecord::create([
            'patient_id' => $patientId,
            'consent_type' => $consentType,
            'version' => $version,
            'granted' => $granted,
            'granted_at' => $granted ? now() : null,
            'revoked_at' => !$granted ? now() : null,
            'ip_address' => $ipAddress,
        ]);
    }

    public function hasActiveConsent(string $patientId, string $consentType): bool
    {
        $latest = ConsentRecord::where('patient_id', $patientId)
            ->where('consent_type', $consentType)->latest()->first();
        return $latest && $latest->granted && $latest->revoked_at === null;
    }

    public function revokeConsent(string $patientId, string $consentType): void
    {
        $latest = ConsentRecord::where('patient_id', $patientId)
            ->where('consent_type', $consentType)
            ->where('granted', true)->whereNull('revoked_at')->latest()->first();

        if ($latest) {
            $latest->update(['revoked_at' => now()]);
            DataAnonymisationJob::dispatch($patientId, $consentType)->onQueue('high');
        }
    }
}

Production Results

After implementing security-by-design across healthcare data platforms:

Metric	Before	After
Security audit findings (critical)	7	0
Data access without audit trail	~15% of operations	0%
Unauthorised access attempts detected	Unknown	23/month (all blocked)
Compliance audit preparation time	4 weeks	3 days
Data breach incidents	N/A	0
Mean time to detect anomalous access	Unknown	< 15 minutes

Key Takeaways

Security is architecture, not a feature. It must be built into every layer from day one.
Log every data access. In healthcare, the question is not "if" an audit will happen but "when."
Encrypt sensitive fields, not just the database. Field-level encryption protects against application-layer breaches and insider threats.
Implement RBAC with conditions. "Doctor" is not a sufficient access level — conditions like assigned patients, working hours, and known IPs matter.
Manage consent as a first-class data model. Consent is a versioned, auditable, revocable record — not a checkbox.
Plan for data retention from the start. Build purging infrastructure before you have millions of records.

Conclusion

Building healthcare data platforms requires a security mindset that goes beyond typical web application security. Every design decision — from database schema to API design to deployment configuration — must account for the sensitivity of the data and the regulatory requirements that govern it.

The patterns in this article are not theoretical. They come from building systems that handle real patient data under real regulatory scrutiny. Whether you build in Laravel or Node.js, the principles are universal: encrypt by default, log everything, enforce access at every layer, and design for the audit that will inevitably come.

From Monolith to Modular: A Strangler Migration Playbook

Tue, 28 Apr 2026 14:20:43 +0000

Every successful application eventually outgrows its original architecture. What started as a clean, well-structured monolith becomes a tangled web of dependencies where changing one feature risks breaking three others. Deployments become risky, test suites take forever, and developers spend more time navigating the codebase than writing new features.

The instinct is to rewrite. Do not. Rewrites are how engineering teams burn months of effort and deliver something that, at best, does what the old system already did. The better approach is incremental migration: systematically extracting capabilities from the monolith while keeping the system running in production the entire time.

I have led these migrations across multiple companies — taking legacy codebases with 15+ modules, hundreds of database tables, and years of accumulated technical debt and transforming them into modular, maintainable architectures without downtime. This article is the playbook.

Why Monoliths Become Painful

Monoliths are not inherently bad. They are fast to build, easy to deploy, and simple to reason about — at small scale. The problems emerge gradually:

Deployment coupling: Every change, no matter how small, requires deploying the entire application. A CSS fix and a payment logic change ship in the same deployment.
Dependency tangles: Module A depends on Module B which depends on Module C which depends on Module A. Circular dependencies make changes unpredictable.
Test suite slowdown: Running the full test suite takes 30+ minutes. Developers start skipping tests. Bugs escape to production.
Team bottlenecks: Multiple teams working on the same codebase create merge conflicts, code review backlogs, and release coordination overhead.
Scaling limitations: You cannot scale the payment processing component independently of the user profile component. Everything scales (or fails) together.

The Strangler Fig Pattern

The strangler fig pattern, named after the plant that gradually envelops its host tree, is the safest approach to migrating away from a monolith. The strategy:

Identify a capability to extract from the monolith
Build the new implementation alongside the old one
Route traffic to the new implementation (gradually or all at once)
Remove the old implementation once the new one is proven
Repeat for the next capability

The monolith continues to run throughout. There is no big bang cutover. Each migration step is small, reversible, and independently testable.

Phase 1: Understanding What You Have

Before you extract anything, you need a map of the current system.

Dependency Analysis

# Laravel: Find all cross-module dependencies
# Look for imports/use statements between modules

Laravel Module Boundary Analysis

namespace App\Console\Commands;

use Illuminate\Console\Command;
use Illuminate\Support\Facades\File;

class AnalyzeModuleDependencies extends Command
{
    protected $signature = 'modules:analyze';

    public function handle(): void
    {
        $modules = $this->getModuleDirectories();
        $dependencies = [];

        foreach ($modules as $module) {
            $files = File::allFiles(app_path($module));
            $imports = [];

            foreach ($files as $file) {
                $content = $file->getContents();
                preg_match_all('/use App\\\\(\w+)\\\\/', $content, $matches);
                $imports = array_merge($imports, $matches[1]);
            }

            $externalDeps = array_unique(
                array_filter($imports, fn ($dep) => $dep !== $module)
            );

            $dependencies[$module] = $externalDeps;
        }

        foreach ($dependencies as $module => $deps) {
            $this->info("{$module} depends on: " . implode(', ', $deps));
        }

        $this->detectCircularDependencies($dependencies);
    }

    private function detectCircularDependencies(array $dependencies): void
    {
        foreach ($dependencies as $moduleA => $depsA) {
            foreach ($depsA as $moduleB) {
                if (isset($dependencies[$moduleB]) && in_array($moduleA, $dependencies[$moduleB])) {
                    $this->warn("Circular dependency: {$moduleA} <-> {$moduleB}");
                }
            }
        }
    }

    private function getModuleDirectories(): array
    {
        return collect(File::directories(app_path()))
            ->map(fn ($dir) => basename($dir))
            ->filter(fn ($dir) => !in_array($dir, ['Console', 'Exceptions', 'Http', 'Providers']))
            ->values()
            ->all();
    }
}

Node.js Dependency Mapping

import fs from 'fs';
import path from 'path';

interface ModuleDependency {
  module: string;
  dependsOn: string[];
  files: number;
  linesOfCode: number;
}

function analyzeModuleDependencies(srcDir: string): ModuleDependency[] {
  const modules = fs.readdirSync(srcDir, { withFileTypes: true })
    .filter((d) => d.isDirectory())
    .map((d) => d.name);

  return modules.map((moduleName) => {
    const moduleDir = path.join(srcDir, moduleName);
    const files = getAllFiles(moduleDir, ['.ts', '.js']);
    const imports: string[] = [];
    let totalLines = 0;

    files.forEach((file) => {
      const content = fs.readFileSync(file, 'utf-8');
      totalLines += content.split('\n').length;

      const importRegex = /from\s+['"]\.\.\/(\w+)/g;
      let match;
      while ((match = importRegex.exec(content)) !== null) {
        if (match[1] !== moduleName) {
          imports.push(match[1]);
        }
      }
    });

    return {
      module: moduleName,
      dependsOn: [...new Set(imports)],
      files: files.length,
      linesOfCode: totalLines,
    };
  });
}

function getAllFiles(dir: string, extensions: string[]): string[] {
  const results: string[] = [];
  const entries = fs.readdirSync(dir, { withFileTypes: true });

  for (const entry of entries) {
    const fullPath = path.join(dir, entry.name);
    if (entry.isDirectory()) {
      results.push(...getAllFiles(fullPath, extensions));
    } else if (extensions.some((ext) => entry.name.endsWith(ext))) {
      results.push(fullPath);
    }
  }

  return results;
}

Phase 2: Establish Module Boundaries

Before extracting services, enforce boundaries within the monolith. This is the most important step and the one most teams skip.

Laravel: Module Service Providers and Contracts

// app/Billing/Contracts/BillingService.php
namespace App\Billing\Contracts;

interface BillingService
{
    public function createInvoice(string $customerId, array $lineItems): Invoice;
    public function processPayment(string $invoiceId, array $paymentMethod): PaymentResult;
    public function getCustomerBalance(string $customerId): Money;
}

// app/Billing/BillingServiceProvider.php
namespace App\Billing;

use Illuminate\Support\ServiceProvider;

class BillingServiceProvider extends ServiceProvider
{
    public function register(): void
    {
        $this->app->bind(
            Contracts\BillingService::class,
            Services\BillingServiceImpl::class
        );
    }
}

// app/Orders/Services/OrderService.php
namespace App\Orders\Services;

use App\Billing\Contracts\BillingService;

class OrderService
{
    public function __construct(private BillingService $billing) {}

    public function completeOrder(Order $order): void
    {
        $invoice = $this->billing->createInvoice(
            $order->customer_id,
            $order->lineItems->toArray()
        );

        $order->update(['invoice_id' => $invoice->id, 'status' => 'invoiced']);
    }
}

Node.js: Module Interfaces

// src/billing/contracts.ts
export interface BillingService {
  createInvoice(customerId: string, lineItems: LineItem[]): Promise<Invoice>;
  processPayment(invoiceId: string, method: PaymentMethod): Promise<PaymentResult>;
  getCustomerBalance(customerId: string): Promise<Money>;
}

// src/billing/index.ts
export { BillingServiceImpl as BillingService } from './services/billing-service';
export type { BillingService as BillingServiceInterface } from './contracts';

// src/orders/services/order-service.ts
import type { BillingService } from '../../billing/contracts';

export class OrderService {
  constructor(private billing: BillingService) {}

  async completeOrder(order: Order): Promise<void> {
    const invoice = await this.billing.createInvoice(
      order.customerId,
      order.lineItems
    );

    await this.orderRepo.update(order.id, {
      invoiceId: invoice.id,
      status: 'invoiced',
    });
  }
}

The key insight: modules communicate through interfaces, not direct implementation references. When you later extract the billing module into its own service, you replace the implementation behind the interface. The calling code does not change.

Phase 3: Extract the First Service

Choose a module that is:

Well-bounded (few incoming dependencies)
Independently valuable
Not on the critical path (if the extraction has problems, it should not take down the whole system)

The Routing Layer

Use a proxy or feature flag to route traffic between the monolith and the new service:

Laravel: Switchable Implementation

// app/Billing/BillingServiceProvider.php
class BillingServiceProvider extends ServiceProvider
{
    public function register(): void
    {
        $this->app->bind(Contracts\BillingService::class, function ($app) {
            $useNewService = config('features.billing_service_v2', false);

            if ($useNewService) {
                return new HttpBillingServiceClient(
                    config('services.billing.url'),
                    config('services.billing.api_key'),
                );
            }

            return new Services\BillingServiceImpl();
        });
    }
}

// The HTTP client talks to the extracted billing service
class HttpBillingServiceClient implements Contracts\BillingService
{
    public function __construct(
        private string $baseUrl,
        private string $apiKey,
    ) {}

    public function createInvoice(string $customerId, array $lineItems): Invoice
    {
        $response = Http::withToken($this->apiKey)
            ->timeout(10)
            ->retry(3, 100)
            ->post("{$this->baseUrl}/api/invoices", [
                'customer_id' => $customerId,
                'line_items' => $lineItems,
            ]);

        if ($response->failed()) {
            throw new BillingServiceException("Failed to create invoice: " . $response->body());
        }

        return Invoice::fromArray($response->json());
    }
}

Node.js: Strategy Pattern Switch

import type { BillingService } from './contracts';
import { LocalBillingService } from './services/billing-service';
import { RemoteBillingService } from './services/remote-billing-service';

export function createBillingService(): BillingService {
  if (process.env.BILLING_SERVICE_V2 === 'true') {
    return new RemoteBillingService(
      process.env.BILLING_SERVICE_URL!,
      process.env.BILLING_SERVICE_API_KEY!
    );
  }

  return new LocalBillingService();
}

class RemoteBillingService implements BillingService {
  constructor(
    private baseUrl: string,
    private apiKey: string,
  ) {}

  async createInvoice(customerId: string, lineItems: LineItem[]): Promise<Invoice> {
    const response = await fetch(`${this.baseUrl}/api/invoices`, {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'Authorization': `Bearer ${this.apiKey}`,
      },
      body: JSON.stringify({ customer_id: customerId, line_items: lineItems }),
    });

    if (!response.ok) {
      throw new Error(`Billing service error: ${response.status}`);
    }

    return response.json();
  }
}

Phase 4: Data Migration Strategy

The hardest part of service extraction is data ownership. When the billing module becomes its own service, who owns the billing tables?

Shared Database Phase

Initially, the new service reads from the same database as the monolith. This avoids data migration complexity during the initial extraction.

Data Sync Phase

Introduce event-based data synchronisation. The new service maintains its own datastore, kept in sync via events:

class BillingDataSyncListener
{
    public function handle(CustomerUpdated $event): void
    {
        Http::post(config('services.billing.url') . '/api/sync/customer', [
            'customer_id' => $event->customerId,
            'name' => $event->name,
            'email' => $event->email,
        ]);
    }
}

Full Ownership Phase

The new service owns its data completely. The monolith no longer writes to billing tables. All access goes through the service API.

Phase 5: Zero-Downtime Cutover

The cutover from monolith to new service should be invisible to users:

Shadow mode: Both implementations run. The new service processes requests but responses come from the monolith. Compare outputs for correctness.
Canary rollout: Route 5% of traffic to the new service. Monitor error rates, latency, and correctness. Gradually increase.
Full rollout: Route 100% to the new service. Keep the monolith implementation for 2 weeks as a rollback option.
Cleanup: Remove the old implementation from the monolith.

class BillingServiceProvider extends ServiceProvider
{
    public function register(): void
    {
        $this->app->bind(Contracts\BillingService::class, function () {
            $strategy = config('features.billing_migration_phase');

            return match ($strategy) {
                'monolith' => new Services\BillingServiceImpl(),
                'shadow' => new ShadowBillingService(
                    primary: new Services\BillingServiceImpl(),
                    shadow: new HttpBillingServiceClient(/*...*/),
                ),
                'canary' => new CanaryBillingService(
                    legacy: new Services\BillingServiceImpl(),
                    modern: new HttpBillingServiceClient(/*...*/),
                    percentage: (int) config('features.billing_canary_percentage', 5),
                ),
                'modern' => new HttpBillingServiceClient(/*...*/),
                default => new Services\BillingServiceImpl(),
            };
        });
    }
}

Measuring Migration Success

Track these metrics throughout the migration:

Metric	Purpose
Deployment frequency	Should increase as modules become independent
Lead time for changes	Should decrease as codebase complexity drops
Test suite runtime	Should decrease per module
Incidents per deployment	Should decrease with smaller change sets
Mean time to recovery	Should decrease with independent rollback capability

Production Results from Past Migrations

Metric	Before (Monolith)	After (Modular)
Deployment frequency	1–2 per week	3–5 per day
Full test suite runtime	35 minutes	8 minutes (per module)
Average deploy risk score	High	Low (per module)
Time to onboard new developer	3 weeks	1 week
Query execution time	1.8s average	180ms average (60% reduction)
System performance	Baseline	40% improvement

Key Takeaways

Never rewrite. Always migrate incrementally. The strangler fig pattern lets you replace the monolith piece by piece while keeping the system running.
Establish boundaries before extracting. Enforce module interfaces within the monolith first. This makes extraction a configuration change, not a rewrite.
Start with a low-risk module. Pick something well-bounded and non-critical for your first extraction. Build confidence before tackling core business logic.
Use feature flags for cutover. Shadow mode, canary rollouts, and instant rollback make the migration safe. Never do a big bang switchover.
Solve data ownership explicitly. Shared database → event-based sync → full ownership is the safest data migration path.
Measure continuously. Deployment frequency, test runtime, and incident rate tell you whether the migration is actually improving things.

Conclusion

Migrating from a monolith to a modular architecture is not a technical project — it is an engineering discipline applied over weeks and months. The strangler fig pattern makes it safe. Interface-first module design makes it clean. Feature flags make it reversible. And continuous measurement makes it accountable.

Whether you are working in Laravel or Node.js, the approach is the same: understand what you have, enforce boundaries, extract behind interfaces, migrate data carefully, and cut over gradually. The monolith did not become painful overnight, and the fix will not happen overnight either. But each step makes the system better, and the cumulative impact is transformative.

Built a Laravel-Inspired Framework in Node.js (Here’s Why) - NetPress

Mon, 27 Apr 2026 14:30:01 +0000

For years, I’ve been working with Laravel.

It gave me something most Node.js ecosystems don’t:
structure, clarity, and speed of development.

But every time I switched to Node.js, I felt like I was rebuilding the same things:

routing structure
middleware flow
validation
auth patterns
project organization

Everything felt… fragmented.

So I decided to build my own solution.

The Problem

Node.js is powerful, but:

too many choices
no clear “standard” architecture
a lot of boilerplate
every project looks different

Compare that to Laravel:

consistent structure
batteries included
clean developer experience

That’s what I wanted in Node.

The Idea

Build a framework that feels like Laravel…
but runs on Node.js.

That’s how Netpress started.

What I Focused On

Instead of building “just another framework”, I focused on:

Predictable Structure

Every project follows a clear pattern:

Controllers
Middleware
Services
Models

No chaos. No guessing.

Clean Routing

Grouping, middleware, prefixes… just like Laravel:

router.group(authMiddleware, (router) => {
  router.get('/me', meHandler);
});

Middleware Pipeline

Simple and powerful request flow:

auth
rate limiting
logging

Rendering Support

You can use:

Vue
React

Server-driven or hybrid apps without overcomplication.

Developer Experience

Commands, structure, and conventions that make you move fast:

generate app
setup rendering
run migrations
seed data
Why Not Just Use Express?

You can.

But then you’ll rebuild:

structure
conventions
patterns
architecture decisions

Again… and again.

Netpress tries to remove that friction.

A Real Example

Instead of wiring everything manually:

app.use(authMiddleware);
app.get('/me', handler);

You get a structured flow:

router.group(authMiddleware, (router) => {
  router.get('/me', meHandler);
});

What I Learned

Building this taught me:

developers don’t just need tools, they need opinionated structure
consistency beats flexibility in most real-world apps
good DX is underrated

Here’s the docs:
https://admicaa.github.io/netpress-docs/

Would love to hear your thoughts.

Designing Audit-Proof Financial Workflows with Immutable Logs

Fri, 17 Apr 2026 10:09:35 +0000

In financial software, data does not just need to be correct — it needs to be provably correct. Regulators, auditors, and compliance teams do not take your word for it. They need an unbroken chain of evidence showing exactly what happened, when it happened, and who triggered it.

I have built financial platforms where a missing audit trail meant weeks of manual reconciliation. I have also built systems where every state change was captured in an append-only log that could answer any auditor's question in seconds. The difference is not complexity — it is intentional design.

This article covers how to build audit-proof financial workflows using immutable event logs, covering architecture decisions, implementation patterns in both Laravel and Node.js, and the operational practices that make the system trustworthy under scrutiny.

Why Mutable Records Break Under Audit

Most web applications store the current state of a record. When an invoice status changes from "pending" to "paid," the database row is updated in place. The previous state is gone.

This works fine for most applications. For financial systems, it is a liability:

No history: You cannot prove what the invoice status was yesterday at 3pm.
No attribution: You cannot tell who changed the status or why.
No reconciliation path: When numbers do not match, there is no trail to follow.
No tamper evidence: A modified record looks identical to a legitimate one.

Financial regulations — PCI DSS, SOX, FCA guidelines — require that systems maintain a complete, tamper-evident record of all financial transactions and state changes. An UPDATE statement destroys exactly the evidence you are required to preserve.

The Immutable Log Pattern

The solution is to never update or delete financial records. Instead, every change is recorded as a new, append-only event:

[Event 1] Invoice #1042 CREATED — amount: £5,000 — by: user_42 — at: 2025-03-01T09:15:00Z
[Event 2] Invoice #1042 APPROVED — approved_by: user_15 — at: 2025-03-01T14:30:00Z
[Event 3] Invoice #1042 PAYMENT_RECEIVED — amount: £5,000 — ref: PAY_8821 — at: 2025-03-05T11:00:00Z
[Event 4] Invoice #1042 RECONCILED — matched_to: BANK_TXN_4401 — at: 2025-03-06T08:45:00Z

The current state of the invoice is derived by replaying the events in order. The audit trail is the events themselves. Nothing is lost, nothing is overwritten.

Architecture Overview

[Client Request]
       |
       v
[Application Layer]
  - Validate business rules
  - Create event record
       |
       v
[DB Transaction]
  - Write event to audit_events table (append-only)
  - Update materialised view / current-state table
       |
       v
[Audit Events Table]           [Current State Table]
  (immutable, append-only)      (derived, rebuildable)
       |
       v
[Async Consumers]
  - Compliance reporting
  - Reconciliation engine
  - Notification service

The critical design decision: the audit events table is the source of truth. The current-state table is a projection that can be rebuilt from events at any time.

Implementation in Laravel

Audit Events Migration

Schema::create('audit_events', function (Blueprint $table) {
    $table->uuid('id')->primary();
    $table->string('aggregate_type');
    $table->string('aggregate_id');
    $table->unsignedBigInteger('sequence_number');
    $table->string('event_type');
    $table->json('payload');
    $table->json('metadata');
    $table->string('actor_id');
    $table->string('actor_type');
    $table->string('ip_address')->nullable();
    $table->string('checksum');
    $table->timestamp('occurred_at');
    $table->timestamp('created_at');

    $table->unique(['aggregate_type', 'aggregate_id', 'sequence_number']);
    $table->index(['aggregate_type', 'aggregate_id']);
    $table->index('event_type');
    $table->index('occurred_at');
    $table->index('actor_id');
});

The checksum column stores a hash of the event data plus the previous event's checksum, forming a hash chain. Any tampering with a historical record breaks the chain.

Audit Event Service

namespace App\Services;

use App\Models\AuditEvent;
use Illuminate\Support\Facades\DB;
use Illuminate\Support\Str;

class AuditEventService
{
    public function record(
        string $aggregateType,
        string $aggregateId,
        string $eventType,
        array $payload,
        string $actorId,
        string $actorType = 'user',
        ?string $ipAddress = null,
    ): AuditEvent {
        return DB::transaction(function () use (
            $aggregateType, $aggregateId, $eventType,
            $payload, $actorId, $actorType, $ipAddress
        ) {
            $lastEvent = AuditEvent::where('aggregate_type', $aggregateType)
                ->where('aggregate_id', $aggregateId)
                ->orderByDesc('sequence_number')
                ->lockForUpdate()
                ->first();

            $sequenceNumber = $lastEvent ? $lastEvent->sequence_number + 1 : 1;
            $previousChecksum = $lastEvent?->checksum ?? 'GENESIS';

            $eventData = [
                'aggregate_type' => $aggregateType,
                'aggregate_id' => $aggregateId,
                'sequence_number' => $sequenceNumber,
                'event_type' => $eventType,
                'payload' => $payload,
                'actor_id' => $actorId,
                'occurred_at' => now(),
            ];

            $checksum = hash('sha256', $previousChecksum . json_encode($eventData));

            return AuditEvent::create([
                'id' => Str::uuid(),
                ...$eventData,
                'metadata' => [
                    'previous_checksum' => $previousChecksum,
                    'schema_version' => '1.0',
                ],
                'actor_type' => $actorType,
                'ip_address' => $ipAddress,
                'checksum' => $checksum,
                'created_at' => now(),
            ]);
        });
    }

    public function verifyChain(string $aggregateType, string $aggregateId): bool
    {
        $events = AuditEvent::where('aggregate_type', $aggregateType)
            ->where('aggregate_id', $aggregateId)
            ->orderBy('sequence_number')
            ->get();

        $previousChecksum = 'GENESIS';

        foreach ($events as $event) {
            $eventData = [
                'aggregate_type' => $event->aggregate_type,
                'aggregate_id' => $event->aggregate_id,
                'sequence_number' => $event->sequence_number,
                'event_type' => $event->event_type,
                'payload' => $event->payload,
                'actor_id' => $event->actor_id,
                'occurred_at' => $event->occurred_at,
            ];

            $expectedChecksum = hash('sha256', $previousChecksum . json_encode($eventData));

            if ($expectedChecksum !== $event->checksum) {
                return false;
            }

            $previousChecksum = $event->checksum;
        }

        return true;
    }

    public function getHistory(
        string $aggregateType,
        string $aggregateId
    ): \Illuminate\Support\Collection {
        return AuditEvent::where('aggregate_type', $aggregateType)
            ->where('aggregate_id', $aggregateId)
            ->orderBy('sequence_number')
            ->get();
    }
}

Using It in a Financial Workflow

class InvoiceService
{
    public function __construct(
        private AuditEventService $auditService,
    ) {}

    public function createInvoice(array $data, string $userId, string $ip): Invoice
    {
        return DB::transaction(function () use ($data, $userId, $ip) {
            $invoice = Invoice::create([
                'number' => $this->generateInvoiceNumber(),
                'client_id' => $data['client_id'],
                'amount' => $data['amount'],
                'currency' => $data['currency'],
                'status' => 'draft',
                'due_date' => $data['due_date'],
            ]);

            $this->auditService->record(
                aggregateType: 'invoice',
                aggregateId: (string) $invoice->id,
                eventType: 'invoice.created',
                payload: [
                    'number' => $invoice->number,
                    'amount' => $invoice->amount,
                    'currency' => $invoice->currency,
                    'client_id' => $invoice->client_id,
                ],
                actorId: $userId,
                ipAddress: $ip,
            );

            return $invoice;
        });
    }

    public function approveInvoice(Invoice $invoice, string $approverId, string $ip): Invoice
    {
        return DB::transaction(function () use ($invoice, $approverId, $ip) {
            $invoice->update(['status' => 'approved']);

            $this->auditService->record(
                aggregateType: 'invoice',
                aggregateId: (string) $invoice->id,
                eventType: 'invoice.approved',
                payload: [
                    'previous_status' => 'draft',
                    'new_status' => 'approved',
                ],
                actorId: $approverId,
                ipAddress: $ip,
            );

            return $invoice->fresh();
        });
    }
}

Implementation in Node.js

Prisma Schema

model AuditEvent {
  id              String   @id @default(uuid())
  aggregateType   String   @map("aggregate_type")
  aggregateId     String   @map("aggregate_id")
  sequenceNumber  Int      @map("sequence_number")
  eventType       String   @map("event_type")
  payload         Json
  metadata        Json
  actorId         String   @map("actor_id")
  actorType       String   @map("actor_type") @default("user")
  ipAddress       String?  @map("ip_address")
  checksum        String
  occurredAt      DateTime @map("occurred_at")
  createdAt       DateTime @default(now()) @map("created_at")

  @@unique([aggregateType, aggregateId, sequenceNumber])
  @@index([aggregateType, aggregateId])
  @@index([eventType])
  @@index([occurredAt])
  @@index([actorId])
  @@map("audit_events")
}

Audit Event Service

import { PrismaClient } from '@prisma/client';
import crypto from 'crypto';

const prisma = new PrismaClient();

interface RecordEventParams {
  aggregateType: string;
  aggregateId: string;
  eventType: string;
  payload: Record<string, unknown>;
  actorId: string;
  actorType?: string;
  ipAddress?: string;
}

export async function recordAuditEvent(params: RecordEventParams) {
  return prisma.$transaction(async (tx) => {
    const lastEvent = await tx.auditEvent.findFirst({
      where: {
        aggregateType: params.aggregateType,
        aggregateId: params.aggregateId,
      },
      orderBy: { sequenceNumber: 'desc' },
    });

    const sequenceNumber = lastEvent ? lastEvent.sequenceNumber + 1 : 1;
    const previousChecksum = lastEvent?.checksum ?? 'GENESIS';

    const eventData = {
      aggregate_type: params.aggregateType,
      aggregate_id: params.aggregateId,
      sequence_number: sequenceNumber,
      event_type: params.eventType,
      payload: params.payload,
      actor_id: params.actorId,
      occurred_at: new Date().toISOString(),
    };

    const checksum = crypto
      .createHash('sha256')
      .update(previousChecksum + JSON.stringify(eventData))
      .digest('hex');

    return tx.auditEvent.create({
      data: {
        aggregateType: params.aggregateType,
        aggregateId: params.aggregateId,
        sequenceNumber,
        eventType: params.eventType,
        payload: params.payload,
        metadata: {
          previous_checksum: previousChecksum,
          schema_version: '1.0',
        },
        actorId: params.actorId,
        actorType: params.actorType ?? 'user',
        ipAddress: params.ipAddress,
        checksum,
        occurredAt: new Date(),
      },
    });
  });
}

export async function verifyAuditChain(
  aggregateType: string,
  aggregateId: string
): Promise<boolean> {
  const events = await prisma.auditEvent.findMany({
    where: { aggregateType, aggregateId },
    orderBy: { sequenceNumber: 'asc' },
  });

  let previousChecksum = 'GENESIS';

  for (const event of events) {
    const eventData = {
      aggregate_type: event.aggregateType,
      aggregate_id: event.aggregateId,
      sequence_number: event.sequenceNumber,
      event_type: event.eventType,
      payload: event.payload,
      actor_id: event.actorId,
      occurred_at: event.occurredAt.toISOString(),
    };

    const expectedChecksum = crypto
      .createHash('sha256')
      .update(previousChecksum + JSON.stringify(eventData))
      .digest('hex');

    if (expectedChecksum !== event.checksum) {
      return false;
    }

    previousChecksum = event.checksum;
  }

  return true;
}

export async function getAggregateHistory(
  aggregateType: string,
  aggregateId: string
) {
  return prisma.auditEvent.findMany({
    where: { aggregateType, aggregateId },
    orderBy: { sequenceNumber: 'asc' },
  });
}

Express Route for Audit Queries

import { Router } from 'express';

const router = Router();

router.get('/audit/:aggregateType/:aggregateId', async (req, res) => {
  const { aggregateType, aggregateId } = req.params;

  const history = await getAggregateHistory(aggregateType, aggregateId);

  res.json({
    aggregate: { type: aggregateType, id: aggregateId },
    eventCount: history.length,
    events: history.map((e) => ({
      sequence: e.sequenceNumber,
      type: e.eventType,
      payload: e.payload,
      actor: e.actorId,
      occurredAt: e.occurredAt,
    })),
  });
});

router.get('/audit/:aggregateType/:aggregateId/verify', async (req, res) => {
  const { aggregateType, aggregateId } = req.params;
  const valid = await verifyAuditChain(aggregateType, aggregateId);

  res.json({
    aggregate: { type: aggregateType, id: aggregateId },
    chainValid: valid,
    verifiedAt: new Date().toISOString(),
  });
});

Retention and Archival Strategy

Audit logs grow fast. A system processing 10,000 transactions per day generates millions of events per year. You need a retention strategy:

Hot storage (0–90 days): Primary database. Full query capability. Used for day-to-day operations and recent audits.
Warm storage (90 days–2 years): Move older events to a read-optimised store (e.g., partitioned table, read replica, or columnar database). Still queryable but not on the critical path.
Cold storage (2+ years): Archive to object storage (S3, GCS) in a structured format (Parquet, JSON Lines). Retained for regulatory compliance periods (typically 5–7 years for financial data).

Laravel Archival Command

class ArchiveAuditEvents extends Command
{
    protected $signature = 'audit:archive {--older-than=90}';

    public function handle(): void
    {
        $cutoff = now()->subDays((int) $this->option('older-than'));

        $events = AuditEvent::where('occurred_at', '<', $cutoff)
            ->orderBy('occurred_at')
            ->cursor();

        $batch = [];
        $batchCount = 0;

        foreach ($events as $event) {
            $batch[] = $event->toArray();

            if (count($batch) >= 10000) {
                $this->uploadBatch($batch, $batchCount);
                $batch = [];
                $batchCount++;
            }
        }

        if (!empty($batch)) {
            $this->uploadBatch($batch, $batchCount);
        }

        AuditEvent::where('occurred_at', '<', $cutoff)->delete();

        $this->info("Archived and purged events older than {$cutoff->toDateString()}.");
    }

    private function uploadBatch(array $batch, int $index): void
    {
        $filename = sprintf('audit-archive/%s/batch-%04d.json', now()->format('Y/m'), $index);

        Storage::disk('s3')->put(
            $filename,
            collect($batch)->map(fn ($e) => json_encode($e))->implode("\n")
        );
    }
}

Reconciliation with Immutable Logs

One of the most valuable outcomes of immutable logs is automated reconciliation. Instead of manually comparing spreadsheets, you can programmatically verify that every financial event has a matching counterpart:

class ReconciliationService
{
    public function reconcilePayments(string $date): array
    {
        $internalEvents = AuditEvent::where('event_type', 'payment.completed')
            ->whereDate('occurred_at', $date)
            ->get()
            ->keyBy(fn ($e) => $e->payload['gateway_reference']);

        $bankStatements = $this->fetchBankStatements($date);

        $matched = [];
        $unmatchedInternal = [];
        $unmatchedBank = [];

        foreach ($bankStatements as $statement) {
            if ($internalEvents->has($statement->reference)) {
                $matched[] = $statement->reference;
                $internalEvents->forget($statement->reference);
            } else {
                $unmatchedBank[] = $statement;
            }
        }

        $unmatchedInternal = $internalEvents->values()->all();

        return [
            'date' => $date,
            'matched_count' => count($matched),
            'unmatched_internal' => count($unmatchedInternal),
            'unmatched_bank' => count($unmatchedBank),
            'discrepancies' => [...$unmatchedInternal, ...$unmatchedBank],
        ];
    }
}

Production Results

After implementing immutable audit logging across financial platforms:

Metric	Before	After
Reconciliation time (weekly)	4+ hours manual	15 minutes automated
Audit preparation time	2–3 weeks	2 days
Unresolved discrepancies	8–12 per month	0–1 per month
Compliance audit findings	Multiple per review	Zero material findings
Data dispute resolution time	3–5 days	< 1 hour

Key Takeaways

Never update financial records in place. Append new events instead. The current state is a projection of the event history.
Use hash chains for tamper evidence. Each event's checksum includes the previous event's checksum. Any modification breaks the chain.
Record who, what, when, and why. Every event needs an actor, a timestamp, and the business context. IP addresses and session identifiers add forensic value.
Plan for retention from day one. Audit logs grow quickly. Tiered storage (hot/warm/cold) keeps costs manageable while satisfying compliance requirements.
Automate reconciliation. Immutable logs enable programmatic reconciliation that replaces hours of manual spreadsheet comparison.
Write events and business data in the same transaction. If they are not atomic, you risk inconsistency between your source of truth and your audit trail.

Conclusion

Audit-proof financial workflows are not about generating more logs — they are about designing systems where every state change is captured, chained, and verifiable. Append-only writes, hash-chain integrity, and tiered retention create a system that answers any auditor's question with evidence, not explanations.

Whether you build in Laravel or Node.js, the patterns are the same. This infrastructure pays dividends every time a regulator asks a question or a discrepancy needs resolution.

Building Crypto Payments into Telegram: A Technical Deep Dive into telegram-wallet-php

Wed, 15 Apr 2026 12:56:51 +0000

Telegram is no longer just a messaging app. With an audience exceeding 1 billion monthly active users by early 2025 and deep integration with the TON blockchain, the platform has become serious infrastructure for commerce and decentralized applications. Developers building bots and Telegram Mini Apps (TMAs) now have a genuine opportunity to monetize their products by accepting cryptocurrency payments directly within the chat interface.

The official Wallet Pay API makes this possible, allowing merchants to accept TON, USDT, BTC, and NOT from users without redirecting them to external sites. However, integrating a raw REST API is never trivial. A developer must implement authentication, construct request payloads, verify cryptographic webhook signatures, and map HTTP status codes to meaningful errors.

This is exactly the problem that telegram-wallet-php solves. Created by Igor Sazonov, this open-source PHP SDK wraps the Wallet Pay API v1.2.0 in a clean, modern, and strictly typed interface. The library works as a standalone solution in any PHP 8.1+ project and provides first-class integration for Laravel (versions 9 through 13).

This post is a technical walkthrough of the current implementation: architectural shape, webhook security, error handling, and production gotchas.

Architectural Shape and Typing

At code level, telegram-wallet-php follows a fairly direct layered structure:

Contracts (interfaces) for the main client
Data Transfer Objects (DTOs) for request payloads and API responses
PHP 8.1 Enums for statuses and event types
Typed exceptions mapped to HTTP status codes
Laravel integration (Service Provider, Facade, Middleware)
Webhook handling classes

In practical terms, the main entry point is the WalletPayClient class, which implements WalletPayClientInterface. Its constructor accepts a PSR-18 compatible HTTP client, which is critical for unit testing — you can inject a mock client to verify your application logic without making real HTTP requests.

The library heavily uses DTOs to represent both request payloads and API responses. This is a significant advantage over an array-based approach. Using named arguments (a PHP 8.0 feature) makes the intent of each parameter crystal clear, and your IDE will warn you if you pass the wrong type.

$request = new CreateOrderRequest(
    amount: new MoneyAmount('USD', '9.99'),
    description: 'Premium subscription',
    externalId: 'ORDER-123',
    timeoutSeconds: 3600,
    customerTelegramUserId: 123456789
);

Order statuses and webhook event types are represented as PHP 8.1 Enums, eliminating the risk of typos when comparing strings. The order lifecycle follows a clear state machine: from ACTIVE (awaiting payment) to PAID (successful payment), EXPIRED (timeout reached), or CANCELLED (aborted).

Webhook Security: The Critical Path

Webhooks are the mechanism by which Wallet Pay notifies your server about payment outcomes. Implementing this correctly is the most security-sensitive part of any payment integration.

When Wallet Pay sends a webhook, it includes two headers: WalletPay-Timestamp (a nanosecond timestamp) and WalletPay-Signature (a Base64-encoded HMAC-SHA256 signature). The signature is computed based on the HTTP method, URI path, timestamp, and request body.

The WebhookVerifier class handles all this cryptography automatically. The developer does not need to implement HMAC verification manually, which is a major security benefit, as manual HMAC implementations are frequently a source of vulnerabilities.

In Laravel, the package provides a ready-to-use walletpay.webhook Middleware. Once registered, the webhook routing becomes extremely concise: the Middleware verifies the signature, and the controller simply parses the events and updates the database state.

Route::post('/webhook/walletpay', function (Request $request, WebhookVerifier $verifier) {
    $events = $verifier->parseWebhookEvents($request->getContent());
    
    foreach ($events as $event) {
        if ($event->type === WebhookEventType::ORDER_PAID) {
            // Payment successful! Update status in DB
        }
    }
    
    return response('OK', 200);
})->middleware('walletpay.webhook');

Error Handling: Typed Exceptions

One of the most developer-friendly aspects of telegram-wallet-php is its exception hierarchy. Instead of catching a generic \Exception and trying to parse the error message, you can precisely handle each failure scenario.

The exception hierarchy maps directly to the HTTP status codes defined in the Wallet Pay API documentation. For example, InvalidRequestException corresponds to status 400, RateLimitException to 429 (allowing you to implement exponential backoff and retries), and InvalidWebhookSignatureException is thrown when webhook signature verification fails.

Important Production Gotchas

Based on the documentation and source code, there are several important considerations for production deployment:

First, the customerTelegramUserId field is mandatory, and only the specified Telegram user can pay for the order. This is a security feature that prevents payment link sharing, but it means you cannot create a generic "pay now" link — you must create a unique order for each user.

Second, the externalId field serves as an idempotency key. If you create an order with the same externalId twice (for example, due to a retry on a network timeout), the API will return the existing order rather than creating a duplicate. You should generate your externalId deterministically.

Third, the Wallet Pay signature verification includes the exact URI path of the webhook endpoint. The path must match exactly what you configured in your store settings, including the presence or absence of a trailing slash. A mismatch will cause all webhook verifications to fail.

The Bottom Line

The telegram-wallet-php library is a well-designed, production-ready SDK that significantly lowers the barrier to integrating cryptocurrency payments into PHP applications and Telegram bots. Leveraging modern PHP 8.1 features (Enums, readonly properties, named arguments, and typed DTOs) makes the code safer, more readable, and easier to maintain.

The first-class Laravel integration is a genuine competitive advantage. The combination of a Service Provider, Facade, and Middleware means that Laravel developers can add Telegram crypto payments to their applications with minimal boilerplate, following conventions they already know. The built-in webhook signature verification eliminates a common source of vulnerabilities in payment integrations.

For developers building products in the rapidly growing Telegram Mini App ecosystem, this library is an excellent foundation.

Engineering Real-Time Delivery Tracking That Increased Checkout Conversions by 20%

Thu, 09 Apr 2026 22:37:20 +0000

In e-commerce and on-demand delivery, the moment a user clicks "Place Order" begins an anxiety cycle. Where is my order? When will it arrive? This uncertainty kills conversions.

Between November 2020 and July 2021, I worked as a Full-Stack Developer at Viaduct, where I engineered a real-time delivery tracking system for an on-demand platform serving 5,000+ active users. The platform connected customers with local vendors for same-day delivery. Before I joined, users were abandoning carts and cancelling orders at alarming rates because they had zero visibility into delivery status.

This article details how I designed and built the tracking system — Google Maps integration, WebSocket-powered live updates, a Vue.js reactive interface, and the Laravel backend tying it together. The result: a 20% increase in checkout conversions.

The Problem: Delivery Opacity Was Killing Revenue

When I joined Viaduct, the delivery platform was functional but opaque. Users placed orders, received a confirmation email, and waited. The only updates were manual — a dispatcher marked orders "out for delivery" when a driver departed and "delivered" when reported back.

The consequences were measurable:

Cart abandonment: 32% of users abandoned at checkout. Exit surveys showed the top reason was "uncertain delivery time."

Post-order cancellations: 15% of completed checkouts were cancelled within 30 minutes, most citing "no delivery updates."

Support overload: 200+ daily calls asking "where is my order?" — each averaging 4 minutes, consuming 13 person-hours daily.

Driver accountability gaps: Without GPS tracking, there was no way to verify delivery times, identify route inefficiencies, or resolve disputes.

My Role: Full-Stack Architect of the Tracking System

I designed and built the entire real-time tracking system end-to-end: the Laravel backend infrastructure, Google Maps API integration, the WebSocket communication layer, and the Vue.js frontend tracking interface. I owned it from initial technical design through production deployment and post-launch optimisation.

Technical Deep Dive: Building the Real-Time Tracking Infrastructure

1. Driver Location Collection Architecture

The foundation of real-time tracking is reliable location data. I built a location reporting service on drivers' devices, transmitting GPS coordinates at configurable intervals.

class DriverLocationController extends Controller
{
    public function updateLocation(UpdateLocationRequest $request): JsonResponse
    {
        $driver = $request->user();
        $validated = $request->validated();

        $location = DriverLocation::create([
            'driver_id' => $driver->id,
            'latitude' => $validated['latitude'],
            'longitude' => $validated['longitude'],
            'accuracy' => $validated['accuracy'],
            'speed' => $validated['speed'] ?? null,
            'heading' => $validated['heading'] ?? null,
            'recorded_at' => Carbon::createFromTimestamp($validated['timestamp']),
        ]);

        if ($activeDelivery = $driver->activeDelivery) {
            $this->broadcastLocationUpdate($activeDelivery, $location);
            $this->updateEstimatedArrival($activeDelivery, $location);
        }

        return response()->json(['status' => 'recorded'], 200);
    }

    private function broadcastLocationUpdate(Delivery $delivery, DriverLocation $location): void
    {
        Redis::publish("delivery:{$delivery->id}:location", json_encode([
            'delivery_id' => $delivery->id,
            'driver' => [
                'latitude' => $location->latitude,
                'longitude' => $location->longitude,
                'heading' => $location->heading,
            ],
            'timestamp' => $location->recorded_at->toIso8601String(),
        ]));
    }
}

Location updates published to Redis channels, bridging the Laravel backend and the WebSocket server. This decoupled location ingestion (high-frequency HTTP POSTs from drivers) from location broadcasting (persistent WebSocket connections to customers), allowing each to scale independently.

2. Google Maps Integration for ETA Calculation

Accurate ETAs were critical. I integrated the Google Maps Directions API with live traffic data:

class GoogleMapsService
{
    public static function getDirections(array $origin, array $destination): ?DirectionsResult
    {
        $response = Http::get('https://maps.googleapis.com/maps/api/directions/json', [
            'origin' => "{$origin['lat']},{$origin['lng']}",
            'destination' => "{$destination['lat']},{$destination['lng']}",
            'mode' => 'driving',
            'departure_time' => 'now',
            'traffic_model' => 'best_guess',
            'key' => config('services.google_maps.api_key'),
        ]);

        if (!$response->successful() || $response->json('status') !== 'OK') {
            return null;
        }

        $leg = $response->json('routes.0.legs.0');
        return new DirectionsResult(
            durationMinutes: (int) ceil($leg['duration_in_traffic']['value'] / 60),
            distanceKm: round($leg['distance']['value'] / 1000, 1),
            polyline: $response->json('routes.0.overview_polyline.points'),
        );
    }
}

Using departure_time=now and traffic_model=best_guess ensured ETAs reflected live traffic — during rush hours, static estimates might show 10 minutes while actual time was 25. However, calling Google Maps on every location update (every 10 seconds per driver) would be prohibitively expensive. I implemented intelligent throttling using Haversine distance:

class ETAService
{
    private const ETA_CACHE_TTL = 60;
    private const MIN_DISTANCE_FOR_RECALC = 0.2; // km

    public function shouldRecalculateETA(Delivery $delivery, DriverLocation $newLocation): bool
    {
        if (!$delivery->eta_updated_at) return true;
        if (now()->diffInSeconds($delivery->eta_updated_at) < self::ETA_CACHE_TTL) return false;

        $lastCalcLocation = Cache::get("eta_calc_location:{$delivery->id}");
        if (!$lastCalcLocation) return true;

        return $this->haversineDistance(
            $lastCalcLocation['lat'], $lastCalcLocation['lng'],
            $newLocation->latitude, $newLocation->longitude
        ) >= self::MIN_DISTANCE_FOR_RECALC;
    }

    private function haversineDistance(float $lat1, float $lon1, float $lat2, float $lon2): float
    {
        $dLat = deg2rad($lat2 - $lat1);
        $dLon = deg2rad($lon2 - $lon1);
        $a = sin($dLat/2)**2 + cos(deg2rad($lat1)) * cos(deg2rad($lat2)) * sin($dLon/2)**2;
        return 6371 * 2 * atan2(sqrt($a), sqrt(1 - $a));
    }
}

ETAs were recalculated only when the driver moved 200m+ and 60+ seconds had elapsed, reducing Google Maps API calls by ~80%.

3. WebSocket Server for Live Customer Updates

The real-time frontend was powered by a Node.js WebSocket server subscribed to Redis channels:

const wss = new WebSocket.Server({ port: 6001 });
const subscriber = new Redis(process.env.REDIS_URL);
const deliverySubscriptions = new Map();

wss.on('connection', (ws) => {
  ws.on('message', (raw) => {
    const msg = JSON.parse(raw);
    if (msg.type === 'subscribe_delivery') {
      if (!deliverySubscriptions.has(msg.deliveryId)) {
        deliverySubscriptions.set(msg.deliveryId, new Set());
        subscriber.subscribe(
          `delivery:${msg.deliveryId}:location`,
          `delivery:${msg.deliveryId}:eta`,
          `delivery:${msg.deliveryId}:status`
        );
      }
      deliverySubscriptions.get(msg.deliveryId).add(ws);
    }
  });

  ws.on('close', () => {
    if (ws.deliveryId) {
      const subs = deliverySubscriptions.get(ws.deliveryId);
      if (subs) { subs.delete(ws); if (subs.size === 0) deliverySubscriptions.delete(ws.deliveryId); }
    }
  });
});

subscriber.on('message', (channel, message) => {
  const [, deliveryId, eventType] = channel.split(':');
  const subs = deliverySubscriptions.get(deliveryId);
  if (!subs) return;
  const payload = JSON.stringify({ type: `delivery_${eventType}`, data: JSON.parse(message) });
  for (const ws of subs) { if (ws.readyState === WebSocket.OPEN) ws.send(payload); }
});

The server was deliberately stateless — it bridged Redis pub/sub to WebSocket connections with no business logic, making it horizontally scalable.

4. Vue.js Real-Time Tracking Interface

The customer-facing tracking page used Vue.js Composition API. The core was a WebSocket composable with exponential backoff reconnection:

export function useDeliveryWebSocket(deliveryId) {
  const driverLocation = ref(null);
  const eta = ref(null);
  const deliveryStatus = ref('confirmed');
  let ws = null, reconnectAttempts = 0;

  function connect() {
    ws = new WebSocket(process.env.VUE_APP_WS_URL);
    ws.onopen = () => {
      reconnectAttempts = 0;
      ws.send(JSON.stringify({ type: 'subscribe_delivery', deliveryId }));
    };
    ws.onmessage = ({ data }) => {
      const msg = JSON.parse(data);
      if (msg.type === 'delivery_location') driverLocation.value = msg.data.driver;
      else if (msg.type === 'delivery_eta') eta.value = msg.data.eta_minutes;
      else if (msg.type === 'delivery_status') deliveryStatus.value = msg.data.status;
    };
    ws.onclose = () => {
      if (reconnectAttempts < 10)
        setTimeout(connect, Math.min(1000 * 2 ** reconnectAttempts++, 30000));
    };
  }
  return { driverLocation, eta, deliveryStatus, connect, disconnect: () => ws?.close() };
}

The map component initialised Google Maps, rendered destination and driver markers, and animated the driver marker between positions using cubic easing. Without animation, the marker would "teleport" every 10 seconds — with smooth interpolation, users perceived continuous movement, dramatically improving perceived quality.

5. Delivery Status Lifecycle and Performance

Every status transition published to Redis for real-time updates, sent push notifications, and recorded metrics:

class Delivery extends Model
{
    public function markPickedUp(): void
    {
        $this->update(['status' => 'picked_up', 'picked_up_at' => now()]);
        Redis::publish("delivery:{$this->id}:status", json_encode([
            'delivery_id' => $this->id, 'status' => 'picked_up',
            'driver' => ['name' => $this->driver->name, 'phone' => $this->driver->phone],
        ]));
        $this->order->customer->notify(new DeliveryPickedUpNotification($this));
    }

    public function markDelivered(): void
    {
        $this->update(['status' => 'delivered', 'delivered_at' => now()]);
        Redis::publish("delivery:{$this->id}:status", json_encode([
            'delivery_id' => $this->id, 'status' => 'delivered',
        ]));
        $this->order->customer->notify(new DeliveryCompletedNotification($this));
        DeliveryMetric::create([
            'delivery_id' => $this->id, 'driver_id' => $this->driver_id,
            'estimated_minutes' => $this->estimated_arrival_minutes,
            'actual_minutes' => $this->picked_up_at?->diffInMinutes($this->delivered_at),
        ]);
    }
}

The DeliveryMetric model enabled comparing estimated vs. actual delivery times, identifying underperforming drivers and slow routes.

For performance at scale, I buffered location writes in Redis and flushed to PostgreSQL in batches every 30 seconds, reducing database write load by 90% while maintaining real-time delivery through the pub/sub layer. Vendor discovery pages used PostGIS spatial queries (ST_DWithin, ST_Distance) with aggressive caching, returning results in under 50ms across thousands of records.

The Results: Measurable Business Impact

The system launched after eight weeks of development. Results over a 60-day observation period:

Metric	Before	After	Change
Checkout conversion rate	68%	88%	+20 percentage points
Post-order cancellation rate	15%	4%	73% reduction
"Where is my order?" support calls	200+/day	~35/day	82% reduction
Customer satisfaction score	3.4/5	4.3/5	26% improvement
Active platform users	~3,200	5,000+	56% growth
Tracking page views per order	0	4.2	New engagement channel

The support call reduction alone freed 11 person-hours daily — redirected to proactive customer outreach and vendor management.

Technical Lessons

Decouple ingestion from delivery. Location collection (Laravel) and broadcasting (Node.js WebSocket) had different performance profiles. Separate services connected by Redis allowed independent scaling.
Animate transitions, don't teleport. Users perceive smooth movement as real-time tracking and position jumps as a broken system.
Throttle expensive API calls intelligently. The Haversine check before ETA recalculation saved thousands of unnecessary Google Maps calls daily.
Buffer writes, stream reads. Batch-writing to the database while streaming through Redis provided both persistence and live performance.
Measure business metrics. WebSocket latency matters, but checkout conversion rate proved the system's value.

Don’t Pass Array or Variables to Laravel Blade Views Instead Do This

Wed, 08 Apr 2026 10:20:36 +0000

Are you a Laravel developer. Do you love Blade. It’s simple, expressive, and fits naturally with the framework. But let’s be honest, most projects eventually turn their Blade files into dumping grounds for random variables. The Controllers pass loose data, views end up receiving unstructured data, partials rely on implicit assumptions, and the whole setup becomes fragile and error-prone.

The Result?

No autocomplete.
Runtime errors from typos.
Partial views with zero contracts.
A mess that only grows as the app scales.

It doesn’t have to be this way. Blade files deserve the same contracts and structure we give to APIs, database models, or services. With a few clear practices, you can bring discipline, contracts, and structure to Blade.

This article will show you the complete approach.

The problem of passing data as arrays or variables in views — solved by introducing ViewModels as contracts.
Enable Autocomplete in Blade so your IDE actually helps.
Annotation to views and partials bound to their own ViewModels.
Lock down data structures with DTO classes for strict typing.
Establish Principles for sustainable Blade development.

Remember, we are only targeting blade for now. Not Twig or Antlr.

Grab a coffee — this is a long read. But by the end, you’ll never look at Blade the same way again.

The Crime Scene: What’s Wrong With “Array Soup” in Blade

Here’s the standard Laravel approach we’ve all seen in controllers.

class ProductController extends Controller
{
    public function index()
    {
		$products = Product::all();
		$categories = Category::all();
		$brand = Brand::all();
        $title = 'Products';
		
		return view('products.index', compact('products','categories','brands','title') );
    }
}

// Or may be

class ProductController extends Controller
{
    public function index()
    {
        return view('products.index', [
            'title' => 'Products',
            'products' => Product::all(),
            'categories' => Category::all(),
            'brand' => Brand::all(),	
        ]);
    }
}

// Or a little cleaner approach

class ProductController extends Controller
{
    public function index()
    {
		$data = [
            'title' => 'Products',
            'products' => Product::all(),
            'categories' => Category::all(),
            'brand' => Brand::all(),	
		];
		
		return view('products.index', $data);
    }
}

And here is how we do it for partials.

// pass no data, access product from current blade context inside partials/product.blade.php
@foreach ($products as $product)
    @include('products.partials.product')
@endforeach

// or pass some additional data
@foreach ($products as $product)
    @include('products.partials.product', ['editable' => $editable])
@endforeach

And finally for components.

@foreach ($products as $product)
    <x-product-row :name="$product->name" :price ="$product->price" />
@endforeach

The Old Lovely Blade

Here is how it works well.

<h1>{{ $title }}</h1>

<ul>
    @foreach ($products as $product)
        <li>{{ $product->name }} ({{ $product->price }})</li>
        {{-- or partial --}}
        @include('products.partials.product')        
        {{-- or component --}}
        <x-product-row :name="$product->name" :price ="$product->price" />
    @endforeach
</ul>

This works but ask yourself:

Do you actually remember all the variables passed to your views?
Do you get autocomplete in Blade to help you catch typos?
What about partials and includes — are you sure the data they rely on is really there?
If a teammate edits the controller, how do you even know the view won’t silently break?
How many times have you opened a Blade file and had no clue what’s in scope?

1. Introducing ViewModels: Contracts for Your Views

Instead of throwing arrays around, define a ViewModel, a simple DTO class. It declares exactly what data is expected.

<?php

namespace App\ViewModels;


class ProductsViewModel
{
    public string $title;
    public array $products;
    public array $categories;
    public array $brand;    
}

And controller.

class ProductController extends Controller
{
    public function index()
    {
        $viewModel = new ProductsViewModel();

        $viewModel->title = 'Products';
        $viewModel->products = Product::all();
        $viewModel->categories = Category::all();
        $viewModel->brands = Brand::all();        

        return view('products.index', ['model' => $viewModel]);
    }
}

Suggestion: Always pass view-model with name model for consistancy. This will help in autocomplete.

Now blade file will look like this.

<h1>{{ $model->title }}</h1>

<ul>
    @foreach ($model->products as $product)
        <li>{{ $product->name }} ({{ $product->price }})</li>
        {{-- or partial  --}}
        @include('products.partials.product',['model' => $product])  
        {{-- or component --}}
        <x-product-row :model="$product" />
    @endforeach
</ul>

@include('partials.brands', ['model' => $model->brands])
@include('partials.categories', ['model' => $model->categories])

Suggestion**: For partials and components, always pass data with name model** for consistancy. This will help in autocomplete._

Benefits:

The contract is explicit.
Adding or removing data requires updating the ViewModel.
Each view, partial or component has a single data access point $model to start with.

2. Installing Extension for Autocomplete

This step does not require any code setup but requires installing plugin/extension in your IDE. I use VS Code for Laravel development. I found an excellent extension PHP Tools by DevSense for VS Code which I used to use in Visual Studio when working with .Net framework. This extension is available for Cursor, Zed ,Visual Studio and VS Code. But if you are using a different editor you need to find similar extension.

Once installed we need to move to next step. Take a look at the feature list to find what's available.

Note: When installing PHP Tools I had to ditch Intellisense and Intelliphence but I still get all what they provide with PHP Tools.

3. Enabling Autocomplete in Blade

Even with ViewModels, Blade doesn’t automatically know the type of `$model`. The trick is to annotate it in blade views, partials and components:

// views/products/index.blade.php
@php
    /** @var \App\ViewModels\ProductsViewModel $model */
@endphp

<ul>
    @foreach ($model->products as $product)
        <li>{{ $product->name }} ({{ $product->price }})</li>
        {{-- or partial  --}}
        @include('products.partials.product')  
        {{-- or component --}}
        <x-product-row :name="$product->name" :price ="$product->price" />
    @endforeach
</ul>

You need to do same in partial or component. Here is partial.

// views/products/partials/product.blade.php
@php
    /** @var \App\Models\Product $model */
@endphp

<span>
    {{ $model->name }}
</span>

Finally, a component.

// views/components/product.blade.php
@php
    /** @var \App\View\Components\Product $model */
@endphp

<span>
    {{ $model->name }}
</span>

Now, in VS Code, typing `$model->` will bring up real autocomplete suggestions.

This is a game-changer:

No more guessing property names.
Mistyped variables get caught instantly.
New developers know exactly what’s available in the view.

4. Enforce Types at Runtime

Since now we are passing ViewModels into views, partials or components and defining annonations in each blade file, lets enforce blade to accept specific type of class. To do this i added two files.

TypedViewFactory – A custom view factory that parses `@var` declarations at the top of Blade files and enforces them.
TypedViewServiceProvider – Wires everything into Laravel automatically.

Checkout the code here.

The Result: if you declare a type in a Blade file, Laravel must pass the correct class, array, or collection. Otherwise, it throws an exception.

Declaring Types in Blade makes views predictable and strict.

Main View

{{-- products/index.blade.php --}}
@php /** @var App\ViewModels\ProductsViewModel $model */ @endphp
<h1>{{ $model->title }}</h1>

Only `ProductsViewModel` works — anything else throws an exception.

Partial

{{-- products/partials/product.blade.php --}}
@php 
    /** @var App\Models\Product $model */ 
@endphp
<div>{{ $model->title }}</div>

The partial now demands a `Post` instance, not random data.

Component

// views/components/product.blade.php
@php
    /** @var \App\View\Components\Product $model */
@endphp

<span>
    {{ $model->name }}
</span>

The component demands Product class instance now.

You can do the same with arrays and collection or other primitive types.

// example of array
@php 
    /** @var App\Models\Product[] $model*/ 
@endphp

// Or collection
@php 
    /** @var \Illuminate\Support\Collection<App\Models\Product> $model */ 
@endphp

Now if wrong type data is passed it will throw the error.

View [products] expects $model of type App\ViewModels\ProductsViewModel, 
but got string.

Similiarly, partials and components will throw the error if passed wrong type of data.

5. Going Fully Typed With DTO Classes

So far, we’ve wrapped data in ViewModels, but what about the data itself? Passing raw Eloquent models to views can be risky — they carry too much baggage and autocomplete will present you a jungle of eloquent methods along with model properties and we will have to stuggle finding properties again . To counter this issue, let's create DTO Classes to describe exactly what's needed.

Note: Since component itself can act as DTO class and carry specific properties, it does not need additional DTO class.

Lets create a BaseDTO class to define some common methods.

<?php

namespace App\DTO;

use InvalidArgumentException;

abstract class BaseDTO
{
    public function __construct(array $data = [])
    {
        foreach ($data as $key => $value) {
            if (!property_exists($this, $key)) {
                throw new InvalidArgumentException(
                    "Property '{$key}' is not defined in " . static::class
                );
            }
            $this->$key = $value;
        }
    }

    public function __get($name)
    {
        throw new InvalidArgumentException(
            "Tried to access undefined property '{$name}' on " . static::class
        );
    }

    public function __set($name, $value)
    {
        throw new InvalidArgumentException(
            "Tried to set undefined property '{$name}' on " . static::class
        );
    }

    public static function columns(): array
    {
        return array_map(
            fn($prop) => $prop->getName(),
            (new \ReflectionClass(static::class))->getProperties()
        );
    }
}

Now our actual SimpleProduct.php class to define only specific properties required for blade view or partial.

<?php

namespace App\DTO\Product;

use App\DTO\BaseDTO;

class SimpleProduct extends BaseDTO
{
    public string $name;
    public string $image;
    public float $price;
    public int $stock;
}

And here's our controller now.

class ProductController extends Controller
{
    public function index()
    {
        $viewModel = new ProductsViewModel();

        $viewModel->products = Product::select(SimpleProduct::columns())->get();
        // other code      

        return view('products.index', ['model' => $viewModel]);
    }
}

And in partial instead of defining Eloquent model as annotation define DTO class as annotation.

// views/products/partials/product.blade.php
@php
    /** @var \App\DTO\Product\SimpleProduct $model */
@endphp

<span>
    {{ $model->name }}
</span>

Now autcomplete will present you only DTO properties.

But wait. There's some issue. We passed Eloquent model but annotating DTO class. How's that supposed to work?

Pay attention on what we selected. Only sepecific columns right. So even though we passed eloquent, due to annotation we will be able to see only DTO properties. But we have to follow one condition.

Suggestion: DTO class properties must be same as Eloquent model columns.

Now here are some points to consider when working this approach.

Strict Enforcement

If you only select `DTO::columns()` in your query and pass raw models to Blade, IDE autocomplete will still work (thanks to the DTO annotation). But at runtime, Blade can still access any hidden column, relation, or accessor. To enforce discipline beyond autocomplete, wrap results into DTOs.

Schema Drift Protection

If a DTO includes a property that doesn’t exist in the table, MySQL will fail loudly with “Unknown column error”. This is actually a feature — it ensures your DTOs always stay in sync with the schema instead of drifting silently.

Losing Eloquent Helpers

DTOs are deliberately "dumb" carriers. Any accessors, relations, or helpers from your Eloquent models are gone. Prepare and transform data in the controller or service layer before converting to DTOs. Views should only see the minimal contract they need.

Mapping Overhead

Mapping into DTOs isn’t as heavy as it sounds. With a `BaseDTO` base and a mapper helper, it’s just one extra line in the query pipeline. Think of it as casting: you do it once, and the rest of your view logic becomes predictable and safe.

A Generic DTO mapper

class DTOMapper
{
    public static function map(object $source, string $dtoClass): object
    {
        $dtoReflection = new ReflectionClass($dtoClass);
        $properties = $dtoReflection->getProperties();

        $args = [];

        foreach ($properties as $property) {
            $name = $property->getName();

            if (isset($source->$name)) {
                $args[$name] = $source->$name;
            }
        }

        return new $dtoClass(...$args);
    }
}

Example implementation.

// For models
$dto = DTOMapper::map($product, SimpleProduct::class);

// for arrays or collection
$dtos = $products->map(fn($p) => DTOMapper::map($p, ProductDTO::class));

Principles of Structured Blade

This approach only holds up if you enforce some ground rules:

No untyped arrays in views Passing raw arrays to Blade is outlawed. Every view should receive a single, typed contract.
One ViewModel per Blade file Keep the mental load low. A view gets exactly one entry point: its ViewModel.
Partials and components need contracts too Even the tiniest include deserves its own ViewModel. Contracts everywhere, no freeloaders.
Always annotate with @var Autocomplete is non-negotiable. Every Blade file starts with a `@var` docblock.
Always pass data as model for consistancy Every view, partial or component must be passed viewmodel as $model so that all blade views has single entry point to start with.
Business logic stays out of Blade Views format and render. Data shaping, conditions, and prep all belong in the ViewModel.
Use DTOs to avoid Eloquent jungle Keep Eloquent in the backend. Views should only see pure, predictable DTOs.
Strict access, fail loudly If a property isn’t defined in the ViewModel, the view should throw—no guessing, no silent nulls.

Final Word

Blade isn’t broken. The way most developers use it is.

Treating Blade files as unstructured trash bins creates brittle, unmaintainable code. Adding ViewModels, autocomplete, partial contracts, and DTOs gives your views the same level of professionalism as the rest of your codebase.

This isn’t overkill. It’s discipline. And discipline is what separates fragile projects from sustainable ones.

So stop passing arrays. Start passing contracts. Give your Blade files the structure they deserve.

If you found this post helpful, consider supporting my work — it means a lot.

Support my work

Introducing The Atomic Query Construction (AQC) Design Pattern

Wed, 08 Apr 2026 10:17:35 +0000

When I started my career as a developer, one of my senior team members used to construct queries in core PHP using concatenation based on different parameters. Once the construction was complete, he would echo it for different use cases and run it in PHPMyAdmin or SQLyog. Once satisfied, he’d move on. I always liked the way he built those queries.

Later, when I moved on to CodeIgniter and eventually Laravel, I noticed something: Developers often write SQL or ORM-based queries buried deep inside controllers, services, views, event listeners — even helpers. This scattered approach leads to redundancy and painful maintenance. We’ve all seen this.

This always bugged me. Why repeat the same logic scattered across the application when it can be centralized?

Being an OOP geek, I finally settled on a pattern that works cleanly and elegantly. To counter this problem, I am introducing a new design principle: Atomic Query Construction — or AQC. It’s a design approach where each query lives in its own class. You write it once and use it everywhere. It’s structured, predictable, and aligned with better software design principles.

What is AQC?

AQC stands for Atomic Query Construction. At its core, it’s a principle of isolating each query into its own class. Each of these classes:

Accepts Parameters
Constructs Query based on those parameters for different use cases
Returns Results

You only call this class whenever that specific query is needed — nothing else. It becomes the single source of truth for that operation.

Rules of the Pattern

1. One Class, One Responsibility

Every class should focus on a single, well-defined query. Stick to the Single Responsibility Principle (SRP).

2. Accept Parameters

Each class should accept parameters — filters, identifiers, flags — whatever’s needed to shape the query dynamically.

3. Construct the Query Internally

Based on the parameters, the class should build and return a query.

4. Single Source of Truth

Anywhere in the app where you need this data — whether in a controller, event, or service — call this class. Do NOT rewrite the query logic elsewhere.

5. Handle Method

Each class should expose a single public method, handle(). It can have private helpers internally, but the interface stays clean.

6. Consistent Naming

Class names must be clear and consistent. For a resource like Product, your AQC classes might be:

GetAllProducts
GetProduct
StoreProduct
UpdateProduct
DeleteProduct

Benefits

Modular: Every query is isolated and self-contained. You know exactly where to look when changes are needed.
Reusable: Once written, the query class can be reused across the app with different params or use cases.
Flexible: It supports multiple scenarios (admin view, frontend listing, etc.) using dynamic input.
Clean Separation: Keeps your controllers, services, and views clean. No query logic there — just calls to your AQC classes.
Testable: Because logic is in isolated classes, it’s easy to write unit tests without involving controllers or database state.

Implementation Example

Let’s say we’re working with a Product model in a typical eCommerce app. First, create a folder:

app/AQC/Product/

GetAllProducts.php
GetProduct.php
StoreProduct.php
UpdateProduct.php
DeleteProduct.php

“While I’ll use Laravel in the code examples, this pattern is framework-agnostic and can be adapted to any OOP-based backend environment — Node.js, PHP, Python, etc.”

GetAllProducts.php

<?php

namespace App\AQC\Product;

use App\Models\Product;

class GetAllProducts
{
    public static function handle($params = [], $paginate = true, $scenario = 'default')
    {
        $productObj = Product::latest('id');

        if (isset($params['category_id']) && $params['category_id'] > 0) {
            $productObj->where('category_id', $params['category_id']);
        }

        if (isset($params['brand_id']) && $params['brand_id'] > 0) {
            $productObj->where('brand_id', $params['brand_id']);
        }

        // add more conditions for different use cases

        switch ($scenario) {
            case 'minimal':
                $productObj->select(['id', 'name']);
                break;
            case 'compact':
                $productObj->select(['id', 'name', 'price', 'image']);
                break;
            case 'admin':
                $productObj->select(['id', 'name', 'price', 'sku', 'image', 'stock', 'cost']);
                break;
            default:
                $productObj->select('*');
        }

        return $paginate
            ? $productObj->paginate(Product::PAGINATE)
            : $productObj->get();
    }
}

Usage:

// Admin listing
$products = GetAllProducts::handle(); 
// return paginated product order id latest 

// Frontend product listing
$products = GetAllProducts::handle($request->all(), true, 'compact');

GetProduct.php

<?php

namespace App\AQC\Product;
use App\Models\Product;

class GetProduct
{
    public static function handle($id, $params = [], $scenario = 'default')
    {
        $productObj = Product::where('id', $id);

        if (isset($params['active']) && $params['active']) {
            $productObj->where('active', $params['active']);
        }

        // add more conditions for different use cases

        switch ($scenario) {
            case 'minimal':
                $productObj->select(['id', 'name']);
                break;
            case 'compact':
                $productObj->select(['id', 'name', 'price', 'image']);
                break;
            case 'admin':
                $productObj->select(['id', 'name', 'price', 'sku', 'image', 'stock', 'cost']);
                break;
            default:
                $productObj->select('*');
        }

        return $productObj->first();
    }
}

Usage:

// Admin edit screen
$product = GetProduct::handle($productID, [], 'admin');

// Frontend product detail
$product = GetProduct::handle($productID, [], 'compact');

StoreProduct.php

<?php

namespace App\AQC\Product;
use App\Models\Product;

class StoreProduct
{
    public static function handle($params)
    {
        $product = new Product();
        $product->fill($params);

        if (isset($params['type']) && $params['type'] === 'combo') {
            $product->is_combo = true;
        }

        if (!isset($params['sku'])) {
            $product->sku = self::generateSku($params);
        }

        $product->save();
        return $product;
    }

    private static function generateSku($params)
    {
        // SKU generation logic
        return 'SKU-' . rand(1000, 9999);
    }
}

UpdateProduct.php

<?php

namespace App\AQC\Product;
use App\Models\Product;

class UpdateProduct
{
    public static function handle($id, $params)
    {
        $product = Product::find($id);

        if (!$product) return null;

        if (isset($params['cost'])) $product->cost = $params['cost'];
        if (isset($params['price'])) $product->price = $params['price'];
        if (isset($params['stock'])) $product->stock = $params['stock'];

        // add more fields as needed

        $product->save();
        return $product;
    }
}

DeleteProduct.php

<?php

namespace App\AQC\Product;
use App\Models\Product;

class DeleteProduct
{
    public static function handle($params = [])
    {
        $productsObj = Product::query();

        if (!empty($params['category_id'])) {
            $productsObj->where('category_id', $params['category_id']);
        }

        if (!empty($params['brand_id'])) {
            $productsObj->where('brand_id', $params['brand_id']);
        }

        if (!empty($params['product_id'])) {
            $productsObj->where('id', $params['product_id']);
        }

        if (!$product) return false;

        $productObj->delete();

        return true;
    }
}

Final Thoughts

Each class builds the query, covers various scenarios, and cleanly separates logic. You can now reuse queries across your entire app — controllers, API endpoints, and admin panels — without rewriting anything.

When a new requirement comes in, you know exactly where to go. No more chasing query logic across 20 files.

“With AQC, every query has a home. No more hunting across layers of your app to find and fix logic. Write it once. Use it everywhere. Welcome to clean, atomic thinking.”

If you try AQC in your projects, I’d love to hear how it works for you — or what you’d improve.

I’ll be sharing more Laravel architecture patterns soon. Follow along if you’re into clean, scalable code.

If you’d like personal mentorship or 1-on-1 help with AQC Design Pattern, I’m available on Topmate.io here.

Schedule a booking

If you found this post helpful, consider supporting my work — it means a lot.

Support My Work

Scaling Laravel Backends for High-Volume Systems: Lessons from Serving 100,000+ Users in Production

Tue, 07 Apr 2026 11:30:59 +0000

How I reduced API latency by 88%, achieved 99.8% uptime, and scaled a platform from 2,000 to 15,000 concurrent users — without downtime.

There is a moment every backend engineer dreads. Traffic is climbing, the monitoring dashboard is turning red, and your database is buckling under the weight of queries it was never designed to handle at this scale. I have lived through that moment more than once.

Over the past nine years, I, Olamilekan Lamidi, have built and scaled backend systems across fintech, gaming, health-tech, and logistics — platforms that collectively serve tens of thousands of users daily. This article distils the hard-earned lessons from scaling Laravel backends to handle high-volume traffic, reduce API latency, and maintain near-perfect uptime under pressure.

If you are building a Laravel application that needs to graduate from "it works" to "it works at scale," this is for you.

The Problem: When Your Backend Becomes the Bottleneck

Most Laravel applications start life the same way: a clean MVC structure, Eloquent models that read like poetry, and Blade templates that ship fast. This works beautifully at 1,000 users. At 10,000, cracks appear. At 100,000+, the whole thing can collapse.

I encountered this problem in its most acute form while leading backend engineering at Lordwin Group, where I architected systems for an investment and hotel management platform serving over 10,000 registered users, alongside a real-time gaming backend supporting 3,000+ concurrent connections. The platform was haemorrhaging performance. API response times had crept above two seconds, database queries were timing out during peak hours, and the engineering team was firefighting daily.

The root causes were familiar to anyone who has scaled a Laravel application:

N+1 query explosions buried deep in nested Eloquent relationships
Unindexed database tables that grew silently from thousands to millions of rows
Monolithic request handling where every API call did too much synchronous work
No caching strategy — every request hit the database, every time
Session and queue bottlenecks running on the same infrastructure as the application

The question was not whether the system needed re-architecting. It was whether we could do it without taking the platform offline.

The Challenges: Scaling Without Breaking

Scaling a live production system is fundamentally different from building a new one. You cannot afford downtime. You cannot rewrite everything at once. And you have to keep shipping features while simultaneously rebuilding the engine underneath.

Here are the specific challenges I faced:

1. Database Performance Degradation

The MySQL database had grown to contain tables with 5+ million rows. Queries that once returned in milliseconds were now taking 3–8 seconds. Eloquent's lazy loading was making things worse — a single API endpoint for listing investment portfolios was firing 47 database queries per request.

2. Synchronous Processing Overload

Critical operations — sending transactional emails, generating PDF reports, processing payment webhooks — were all running synchronously within the HTTP request cycle. This meant users were waiting 4–6 seconds for operations that did not need to block the response.

3. Absence of a Caching Layer

There was no Redis or Memcached layer. Configuration data, user permissions, and even static reference data were fetched from the database on every single request. During peak traffic, the database connection pool was exhausted within minutes.

4. Infrastructure That Could Not Scale Horizontally

The application was deployed on a single server with no load balancing, no auto-scaling, and no separation between the application server, queue workers, and database. Everything competed for the same CPU and memory.

The Solution: A Systematic Approach to Laravel Performance at Scale

I approached the problem methodically, treating it as four distinct engineering initiatives that could be executed incrementally without disrupting the live platform.

Phase 1: Query Optimisation and Database Restructuring

The single highest-impact change was eliminating N+1 queries and restructuring how the application interacted with the database.

Eager Loading Enforcement

I audited every Eloquent query across 15+ modules using Laravel Debugbar and Clockwork, cataloguing every N+1 violation. I then introduced eager loading constraints:

// Before: 47 queries for a portfolio listing
$portfolios = Portfolio::all();
foreach ($portfolios as $portfolio) {
    echo $portfolio->user->name;
    echo $portfolio->transactions->count();
}

// After: 3 queries with eager loading and aggregation
$portfolios = Portfolio::with(['user:id,name', 'transactions'])
    ->withCount('transactions')
    ->paginate(50);

Strategic Indexing

I analysed slow query logs and added composite indexes on columns used in WHERE, JOIN, and ORDER BY clauses. For the investment transactions table alone, adding a composite index on (user_id, status, created_at) reduced a critical query from 6.2 seconds to 180 milliseconds.

CREATE INDEX idx_transactions_user_status_date
ON transactions (user_id, status, created_at);

Query Refactoring

For complex reporting queries, I replaced Eloquent with raw SQL and database views where the ORM was generating inefficient joins. I also introduced read replicas to offload reporting queries from the primary database.

Result: Average query execution time dropped by 60%. The portfolio listing endpoint went from 2.3 seconds to 320 milliseconds.

Phase 2: Asynchronous Processing with Queue Architecture

I decoupled all non-critical work from the HTTP request cycle using Laravel's queue system backed by Redis.

class ProcessPaymentWebhook implements ShouldQueue
{
    use Dispatchable, InteractsWithQueue, Queueable, SerializesModels;

    public int $tries = 3;
    public int $backoff = 60;

    public function handle(): void
    {
        $this->updateTransactionStatus();
        $this->notifyUser();
        $this->syncWithAccountingService();
        $this->generateReceipt();
    }

    public function failed(Throwable $exception): void
    {
        Log::critical('Payment webhook failed', [
            'transaction_id' => $this->transaction->id,
            'error' => $exception->getMessage(),
        ]);
        AlertService::notifyEngineering($exception);
    }
}

I configured dedicated queue workers for different job priorities:

High priority: Payment processing, authentication events
Medium priority: Email notifications, PDF generation
Low priority: Analytics aggregation, cache warming

Result: API response times for webhook endpoints dropped from 4.2 seconds to under 200 milliseconds. The user-facing experience became near-instantaneous.

Phase 3: Multi-Layer Caching Strategy

I implemented a three-tier caching architecture using Redis:

Application-Level Caching

class PermissionService
{
    public function getUserPermissions(int $userId): Collection
    {
        return Cache::tags(["user:{$userId}", 'permissions'])
            ->remember(
                "user_permissions:{$userId}",
                now()->addHours(6),
                fn () => $this->repository->getPermissionsForUser($userId)
            );
    }

    public function invalidateUserCache(int $userId): void
    {
        Cache::tags(["user:{$userId}"])->flush();
    }
}

Route-Level Caching

For endpoints serving semi-static data (e.g., hotel listings, investment product catalogues), I introduced HTTP response caching with cache invalidation tied to model events:

Route::middleware('cache.response:300')->group(function () {
    Route::get('/products', [ProductController::class, 'index']);
    Route::get('/listings', [ListingController::class, 'index']);
});

Database Query Caching

For expensive aggregation queries used in dashboards, I implemented scheduled cache warming through Laravel's task scheduler, ensuring cached data was always fresh without burdening the database during peak hours.

Result: Database load reduced by approximately 70% during peak traffic. Redis handled 85% of read requests, and the database connection pool was no longer a bottleneck.

Phase 4: Infrastructure and Deployment Architecture

I redesigned the deployment topology to support horizontal scaling:

Load Balancer (Nginx) — Distributed traffic across multiple application instances
Separated Queue Workers — Dedicated servers for background job processing, preventing queue backlogs from impacting API response times
Read Replicas — Reporting and analytics queries routed to MySQL read replicas
Docker Containerisation — Standardised environments across development, staging, and production, eliminating "works on my machine" deployment failures
CI/CD Pipeline — Automated testing and zero-downtime deployments using rolling updates

services:
  app:
    build: .
    deploy:
      replicas: 3
    depends_on:
      - mysql
      - redis

  queue-worker:
    build: .
    command: php artisan queue:work redis --queue=high,medium,low
    deploy:
      replicas: 2

  scheduler:
    build: .
    command: php artisan schedule:run

  mysql:
    image: mysql:8.0
    volumes:
      - db_data:/var/lib/mysql

  redis:
    image: redis:alpine

Result: The platform could now scale horizontally by adding application instances. Deployments went from 15-minute maintenance windows to zero-downtime rolling updates.

The Results: Measurable Impact

After executing these four phases over a 10-week period, the performance transformation was significant:

Average API response time
Before: 2.3s → After: 280ms → 88% reduction

Database query execution time
Before: 1.8s avg → After: 180ms avg → 60% reduction

Payment webhook processing
Before: 4.2s → After: 190ms → 95% reduction

Database connections at peak
Before: 95% utilised → After: 30% utilised → 70% reduction

System uptime (monthly)
Before: 96.2% → After: 99.8% → 3.6% improvement

Concurrent user capacity
Before: ~2,000 → After: ~15,000 → 7.5x increase

These were not theoretical benchmarks. They were measured in production using New Relic APM and custom Prometheus dashboards over a 30-day observation period after the final deployment.

Broader Impact: Patterns That Transfer Across Industries

The architectural patterns I applied are not unique to any single domain. I have since applied the same principles across:

Fintech — At 2am Tech, I contributed to Addio, a financial platform used by 500+ organisations, where queue-based architecture and database optimisation were essential for handling high-volume transactional workflows across factors, debtors, and vendors.

Logistics — At Viaduct, I engineered a high-performance on-demand delivery platform with Laravel and Vue.js serving 5,000+ active users, where real-time order tracking demanded low-latency APIs and efficient WebSocket communication.

Enterprise SaaS — At VacancySoft, I led the refactoring of a legacy codebase across 15+ modules, migrating services to a modern architecture — cutting query execution time by 60% and improving overall system performance by 40% while handling 50,000+ daily requests.

The fundamental lesson is this: scaling is not about throwing more hardware at the problem. It is about understanding where your system spends time and eliminating waste systematically. Database queries, synchronous processing, missing caches, and monolithic deployment topologies are the four horsemen of backend performance degradation. Address them methodically, measure relentlessly, and you can scale a Laravel application to handle traffic volumes that would surprise most engineers.

Key Takeaways for Engineers Building High-Volume Systems

Profile before you optimise. Use Laravel Debugbar, Clockwork, or APM tools to identify actual bottlenecks. Gut instinct is unreliable.
Eliminate N+1 queries aggressively. This is almost always the single highest-impact optimisation in any Eloquent-based application.
Move everything non-essential off the request cycle. If the user does not need to wait for it, it belongs in a queue.
Cache strategically, invalidate precisely. A poorly invalidated cache is worse than no cache. Use tagged caching and model event listeners to keep data fresh.
Design for horizontal scaling from day one. Stateless application servers, externalised sessions (Redis), and containerised deployments make scaling a configuration change rather than an architectural rewrite.
Measure everything. If you cannot quantify the improvement, you cannot prove it happened. Set up monitoring before you start optimising.

Final Thoughts

Backend performance at scale is a discipline, not a one-time fix. Every system I have worked on has taught me that the architecture decisions you make early compound over time — for better or worse. The patterns described in this article have been tested in production across financial platforms, real-time gaming systems, logistics networks, and enterprise SaaS products.

If you are an engineer facing similar scaling challenges, I hope this gives you a practical roadmap. And if you have solved these problems differently, I would genuinely like to hear about it. The best engineering solutions come from sharing what we have learned.

How to Implement Caching in Laravel Using Different Caching Tools (A Practical Guide)

Tue, 31 Mar 2026 11:12:00 +0000

If your Laravel application feels slow under load, chances are you're doing too much work on every request.

Database queries, API calls, heavy computations these things add up fast. And when traffic increases, performance drops, users complain, and suddenly you're firefighting.

I’ve been there.

The turning point? Caching.

When implemented correctly, caching can dramatically improve performance, reduce server load, and make your app feel instant. In this guide, I’ll walk you through how to implement caching in Laravel using different caching tools, with real world context not just theory.

Why Caching Matters in Laravel Applications

Before we dive into code, let’s make it real.

Every time a user hits your endpoint, your app might:

Query the database
Process business logic
Format a response

Now imagine doing that thousands of times per minute.

Caching allows you to:

Store the result once
Reuse it multiple times
Avoid unnecessary computation

Result: Faster responses, lower costs, happier users.

Understanding Laravel’s Cache System

Laravel makes caching incredibly simple through its unified API.

You interact with caching using:

use Illuminate\Support\Facades\Cache;

Behind the scenes, Laravel supports multiple drivers:

File
Database
Redis
Memcached
Array (for testing)

The beauty is: You can switch drivers without changing your core logic..

Step 1: Basic Caching in Laravel (Start Here)

Let’s begin with the simplest use case.

Storing Data in Cache

Cache::put('users', $users, 60); // cache for 60 seconds

Retrieving Data

$users = Cache::get('users');

The Better Approach: Remember Pattern

$users = Cache::remember('users', 60, function () {
    return User::all();
});

This is my go to pattern.

Note: It checks the cache first, and only hits the database if needed.

Step 2: Choosing the Right Cache Driver

Not all caching tools are equal. Your choice depends on your scale and architecture.

1. File Cache (Default)

Best for: Small apps, local development
Storage: storage/framework/cache

CACHE_DRIVER=file

✔ Easy to set up
❌ Slow for high traffic

2. Database Cache

Best for: Shared environments without Redis

php artisan cache:table
php artisan migrate

CACHE_DRIVER=database

✔ Persistent
❌ Slower than in memory caching

3. Redis (Recommended for Production)

Best for: High performance applications

CACHE_DRIVER=redis

composer require predis/predis

✔ Extremely fast (in memory)
✔ Supports advanced features (queues, pub/sub)
✔ Scales well

For Me: This is what I use in most production systems.

4. Memcached

Best for: Distributed systems

CACHE_DRIVER=memcached

✔ Fast and lightweight
❌ Less flexible than Redis

Step 3: Caching Database Queries (Real Impact)

This is where you’ll see immediate performance gains.

Without Caching:

$products = Product::where('active', 1)->get();

With Caching:

$products = Cache::remember('active_products', 300, function () {
    return Product::where('active', 1)->get();
});

Note: You just reduced database load significantly.

Step 4: Cache Invalidation (The Part Everyone Gets Wrong)

Caching is easy.

Invalidation is hard.

If you don’t clear or update cache properly, users will see stale data.

Manual Invalidation:

Cache::forget('active_products');

Example (After Updating Data):

Product::create($data);
Cache::forget('active_products');

Note: Always tie cache invalidation to data changes.

Step 5: Using Cache Tags (Advanced Control)

If you're using Redis or Memcached, Laravel supports cache tags.

Cache::tags(['products'])->put('active_products', $products, 300);

Clearing by Tag:

Cache::tags(['products'])->flush();

This is powerful when dealing with grouped data.

Step 6: Caching API Responses

If your app consumes external APIs, caching is a lifesaver.

Example:

$response = Cache::remember('weather_data', 600, function () {
    return Http::get('https://api.weather.com/data')->json();
});

✔ Reduces API calls
✔ Avoids rate limits
✔ Improves response time

Step 7: Full Page Caching (When You Need Speed)

For content heavy apps (blogs, dashboards), full page caching can be huge.

You can use packages like:

spatie/laravel-responsecache

Note: This caches entire HTTP responses.

Step 8: Cache Configuration Best Practices

Here’s what I’ve learned from production systems:

1. Use Redis in Production

It’s faster and more reliable.

2. Set Meaningful Expiry Times

Short lived data → 1–5 minutes
Semi static data → 10–60 minutes
Rarely changing → hours or days

3. Avoid Cache Stampede

Use remember to prevent multiple requests hitting the DB at once.

4. Monitor Cache Usage

Track:

Hit rate
Miss rate
Memory usage

Step 9: Common Mistakes to Avoid

Let me save you some pain:

❌ Caching everything blindly
❌ Forgetting to invalidate cache
❌ Using file cache in production
❌ Storing sensitive data in cache
❌ Setting no expiration

Note: Caching is powerful but only when used intentionally.

A Practical Workflow I Use

When optimizing a Laravel app:

Identify slow queries/endpoints
Add caching using Cache::remember()
Choose Redis as driver
Add invalidation logic
Monitor performance improvements

Simple. Effective.

Final Thoughts: Caching Is a Performance Multiplier

If you’re not using caching in your Laravel app, you’re leaving performance on the table.

The goal isn’t just speed it’s scalability and efficiency.

A well cached application:

Handles more users
Reduces infrastructure costs
Delivers a better user experience

Call to Action

If this guide helped you:

Share it with your Laravel team
Bookmark it for your next optimization sprint
Drop a comment: What’s the biggest performance issue you’ve faced in Laravel?

And if you’re serious about building scalable systems, start treating caching not as an optimization but as a core part of your architecture.

Laravel Testing Environment Setup

Sun, 29 Mar 2026 14:36:21 +0000

title: Laravel Testing Environment Setup
published: true
description:
tags: #test #laravel #phpunit

published_at: 2026-03-26 14:38 +0000

This guide explains how to properly configure a testing environment in Laravel using .env.testing and phpunit.xml.

Overview

When running automated tests, you should isolate your testing environment from development and production. This prevents accidental data loss and improves test reliability.

⚙️ 1. Create .env.testing

Create a .env.testing file in the root of your Laravel project:

APP_NAME=laravel
APP_ENV=local
APP_KEY= # application key
APP_DEBUG=true
APP_URL=http://laravel.test

APP_LOCALE=en
APP_FALLBACK_LOCALE=en
APP_FAKER_LOCALE=en_US

APP_MAINTENANCE_DRIVER=file

BCRYPT_ROUNDS=12

DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE= # your testing database (e.g., laravel-testing)
DB_USERNAME=root
DB_PASSWORD=

SESSION_DRIVER=database
SESSION_LIFETIME=120
SESSION_ENCRYPT=true
SESSION_PATH=/
SESSION_DOMAIN=null

✅ Notes
Use a separate database for testing.
Never reuse your development or production database.

Configure phpunit.xml

Update your phpunit.xml file:

<?xml version="1.0" encoding="UTF-8"?>
<phpunit xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:noNamespaceSchemaLocation="vendor/phpunit/phpunit/phpunit.xsd"
         bootstrap="vendor/autoload.php"
         colors="true"
>
    <testsuites>
        <testsuite name="Unit">
            <directory>tests/Unit</directory>
        </testsuite>
        <testsuite name="Feature">
            <directory>tests/Feature</directory>
        </testsuite>
    </testsuites>

    <source>
        <include>
            <directory>app</directory>
        </include>
    </source>

    <php>
        <env name="APP_ENV" value="testing"/>
        <env name="APP_MAINTENANCE_DRIVER" value="file"/>
        <env name="BCRYPT_ROUNDS" value="4"/>

        <env name="BROADCAST_CONNECTION" value="null"/>
        <env name="CACHE_STORE" value="array"/>
        <env name="DB_CONNECTION" value="mysql"/>
        <!-- <env name="DB_DATABASE" value="your-testing-db"/> -->
        <env name="DB_URL" value=""/>

        <env name="MAIL_MAILER" value="array"/>
        <env name="QUEUE_CONNECTION" value="sync"/>
        <env name="SESSION_DRIVER" value="array"/>

        <env name="PULSE_ENABLED" value="false"/>
        <env name="TELESCOPE_ENABLED" value="false"/>
        <env name="NIGHTWATCH_ENABLED" value="false"/>
    </php>
</phpunit>

Run Tests

Before running tests:

Ensure your testing database exists
Run migrations if needed

Then execute:

php artisan test

⚡ Tips
Isolation: APP_ENV=testing ensures .env.testing is used.
Performance:
CACHE_STORE=array
SESSION_DRIVER=array
QUEUE_CONNECTION=sync
Faster Hashing:
Reduce BCRYPT_ROUNDS during testing
Disable Extras:
Disable tools like Telescope, Pulse, etc., to speed up tests

✅ Summary

With this setup:

Tests run faster ⚡
Data remains safe
Environment stays isolated

Leveraging Laravel with Docker for Streamlined Development

Mon, 09 Mar 2026 19:44:13 +0000

Explore how to integrate Docker into your Laravel development workflow for enhanced efficiency and consistency.

Setting up a development environment can be challenging. Using Docker with Laravel can simplify this process remarkably. Here’s how to get started:

Install Docker: Ensure you have Docker installed on your machine. Follow the official Docker documentation for your operating system.

Create a Dockerfile: In your Laravel project, create a Dockerfile to define your application environment. For example:

FROM php:8.0-fpm
WORKDIR /var/www
COPY . .
RUN apt-get update && apt-get install -y libpng-dev libjpeg-dev libfreetype6-dev && docker-php-ext-configure gd --with-freetype --with-jpeg && docker-php-ext-install gd
CMD php artisan serve --host=0.0.0.0

This example sets up PHP with GD support, essential for image processing in Laravel applications.

Create a docker-compose.yml file: This file will manage your multi-container application. For Laravel, it might look like this:

version: "3.8"
services:
  app:
    build:
      context: .
    volumes:
      - .:/var/www
    ports:
      - "8000:8000"
  db:
    image: mysql:5.7
    environment:
      MYSQL_ROOT_PASSWORD: root
      MYSQL_DATABASE: laravel

The above example sets up a MySQL database alongside your Laravel app.

Run the containers: Execute the following command in your terminal:
```
docker-compose up -d
```
This command will bring up your Laravel application and your database as defined in the docker-compose.yml file.
Access your application: You can now access your Laravel application running on http://localhost:8000.

Final Thoughts: By using Docker, you ensure a consistent development environment across different setups, leading to fewer deployment headaches. It’s a game-changer for collaborative projects where each developer may have different local setups.

Take Action: Try integrating Docker into your Laravel project today and notice how it changes your workflow for the better.

Essential Laravel Tools for Efficient Development

Thu, 26 Feb 2026 09:45:00 +0000

Explore the must-have tools that every Laravel developer should consider for streamlined development and improved efficiency.

As a Laravel developer, using the right tools can significantly enhance your productivity. Here are some essential tools worth checking out:

Tinker - Laravel's built-in REPL allows you to interact with your application directly. You can quickly test models and run database queries without the overhead of a full server environment.
Laravel Debugbar - This package offers an easy way to debug your application. It provides insights into your application's performance, route details, and queries executed, making it easier to identify bottlenecks.
PHPStorm - Although not exclusive to Laravel, PHPStorm provides excellent support for Laravel projects. Features like code completion, navigation, and refactoring tools streamline your coding process.
Laravel Mix - Enhance your asset compilation with Laravel Mix. It enables you to use modern JavaScript libraries and preprocessors like Sass with minimal configuration.
Postman - Essential for API testing. With Postman, you can easily manage your API endpoints, conduct tests, and automate workflows, ensuring your APIs are robust and well-documented.
Git - Version control is vital for team collaboration and maintaining code integrity. Familiarize yourself with Git commands to manage your project's development lifecycle effectively.
Laravel Envoy - If you manage server deployments, Laravel Envoy simplifies the process. Use it to define deployment tasks as code, making deployments consistent and repeatable.
Spatie Packages - The Spatie team offers a suite of packages that add great functionality to Laravel applications, from media management to role and permission handling. Try them out to save time on common tasks.

By integrating these tools into your workflow, you can enhance your capabilities as a Laravel developer and build applications that not only meet user expectations but exceed them.

How I optimized a web application early in my career

Mon, 23 Feb 2026 19:36:59 +0000

This happened nearly 6 years ago, around the year 2019. I was working on my first job at the time as a junior web developer.

At that time I was working on an e-learning platform. My work mainly revolves around building and maintaining the marketing website for the platform. That includes home website, blogs and courses section. I was working in that project as the lead developer along with another front-end developer. It’s a small startup, so I was involved on many things even though I was a junior developer.

The project was migrated from Wordpress, and rebuilt with Laravel & MySQL. I handled most part of the migration that time.

The website was smooth, everything working fine. In my perspective at that time, if the website loads, then it was smooth. I was naive.

One day my team lead, (There was only one team lead in the entire company) called me and explained his concerns regarding the website speed and performance. I didn’t understand it at first. The website was working fine. While it wasn’t loading at the same speed like a single-page application, it was decent enough. But for him, that wasn’t good enough.

He told me to do whatever I can to optimize the website to load faster. He gave me three days to do it.

At that moment, I was like a boy who had just been thrown into something much bigger.

I was just slightly better than a beginner at best. I knew how to build features, I knew how to make things work. But scaling? Performance? Optimization? I hand no idea where to even begin.

I couldn’t refuse the task. And honestly, I have no reason to refuse. He gave me complete freedom to research, experiment and approach the problem however I want.

Even though I hesitated at first because I thought I might break things that were working fine, I eventually agreed to do it. But to be honest, I had no clue where to start.

First day was all about researching and analyzing. I went through articles on Laravel optimization techniques, caching, query optimization, etc. I literally went through everything I found on Google.

I’ve analyzed the website through multiple tools like Checkbot, GTMetrix, etc., to find what’s affecting the performance.

I’ve listed out every suggested change I could. But honestly there wasn’t much I could do in the remaining two days.

I couldn’t risk trying to optimize queries in this stage and breaking something. We are using Laravel eloquent queries for database operations and I barely know basic SQL querying at that time.

I don’t know much about caching at that time and I don’t have the bandwidth to learn and implement it.

There were quite a few of limitations on what I could do.

First one is we are using shared hosting and hosted the website on cpanel. So, I can’t freely install additional software like Redis for caching. The server only supports PHP and MySQL.

Second one is, the website was working perfectly fine and I couldn’t risk breaking anything in the perfectly working system.

Third one is I’ve limited time. And whatever I do, I have to do it in the remaining two days.

So, I’ve listed only the issue that I was confident to work on.

a. This was the first and most important issue that I’ve listed. The website contains multiple components such as dynamic listing, infinite scrolling, dynamic filters, etc. And I was rendering all these contents through API from frontend at the time of page load using Javascript. This is one of the factors that’s increasing the page load time.

b. In the current website, I am serving uncompressed styles and scripts, even though Laravel comes with Laravel Mix by default.

c. Some of the images that were used in the website are of high quality and comes in large size, that were resizing on frontend from CSS.

There were some other issues too, but these were the main issues among the ones that I remember.

Then I’ve started working on the second day.

1) Reduced the usage of Javascript

Logically this was the best thing to do. But honestly, many components are working dynamically front frontend. So, I couldn’t fully avoid the usage of Javascript.

So I did this. I’ve listed out the content that’s dynamically on page load, and rendered it from server-side. This way I’ve mostly avoided API calls, and rendering content using Javascript on page load event. Now the DOM will only get modified when something’s changed or the events get triggered.

2) Building assets for production

At that time, I am not familiar with things like webpack, mixing assets etc. So, even though Laravel comes with Laravel Mix, I’ve served assets normally from /public folder.

But after some digging, I’ve learned how to use Laravel Mix. Honestly, it was super easy and fun. I still use it as my default bundler for my projects, even though the repository is abandoned.

I’ve removed all inline and uncompressed styles and scripts, moved them into the /resources folder, centralized them properly, and ensured that only production-ready compiled assets were being served.

It might sound small, but this reduced unnecessary load and made the application clearer and more maintainable.

3) Compressing Images

This is where it got little trickier. For the website, the client provides the images. Normally the images are of high quality and heavy-weighted and too large. So, we are embedding the images using image tag and resizing using CSS on frontend.

After brainstorming a bit, I’ve decided to compress them and load the images with exact sizes to avoid the resizing from frontend. I’ve used PHPIntervention library to compress and resize images from server side.

I’ve created a new method something like this :

function load_image($filename, $width, $height) {  
 $path = "new folder for resized images";  
 $new_name = $width . "_" . $height . "_" . $filename;  
 if(!file_exists($path . "/" . $new_name)) {  
  resize_image_using_intervention();  
  return resized_image_path();  
 }  
  
 return resized_image_path();  
}

The role of this method is, it will check if the resized version of the given image is present in the file system and if not, it will compress and resize the image and store it in the file system. If exists, it will return the image URL as string.

I can use in blade template like below :

<img src="{{ load_image("image.png", 200, 100) }}" alt="" />

And it will display the resized image. As it won’t touch the original image and create resized copies of it, I can use the same image with multiple sizes in multiple places.

This way, the browser don’t need to adjust the image sizes on frontend as the images already loading with correct dimensions.

4) Rendering Minified HTML

Well, this isn’t actually a problem, but an extra I’ve decided to do. And this was easy, there were many packages available for Laravel to minify the templates before rendering. Honestly, I just went with the flow for this one.

5) Gzip Compression

At that time, I don’t even know anything about Gzip compression. I’ve found it in some article, and after looking into it, I’ve decided to give it a try, since I only needed to modify .htaccess file and thats it. No code changes, nothing.

That’s it. This is all I did and I’ve managed to do it in the given timeframe. And to my surprise, the speed of the page loading increased more than before, even client acknowledged it.

Looking back now, compared to the optimization techniques and tools available today, what I did might seem small, or may be even basic.

But at that time, I was barely more than a beginner. I don’t know advanced scaling strategies or deep performance engineering. I simply did what I was capable of doing with the knowledge I had. And luckily, it worked better than I expected.

When I look back at that project, I also remember something else.

The application was fully server-size rendered. I initially used web components, but later I removed them during optimization.

Today, things feel very different.

We ship large amounts of Javascript by default. Rendering logic that could easily live on the server is being pushed to the client. Using complete frontend frameworks has almost become the norm.

There was even a time when I disliked PHP and SSR. I was drawn toward modern shiny frameworks like React and Vue, believing they were automatically better.

But think what, after working on real-world projects that relied heavily on them, I’ve actually started to like and appreciate PHP and SSR more.

Conclusion

Developers today are, in many cases, taking Javascript for granted.

Javascript is really powerful, but it should be used for what it’s meant to be used. Handling dynbamic client-size interactions, managing complex UI state, and enhancing user experience are prefect use cases. But rendering everything on the client by default isn’t always the smartest choice.

Forcing one language or one ecosystem into every layer of an application may look modern and clean, but we must consider what we are trading for it, bundle size, performance overhead, complexity, and long-term maintainability.

I don’t hate modern technologies. In fact, I’ve worked with them and learned from them. What I’ve come to understand is simple. What I’ve come to understand is simple. Choose your stack wisely. Let the problem decide the tools, not the trends.

Originally published at https://bhaswanth.com.

Getting Started with GraphQL for Laravel Developers

Mon, 23 Feb 2026 06:56:26 +0000

Unlock the potential of GraphQL in your Laravel applications. This guide covers the fundamentals, advantages over REST, and practical ways to integrate GraphQL into your projects.

Introduction to GraphQL

GraphQL is a powerful query language for APIs, initially developed by Facebook. Unlike REST, which exposes multiple endpoints, GraphQL provides a single endpoint. Here, you can request only the data you need, reducing payload size and improving speed.

Architecture of GraphQL

At its core, GraphQL is built around the concepts of types and fields. You define a schema that describes what queries can be made and what types of data each query returns. This schema acts as a contract between the client and the server.

Key Components of GraphQL:

Queries: Read data.
Mutations: Write data.
Subscriptions: Listen to real-time updates.

Advantages Over REST

Single Endpoint: Eliminate the need for multiple URLs, streamlining your API.
Client-Driven: Clients request exactly what they need, minimizing over-fetching and under-fetching.
Strongly Typed: Changes to the data structure can be managed more easily due to the schema definition.

Getting Started

Integrating GraphQL with Laravel

To start using GraphQL in your Laravel application, follow these steps:

Install the Package:
You can use the lighthouse-php package, which is a popular choice for integrating GraphQL in Laravel:
```
composer require nuwave/lighthouse
```
Publish the Config File:
Run the following command:
```
php artisan vendor:publish --tag=lighthouse
```
Define Your Schema:
Create a graphql/schema.graphql file. Here’s a simple example:
```
type Query {
    users: [User]
}
type User {
    id: ID!
    name: String!
}
```

Create Resolvers:
For the users query, you might set up a resolver in app/GraphQL/Queries/UserQuery.php:

namespace App\GraphQL\Queries;
use App\Models\User;
   
class UserQuery {
    public function resolve($root, array $args) {
        return User::all();
    }
}

Testing Your GraphQL API:
You can use tools like Postman or GraphQL Playground to play around with your API. Here’s a simple query to get started:
```
query {
    users {
        id
        name
    }
}
```

Conclusion

GraphQL offers a flexible way to interact with your data, which can improve performance and reduce the time it takes to build features. By adopting these principles, you can create APIs that better serve the needs of your applications. Start experimenting, and you might find that GraphQL changes how you think about API design altogether.

Seamless Dropbox Integration in PHP & Laravel: A Modern SDK Tutorial

Fri, 13 Feb 2026 10:49:44 +0000

You've been there. Tasked with integrating cloud storage, you find yourself wrestling with verbose API documentation, handling cumbersome OAuth 2.0 flows, and writing boilerplate code just to upload or share a file. While services like Dropbox offer powerful APIs, the integration process can often feel clunky and outdated, pulling you away from building the features that matter.

This is where a modern, well-designed SDK becomes invaluable. For developers in the PHP ecosystem, especially those using Laravel, the tigusigalpa/dropbox-php package emerges as a clean, intuitive, and powerful solution for streamlining Dropbox integration. This tutorial will walk you through how this library simplifies cloud storage operations, from basic file handling to advanced features like chunked uploads.

Why a Modern SDK Matters

In a landscape of rapidly evolving development practices, using a modern SDK is about more than just convenience; it's about leveraging the full power of the language. Built for PHP 8.1+, this library embraces modern features like typed properties and a clean, fluent API. This results in code that is not only easier to write but also more readable, maintainable, and less prone to errors compared to older libraries or manual cURL requests.

Core Features at a Glance

The library is packed with features designed to provide a comprehensive and developer-friendly experience. It covers the entire Dropbox API v2, ensuring you have the tools for any task.

Feature	Description
Full API v2 Coverage	Access over 40 methods for files, folders, sharing, users, and Paper.
Laravel 8-12+ Support	Includes a service provider, facade, and publishable config for seamless framework integration.
Standalone Capability	Works perfectly without any framework, making it versatile for any PHP project.
Chunked Uploads	Reliably upload large files (up to 350GB) by splitting them into smaller, manageable chunks.
Batch Operations	Efficiently copy, move, or delete up to 1,000 files in a single API call.
OAuth 2.0 Flow	Provides helpers to easily manage the complete authorization process, including token generation and refresh.

Getting Started: Installation & Configuration

Integrating the package into your project is straightforward. First, pull it in using Composer:

composer require tigusigalpa/dropbox-php

For Laravel Users

The package automatically registers its service provider and facade. All you need to do is publish the configuration file and add your credentials to the .env file.

Publish the configuration:

php artisan vendor:publish --tag=dropbox-config

Update your .env file:

DROPBOX_ACCESS_TOKEN=your_access_token_here
DROPBOX_APP_KEY=your_app_key
DROPBOX_APP_SECRET=your_app_secret
DROPBOX_REDIRECT_URI=https://your-app.com/callback

Practical Usage: A Step-by-Step Guide

Let's dive into some code. The library's clean API makes performing common tasks incredibly simple.

Example 1: Standalone PHP - Uploading a File

Even without a framework, using the client is intuitive. After obtaining an access token from the Dropbox App Console, you can start making calls immediately.

use Tigusigalpa\Dropbox\DropboxClient;

// Instantiate the client with your access token
$client = new DropboxClient('your_access_token');

// Get current user's account info
$account = $client->users->getCurrentAccount();
echo "Hello, " . $account['name']['display_name'];

// Upload a simple text file
$result = $client->files->upload(
    '/Apps/MyApp/hello.txt',
    'Hello, World!',
    'add' // Use 'overwrite' to replace existing files
);

echo "File uploaded successfully: " . $result['path_display'];

Example 2: Laravel Integration - File Uploads in a Controller

Within a Laravel application, you can leverage either the Dropbox facade or dependency injection for a clean, testable implementation. Here’s how you might handle a file upload from a user request.

use Illuminate\Http\Request;
use Tigusigalpa\Dropbox\DropboxClient;
use App\Http\Controllers\Controller;

class FileUploadController extends Controller
{
    public function store(Request $request, DropboxClient $dropbox)
    {
        $request->validate(['document' => 'required|file']);

        $file = $request->file('document');
        $content = file_get_contents($file->path());
        $path = '/uploads/' . $file->getClientOriginalName();

        // Upload the file to Dropbox
        $result = $dropbox->files->upload($path, $content);

        return response()->json([
            'message' => 'File uploaded successfully.',
            'data' => $result
        ]);
    }
}

Conclusion

The tigusigalpa/dropbox-php library offers a robust and elegant solution for integrating the Dropbox API into modern PHP and Laravel applications. By providing a clean, fluent interface and handling the complexities of features like chunked uploads and batch operations, it allows developers to focus on building features rather than wrestling with API mechanics. Whether you're building a simple file-sharing tool or a complex, enterprise-level application, this SDK provides the foundation you need for seamless and reliable cloud storage integration.

Give it a try in your next project and experience a more productive way to work with Dropbox.

References

[1] tigusigalpa/dropbox-php GitHub Repository: https://github.com/tigusigalpa/dropbox-php [2] Official Wiki and Documentation: https://github.com/tigusigalpa/dropbox-php/wiki

Four Spaces Before
Tue, 10 Feb 2026 13:35:08 +0000

I was working on a Livewire component when every interaction started throwing 419 errors. CSRF token mismatch, on every click. The kind of thing that makes you question your setup immediately.

At first I assumed it was a Livewire issue. But then I noticed something stranger — every page refresh generated a new session ID. Sessions worked fine with `php artisan serve`, but the moment I switched to Herd, no cookies stuck. Each request was a clean slate.

The 419 errors were just a symptom. Laravel couldn't maintain sessions because the browser never received a cookie.

Chasing the usual suspects

I started with the .env file:

SESSION_DRIVER=redis
SESSION_LIFETIME=120
SESSION_DOMAIN=null
SESSION_SECURE_COOKIE=false

Redis was running, PHP could connect to it. I created a test route to confirm sessions worked at the PHP level — they did. Data was stored, but the browser never got the Set-Cookie header.

I checked DevTools. No laravel_session cookie. No Set-Cookie header at all.

I went through the usual list: cookie domain, HTTPS settings, session path, Redis connection. All fine. Switched to the file driver. Same result. Tried setting a cookie manually:

Route::get('/cookie-test', function () {
    return response('Test')
        ->cookie('test_cookie', 'test_value', 60);
});

Still no Set-Cookie header. At this point it clearly wasn't a Laravel config problem. Something was preventing PHP from sending cookies entirely.

The actual problem

The breakthrough came from a raw header() call:

Route::get('/header-test', function () {
    header('X-Custom-Test: working');
    // ...
});

PHP responded with: "Cannot modify header information — headers already sent", and pointed to routes/web.php:1.

Line 1 should just be <?php. I opened the file and there it was — the tag was indented. Four spaces sitting right there, plain as day. I just hadn't noticed.

Why it only showed up in Herd

The bug existed all along. php artisan serve has output buffering enabled by default, so those spaces never reached the browser before the headers. The problem was silently masked.

Herd uses nginx + PHP-FPM with output_buffering = 0. Output goes out immediately. Those four spaces hit the browser before Laravel could send any headers — which meant no cookies, which meant no sessions.

The fix

Delete four spaces. That's it.

I made sure routes/web.php started with <?php on the very first character of the very first line. Saved. Everything worked.

Livewire relies on the session to verify CSRF tokens on every request. Without a Set-Cookie header, the browser never stores a session — and without a session, every Livewire interaction fails with a 419.

Four spaces before <?php were enough to start the response body, and once the body starts, PHP can't send headers anymore.

Structuring Large Laravel Projects Without Overengineering

Sat, 07 Feb 2026 10:58:01 +0000

In my experience , Laravel makes it incredibly easy to start a project. A few commands, some controllers, migrations, and you’re shipping features fast. The problem usually doesn’t appear in week one it shows up months later, when the codebase grows, the team expands, and simple changes start feeling risky.

At that point, developers often swing to extremes:

Either everything stays messy and tightly coupled
Or the project becomes overengineered with layers, abstractions, and patterns no one fully understands

The sweet spot lies in between.

This article explores how to structure large Laravel projects without overengineering, keeping your codebase scalable, readable, and friendly to future contributors.

The Real Problem With “Default Laravel Structure”

Laravel’s default structure is intentionally simple and that’s a good thing. But in larger projects, issues start to emerge:

Controllers grow too large
Business logic leaks everywhere
Repeated patterns appear across features
Debugging becomes harder than it should be

The instinctive reaction is to introduce complex architectures too early. Unfortunately, that often creates more problems than it solves.

The goal isn’t to make Laravel “enterprise looking.”
The goal is to make it maintainable.

Start With Features, Not Layers

One of the most common mistakes in large Laravel projects is organizing code strictly by technical layers.

Instead of thinking:

“Where do I put this service?”

Ask:

“What feature does this belong to?”

A Practical Feature Based Structure

app/
 ├── Features/
 │   ├── Orders/
 │   │   ├── Controllers/
 │   │   ├── Actions/
 │   │   ├── Requests/
 │   │   └── Policies/
 │   ├── Payments/
 │   └── Users/

This keeps related logic close together and makes onboarding easier. When someone works on “Payments,” everything they need is in one place.

Keep Controllers Thin (But Don’t Panic About It)

Controllers shouldn’t contain complex business logic but that doesn’t mean every line needs a separate class.

A good rule of thumb:

Controllers handle HTTP concerns
Business logic lives elsewhere

Instead of massive controllers, extract logic into:

Action classes
Service classes (when justified)
Domain specific helpers

Example:

public function store(StoreOrderRequest $request)
{
    return CreateOrder::run($request >validated());
}

Simple, readable, and testable without unnecessary abstraction.

Use Services Only When Logic Is Reused or Complex

Service classes are useful but only when they solve a real problem.

Create a service when:

Logic is reused across multiple features
The operation is complex or multi step
You need clear separation for testing

Avoid services that just wrap a single model call. That’s not architecture it’s ceremony.

Let Models Do Some Work (Within Reason)

Laravel models are powerful, and it’s okay to use them.

Helpful patterns:

Query scopes for reusable queries
Model methods for domain specific behavior
Accessors and mutators for data shaping

Avoid turning models into “god objects,” but don’t fear using them either. Balance matters more than purity.

Avoid Premature Design Patterns

Patterns like:

Repositories
CQRS
Event sourcing
Hexagonal architecture

are not bad but they are expensive in complexity.

If your team doesn’t feel the pain these patterns solve, adding them early will slow development and confuse contributors.

Start simple. Introduce patterns only when a real problem appears.

Configuration and Boundaries Matter More Than Classes

Large Laravel projects stay healthy when boundaries are clear.

Focus on:

Consistent naming conventions
Clear folder responsibilities
Well defined APIs between features
Shared code living in obvious locations

Good structure is about clarity, not class count.

Tests Are Part of the Structure

A well structured project is easy to test.

Feature tests validate behavior
Unit tests protect core logic
Clear boundaries make mocking easier

If testing feels painful, it’s often a sign the structure needs refinement not more abstractions.

Signs You’re Overengineering

If any of these sound familiar, it may be time to simplify:

Every request touches 6+ layers
New developers struggle to find code
Refactoring feels dangerous
The architecture needs a diagram to explain

Good architecture fades into the background. It supports development it doesn’t dominate it.

Final Thoughts: Structure Should Serve the Team

Structuring large Laravel projects isn’t about following trends or copying architectures from conference talks. It’s about building systems that real developers can understand, maintain, and evolve.

Start simple. Organize by features. Add structure only when it earns its place.

If this article resonated with you, share it with a teammate who’s fighting an overcomplicated codebase. And if you enjoy practical Laravel content focused on real world tradeoffs, there’s plenty more worth exploring.

Vector: The easiest way to plug Vue in Blade

Tue, 03 Feb 2026 19:24:34 +0000

You know that feeling when you're building a Laravel app and you just need a tiny bit of reactivity? A counter. A toggle. Something that feels overkill for a full Vue component but too annoying for vanilla JavaScript?

I kept reaching for Alpine.js, which is great, but I wanted Vue's Composition API. The ref(), the computed(), the familiar syntax I already know. So I bu4ilt Vector.

What Even Is This?

Vector is a Laravel package that lets you write Vue directly in your Blade templates with zero ceremony:

<script setup>
    const i = ref(0);
</script>

<div>
    <button @click="i++">Click Me</button>
    <div>
        Count: @{{ i }}
    </div>
    <div v-if="i > 5">Success!</div>
</div>

That's the whole thing. No build step for your components. No separate .vue files. No special directives wrapping your code. Just a <script setup> tag and you're done.

How It Works

The <script setup> tag gets transformed at compile time. Vector treats the element immediately after the script tag as your Vue template. Everything inside that element becomes reactive, and anything outside it remains regular Blade.

Blade's precompiler finds your <script setup> blocks
Extracts your variable declarations
Mounts Vue on the next sibling element

The key part is the variable extraction. It parses const, let, and var declarations and auto-returns them to the template. You write normal code, it figures out the rest.

Escaping Blade Syntax

Since Blade also uses {{ }} for output, you need to prefix Vue's mustache syntax with @ to prevent Blade from processing it:

{{-- This is Blade --}}
{{ $phpVariable }}

{{-- This is Vue (note the @) --}}
@{{ vueVariable }}

Alternatively, use Vue directives like v-text which don't conflict with Blade:

<span v-text="count"></span>

Installation

composer require brunoabpinto/vector

Add Vector to your Vite entry points in vite.config.js:

plugins: [
    laravel({
        input: [
            "resources/css/app.css",
            "resources/js/app.js",
            "resources/js/vendor/vector.js",
        ],
        // ...
    }),
],
resolve: {
    alias: {
        'vue': 'vue/dist/vue.esm-bundler.js',
    },
},

Add @vectorJs before your closing </body> tag in your layout:

<body>
    {{ $slot }}

    @vectorJs
</body>

That's it. Vector auto-publishes its runtime, and @vectorJs loads it where you need it.

The Trade-offs

Let's be real about what this is:

Good for:

Quick interactive elements
Prototyping
When you want Vue's API without Vue's ceremony
Laravel apps that are mostly server-rendered with islands of reactivity

Not great for:

Complex component hierarchies
When you need proper SFC features (scoped styles, etc.)
Large-scale SPAs (just use Inertia at that point)

Try It

The package is available on GitHub. Star it, fork it, tell me it's an abomination. Whatever feels right.

composer require brunoabpinto/vector

I Turned Images Into 10,000 Tiny HTML Elements Because Why Not

Thu, 29 Jan 2026 23:34:43 +0000

Sometimes the best projects are the ones that solve problems nobody has.

Last weekend, I found myself staring at my screen, thinking about images. Not in a productive way. Not "how can I optimize image loading" or "what's the best format for web." No, I was thinking something far more unhinged:

What if every pixel was just a tiny HTML element?

And thus, IMGML was born.

The Premise

Here's the concept: take an image, read it pixel by pixel, and generate an HTML file where each pixel is represented by a 1x1 <hr> element with a background color matching the original pixel.

That's it. That's the whole thing.

No <img> tags. No <canvas>. No SVG. Just thousands upon thousands of microscopic horizontal rules, arranged in a grid, pretending to be an image.

Does It Work?

Technically? Yes.

Practically? That's a strong word.

Upload a 100x100 pixel image and you get 10,000 HTML elements. A 200x200 image? 40,000 elements. Your browser will render it. Your browser might also ask you why you've done this.

But here's the thing — it does look like the image. Open the HTML file and there it is, your photo, reconstructed entirely from styled <hr> tags. It's beautiful in the way that a Rube Goldberg machine is beautiful. Unnecessarily complex, deeply impractical, and yet somehow satisfying.

Why Though?

I get asked this a lot. "Why would you do this?" "What's the use case?" "Are you okay?"

The answers are: because I could, there isn't one, and debatable.

This is a "what if" project. It exists in that space between curiosity and questionable judgment. The space where you wonder "can I do this?" before asking "should I do this?"

Some might call it a waste of time. I call it a learning experience wrapped in absurdity.

The Tech

For those curious, it's built with Laravel 12 and Livewire. Upload an image, the backend processes it pixel by pixel, and you download your freshly minted HTML monstrosity.

Here's what the output looks like — just a wall of <hr> tags, each with an inline background color:

<r>
  <hr style="background:#cad5d9" />
  <hr style="background:#c5ced3" />
  <hr style="background:#cdd6db" />
  <hr style="background:#dde4ea" />
  <hr style="background:#e4ebf1" />
  <hr style="background:#e1e6ec" />
  <hr style="background:#dadfe5" />
  <hr style="background:#d7dadf" />
  ...
</r>

The code is straightforward. PHP's image functions handle the pixel reading, a loop builds the markup, and Livewire makes the upload/download flow seamless. Nothing revolutionary — just reasonable tools applied to an unreasonable idea.

The Optimization Rabbit Hole

Once I committed to this absurd idea, I became obsessed with making each pixel as small as possible. Here's how that went:

Attempt 1: RGB

<hr style="background:rgb(255, 255, 255)">

Works, but verbose. All those characters add up.

Attempt 2: Hex

<hr style="background:#c5ced3"/>

Shorter. Hex codes are more compact than RGB.

Attempt 3: Drop the self-closing slash

<hr style="background:#c5ced3">

It's optional in HTML5. Every byte counts.

Attempt 4: Drop the quotes

<hr style=background:#c5ced3>

Also valid HTML. We're getting minimal.

Attempt 5: The bgcolor attribute

<hr bgcolor="#c5ced3">

Deprecated, and for some reason only works on <body>. Dead end.

Attempt 6: The color attribute

<hr color=#c5ced3>

This works. It's deprecated, it's not recommended, and it's perfect for this project.

Attempt 7: Drop the hashtag

<hr color=c5ced3>

Turns out the # is optional on hex colors. One more character gone.

This is the shortest I could make each pixel. If you know a way to make it smaller, I'm genuinely curious.

The code is straightforward. PHP's image functions handle the pixel reading:

// Resize to keep things manageable
$image = $this->resizeImage($path, 200, 200);
$resource = imagecreatefromjpeg($image);

$width = imagesx($resource);
$height = imagesy($resource);
$pixels = [];

// Loop through every pixel
for ($y = 0; $y < $height; $y++) {
    for ($x = 0; $x < $width; $x++) {
        // Get color index at this coordinate
        $color = imagecolorat($resource, $x, $y);

        // Convert to RGB array
        $rgb = imagecolorsforindex($resource, $color);

        // Format as hex (no hashtag needed)
        $hex = sprintf('%02x%02x%02x', $rgb['red'], $rgb['green'], $rgb['blue']);

        $pixels[] = $hex;
    }
}

Loop through each row, each column, grab the color, convert to hex, done. Livewire handles the upload/download flow. Nothing revolutionary — just reasonable tools applied to an unreasonable idea.

What I Actually Learned

Despite the silliness, building IMGML reminded me of a few things:

Constraints breed creativity. Limiting myself to just HTML elements forced me to think differently about rendering.
Performance matters everywhere. Processing images pixel by pixel taught me to respect the work that actual image libraries do.
Side projects don't need purpose. Not everything has to ship, scale, or solve a real problem. Sometimes you just build something weird and smile.

Should You Use This?

Absolutely not.

Well, maybe. If you need to:

Confuse a web developer
Create the world's least efficient image format
Prove a point about HTML being turing complete (it's not, but this feels adjacent)
Kill time on a Saturday

Then yes, IMGML is for you.

Try It Yourself

The project is open source. Clone it, run it, upload an image, and watch your browser question its life choices as it renders your photo one <hr> at a time.

Will it change the world? No.

Will it make you briefly happy in a "wow, that's dumb" kind of way? Almost certainly.

And sometimes, that's enough.

Here's my GitHub avatar in IMGML format if you want to see it in action.

IMGML is available on GitHub. Star it if you appreciate the absurdity.

Top Laravel Development Tools Every Developer Needs in 2026

Wed, 28 Jan 2026 11:01:38 +0000

In 2026, web applications will be more complex than ever. Modern developers demand efficiency, scalability, reliability, and speed. Laravel development tools bridge gaps between code and deployment, providing:

Faster feedback loops
Automated testing and quality checks
Seamless local and cloud environments
Enhanced debugging and monitoring
Better team collaboration

Using the right tools isn’t a luxury; it’s essential to maintaining high-quality codebases and delivering value quickly.

Best Laravel Development Tools: Why the Right Tools Matter in 2026

Choosing the right tools can significantly impact your Laravel development workflow. In 2026, the top Laravel tools help developers create applications that are faster, cleaner, and easier to maintain.

1. Laravel Sail

Laravel Sail is the official lightweight development environment for Laravel, powered by Docker. It abstracts away the complexity of container setup and provides a consistent environment across development teams.

Why Developers Love Laravel Sail

Developers appreciate Sail because it eliminates the “works on my machine” problem. Sail ensures everyone on the team runs the same PHP version, services like MySQL/PostgreSQL, Redis, and more, all through Docker.

Who Should Use Laravel Sail

Sail is perfect for:

New Laravel developers who want a standardized environment
Teams collaborating across different operating systems
Projects that rely on multiple services (e.g., queues, caches, search)

Key Features and Benefits

Zero configuration, start sail up spins up services instantly
Supports multiple service containers (MySQL, Redis, Meilisearch)
Customizable PHP versions
Works with major OS environments
Integrated testing environment

Ratings and Developer Feedback

Developers consistently rate Sail highly for ease of use. On community forums, over 90% of users say Sail drastically improved setup time and reduced environment-related bugs.

2. Laravel Octane

Laravel Octane supercharges Laravel applications with lightning-fast performance by leveraging high-performance application servers like RoadRunner and Swoole.

Why Developers Love Laravel Octane

Octane keeps the application bootstrapped in memory, reducing overhead per request. This results in huge performance gains, often 2x to 10x faster than traditional request cycles.

Who Should Use Laravel Octane

Octane is ideal for:

High-traffic websites
Real-time applications
API-first backend services
Developers keen on performance optimization

Key Features and Benefits

Persistent application memory
Worker-based architecture
Faster queue processing
Better throughput and lower latency

Ratings and Developer Feedback

Octane is widely praised for its performance enhancements. Developers building high-scale apps often cite a dramatic improvement in response times after enabling Octane.

3. Laravel Debugbar

Debugbar is a development tool that visually displays debugging and profiling information within your browser.

Why Developers Love Laravel Debugbar

Debugbar gives real-time insights into SQL queries, route details, render times, cache usage, and more without leaving the app. It’s invaluable during development and debugging sessions.

Who Should Use Laravel Debugbar

Developers focused on debugging performance issues
Teams optimizing database queries
Anyone who wants visibility into application internals

Key Features and Benefits

Query logs with execution time
View rendered templates
Exception tracking
Performance profiling

Ratings and Developer Feedback

Laravel Debugbar is considered a staple in the developer toolset. Many report that it helps catch database inefficiencies early in development.

4. Laravel Forge

Laravel Forge is a server provisioning and deployment tool that allows you to deploy Laravel applications without managing servers manually.

Why Developers Love Laravel Forge

Forge abstracts away server configuration, enabling one-click deployments to popular cloud providers like DigitalOcean, AWS, and Linode.

Who Should Use Laravel Forge

Freelancers and small teams without dedicated DevOps
Developers deploying to cloud servers frequently
Projects requiring SSL, queue workers, and scheduled jobs

Key Features and Benefits

Automated server provisioning
One-click deployment
SSL certificate management
Queue and cron management
Service monitoring

Ratings and Developer Feedback

Forge earns high marks for simplifying deployments. Many developers highlight its intuitive interface and reliable performance for production deployments.

5. Laravel Envoy

Envoy provides a simple way to run remote tasks in your Laravel projects via SSH, without writing full scripts.

Why Developers Love Laravel Envoy

Envoy makes automation tasks (deployments, migrations, cache clears) easy using elegant Blade-like syntax.

Who Should Use Laravel Envoy

Developers who want lightweight deployment scripts
Teams without full CI/CD pipelines
Anyone automating common server tasks

Key Features and Benefits

Simple task definitions
SSH-based execution
Reusable scripts
Clean syntax

Ratings and Developer Feedback

Envoy’s simplicity is its biggest asset. Developers enjoy how straightforward it is compared to traditional shell scripting.

6. Laravel Telescope

Laravel Telescope is a powerful debugging assistant that provides real-time insights into your application.

Why Developers Love Laravel Telescope

It delivers deep visibility into requests, logs, database queries, cache operations, queued jobs, and more all in an elegant UI.

Who Should Use Laravel Telescope

Developers needing real-time diagnostics
Those optimizing performance
Teams debugging complex workflows

Key Features and Benefits

Request and exception monitoring
Query performance
Redis and cache insights
Queue job tracking

Ratings and Developer Feedback

The telescope is consistently rated among the most useful Laravel development tools for debugging at scale.

7. PHPStorm with Laravel Plugin

While not Laravel-specific, PHPStorm, combined with a dedicated Laravel plugin,s is a powerful IDE choice for Laravel developers.

Why Developers Love PHPStorm

PHPStorm offers intelligent code completion, refactoring tools, deep framework support, and integrated debugging, crucial for professional development.

Who Should Use PHPStorm

Professional developers
Teams standardizing on a powerful IDE
Large codebases needing code intelligence

Key Features and Benefits

Laravel route and view navigation
Blade and PHP support
Database tools
Integrated test runner
Refactoring tools

Ratings and Developer Feedback

PHPStorm is widely regarded as the top IDE for Laravel development, with many developers claiming it significantly increases productivity.

8. Livewire & Inertia

While technically libraries, Livewire and Inertia have become essential Laravel development tools for building reactive UIs with minimal JavaScript.

Why Developers Love Livewire & Inertia

They allow developers to build modern interfaces without abandoning server-driven workflows.

Who Should Use Them

Teams building dynamic interfaces
Developers preferring PHP-centric UI logic
Projects avoiding full SPA frameworks

Key Features and Benefits

Component-based UI
Reactive updates
Blade integration
Minimal JavaScript

Ratings and Developer Feedback

Both are community favorites. Many Laravel developers praise how they simplify SPA-like experiences without complexity.

Conclusion: Levelling Up with Laravel Development Tools

In 2026, leveraging the right Laravel development tools is crucial for building maintainable, scalable, and high-performing applications. From environment setup with Sail to deployment automation with Forge, and debugging with Telescope and Debugbar, the modern Laravel ecosystem has never been stronger.

Whether you’re a solo developer or working with a professional Laravel development company, integrating these tools into your workflow helps save time, reduce bugs, and significantly improve overall development efficiency.

Ready to supercharge your Laravel projects? Start with the tools above and build with confidence in 2026.

Frequently Asked Questions (FAQs)

1. What are Laravel development tools, and why are they important?

Laravel development tools help developers build, test, debug, and deploy Laravel applications faster and more efficiently. They improve code quality, reduce errors, and streamline the overall development workflow.

2. Which are the best Laravel development tools for beginners in 2026?

The Best Laravel Development Tools for beginners include Laravel Sail, Laravel Debugbar, and PHPStorm with Laravel plugins. These tools simplify environment setup, debugging, and coding for new developers.

3. How do I choose the right Laravel development tools for my project?

Select Laravel development tools based on your project size, performance needs, and team experience. Small projects need basic tools, while large or high-traffic apps benefit from advanced monitoring and deployment tools.

Happy New Year, Laravel Developers! Welcome to 2026

Fri, 02 Jan 2026 12:22:49 +0000

As we step into a brand new year, I want to officially welcome everyone back and wish you a year filled with growth, learning, clean code, and successful deployments

This group remains a space for:

Sharing Laravel tips, patterns, and best practices
Asking questions (no matter how small)
Showcasing projects and ideas
Helping each other grow as developers

Whether you’re just starting with Laravel or you’ve been building production apps for years, your contributions matter here.

Let’s make 2026 a year of:

Better architecture
Scalable applications
Strong community support

Feel free to introduce yourself in the comments—what are you building this year with Laravel?

Once again, welcome, and happy coding!

Mastering Laravel Task Scheduling for Automated Jobs (Compatible with Laravel 10, 11 & 12)

Wed, 29 Oct 2025 10:45:59 +0000

If you’ve ever wanted your Laravel app to automatically perform tasks — like sending daily reports, clearing logs, or running database cleanups — task scheduling is exactly what you need.

Laravel makes this incredibly easy. No need for messy cron scripts or complex automation tools — everything is neatly handled right inside the framework.

In this post, I’ll walk you through how Laravel’s Task Scheduler works, step-by-step, so you can start automating jobs confidently. Whether you’re using Laravel 10, 11, or 12, this guide has you covered.

What is Task Scheduling in Laravel?

Task Scheduling allows your application to automatically perform repetitive tasks at specific intervals — hourly, daily, weekly, or even every few minutes.

Think of it as Laravel’s built-in personal assistant.

Instead of manually running commands every time, Laravel’s scheduler lets you define everything in code — so tasks just happen, reliably.

For example, you could:

Send daily email reports.
Clean up old database records.
Sync data from APIs.
Generate invoices automatically every midnight.

⚙️ Step 1: Understand How the Scheduler Works

Laravel’s scheduler is powered by a single cron job on your server. Once that cron job runs every minute, Laravel handles the rest — deciding which tasks should run and when.

In other words:

One cron job to rule them all.

You don’t have to create multiple cron jobs for different tasks — just one that triggers Laravel’s internal scheduler.

Step 2: Setting Up the Cron Job

First, open your terminal and type:

crontab -e

Then add this line at the end of the file:

* * * * * cd /path-to-your-laravel-app && php artisan schedule:run >> /dev/null 2>&1

Here’s what each part means:

* * * * * → Run every minute.
cd /path-to-your-laravel-app → Change directory to your Laravel project.
php artisan schedule:run → Triggers Laravel’s scheduler.
>> /dev/null 2>&1 → Silently discard output (to keep logs clean).

Once that’s saved, your Laravel app can automatically run any scheduled tasks you define in code.

Step 3: Create Your First Scheduled Task

All task definitions live inside this file:
app/Console/Kernel.php

Open it and find the schedule() method. You’ll see something like this:

protected function schedule(Schedule $schedule)
{
    // Define your tasks here
}

Now, let’s create a simple example — maybe we want to log a message every hour.

protected function schedule(Schedule $schedule)
{
    $schedule->call(function () {
        \Log::info('Hourly job ran successfully at ' . now());
    })->hourly();
}

That’s it!

Laravel will now automatically log this message every hour.

Step 4: Scheduling Artisan Commands

You can also schedule Artisan commands — for example, to run php artisan backup:run every night:

$schedule->command('backup:run')->dailyAt('01:00');

Or a custom command you’ve written yourself:

$schedule->command('emails:send')->everyThirtyMinutes();

Laravel 11 & 12 make this even smoother with improved method chaining, so you can easily attach conditions or environments like this:

$schedule->command('queue:work')
         ->withoutOverlapping()
         ->onOneServer()
         ->everyMinute();

Step 5: Scheduling Shell Commands

Sometimes, you may want to run system-level commands, such as clearing logs or syncing files.
You can use the exec() method for that:

$schedule->exec('rm -rf /var/logs/old_logs')->weekly();

Just be careful when using system commands — always double-check your paths and permissions.

Step 6: Adding Notifications and Error Handling

What if something goes wrong during a scheduled task?

Laravel lets you automatically send notifications when tasks fail or succeed.

Example:

$schedule->command('inspire')
         ->daily()
         ->emailOutputTo('*Emails are not allowed*')
         ->sendOutputTo(storage_path('logs/inspire.log'))
         ->onFailure(function () {
             \Log::error('The scheduled Inspire command failed!');
         });

You can also notify through Slack, Telegram, or custom integrations. (Check Laravel’s Notification system for advanced options!)

Step 7: Automating Database Maintenance

Here’s a real-world example — let’s clean up old user sessions daily:

$schedule->call(function () {
    DB::table('sessions')->where('last_activity', '<', now()->subDays(7)->timestamp)->delete();
})->daily();

This automatically deletes inactive sessions every day at midnight — hands-free!

Bonus Tips

Use `withoutOverlapping()`

Prevents the same job from running multiple times if it hasn’t finished yet.

$schedule->command('emails:send')->everyFiveMinutes()->withoutOverlapping();

Use `onOneServer()`

Perfect for multi-server environments — ensures the job runs only once.

$schedule->command('reports:generate')->daily()->onOneServer();

Use `runInBackground()`

Allows Laravel to keep executing other tasks while one runs in the background.

$schedule->command('backup:run')->daily()->runInBackground();

✅ Conclusion

Laravel’s Task Scheduler is one of the framework’s most powerful (and often underrated) features.
By setting it up once, you can fully automate repetitive tasks — whether it’s sending emails, cleaning data, or backing up files.

And the best part? It’s simple, elegant, and works seamlessly across Laravel 10, 11, and 12.

So next time you find yourself running the same command daily, let Laravel do the heavy lifting. ⚙️

Building a Robust API with Laravel, Clean Architecture, and SOLID Principles

Fri, 17 Oct 2025 15:44:17 +0000

Excited to share a recent back-end project I architected and developed: the Favorite Products API. This isn't just another CRUD API; it's a practical case study on implementing Clean Architecture and SOLID principles with Laravel to build a secure, high-performance, and scalable solution.

The project is a RESTful API designed to manage user's favorite product lists, integrating with an external e-commerce service.

✨ Key Highlights & Challenges Overcome

Performance Optimization (N+1 Problem): I refactored the service layer to transform N+1 external API calls into a single, efficient bulk request (findProductsByIds), dramatically reducing latency.
Security First (IDOR Vulnerability): We patched a critical Insecure Direct Object Reference vulnerability by implementing strict, ownership-based authorization rules in the Form Requests. This is reinforced with feature tests covering 200, 401, and 403 status codes.
Decoupled & Testable Architecture: By using Dependency Inversion (Contracts/Interfaces), we fully decoupled our business logic from the external API client. This makes unit testing a breeze (just mock the interface!) and swapping data sources trivial.
Resilient Error Handling: Instead of letting external service failures fail silently (returning an empty 200 OK), the system now throws custom exceptions, which are caught by a global handler to return a meaningful 503 Service Unavailable response.

The entire stack runs on PHP 8.3/Laravel 12, PostgreSQL, and is containerized with Docker. We also have a comprehensive test suite using Pest and auto-generated, interactive documentation with OpenAPI (Swagger).

Open Source

The project is fully open-source. Feel free to explore the code, learn from the architectural decisions, or even contribute!

Check out the full source code on GitHub: lfrichter/favorite-products-api

I hope this can be a useful resource for anyone looking to deepen their understanding of modern back-end architecture.

Tags: #laravel #php #backend #webdev #architecture

Protecting Your Laravel API from DDoS Attacks: Best Practices

Mon, 13 Oct 2025 21:02:50 +0000

When you deploy your Laravel API to production, it becomes exposed to the wild — and with that comes the risk of Distributed Denial of Service (DDoS) attacks. These attacks can overwhelm your application with traffic, slow down your API, or even take your entire server offline.

As Laravel developers, understanding how to prevent and mitigate these attacks is critical. In this guide, we’ll explore how to use Laravel’s built-in features, server configurations, and external tools to protect your API from overloads.

Understanding DDoS Attacks

A DDoS (Distributed Denial of Service) attack happens when multiple systems flood a server or API with fake requests, exhausting its resources.
In simpler terms — it’s like having thousands of people knocking on your door at once so real visitors can’t get in.

There are two main types of DDoS attacks developers should know:

Network-Level Attacks (Layer 3 & 4): Flooding your server with packets to choke bandwidth.
Application-Level Attacks (Layer 7): Targeting your web app or API directly with valid-looking HTTP requests.

Our focus will be on Layer 7, which is where Laravel operates.

Laravel-Level Protection

Let’s start with what Laravel gives us right out of the box.

1. Rate Limiting Middleware

Laravel includes a built-in throttle middleware that prevents users from making too many requests in a given time.

Route::middleware(['throttle:60,1'])->group(function () {
    Route::get('/api/data', [ApiController::class, 'index']);
});

In this example:

60 = Number of allowed requests
1 = Time period in minutes

If a client exceeds this, Laravel automatically responds with HTTP 429 Too Many Requests.

You can also create custom rate limits for different routes using the RateLimiter facade:

use Illuminate\Cache\RateLimiting\Limit;
use Illuminate\Support\Facades\RateLimiter;

RateLimiter::for('api', function ($request) {
    return Limit::perMinute(30)->by($request->ip());
});

This allows per-IP or per-user limits — offering more flexibility.

Tip: Start with generous limits and tighten them as you observe real traffic. Too strict limits can frustrate legitimate users.

2. Use Caching and Queues

Caching reduces load on your application by avoiding repetitive queries.
Example:

$posts = Cache::remember('posts', 3600, function () {
    return Post::all();
});

Also, using queues (via Laravel Horizon or Redis) prevents slow API responses by offloading heavy tasks to background workers.

3. Log and Detect Suspicious Patterns

You can create middleware to track IPs sending too many requests or unusual payloads.

public function handle($request, Closure $next)
{
    $ip = $request->ip();
    Log::info("Request from IP: $ip");
    return $next($request);
}

Combine this with monitoring tools like Laravel Telescope to visualize unusual behavior.

Server-Level Protection

Even the best Laravel code can’t defend against everything.
Let’s strengthen things on the server side.

1. Use a Firewall

Set up a firewall (like UFW or iptables) to allow only specific ports and IP ranges.

sudo ufw allow 22/tcp
sudo ufw allow 80,443/tcp
sudo ufw enable

This ensures only HTTP(S) and SSH traffic gets through.

2. Install Fail2Ban

Fail2Ban automatically bans IPs that show malicious behavior or too many failed requests.

sudo apt install fail2ban

Configure it to watch Nginx or Apache logs for repeated hits.

3. Add Nginx Rate Limiting

At the reverse proxy layer, you can limit the number of requests per IP before they even reach Laravel.

Example Nginx config:

limit_req_zone $binary_remote_addr zone=api_limit:10m rate=10r/s;

server {
    location / {
        limit_req zone=api_limit burst=20 nodelay;
    }
}

This allows 10 requests per second with a small burst tolerance.

☁️ Infrastructure-Level Protection

To handle larger-scale attacks, combine Laravel and server-side protections with infrastructure solutions:

Cloudflare / AWS Shield: Blocks suspicious traffic before it reaches your server.
Load Balancer: Distributes requests across multiple instances.
SSL (HTTPS): Encrypts traffic, making data tampering harder.
Automatic Scaling: In cloud environments, automatically spin up more instances during high load.

Monitoring and Alerts

Detection is half the battle.
Use monitoring tools like:

Grafana + Prometheus for real-time server metrics.
Laravel Telescope for application-level tracking.
Custom Alerts: Send a Telegram or Slack message when request rates spike.

Example:

*/5 * * * * /usr/bin/php /var/www/html/artisan schedule:run >> /dev/null 2>&1

Set up a cron job to monitor request logs and notify you of anomalies.

✅ Conclusion

No single defense is bulletproof, but layered protection is your best bet.
Laravel’s rate limiting helps filter abuse, while server and infrastructure layers handle more serious floods.

By combining these strategies — middleware, firewalls, monitoring, and CDNs — your Laravel API will be resilient, stable, and ready for real-world traffic surges.

Pro-Tip: Don’t wait for an attack to happen. Simulate high traffic, monitor performance, and tune your defenses early.

Coder Legion - Recent posts tagged laravel

How to Protect a Laravel App with a WAF Using a Placement Checklist

What the sources actually support

Proxy record, DNS, and upstream

What stays inside Laravel

Host floor and proof

FAQ

Does SafeLine ship a Laravel package?

Which attack classes can I cite from the docs?

Will IP rate limiting replace Laravel auth?

What fails the host checklist?

How do I know the WAF is actually in front?

How to Protect a Laravel App with a WAF Cutover Checklist

What belongs in the checklist

How the proxy record should look

What to test before you call it protected

Does SafeLine include a Laravel plugin or middleware?

Can application validation be removed after the WAF is live?

Which documented controls should I enable first?

What proves the cutover worked?

Is the minimum server size enough for every Laravel app?

A Clean Scan Is a Data Point, Not a Verdict: Lessons from PHP2Shell Week

The scan that found nothing

Why a negative result is weak evidence

A ladder of claims

Why the timing makes this sharper

What I would write in a post-patch note

Stripe Webhooks in Laravel: Verify, Dedupe and Retry Safely

Why webhooks, not just the redirect after checkout

The six rules for a safe webhook endpoint

1. Verify the signature

2. Exempt the route from CSRF, and only that route

3. Respond fast, process later

4. Deduplicate by event ID

5. Don't assume order

6. Make handlers safe to run twice

A reliable architecture

Which events to handle

When Stripe can't reach you

Testing webhooks locally

Should you use Laravel Cashier?

A real-world example

Common mistakes to avoid

Key takeaways

I built a generic multi-step flow engine on top of Laravel controllers

How Much Can You Trust a Filesystem Baseline? Design Notes from Laravel Scalpel

What a baseline records

Decision 1: what to leave out

Decision 2: strict or fast hashing

Decision 3: sign the baseline

Decision 4: when to refresh

The trust boundary

Try it

JSON vs MessagePack in Laravel: A Practical API Benchmark

The short answer

What are we comparing?

Add MessagePack to Laravel

How content negotiation works

Run a repeatable benchmark

Results from this package

Decode MessagePack requests

When a route must always return MessagePack

A practical decision guide

Limitations to keep in mind

Try it in your project

Building explainable duplicate detection in Laravel (no ML, no packages)

The Architecture

1. Creating a Property Fingerprint

An Important Database Lesson

2. Candidate Selection

Group your orWhere clauses

3. Scoring the Candidates

Keeping the Explanation

4. Comparing the Area

5. Comparing Rent

6. Comparing Descriptions

7. The Fingerprint Rule

8. Turning the Score Into a Match Level

9. Persisting the Match Details

10. Reviewer Decisions Must Survive Edits

Group your `orWhere` clauses

`similar_text()` Performance

1. The "Localhost" Trap (The `127.0.0.1` Connection Refused)

Your Laravel Isn’t Slow, Your Architecture Is.