Reclaim · Lost & Found Management System

Reclaim is a self-hosted PHP and MySQL app for the lost property desk. Staff log found items with a photo and a QR label, Reclaim matches them with lost reports, tells the owner by email, WhatsApp or letter, and records a safe handover with an ID check, a signature and a PDF receipt. Items that nobody claims are disposed of with a certificate, and every step is in the audit log.

It is built for hotels, resorts, airports, shopping malls, universities, hospitals, stadiums, gyms and offices. It is plain PHP 8 with no framework, no Composer and no build step, so it runs on ordinary shared hosting.

What's new in 2.0

• Matching: a match inbox with scores and the reasons for each match. Optional AI check and AI photo description.
• Owner contact: branded emails with the item photo, WhatsApp Business messages, printed letters with a QR code, collection reminders and "still looking?" follow-ups.
• Returns by post: owners request delivery and pay; you print a packing slip and add tracking.
• Chain of custody: every move is logged; police and legal hold blocks handover and disposal.
• Intake and storage: QR labels, a scanner, a storage map, CSV import and several sites.
• Public pages: a front page, search of found items, "Found something?" reports and report tracking.
• Handover: pickup codes, ownership question, second approval for valuable items, receipts by email.
• Reports: an insights dashboard and branded PDF export of five registers.
• Administration: manager and read-only auditor roles, two-factor sign-in, scheduled tasks, backups, a health check, dark mode, an installable app and a Spanish translation.
• Data: finder and claimant contacts are now separate email and phone fields (split automatically on upgrade).

Server requirements

Installation (web installer)

1. Upload the contents of the package to your web root or a subfolder.
2. Make these folders writable by the web server: config, uploads, storage.

   chmod -R 775 config uploads storage

3. Open https://your-domain/install/ in a browser.
4. Requirements: the installer checks PHP, extensions and folder permissions.
5. Database: enter the host, database name, user and password. The database is created if it does not exist.
6. Account: enter your organization name, admin email, password and timezone. Tick Install demo data to try Reclaim with sample items and photos.
7. Done: delete the install folder and sign in.

Running it on your own computer

Reclaim also runs locally, for trying it out, training staff or a single front-desk PC. With XAMPP (Windows, macOS, Linux), MAMP, Laragon or WampServer:

1. Start Apache and MySQL in the control panel.
2. Copy the Reclaim folder into the web root (htdocs for XAMPP and MAMP, www for Laragon and WampServer), for example htdocs/reclaim.
3. Open http://localhost/reclaim/install/ and follow the installer. The default local database user is usually root with an empty password (MAMP: root / root).

Manual installation

1. Create a utf8mb4 database and import install/sql/schema.sql.
2. Optionally import install/sql/demo_data.sql and copy the photos in install/seed/items/ into both uploads/items/ and uploads/thumbs/.
3. Copy config/config.sample.php to config/config.php and fill in the database details and APP_URL.
4. Make uploads and storage writable.

Upgrading from 1.0

1. Back up your files and database (your host's backup tool or phpMyAdmin export).
2. Upload the new files over the old ones. Keep your config/config.php, uploads and storage folders. Do not upload the install folder.
3. Open Reclaim in the browser. It shows the Upgrade screen because the database is older than the files.
4. Sign in with an administrator email and password and click Upgrade. A safety backup of the database is made in storage/backups, then the upgrade runs.
5. You are sent to the dashboard. All items, reports, handovers, users and settings are kept.

What changes in your data: finder and claimant contacts are split into separate email and phone fields (anything that looks like an email goes to email, the rest to phone), and the new tables and settings are added with safe defaults. New features such as WhatsApp, AI and returns by post stay off until you turn them on.

After upgrading, set up the cron job, review Settings (new tabs: Matching & AI, Returns by post, Email & WhatsApp) and give the new manager or auditor role to anyone who needs it.

Scheduled tasks (cron)

Reclaim has background tasks: expiring stale lost reports, owner reminders and follow-ups, retrying failed emails, retention clean-up and backups. They run while people use the app (at most every 5 minutes), but for reliable timing add one of these to your server's cron every 5 minutes. System → Scheduled tasks shows both lines with your path and key filled in, with copy buttons.

*/5 * * * * php /path/to/reclaim/cron.php >/dev/null 2>&1
*/5 * * * * wget -q -O /dev/null "https://your-domain/cron.php?key=YOUR_KEY"

On cPanel use Cron Jobs and paste the line. Over the web the key is required; from the command line it is not. You can create a new key on the System page at any time. The page also shows when each task last ran and lets you run them now.

First-run setup

1. Settings → General: organization name, timezone, date format, currency, language.
2. Settings → Design: logo, brand colour and app icon.
3. Sites and Storage locations: your premises and the shelves or cabinets in each.
4. Categories: electronics, wallets, keys and so on, each with its own retention period.
5. Users: add your team with the right role.
6. Settings → Email & WhatsApp: connect SMTP so owners are told automatically.
7. System: set up the cron job.

Interface basics

• Dashboard: what needs attention today, recent items and the return rate for the last 90 days.
• Lists: stat cards, a filter bar, sortable columns, searchable dropdowns and pagination. Filters carry into exports.
• Detail pages: a photo, a status timeline, the facts that matter and an Actions panel. On phones the actions sit in a bar at the bottom.
• Confirmation: every action that changes or removes something asks first.
• Notification bell: new public reports, possible matches and shipments waiting.
• Dark mode follows your device or the switch in the top bar. Reclaim can be installed as an app from the browser menu on phones and desktops.

Found items

Found items → Log found item. Add a title, category, site and storage location, a photo (the phone camera opens on mobile), the finder's name, email and phone, and an estimated value. A reference such as F-2026-000123 is given automatically (sequential or random, see Settings → Items). An optional ownership question ("What is the lock screen picture?") helps you check the owner later.

Item statuses: in storage → matched → returned (to the owner), or returned to finder, or disposed. Matching, handovers and disposals can be undone if they were recorded by mistake.

Import

Found items → Import reads a CSV file from your old register. Download the template on that page, fill it in and upload it. Rows with errors are listed and skipped.

Return to finder

When nobody claims an item and the finder wants it, open the item and use Return to finder.

Trash

Deleted items go to the Trash and can be restored from the Found items list.

QR labels, scanner & storage map NEW

• Label: on an item, click Label to print a label with a QR code, the reference and the shelf: one 62 × 29 mm label per page for Brother or Dymo label printers, or an A4 sheet of 3 × 8 labels (Avery L7160). Select several items on the list to print their labels together.
• Scan: Found items → Scan opens the camera. Scan a label to jump to the item, or type a reference.
• Storage map: shows every shelf with how many items it holds and how many are due for disposal.
• Move to another shelf: from the item's Actions; the move is recorded in the custody trail.

Chain of custody & holds NEW

Every item has a custody trail: logged, moved between shelves or sites, handed to a colleague, returned, posted or disposed, with the person and time for each step.

Place on hold (manager or admin) when the police, a court or an insurer asks you to keep an item. Enter the reason, a reference and an optional end date. While on hold, the item cannot be handed over, posted, returned to the finder or disposed of, and it is left out of disposal lists. Release the hold from the same page.

Lost reports

Staff log reports with Lost reports → Log lost report; owners can use the public form. Reports get a reference such as L-2026-000045.

Each report has a letter you can print and post to owners without email.

Matching

Reclaim compares every open lost report with every item in storage: category, colour, brand, words, place and date. Each pair gets a score from 0 to 100 with the reasons shown. Pairs above the minimum score appear in the Matches inbox; you confirm or dismiss them. Confirming links the two records and can email the owner. Matches are never confirmed automatically.

Settings → Matching & AI: minimum score and the date window. See AI features for the optional AI check.

Contacting owners NEW

Owners are told automatically at each step, by email and optionally WhatsApp:

Each message can be turned on or off in Settings → Email & WhatsApp. For owners without email, print the letter from the item or report; it has a QR code that opens the owner's private page.

Handover

From a found item, click Hand over to owner:

1. Owner: name, email and phone (filled in from the lost report when matched).
2. Identity: ID type and reference, an optional photo of the ID, the ownership answer and the pickup code.
3. Second approval: items worth more than the high-value amount need a manager or admin to approve.
4. Signature on screen (mouse, finger or stylus).

Confirming sets the item to returned, closes the report and creates a PDF receipt that can be emailed. What is required (ID, signature, pickup code) is set in Settings → Items & public pages. The Handovers register lists every return; a handover recorded by mistake can be voided.

Returns by post NEW

1. Turn on Settings → Returns by post and set the default fee and payment instructions.
2. The owner asks for delivery on their private page and enters the address, or staff use Send by post on the item.
3. The shipment waits for payment. Record the payment (amount, method, reference, optional proof).
4. Print the packing slip, send the parcel and enter the courier and tracking number.
5. The owner is told by email and WhatsApp. Shipments lists everything waiting or in transit.

Retention & disposal

Each category can have its own retention period (or the default in Settings). Items past it appear on the Disposals page. Dispose of one item or select several for a batch, choose the method (donated, discarded, returned to finder, handed to the authorities) and print a certificate of disposal. Items on hold are never listed. Disposals can be edited or deleted, which returns the item to storage.

Reports & insights

• Insights: items logged and returned, return rate, average time to return, value returned, categories and team activity over any period.
• Reports: five registers (found items, lost reports, claims & handovers, disposals, shipments) with filters. Export to CSV for Excel or a branded PDF.

Public pages

Each public page can be turned on or off in Settings → Items & public pages:

Forms are protected by a hidden honeypot field and a math question, and tracking lookups are rate-limited. Print a QR poster for each desk from Sites → Poster.

Email (SMTP)

Settings → Email & WhatsApp. Turn on email and enter your SMTP host, port, username, password and from-address, then use Send test. Common settings: port 465 (SSL) or 587 (STARTTLS). Emails use your logo and brand colour. Failed sends are retried by the scheduled tasks.

WhatsApp NEW

Reclaim sends WhatsApp messages through the official WhatsApp Business Cloud API from Meta, using your own business number. It is optional; email keeps working without it.

1. In Meta's WhatsApp Manager, add a phone number and create a permanent access token.
2. Create and get approval for the message templates you want to use. Each template takes three variables:

   Message	{{1}}	{{2}}	{{3}}
   Report received	name	reference	private link
   Possible match	name	item	private link
   Ready for pickup	name	pickup code	private link
   Shipped	name	courier and tracking number	private link

3. In Reclaim, turn on Also message owners on WhatsApp, enter the phone number ID, the token, the template language, your country code (for local numbers) and the template names.
4. Use the test form to send a template to your own phone.

AI features NEW

AI is optional and off by default. Reclaim works fully without it. It uses your own API key; nothing is sent until you turn it on.

• Describe from photo: on the log-item form, AI suggests a title, category, colour, brand and description from the photo. Staff review it before saving.
• Smart match check: AI gives a second opinion on likely matches, which can lift or lower the score.

Settings → Matching & AI: choose the provider (OpenAI, Google Gemini or any OpenAI-compatible API such as a local or third-party server), paste the API key and, if you like, the model. For compatible APIs also enter the base URL. Item photos and texts are sent to the provider you choose, so mention this in your privacy notice.

Payments

Reclaim does not process cards itself. For returns by post you choose how owners pay, in Settings → Returns by post:

• Payment instructions (bank transfer details, pay at the desk, and so on),
• a payment link from your provider (Stripe Payment Link, PayPal.me, etc.),
• and/or a payment QR code image.

Staff record the payment on the shipment when it arrives.

Settings

Roles & permissions

The last active administrator cannot be removed or demoted.

Security & privacy

• Two-factor sign-in: each user can turn it on under My account with an authenticator app.
• Sign-in protection: accounts lock for a few minutes after repeated wrong passwords; public lookups are rate-limited.
• CSRF protection on every form, prepared SQL statements, escaped output and security headers.
• Uploads: only images (JPG, PNG, WebP) up to 5 MB, stored with random names and never executed.
• Audit log of every change, sign-in and export, with the user, time and IP.
• GDPR: export or erase one person's data from Settings → Privacy, and anonymize personal data on old records automatically.

System, backups & health

System (admin only) has a health check (PHP, extensions, folders, email, cron), the scheduled tasks, database backups (make, download, restore; one is made automatically before each upgrade), the PHP error log and maintenance mode, which shows a notice to everyone except admins.

Customization & languages

• Branding: logo, app icon and colour in Settings → Design. They are used in the app, emails, letters and PDFs.
• Languages: English and Spanish are included. To add one, copy core/lang/es.php to e.g. core/lang/fr.php, change '_name' at the top and translate the right-hand side of each line (keep {placeholders} as they are). Missing lines fall back to English. It then appears in Settings → General.
• Styling: the design tokens are at the top of assets/css/theme.css (prefixed --lf-).
• Routing: all requests go through index.php, which maps clean URLs such as /found-items/view to views/found-items/view.php. On Nginx use try_files $uri $uri/ /index.php?$query_string;.

Demo mode

Setting define('DEMO_MODE', true); in config/config.php shows a demo banner and the demo logins, and locks secret settings (email, WhatsApp and AI keys). Leave it false for a real installation.

FAQ & troubleshooting

Blank page or error 500

Check the database details in config/config.php and look at System → Error log or your host's PHP error log.

Pages other than the home page show "Not found"

Apache's mod_rewrite is off or .htaccess was not uploaded (it is a hidden file). On Nginx add the try_files rule above.

Photos will not save

Make uploads and storage writable (chmod -R 775) and check the photo is JPG, PNG or WebP under 5 MB.

Email is not sending

Use Send test in Settings → Email & WhatsApp; the error from your mail server is shown. Try port 465 with SSL or 587 with STARTTLS, and use the full mailbox address as the username.

WhatsApp test fails

Check the token has not expired (use a permanent system-user token), the template name and language match exactly what Meta approved, and the number includes the country code.

Reminders and follow-ups are not sent

Set up the cron job. System → Scheduled tasks shows when each task last ran.

The camera does not open for scanning

Browsers only allow the camera on HTTPS. Install an SSL certificate (free with Let's Encrypt on most hosts).

The site shows the Upgrade screen

The files are newer than the database. Sign in on that screen as an administrator and click Upgrade.

"Already installed" on the installer

Reclaim is installed. Delete the install folder. To start over, delete config/config.php first.

Changelog

2.0.0

• New: match inbox with scores and reasons, AI match check and AI photo description
• New: WhatsApp Business notifications, branded emails with the item photo, collection reminders and follow-ups
• New: returns by post with payment, packing slip and tracking
• New: chain of custody, police and legal hold
• New: QR labels, scanner, storage map, CSV import
• New: public front page, search, "Found something?" reports, report tracking, desk QR posters
• New: owner letters, pickup codes, second approval for valuable items, receipts by email
• New: batch disposal, certificates of disposal, retention per category
• New: insights dashboard, branded PDF export, shipments register
• New: manager and auditor roles, two-factor sign-in, public lookup throttling
• New: scheduled tasks, backups, health check, maintenance mode, web upgrade
• New: dark mode, installable app, brand colour and app icon, Spanish translation
• Improved: separate email and phone for finders and claimants
• Improved: redesigned dashboard, detail pages, public pages and print layouts
• Improved: confirmation before every action

1.0.0

• Initial release

Credits

Bundled open-source components (Bootstrap, Bootstrap Icons, jQuery, Chart.js, Dompdf, PHPMailer, jsQR, qrcode-generator, Signature Pad, Inter font) and their licenses are listed in licenses/index.html. The demo photos are public domain (CC0) and listed in install/seed/items/CREDITS.txt.

Support

Use the support tab on the item's CodeCanyon page. Please include your PHP and MySQL versions, the Reclaim version (shown on the System page) and any error message.