Install on cPanel (Step-by-Step)

This guide walks you through installing XSender on a cPanel shared host, end to end, with no terminal access required. Most customers buying XSender on CodeCanyon land here, so we have kept every step explicit and called out the parts that most often cause "doesn't load" or "white page" support tickets.

Prefer a VPS? Performance is materially better on a VPS. See Getting Started → Installation for the VPS path (SSH + composer optional). This article is for customers stuck on shared hosting.

Before you start — checklist

A cPanel account with PHP 8.2 or higher available (Software → Select PHP Version).
The following PHP extensions enabled: bcmath, ctype, curl, fileinfo, gd (or imagick), intl, json, mbstring, openssl, pdo, pdo_mysql, tokenizer, xml, zip.
A blank MySQL 5.7+ / MariaDB 10.3+ / MySQL 8.x database with a username and password (we will create both in Step 2).
The xsender-installer-vX.Y.zip downloaded from your CodeCanyon → Downloads page (use "All files & documentation", not "Installable Laravel only").
A domain or subdomain pointed at your cPanel account (e.g. app.yourcompany.com).

Step 1 — Set PHP version & extensions

cPanel → Software → Select PHP Version (or "MultiPHP Manager").
Set the version to 8.2 or higher for the domain you will install on.
Open the Extensions tab and tick every extension listed above. Click Save.
In Options, raise: upload_max_filesize ≥ 64M, post_max_size ≥ 64M, memory_limit ≥ 256M, max_execution_time ≥ 300.

Step 2 — Create the database

cPanel → Databases → MySQL Databases.
Create a database (e.g. youracct_xsender) — note the full name including the youracct_ prefix cPanel adds.
Create a database user (e.g. youracct_xs) with a strong password.
Scroll to Add User to Database, attach the user to the database, grant ALL PRIVILEGES.

Step 3 — Upload & extract the ZIP

cPanel → File Manager → public_html (or your domain's docroot folder).
If public_html contains a default cPanel landing page, delete cgi-bin's siblings (index.html, default .htaccess) — do not delete cgi-bin itself.
Upload xsender-installer-vX.Y.zip.

Right-click the ZIP → Extract. Choose the same folder. After extraction your public_html should contain:

public_html/
├── assets/
├── src/
├── xsender-whatsapp-service/      ← optional, only if you will run WhatsApp Node
├── .htaccess
├── config.json
└── index.php

Delete the ZIP file to reclaim space.

Do NOT set your domain's document root to public_html/src/public/. XSender ships a pre-built index.php at the project root that handles the Laravel structure for you. Setting the doc root inside src/public will break asset URLs and the installer.

Step 4 — Set folder permissions

cPanel File Manager → select these folders → Permissions → 755:

src/storage and everything inside
src/bootstrap/cache
assets/

If files are owned by the wrong user (rare on cPanel), open Terminal (if enabled) and run chown -R $(whoami):$(whoami) public_html. Otherwise open a support ticket with your host.

Step 5 — Run the web installer

Open your browser at https://yourdomain/ (or https://app.yourcompany.com/).
You should land on the XSender Installer wizard. If you see a Laravel error page instead, jump to Troubleshooting.
Step 1 — Server Check. Every row must be green. Red rows tell you exactly which PHP extension or write permission is missing — fix it in cPanel (Step 1 or 4), refresh.
Step 2 — Purchase Code. Paste the Envato Purchase Code from CodeCanyon → Downloads.
Step 3 — Database. Enter the database name, user, password from Step 2. Hostname is almost always localhost on cPanel. Click Test Connection — if it fails, double-check the youracct_ prefix on both fields.
Step 4 — App Setup. Pick your site name, super-admin email + password.
Step 5 — Finish. The installer runs the migrations and writes .env. When done, sign in at https://yourdomain/admin/login.

Step 6 — Cron jobs (critical for campaigns)

Without a cron, scheduled campaigns and automation workflows will not fire. cPanel → Advanced → Cron Jobs:

Add a cron set to * * * * * (every minute):
```
cd /home/youracct/public_html && /usr/local/bin/php src/artisan schedule:run >> /dev/null 2>&1
```
Replace youracct with your cPanel username and /usr/local/bin/php with the path printed by cPanel's "PHP version" page (sometimes /opt/cpanel/ea-php82/root/usr/bin/php).

Optional: Add a second cron at */5 * * * * to keep the queue worker alive:

cd /home/youracct/public_html && /usr/local/bin/php src/artisan queue:work --stop-when-empty >> src/storage/logs/queue.log 2>&1

Step 7 — Force HTTPS

cPanel → Security → SSL/TLS Status. Confirm the domain has a green padlock (AutoSSL covers most shared hosts).
cPanel → Domains → toggle Force HTTPS Redirect on for the XSender domain.
Sign back into /admin/login and confirm everything loads under https://.

Updating XSender on cPanel later

When a new version ships:

From Admin Panel → System Update, click Check for Update. If your installation can write to its own folder, XSender will pull, extract, and run migrations automatically.
If the in-app update fails (some cPanel hosts disable PHP's exec), download the update ZIP from CodeCanyon and re-upload via File Manager, extracting over the existing files. The config.json migration list in the new ZIP will be picked up on the next request.
If the panel returns 500 after an update, open https://yourdomain/repair.php?token=xsender-repair — this ships with every release, clears the bootstrap cache + OPcache, then self-deletes.

Common cPanel issues

Symptom	Cause	Fix
Blank page / 500 at the installer	PHP extension missing, or wrong PHP version	cPanel → Select PHP Version → enable extensions; raise `memory_limit`.
"This site can't be reached"	Domain doc-root set inside `src/public`	Reset doc-root back to `public_html/` (or your addon-domain root).
404 on every page after install	Missing `.htaccess` or AllowOverride disabled	Re-upload the bundled `.htaccess`. If still 404, raise a ticket with your host to allow `.htaccess` overrides.
"SQLSTATE[HY000] [2002] Connection refused"	Wrong DB host	Use `localhost`, not `127.0.0.1`, on shared cPanel.
"Permission denied" writing to storage	Wrong folder permissions	Step 4 — chmod `755` on `src/storage` and `src/bootstrap/cache`.
Campaigns scheduled but never sending	Cron not running	Step 6 — confirm the per-minute cron exists; check `src/storage/logs/laravel.log`.
"Class Barryvdh\Debugbar\ServiceProvider not found"	Stale `bootstrap/cache` after an update	Visit `/repair.php?token=xsender-repair` to clear it.
"Object of class App\Enums could not be converted to string"	OPcache holding stale bytecode	`/repair.php?token=xsender-repair` calls `opcache_reset()`.

Known shared-hosting limitations

Long-running queues are unreliable — most cPanel hosts kill PHP processes after 60–120 s. The cron-based queue:work --stop-when-empty in Step 6 sidesteps this but processes fewer messages per minute than a Supervisor-managed worker on a VPS.
WhatsApp Node service (Node.js sidecar for WhatsApp Web sessions) requires a Node process running 24/7. cPanel Application Manager can host this if your provider enabled it; otherwise use a small VPS or container for the Node service and point it at your cPanel install. See Gateway → WhatsApp Node Service Setup.
Heavy bulk sends (50k+ recipients per hour) outrun shared-hosting CPU quotas. Consider a VPS once you exceed ~10k/hour.

Screenshots to add later

(For documentation maintainer.) Upload screenshots for these steps and replace the <img> tags:

cPanel → Select PHP Version page with 8.2 set
cPanel → MySQL Databases with database + user attached
File Manager showing public_html contents after extract
Installer Step 1 server check (all green)
Installer Step 3 database form filled in
Cron Jobs page with the per-minute schedule:run row