If your local development environment doesn't already have the required stack and tools, we'll now set them up. We'll go through the following:
If you followed the previous pages, you probably noticed two pieces of software absent from that list: The web server software and the database. This is on purpose. This guide uses the built-in PHP Server and SQLite, which don't require additional installation. Optionally, you may want to install a web server (e.g.: Apache, Nginx, etc) and a database (MariaDB, MySQL, Postgres or SQL Server). The "optional" part of this guide will cover setup for those.
The command line interface will be required to perform most tasks in this guide. It's usage depends on your OS :
If you're using MacOS, the Terminal is already installed on your computer. You'll find the app in /System/Applications/Utilities/Terminal.
Every Linux distro uses the command line. On Ubuntu for example, you can find a launcher for the terminal by clicking on the Activities item at the top left of the screen, then typing the first few letters of "terminal", "command", "prompt" or "shell".
The easiest way to setup a local dev environnement on Windows is through Windows Subsystem for Linux (WSL2). This is basically running Linux inside Windows. Best of both worlds! This also means most installation instructions for Windows you'll find on the internet won't work, as we're not technically on Windows, we're on Ubuntu. We'll instead use the Ubuntu installation instructions!
See this guide for more detail on this process : Set up a WSL development environment. The gist of it is :
wsl --install.When using Windows and WSL2, keep in mind your project files will be stored inside the Linux file system. For example, your project files will be in the Linux file system root directory (\\wsl$\<DistroName>\home\<UserName>\Project), not the Windows file system root directory (C:\Users\<UserName>\Project or /mnt/c/Users/<UserName>/Project$). See Microsoft guide on file storage for more information.
Installing PHP 8.3 locally will make it easier to develop locally, as it will allow you to run Composer locally, too.
The easiest way to install PHP on MacOS is through Homebrew:
xcode-select --installbrew install shivammathur/php/[email protected] Install PHP through the package manager. For example, on Ubuntu :
Add Ondřej Surý PPA to get the latest version :
sudo add-apt-repository ppa:ondrej/php
sudo apt updateInstall PHP and the necessary extensions :
sudo apt install php8.3 php8.3-gd php8.3-dom php8.3-zip php8.3-sqlite3 php8.3-pdo_mysql php8.3-curl php8.3-mbstring unzipBefore going further, you should check which version of PHP will be run in the command line. It is very common for a single environment to have multiple different versions of PHP installed. If you've never run PHP from the command line before, you may not realize that the version of PHP run by the webserver (Apache, nginx, etc.) can be different from the one that will run in the command line.
To check the "command line" version, use the command:
php -vYou should then see a message like:
PHP 8.3.0 (cli) (built: Nov 21 2023 14:40:35) (NTS)
Copyright (c) The PHP Group
Zend Engine v4.3.0, Copyright (c) Zend Technologies
with Xdebug v3.3.0, Copyright (c) 2002-2023, by Derick Rethans
with Zend OPcache v8.3.0, Copyright (c), by Zend TechnologiesThis is the version of PHP which will be used by Composer. Make sure it meets the minimum required version for UserFrosting!
php command. This happens because there is an older version of PHP (often preinstalled with your operating system) in one of the paths specified in your path variable ($PATH in *nix systems, PATH environment variable in Windows).
To check the value of your PATH variable in *nix environments, simply run echo $PATH.
To check if the required extensions are enabled, you can use :
php -mNext step is to install Composer 2. At this point, the installation is the same for MacOS, Linux and Windows WSL2. The full instructions for installing Composer can be found at their website. We strongly recommend that you install Composer globally on your system. This will let you run Composer using the composer command.
mv composer.phar /usr/local/bin/composerTo check if Composer is correctly installed:
$ composer --version
Composer version 2.5.4 2023-02-15 13:10:06It's now time to install Node.js. Any version above 18.0 will work with UserFrosting 5, however we recommend using the latest LTS version of Node.js (18.18.2 LTS as of October 2023).
Node.js has an installer that you can use for MacOS - Node.js Download. Node will then be available in Terminal.
Node.js binary distributions are available from NodeSource.
To check if Node.js is installed:
$ node -v
v18.17.1When you installed Node, it should have automatically installed npm as well. However, we still recommend updating npm (if unable to update, any version later than 9.0 should work):
npm install npm@latest -gTo check which version of Npm is installed:
$ npm -v
10.1.0UserFrosting build scripts will automatically install all other Node and NPM dependencies for you !
As we've seen in previous pages, UserFrosting requires an SMTP server for sending email to your users, especially registration emails. However, in a local environment you don't want "test" emails to be sent to your users. You also don't want to fill your inbox with test emails.
This is where email testing tools come in. When an email is sent by UserFrosting, instead of sending the email to a real mailbox, the email testing tool will capture the email and makes it available to you to read, regardless of the recipient of the email. In other words, if UserFrosting send five emails to five different email address, all five email will be captured and displayed in the same "test" inbox.
While multiple solutions are available, two are recommended by UserFrosting : Mailpit and Mailtrap. It's up to you to choose the one you prefer.
Mailpit is a small, fast, low memory, zero-dependency, multi-platform email testing tool & API for developers. Mailpit runs locally, acts as a fake SMTP server and provides a modern web interface to view & test captured emails. Oh, and it's free and Open Source!
Mailpit can be installed on MacOS through Homebrew, on Linux/WSL2 through their Bash Script](https://github.com/axllent/mailpit#install-via-bash-script-linux--mac), or through Docker. By default, Mailpit UI can be access at http://0.0.0.0:8025.
When using Mailpit with UserFrosting, the following parameters will need to be provided during UserFrosting installation, which we'll see on the next page :
| Param | Value |
|---|---|
| SMTP_HOST | localhost |
| SMTP_PORT | 1025 |
| SMTP_SECURE | false |
| SMTP_AUTH | false |
Mailtrap is similar to Mailpit, but it runs in the cloud, so there's nothing to install. However, Mailtrap is not open source. Mailtrap features a forever free plan that offers basic functionality for personal use. The Free Sandbox provides one inbox and up to 100 emails per month. It's a great way to get started, as it's super easy and fast to setup. For a more permanent solution however, Mailpit should be preferred.
To get started, simply create your account on Mailtrap's website.
When using Mailtrap with UserFrosting, the following parameters will need to be provided during UserFrosting installation, which we'll see on the next page :
| Param | Value |
|---|---|
| SMTP_HOST | sandbox.smtp.mailtrap.io |
| SMTP_PORT | 25 or 465 or 587 or 2525 |
| SMTP_USER | See below |
| SMTP_PASSWORD | See below |
The user and password are unique to your Mailtrap inbox, and can be found in your Mailtrap account.
The next tools are not required in your local development environment to run UserFrosting. However, you may be interested in installing them anyway; or the instructions may be helpful for those tools which apply to you.
By default, MacOS and other Linux operating systems should come with git preinstalled. On MacOS, Apple also ships a binary package of Git with Xcode. You may not need to install it manually. If you would like to update your version of git, you can do so with their installer.
As mentioned at the beginning of this page, it's not required to install a web server on your local stack, as we'll use the PHP Built-in Server. However, if you prefer to install Apache or Nginx, it's certainly possible to do so.
To serve UserFrosting with a web server, you should configure your web server's document / web root to be the /public directory. The index.php in this directory serves as the front controller for all HTTP requests.
Apache can be installed natively on Linux using most package managers. Some very useful guides can be found online with instructions for Ubuntu. It can also be installed through Homebrew on MacOS.
When using Apache to serve UserFrosting, check that you have the Rewrite Engine module (mod_rewrite.c) installed and enabled. Some distributions may not have this module automatically enabled, and you will need to do so manually. In a shared hosting environment, you may need to have your hosting service do this for you.
In addition, make sure that the Directory block in your VirtualHost configuration is set up to allow .htaccess files. For example:
# Allow .htaccess override
<Directory /var/www/userfrosting/public/>
Options Indexes FollowSymLinks MultiViews
AllowOverride All
Order allow,deny
</Directory>UserFrosting includes a public/.htaccess file that is used to provide URLs without the index.php front controller in the path. Before serving UserFrosting with Apache, be sure to enable the mod_rewrite module so the .htaccess file will be honored by the server.
Nginx can be installed natively on Linux using most package managers. Some very useful guides can be found online with instructions for Ubuntu. It can also be installed through Homebrew on MacOS.
When using Nginx to serve UserFrosting, make sure to include this directive in your site config.
location / {
try_files $uri $uri/ /index.php?$query_string;
}As mentioned at the beginning of this page, it's not required to install a database provider in your local stack, as we'll use the file-based SQLite database. However, if you prefer to install MySQL or Progress, you may do so.
For example, MySQL can be installed natively on Linux. If you're interested, check out Digital Ocean's [How To Install MySQL on Ubuntu 22.04](https://www.digitalocean.com/community/tutorials/how-to-install-mysql-on-ubuntu-20-04) guide. On MacOS, it can obviously be installed through Homebrew.
It's also possible to install each database provider with Docker:
Before installing UserFrosting, you'll need to create a database and database user account. Consult your database documentation for more details. If you use phpmyadmin or a similar tool, you can create your database and database user through their interface. Otherwise, you can do it via the command line.