Pillbox

A medication and health tracker built with PHP and MySQL. It works in mobile and desktop browsers.

How to use it: see the documentation, also in the app under Docs in the footer (and the ? next to headings).

• Medications: search the NHS medicines dictionary (dm+d) or type them in; add, edit, stop (history is kept) or permanently delete. Each medicine can have several dose times with different amounts, on chosen weekdays, and between set dates (useful for reducing doses). "As needed" medicines can have a daily maximum, and any medicine an optional expiry date (set when you add it or collect a new supply), flagged on Today when it's within 30 days or past. Dose changes only apply from now on: past days keep the dose they had, and if any of today's doses are already logged the change starts tomorrow (or on a later "takes effect from" date). The latest change under each medicine is hidden unless you tick Show dose changes. Doses can also repeat every few days or weeks, only on some days of a repeating cycle (e.g. sequential HRT) or of each calendar month, and a minimum time between doses refuses a dose logged too soon (with "log anyway" if it really was taken).
• Today view: tick off doses (Take, Skip or Undo), see missed doses, get low-stock warnings and log as-needed doses.
• Health readings: blood pressure, heart rate, blood glucose, ketones, weight, temperature, SpO₂, breathing rate, peak flow, INR, cholesterol, pain, mood, sleep, fluid intake, steps, and symptoms or side effects. Each user picks the ones their doctor wants, and can add their own custom measurements. Every measurement has trend charts and averages.
• Apple Health import: upload the Health app's export, or sync automatically every day from an iPhone using Shortcuts or the Health Auto Export app.
• History and adherence: each day's doses, plus the percentage of doses taken for each medicine, and each day's Care routines, Mind habits and self-care checklist, which can be ticked off afterwards (up to a year back).
• Dose change history: changes to strength, amount or timing are recorded automatically, e.g. "Increased from 10mg to 20mg a day", with the date and reason. Each medicine has a timeline, and you can add earlier changes by hand.
• Travel mode: plan trips across time zones and choose to switch to local time, stay on home time, or shift gradually by 1–4 hours a day, with a day-by-day preview of dose times.
• Care (the Care tab): dental care, eye care, sleep, physical activity & rehab, respiratory, allergies, private health care, diabetes, blood tests, prescriptions and payments, foot health, periods and contraception, menopause, pregnancy, blood pressure, migraine, thyroid, ADHD and autism, gender-affirming care, hearing, skin and wound care, mobility and supports, emergency and first aid, sharps and disposal, screening and vaccinations. Choose which appear under Account → Health profile, along with your date of birth and sex (for screening). Each category can have:
  • Routines ticked off on the Today page: one-tap presets (brushing, screen breaks, physio exercises with reps, stretching, foot checks, monthly mole checks, CPAP cleaning...) or your own, at set times on chosen days or every few days or weeks, with a streak and a 7-day view for catching up on missed ticks.
  • Blood tests that medicines need (lithium, methotrexate, INR, thyroid, kidney...), linked to the medicine, with a results log; and Prescriptions and payments: PPC and HRT PPC (start date and length), MedEx, MatEx and HC2 certificates with renewal reminders, a cost log, and a calculator showing whether a PPC would save money (prices in config/config.php). Medicines can be marked as a private prescription or bought without one, with their price: these are logged when a new supply is recorded and kept out of the PPC sums.
  • Blood pressure: guided home monitoring the NICE way (2 readings a minute apart with a 1-minute timer, morning and evening for up to 7 days, day 1 left out of the average) against the home target (under 135/85, or 145/85 from 80, or what your clinician sets); pulse and irregular heartbeat flags; a 90-day chart with blood pressure medicine changes marked, and morning and evening averages; medicines recognised by type (ACE inhibitors, ARBs, calcium channel blockers, diuretics, beta blockers) with one-tap side effects; sick-day rules only if your clinician gave them; advice for readings of 180/120 or more and low readings (also in Readings); blood tests after starting an ACE inhibitor or ARB; a monitor CSV import (such as Omron); prompts for pregnancy and combined contraception; and a clinician summary.
  • Migraine and headaches: a diary (start and end or ongoing, severity, where, migraine, aura, symptoms, triggers, and medicines taken with how well they helped, optionally logged as a dose); headache, migraine and acute-medicine days each month (including as-needed doses logged on Today); medication overuse warnings at the NHS thresholds (15+ days of simple painkillers, 10+ of triptans, opioids, combination painkillers or a mix) with an early nudge from 8 days; common triggers; menstrual migraine (days -2 to +3); weather for your town (Open-Meteo: pressure falls, low pressure, temperature changes, heat and humidity compared with headache days, and a heads-up when a big pressure fall is forecast); preventive treatment with a before-and-after review; the evidence NICE uses for CGRP medicines; warnings for topiramate (pregnancy prevention) and for combined hormonal contraception with migraine with aura (also on Meds); red flags; and a clinician summary. Admins can switch weather off with in the section (or under Site settings).
• Care summary: a printable page (Care → Summary) for any period and one or all categories: how often each routine task was done, every check, screening and vaccination with last done and next due, sleep and cycle figures.
• Mind (its own tab; switch it off under Account → Health profile):
  • Check-ins: mood (1 to 5), energy, motivation, anxiety (0 to 10), words that fit, triggers and a note, with 30 and 90-day charts and patterns such as "mood is lower after under 6 hours of sleep". No streaks.
  • Help now (the lifebuoy in the header, on every page): UK crisis lines (999, NHS 111 option 2, Samaritans, Shout), editable for other countries, your own people and professionals, and your safety plan in the NHS / Stanley-Brown format. A check-in saying you're having thoughts of harming yourself, or any answer above "Not at all" to PHQ-9 question 9, goes straight here.
  • Coping toolkit of what helps you, shown after a low check-in, plus box breathing and 5-4-3-2-1 grounding timers.
  • PHQ-9 and GAD-7 with scores over time; journal with prompts, and CBT thought records.
  • Therapy and care: therapy and psychiatrist appointments (suggested topics include your mood since last time, PHQ-9/GAD-7 changes, medication notes and your running list of questions), actions agreed, care team contacts.
  • Mental health medication: mark medicines as such, and keep side-effect and "how I've felt since the change" notes.
  • Today on the Mind page: a self-care checklist (eaten, water, outside...), planned activities, and reminders to get in touch with people you've chosen. After a few low days, your own early-warning steps are shown.
  • Symptoms of your own, rated in each check-in; activity scheduling with enjoyment and achievement ratings; habits and routines (morning, evening, screen-time limits) on Today; a wins and gratitude log shown on hard days.
  • Staying well plan (relapse prevention: well, early warning signs, crisis) and a printable advance statement.
  • Summary: a printable 4, 8 or 12-week report (notes and journal only if you tick them).
  • Privacy: an optional PIN (locks after 10 minutes; crisis contacts are never locked), and a daily check-in reminder in the calendar feed worded just "Pillbox check-in".
• Appointments: GP, specialist, hospital, dentist, optician, blood tests and more, with a private calendar link per person that Apple Calendar, Google Calendar and Outlook can subscribe to.
• Doctor's report (the Report tab): a printable summary (or save as PDF) of allergies, current medicines, changes, adherence, as-needed use, appointments and readings, plus doses and readings as CSV.
• Accounts: local username/password, Microsoft Entra ID and other OpenID Connect single sign-on, with optional self sign-up and admin approval; two-factor sign-in (authenticator apps with backup codes, and security keys); Remember this device; Forgotten your password? by email; and a list of active sessions that can each be signed out. Supports multiple users, each with private data, plus an admin page.

Appointments and the calendar link

The calendar icon in the top bar opens Appointments. Add the date, time, length, type (GP, specialist, hospital, dentist, optician, blood test, scan, physio, mental health, vaccination, ...), who it's with, where, notes and an optional reminder. The next two weeks also show on the Today page, and the doctor's report lists appointments.

Add to your calendar creates a private calendar link (calendar.php?token=…) unique to each person. Subscribe to it in Apple Calendar, Google Calendar or Outlook, and new or changed appointments appear there automatically. Calendar apps check every few hours.

• Anyone with the link can see that person's appointments. Notes are left out unless the person switches them on. Make a new link stops the old one working immediately, and Turn off link disables it.
• The link uses the site address from Admin → Site settings (or 'public_url' in the app section of config/config.php). Until one is set, Pillbox uses the address an administrator last opened it at, never just the address a request claims (which anyone can fake). If links show the wrong address, set it.

Preparing for an appointment

Tap an appointment to open its page. It has:

• Questions to ask, ticked off on the day, with space for each answer.
• Suggested topics from what you've recorded since your last appointment: side effects, missed doses, heavy use of as-needed medicines, recent dose changes, prescriptions running low, and blood pressure.
• After the appointment notes for what was decided.

Print / save as PDF gives a one-page sheet with tick boxes and space to write answers.

Travel mode

Meds → ✈ Travel lets you plan a trip: where you're going (its time zone), when you leave and when you get back, and how dose times should change:

Option	What happens (e.g. 08:00 dose, London → Tokyo)
Switch to local time	08:00 Tokyo time. Home time resumes the day after you get back.
Stay on home time	16:00 Tokyo time, the same moment as 08:00 in London.
Shift gradually	Moves 1–4 hours a day until it's 08:00 Tokyo time, then moves back the same way after you return.

While you're away, all times in Pillbox are shown in local time, and each dose also shows its home time. If any medicines are time-critical (insulin, contraceptive pills, epilepsy, Parkinson's or HIV medicines), check with a doctor or pharmacist before travelling.

Apple Health

Apple doesn't let websites read Apple Health directly, so Readings → Import from Apple Health offers two ways:

1. Import the Health export. In the Health app, tap your picture → Export All Health Data, then upload export.zip (from the phone itself or a computer). Large exports are uploaded in pieces, so your web host's upload limit doesn't matter. Re-importing never creates duplicates.
2. Sync automatically. Create a private sync link, then use the Health Auto Export app (REST API automation, JSON) or an Apple Shortcuts automation to post new readings to it every day.

What's imported:

• Each reading: blood pressure, weight, blood glucose, body temperature, peak flow.
• One value per day: resting heart rate, oxygen saturation, breathing rate, steps, and sleep (time asleep).

Units are converted to Pillbox's (kg, mmol/L, °C, %). Steps and sleep recorded by both an iPhone and a Watch are only counted once. Measurements that receive data are switched on automatically. Imported readings are labelled "Apple Health", and Remove all imported readings takes them out again without touching readings you typed in yourself.

The server needs PHP's xmlreader extension (standard) and, to read export.zip directly, zip. Without zip, unzip the export and upload export.xml instead.

Requirements

• Apache 2.4 with mod_rewrite (normally enabled) and ideally mod_headers
• PHP 8.1+ with pdo_mysql, curl, openssl, mbstring; zip, xmlreader and zlib for imports, policy documents and self-updates (all standard)
• MySQL 8.0+ or MariaDB 10.5+
• HTTPS (required for Entra ID sign-in and strongly recommended anyway)

Installing on an Apache server

1. Upload the whole folder, for example to /var/www/pillbox or into your web space.

2. Create a database and user, either in phpMyAdmin or with:

   CREATE DATABASE pillbox CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
   CREATE USER 'pillbox'@'localhost' IDENTIFIED BY 'a-strong-password';
   GRANT ALL PRIVILEGES ON pillbox.* TO 'pillbox'@'localhost';
   

   You don't need to import any tables, because Pillbox creates them the first time it is opened. You can import database/schema.sql yourself if you prefer.

3. Configure: copy config/config.example.php to config/config.php and fill in the database details. config/config.php is the only settings file; it is git-ignored, so your passwords stay off GitHub. If the site is in a sub-folder (e.g. https://example.com/pillbox/), set 'base_path' => '/pillbox'. If config/config.php is empty or damaged (for example overwritten by an upload), Pillbox shows a page saying so rather than an error.

4. Make storage/ writable by the web server: chown www-data storage (or set it to 775 in your file manager). It holds sessions, the encryption key for private pages and sign-in tokens (app.key), the notification keys, the setup code, update backups, encrypted photos and caches. Back it up, especially app.key: without it, private pages can't be read.

5. Open the site. On a new install you'll be asked to create the first administrator account, with a one-time setup code so nobody else who finds the site first can take it over. The code is in storage/setup_code.txt on the server, and in PHP's error log (docker logs, or your host's error log); or set your own as 'setup_code' under 'app' in config.php. It's deleted once the administrator exists. After 10 wrong codes an address is paused for 15 minutes, and after 40 wrong codes from all addresses together everyone is (it just keeps being told the code isn't right; the error log says so). If you're stuck, clear it with DELETE FROM login_attempts WHERE username = 'setup';. Behind a reverse proxy or load balancer, set 'trust_proxy' => true so each visitor's own address is used. Everyone's first sign-in then goes through a short setup (about you, what to use, reminders), and administrators get a Site settings step too: site name and address, default time zone, email, scheduled tasks, demo mode. Those are saved in (git-ignored), which overrides , so config.php itself, with its comments and database details, is never rewritten; they can be changed later on the Admin page. If the folder isn't writable, Pillbox shows what to paste into config.php instead.

Where the web root should point

• Best: point the virtual host's DocumentRoot at the public/ folder:

  <VirtualHost *:443>
      ServerName pillbox.example.com
      DocumentRoot /var/www/pillbox/public
      <Directory /var/www/pillbox/public>
          AllowOverride All
          Require all granted
      </Directory>
      # ... SSL settings ...
  </VirtualHost>
  

• Shared hosting / can't change it: upload the whole folder into the web root (or a sub-folder). The top-level .htaccess sends requests into public/ and blocks src/, config/, database/ and storage/. Each of those folders also has its own deny-all .htaccess as a fallback. This needs AllowOverride All (or at least FileInfo and AuthConfig).

  Check it: browsing to https://your-site/config/config.php should return 403 Forbidden.

Installing as an app on iPhone and Android

Pillbox is a Progressive Web App (PWA). Once it's on your HTTPS site, people can add it to their home screen. It then opens full screen with its own icon, like a normal app; no App Store or Google Play listing is needed. Account → Install Pillbox on your phone explains how:

• iPhone / iPad: open the site in Safari → Share → Add to Home Screen.
• Android: open the site in Chrome → ⋮ menu → Install app (or tap Install the app on the Account page).

Notes:

• HTTPS is required; browsers won't install the app over plain HTTP.
• The app needs a connection. Health data is never stored on the phone, only on your server; if the phone is offline it shows a "You're offline" page.
• Sign-ins last for session_idle_minutes (8 hours by default) since last use, even if the app is closed. Raise it in config/config.php if people find they're signed out too often, e.g. 10080 for a week.
• Sessions are stored in storage/sessions, so storage/ must be writable.

Microsoft Entra ID single sign-on

1. In the Entra admin centre go to App registrations → New registration.
   • Supported account types: This organisational directory only (single tenant) is usual.
   • Redirect URI: platform Web, https://your-site/auth_callback.php (or .../pillbox/auth_callback.php).
2. Under Certificates & secrets, create a client secret and copy its value.
3. Under Token configuration, optionally add the email claim.
4. (Optional, for admins) Under App roles, create a role with value Pillbox.Admin. Then in Enterprise applications → Pillbox → Users and groups, assign it to people who should manage users. Admin rights are then synced from Entra at each sign-in. Set 'admin_role' => '' to manage admins only inside Pillbox.
5. (Optional) To limit who can sign in, set Assignment required = Yes on the enterprise application and assign users or groups.
6. In config/config.php, set the entra section:

   'entra' => [
       'enabled'       => true,
       'tenant_id'     => '<Directory (tenant) ID>',
       'client_id'     => '<Application (client) ID>',
       'client_secret' => '<secret value>',
       'redirect_uri'  => 'https://your-site/auth_callback.php',
   ],
   

How accounts are created:

• With auto_provision on (the default), anyone from your tenant gets a Pillbox account on first sign-in.
• With it off, an admin adds them first under Admin → Add a user → Microsoft, using their sign-in email.
• Accounts are matched by Entra object ID and tenant ID, so a name or email change won't create a second account.
• On a new install, the administrator can be a Microsoft account: open the site, enter the setup code, then sign in with Microsoft.

Multi-tenant: set tenant_id to organizations and list the permitted tenant GUIDs in allowed_tenants. Only list tenants you control or trust. Pre-registered accounts are only linked by email for people from your tenant_id or a tenant listed by GUID; never through '*' (any tenant), since another tenant could claim someone else's email address. Sign-ins from any other tenant are rejected.

You can run local and Microsoft accounts side by side. To allow Microsoft accounts only, set 'allow_local_login' => false.

Other single sign-on providers (OpenID Connect)

Besides Microsoft, Pillbox can sign people in with any OpenID Connect provider, such as Google, Okta, Auth0, Keycloak, Authentik, Authelia or Zitadel. Add as many as you like under 'oidc' => ['providers' => [...]] in config/config.php; each gets its own button on the login page. The template has a Google example plus commented examples for Okta, Keycloak and Authentik.

For each provider:

1. Create an OAuth/OIDC web application client in the provider's admin console.
2. Set its redirect (callback) URI to https://your-site/oidc_callback.php (the same URL for every provider).
3. Copy the client ID and secret into config/config.php, set issuer to the provider's issuer URL and 'enabled' => true.

Provider	issuer
Google	https://accounts.google.com
Okta	https://YOUR-ORG.okta.com (or https://YOUR-ORG.okta.com/oauth2/default)
Auth0	https://YOUR-TENANT.auth0.com/
Keycloak	https://HOST/realms/REALM
Authentik	https://HOST/application/o/SLUG/

Options per provider:

• auto_provision: create an account on first sign-in. With Google, always combine this with allowed_email_domains, or anyone with a Google account can sign up.
• allowed_email_domains: only accept verified email addresses at these domains, e.g. ['example.com'].
• admin_claim / admin_values: make people admins from a claim in the ID token, e.g. 'groups' / ['pillbox-admins']. This only applies to accounts that sign in only with that provider.
• single_logout: also sign out of the provider when signing out of Pillbox.

How accounts work:

• Pre-registering people: with auto_provision off, an admin adds them under Admin → Add a user and picks the provider. They're matched by their verified email the first time they sign in.
• Linking: anyone signed in can link a provider account under Account → Sign-in options, and then sign in either way. Pillbox never lets you unlink your last way of signing in.

Pillbox uses the authorisation-code flow with PKCE. It checks every ID token's RS256/384/512 signature against the provider's published keys, plus the issuer, audience, expiry and nonce.

'disable_local_login_when_sso' => true (in the app section) turns off password sign-in whenever Microsoft or any OIDC provider is enabled.

Signing in safely

• Two-factor sign-in (Account → Password & security): authenticator apps (TOTP, with a QR code and backup codes) and security keys (WebAuthn, e.g. a YubiKey), as many of each as people like. It's asked for after every kind of sign-in, single sign-on included. Adding one needs the password again, or a fresh Microsoft or other single sign-on. Authenticator secrets are stored encrypted (storage/app.key).
• Remember this device keeps a device signed in for remember_days (90 by default; 0 turns it off) after it was last used. Only a hash of its token is stored. Signing out, changing the password and Sign out everywhere else forget remembered devices.
• Forgotten your password? emails a single-use link that works for an hour, without saying whether an account exists, at most 3 an hour. It needs email and a known site address (see Site settings); otherwise people are told to ask an admin, who can reset it from Admin → Manage.
• Active sessions lists every device signed in now, with its IP address, and signs out any of them at once. With 'geoip_lookup' => true (in the app section; off by default) it also shows an approximate city and country, by sending the IP address to ipapi.co at sign-in. The privacy policy then says so.
• Wrong passwords are limited to 8 per username and 24 per address in 15 minutes; two-factor codes, PINs and setup codes have their own limits.

Inclusive care and privacy

Everything clinical follows a person's body and medicines, never a gender field:

• Profile: pronouns (shown on reports) and an optional gender identity in your own words.
• Body inventory (Account → Health profile, optional): cervix, uterus, ovaries, breasts or chest tissue, prostate and testes, each "have", "removed (surgery)" with a date, or "don't have". When it's filled in, screening follows it (cervical: a cervix; breast: breast or chest tissue; AAA: a prostate or testes, now or before surgery; bowel: everyone), and Pregnancy and Pregnancy options only appear with a uterus. NHS invitations follow the sex on the GP record, so the Screening page points out any that may not arrive automatically, and suggests asking the GP practice. "Women's health" is now Periods and contraception, and can be switched off.
• Hormones are ordinary medicines with one-tap set-ups (Menopause and Gender-affirming care): testosterone gel, short- and long-acting injections, oestradiol patches, gel, spray, tablets and injections, progesterone, blockers and anti-androgens, with any dose (including micro-dosing). Doses can repeat every N days or weeks (e.g. every 3 or 12 weeks), and injections get a site rotation: Take suggests the next site, and the medicine shows when each was last used.
• Blood tests → Results and trends: results in UK units with trend charts, the lab's range from the report, and a target range set by you or your clinic (lab ranges follow the sex on your record, which often doesn't fit on hormones). Each result can note its timing (e.g. trough, just before an injection) and works out the time since your last dose.
• Gender-affirming care (a private page, like Pregnancy options): GIC waiting-list tracker, prescriber, shared care agreement with a renewal reminder, fertility preservation, a changes journal with your own fields, and progress photos, all encrypted (photos as encrypted files in storage/private/), with its own PIN, never shared, and deleted in one go.
• Privacy: tick Private on a medicine so reminders and emails just say "Reminder" and it's hidden from anyone you share Pillbox with; hide the screen when switching apps; and a disguised name and icon ("Planner" or "Notes") for the home screen and browser tab.

ADHD, autism and accessibility

• ADHD and autism (Care, no diagnosis needed): self-identified, waiting or diagnosed per condition; waiting lists for assessments (NHS, Right to Choose, private) with time waited; assessment prep notes by topic (printable); a communication passport shown full screen or printed, added to appointment sheets, and as text to copy into an ICE / medical ID; a Reasonable Adjustment Flag reminder; optional energy (spoons), sensory load, meltdowns or shutdowns, sleep and burnout signs, with a gentle note when a week looks hard and a cycle link; and checks for blood pressure and pulse, weight, the yearly medication review and shared care.
• Controlled drugs (any medicine): prescriptions are often 30 days and expire 28 days after writing, so Meds shows when to ask for the next one and a "collect by" date, with notifications, and a pharmacy and shortage log.
• How it's working (any medicine): when each dose was taken, kicked in and wore off (and any crash), a rating and side effects; a timeline, each dose compared (titration), and, with cycle tracking, how it works before a period.
• For everyone (Account → Display and reminders): larger text, more spacing, an easy-read font, no animations, hidden streaks, and an optional "did you take it?" follow-up notification. Doses can be logged with the time they were taken ("At…"), Today has a Now / Next view with a timeline of the day, there's a visual timer, running-low notices show the steps (order, collect, log stock), and unlogged doses say "Not logged" rather than "Missed".

Terms and privacy

Terms and Privacy pages are linked in every page's footer, and people agree to them when they sign up (the date is saved with the account). The text is generated from what Pillbox actually does: what it stores, encryption, sharing, the optional services you've switched on (email, push, connected apps, dm+d, single sign-on, weather, IP location), its cookies, and people's rights under UK GDPR. Fill in who runs it, a contact and the governing law under Admin → Site settings → Terms and privacy (or 'legal' in config/config.php), or replace either text with your own. It's a starting point, not legal advice.

Letting people sign up

By default only admins add people. To let people create their own accounts, turn on Admin → Site settings → Sign-ups (or set it in config/config.php):

'signup' => [
    'enabled'          => true,   // "Create an account" on the sign-in page
    'require_approval' => true,   // new accounts wait for an admin to approve them
    'notify_admins'    => true,   // email admins about each new sign-up
],

• How people sign up: the sign-in page gets a Create an account link. The sign-up page has a button for Microsoft and each OpenID Connect provider that's switched on ("Sign up with Google", ...), plus a username and password form if password sign-in is allowed. Signing in with a provider for the first time while sign-ups are open also creates an account.
• Approval: with require_approval, a new account can't be used until an admin presses Approve under Waiting for approval on the Admin page (admins also see a notice on Today). Decline removes the account. People who gave an email address are emailed when they're approved.
• Admin emails: with notify_admins and the mail settings filled in, every active admin with an email address is told about each sign-up, with a link to the Admin page.
• New accounts go through the first-login setup. Sign-ups from one address are limited to 5 an hour.
• Providers with 'auto_provision' => true (a trusted Microsoft tenant or company directory) still create accounts on first sign-in whatever these settings say, without approval. With open sign-ups and a public provider such as Google, anyone with an account there can sign up, so keep require_approval on or set allowed_email_domains.

NHS medicines dictionary (dm+d) lookup

When adding a medication, you can search the NHS Dictionary of Medicines and Devices (dm+d) and pick the exact product, e.g. "Metformin 500mg modified-release tablets". Pillbox fills in the name, strength, form and dose unit, and stores the product's dm+d code, which is shown on the doctor's report. Typing details in by hand still works.

The search uses the NHS England Terminology Server. dm+d is licensed content, so you need a free system-to-system account:

1. Go to NHS England Terminology Server: how to access and request a system-to-system account. You'll be given a client ID and client secret.
2. Add them to config/config.php:

   'nhs_terminology' => [
       'enabled'       => true,
       'client_id'     => '<client id>',
       'client_secret' => '<client secret>',
   ],
   

Only the search words are sent to the NHS server, never anything about the patient.

Why there's no "import my medications from the NHS"

As of October 2026, NHS England doesn't let new apps read a patient's medication record:

• GP Connect (Patient Facing) Prescriptions, the API behind the NHS App's medicines list, states that NHS England is "not onboarding any additional consumer suppliers".
• IM1 pairing with GP clinical systems (EMIS, TPP) is open only to suppliers, after an application and clinical-safety and information-governance assurance.

If that changes, the stored dm+d codes are the same codes GP records use, so imported medicines could be matched to ones already in Pillbox.

Version and updates

The installed version is in the VERSION file and is shown in the footer, with a link to the GitHub repository (github_repo in config/config.php; set it to '' to hide both). For admins, Pillbox compares its VERSION with the newest published release on GitHub, at most twice a day, and shows Update available in the footer when that release is newer (or Development version when this copy is ahead of it). Drafts and pre-releases are ignored. The Admin page's Version section has Check now, the Changelog (every release's notes) and the Licenses of Pillbox and the code it includes.

• To release a new version: raise the number in VERSION (e.g. 1.0.0 → 1.1.0), merge it into main, then publish a GitHub release tagged with the same number (v1.1.0 or 1.1.0).
• Private repository: create a fine-grained GitHub token with read-only Contents access to the repository and put it in github_token. Without it, GitHub hides the repository and the check reports that it couldn't look.

Email and scheduled tasks

Fill in the 'mail' settings in config/config.php: 'transport' => 'mail' uses PHP's mail() (most shared hosting), or 'smtp' with a host, port, 'secure' => 'tls' (587) or 'ssl' (465), username and password. Each person chooses under Account → Email:

• Daily summary at a chosen hour: today's doses, anything not logged yesterday, medicines running low or expiring, Care items coming up, and appointments today and tomorrow. Nothing from Mind is ever included.
• Appointment reminders, at each appointment's reminder time (or the day before), with the questions you want to ask.

Admins are emailed once when a new version is released. The scheduled tasks also refresh the update check and tidy up (old sign-in attempts, leftover upload files, stale sessions, finished demo accounts). They check for updates but never install them. Send me a test email on the Account page checks the settings.

Sharing with a carer or partner

Under Sharing (the people icon), you can give someone with an account on the same Pillbox access to parts of yours. For each part (medicines and doses, readings, appointments, Care, Mind, reports) you choose no access, see, or a level of change: for medicines, log doses (take, skip, collected prescriptions) or change medicines. You can keep chosen Care categories private (e.g. Periods and contraception), include or leave out the Mind journal, and set an end date. Quick choices: "See everything except Mind", "Help with medicines", "Full help (not Mind)".

Each part's permission applies wherever its information appears, not just on its own page: someone without Readings doesn't see readings in Care, on Today or in the report, and someone without Medicines doesn't see medicines anywhere (including the headache diary). Private medicines and the private pages are never shared.

They open it from their own Sharing page, with a banner showing whose Pillbox it is and Back to mine; only the tabs and parts they've been given appear. Pages are checked centrally, and anything not shared is refused. They can never see or change your account settings, sign-in details, sync and calendar links, data export or Mind PIN, can't permanently delete medicines, and can't share your Pillbox further. Every change they make is listed under their name (Recent activity), and you can stop sharing at any time.

Tests

Sharing permissions have a regression test. Run it against a test database (it works inside a transaction that is rolled back, but don't point it at live data):

php tests/sharing_medicines_test.php

It checks the Migraine page for three viewers: the owner, someone with Medicines shared, and someone without. Only the first two see medicine names, and private medicines are never shown to anyone but the owner.

Demo mode

Set 'demo' => ['enabled' => true] in config/config.php to add Try the demo to the sign-in page. Each visitor gets their own copy of a sample account for Nell Whitcombe, a made-up person (the same one as the ICE demo), with a few weeks of doses, readings, appointments, Care and Mind data. Everything they change is deleted when they end the demo or sign out, or after 'hours' if they just leave. Sign-in details, email, sharing, Apple Health sync, calendar links and passkeys are switched off in the demo, and demo accounts don't appear in the admin's user list.

Connecting apps and devices

Readings → Connect apps and devices brings readings in from other places, labelled with where they came from and never duplicated:

• Apple Health (export file, or automatic sync from an iPhone app), see above.
• Android Health Connect (Samsung Health, Google Fit, Fitbit and most Android apps): Health Connect only works on the phone, so an Android app that can send its data to a web address posts it to your private sync link, in the same format as the iPhone sync.
• WHOOP, Fitbit, Withings and Oura: direct connections. An admin registers a free app with each service (WHOOP: developer.whoop.com, Fitbit: dev.fitbit.com, Withings: developer.withings.com, Oura: cloud.ouraring.com), using the return address shown on the Admin page (.../connect.php), and enters its client ID and secret under Admin → Site settings → Connected services. Each person then presses Connect. Readings sync about once an hour via the scheduled tasks; sign-in tokens are stored encrypted (key in storage/app.key). They bring in resting heart rate, heart rate variability, oxygen level, sleep, breathing rate, steps, weight, and (Withings) blood pressure and temperature, depending on the service.
• MyFitnessPal has no public API: import its Export data file (weight, and calories eaten per day), or let it write to Apple Health or Health Connect.
• Google Fit is being retired: import Daily activity metrics.csv (or the whole zip) from Google Takeout.
• Garmin only shares data with approved businesses, so connect it through Apple Health or Health Connect.

Push notifications

Each person can turn on notifications in each browser or device they use (Account → Notifications): dose reminders at dose time (if not logged), Care reminders and a daily "coming up", appointment reminders, and the Mind check-in. Hide details on the lock screen shows just "Pillbox: you have a reminder". They use the standard Web Push protocol (VAPID keys are created automatically in storage/; messages are encrypted for the device), so no third-party service or account is needed. They're sent by the scheduled tasks, so run those every 5 minutes. On iPhone and iPad, notifications work once Pillbox has been added to the Home Screen (iOS 16.4 or later). Notifications are only sent to the browsers' own push services (Google, Mozilla, Apple, Microsoft); to allow another, such as a self-hosted UnifiedPush server, list its host in 'push' => ['allowed_hosts' => ['push.example.com']] (a leading dot allows its subdomains too).

Updating

Admins can update from the Admin page: Install version X now downloads the release from GitHub, checks it, saves a backup of the current files in storage/backups/, then replaces them. config/config.php and storage/ are never touched, and the database updates itself on the next page load. Any backup can be put back with Restore. It needs PHP's zip and curl extensions and write access to the Pillbox folder; copies that are git checkouts should use git pull. Uploading the files by hand works too.

Tidy addresses

With Apache's mod_rewrite, pages have addresses without ".php" (e.g. /medications); public/.htaccess turns this on and tells Pillbox, which then makes its links that way and redirects old ".php" addresses. Calendar feed and Apple Health sync addresses keep working as they are. Without mod_rewrite (or with 'pretty_urls' => false), everything uses ".php" as before.

Moving your data

Account → Your data → Download all my data gives one file with everything (readable sections, plus a complete backup). Import data restores that backup into an account, replacing what's there: useful for moving to another Pillbox. Sign-in details, sharing, passkeys and sync links aren't included.

Security notes

• Passwords are hashed with PHP's password_hash. Local logins are rate-limited per username and per IP, and optional two-factor sign-in covers every way of signing in (see Signing in safely).
• All forms have CSRF protection. Sessions use HttpOnly and SameSite cookies, which are Secure over HTTPS.
• Every page sends a strict Content-Security-Policy (no inline scripts or styles, and no third-party assets), plus Strict-Transport-Security (over HTTPS), X-Frame-Options, X-Content-Type-Options, Referrer-Policy, Permissions-Policy, Cross-Origin-Embedder-Policy, Cross-Origin-Opener-Policy and Cross-Origin-Resource-Policy. Files Apache serves directly (CSS, JavaScript, icons) don't get them unless you add them in the server config.
• Entra ID tokens are obtained with the authorisation-code flow plus PKCE. The ID token's signature, audience, issuer, expiry, nonce and tenant are all checked.
• Every query is scoped to the signed-in user, so people can only see their own data, or data that has been shared with them (see Sharing above).
• Mind can have its own PIN, plus a passkey (WebAuthn, platform authenticators only: the device asks for a fingerprint, face or its own PIN; needs HTTPS). The device signs a one-time challenge; the origin, site, user verification and signature are all checked, and the PIN still works. Crisis contacts are never locked.
• Health data is sensitive. Use HTTPS, keep the server patched, back up the database, and check what your local data-protection rules require.

Project layout

public/      web root: pages, assets (CSS, JS, logo, icons), service worker
src/         application code (auth, single sign-on, two-factor, scheduling, metrics, charts, layout, Care
             categories, Mind, sharing, mail, push, tasks, updater, demo)
bin/         cron.php: the scheduled tasks, for the command line
config/      config.example.php (template) -> copy to config.php (your settings); settings.php (Site settings)
database/    schema.sql
docs/        the user documentation, also shown in the app (Docs in the footer)
tests/       regression tests (run against a test database)
vendor/      bundled third-party code (qrcode-generator, MIT)
storage/     keys, sessions, backups, encrypted photos and caches (must be writable; back it up)

License

Pillbox is free software, released under the GNU General Public License v3.0. You can use, study, change and share it. If you share it (changed or not), you must share the source code under the same licence.

Copyright (C) 2026 Michelle Findlay

Pillbox is a record-keeping aid. It is not medical advice; always follow your prescriber's instructions.