Download the PHP package awaisjameel/laravel-cpanel-hosting without Composer

Laravel cPanel Hosting

A robust, secure, and production-ready Laravel package that makes deploying Laravel applications on cPanel / shared hosting painless and professional.

Shared hosting doesn't give you SSH-driven CI/CD, so this package exposes a small set of authenticated HTTP endpoints that let a webhook (GitHub, GitLab, Bitbucket, or your own script) drive a deployment: pull the latest code (outside the scope of this package), then hit /deploy to sync the environment, run migrations, rebuild caches, relink storage, and flip maintenance mode — all guarded by a token, an IP allowlist, and optional rate limiting.

Features

• Secure deploy endpoints — token (X-Deploy-Token header or ?token=) or webhook signature (X-Hub-Signature-256 / X-Gitlab-Token) authentication, optional IP allowlist, optional in-memory rate limiting.
• Configurable deploy pipeline — a single GET /deploy runs an ordered list of steps (strings, artisan command arrays, or closures) and stops or continues on failure per your config.
• Granular endpoints — every pipeline step is also its own route, so you can call storage-link or migrate on their own.
• .env sync — copies a server-side env file (e.g. .env.server) over .env, with automatic timestamped backups and required-key validation (APP_KEY by default).
• Storage link fallback — tries symlink() first, and transparently falls back to a recursive directory copy (with correct file/directory permissions) on hosts where symlink() is disabled.
• Installer command — publishes config, root index.php passthrough and hardened .htaccess stubs for cPanel's public_html layout, and (interactively) writes your deploy token/prefix straight into .env.
• Dedicated deploy log channel — auto-registered if you haven't already defined one, so deploy activity doesn't get lost in laravel.log.
• Deploy lifecycle events — DeployStarting, DeployStepCompleted, DeployCompleted for hooking in notifications (Slack, email, etc.).
• MySQL legacy compatibility — automatically applies Schema::defaultStringLength() for older MySQL/MariaDB versions still common on shared hosting (utf8mb4 + short index key limits).

Requirements

• PHP 8.2+
• Laravel 11.x, 12.x, or 13.x

Installation

Run the installer:

This will:

1. Publish config/cpanel-hosting.php.
2. Install index.php and .htaccess at your project root (backing up any existing files first), so the app root can be pointed at your Laravel project directory directly instead of public/ on cPanel.
3. Append the package's env keys to .env.example if they're missing.
4. When run interactively, prompt you to generate/set a deploy token, choose a route prefix, and optionally enable deploy routes immediately — writing the answers straight into .env.

Installer options:

Non-interactively (e.g. in CI or a deploy script), the command skips the .env prompts and just publishes files:

Configuration

Publish the config manually if you skipped it during install:

Every option reads from an environment variable so config/cpanel-hosting.php rarely needs to be touched directly:

Endpoints

Once CPANEL_DEPLOY_ENABLED=true, routes are registered under CPANEL_DEPLOY_PREFIX (default deploy):

Every endpoint returns a consistent JSON shape:

Deploy routes deliberately bypass the session, CSRF, and default throttle middleware (see routes/deploy.php) since requests come from webhooks/CLI, not a browser session — auth is entirely handled by EnsureDeployTokenIsValid.

Authentication

Checked in this order by the deploy middleware:

1. IP allowlist (CPANEL_DEPLOY_ALLOWED_IPS) — if set, non-matching IPs get a 403 before auth is even checked.
2. Rate limit (if enabled) — exceeding it returns 429.
3. Webhook signature — X-Hub-Signature-256: sha256=... (HMAC-SHA256 of the raw request body, GitHub-style) or X-Gitlab-Token: <secret>, compared with hash_equals().
4. Deploy token — X-Deploy-Token: {token} header (preferred) or ?token={token} query string, compared with hash_equals().

If none of these pass, the route returns 403. If CPANEL_DEPLOY_ENABLED is false, every deploy route returns 404 rather than 403, so an unconfigured install doesn't leak the fact that the routes exist.

Customizing the pipeline

pipeline.default_steps accepts a mix of:

• Named steps (strings) — sync-env, maintenance-down, optimize-clear, migrate, migrate-fresh, cache, queue-restart, storage-link, maintenance-up, optimize.
• Arbitrary artisan commands — 'artisan:cache:clear' runs php artisan cache:clear, or use an array to pass parameters: ['command' => 'queue:work', 'parameters' => ['--once' => true]].
• Closures — for anything custom; must return bool or a ['success' => bool, 'message' => string, 'data' => array, 'errors' => array] shape.

Events

Listen for these to wire up notifications or auditing:

Facade

Root hosting layout (cPanel public_html)

cPanel-style shared hosting typically serves everything under public_html/ directly, but Laravel expects the web root to be public/. The installer's root stubs solve this without a symlink:

• index.php — a one-line passthrough (require __DIR__.'/public/index.php') so the app root is your project root.
• .htaccess — blocks direct access to sensitive files (.env, composer.json/.lock, phpunit.xml, artisan) and internal framework directories (app, bootstrap, config, database, resources, routes, storage, tests, vendor), rewrites /public/... requests away, and serves everything else from public/ — with baseline security headers (X-Frame-Options, X-Content-Type-Options, Referrer-Policy, a permissive Content-Security-Policy you should tighten per app).

Deploy your Laravel project as-is to public_html/ (or a subdirectory pointed at by your domain), run the installer once, and the app is servable without moving files around or fighting cPanel's document root.

Security Notes

• Keep CPANEL_DEPLOY_TOKEN secret and rotate it immediately if it's ever exposed (logs, error trackers, a public repo).
• Prefer the header token (X-Deploy-Token) over the query-string token — query strings tend to end up in access logs and browser history.
• Restrict with CPANEL_DEPLOY_ALLOWED_IPS whenever your CI/webhook provider publishes a stable IP range.
• Never expose deploy routes with APP_DEBUG=true in production — a failed step's stack trace should not be visible to the public internet.
• migrate-fresh is destructive — it drops every table. Only include it in your pipeline if you're certain you want that behavior on every deploy (most apps shouldn't).
• The built-in rate limiter is process-local, in-memory state (a static array), not a shared cache-backed limiter — it resets on every new PHP-FPM/CLI process and offers no protection across concurrent requests or multiple app servers. Treat it as a minor speed bump, not a defense against brute force; for real protection, pair the deploy token with CPANEL_DEPLOY_ALLOWED_IPS or a firewall rule at the host level.
• Webhook signatures beat static tokens where the provider supports them (GitHub/GitLab) — the payload is authenticated, not just a shared secret in a header.

Testing

Runs the Pest suite under tests/ (feature tests for deploy routes/middleware, unit tests for SyncEnvAction and StorageLinkAction) via Orchestra Testbench. Also available:

Changelog

See CHANGELOG.md for recent changes.

Contributing

Issues and pull requests are welcome at github.com/awaisjameel/laravel-cpanel-hosting.

License

The MIT License (MIT). See LICENSE for more information.