How-to develop TYPO3 projects locally with the built-in PHP dev server

You can develop TYPO3 projects locally without MAMP, Vagrant or Docker.

This how-to is targeted for TYPO3 developers who want to run and develop their projects on their Mac. This solution might work in a similar way on other operating systems. Feel free to add helpful information in the comments.

Prerequesite: Switchable PHP versions

One time setup

There is a verbose article on grav that explains how to install multiple PHP versions with homebrew. If you read it you can skip all the apache related steps. Here's the essence of it, that we will need:

If you don't have homebrew on your machine, install it:

$ ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"

Install all the PHP versions you need:

$ brew install [email protected] [email protected] [email protected] libyaml

You may ommit any versions that you won' t need, but it's also handy to have them all available.

Switching the PHP version

Install the switcher script:

$ curl -L https://gist.githubusercontent.com/rhukster/f4c04f1bf59e0b74e335ee5d186a98e2/raw > /usr/local/bin/sphp
$ chmod +x /usr/local/bin/sphp
$ /usr/local/bin/sphp

Check the currently installed version:

$ php --version
PHP 7.1.14 (cli) (built: Feb  7 2018 18:33:30) ( NTS )
Copyright (c) 1997-2018 The PHP Group
Zend Engine v3.1.0, Copyright (c) 1998-2018 Zend Technologies

This is how you switch to PHP 7.2:

$ sphp 7.2 -s

The TYPO3 download page will tell you which PHP version you need for which TYPO3 version.

Install Xdebug, APCu and YAML

$ sphp 7.0 -s
$ pecl uninstall -r apcu && pecl install apcu && pecl uninstall -r yaml && pecl install yaml && pecl uninstall -r xdebug && pecl install xdebug

Repeat that for every PHP version.

Prerequesite: Prepare your local mysql

If you don't have the root password for the mysql that was shipped with macOS, here's how to reset it.

Then disable MySQL strict mode by creating or updating the file /etc/my.cnf with following content:

[mysqld]
sql_mode=IGNORE_SPACE,NO_ZERO_IN_DATE,NO_ZERO_DATE,ERROR_FOR_DIVISION_BY_ZERO,NO_AUTO_CREATE_USER,NO_ENGINE_SUBSTITUTION

Set up the TYPO3 project

Create a database and a user in your local mysql database.
Copy/clone your TYPO3 project into a local folder
Configure your db credentials (depends on your project, e.g. in AdditionalConfiguration.php)
$ php -S 127.0.0.1:8026 -t web/ (stop the server with Ctrl + c)

The web/ folder is the public web folder relative to your project root. This can differ for your project, e.g. htdocs/ or ./ if your project root equals your web root.

The port number is arbitrarily chosen. Use different port numbers for different projects if you need to run multiple projects simultaneously.

Now your installation is available at http://127.0.0.1:8026 in your browser.

What if I need (multiple) host names?

Start your php server with this command:

$ php -S 0.0.0.0:8080 -t web/

And add your host names to your /etc/hosts file:

# hosts for myproject
127.0.0.1 de.mycms.local
127.0.0.1 en.myproject.local

http://de.mycms.local:8080 should now be available in your browser.

Hint for a better co-working experience

Document the setup steps in a README.md in the project root directory. Every of our projects has a README.md like this:

Caveats

If you want/need to get rid of the port number in your local URL, I have two bad solutions for you:
1. Run the php server on port 80. You'll need sudo for that and I absolutely don't recommend to run your project with those privileges.
2. Run the php server on port 8080 and configure a hard port-forward from 8080 to 80 on your machine. This is a tricky task that cost us a bit time working through a handful of StackOverflow pages. I don't have the solution that eventually worked for as at hand at the moment, sorry.

I can't promise you that it will help you, but I can promise you that it helps us.

Sebastian Michaelsen
maschinenraum.digital

smichaelsen/howto.md