SFTP Deployment with Automatic Upload on Save in PhpStorm

1. When SFTP deployment still makes sense at all

For mironsoft.de the rule is that live changes get uploaded exclusively via FTP, because no automated deployment via a Docker setup or a CI pipeline exists. This exact situation is what PhpStorm's SFTP deployment feature is built for: smaller agency projects, shared hosting environments, or legacy systems where a full container or pipeline setup is not economically worthwhile.

The distinction from the main project matters here: while the actual Mironsoft Docker setup works with bin/magento and its wrapper scripts, SFTP deployment typically concerns separate smaller projects or exactly those cases where the local test environment does not automatically match the live state, and a manual but tool-assisted upload remains necessary.

2. Setting up an SFTP connection in PhpStorm

Under Settings > Build, Execution, Deployment > Deployment, a new server connection of type SFTP can be created via the plus icon. Alongside host, port, username, and authentication method, the root path field is decisive: it defines which directory on the server serves as the base for all relative paths, and should always be restricted as tightly as possible to the actual project directory.

On the Mappings tab, you then define which local folder corresponds to which remote directory. For multiple environments, such as a staging and a live account, it is advisable to create a separate, clearly named server connection for each environment, for instance 'Customer-X Staging' and 'Customer-X LIVE', instead of reusing a single connection by repeatedly switching credentials.

Settings > Build, Execution, Deployment > Deployment
  + New connection: SFTP
    Name: Customer-X LIVE
    Host: ftp.customer-x-hosting.com
    Port: 22
    Root path: /httpdocs

  Mappings tab:
    Local path: /home/mir/development/customer-x
    Deploy path: /

3. Enabling automatic upload on every save

Automatic upload is enabled via Tools > Deployment > Automatic Upload (always). With this option set, PhpStorm uploads every saved file to the configured server immediately, without needing a manual upload command. For quick fixes to a single CSS file or a PHP template on a shared hosting system, this saves noticeable time compared to a classic FTP client, since switching to a separate tool is no longer necessary.

This convenience is at the same time the biggest risk factor of the entire feature: without further safeguards, PhpStorm uploads every file saved in the mapped folder, regardless of whether it is a deliberate change, an accidental test edit, or an automatically generated file. This is exactly why automatic upload without accompanying exclusion rules is not recommended for production environments.

4. The concrete risks of uncontrolled auto-upload

The most common failure pattern: a developer opens a file to look something up, accidentally changes a line during a test experiment, saves reflexively with Ctrl+S, and the faulty version goes live immediately without any further confirmation. With auto-upload active, there is no intermediate step that catches this action, unlike a manual FTP upload where at least the deliberate act of uploading serves as a mental control point.

A second, subtler risk concerns generated or temporary files. If an IDE cache folder, a local .env with different credentials, or a composer.lock from a local test run gets uploaded by accident, it can change the live state in a way that does not show up immediately as an error but later leads to inconsistent behavior. Such files fundamentally belong on an exclusion list, regardless of whether auto-upload is active or not.

5. Configuring exclusion rules as a safeguard

The Excluded Paths section of a deployment configuration lets you exclude individual folders or file patterns from the upload. Sensible candidates are directories like .git, node_modules, var/log, generated, and pub/static, as well as configuration files like .env or local database dumps that should never end up on the live server. This list should be maintained per project, not copied generically from another project.

In addition to the exclusion list, PhpStorm also supports explicitly marking directories as 'Excluded' right in the project tree, via the context menu under Mark Directory As. Files in a folder marked this way are exempt from both indexing and deployment alike, which is particularly useful for large, generated directories that should never be edited manually anyway.

Deployment configuration > Excluded Paths:
  /.git
  /node_modules
  /var/log
  /var/cache
  /generated
  /pub/static
  /.env
  /*.sql

6. Making staging and live connections visually distinguishable

Because mixing up the staging and live connection is the most likely human error in this workflow, it is worth deliberately naming both server connections differently and, if the Deployment panel allows it, giving them different color markers. A name like 'WARNING LIVE Customer-X' is admittedly inelegant, but demonstrably reduces the number of misclicks compared to neutral names like 'Server 2'.

Additionally, automatic upload should only apply to the server connection actually set as active. Before working on a live project, it is worth deliberately checking Tools > Deployment to confirm which connection is marked as the default, since that exact connection is what automatic upload uses, not necessarily the most recently used one.

7. A safer middle ground: manual upload with preview

Instead of fully automatic upload on every save, PhpStorm offers Tools > Deployment > Upload to as a variant where the upload is triggered deliberately, per file or per marked directory. Combined with the Sync with Deployed to feature, a diff between the local and remote version can also be shown before anything is actually uploaded, which represents a sensible middle ground between convenience and safety for sensitive live environments.

For projects where accidental live changes would be especially costly, for instance during peak sales periods in the shop, it is advisable to disable automatic upload entirely and instead work deliberately with Upload to before every deployment. The time cost compared to the automatic mode is small, while the safety gain is considerable.

8. Regularly comparing local and remote state

Since SFTP deployment has no version control on the server, the live state can drift from the local state over time, for instance if a colleague made changes directly via a classic FTP client without using PhpStorm. Via Tools > Deployment > Browse Remote Host, the server contents can be viewed directly in a project-tree-like style and compared against the local state.

A regular comparison, especially before larger changes, prevents an automatic upload from accidentally overwriting changes that were made directly on the server outside of PhpStorm. This check does not replace real version control, but it substantially reduces the risk of conflicting states.

9. Practical checklist before enabling auto-upload

Before enabling Automatic Upload (always) on a new connection for the first time, the following sequence pays off: check root path and mappings, populate the exclusion list for .git, node_modules, .env, and generated directories, name the server connection unambiguously as staging or live, and perform a first test upload with a non-critical file to confirm the mapping is correct before production code is affected.

This checklist rarely takes longer than ten minutes on a new project, but it prevents exactly the mistakes that are most costly with SFTP deployment: accidentally overwriting live files through a wrongly mapped or unprotected connection.

10. Summary

11. FAQ: SFTP Auto-Upload in PhpStorm: Key Takeaways