The shop uses your Bluehost MySQL database for shared records and protected server storage for attachments. It does not use browser storage for shop records.
Admin and volunteer guide · Release notes
# Den Shop — Bluehost installation Status: installable PHP/MySQL test build. Do not use real transactions until the Bluehost acceptance checks below pass. No connection to azsuq.com or Bluehost has been made from this workspace. ## Package contents - public/: prebuilt shop UI, login/registration, installer, API, mail worker and admin mail/export screen. - app/: PHP business rules, SQL schema, catalogue, private configuration example and supporting code. - source-ui/: editable React source. Node is only needed to rebuild the UI, not to run it on Bluehost. - tests/: PHP business-rule tests. - tools/: CLI environment checker. ## 1. Create the subdomain In Bluehost/cPanel, create denshop.azsuq.com. Use a separate document root for this application. Do not overwrite azsuq.com's existing site. Recommended layout: /home/CPANEL_USER/den-shop/app/ /home/CPANEL_USER/den-shop/public/ <- subdomain document root /home/CPANEL_USER/den-shop/tests/ /home/CPANEL_USER/den-shop/tools/ Upload/extract the package into /home/CPANEL_USER/den-shop. Set the subdomain document root to its public/ folder. All private code and uploads must be outside the public document root. If Bluehost restricts document root locations, ask support to set this up; do not expose app/ or the entire ZIP as the public website. app/.htaccess is an additional safeguard, not a replacement for correct placement. Enable the free SSL certificate for denshop.azsuq.com and ensure HTTPS works before login/setup. Select PHP 8.3 for this subdomain only; do not change unrelated websites. ## 2. Create the MySQL database In cPanel MySQL Databases / Database Wizard: 1. Create a database, for example CPANEL_USER_denshop. 2. Create a dedicated database user with a strong password. 3. Add that user to this database with the privileges needed to create and operate its tables. 4. Keep the password private. Never send it in chat. The SQL uses InnoDB and utf8mb4 and avoids MySQL 8-only features, targeting MySQL 5.7+. Database creation is not performed by the application. The installer creates only tables prefixed den_ in the selected database. ## 3. Configure the application Copy app/config.example.php to app/config.php and edit it using cPanel File Manager: - base_url: https://denshop.azsuq.com (no trailing path). - db_host: normally localhost; use Bluehost's value if different. - db_name and db_user: use full cPanel-prefixed values. - db_password: the database password created above. - setup_key: your own randomly generated string, at least 32 characters. Do not leave the placeholder. Keep it private. - mail_from: an actual mailbox on your domain, for example denshop@azsuq.com. - storage: leave the default if app/ is outside the public document root. Use permissions 600 for config.php where supported. Create app/storage with permissions 700, writable by the PHP process. Do not use 777. The cron_key field is reserved; the supplied mail worker accepts CLI only and does not expose a public cron URL. ## 4. Create the administrator Visit https://denshop.azsuq.com/setup.php. Enter the private setup key, administrator name, email, password and confirmation. You choose the administrator credentials directly; none are provided in this ZIP. Choose whether to load the reference product catalogue. If selected it contains template variants/prices, zero stock and unknown costs. All prices are provisional until checked; the original MESAC Pants XS price was blank and is provisionally AED 110. If not selected, the admin starts with an empty catalogue. Complete installation. Then DELETE public/setup.php. The database flag also prevents a second installation. Visit the normal site and sign in. In Settings, set the admin report email. The admin can add/edit products and photos, prices/costs, opening stock, POs and users without coding. ## 5. Configure email and the cron worker Create/confirm the sender mailbox in Bluehost. Configure the domain's SPF and DKIM using Bluehost's Email Deliverability tools. This version uses PHP mail() through the hosting mail service; it does not use an external SMTP provider. Add a cPanel cron job every five minutes. Use the PHP CLI executable matching PHP 8.3 (ask Bluehost for its exact path): /PATH/TO/PHP83 /home/CPANEL_USER/den-shop/public/cron.php Do not copy /PATH/TO/PHP83 literally. Run the command once from Terminal, if available, to check for errors. Mail is queued in MySQL; a retry worker attempts failed sends up to five times. Queue acceptance does not prove inbox delivery. An interrupted send can be retried and produce a duplicate email; the queue marks that limitation. In Settings, follow Mail queue, delivery test & data export. Send a test and confirm actual inbox delivery, including spam. Test registration verification, password reset and closing-shift emails before inviting users. If Bluehost blocks PHP mail or messages do not arrive, have the hosting administrator resolve delivery or integrate an SMTP provider before rollout. ## 6. Administrator setup 1. Add or review products, colour/size variants, prices and actual unit costs. 2. Upload genuine item photos. 3. Count stock and enter opening quantities before starting sales/POs. Later changes use stock corrections with reasons. 4. Set the report email and verify test delivery. 5. Invite volunteers to the registration page by sharing the shop URL. They register, verify email and wait for your approval. 6. Approve only verified accounts. Decline/deactivate a volunteer when access must stop; existing sessions are invalidated. ## 7. Run a test day before launch Use a separate staging database for tests, then install a clean live database. Do not manually delete individual production transactions. - Admin creates a sample item with price AED 60, cost AED 27, stock 10. - Volunteer opens with AED 300, sells one item and receives AED 100. Change AED 40; expected cash AED 360; stock 9. - Add ES cash donation AED 20. Expected cash AED 380. Sales remain AED 60. - Submit an AED 10 expense with a receipt. It must not change cash until admin approval. After approval, expected AED 370. - Exchange the purchased item for another variant and verify stock/cash differences. - Close with AED 370. Variance zero. Confirm closing report reaches both admin and closing volunteer. - Open the next shift with the retained AED 370. The period report must not add the same float again. - Check a dated period, exports, user permissions, receipt permissions and two-device access. - Test simultaneous sale attempts for low stock and duplicate purchase-order receiving. - Test password reset and revoked-account session blocking. ## 8. Backups and handover Configure daily hosting backups for BOTH the MySQL database and app/storage. Keep app/config.php and the application code in a separate private recovery backup. Verify a restore into staging. phpMyAdmin exports/cPanel backups may contain password hashes and reset tokens; restrict access. The admin Operational data export is useful for inspection but is NOT a complete disaster recovery backup: it omits password/account secrets and uploaded files. Normal CSV exports are not full backups either. Record who owns the domain and hosting; give the school designated admin credentials securely and a copy of this guide. Keep at least one responsible hosting contact. Agree on retention and backup monitoring with the school. ## Verification completed here PHP syntax was checked under a PHP 8.3 WebAssembly runtime. Domain-rule tests passed for sales/change/stock, cash donations, exchanges, approval, closing variance, continuous cash balance, roles and duplicate PO receipts. The responsive UI was reused from the tested prototype and rebuilt for PHP endpoints. Not verified here: native Bluehost execution, MySQL 5.7 integration/locking under load, cron path, file permissions, domain/SSL, actual mail delivery, cross-device sessions or a full browser acceptance run of this PHP build. These must be verified in staging before the system is considered ready for real operations. ## Limitations - Small-shop architecture: the operational workspace is stored as a JSON document in a MySQL LONGTEXT row under a database transaction and revision check. It is database storage, not browser storage. Accounts, files, audit, mail queue and request IDs have separate tables. Normalize large datasets before high-volume use; monitor max_allowed_packet and backup sizes. - One shared cashbox shift at a time; multiple volunteers cannot independently open different tills. - Purchase orders are commitments/stock receipts, not supplier payment accounting. Full-order receiving only. - Cash register operational reports are not statutory financial statements. Stock donations and samples are recorded as movements; their accounting valuation is not a full general ledger. - Monetary values are integer fils. Costs are weighted on PO receipt; unknown costs remain visibly unknown.