# Green Submissions

**Submission Manager by Glenn Lyvers, provided freely through [greensubmissions.com](https://greensubmissions.com)**

A complete, self-hosted submission manager for literary journals, magazines,
and small presses — the same software that has run a working poetry journal
since 2010, refined continuously and released here as free shareware.

> **Full documentation** — an exhaustive install / writer / editor guide —
> is online at [greensubmissions.com/docs/](https://greensubmissions.com/docs/).

Writers create accounts, upload their work, track statuses, and exchange
revision messages with your editors. Your staff work a sortable slush pile,
run blind reading if they wish, manage editions and contests, grant
submission credits, take contest entry fees through PayPal, and mass-mail
contributors — all from a built-in Editorial Suite.

---

## License (the short version)

Free for everyone, including commercial use. The **only** requirement is that
the footer credit — *"Submission Manager by Glenn Lyvers, provided freely
through greensubmissions.com"* — remains visible with its link active on
every page. That's it. See `LICENSE.txt` for the details.

---

## Features

### For writers
- Simple signup with email confirmation (name + email only)
- Upload one attachment per submission (allowed file types are configurable)
- Track every submission's status from a personal dashboard
- In-thread revision collaboration with editors (messages + file exchange)
- Public contributor directory with self-managed biographies (safe,
  whitelisted rich text)
- Optional pen names; writers control their public visibility
- Instant self-service withdrawal of pending submissions (toggleable)
- Two-step verified email changes; secure password resets

### For editors and admins
- **Slush pile** with sorting, scores, IP display, and paid-entry priority
- **Blind reading mode** (hide author identity from editors) — one setting
- **Editions & contests**: open/close editions, per-contest entry fees
- **Contest fees via PayPal** (Checkout / Orders v2 REST — server-side
  capture; the browser is never trusted to say "paid")
- **Submission credits**: grant fee waivers writers can spend on contests,
  with a full audit ledger
- **Volunteer readers**: application queue, approval flow, 1–10 ratings
- **Status system**: add your own custom statuses beyond
  Accepted / Rejected / Revision Requested
- **Mail center**: message everyone, an edition's contributors, or one
  writer, with mail-merge variables
- **Guidelines editor** built into the admin area
- New-submission email notifications to any staff list

### Security (built in, no plugins)
- PDO prepared statements everywhere; no string-built SQL
- Passwords hashed with `password_hash()` (bcrypt/argon per your PHP)
- CSRF tokens on every form; session fixation protection at login
- Hardened session cookies (HttpOnly, SameSite, Secure on HTTPS)
- Bot protection on login/signup/reset: **Cloudflare Turnstile** (free) if
  you add keys, or the built-in image captcha with zero configuration
- Upload folder locked down (`.htaccess` blocks all script execution)
- Config files blocked from direct web access

---

## Requirements

| Requirement | Notes |
|---|---|
| PHP **8.0+** (8.3 recommended) | shared hosting is fine |
| MySQL 5.7+ / MariaDB 10.3+ | one database |
| PHP extensions | `pdo_mysql`, `curl`, `gd`, `mbstring`, `openssl` |
| Apache with `.htaccess` support | (or port the two .htaccess files to your server) |
| An SMTP mailbox | for confirmations, resets, and notifications |
| ~25 MB disk | plus room for uploaded submissions |

> **Need a host?** [instantaccess.net](https://instantaccess.net) offers
> deeply discounted, fast, reliable hosting and already runs this software
> for a multitude of customers — every requirement above is met out of the
> box, and their support knows this app. It's the zero-friction option.

---

## Installation (5 minutes)

### The easy way — web installer

1. **Create a database** and a database user with full privileges on it
   (cPanel → *MySQL Databases*).
2. **Upload** the contents of this package to your server — either a
   subfolder like `/submit/` or a subdomain like `submissions.yoursite.com`.
3. **Visit the folder in your browser** (e.g. `https://yoursite.com/submit/`).
   You'll be redirected to the installer automatically.
4. Follow the four steps: requirements check → database & site identity →
   first administrator → done.
5. **Delete the `/install` folder.** The installer refuses to run twice, but
   don't leave tools lying around.

### Manual install (if you prefer)

1. Import `install/schema.sql` into an empty database (phpMyAdmin → Import).
2. Copy `config-sample.php` to `config.php` and fill in the values.
3. Insert your first admin into `sm_editors` (user_type `superadmin`,
   password from `password_hash()`), or just open `/install/index.php?step=3`
   to create it, then delete `/install`.

### First-run checklist (in the Editorial Suite, `/editors/login.php`)

1. **SMTP** — enter your outgoing-mail settings first; signups can't be
   confirmed without email.
2. **Editions** — create an edition and mark it *Open for Submissions*.
3. **Guidelines** — replace the placeholder guidelines with your own.
4. **Settings** — review toggles (blind reading, withdrawals, downloads,
   allowed file types, scores, notification emails…).
5. **PayPal** *(optional)* — for contest fees, add REST credentials on the
   PayPal page or in `paypal_config.php`, sandbox-test, then flip to live.
6. **Staff** — add your editors and approve volunteer readers.

---

## Folder map

```
/                     writer-facing app (index, signup, submit, dashboard…)
/editors/             the Editorial Suite (staff login, slush pile, admin)
/attachments/         uploaded submissions (script execution disabled)
/captcha/             built-in image captcha (used when Turnstile is off)
/install/             web installer + schema.sql  ← DELETE AFTER INSTALL
/phpmailer/           bundled PHPMailer (SMTP email)
/tinymce/             bundled TinyMCE (bio & guidelines editors)
config-sample.php     configuration template (installer writes config.php)
paypal_config.php     optional PayPal credentials file
styles.css            the entire design system — restyle freely
LICENSE.txt           free-use license (keep the footer link!)
```

## Customizing

- **Branding**: your journal name, tagline, and links come from `config.php`
  — no code edits needed. Fonts/colors live in `styles.css` (CSS variables
  at the top).
- **Submission limit**: writers may submit 3 pieces per edition by default —
  change `SUB_LIMIT_REGULAR` in `credits.php`.
- **Admin folder**: you may rename `/editors/` to anything (all its links
  are relative). If you do, update the one reference in
  `editors/forgot-password.php` and tell your staff the new URL.
- Keep the footer credit intact (see `LICENSE.txt`).

## Upgrading

Overwrite the application files with the new release, keeping your
`config.php`, `paypal_config.php`, `guidelines_content.html`, and
`/attachments/`. Release notes will list any SQL migrations.

## Support

This software is provided as-is (see `LICENSE.txt`), but bug reports are
welcome through [greensubmissions.com](https://greensubmissions.com).
Hosting-related questions are best answered by a host that already runs
this app — [instantaccess.net](https://instantaccess.net).
