Download the PHP package inja-online/ftp-deployer without Composer

Laravel FTP Deployer

Deploy Laravel apps to FTP-only cPanel/shared hosts without SSH.

This package uploads ZIP artifacts over FTP by default, skips unchanged vendor/ uploads with a remote manifest, then runs remote Laravel maintenance commands through a short-lived tokenized HTTP runner. Disable archive mode to fall back to recursive changed-file FTP uploads.

Use it when shared hosting gives you FTP/FTPS but no SSH, no remote Composer, and no safe way to run Laravel maintenance commands after upload.

What problem does this solve?

After multiple privilege escalation vulnerabilities, such as CVE-2021-4034 “PwnKit” and CVE-2021-3156 “Baron Samedit”, showed non-root to root escalation was possible, many hosts restricted or disabled SSH access for deployment. OpenSSH hardening guidance and CIS Benchmarks pushed the same direction.

At the same time, many hosts still lacked built-in deployment tooling, especially shared-hosting panels like DirectAdmin with limited automation APIs.

This gap created the need for a minimal, secure deployment path that does not rely on full SSH access.

GitHub: https://github.com/inja-online/ftp-deployer

Requirements

• PHP 8.1+
• Laravel 10, 11, 12, or 13
• PHP ftp extension
• PHP zip extension locally and on the remote host when archive mode is enabled
• FTP/FTPS access to your host
• Public HTTPS URL for the deployed app
• Local/CI build already completed for frontend assets

Install

From Packagist

From a local directory (Local Install)

Use this if you want to download the package code directly and put it in a local directory inside your Laravel application.

1. Download or clone this repository and place the files in a local folder within your Laravel project, e.g., packages/ftp-deployer.

2. Add a path repository pointing to your local folder in your Laravel application's composer.json:

(Note: Set "symlink": false if you want Composer to mirror/copy the package files instead of creating a symlink, which is useful in environments like Docker or shared hosts where symlinks might not be supported or desired).

3. Run the require command:

From custom GitHub repository

Use this when installing from a fork, private repo, or before Packagist release.

Add repository to your Laravel app composer.json:

Then require package:

For a fork/private repo, replace URL:

Then install from chosen branch:

Configure

Published config file:

Add deploy values to your local/CI .env:

Default remote layout:

If your domain root is FTP_DEPLOYER_FTP_ROOT=/public_html/laravelapp.inja.online, set FTP_DEPLOYER_FILESYSTEM_ROOT to the matching absolute PHP path, for example /home/<cpanel-user>/public_html/laravelapp.inja.online.

Remote .env must already exist and contain APP_KEY. This package does not upload your local .env.

Deploy

Build your app locally or in CI first:

For Bun/React/Vite projects, build with Bun instead:

No frontend? Skip Node/Bun entirely; if no package.json exists, frontend detection is skipped automatically.

Run deploy:

For automation or AI agents, use structured JSON output:

Default remote commands:

Change them in config/ftp-deployer.php under remote_commands:

For Bun/React builds, no-frontend apps, custom commands, queues, caches, and CI, see Extending & Overriding.

Connection Check

Before performing a deploy, you can verify your FTP connection settings (host, username, password, port, SSL, and passive mode) using:

For automation or AI agents, use structured JSON output:

Migration to Versioned Mode

If you have an existing profile configured in simple mode and want to upgrade it to versioned mode, you can use the interactive migration command:

Arguments & Options:

• profile (optional): The profile key to migrate (defaults to production).
• --write: Automatically updates/appends the required environment variables to your local .env file (if writable).
• --format=agent: Emits a structured JSON payload instead of interactive prompts, making it ideal for automation.

Remote Server Changes

Note that the migration command only updates your local configuration and does not touch your remote .env. To complete the transition:

1. Log into your FTP server.
2. Move your remote .env from {ftp_root}/{app_root}/.env to {ftp_root}/{shared_root}/.env.
3. Move your remote storage/ directory to {ftp_root}/{shared_root}/storage/.
4. Ensure the remote storage/ directory remains writable (chmod -R 775 or equivalent).
5. Run php artisan ftp-deploy <profile> to deploy the bootloader and link the new release layout.

Archive deploy mode

Archive mode is enabled by default. It uploads an app ZIP every deploy and a vendor ZIP only when composer.json or composer.lock changes. Temporary ZIPs use random filenames under .ftp-deployer/archives/, are protected with deny .htaccess files, and are deleted after extraction. SQLite files under database/ are excluded from app archives. ZIP passwords are not used in v1.

After extraction succeeds, stale files from the previous manifest are deleted, then the new manifest is saved before remote commands run. If extraction fails, the manifest and stale files are left unchanged. If your host times out during extraction or filesystem-root mapping is unavailable, set FTP_DEPLOYER_ARCHIVE_ENABLED=false to use recursive FTP uploads.

Simple mode extracts over live files and is best-effort. Use versioned mode for safer releases.

Versioned deploy mode

Simple mode uploads to stable app/public paths. Versioned mode uploads app code into release directories and updates a current-release pointer after success.

AI Agent Integration

This repository includes a pre-configured AI Agent Skill (ftp-deployer) to help autonomous coding assistants (such as Google Antigravity or Claude Code) run, configure, and troubleshoot deployments safely.

To install this skill to your agent globally:

For more details on integration, configuration custom roots, and sample agent prompts, see the AI Agent Integration docs.

Documentation

• Installation
• Configuration
• Cookbook & Examples
• Extending & Overriding
• CLI Commands
• Troubleshooting

Security

• Runner filename and token are random per deploy.
• Runner accepts JSON and returns JSON.
• Runner is deleted after deploy success or failure.
• .env is excluded by default.
• Use HTTPS for FTP_DEPLOYER_APP_URL.

Manual release workflow

Repository includes a manual GitHub Actions workflow for tagged package releases:

1. Open GitHub → Actions → manual-release.
2. Click Run workflow.
3. Enter version like v1.2.3.
4. Optionally mark as prerelease or add release notes.

The workflow validates Composer metadata, runs tests, PHPStan, lint dry-run, creates an annotated Git tag, then creates the GitHub release. Packagist can pick up the tag from GitHub.

Useful commands

License

AGPL-3.0-or-later. See LICENSE.md.