PhpStorm SFTP Deployment: An Architecture Note for Small PHP Teams

The Problem: Moving PHP Files Without a Pipeline

You maintain a PHP application on your workstation and need edited files to appear on a remote server. Building a CI/CD pipeline feels disproportionate when one person is making the changes. PhpStorm's built-in SFTP deployment is the smallest design that closes the gap: map a local project root to a remote document root, exclude what should not ship, and let the IDE transfer files on save. This note covers the minimal configuration, where the trust boundaries sit, and how to verify the result before relying on it.

Requirements for the Smallest Deployment Design

The design assumes a single local project root and a single remote document root. It requires SSH access to the target server and a decision about which files never leave the workstation. PhpStorm supports SFTP, FTPS, and mounted remote filesystems; for this note, SFTP is the baseline because it rides the existing SSH connection and needs no extra server daemon beyond the SSH service already running.

You do not need an external sync tool, a build step, or a shared staging area. You do need explicit path mappings and exclusion rules. Without exclusions, the IDE will transfer everything under the project root, including version-control metadata, local environment files, and dependency directories that may not belong on the server.

One Root, One Mapping: The Minimal Configuration

In the deployment settings, create an SFTP connection and set the local path to your project root. Set the remote path to the web server document root—the directory the web server serves files from. If the application lives in a subdirectory, define the web path so generated links resolve correctly.

Enable automatic upload only for explicit saves. The alternative—uploading on every change, including files modified by external tools—widens the blast radius of a mistaken keystroke. Labels and defaults vary by IDE version, so verify the setting after upgrades rather than assuming it persisted.

Exclusions are the most important part of the configuration. Add patterns for:

• .git/ and other version-control metadata
• .env and .env.* files
• vendor/ and node_modules/ if dependencies are installed on the server
• Server-writable paths such as storage/logs/, storage/cache/, or var/cache/

These exclusions prevent transfer; they do not delete remote files. A file excluded locally remains on the server if it already exists there.

Trust Boundaries: What the IDE Can Reach

When you configure SFTP deployment, the IDE process becomes a deployment agent. It gains read access to your local source tree and write access to the remote web root. SSH credentials are stored in the PhpStorm password safe, which encrypts them on disk and ties access to your workstation login. The practical boundary is this: anyone who can unlock your workstation can deploy, and anyone who can read your project's .idea/ directory may see connection metadata if it is not ignored by version control.

Do not commit deployment configuration to a shared repository unless you have verified that credentials are not stored in plain text. Hostnames, usernames, and path mappings are often stored in readable XML even when passwords are protected.

Operational Checks Before You Rely on It

Run these checks in a scratch project before touching production.

Check	Method	Expected result
Save-only trigger	Create and save a scratch file	File appears on the server; merely opening a file does not trigger upload
Path mapping	Manually upload one changed file	Remote path equals document root plus the same relative path as local
Exclusion coverage	Compare exclusions against .gitignore	Secrets, vendor directories, and VCS metadata are absent from transfers
Ownership and permissions	Inspect remote files after upload	Web server user (commonly www-data or nginx) can read the files

For the permission check, run ls -l in the remote document root over SSH. The IDE typically preserves local permissions or applies the SFTP server's umask—a default permission mask applied to new files. Verify the outcome rather than assuming it matches your local setup.

Failure Modes and What They Cost

Partial uploads. SFTP transfers are not atomic. If the connection drops mid-transfer, the remote file may be truncated, or a new file may exist while an old one remains. The IDE does not roll back. A broken partial state is the normal failure mode of an interrupted save-triggered upload.

Server-generated file overwrites. If your application writes logs, cache, or compiled templates under the document root, an automatic upload can overwrite those files with local versions. This causes runtime errors or silent data loss. Exclude server-writable paths to reduce the risk.

Credential exposure. If the .idea/ folder is committed to version control, deployment connection details may leak. The password safe protects the secret, not the topology.

Exclusion drift. The IDE exclusion list is manual. When a developer adds a new secrets file locally and forgets to update the exclusions, the next save pushes it to the server. This is the most common silent failure in small-team IDE deployment.

When to Abandon IDE Deployment for CI/CD

IDE-based deployment is a convenience for a single operator, not a release management system. Change the design when any of these conditions appear:

• Two or more developers edit the same files and need coordinated releases.
• Compliance requires an auditable, reproducible deploy artifact.
• The application needs atomic deploys, database migrations run as a separate step, or instant rollback.
• The server is reachable only from a CI runner, not from developer workstations.

In those cases, a CI/CD pipeline that builds an artifact and deploys it through a controlled runner is the correct architecture. Until then, a single mapped root with disciplined exclusions is the smallest design that works.

Practical Verification

Before trusting the setup, upload one known file. Check its remote timestamp and content hash. Then modify a file that should be excluded and save it. Confirm the remote server does not receive the change. If either check fails, the path mappings or exclusions are wrong. Fix them before the next save.