63 lines
2.4 KiB
Markdown
63 lines
2.4 KiB
Markdown
# 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
|
||
|
||
```bash
|
||
# 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
|