dir2json - a PHP CLI script to output the contents of a folder tree into a JSON object

dir2json - a PHP CLI script to output the contents of a folder tree into a JSON object

When you're working with Javascript frameworks such as Phaser.io or CraftyJS you often need to retrieve a set of resources - such as images, videos, sounds & more - from your project asset folders and load/preload them into your code. It's easy when you already know the URL, but it can be tricky if you need to rely to your assets folder tree only, because... well, because Javascript simply isn't allowed do that: as a matter of fact, for security reasons, it cannot issue IO calls at all. The only thing it could do would be to load a structured index of sort - possibly built using a standard, readable format - which can be used to "browse" in order to retrieve the needed contents.

That's when dir2json comes to help.

What does it do

It's basically a PHP CLI script that can be used to ouput the contents of a whole directory tree into a JSON-formatted file.

To properly understand it, let's do a quick example. Suppose we have a directory tree structure like this:

This would be the file generated by dir2json:

As we already said, it can be very useful when working with Javascript frameworks and/or similar scenarios where you need to load/browse/show a directory structure without being allowed to access the system IO.

Conversion rules

The json conversion is handled by the native php json_encode  function (available in PHP 5 >= 5.2.0, PECL json >= 1.2.0, PHP 7). For further info on PHP's json_encode function, read here: http://php.net/manual/en/function.json-encode.php

The generated JSON object will adopt the following conventions:

  • If a folder contains only files (without subfolders), they will be listed as items of a single array.
  • If a folder contains one or more subfolders, each one will be listed as a key/value array.
  • If a folder contains files and subfolders, both will be listed as a key/value array: each file will have an auto-generated numeric key starting from 0 (numbers already used by a subfolder's name will be skipped).


The code it's meant to be used as a dedicated CLI script, but you can also execute it from a standard, web-hosted PHP page by populating the $argv[]  array directly from code. If you need further help to implement it into a PHP page, contact me and I'll update the docs accordingly.

From CLI

JSON_OPTIONS  is a bitmask consisting of:


The behaviour of these constants is described on the JSON constants page in the official PHP docs:



This example uses JSON_PRETTY_PRINT, a constant that will tell json_encode  to output the JSON result in a readable way using spaces, linefeeds and indents.

For more info, please read the dir2json's project page on this website.

Download links


That's it for now: hope you'll like it!


About Ryan

IT Project Manager, Web Interface Architect and Lead Developer for many high-traffic web sites & services hosted in Italy and Europe. Since 2010 it's also a lead designer for many App and games for Android, iOS and Windows Phone mobile devices for a number of italian companies. Microsoft MVP for Development Technologies since 2018.

View all posts by Ryan

One Comment on “dir2json - a PHP CLI script to output the contents of a folder tree into a JSON object”

  1. “If you need further help to implement it into a PHP page, contact me and I’ll update the docs accordingly”…

    Hi Ryan, can you give more info about using this in a php web page ?

Leave a Reply

Your email address will not be published. Required fields are marked *

The reCAPTCHA verification period has expired. Please reload the page.

This site uses Akismet to reduce spam. Learn how your comment data is processed.