📄Docs for Toplist Script

Toplist Script is a PHP-based toplist CMS for ranked comparison and directory sites. The public site shows a category grid homepage, category listing pages, and individual review pages for each ranked entry. The admin panel handles content, layout, affiliates, analytics, and AI-assisted publishing.

What you get out of the box:

• Homepage grid layout with drag-and-drop editor
• Categories and ranked entries (manual sort order)
• Per-entry review pages with pros, cons, ratings, and thumbnails
• Affiliate link fields and site-wide outbound tracking
• Self-hosted analytics (pageviews and outbound clicks)
• AI Generator for categories and website discovery
• Light/dark theme, color schemes, popups, and info pages

There is no Composer install and no .env file. Configuration is config/config.php plus a MySQL settings table managed from admin.

Optional: OpenAI API key for AI Generator; ScreenshotOne or Site-Shot keys for thumbnail capture on protected sites.

1. Upload the script to your web root (e.g. public_html or htdocs/toplist).
2. Edit config/config.php — set DB_HOST, DB_NAME, DB_USER, DB_PASS.
3. If the site is not in a subfolder, ensure RewriteBase in .htaccess matches your path (default /toplist/).
4. Visit https://yourdomain.com/install/install.php (adjust path if not in /toplist/).
5. The installer creates the database from database/schema.sql, seeds sample content if empty, creates default settings, and adds an admin user if none exists.
6. Delete the install/ folder when installation succeeds.
7. Log in at /admin/login.php and change the default password immediately.

// config/config.php
define('DB_HOST', '127.0.0.1');
define('DB_NAME', 'toplist_cms');
define('DB_USER', 'your_db_user');
define('DB_PASS', 'your_db_password');

After updates to the script, run /install/migrate.php once to apply database migrations (v2 through v11).

config/config.php

File path: config/config.php

• DB_HOST, DB_NAME, DB_USER, DB_PASS — database connection
• APP_NAME, APP_TAGLINE — defaults; usually overridden by admin settings
• BASE_PATH and BASE_URL — auto-detected from the request (strips /admin, /install, /api)

Settings table (admin-managed)

Most site behavior is stored in the settings table and edited under Admin → Settings and related Site screens. Key groups:

• Site identity — site name, meta description, contact email, Telegram, social follow URL
• Outbound link tracking — query parameter name (default ref) and value; leave value empty to disable
• Analytics — enable/disable, retention days (7–365)
• Thumbnails — screenshot API keys, proxy list, capture preferences
• AI — OpenAI API key (stored encoded), model selection

URL: {your-site}/admin/

Navigation is grouped into four areas:

Dashboard shows setup health, recent entries, KPIs, and a short analytics chart. Use it to spot missing thumbnails, descriptions, or meta fields before launch.

Reports lists problems visitors submit from entry pages (broken links, outdated info, etc.). Requires the entry_reports table from migrations — run install/migrate.php if the screen shows a setup warning.

Top bar actions: View site, + New entry, username menu.

Categories are the homepage grid blocks and listing sections (e.g. “Best VPNs”, “Project management tools”). Each category has its own public URL: /{slug}/

Admin → Categories → Add category

Important fields:

• Name and Slug — public title and URL
• Description and Intro headline — category page copy
• Icon — CSS icon class or emoji
• Accent / title line / button colors — RGB values for the block
• Grid column (1–4) and Sort order — homepage position
• Visible rows — how many entries show on the homepage block
• Meta title and Meta description — SEO for the category page
• Active — hide without deleting

Entries are the ranked sites inside a category. Ranking is controlled by Sort order (lower number = higher rank). There is no public voting — order is set in admin.

Admin → Entries → + New entry or use the layout editor / AI Generator.

Important fields:

• Category, Name, Slug
• URL — destination website
• Affiliate link — optional; overrides outbound URL when valid (see Affiliates)
• Thumbnail — auto-captured screenshot or manual upload
• Description — short summary
• Review content — full HTML review (rich editor)
• Rating, Pros, Cons
• NEW / Featured badges
• nofollow on outbound links (default on)
• Meta title / Meta description
• Active, Skip snapshot

Public URLs:

• Review page: /{entry-id}/{slug}/
• Outbound “Visit site” uses affiliate URL when set, otherwise the entry URL

Entries list supports filtering by category, completeness flags (missing thumb, description, review, etc.), drag reorder when filtered to one category, and bulk AI fill.

Per-entry affiliate links

On each entry, set Affiliate link to your tracking URL from Impact, CJ, ShareASale, or a direct program. When valid, every “Visit site” button uses this URL instead of the plain destination URL.

Affiliate links are marked so site-wide ref tracking is not appended on top of partner URLs (avoids broken double tracking).

Site-wide outbound tracking

Admin → Settings → Site identity → Outbound link tracking

• Query parameter name — default ref
• Parameter value — e.g. your site identifier; leave empty to disable

When enabled, external clicks on category links get ?ref=yourvalue appended client-side. This is separate from affiliate network links and from self-hosted analytics.

Admin → Analytics — self-hosted pageview and click tracking. No Google Analytics required.

• Enable under Settings → Site identity → Enable analytics tracking
• Set Raw data retention (7–365 days)
• View trends for pageviews, outbound clicks, and top pages/entries

Data is collected via POST /api/analytics-collect.php from the front-end. Admin pages are not indexed and use noindex, nofollow.

Light / dark mode

Visitors can toggle light/dark theme. Configure separate background patterns for each mode under Appearance or from the layout editor Background control.

Color schemes

Admin → Colors — preset schemes (Classic Orange, Ocean Breeze, Forest Trust, Royal Violet, Ember Sunset, Graphite Pro, etc.) plus per-token overrides for brand, footer, browser chrome, and more.

Logos & images

Appearance — site logo, mobile logo, favicon, backgrounds, footer banner.
Site images — replace UI sprites, badges, OG default image, toggle icons.

Homepage footer block

Admin → Homepage — rich HTML footer/FAQ section, gradient colors, bottom bar styling.

Info pages

Admin → Info pages — About, FAQ, legal pages at /{slug}/ (routed via route.php). Each page has title, slug, HTML body, and meta fields.

Pages (entry templates)

Admin → Pages — entry disclaimer text, mobile toolbar, bottom promo block settings.

Popups

Admin → Popups — welcome modal, promo bubble, chat widget, language suggest, review disclaimer, report review, saved drawer, “Buy this Script” overlay. Preview from the layout editor Previews menu.

Links

Admin → Links — footer social icons, footer link columns, promo/copyright JSON config.

Built-in SEO features:

Not included: automatic XML sitemap generator or robots.txt file — add these at server level if needed.

Rewrite rules live in .htaccess. If you deploy to domain root instead of /toplist/, update RewriteBase accordingly.

After uploading a new version of the script:

1. Back up your database and assets/uploads/ folder
2. Overwrite PHP files (keep config/config.php and uploaded assets)
3. Visit /install/migrate.php once
4. Confirm admin dashboard loads and run a quick front-end check

Migrations add features incrementally (entry pros/cons, affiliate URLs, info pages, analytics tables, skip snapshot, etc.).