PhpStorm 2019.1 Help

Vagrant

PhpStorm integrates with Vagrant helping you create reproducible development environments defined by Vagrantfile configuration files. You can create and delete virtual boxes, initialize Vagrant boxes, configure remote interpreters by reading settings from the Vagrant configuration files, and execute other Vagrant commands without leaving the IDE. You can also choose among several virtual boxes when performing the vagrant up command (Multiple Vagrant configuration).

In the context of PhpStorm, the following terms are used to denote Vagrant-specific notions:

  • A Vagrant box in the PhpStorm user interface or Vagrant base box in the current documentation is a box in the native Vagrant terminology. It denotes a pure image, a skeleton, on the base of which a specific environment is customized, provisioned, and deployed on your machine.

  • An instance is a virtual machine. In other words, it is a specific environment customized, provisioned, and deployed on your machine on the base of a Vagrant base box and in accordance with a Vagrantfile. In other similar products and documentation, an instance can be referred to as virtual machine.

  • An instance folder is the folder where the relevant Vagrantfile is stored after initialization and where PhpStorm will look for it. By default, it is the project root folder.

Preparing to work with Vagrant

Before you start, ensure that the following steps and checks are done:

  1. Make sure that you have Vagrant and Oracle's VirtualBox installed on your computer and the parent folders of their executable files are added to the system PATH variable. If you followed the standard installation procedure, these folders are added automatically.

  2. Make sure that the parent folders of the following executable files are added to the system PATH variable:

    • vagrant.bat or vagrant from your Vagrant installation. This should be done automatically by the Vagrant installer.

    • VBoxManage.exe or VBoxManage from your Oracle's VirtualBox installation.

In the Settings/Preferences dialog (Ctrl+Alt+S), verify or modify the Vagrant settings:

  1. Click Vagrant under Tools. The Vagrant page page opens.

  2. Specify the Vagrant executable file. Because the parent folder of the executable file has been already added to the system PATH variable, type just the name of the executable.

  3. In the Instance Folder field, specify the fully qualified path to the directory where the Vagrantfile is initialized and stored. A Vagrantfile is a configuration file that defines the instance (virtual machine) you need. The file contains the virtual IP address, port mappings, and the memory size to assign. The file can specify which folders are shared and which third-party software should be installed. According to the Vagrantfile your instance (virtual machine) is configured, provisioned against the relevant Vagrant base box, and deployed on your computer. A Vagrantfile is created through the vagrant init command.

    When creation of an instance (virtual machine) is invoked either through the vagrant up command or through the Tools | Vagrant | Up menu option, PhpStorm looks for the Vagrantfile in the directory specified in the Instance folder field. For more information, see http://docs.vagrantup.com/v2/vagrantfile/.

    You can create a Vagrantfile in any directory and appoint it as instance folder. If the field is empty, PhpStorm will treat the project root as the instance folder and look for a Vagrantfile in it.

  4. In the Vagrant Boxes area, configure a list of the predefined Vagrant base boxes available in PhpStorm. Each item presents a Vagrant base box on which Vagrant configures and launches its instances (virtual machines). The entries of this list correspond to the output of the command vagrant box list.

    • To download a new base box, click the Add button Add the base box. In the dialog that opens, specify the URL address to access the base box and the name to refer to it in PhpStorm. By default, PhpStorm suggests the URL to the lucid32 box.

      This command corresponds to vagrant box add <name> <URL>. As a result, the specified base box is downloaded to your machine.

    • To remove a base box, select it in the list and click the Remove button Remove the base box. The base box and the nested files are physically deleted from the disk. This command corresponds to vagrant box remove <name>.

Initializing the Vagrantfile

A Vagrantfile is a configuration file that defines the instance (virtual machine) you need. The file contains the virtual IP address, port mappings, and the memory size to assign. The file can specify which folders are shared and which third-party software should be installed. According to the Vagrantfile your instance (virtual machine) is configured, provisioned against the relevant Vagrant base box, and deployed on your computer. A Vagrantfile is created through the vagrant init command.

You can initialize the Vagrantfile in any folder, just keep in mind that this folder should be specified as the instance folder on the Vagrant page of the Settings Preferences dialog. Otherwise PhpStorm will be unable to find the relevant Vagrantfile during the instance (virtual machine) creation.

To initialize the Vagrantfile, do one of the following:

Initialize the Vagrantfile

  1. To have the Vagrantfile created in the project root, choose Tools | Vagrant | Init on Project Root on the main menu and select the target project root from the list that opens. The output of the init command is displayed in the Run tool window.

  2. To have the Vagrantfile created in a specific folder, open the embedded Terminal (Alt+F12), and then type the following commands:

    cd <directory to initialize the Vagrantfile in> vagrant init <base box name> <base box url>

After the Vagrantfile is created, you can preview it in the Editor: it contains the detailed list of the available configuration options. Alter or add configuration settings, if needed. Note that code completion is enabled for Vagrantfile.

The initial view of the newly created Vagrantfile

Once the Vagrantfile initialization is successfully completed, you are ready to import the base box, provision and deploy it according to the Vagrantfile, thus creating your own instance (virtual machine).

Creating and launching an instance (virtual machine)

Creating an instance (virtual machine) means importing and provisioning a base box according to the Vagrantfile located in the instance folder.

Create an instance, follow these steps:

  1. Do one of the following:

    • To have the instance created in the project root, go to Tools | Vagrant | Up.

    • To create an instance in a specific folder, open the embedded Terminal (Alt+F12) and then type the following commands:

      cd <instance folder> vagrant up

  2. Select the desired virtual machine configuration from the suggestion list:

    Select VM configuration

Stopping, suspending, resuming, reloading, and destroying an instance (virtual machine)

Reload an instance

  • If you have made some changes to the Vagrantfile and want a running virtual machine updated in accordance to them, choose Tools | Vagrant | Reload on the main menu or run the following command in the embedded Terminal:

    vagrant reload
    For details, see http://docs.vagrantup.com/v2/cli/reload.html.

Suspend an instance

  • To temporary stop the operating system on a running virtual machine (guest machine) and save the exact state of the environment as it is at this moment so it can be resumed exactly from this point, choose Tools | Vagrant | Suspend on the main menu or run the following command in the embedded Terminal:

    vagrant suspend
    For details, see http://docs.vagrantup.com/v2/cli/suspend.html.

Resume an instance

  • To resume a previously suspended operating system on a virtual machine (guest machine) and have it run from the state saved at the suspension moment, choose Tools | Vagrant | Resume on the main menu or run the following command in the embedded Terminal:

    vagrant resume
    For details, see http://docs.vagrantup.com/v2/cli/resume.html.

Shut an instance down

  • To shut down the operating system on a virtual machine (guest machine), choose Tools | Vagrant | Halt on the main menu or run the following command in the embedded Terminal:

    vagrant halt
    For details, see http://docs.vagrantup.com/v2/cli/halt.html.

  • To shut down the operating system on a virtual machine (guest machine), stop the virtual machine itself, and remove the resources provisioned on it during the creation (vagrant up), choose Tools | Vagrant | Destroy on the main menu or run the following command in the embedded Terminal:

    vagrant destroy
    For details, see http://docs.vagrantup.com/v2/cli/destroy.html.

Last modified: 26 July 2019
DockerCreating and Removing Vagrant Boxes

See Also

Procedures:

Reference:

External Links:

Tutorials and Examples: