LankaAds Customer Documentation

1. Getting Started & Package Contents

Welcome to LankaAds. LankaAds is a comprehensive, self-hosted classified advertisements marketplace platform designed for high performance, reliability, and ease of management. It features a complete multi-tier moderation system, image watermark branding, manual bank transfer verification with deposit slip inspection, tiered subscription memberships, featured/urgent listing promotions, and cryptographically signed system updates.

Configurable Internationally (Shipped Defaults vs. Custom Adaptation)

LankaAds is built to be configured for any country or market worldwide:

• Shipped Defaults: Out of the box, the software includes pre-seeded Sri Lankan administrative geography (9 provinces, 25 districts, hundreds of cities) and default English and Sinhala (සිංහල) language dictionaries. These serve as ready-to-launch blueprints.
• International Adaptation: Any marketplace operator can easily customize the platform for any country, territory, or localized region by configuring their national currency (USD, EUR, GBP, LKR, AUD, CAD, INR, etc.), selecting their local timezone, adding or renaming categories and custom specification fields, creating local regions/cities in Settings → Locations, and tailoring translations.

Customer Package File Structure

When you extract your customer release archive, you will find the following clean directory structure:

lankaads/
├── app/                      # Backend PHP Application (Custom MVC architecture)
│   ├── Config/               # Database, Env, license keys & update trust store
│   ├── Controllers/          # REST API & web route controllers
│   ├── Core/                 # Request, Response, CSRF & Router primitives
│   ├── Middleware/           # Authentication, CORS, Rate-limiting & Maintenance
│   └── Services/             # StoreService, License, Crypto & Update engine
├── cli/                      # Customer CLI utilities (Setup token, cron, recovery)
│   ├── generate_setup_token.php  # Utility to generate storage/installer/setup_token.txt
│   ├── update_recovery.php       # Private update recovery & rollback tool
│   ├── cron.php                  # Scheduled task runner (ad expiry & maintenance)
│   ├── license_refresh.php       # Scheduled background license renewal
│   └── reset_admin_password.php  # Emergency administrator password reset utility
├── database/                 # SQL schemas & blueprints
│   └── install/              # schema.sql, seed.sql, triggers.sql
├── public/                   # Public Web Root (Domain Document Root)
│   ├── assets/               # Pre-compiled React bundle (app.js, app.css)
│   ├── uploads/              # Customer listing photos, banners, watermarks
│   ├── .htaccess             # Apache rewrite rules & security headers
│   ├── favicon.ico           # Platform default favicon
│   └── index.php             # Web entry point
├── storage/                  # Private application storage (Must be protected from HTTP)
│   ├── installer/            # setup_token.txt & installed.lock
│   ├── license/              # Cached license certificate & state
│   ├── logs/                 # Security & error logs
│   ├── receipts/             # Customer uploaded bank deposit slips
│   ├── sessions/             # File-based PHP sessions
│   └── updates/              # Pre-update backups & staging directory
├── .env.example              # Environment variables template
├── .htaccess                 # Shared hosting root redirect to public/
├── INSTALLATION.md           # Quick setup guide
└── UPDATE_GUIDE.md           # System update reference guide

2. Server & Hosting Requirements

LankaAds runs efficiently on standard Linux shared hosting with cPanel, DirectAdmin, Plesk, Cloud VPS, or dedicated servers. The built-in Web Installer automatically audits your server environment in Step 1 before proceeding.

MySQL Database User Privileges

When creating your MySQL user in cPanel or phpMyAdmin, you only need to grant standard data and table structure permissions. High-risk administrative privileges are intentionally not required:

Directory Permissions

Set directory permissions to 0755 (or 0775) and files to 0644. Never use 0777 on any directory. The installer and application need write access to:

• Application root directory (to atomically write .env with 0600 permissions upon installation completion).
• storage/ and all subdirectories (storage/installer/, storage/license/, storage/sessions/, storage/logs/, storage/receipts/, storage/updates/).
• public/uploads/ and subdirectories (public/uploads/listings/, public/uploads/banners/, public/uploads/watermarks/, public/uploads/footer/).

3. cPanel & Server Installation Walkthrough

LankaAds includes a browser-based, self-contained 5-step Web Installer Wizard located at /install. You do not need SSH, terminal access, or command-line experience to install LankaAds.

Creating the MySQL Database & User in cPanel

Before launching the web installer, create an empty MySQL database and dedicated database user in your hosting control panel:

Supported Hosting File Layouts

Choose the placement method that matches your cPanel configuration:

The Private One-Time Setup Token

To prevent unauthorized strangers from visiting a freshly pointed domain and running the installer before you do, LankaAds is protected by a one-time Setup Token stored outside the public directory.

Step-by-Step Installation Walkthrough

Navigate to https://yourdomain.com/install in your web browser. Visiting your homepage before installation automatically redirects you to the installer.

0

Gate 0: Setup Ownership Verification

Security Gate

Enter the private token you created in storage/installer/setup_token.txt and click Verify Setup Token & Begin. The token is checked in constant time, your session is regenerated, and Step 1 unlocks.

1

Step 1: Server Requirements & Permissions

Audit Complete

The installer runs real-time checks on your PHP version (≥ 8.1), required extensions (PDO, OpenSSL, cURL, mbstring, JSON, fileinfo, GD/Imagick), directory permissions (.env root, storage/*, public/uploads/*), pre-built frontend bundles, and the bundled RSA license key trust store.

Click Continue to Website & Database → once all blocking requirements show green checkmarks.

2

Step 2: Website & MySQL Database Configuration

Configuration

Configure your marketplace identity and database connection credentials:

• Website Title: Your site name (e.g. LankaAds Classifieds).
• Canonical Installation URL: Your full website URL with https:// (e.g. https://yourdomain.com). No trailing slash.
• Default Timezone: Select your timezone (defaults to Asia/Colombo, configurable for any international timezone).
• Default Currency: Choose your single platform currency (USD, EUR, or LKR).
• Database Connection: Host (127.0.0.1 or localhost), Port (3306), Database Name, Username, and Password.

Empty Database Protection: The database you specify must already exist and be completely empty (0 tables). If existing tables from another application are detected, the installer halts to protect your data from being overwritten.

Click Test Connection & Continue →. The installer tests MySQL connectivity, verifies UTF-8 collation, and tests table creation permissions.

3

Step 3: License Activation

Domain Binding

The installer displays your normalized domain host, base path, and persistent installation ID. Enter your Envato Purchase Code (UUID) or Author-Issued Manual License Code (LKA-MAN-...).

Click Activate License & Continue →. The installer validates your license with the author's licensing service and stores the validated certificate locally in storage/license/license_state.json.

4

Step 4: Administrator Account Creation

Super Admin

Create your primary Super Administrator account. Enter your Full Name, Email Address, and a strong password (minimum 8 characters, containing at least one letter and at least one number or symbol).

Zero Default Passwords: LankaAds does not create any insecure default accounts or hardcoded passwords. Your administrator password is encrypted using PBKDF2-HMAC-SHA512 (100,000 iterations).

Click Save Administrator & Review →.

5

Step 5: Review & Execute Installation

Execution

Review the non-sensitive configuration summary: Site Title, Canonical URL, Timezone, Currency, MySQL credentials, License Status, and Administrator Email.

Click Install LankaAds Now. The installer will:

1. Acquire an exclusive file mutex lock (storage/installer/install.lock) to prevent duplicate submissions.
2. Execute database/install/schema.sql, creating all 45 InnoDB tables in foreign-key order.
3. Execute database/install/seed.sql (curated Sri Lanka districts, categories, email templates, and system pages — with 0 sample ads or fake users).
4. Apply your chosen Currency, Timezone, and Site Title to system_settings and currencies.
5. Create your initial Super Administrator account (usr-admin-1).
6. Generate fresh application encryption keys (APP_SECRET, MEMBERSHIP_PAYMENT_WEBHOOK_SECRET) and write .env with 0600 permissions.
7. Write storage/installer/installed.lock, delete setup_token.txt, and lock the installer permanently.

✓

Installation Complete & Locked

Ready for Launch

Upon completion, the installer presents the confirmation card verifying that all 45 database tables have been created and the installer lock is engaged.

Any subsequent attempt to access /install displays the locked screen and blocks re-execution:

4. License Activation, Limits & Domain Migration

LankaAds validates your software license upon installation and caches the verified status locally in storage/license/license_state.json, ensuring your marketplace continues to run at maximum speed with zero external network delays on customer page visits.

Supported License Formats & Verification Path

License Runtime States & Outage Grace Policy

5. Initial Setup & Platform Identity

After installation, sign in to your administrator dashboard at https://yourdomain.com/admin/login using your administrator email and password.

Upon signing in, you are greeted by the System Overview Dashboard (/admin/system-overview), displaying real-time metrics for total ads, pending moderation items, approved ads, registered users, and active revenue.

Platform Identity & Branding (Logo & Favicon)

Navigate to General Settings → Identity & Branding (/admin/general-settings?tab=logo-favicon) to customize your site appearance:

• Site Title: Displayed across browser tabs, emails, and OpenGraph social share cards.
• Header Logo: Upload your marketplace header logo (recommended: transparent PNG or SVG, max height 48px).
• Admin Sidebar Logo: Compact logo rendered in the top-left of the admin navigation pane.
• Favicon: 32x32 PNG or ICO icon displayed in web browser tabs.

Single-Currency Settlement Model (No Exchange Rate Drift)

LankaAds implements a Single Active Currency model (configured in /admin/general-settings?tab=currency-timezones). By design, there are no live exchange rate feeds or currency drift calculations. All listings, membership subscriptions, urgent/featured promotions, and bank transfer receipts settle strictly in your designated platform currency.

Timezone Baseline & International Adaptation

LankaAds defaults to Asia/Colombo (UTC+05:30) as its baseline default timezone, synchronized across:

• PHP runtime date-time formatting (date_default_timezone_set()).
• MySQL session timezone (e.g. SET time_zone = '+05:30').
• Classified ad expiry countdowns and moderation audit timestamps.

You can select any valid IANA timezone worldwide in /admin/general-settings?tab=currency-timezones (e.g. America/New_York, Europe/London, Asia/Dubai, Australia/Sydney) or click Reset to Baseline at any time to restore Asia/Colombo.

Email & SMTP Configuration

To deliver transactional notifications (welcome emails, password resets, ad approval/rejection notices, bank slip verifications), configure your SMTP credentials in Settings → Email Settings:

• SMTP Host: (e.g. mail.yourdomain.com or smtp.sendgrid.net).
• SMTP Port: 587 (STARTTLS) or 465 (SSL/TLS).
• SMTP Username & Password: Encrypted securely in the database using CryptoService.
• Sender Name & Email: (e.g. LankaAds Notifications <noreply@yourdomain.com>).

Click Send Test Email to verify outbound connectivity before enabling mandatory email verification.

6. Users, Roles & Permissions

LankaAds enforces strict Role-Based Access Control (RBAC) defined in App\Services\PermissionPolicy. Every user is assigned exactly one role:

The 11 Moderator Allowed Sections

When hiring community moderators to review listings, you can create accounts with the moderator role. Moderators are permitted into exactly these 11 areas:

Listing Moderation Workflow

If Approval Mode is enabled in /admin/approval-settings, newly posted listings and seller edits are routed to Pending Ads (/admin/pending-ads):

• Approve: Immediately publishes the listing to the public marketplace, generates watermarked images, stamps the moderator ID, and sends an approval email to the seller.
• Reject: Opens a rejection modal to select or type a specific reason (e.g. "Low resolution photos" or "Incorrect district selected"). LankaAds automatically dispatches the advertisement_rejected email with the reason so the seller can edit and resubmit their ad from /my-account.

7. Categories, Locations & Ad Management

LankaAds includes a flexible categorization engine that supports unlimited categories, nested subcategories, and category-specific custom specifications:

Locations & Geographical Hierarchy

The software ships with the complete administrative geography of Sri Lanka (9 Provinces, 25 Districts, and hundreds of cities) as its default blueprint. In Settings → Locations (/admin/locations), operators can edit, delete, or create new countries, provinces, states, districts, and cities for any regional market:

The Public Ad Posting Workflow (/post-ad)

Customers submit classified listings through a visual multi-step wizard:

1. Category Selection: Choose primary category (e.g. Vehicles) and subcategory (e.g. Cars).
2. Location Selection: Select District and City/Town.
3. Specifications: Dynamically generated custom fields (e.g. Brand, Model, Year of Manufacture, Mileage, Fuel Type, Transmission).
4. Pricing: Enter price with an optional Negotiable toggle switch.
5. Photos Upload: Drag & drop multiple listing photos. The server automatically optimizes image sizes and applies your custom watermark.
6. Contact Details: Verified phone number and optional direct WhatsApp chat button.

8. Manual Bank Payments, Transactions & Memberships

LankaAds includes an offline Bank Transfer / Direct Deposit Gateway designed for local banks and direct wire transfers.

Bank Transfer Receipt Submission & Verification Workflow

1. When purchasing a membership or ad promotion, the customer selects Bank Transfer.
2. The system displays your account details (Bank Name, Account Number, Branch, and Reference Code instructions).
3. The customer deposits funds at a bank branch, online banking portal, or CDM kiosk and uploads a photo or PDF of the deposit slip.
4. The transaction appears in Admin → Transactions (/admin/transactions) marked as pending_verification.
5. The admin or moderator inspects the slip in the Transaction Detail Modal and clicks Approve or Reject.
6. Upon approval, the system automatically activates the membership package or applies the Urgent/Featured promotion badges to the listing.

Membership Packages (Free, Silver, Gold, Platinum)

Monetize your marketplace by offering tiered subscription packages for volume dealers, real estate agents, and commercial stores:

Listing Promotions: Featured & Urgent Badges

Sellers can boost individual listings without subscribing to a monthly membership:

• Featured Ad: Pinned to the top of category search results and displayed in the homepage Featured Ads Carousel with a prominent golden badge.
• Urgent Ad: Displays a high-contrast red URGENT badge, signaling immediate availability to interested buyers.

9. CMS & Customization

LankaAds includes comprehensive visual styling, content management, and localization controls so you can match your company's corporate branding and regional preferences without touching code:

Theme Package Information & Preview (/admin/themes)

The Themes section in the administrator console provides an overview of your active marketplace layout, theme package metadata, and author attribution:

• Theme Identification: Displays current active theme name, author, release version, and feature summary.
• Responsive Preview: Open the built-in preview modal to inspect the theme across desktop, tablet, and mobile viewport simulations before applying changes.

Website Colors Management (/admin/website-colors)

Live marketplace color customization is managed independently from the theme card on the dedicated Website Colors page (/admin/website-colors). This interface gives you fine-grained control over public styling with real-time preview and accessibility contrast checking:

LankaAds provides 3 primary visual brand color controls:

• Primary Color (primaryColor, Default: #10b981):
  Controls public brand accents across the entire marketplace, including the homepage search hero banner, listing price labels on cards and detail views, active category and filter pills, count badges, focus rings on form inputs, and step progress indicators.
• Header Color (headerColor, Default: #0f172a):
  Controls the top fixed navigation header background color. The engine dynamically calculates font contrast to ensure navigation links, category menus, and user account buttons remain crisp and readable against both light and dark backgrounds.
• Button Color (buttonColor, Default: #10b981):
  Controls primary high-visibility call-to-action buttons, including the prominent Post Free Ad button in the header, search submission buttons, form submit buttons, and active category badges.

Interactive Tools: Use the live visual color picker or input exact 6-character hex codes (e.g. #2563eb). An interactive preview card displays exactly how listings, price tags, and buttons will appear to your customers. Click Reset to Defaults at any time to restore the factory color palette, or click Save Changes to store and apply the new styles platform-wide.

Automatic Listing Watermark Branding (/admin/settings/watermark)

Protect your sellers from image scrapers. LankaAds automatically applies a transparent PNG watermark across all newly uploaded photos:

• Default Watermark: LankaAds ships with a clean, pre-seeded transparent watermark graphic (/uploads/watermarks/default-watermark.png).
• Custom Watermark Upload: In Settings → Watermark (/admin/settings/watermark), upload your custom logo (transparent PNG, recommended 400x100px).
• 9 Valid Grid Positions: Position the watermark at center, top-left, top-center, top-right, middle-left, middle-right, bottom-left, bottom-center, or bottom-right.
• Precision Sizing & Opacity: Adjust watermark size (10% to 80% of canvas width, default 38%), opacity (0% to 100%, default 50%), and outer margin (0px to 60px, default 24px).

Promotional Banner Management & Ad Modes

Monetize your website traffic by placing advertising banners across high-traffic sections in Settings → Banners (/admin/settings/banners) and Mobile Banners (/admin/settings/mobile-banners):

LankaAds supports 4 distinct banner advertising modes for each slot:

• Image Mode: Upload image banners (max 5MB, JPG/PNG/WebP/GIF) with custom click-through destination URLs and optional Open in New Tab.
• Custom HTML Ad Code: Embed sandboxed HTML/JavaScript snippets from affiliate networks, sponsors, or third-party ad exchanges.
• Google AdSense: Enter your Google Ad Client ID (ca-pub-xxx) and Ad Slot ID for automated banner delivery.
• Google Mobile AdSense: Dedicated responsive mobile ad format optimized for smartphones and tablets.

Available Banner Slots:

• All Ads Browsing: Top Banner, Sidebar/Right Banner, and Bottom Banner.
• Single Ad Detail Page: Top Banner, Sidebar Banner, and Bottom Banner.

System CMS Pages Management (/admin/settings/pages)

Create and edit legal, informational, and marketing pages in Settings → Pages (/admin/settings/pages). Footer links can be grouped and ordered in /admin/settings/footer:

• Pre-Seeded Core Pages: Ships with standard content for About Us (/pages/about), Terms & Conditions (/pages/terms), Privacy Policy (/pages/privacy), Safety & Anti-Fraud Tips (/pages/stay-safe), and Contact Us (/pages/contact).
• Dynamic System Workflows: Pages such as Memberships (/pages/memberships), Advertising (/pages/advertising), and Boost Ad (/pages/boost-ad) automatically bind to backend databases and active pricing plans.
• Rich WYSIWYG Content Editor: Create custom informational pages with headings, bold/italic typography, bullet/numbered lists, inline links, embedded images, tables, and blockquotes.
• Placement & Status Controls: Choose display locations (Header navigation, Footer Column 1, Footer Column 2, or standalone direct link) and toggle between Draft and Published status. System pages also include a Reset to Factory Content action.

Multilingual Translation & Languages Management (/admin/general-settings?tab=languages)

LankaAds is built from the ground up for internationalization and regional localization. The Languages tab under General Settings (/admin/general-settings?tab=languages) provides full control over supported marketplace languages and translations:

Key Language Capabilities:

1. Pre-Configured Language Catalogs:
   Ships with complete, pre-configured English (en) and Sinhala (si, සිංහල) language catalogs ready out of the box.
2. Default Marketplace Language:
   Select which language is automatically served to new, unauthenticated visitors when they first arrive at your site.
3. Header Language Button Slots & Visibility Controls:
   The public navigation header supports two dedicated quick-switch button slots: Language Button 1 (default: en English) and Language Button 2 (default: si Sinhala).
   • Slot Assignment: In the language table, click Set as Language Button 1 or Set as Language Button 2 on any enabled language row to assign it to that header slot. A single language cannot be assigned to both slots simultaneously, and disabled languages cannot be assigned until re-enabled.
   • Visibility Controls: In the Public Header Language Buttons card below the table, independent toggles control whether each button is displayed in the public header (Button 1: ON (Visible) / Button 2: ON (Visible)). Toggling a button to hidden conceals that specific header button without disabling the language or affecting visitor translation catalogs.
4. Adding New Languages:
   Click + Add Language to open the modal. Enter the English Name (e.g. Tamil), Native Script Name (e.g. தமிழ்), ISO Locale Code (e.g. ta), and initial visibility state.
5. In-Browser Translation Catalog Editor:
   Click Translate / Edit on any language row to open the interactive translation studio. It features over 320 categorized translation keys divided across functional groups: Common, Header & Navigation, Footer, Authentication, Classified Ads, User Dashboard, Admin Panel, and Notifications.
6. Search, Filter & Placeholder Validation:
   Use the live search box to find strings instantly. Filter by section or view only Missing Translations. Built-in variable validation protects dynamic tokens (e.g. {name}, {count}, {amount}) so translation edits cannot break site functionality.
7. Save & Reset to Defaults:
   Click Save Translations to commit updates directly to the database. If you ever need to revert custom edits, click Reset to System Defaults to restore factory catalog strings.

10. Signed System Updates & Disaster Recovery

LankaAds includes a built-in, cryptographically signed Manual System Updater (/admin/system-updates). It allows you to update your live installation in place without reinstalling or losing your listings, customer accounts, uploaded photos, payment receipts, memberships, or custom settings.

Step-by-Step Update Procedure

1. Download Official Signed ZIP: Obtain the official update archive published by the author for your version path (e.g. lankaads-update-v1.0.0-to-v1.0.1.zip). Customers must upload the original official signed archive directly without modifying, extracting, or repacking it.
2. Upload Package: In the admin panel, navigate to System Updates (/admin/system-updates), select the ZIP archive, and click Upload & Validate Package.
3. Preflight Verification: The server verifies the author's detached cryptographic signature (update-manifest.sig), checks minimum PHP and MySQL version requirements, tests storage directory write permissions, checks database connectivity, and audits the code tree for modified-file conflicts.

4. Mandatory Confirmation Checkbox & Install Trigger:
   Review the staged preflight verification summary, target version, build ID, and backup plan. You must explicitly check the confirmation checkbox:
   “I confirm that I have reviewed the preflight checks and wish to proceed with the update”
   Once checked, the green Install Update button becomes active. Click it to begin durable, checkpointed execution.
5. Durable Execution Pipeline & Verified Backups:
   The system updater initiates an automated, checkpointed execution pipeline in the following verified order:
   • Step 1 — Prepare & Engage Maintenance Mode: Re-validates directory permissions and manifest signature, then puts the website into Maintenance Mode (503 Service Unavailable) to prevent concurrent customer writes while keeping the admin update screen accessible.
   • Step 2 — Pre-Mutation Backups: Under active maintenance mode, creates and SHA-256 verifies a code archive (code_backup.zip) and consistent database snapshot (db_backup.sql) in private storage (storage/updates/backups/) before any mutations occur. If a backup fails before changes are made, maintenance mode is safely disabled and the update is aborted with zero mutations.
   • Step 3 — Apply Files: Copies update files individually to their target paths across the codebase, ordering ordinary files first and deferring updater core files to the final phase.
   • Step 4 — Database Migrations: Executes bundled incremental SQL schema migrations in strict sequence, recording applied migration tracking numbers.
   • Step 5 — Finalize & Release Maintenance Mode: Runs post-update health verification, updates installed_manifest.json and installed.lock, resets OPcache/bytecode caches, marks the update journal COMPLETED, and automatically releases Maintenance Mode to restore public access.
6. Post-Update Health Verification:
   Verify that the System Updates interface displays the new target version and build ID with a verified journal state (Figure 10.3). Next, visit your public marketplace homepage (/), browse listings, and test submitting an ad (/post-ad) to confirm that web requests, React components, and database queries are functioning flawlessly.

Understanding Rollback Options & Schema Migration Compatibility

Private Server CLI Recovery (cli/update_recovery.php)

If a server timeout, network drop, or unexpected hosting failure interrupts an update mid-execution, run the private CLI tool directly from your application root directory over SSH or cPanel Terminal.

Step 1: Navigate to Root & Inspect System Status

Always begin by navigating to your application root directory and inspecting the active journal status, maintenance state, and verified backup files:

cd /path/to/lankaads
php cli/update_recovery.php --status

The --status output will display:

• Current Installed Version & Build ID: The live codebase state.
• Maintenance Mode: Whether the site is locked (ENABLED) or open (DISABLED).
• Active Journal ID: A unique identifier (e.g. upd_jnl_v1.0.1_20261111_a1b2c3d4) recording the staged update checkpoints.
• Available Backups: Absolute paths to verified code_backup.zip and db_backup.sql with their exact row counts and SHA-256 hashes.

How to Substitute <JOURNAL_ID>

In the recovery commands below, replace the placeholder <JOURNAL_ID> with the exact Journal ID printed in your --status output (for example, upd_jnl_v1.0.1_20261111_a1b2c3d4). Do not include the angle brackets. Explicit journal identification prevents accidental rollbacks from targeting the wrong backup archive.

Select ONE Appropriate Recovery Action

Action Option A: Resume an Interrupted Update (Recommended for Timeouts)

If your update was interrupted by a PHP execution timeout (e.g. max_execution_time reached) or temporary server drop while extracting files, this command resumes execution cleanly from the last durable checkpoint without repeating completed steps:

php cli/update_recovery.php --resume

Action Option B: Roll Back Application Code Files Only (Non-Destructive)

Restores application PHP, JavaScript, and CSS files from code_backup.zip while leaving all database tables and customer records untouched. Use this if an update fails during file staging or asset caching, provided database schema migrations have not altered tables:

php cli/update_recovery.php --rollback-code --journal-id=<JOURNAL_ID>

Action Option C: Restore Database Snapshot (Destructive to New Customer Writes)

Restores database tables from the pre-update db_backup.sql snapshot. Warning: Completely overwrites database tables. Any listings, customer accounts, or payment records created after the snapshot will be permanently lost. Requires explicit confirmation token:

php cli/update_recovery.php --restore-db --confirm=RESTORE_DATABASE --journal-id=<JOURNAL_ID>

Action Option D: Full Rollback (Code Files and Database Snapshot)

Reverts the entire installation to its pre-update baseline by restoring both code files from code_backup.zip and database tables from db_backup.sql, updates the journal to ROLLED_BACK, and exits maintenance mode. Requires explicit confirmation token:

php cli/update_recovery.php --full-rollback --confirm=FULL_ROLLBACK --journal-id=<JOURNAL_ID>

Releasing Maintenance Lock After Verification

Once you have successfully completed an update, resumed execution, or finished a rollback, verify that your site is operating normally. If maintenance mode was not released automatically, run this utility to clear the lock:

php cli/update_recovery.php --disable-maintenance

11. Troubleshooting & Common Error Solutions

Consult this quick reference table if you encounter common error codes or installation blockers:

12. Support, Changelog & Third-Party Credits

Customer Package Opening & First Steps

When you download your purchased customer release package, follow these initial steps:

1. Extract the Downloaded ZIP: Extract the archive on your local computer using standard archive tools (Windows Explorer, 7-Zip, or macOS Archive Utility).
2. Review the Documentation Locally: Double-click Documentation/index.html. It opens directly in any web browser without an internet connection or web server.
3. Upload to Hosting: Upload the application files to your hosting server via cPanel File Manager, SFTP, or rsync.
4. Run the Web Installer: Create your private setup token in storage/installer/setup_token.txt, create an empty MySQL database, and navigate to https://yourdomain.com/install.

Official Customer Support

If you need assistance with installation, have questions regarding configuration, or encounter a software bug, please reach out through the author's confirmed item support tab and contact channel on the purchase marketplace where you bought LankaAds.

Changelog — Version 1.0.0 (Baseline Release)

Third-Party Notices & Open Source Credits

LankaAds is built with gratitude to the open-source community and utilizes the following software:

• React & React-DOM (v19.3.0): Copyright © Meta Platforms, Inc. and affiliates (MIT License).
• Lucide Icons (lucide-react v1.56.0): Copyright © Lucide Contributors (ISC License).
• TypeScript (Build-time): Copyright © Microsoft Corporation (Apache License, Version 2.0).
• Webpack (Build-time): Copyright © JS Foundation and other contributors (MIT License).
• PHP Core Extensions: Copyright © The PHP Group (PHP License & OpenSSL/Apache-2.0 License).

About the Author