Vagrant: Working with Reproducible Development Environments
In this section:
Before you start working with Vagrant, make sure that the Vagrant plugin is enabled. The plugin is bundled with PhpStorm and is activated by default. If the plugin is not activated, enable it on the Plugins page of the Settings / Preferences Dialog as described in Enabling and Disabling Plugins.
Besides that, make sure that the following prerequisites are met (outside of PhpStorm):
- Oracle's VirtualBox is installed on your computer.
- Vagrant is installed on your computer, and all the necessary infrastructure is created.
- The parent folders of the following executable files are added to the system PATH variable:
- The required virtual boxes are created.
Integration with Vagrant helps you create reproducible development environments defined by VagrantFile configuration files. To have the same environment set up on the machines of all the team members you only need to put the VagrantFile under your team version control. Any team member can set up the required environment by running the
vagrant up command with the relevant VagrantFile. Vagrant support in PhpStorm is provided through the Vagrant plugin that comes bundled with PhpStorm .
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.
Once the Vagrant plugin is enabled, the following changes are made to the PhpStorm UI:
- A Vagrant page is added to the Settings dialog.
- A Vagrant node is added to the menu. The node contains the following commands that correspond to the standard Vagrant actions:
Vagrant support in PhpStorm features:
- capability to create new virtual boxes, and delete the unnecessary ones.
- capability to initialize Vagrant boxes, and execute other Vagrant commands without leaving the IDE.
- Multiple Vagrant configuration: when performing the vagrant up command, you are suggested to select the desired virtual box.
Preparing to work with Vagrant
- Open the Settings / Preferences Dialog by pressing Ctrl+Alt+S or by choosing for Windows and Linux or for macOS, and click Vagrant under Tools. The Vagrant page opens.
- 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.
- In the Instance Folder field, specify the fully qualified path to the directory where the
VagrantFileis initialized and stored. A
VagrantFileis 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
VagrantFileyour instance (virtual machine) is configured, provisioned against the relevant Vagrant base box, and deployed on your computer. A
VagrantFileis created through the
When creation of an instance (virtual machine) is invoked either through the
vagrant upcommand or through the menu option, PhpStorm looks for the
VagrantFilein the directory specified in the Instance folder field. For more information, see http://docs.vagrantup.com/v2/vagrantfile/.
- 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 . In the dialog box 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.
- To remove a base box, select it in the list and click the Remove button . The base box and the nested files are physically deleted from the disk. This command corresponds to
vagrant box remove <name>.
Initializing the Vagrantfile
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 dialog box. Otherwise PhpStorm will be unable to find the relevant VagrantFile during the instance (virtual machine) creation.
To initialize the Vagrantfile
- To have the Vagrantfile created in the project root, choose on the main menu and select the target project root from the pop-up list that opens. The output of the
initcommand is displayed in the Run tool window.
- To have the Vagrantfile created in a specific folder, launch the embedded Terminal ( or by hovering your mouse pointer over in the lower left corner of PhpStorm and choosing Terminal from the menu and then type the following commands at the prompt:
cd <directory to initialize the VagrantFile in>vagrant init <base box name> <base box url>
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)
To create an instance, follow these steps:
- Do one of the following:
- Select the desired virtual machine configuration from the suggestion list:
Stopping, suspending, resuming, reloading, and destroying an instance (virtual machine)
To reload an instance
- If you have made some changes to the VagrantFile and want a running virtual machine updated in accordance to them, choose on the main menu or run the following command in the embedded Terminal: For details, see http://docs.vagrantup.com/v2/cli/reload.html.
To 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 on the main menu or run the following command in the embedded Terminal: For details, see http://docs.vagrantup.com/v2/cli/suspend.html.
To 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 on the main menu or run the following command in the embedded Terminal: For details, see http://docs.vagrantup.com/v2/cli/resume.html.
To shut an instance down
- To shut down the operating system on a virtual machine (guest machine), choose on the main menu or run the following command in the embedded Terminal: 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 on the main menu or run the following command in the embedded Terminal:For details, see http://docs.vagrantup.com/v2/cli/destroy.html.