# BitForgeNet Guest Tickets

**Professional event registration, ticketing and door access control for WordPress.**

Built for BitForgeNet Guest Tickets. One payment can cover a whole family — and every guest still
gets their own numbered ticket with their own single-use QR code, so five people cannot
walk in on one scan.

---

## What it does

```
Guest books on your page  →  reference issued, email sent
        ↓
Guest pays you on WhatsApp
        ↓
You open Subscribers and flip the booking to "Paid"
        ↓
One ticket per guest is generated · unique QR · rendered onto your design
        ↓
PDFs emailed automatically
        ↓
At the door, scanning the QR checks that guest in — once, and only once
```

---

## Highlights

**Events that are actually events.** Not a repurposed post editor. A purpose-built form
with series (*Friday Sessions*), edition, line-up (DJ, orchestra, band), venue with a Google
Maps link, organizer profile, dress code, capacity, ticket categories and a registration
window that opens and closes on schedule.

**Families handled properly.** One order, one payment, N attendees — each with their own
name, their own serial number, their own QR token and their own PDF. The buyer also gets
a single combined PDF so one person can print for everyone.

**Tickets you would be happy to hand out.** 100 × 250 mm at 300 dpi, engraved by the
plugin onto your artwork: guest name, serial, category, date, venue, line-up, organizer
contact and the QR. Seven built-in colour variations, plus an HTML5 designer for bespoke
work.

**A door system with no app to install.** Agents scan in the WordPress admin using the
phone's camera, or simply point the native camera at the ticket — the QR opens a signed
verification page that shows a full-screen green or red verdict. USB barcode scanners work
too.

**Security taken seriously.** QR tokens are 192 bits of entropy, stored only as an
HMAC-SHA256 digest keyed with your site's `AUTH_SALT` — a leaked database alone cannot
forge a working ticket. Ticket PDFs live outside the reachable web root and are served
through expiring signed URLs. Every write is nonce-checked and capability-gated, every
query is prepared, every output escaped. Rate limiting, honeypot and time-trap on the
public form.

**No external dependencies.** The QR encoder, the ticket compositor and the PDF writer
are all written from scratch for this plugin. No Composer, no vendor folder, no
multi-megabyte PDF library that breaks on shared hosting. PHP 7.4+ and GD is the whole
requirement list.

---

## Requirements

| | |
|---|---|
| WordPress | 5.8 or newer |
| PHP | 7.4 – 8.4 |
| Extensions | **GD** (with FreeType), `mbstring`, `json` |
| Database | MySQL 5.6+ / MariaDB 10.1+ |
| Disk | ~1.5 MB for the plugin, plus ~250 KB per issued ticket PDF |

Works on virtually any shared host. No shell access, no cron daemon, no external service.

---

## Installation

1. Upload `bitforgenet-guest-tickets.zip` through **Plugins → Add New → Upload Plugin**, or unzip it into
   `wp-content/plugins/`.
2. Activate it. The tables, roles and default ticket design are created automatically.
3. Create a page and put the shortcode on it:

   ```
   [bitforgenet_registration]
   ```

4. **BitForgeNet Guest Tickets → Settings** — set your currency, WhatsApp number, sender email, and point
   *Booking page* at the page you just made.
5. **BitForgeNet Guest Tickets → Venues** and **→ Organizers** — add your first venue and confirm the
   BitForgeNet Guest Tickets profile.
6. **BitForgeNet Guest Tickets → Events → New event** — create your first night.

---

## Shortcodes

| Shortcode | Purpose |
|---|---|
| `[bitforgenet_registration]` | The booking surface. Shows the open event, or a chooser when several are running. |
| `[bitforgenet_registration event="opening-night"]` | Locks the page to one event. |
| `[bitforgenet_registration series="Friday Sessions"]` | Restricts to one series. |
| `[bitforgenet_events limit="6"]` | A listing, no booking form. |
| `[bitforgenet_events past="yes"]` | Past events. |
| `[bitforgenet_event slug="…"]` | One event with its form. |

Deep-link straight to an event by appending `?bfnet_event=<slug>` to your booking page —
handy for WhatsApp.

---

## Roles

| Role | Can do |
|---|---|
| **Administrator** | Everything |
| **BitForgeNet Guest Tickets Manager** | Events, bookings, payments, tickets, designs, reports |
| **BitForgeNet Guest Tickets Door Agent** | Scan tickets. Nothing else. |

Create an account per door agent. Every scan is attributed to them in the activity log.

---

## The check-in flow

Two ways in, both work at the same time:

**In the admin.** *BitForgeNet Guest Tickets → Door scanner*. Pick the event and the gate, tap *Start
camera*. Uses the browser's native barcode detector (Chrome on Android is ideal). Live
counters show who is inside, who is expected, and who has not arrived. There is a manual
box for typed or USB-scanned codes.

**With the phone's own camera.** The QR contains a URL. The agent points the camera, taps
the notification, and gets a full-screen verdict. They sign in once; after that every scan
is one tap.

Either way the ticket is validated against the database, marked used, and a second attempt
is refused with the time of the first entry. Every attempt — valid, duplicate, unknown,
unpaid — is written to the scan log.

---

## Documentation

| Document | Contents |
|---|---|
| [`docs/TICKET-DESIGN-SPEC.md`](docs/TICKET-DESIGN-SPEC.md) | Illustrator artboard sizes, every field coordinate, the QR rules |
| [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md) | Database schema, class map, hooks, security model |
| [`docs/CHANGELOG.md`](docs/CHANGELOG.md) | Version history |
| [`tools/ticket-designer/README.md`](tools/ticket-designer/README.md) | The HTML5 → PNG + field map designer |

---

## Updates

BitForgeNet Guest Tickets updates through WordPress itself, like any plugin from the directory.

---

## Data and privacy

Everything lives in your own database, in eleven `wp_bfnet_*` tables. Nothing is sent
anywhere. IP addresses are stored only as salted hashes. Uninstalling **preserves** your
data unless you explicitly tick *Delete all BitForgeNet Guest Tickets data* in Settings first.

---

## Licence

GPL-2.0-or-later, matching WordPress.

Bundled fonts: Poppins and Lora, both under the SIL Open Font License 1.1.
