📄 Working with Files and JSON

The Shape of File I/O

A file on disk is just a sequence of bytes. To turn those bytes into something useful your program does two steps in a row: it reads the raw bytes into a string, then it decodes that string into a structure (often via JSON). Writing runs the same pipeline in reverse.

Reading a Text File

The simplest case: read an entire text file into a string. Note that Node's file API is asynchronous by default — you await it — while Python and PHP read synchronously.

// Node.js — the modern promise-based API
import { readFile } from 'node:fs/promises';

const text = await readFile('notes.txt', 'utf8');
console.log(text);

# Python — open() with a context manager (auto-closes)
with open('notes.txt', 'r', encoding='utf-8') as f:
    text = f.read()
print(text)

<?php
// PHP — one call reads the whole file into a string
$text = file_get_contents('notes.txt');
echo $text;

Reading line by line

For large files you often don't want the whole thing in memory at once:

# Python — iterate a file object line by line, lazily
with open('big.log', 'r', encoding='utf-8') as f:
    for line in f:
        process(line.rstrip('\n'))

<?php
// PHP — file() returns an array of lines
foreach (file('big.log', FILE_IGNORE_NEW_LINES) as $line) {
    process($line);
}

Writing a Text File

Writing replaces the file's contents (or creates it if absent). A separate append mode adds to the end instead.

// Node.js
import { writeFile, appendFile } from 'node:fs/promises';

await writeFile('out.txt', 'Hello\n', 'utf8');   // overwrite / create
await appendFile('out.txt', 'Another line\n');    // add to the end

# Python — mode 'w' overwrites, 'a' appends
with open('out.txt', 'w', encoding='utf-8') as f:
    f.write('Hello\n')

with open('out.txt', 'a', encoding='utf-8') as f:
    f.write('Another line\n')

<?php
// PHP — file_put_contents overwrites; add FILE_APPEND to append
file_put_contents('out.txt', "Hello\n");
file_put_contents('out.txt', "Another line\n", FILE_APPEND);

Parsing & Serializing JSON

JSON is just a string in a specific format. Parsing turns that string into a native structure; serializing turns a native structure back into a string. This step is entirely separate from touching the disk.

Parse: text → object

// Node.js
const obj = JSON.parse('{"name":"Ada","tags":["a","b"]}');
obj.name;      // 'Ada'  -> a normal JS object

# Python
import json
obj = json.loads('{"name":"Ada","tags":["a","b"]}')
obj['name']    # 'Ada'  -> a dict

<?php
// PHP — pass true to get an associative array (else you get stdClass)
$obj = json_decode('{"name":"Ada","tags":["a","b"]}', true);
$obj['name'];  // 'Ada'

Serialize: object → text

// Node.js — the 3rd arg is indent width for pretty output
const data = { name: 'Ada', tags: ['a', 'b'] };
JSON.stringify(data);          // '{"name":"Ada","tags":["a","b"]}'
JSON.stringify(data, null, 2); // pretty, 2-space indent

# Python — indent= for pretty; ensure_ascii=False keeps é, 中 as-is
json.dumps(data)                          # compact
json.dumps(data, indent=2, ensure_ascii=False)  # pretty + unicode

<?php
// PHP — flags control formatting
json_encode($data);                                    // compact
json_encode($data, JSON_PRETTY_PRINT | JSON_UNESCAPED_UNICODE);

The Read–Modify–Write Round Trip

Combine the two halves and you get the everyday pattern: load a JSON file into an object, change something, and write it back. Here it is end-to-end in each language, with the parse guarded against a malformed or missing file.

// Node.js — bump a counter stored in data.json
import { readFile, writeFile } from 'node:fs/promises';

let data;
try {
  data = JSON.parse(await readFile('data.json', 'utf8'));
} catch (err) {
  data = { count: 0 };   // file missing or invalid -> start fresh
}

data.count += 1;
await writeFile('data.json', JSON.stringify(data, null, 2), 'utf8');

# Python
import json

try:
    with open('data.json', 'r', encoding='utf-8') as f:
        data = json.load(f)          # load() reads + parses in one step
except (FileNotFoundError, json.JSONDecodeError):
    data = {'count': 0}

data['count'] += 1
with open('data.json', 'w', encoding='utf-8') as f:
    json.dump(data, f, indent=2)     # dump() serializes + writes

<?php
// PHP
$data = ['count' => 0];
if (is_readable('data.json')) {
    $decoded = json_decode(file_get_contents('data.json'), true);
    if (is_array($decoded)) {
        $data = $decoded;            // guard against null on bad JSON
    }
}

$data['count'] = ($data['count'] ?? 0) + 1;
file_put_contents('data.json', json_encode($data, JSON_PRETTY_PRINT));

Encoding, Binary & Error Cases

Text vs binary

Text mode decodes bytes into characters using an encoding. Binary mode hands you the raw bytes untouched — use it for images, PDFs, or anything that isn't human-readable text.

# Python — 'rb' = read bytes; no encoding argument in binary mode
with open('logo.png', 'rb') as f:
    raw = f.read()          # a bytes object, not a str

// Node.js — omit the encoding to get a Buffer of raw bytes
import { readFile } from 'node:fs/promises';
const raw = await readFile('logo.png');   // a Buffer

Common error cases to handle

<?php
// PHP — make json_decode throw instead of returning null
try {
    $data = json_decode($text, true, 512, JSON_THROW_ON_ERROR);
} catch (JsonException $e) {
    // now handled like Python / Node
}

💡 Safe-write tip: To avoid a half-written file if the process dies mid-write, write to a temp file first and then rename it over the target. A rename is atomic on most filesystems, so readers never see a partial file.

Hands-on Exercise

// Node.js — visits.js  (run with: node visits.js)
import { readFile, writeFile } from 'node:fs/promises';

let data;
try {
  data = JSON.parse(await readFile('visits.json', 'utf8'));
} catch {
  data = { total: 0, lastVisit: null };
}

data.total += 1;
data.lastVisit = new Date().toISOString();

await writeFile('visits.json', JSON.stringify(data, null, 2), 'utf8');
console.log(`Total visits: ${data.total}`);

# Python — visits.py  (run with: python visits.py)
import json
from datetime import datetime

try:
    with open('visits.json', 'r', encoding='utf-8') as f:
        data = json.load(f)
except (FileNotFoundError, json.JSONDecodeError):
    data = {'total': 0, 'lastVisit': None}

data['total'] += 1
data['lastVisit'] = datetime.now().isoformat()

with open('visits.json', 'w', encoding='utf-8') as f:
    json.dump(data, f, indent=2)

print(f"Total visits: {data['total']}")

<?php
// PHP — visits.php  (run with: php visits.php)
$data = ['total' => 0, 'lastVisit' => null];
if (is_readable('visits.json')) {
    $decoded = json_decode(file_get_contents('visits.json'), true);
    if (is_array($decoded)) {
        $data = $decoded;
    }
}

$data['total'] = ($data['total'] ?? 0) + 1;
$data['lastVisit'] = date('c');

file_put_contents('visits.json', json_encode($data, JSON_PRETTY_PRINT));
echo "Total visits: {$data['total']}\n";

Summary & Quiz

📚 Further Reading

• Node.js docs — fs/promises API
• Python docs — the json module
• PHP manual — json_decode

🚀 What's Next?

You now have every language-level building block — data structures, error handling, and file/JSON I/O. Next you'll put them together in the Weekend Project: A Polyglot Mini-Server, building the same small server in each language to feel their differences first-hand.