Skip to end of metadata
Go to start of metadata

Deployments in PhpStorm are a powerful way to transfer files between the project and the deployment server. But what if something goes wrong? It's good to first make sure the deployment tutorials are followed, but if that does not work we may need some troubleshooting. In this tutorial, we will explore some common issues and their solutions as well as some other interesting scenarios. Consider it a FAQ for PhpStorm deployments.

General troubleshooting

How to collect deployment logs and provide them to our support engineers?

If the answer to your deployment issue is not on this page, you can contact our support engineers. They may need you to capture logs of the operation at hand. If that is the case, please follow instructions to collect deployment logs.

Show instructions here...

If you have PhpStorm 7.1.3 or above:

1. Open Help | Configure Debug Log Settings

2. Add the following lines:

  • Problems with PHP debugging: com.jetbrains.php.debug
  • Problems with deployment/synchronization: com.jetbrains.plugins.webDeployment

3. Click OK
4. Reproduce the problem.
5. Log files are to be found at:

  • from PhpStorm (since 2.1 EAP):
    • Windows\Linux: Help | Show Log in Explorer
    • Mac OS X: Help | Show Log in Finder
  • manually (~ stands for user home directory):
    • Windows and Linux: ~\.WebIde70\system\log
    • Mac OS X: ~/Library/Logs/WebIde70

The latest log file is named idea.log; older files names end with a number, i.e. idea.log.1, idea.log.2 etc. In most cases you need only the latest one.

6. Attach the log file(s) to the issue or forum thread.

If you have PhpStorm 7.0 or below:

1. Close PhpStorm application.
2. Open file <PhpStorm installation>/bin/log.xml with the text editor
3. Scroll to the bottom and add the following lines before the <root> tag:

where category_name is:

  • Problems with PHP debugging: com.jetbrains.php.debug
  • Problems with deployment/synchronization: com.jetbrains.plugins.webDeployment

4. Start PhpStorm and reproduce the problem.

5. Log files are to be found at:

  • from PhpStorm (since 2.1 EAP):
    • Windows\Linux: Help | Show Log in Explorer
    • Mac OS X: Help | Show Log in Finder
  • manually (~ stands for user home directory):
    • Windows and Linux: ~\.WebIde70\system\log
    • Mac OS X: ~/Library/Logs/WebIde70

The latest log file is named idea.log; older files names end with a number, i.e. idea.log.1, idea.log.2 etc. In most cases you need only the latest one.

6. Attach the log file(s) to the issue or forum thread.

Deployment is slow or fails

Deployment can be a resource-intensive operation, especially if a project or a deployment server contains lots of directories and files. The following configuration options should speed up deployment:

  • Exclude directories that are not needed from deployment (e.g. images). This can be done from the deployment server settings under Excluded Paths.
  • Under Project Settings | Deployment | Options, uncheck Overwrite up-to-date files to avoid uploading files that don't have to be uploaded.
  • Depending on the server, switching between active and passive mode in the advanced FTP settings may help. This can be done from Project Settings | Deployment, opening Advanced Settings for the server and toggling Passive mode.
  • Limit number of concurrent FTP connections. To do this, select Project Settings | Deployment, open Advanced Settings for the server and toggle the mode Limit concurrent connections, setting the number of connections (usually 3-5 concurrent connections is OK for any server if you experience problems with a greater number of connections).

Download/upload actions are not available

Download/upload actions may not be available because of a missing mapping. If a file or folder that you want to download is not configured in any mapping, PhpStorm will not download it. Mappings can be configured as described in the Deploying PHP applications with PhpStorm tutorial; alternatively, select Project Settings | Deployment, open the Mappings tab for the server and add the paths.

For some actions, a default deployment server has to be specified under Project Settings | Deployment.

Why are some folders not being deployed?

A common cause of folders not being deployed is when they are explicitly excluded. To solve this, use the context menu on the given folder in the Remote Host tool window and click Remove Path From Excluded. Once this is done, the folder will be deployed.

This can also be configured from Project Settings | Deployment, opening the Excluded Paths tab for the server and removing the excluded path. Please note that both source and target folders should be checked.

Folders may also be excluded by name in Project Settings | Deployment | Options under Exclude items by name.

The File | Synchronize menu does not synchronize files with the deployment server

The File | Synchronize is not related to deployments: it synchronizes the files with the file system in case external changes were not detected automatically by the IDE. Synchronizing files between the project and the deployment server is described in the Sync changes and automatic upload to a deployment server in PhpStorm tutorial.

Can I have different deployment configurations for different projects? Do I have to enter connection details for every project?

Deployment Servers are configured at the IDE level, even if they are displayed under Project Settings | Deployment. Because of this, they are available for all projects and shared between them. Note that only the name and connection details (the Connection tab) are shared between projects---mappings and excluded paths are project-specific and have to be configured separately.

Using this approach, connection details have to be entered just once, while mappings and excluded paths can be configured per-project, sharing the connection details.

Of course, this is only useful when projects share the same deployment server and use the same connection settings. If connection settings are different per project, they have to be configured for every project.

File | Default Settings | Deployment does not allow me to configure mappings

The File | Default Settings | Deployment is used to configure defaults for future projects and does not affect currently opened projects. To configure those, use the File | Settings menu instead.

Is there a way to have different deployment settings on different subfolders within the same folder? Can a local folder be deployed to multiple locations?

There are a couple of things to note about uploading folders and configuring mappings:

  1. You can specify mappings for specific folders to different paths on the deployment server. This can be configured from Project Settings | Deployment, opening the Mappings tab for the server.
  2. You can exclude specific folders and files from being uploaded/downloaded. This can be configured from Project Settings | Deployment, opening the Excluded Paths tab for the server.
  3. You cannot upload the same folder (or subfolders) to different sites at once. A separate deployment configuration has to be created for each of them and uploaded to each site one by one.

If this is what you want to do, we recommend automating the process with a capable tool. For example, Phing has an FTP task which can be used from PhpStorm.

Within PhpStorm, you can use the Sync with Deployed... menu and select from available deployment servers for every upload.

Can I assign a keyboard shortcut to the Sync With Deployed to My Server menu item?

It is not possible to assign a keyboard shortcut directly to the Sync With Deployed to <server name> menu, only to the generic Sync with Deployed to... action, which will show a pop-up with the list of configured servers. This can be done from through IDE Settings | Keymap.

If you do wish to assign a keyboard shortcut to a specific deployment server, it is possible to record a Macro and assign a shortcut to it instead:

  1. Select Edit | Macros | Start Macro Recording and start recording a Macro.
  2. Select Tools | Deployment | Sync With Deployed to <server name> and close the sync window.
  3. Stop recording the Macro from the menu Edit | Macros | Stop Macro Recording.
  4. Set the Macro name, for example Sync with <server name>
  5. Open IDE Settings | Keymap and find the Macros node. Use the context menu on the new sync Macro that was just recorded and Add keyboard shortcut.

How do I deploy a database using PhpStorm?

There are a couple of ways to deploy a database using PhpStorm:

Can I run a script or executable on my files before the upload occurs?

Things like minifying CSS, optimizing images, encoding PHP files using IonCube and so on are actions that you may want to execute before an upload happens. The best approach to do this is run them not when the upload is started, but when the files are changed, by using File Watchers in PhpStorm. When the time comes to upload them to a deployment server, simply upload the processed files instead.

Note that the Upload external changes option must be enabled under Project Settings | Deployment | Options for this to work.

Sometimes files are not autouploaded

By default, only files updated in the editor will be autouploaded. To enable autoupload for files changed by external processes (VCS, transpilers, etc.), select the Upload external changes check box under Project Settings | Deployment | Options.

FTP troubleshooting

FTP issue: Invalid descendent file name "http:"

When a deployment server has been configured or when using the Test Connection button in the project settings, an error Invalid descendent file name "http:" is shown. Note that all file names with a colon (":") in the name will be considered invalid.

This can happen if a file containing "http:" exists in the project. The library that PhpStorm uses to connect to FTP (Apache Commons VFS) cannot read the contents of a folder containing such file, and thus causes the operation to fail. The only solution to this issue is to remove the file containing "http:" from the project.

PhpStorm seems to connect to the server but can't list files or perform upload

This may be because the deployment server requires a so-called passive FTP connection. To set this mode, select Project Settings | Deployment, open Advanced Settings for the server and toggle Passive mode.

Limiting the number of concurrent FTP connections may also help in this situation. To do this, select Project Settings | Deployment, open Advanced Settings for the server and toggle Limit concurrent connections mode setting the number of connections (usually 3-5 concurrent connections is OK for any server if you experience problems with a higher number of connections).

Deploy files when changing branches using Git checkout

There are a couple of ways to go about deploying files when switching between branches using Git checkout.

  • One way is to configure deployments to always upload files and external changes. To do this, select Project Settings | Deployment | Options, set Upload changed files to the default server to Always and select the Upload external changes check box. Note that this will upload all files to the server when switching branches.
  • Another way is to use git-ftp. It performs minimal uploads and is also able to mirror file and directory removals.

Known issues

It takes time to reconnect on every sync operation. Is there an option not to break the existing connection to the deployment server?

Currently this is not supported. There is an issue with workarounds described in our issue tracker.

Is it possible to open or download directly from FTP without specifying mappings?

No. As described earlier in this tutorial, mappings are currently required to be able to download files and folders from the deployment server. Check this issue for more information.

Note that using drag-and-drop from FTP to the local project will work as it does not require a mapping to be present.

Is rsync supported to synchronize files and folders with a deployment server?

No. If you feel this should be part of PhpStorm please upvote this issue.

Can I run an action pre- and post-deployment?

This is currently not possible. Please vote for this issue if you want to see it supported in the future.

Labels:
None
Enter labels to add to this page:
Please wait 
Looking for a label? Just start typing.