CLAUDE.md — Databrae

Project Overview

Databrae is a PHP web application that generates printable library spine labels with Data Matrix 2D barcodes. It serves as a low-cost alternative to RFID for library inventory, shelf-reading, and weeding workflows. Licensed under GNU GPL v3.

Tech Stack

Language: PHP >= 8.1 (no framework — standalone)
Frontend: HTML5, CSS3, vanilla JavaScript
Dependencies: Composer — single dependency: tecnickcom/tc-lib-barcode ^2.4
Required PHP extensions: BCMath, GD, PCRE
Database: None (stateless, no persistence)
Tests: None currently

Project Structure

databrae/
├── index.php          # Single label generator (simple form)
├── index-csv.php      # Bulk CSV label generator with sheet templates
├── composer.json       # Dependency config
├── composer.lock
├── vendor/             # Composer dependencies (do not edit)
├── README.md
└── LICENSE

Key Files

index.php — Single-label mode. Form with 4 data fields + barcode field. Renders one Data Matrix barcode as inline SVG.
index-csv.php — Advanced mode. CSV upload (auto-detects delimiter), sheet template system with customizable page/label dimensions, pagination. Required CSV headers: data1, data2, data3, data4, barcode.

Coding Conventions

declare(strict_types=1) used in index-csv.php
Variables: snake_case ($page_width_in, $csv_file)
Functions: snake_case (safe(), strip_bom(), detect_delimiter())
CSS classes: kebab-case (.label-card, .barcode-block)
All user input escaped via safe() helper wrapping htmlspecialchars(ENT_QUOTES, 'UTF-8')
Null coalescing (??) for safe defaults
Barcodes rendered as inline SVG (not images)
CSS uses physical units (in, cm) for print accuracy
@media print rules hide UI and preserve label dimensions

Common Tasks

# Install dependencies
composer install

# Run locally (PHP built-in server)
php -S localhost:8000

Architecture Notes

No routing — each PHP file is its own entry point
No database or session state — all processing is per-request
CSV files are processed in memory (10MB max upload)
Sheet template parameters passed via POST, with sensible defaults (Demco 1.5"×1.0" on Letter)
Error handling: validation errors collected in array, displayed as list; barcode generation wrapped in try-catch

2.4 KiB Raw Permalink Blame History Unescape Escape