{"id":649,"date":"2026-09-04T13:04:17","date_gmt":"2026-09-04T13:04:17","guid":{"rendered":"https:\/\/abrarqasim.com\/blog\/laravel-13-30-chunkby-and-the-storage-path-line-i-had-in-production\/"},"modified":"2026-09-04T13:04:17","modified_gmt":"2026-09-04T13:04:17","slug":"laravel-13-30-chunkby-and-the-storage-path-line-i-had-in-production","status":"publish","type":"post","link":"https:\/\/abrarqasim.com\/blog\/laravel-13-30-chunkby-and-the-storage-path-line-i-had-in-production\/","title":{"rendered":"Laravel 13.30: chunkBy() and the Storage::path() Line I Had in Production"},"content":{"rendered":"

Short version for the impatient: Laravel 13.30 gives collections a chunkBy()<\/code> method, and it quietly closes a hole where Storage::path()<\/code> would happily hand you a filesystem path to your .env<\/code> file. If you have a download endpoint that takes a path from the request, go grep for Storage::path<\/code> before you read the rest of this.<\/p>\n

Now the longer version. I almost skipped this release. Point releases in Laravel land are a weekly thing now, and most of them are the kind of change you nod at and forget. I opened the changelog on Wednesday morning mostly out of habit, saw “chunkBy”, thought “nice, another helper”, and was about to close the tab. Then I got to the part about Storage::path()<\/code> and went a bit cold, because I had written the exact vulnerable line in a client project in 2023. I checked. It had been refactored out since, but not because anyone noticed the problem. We just moved to signed URLs for other reasons. That’s luck, not engineering.<\/p>\n

So this post is two things. A look at chunkBy()<\/code>, because I like collection helpers and this one replaces a pattern I’ve typed dozens of times. And a slightly more serious look at what changed in Storage::path()<\/code>, why it was inconsistent with the rest of the filesystem layer for years, and what it might break when you upgrade.<\/p>\n

What chunkBy() replaces<\/h2>\n

Laravel’s collections<\/a> have had chunk()<\/code> forever. It splits a collection into pieces of a fixed size. Useful for batching, useless for grouping adjacent items that share something.<\/p>\n

For that, the tool since Laravel 8 has been chunkWhile()<\/code>. It takes a callback and starts a new chunk whenever the callback returns false. Every time I’ve used it, the callback compared the current item to the last item of the chunk being built:<\/p>\n

\/\/ Before: chunkWhile with the comparison you always end up writing\n$grouped = $orders->chunkWhile(\n    fn ($order, $key, $chunk) => $order->customer_id === $chunk->last()->customer_id\n);\n<\/code><\/pre>\n
That works. It also has a shape I have to re-derive every time. Which argument is the chunk? Is it ->last()<\/code> or ->first()<\/code> I want? Does ==<\/code> or ===<\/code> matter for the ids coming out of this particular database driver? None of those are hard questions, but they’re the kind of questions that cost me a minute of staring each time, and a minute of staring is exactly what a helper should remove.<\/p>\n
chunkBy()<\/code> is that comparison as a method:<\/p>\n
\/\/ After: chunkBy with a key\n$grouped = $orders->chunkBy('customer_id');\n\n\/\/ Or a callback, if the grouping value needs computing\n$grouped = $orders->chunkBy(fn ($order) => $order->created_at->toDateString());\n\n\/\/ Dot notation works, because the key goes through data_get()\n$grouped = $addresses->chunkBy('address.city');\n<\/code><\/pre>\n
Two details from the pull request<\/a> that I care about. The key resolves via data_get()<\/code>, so nested keys and objects behave the way they do everywhere else in the framework. And the original keys are preserved inside each chunk, which matters if you’re chunking a keyed collection and want to write the results back somewhere by id.<\/p>\n
It also lands on LazyCollection<\/code>, which is the version I’ll use most. A common job I write is “walk a big export in order, emit one file per group”. With chunkWhile<\/code> on a lazy collection I always had a nagging feeling that the $chunk->last()<\/code> lookup was doing more work than it needed to. With chunkBy<\/code> I stop thinking about it.<\/p>\n
The thing to remember: it’s adjacency, not grouping<\/h2>\n
Here’s where I’ll push back on how I’ve seen this described online already. chunkBy<\/code> is not groupBy<\/code> with a different name. It only groups items that are next to each other.<\/p>\n
collect([1, 1, 2, 2, 1, 1])->chunkBy(fn ($v) => $v);\n\/\/ [[1, 1], [2, 2], [1, 1]]  <- three chunks, not two\n\ncollect([1, 1, 2, 2, 1, 1])->groupBy(fn ($v) => $v);\n\/\/ [1 => [1, 1, 1, 1], 2 => [2, 2]]  <- two groups\n<\/code><\/pre>\n
That’s the whole point of it, and it’s the whole trap. If your query doesn’t have an orderBy<\/code> on the column you’re chunking by, you’ll get fragmented chunks and probably not notice in dev because your seed data happens to be sorted. I have been bitten by this with chunkWhile<\/code> and I’ll be bitten by it with chunkBy<\/code>. The fix is boring: sort first, then chunk, and put a test in with deliberately shuffled input.<\/p>\n
When do you want adjacency instead of a full group? Usually when the order carries meaning. Consecutive log lines from the same request. Runs of the same status in a timeline. Line items on an invoice that should be visually grouped under a parent without being reordered. groupBy<\/code> would destroy the sequence; chunkBy<\/code> keeps it.<\/p>\n
Storage::path() finally goes through the normalizer<\/h2>\n
This is the part that made me check old projects.<\/p>\n
Every filesystem call on a Laravel disk goes through Flysystem, and Flysystem normalizes the path before doing anything with it. If the normalized path resolves outside the disk root, it throws PathTraversalDetected<\/code>. So this has been rejected for years:<\/p>\n
Storage::get('..\/..\/..\/.env'); \/\/ throws PathTraversalDetected\n<\/code><\/pre>\n
Storage::path()<\/code> was the one exception. It didn’t call into the driver’s read or write methods, it just asked the PathPrefixer<\/code> to glue the disk root onto whatever string you gave it. No normalization, no traversal check. So on the default local disk:<\/p>\n
\/\/ Before 13.30\nStorage::path('..\/..\/..\/.env');\n\/\/ => "\/var\/www\/app\/storage\/app\/..\/..\/..\/.env"\n\/\/ which is a perfectly valid native path to your .env\n<\/code><\/pre>\n
get()<\/code>, delete()<\/code> and readStream()<\/code> all refused that argument. path()<\/code> returned a string pointing at your secrets. And the string is where it gets dangerous, because path()<\/code> is the method you reach for when you want to hand a file to something that isn’t Flysystem. Like PHP’s own file functions. Or a response:<\/p>\n
\/\/ The line I had in a 2023 project. Do not do this.\nreturn response()->download(Storage::path($request->query('path')));\n<\/code><\/pre>\n
response()->download()<\/code> doesn’t know or care about disk roots. It just streams whatever native path you give it. So the one Laravel method that skipped the traversal check was also the one most likely to be sitting directly in front of fopen<\/code>.<\/p>\n
As of #61343<\/a>, path()<\/code> runs the argument through WhitespacePathNormalizer<\/code>, the same normalizer that League\\Flysystem\\Filesystem<\/code> builds for every other operation. Relative segments now resolve the way the driver resolves them, and anything that escapes the root throws instead of returning a string.<\/p>\n
\/\/ After 13.30\nStorage::path('reports\/..\/invoices\/2026-08.pdf');\n\/\/ => "\/var\/www\/app\/storage\/app\/invoices\/2026-08.pdf"  (resolved inside the root, fine)\n\nStorage::path('..\/..\/..\/.env');\n\/\/ throws League\\Flysystem\\PathTraversalDetected\n<\/code><\/pre>\n
I want to be fair here. This was a known inconsistency rather than a hidden zero-day, and a lot of teams never hit it because they don’t pass request input to path()<\/code>. But “a lot of teams” isn’t “all teams”, and I was on one of the other kind. I wrote about the general shape of this problem, where the tool you use for the review is only as good as the surface it knows about, in my post on running a Laravel security audit with the agent you already use<\/a>. That audit would have flagged the download()<\/code> line. It would not have flagged path()<\/code> itself as the cause, because until this week, path()<\/code> behaving that way was just how it worked.<\/p>\n
What this might break on upgrade<\/h2>\n
The flip side of a hardening change is that code depending on the old behaviour now throws.<\/p>\n
If you have anything that deliberately uses ..<\/code> in a path given to Storage::path()<\/code>, it will now either resolve (if the result stays inside the root) or throw (if it doesn’t). The first case is silent and probably fine. The second case is an exception in production, and the framework isn’t going to guess whether you meant it.<\/p>\n
The pattern I’ve seen most is a “shared” folder one level above the disk root that someone reached with Storage::path('..\/shared\/thing.csv')<\/code> because configuring a second disk felt like too much ceremony. That will now throw. The fix is to configure the second disk. It was always the right answer, it just wasn’t enforced.<\/p>\n
The other one to watch is tests. If you have a test that asserts Storage::path()<\/code> returns a specific string for a path with relative segments, the string changes even when nothing throws, because the segments now collapse. Search your test suite for Storage::path(<\/code> and ->path(<\/code> on a disk before you bump.<\/p>\n
My own upgrade checklist for this release, in the order I actually did it:<\/p>\n
    \n
  1. grep -rn \"Storage::path\\|->path(\" app\/<\/code> and read every hit.<\/li>\n
  2. For each hit, ask: can any part of this argument come from a request, a webhook payload, a queued job payload, or a database column a user can edit?<\/li>\n
  3. If yes, either validate the path against an allow list before it reaches path()<\/code>, or stop using path()<\/code> there entirely and use download()<\/code> \/ response()<\/code> on the disk, which go through the normalizer.<\/li>\n
  4. Run the suite. Anything that throws PathTraversalDetected<\/code> gets fixed, not caught.<\/li>\n<\/ol>\n
    Step three is the real one. The 13.30 change means the traversal case throws, which is far better than silently returning a path. But an exception in front of a download endpoint is still a broken endpoint, and I’d rather reject bad input with a 422 than let it reach the filesystem layer at all.<\/p>\n
    The small one I’ll use every day: worker stop reasons<\/h2>\n
    There’s a third change in this release that isn’t security related and isn’t as clever as chunkBy<\/code>, but I suspect it’ll save me more time than either. queue:work<\/code> now prints why the worker stopped as its last line of output.<\/p>\n
    Before, a worker that exited just exited. The WorkerStopping<\/code> event has carried a WorkerStopReason<\/code> for a while, but you had to register a listener to read it, which is a lot of ceremony for something you usually want to know while staring at a terminal at 11pm.<\/p>\n
    Now:<\/p>\n
    2026-09-01 13:20:40 Worker STOPPED Memory limit exceeded\n<\/code><\/pre>\n
    With --json<\/code> it’s a structured record, with the reason, exit code, jobs processed and memory alongside the per-job lines. The WorkerStopReason<\/code> enum gained a description()<\/code> method covering nine cases, including memory limit, max jobs, max time, queue empty, restart signal and job timeout. Nothing prints under --quiet<\/code> or --silent<\/code>, so it won’t spam a supervisor log.<\/p>\n
    This connects to something I wrote about in the queue defaults I stopped trusting in production<\/a>. A large fraction of “why did my worker die” investigations end with “it hit the memory limit and Horizon restarted it”, and until now the evidence for that was indirect. Having the reason in the log line turns a fifteen minute investigation into a glance.<\/p>\n
    Was it worth a whole post?<\/h2>\n
    I think so, and not because chunkBy<\/code> is exciting. It’s because the Storage::path()<\/code> change is the kind of thing that’s easy to miss in a weekly release note, and it has a real “go check your code” action attached to it. Most weeks the answer to “should I read the changelog” is “probably not”. This week it was yes.<\/p>\n
    A few other things in the release worth a glance if you’re on SQL Server (native sqlsrv:<\/code> DSN strings now parse instead of getting mangled by parse_url<\/code>), or if you build Artisan tooling (Artisan::commandNamed()<\/code> resolves a single command without constructing all of them). The full list is in the Laravel News write-up<\/a> and the official changelog<\/a>.<\/p>\n
    If you want to see how I handle file handling and upgrades on client projects more generally, that’s covered on my work page<\/a>.<\/p>\n
    What to do this week<\/h2>\n
    Run this in every Laravel project you maintain, even the ones not on 13 yet:<\/p>\n
    grep -rn "Storage::path\\|Storage::disk([^)]*)->path" app\/ routes\/\n<\/code><\/pre>\n
    For every line it finds, trace where the argument comes from. If any part of it originates outside your own code, wrap it in validation now. Don’t wait for the upgrade to throw the exception for you. Then bump to 13.30, run your suite, and swap your first chunkWhile<\/code> comparison for chunkBy<\/code> while you’re in there. That last one is just for fun.<\/p>\n","protected":false},"excerpt":{"rendered":"
    Laravel 13.30 adds chunkBy() for adjacent grouping and finally stops Storage::path() escaping the disk root. What changed, what breaks, and what to grep for.<\/p>\n","protected":false},"author":2,"featured_media":648,"comment_status":"","ping_status":"open","sticky":false,"template":"","format":"standard","meta":{"rank_math_title":"","rank_math_description":"Laravel 13.30 adds chunkBy() for adjacent grouping and finally stops Storage::path() escaping the disk root. What changed, what breaks, and what to grep for.","rank_math_focus_keyword":"laravel collections","rank_math_canonical_url":"","rank_math_robots":"","footnotes":""},"categories":[173,52],"tags":[709,56,710,53,154],"class_list":["post-649","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","category-laravel","category-php","tag-collections","tag-laravel","tag-laravel-13","tag-php","tag-security"],"_links":{"self":[{"href":"https:\/\/abrarqasim.com\/blog\/wp-json\/wp\/v2\/posts\/649","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/abrarqasim.com\/blog\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/abrarqasim.com\/blog\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/abrarqasim.com\/blog\/wp-json\/wp\/v2\/users\/2"}],"replies":[{"embeddable":true,"href":"https:\/\/abrarqasim.com\/blog\/wp-json\/wp\/v2\/comments?post=649"}],"version-history":[{"count":0,"href":"https:\/\/abrarqasim.com\/blog\/wp-json\/wp\/v2\/posts\/649\/revisions"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/abrarqasim.com\/blog\/wp-json\/wp\/v2\/media\/648"}],"wp:attachment":[{"href":"https:\/\/abrarqasim.com\/blog\/wp-json\/wp\/v2\/media?parent=649"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/abrarqasim.com\/blog\/wp-json\/wp\/v2\/categories?post=649"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/abrarqasim.com\/blog\/wp-json\/wp\/v2\/tags?post=649"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}