ShortLink — Installation & User Guide

1. Overview & features

ShortLink turns long URLs into short, shareable links and records detailed analytics for every visit. It is plain PHP with no framework and no build step, so it installs on ordinary shared hosting (cPanel, Hostinger, Plesk, XAMPP) in a couple of minutes.

Core features

• Login-free shortening — paste a URL on the home page and get a 7-character short link straight away.
• Duplicate protection — the same long URL always returns the same short code instead of creating a new one.
• Loop protection — URLs pointing at your own domain are rejected, so a short link can never redirect to itself.
• Click analytics at /{code}/stats — total clicks, unique and returning visitors, today / 7-day / 30-day totals, week-on-week trend, a daily (or weekly) timeline, devices, browsers, operating systems, countries, busiest hours, traffic sources, top referrers and a recent-activity table.
• Banner ad system new — image or HTML banners (ad-network snippets) on the home and stats pages, with impression and click tracking, CTR reporting, optional expiry dates, editing and three rotation modes.
• White-label settings — site name, SEO description/keywords, logo and favicon are all editable from the dashboard.
• Dual storage engine — choose MySQL or a flat-file JSON store during installation. Both expose exactly the same features.
• Privacy minded — public stats pages never expose IP addresses, and the JSON data folder plus banner uploads are blocked from web access.

2. Server requirements

3. Package contents

Upload the whole tree below, keeping the folder structure exactly as it is.

/
├── .htaccess                 Pretty-URL rewrite rules + directory browsing off
├── index.php                 Front controller: router, home page, analytics page
├── admin.php                 Admin dashboard (links, banner ads, white label)
├── install.php               Installation wizard  (delete after installing)
├── recover.php               Password recovery using the License UUID
├── page.php                  Terms / Privacy / Contact pages
├── config.sample.php         Example configuration (the installer writes config.php)
├── api/
│   ├── shorten.php           Creates short links
│   └── stats.php             Analytics JSON endpoint for the stats page
├── includes/
│   ├── db.php                Storage abstraction - MySQL and JSON engines + banner schema
│   ├── functions.php         Short-code generator, URL/IP/user-agent helpers
│   ├── banners.php           Banner domain: types (image/HTML), expiry, rotation, admin UI
│   ├── ads.php               Public endpoints /ad/impression/{id} and /ad/click/{id}
│   ├── header.php            Site navigation
│   └── footer.php            Footer (Terms, Privacy, Contact)
├── css/
│   └── style.css             Legacy stylesheet + banner image rules
├── js/
│   ├── analytics.js          Stats-page rendering (charts, tiles, tables)
│   ├── chart.min.js          Chart.js 4.4.9 (bundled, no CDN required)
│   └── main.js               Legacy helper, not loaded by the current UI
├── uploads/
│   └── banners/
│       └── .htaccess         Blocks script execution inside the upload folder
├── data/
│   └── .htaccess             Blocks web access to the JSON data store
└── Doc/
    └── index.html            This documentation

4. Upload the files

Option A — cPanel / shared hosting

1. Open File Manager and go to public_html (or public_html/your-folder for a subfolder install).
2. Upload the package ZIP and choose Extract in the same directory, so that index.php sits directly inside the target folder.
3. Select the extracted folder, choose Permissions and set 755 (with "recurse into subdirectories").

Option B — FTP (FileZilla and similar)

1. Connect to your host and open the web root (public_html, htdocs, www).
2. Upload every file and folder from the package, preserving the directory structure.
3. Make sure hidden files are visible in your FTP client so that .htaccess and data/.htaccess are transferred too — they are what makes pretty links and data protection work.

Option C — local test server (XAMPP / WAMP / MAMP)

1. Copy the package into C:\xampp\htdocs\shortlink (Windows) or /Applications/XAMPP/htdocs/shortlink (macOS).
2. Start Apache (and MySQL if you want to use MySQL mode) from the XAMPP control panel.
3. Continue with the installer at http://localhost/shortlink/install.php.

5. Run the installer

Open the installer in your browser:

https://your-domain.com/install.php
http://localhost/shortlink/install.php      (local test server)

Step 1 — Requirements check

The wizard verifies the PHP version, extensions and folder permissions. If anything fails it tells you exactly what to fix (usually folder permissions of 755).

Step 2 — Configuration

Step 3 — Installation complete

When the success screen appears:

• config.php has been generated with your settings.
• install.lock has been created, which stops anyone from reinstalling or hijacking the script.
• The admin account exists, and in MySQL mode all tables have been created.

6. Post-install checklist

1. Delete install.php from the server (keep a local copy in case you reinstall later).
2. Confirm config.php exists in the script root. If it does not, the folder was not writable — set permissions to 755 and run the installer again.
3. Open the home page and shorten a test URL. Copy the short link and open it: it should redirect to the destination and then show up in the analytics page.
4. Log in to /admin.php and
   • upload your logo and favicon and set the SEO description/keywords (White Label Settings);
   • upload at least one banner and choose a rotation mode (Banner Ads);
   • check that the click counter for your test link shows 1.
5. Recommended — enable HTTPS so short links and analytics run over TLS.
6. Optional — set your timezone so analytics match your local clock: add date_default_timezone_set('Asia/Kolkata'); near the top of index.php, or set date.timezone in php.ini. Without it, "Today" and the busiest-hour chart use the server default (often UTC).

7. Installing in a subfolder

ShortLink works at any depth. The only rule is that the Site Installation URL in the installer must match where the script actually lives:

The bundled .htaccess rewrites relative to its own directory, so subfolder installs need no manual rewrite edits. On Nginx add:

location /shortlink/ {
    try_files $uri $uri/ /shortlink/index.php?$query_string;
}

8. Reinstalling / changing the storage engine

To run the installer again — for example to switch from JSON to MySQL — you must remove the guard files:

1. Delete install.lock.
2. Delete config.php.
3. Open install.php again and complete the wizard.

9. Shortening links

Everything happens on the home page — no login required.

1. Paste the long URL into the input field (include http:// or https://).
2. Press Shorten. A green result card appears with the finished link.
3. Press Copy to copy it to the clipboard, or open the link directly.
4. Open /{code}/stats (or click Stats in the admin link table) to watch the traffic.

Behaviour worth knowing

10. The analytics page

Every short code has its own report at /{code}/stats, for example https://your-domain.com/5cnLTLu/stats. The page is public (anyone who knows the code can view it) but it is marked noindex so search engines stay out, and it never reveals IP addresses.

Buttons on the report

• Refresh — reloads the numbers immediately (the page also auto-refreshes every 60 seconds while the tab is visible).
• Copy Short Link — copies the /ad-aware short URL.
• ← Shortener — back to the home page.

11. The admin panel

Log in at /admin.php with the account created during installation. The dashboard has three sections.

Manage Links

• Table of every short link: code, destination, click count and creation date.
• Stats opens the analytics page for that link in a new tab.
• Delete removes the link and all of its click history (a confirmation dialog appears first).
• Pagination appears automatically once you have more than 10 links.

Banner Ads

Add image or HTML banners, choose the slot, set weights and an optional expiry date, edit an existing banner, flip the rotation mode and read the performance of each creative. Full details in section 12.

White Label Settings

• Site Name — navigation, page titles and the footer.
• Logo — PNG/JPG/GIF/WebP/Ico; replaces the text logo in the navigation bar.
• SEO Meta Description and Keywords — written into the page <meta> tags.
• Favicon — .ico or .png.

Logging out

The navigation bar shows Dashboard and Logout while you are signed in. Sessions are PHP sessions, so closing the browser does not sign you out — use Logout on a shared computer.

12. Banner ads

ShortLink can rotate its own banner ads in two positions. A banner is either an uploaded image or a block of HTML code, and each one can carry an optional expiry date. Impressions, clicks and CTR are tracked per banner — on both storage engines.

Slots

If no banner is active for a slot, a dashed "Advertise here" box is shown instead, linking to https://onwebco.com/contact.

Banner types

Adding a banner

1. Choose the Banner type (Image file or HTML code); the form switches between the image and the code fields automatically.
2. Image file: pick a JPG, PNG, GIF or WebP, maximum 2 MB. The type is verified by file content (not by file name) and the saved extension comes from the detected type. Then enter the Target URL (where a click should go) — only http:// / https:// URLs are accepted.
3. HTML code: paste the snippet into the textarea. It is stored exactly as pasted and no target URL is needed (or stored).
4. Pick the Position (Home page / Stats page).
5. Set a Weight (1–100) — used only by weighted rotation.
6. Set the Expiry date (the field is pre-filled with 30 days) or tick Unlimited (never expires).
7. Press Add Banner. It goes live immediately.

Rotation modes

The mode is stored in config.php as define('BANNER_ROTATION_MODE', 'weighted'); and applies to every slot. A brand-new installation does not contain that line yet and falls back to weighted; saving a mode in the admin panel adds it.

The banner list

• Thumbnail (or an HTML chip), target URL, ID and date for each banner.
• Type — Image or HTML.
• Weight, Impressions, Clicks and CTR (clicks ÷ impressions as a percentage; an em dash until the first impression — and always for HTML banners, which are not click tracked).
• Expires — the expiry date, Unlimited, or the date together with a red Expired badge and a "hidden while expired" note under the status.
• Status — Active or paused, toggled with the Pause / Activate link.
• Edit — re-opens the banner in a pre-filled form (type, fields, position, weight, expiry). Leave the file field empty to keep the current image; switching a banner from Image to HTML keeps the stored file, so nothing has to be re-uploaded if you switch back.
• Delete — removes the record, the image file and its statistics.

Expiry dates

Every banner can expire: the visitor-facing slots stop serving it as soon as the stored date has passed, so an expired banner drops out of the rotation and the slot moves on to the next active banner (or to the "Advertise here" placeholder).

• The banner itself is never deleted — it stays in the list with an Expired badge, so you can extend it, re-activate it or re-run it later.
• Unlimited (the checkbox) stores no date at all and never expires — that is also what banners created by older versions use.
• The check runs server-side on every page view, never in JavaScript, so it cannot be bypassed by the visitor or cached away.
• To revive an expired banner: Edit → set a new date (or tick Unlimited) → Save Changes.

How tracking works

Best practice

• Keep banners at the suggested pixel sizes — they scale down responsively but look sharpest at their native width.
• Add UTM parameters to target URLs (for example ?utm_source=banner&utm_campaign=home) so you can measure each slot.
• Use weighted rotation to favour your best creative, and check CTR in the banner list weekly.
• Pause instead of deleting a banner you may re-run later — deleting also discards its statistics.
• Set an Expiry date for anything with a fixed booking, and Unlimited for your own house ads.
• Keep HTML snippets small and HTTPS-only — heavy third-party iframes slow down the home page they are embedded in.

13. Terms / Privacy / Contact pages

These are static pages served by page.php and linked from the footer:

14. Password recovery

If you lose the admin password, open:

https://your-domain.com/recover.php

Enter the License UUID (the INSTALL_UUID value from config.php, which is the same UUID you entered during installation) and choose a new username and password. No e-mail is required.

15. config.php reference

config.php is generated by the installer; the admin panel updates some values for you. Never commit it to a public repository.

Where the data lives

16. Troubleshooting

17. Security notes

18. FAQ

Do visitors need an account to shorten a link?

No. Only the admin panel at /admin.php is protected.

Which storage mode should I choose?

JSON if you want a zero-configuration install and modest traffic — one file per short code, easy to back up. MySQL if you expect heavy traffic or many links, because the database handles concurrent writes better than flat files.

Can I switch from JSON to MySQL later?

Yes, by reinstalling (see section 8), but your existing links, clicks and banners are not migrated automatically — export or re-create them.

Can I change the short codes?

Codes are generated automatically (7 characters, base62) and duplicates of the same destination share one code. There is no manual "custom alias" field in this version.

How long are click statistics kept?

Forever, until you delete the link (which deletes its clicks too). There is no automatic pruning, so very busy links accumulate large files in JSON mode.

How many banners can I add?

No limit, and you can mix both types. Add as many as you like per position and let the rotation mode decide which one shows.

Can I use an ad network snippet instead of an image?

Yes — choose the HTML code banner type and paste the snippet: a <script> tag, an <iframe>, or plain <a><img> markup. It is output verbatim. Because the snippet carries its own links, clicks are not counted for HTML banners, but impressions still are. A target URL is not needed (and is not stored) for them.

What happens to a banner when its expiry date passes?

It stops being served right away and the slot falls back to the next active banner, or to the "Advertise here" placeholder. The banner stays in the admin list with an Expired badge and keeps all of its statistics — open Edit, set a new date (or tick Unlimited) and save to bring it back. Banners created before this feature existed count as unlimited.

Can I edit a banner instead of deleting and re-adding it?

Yes — use Edit in the banner list. You can change the type, the image (leave the file field empty to keep the current one), the target URL, the HTML code, the position, the weight and the expiry date. Impressions and clicks are never reset by an edit, and switching a banner from Image to HTML keeps its stored file, so nothing is lost if you switch back.

Do banners appear on the 404 page or the Terms page?

No. Banner slots exist only on the home page (home) and the analytics page (stats).

Why does my country show as "Unknown"?

You are almost certainly testing from a private IP address (localhost), which is never sent to the geo lookup service. Real visitors resolve normally, provided the curl extension is enabled.

Can I remove the "Powered by" credit in the footer?

The credit lives in includes/footer.php and can be edited, but please respect the licence terms of your purchase.

Will the analytics charts keep working offline?

Yes. Chart.js is bundled in js/chart.min.js, so no CDN connection is required.

Something is broken — where do I start?

Work through section 16, then check the browser console (F12) for missing assets and the server error log for PHP messages.