Deployment and Remote Hosts in PhpStorm: When Useful, When Not

1. What PhpStorm Deployment really is, and what it isn't

The term "deployment" in PhpStorm is misleading when compared to modern CI/CD pipelines. PhpStorm deployment is, at its core, a file synchronization tool: it transfers local files to a remote server via SFTP, FTP, or FTPS. It has no rollback mechanism, no deployment hooks, no zero-downtime deployment, and no health checks. What it can do: automatically upload a local file to the server on save, sync directories manually, and show differences between local and remote files.

That makes it valuable for certain scenarios: when a developer is working on a remote server without a local Docker setup, when a staging server needs a quick update with a corrected file, or when a legacy project doesn't yet have Git-based deployment. For production servers running Magento 2 or other complex CMS systems that require cache clearing, compiler runs, and database migrations after every deployment, PhpStorm deployment alone is not enough, it is missing the orchestration step after the upload.

2. Setting up a remote host and deployment profile

Configuration starts under Settings → Build, Execution, Deployment → Deployment → + (Add). As the type, choose SFTP for password-based or key-based SSH connections. On the Connection tab, enter the hostname, port (22 for SSH), username, and the path to the private SSH key. PhpStorm supports both RSA and Ed25519 keys and reads the SSH configuration from ~/.ssh/config, which means SSH aliases already defined there can be used directly, just enter the alias name as the hostname.

For password authentication, PhpStorm can store the password in the system keychain so it doesn't need to be re-entered on every upload. With key-based authentication using a passphrase, PhpStorm integrates with the SSH agent if one is running. The Root Path field on the Connection tab defines the base path on the server that serves as the starting point for all relative paths in the deployment maps. For typical web server setups this is usually /var/www/html or the vhost's DocumentRoot.

# ~/.ssh/config (PhpStorm reads this automatically)
# Use Host alias directly as "Host" in PhpStorm deployment settings

Host staging-mironsoft
  HostName staging.mironsoft.de
  User deploy
  Port 22
  IdentityFile ~/.ssh/id_ed25519_deploy
  ServerAliveInterval 60
  ServerAliveCountMax 3
  AddKeysToAgent yes

Host prod-mironsoft
  HostName mironsoft.de
  User deploy
  Port 2222
  IdentityFile ~/.ssh/id_ed25519_deploy
  ForwardAgent no
  # Production: never use automatic upload from PhpStorm
  # Always deploy via CI/CD pipeline (GitHub Actions / GitLab CI)

3. Deployment maps: mapping local paths to remote paths

On the Mappings tab of the deployment profile, you define which local directories map to which remote directories. A mapping rule consists of three fields: Local path, Deployment path (relative to the root path), and Web path (for the browser). The web path field matters for the "Open in Browser" feature: PhpStorm uses it to compute the URL of the currently open file and can open it directly in the browser.

For Magento 2 projects that use a src/ subfolder as the Magento root, the mapping typically looks like this: Local path /home/mir/development/mironsoft/src → Deployment path /var/www/html. Multiple mappings within a profile allow different sync rules for different directories. That way you can sync the app/code/ directory while explicitly excluding vendor/ and var/, which saves upload time and prevents vendor files from being accidentally overwritten.

4. Manual, on save, or on explicit save

PhpStorm offers three upload modes: manual (Upload to from the context menu), Upload changed files automatically to the default server (on save), and Always upload. On-save mode is the most convenient, but also the most dangerous for shared servers: every file save immediately triggers an upload, even if the file isn't error-free yet. A half-finished refactor that compiles locally but produces a syntax error remotely lands on the server instantly and can break the application.

The safer alternative is manual upload or Upload on Explicit Save, where the upload is only triggered by an explicit Ctrl+Shift+S instead of the regular Ctrl+S. For staging servers where a single developer works alone and wants to test changes quickly, on save is acceptable. For any server where multiple developers work or where live traffic runs, manual upload is the only defensible option. PhpStorm shows upload progress and any errors in the status area at the top right.

5. Exclude rules: what must never be uploaded

Excluded Paths in the deployment settings are one of the most important safety features. Under Settings → Deployment → Options → Excluded paths, you define paths that are excluded from synchronization, either on both sides or only locally. For a Magento 2 project, at minimum the following paths should be excluded: vendor/ (managed remotely by Composer), var/ (cache, logs, session files), pub/static/ (static content should be deployed, not synced) and any .env files that contain production configuration.

Another critical exclusion: the .git/ directory should never be uploaded to the server. PhpStorm doesn't exclude it by default, so it must be added to Excluded Paths explicitly. Deploying .git/ to a web server is a security risk because the source code becomes accessible via public URLs if the web server doesn't explicitly block the directory. Exclude rules support wildcards, so you can define patterns like *.log or *cache*.

<?php
// PhpStorm Deployment: Excluded Paths for Magento 2
// Settings → Build, Execution, Deployment → Deployment → [Profile] → Excluded Paths

/*
Local paths that must NEVER be uploaded:

Deployment Path (relative to root):    Reason
/vendor/                               Managed by Composer on server
/var/                                  Cache, logs, sessions, server-specific
/pub/static/                           Deploy via setup:static-content:deploy
/.git/                                 Security: source code exposure
/.env                                  Server-specific environment config
/env/                                  Docker environment files
/node_modules/                         Build artifacts, server not needed
/pub/media/ (optional)                 Large binary files, use CDN sync instead

Recommended: always use SSH key auth, never password for deployment profiles.
Recommended: mark production server profile as "disabled" to prevent accidents.
Set default server to Staging only, never Production.
*/

// After uploading PHP files to Magento staging, always run:
// bin/magento cache:flush
// bin/magento setup:di:compile (if DI changes)
// The PhpStorm deployment does NOT handle post-deploy steps automatically.

6. Remote File Browser: editing files directly on the server

The Remote File Browser (View → Tool Windows → Remote Host) shows the directory structure of the configured remote host directly inside PhpStorm. You can open files from the server, edit them locally, and save them back with a click. That's useful for quick fixes on staging servers without having a full local copy of the project, or for reading remote log files.

An important limitation: when you open a file from the Remote File Browser and edit it locally, that local temporary copy isn't linked to the Git repository. Changes saved only remotely are lost from the repository on the next deployment. Anyone editing files through the Remote File Browser must make sure those changes also make it into the local repository. For this workflow it's better to edit the file locally and upload it through the deployment profile rather than editing directly in the remote browser.

7. Risks of automatic upload, and how to mitigate them

Automatic Upload is convenient, and it carries three serious risks at the same time. First, a syntactically broken PHP file can be uploaded to the server before the developer notices the error, which for Magento 2 results in a completely broken storefront. Second, a developer can unintentionally upload a configuration file containing local development data that overwrites production settings. Third, simultaneous uploads from multiple developers to the same server are a recipe for inconsistent states.

The most important mitigation steps: (1) enable Automatic Upload only for staging servers, never for production. (2) Never use PhpStorm deployment as the only deployment path for production. (3) Fully configure Excluded Paths before activating the profile. (4) Check synchronization regularly: Tools → Deployment → Compare with Deployed Version shows differences between local and remote and reveals when someone has edited directly on the server.

8. When CI/CD and Git deployment are the better choice

Git-based deployments through CI/CD pipelines are the better choice in every scenario where more than one person works on the project, where production servers are affected, or where deployment involves more steps than a plain file upload. A GitHub Actions pipeline can automatically run Composer install, static content deploy, DI compile, and cache flush after a push to the main branch, without manual intervention and with a complete audit trail. That's not just safer, it's also more reproducible.

For Magento 2, the deployment process is complex enough that it should always run through a pipeline or a deploy script: CSS build, static content deploy with the correct locales and themes, DI compile, cache flush, in exactly that order. PhpStorm deployment doesn't handle any of these steps. In practice, PhpStorm deployment is most useful for PHP projects without a compilation step, classic Laravel or Symfony apps without an asset pipeline, where a plain file upload is actually sufficient.

9. Deployment methods compared

Choosing a deployment path depends on project size, team, and server infrastructure. A direct comparison helps with the decision.

For solo developers working on a simple PHP project without compilation steps on a staging server, PhpStorm SFTP is a fast and practical solution. Once the project grows, a team joins, or the production environment requires compilation steps, switching to a CI/CD pipeline becomes necessary. The good news: both methods can coexist. PhpStorm SFTP for quick staging tests, CI/CD pipeline for clean production deployments.

10. Summary

PhpStorm deployment isn't a complete deployment mechanism, it's a file synchronization tool over SFTP. For simple PHP projects without compilation steps and for solo developers on staging servers, it's a convenient and fast solution. For Magento 2, teams, and production servers, it falls short because it doesn't cover post-deploy steps, rollback, or an audit trail. Excluded Paths aren't optional configuration, they're a safety requirement: vendor/, var/, pub/static/, .git/, and environment files must always be excluded.

The best strategy for Magento 2 projects: enable PhpStorm SFTP for quick staging tests (manual upload, never Automatic Upload), and run a CI/CD pipeline in parallel for all production deployments. This way you get the strengths of both approaches without the risks of automatic upload on production servers. The key is that the team clearly understands which path applies to which environment, and that production deployments are never triggered by an IDE button.

11. FAQ: Deployment and Remote Hosts in PhpStorm

PhpStorm deployment and remote hosts are valuable tools for specific scenarios, but they don't replace a complete CI/CD pipeline. Use these features where quick testing on staging systems matters more than full automation.

The right combination of local deployment for fast iteration and a complete CI/CD pipeline for production systems is the key to an efficient and secure deployment workflow in PHP projects.