Vagrant development environment for PHP

As a developer, I work on projects that require a variety of software, each tuned to different configurations. The easiest way to achieve this is to set up a virtual machine and configure that as per the need of the project. This allows me to keep my host machine clean, and share the virtual machine with other developers on the project.

In this blog, I’ll describe the configuration of a Vagrant machine that I’ve setup for PHP web development. Here’s a link to the box on vagrant cloud.

Vagrant configuration

Vagrant.configure("2") do |config|
  config.vm.box = "php-dev"
  config.ssh.forward_agent = true
  config.vm.network "forwarded_port", guest: 80, host: 8888
  config.vm.network "forwarded_port", guest: 3306, host: 8306
  config.vm.network "forwarded_port", guest: 8000, host: 8000
  config.vm.synced_folder ".", "/vagrant",
        :owner => 'vagrant',
        :group => 'www-data',
        :mount_options => [ 'dmode=775', 'fmode=775' ]
  config.vm.provider "virtualbox" do |v|
    v.memory = 1792
    v.cpus = 2
  end
end

Recommended configuration

The vagrant box runs Debian 10 Buster. It uses,

1. 2 dedicated CPU cores
2. 1560 MB of RAM from the host machine.

Port configuration

Following is the port configuration for the vagrant box,

80 (guest) = 8888 (host)    # Apache 
3306 (guest) = 8306 (host)  # MariaDB 
8000 (guest) = 8000 (host)  # Extra port for PHP / Node server 
22 (guest) = 2222 (host)    # SSH

Other configuration

• Added vagrant user to www-data and adm group, in order to handle Apache permissions and view application logs.
• SSH agent forwarding has been enabled.

Installed software

Listed below are software that have been installed on the system,

1. Apache 2.4.38
2. MariaDB 10.3.18
3. htop, ncdu, curl, git, unzip
4. PHP 7.3 and extensions
5. Composer 1.9.1 (globally)
6. Redis 5.0.3
7. Node 12.14. 1 and npm 6.13.4 (via nvm)

Software configuration

1. The base directory for Apache2 is configured to /vagrant/code. The vagrant user has been added to the www-data group to handle permission issues.
2. Apache2 mod_rewrite module has been enabled.
3. MariaDB has been configured with the following users,
   • Username: root / Password: T0P!33L
   • Username: admin / Password: C00La!d
4. Following changes have been made to MariaDB configuration,
   • Increased innodb_buffer_pool_size to 768MB
   • Set innodb_file_per_table to 1.
   • Set max_allowed_packet to 256MB for MySQL, and 192MB for mysqldump
   • Enabled slow query logging. Long query time has been set to 5 seconds. Slow logs will be written to /var/log/mysql/mysql_slow.log.
5. All PHP extensions required to run Laravel 6 have been installed. In addition, the tidy, xdebug, redis, and yaml extensions have been installed.
6. Following changes have been made to PHP configuration file,
   • upload_max_filesize and post_max_size have been set to 20MB.
   • memory_limit has been set to 256MB.
   • Enabled error logging for both Apache and CLI.
7. For Redis, maxmemory has been set to 256MB.
8. Composer bin folder has been added to the PATH via .bashrc

PHP debugging support

Debugging support for PHP has been added via Xdebug and tested using VSCode with the PHP Debug extension.

Consider a sample VSCode project – debugging, created under /vagrant/code/debugging. This project has a file called index.php. Following is the configuration that needs to be put under the VSCode launch file. (/vagrant/code/debugging/.vscode/launch.json).

{
  // Use IntelliSense to learn about possible attributes.
  // Hover to view descriptions of existing attributes.
  // For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387
  "version": "0.2.0",
  "configurations": [
    {
       "type": "php",
       "request": "launch",
       "name": "Listen for XDebug",
       "pathMappings": {
         "/vagrant/code/debugging": "${workspaceFolder}",
       },
       "port": 9000 // XDebug port
     }
  ]
}

Following is the configuration for Xdebug,

xdebug.remote_enable = true
xdebug.remote_autostart = true
xdebug.remote_host = 10.0.2.2
xdebug.remote_port = 9000
xdebug.remote_log = /var/log/xdebug.log
xdebug.max_nesting_level = 1000

---

Future improvements

I currently have the following things in mind,

• The box is set to use 1536MB of RAM, and I might have to tweak this a little higher.
• Test debugging support for applications run via the PHP server and on the PHP CLI
• Install and setup XHProf and XHProf UI.

I plan on keeping this box up-to-date for the foreseeable future. I’m open to suggestions on how this box can be improved, and made more useful for PHP developers to quickly start their development.