Recipes
A recipe installs or sets up a tool in a project. Each recipe shows the steps before it runs them, and shows the output while it runs.
Recipes
One-click actions for common or laborious chores.
This project · acme-app runs here only
This computer same for every project
Rector
Verifying PHP version
Installing Rector
Creating Rector configuration
Run a recipe
- Click Recipes at the right end of the project tab bar. The Recipes panel opens.
- Click a recipe. The dialog shows the steps.
- Click Proceed. The dialog goes back to the top, so you see the first step and its output.
A recipe continues to run when you close the dialog or the panel, or go to a different tab or project. While a recipe runs, the Recipes button shows a spinner. Each recipe shows its state on the right of its row:
| State | Meaning |
|---|---|
| Running | The recipe runs now. Click the recipe to see the steps and the live output. |
| Finished | The recipe is complete. Click the recipe to see the result and next steps. |
| Failed | The recipe stopped with an error. Click the recipe to see the output. |
| Installed, Set up or Up to date | The recipe has nothing left to do. |
| Not installed or Not set up | The tool is not in the project or on your computer yet. |
| Update available | A newer DDEV version is out. Only on Upgrade DDEV. |
| A reason, for example Project is not running | The recipe cannot run now. Click it to see the full reason. |
The Finished or Failed state stays until you open the dialog and close it. A notification also shows when a recipe ends.
A recipe cannot run two times at the same time. While it runs, the dialog does not show Proceed.
The panel has two groups:
| Group | Recipes | State |
|---|---|---|
| This project | The recipes that apply to this project. They run in this project only. | For each project |
| This computer | Upgrade DDEV, Whisper CLI, whisper-server and ffmpeg. They install tools for all projects. | The same in all projects |
Each recipe declares the projects that it applies to, for example DDEV projects, PHP projects in DDEV or Laravel projects in DDEV. The panel does not show a recipe that does not apply. For example, a .NET project does not show the DDEV and PHP recipes. The panel also does not show NPM Dependencies when the project has no package.json, or Sail to DDEV when the project has no Sail compose file. DDEV to Native PHP and Convert to DDEV show only on macOS for now. Linux and WSL support is coming. If no recipe applies, the This project group shows a short line that tells you so.
The PHP recipes (Rector, Rector Laravel, Laravel Upgrade, Prettier PHP and Laravel Pint) show only for PHP projects that run in DDEV. Support for PHP projects outside DDEV is in progress.
The app does not keep the recipe state after a restart.
Some recipes show next steps and links when they finish. When a recipe shows Installed, Set up or Up to date, a click does not open the dialog. A notification tells you that the tool is already installed or set up. Additional Database is different: it opens the dialog, so you can change the database name.
Before you run a recipe that changes project files, commit your work. Then review the recipe's changes with git diff or in Git › Changes. See Git Changes.
Available recipes
Addons
Enable or disable DDEV add-ons for the project. See Services & Addons.
NPM Dependencies
Runs npm outdated and lists the outdated packages. The recipe shows only when the project has a package.json.
Cloudflare Tunnel
Share your local site on a public URL through Cloudflare Tunnel. The recipe installs the parts that the project does not have yet:
cloudflared. On macOS, the recipe installs it with Homebrew.- The ddev-share-cf add-on, with
ddev add-on get davo20019/ddev-share-cf. The add-on is installed for each project.
The project must be running. After the recipe, click Share on the project page, or run ddev share-cf. If the project does not have the add-on, Share shows how to install it. Click Or install from Recipes > Cloudflare Tunnel to open this recipe.
Rector
Installs rector/rector with Composer (--dev) and creates rector.php. Needs PHP 7.2 or later. Not available if rector.php exists.
Rector Laravel
Installs driftingly/rector-laravel with Composer (--dev).
Laravel Upgrade
Reads the Laravel version from composer.json and upgrades the code one major version, for example from Laravel 10 to 11. It runs vendor/bin/rector process with the rector-laravel set of the next version on app, bootstrap/app.php, config, database, routes and tests. It supports Laravel 8 to 13. The recipe works only on Laravel projects that run in DDEV. The project must be running. Install Rector and Rector Laravel first.
The recipe does not change composer.json. To finish the upgrade, update laravel/framework and the packages in the Laravel upgrade guide, then run composer update -W yourself. Do this before you use the code, because some changes do not work on the old version. For example, Laravel 10 does not read the casts() method that the recipe adds for Laravel 11. Until you update composer.json, the recipe shows the same version. See Upgrade Laravel with Rector.
Prettier PHP
Installs prettier and @prettier/plugin-php, creates or updates .prettierrc, and adds PHP to the Prettier settings in .vscode/settings.json.
Laravel Pint
Installs laravel/pint with Composer (--dev) and creates pint.json with the laravel preset. Not available if pint.json exists.
Whisper CLI, whisper-server and ffmpeg
Install the tools for Voice-to-Text. Voice-to-Text does not need this recipe, because whisper-server is part of DevWorkspace Pro. ffmpeg converts audio. It installs with brew (macOS), choco (Windows) or apt-get (Linux).
Upgrade DDEV
Upgrade DDEV to the latest release and remove the Docker images of older DDEV versions. The recipe asks DDEV (ddev self-upgrade) how it was installed, then:
- Stops all projects (
ddev poweroff). - Runs the upgrade command for your install method, for example
brew upgrade ddev/ddev/ddevor the DDEV install script. If the upgrade needs administrator rights, macOS asks for your password. On Linux and WSL, run the command that the recipe shows in a terminal, then run the recipe again. - Removes old DDEV images (
ddev delete images -y) to free disk space. - Starts the projects that were running before.
When DDEV is up to date, the recipe shows Up to date. Click it, then click Remove old images in the notification to remove the images of older DDEV versions.
When a new DDEV release is available, a notification tells you. Click Upgrade to open this recipe, or skip that version.
Additional Database
Create another database in your DDEV project, for example a separate database for tests. Enter a name (letters, numbers and underscores). The recipe:
- Writes a script to
.ddev/commands/web/create_additional_database.sh. - Adds the script as a DDEV
post-starthook in.ddev/config.yaml.
Run ddev restart after the recipe. DDEV then creates the database, and creates it again on each ddev start. The recipe supports MySQL, MariaDB and PostgreSQL. The project must be running. The Database card on the Overview tab lists the additional databases. See Database.
Sail to DDEV
Move a Laravel Sail project and its data to DDEV. The recipe converts the project in place: when the data is in DDEV, it removes the Sail containers and volumes of the project. The recipe shows for Laravel projects that do not use DDEV and that have a compose file with a laravel.test service that is built from a Sail runtime.
When you open the recipe, it checks the computer first. The checks run at the same time:
| Check | What it needs |
|---|---|
| Docker | Docker is installed and running, and docker compose up --wait works. |
| DDEV | DDEV is installed and has the commands that the recipe uses (ddev add-on get, ddev config --web-environment-add). |
| bash and gzip | The recipe runs in bash. On Windows, use WSL 2. |
| Sail data | The Sail database (and MongoDB) container or volume exists. |
| Database version | DDEV supports the database version that Sail runs. The recipe asks DDEV which versions it supports. |
| Ports | No other program uses the ports that DDEV needs for Vite (5172 and 5173). Ports that this Sail project uses are free when the recipe stops Sail. |
| Disk | The disk has space for the database dump. |
| Hostname | The project hostname resolves. If it does not, DDEV adds it to the hosts file. On macOS, the recipe asks for your password. On Linux, run the ddev hostname command that the recipe shows. |
Each failed check shows how to fix it. Convert to DDEV stays disabled until all checks pass. Click Check again after you fix a problem.
The dialog shows only the steps that the recipe does:
- Copies
.env(and the Vite config, if the recipe changes it) to the temporary folder.sail-to-ddev-backup/. Git ignores this folder. - Dumps the database from the Sail container to
.sail-to-ddev-backup/database.sql.gz(MySQL, MariaDB or PostgreSQL), and records the list of tables and the row counts of small tables. - Dumps MongoDB to
.sail-to-ddev-backup/mongodb.archive.gzand records the list of collections, if the project has a MongoDB service. - Stops Sail.
- Runs
ddev configwith the PHP version, the database type and version, and the Node.js version of the Sail setup. - Installs the DDEV add-ons for the Sail services, for example Redis, Memcached, MongoDB, Meilisearch, Typesense, RabbitMQ and Selenium.
- Configures Vite, if
vite.config.jshas the standard Laravel shape. The recipe exposes port 5173 in DDEV and setsVITE_DEV_SERVER_ORIGINin the DDEV web container from the project URL thatddev describeshows. The Vite config uses the DDEV server settings only when this variable is set. - Starts DDEV and imports the database with
ddev import-db. - Restores the MongoDB dump into the MongoDB service that
ddev describeshows, and setsMONGODB_URIin.envto it. - Removes the Sail-only keys from
.env, for exampleAPP_PORT,FORWARD_DB_PORT,WWWUSERandWWWGROUP. - Checks the data in DDEV. The tables (and MongoDB collections) in DDEV must be the same as in Sail, and the row counts of small tables must match.
- Removes the Sail containers and volumes of this project with
docker compose down -v --remove-orphans, then removes.sail-to-ddev-backup/. The recipe does this only after the data check passes. It does not change the compose file, thedocker/folder orvendor/laravel/sail, because they are project code. It does not remove Docker images. - Opens the project as a DDEV project.
The recipe does not do other tasks, for example copy the data of other services or a second database service. Do these tasks yourself.
When the recipe finishes, the project runs in DDEV, and the Sail containers and temporary files are gone.
If a step fails, the recipe stops and does not remove Sail. Sail is stopped, and its containers and data stay. .sail-to-ddev-backup/ also stays: it has the dumps, the files from before the conversion, and RESTORE.txt with the commands to run the project with Sail again. If the data check fails, the error lists the tables or collections that are missing or different. Fix the problem and run the recipe again.
DDEV to Native PHP
Move a DDEV project and its data to native PHP on your Mac: PHP-FPM, MySQL or MariaDB and nginx, at https://<name>.test. When the data and the site are in place, the recipe removes the DDEV copy of the project and deletes its .ddev folder. The recipe shows only on macOS for now, for DDEV projects of type laravel or php. Linux and WSL support is coming. A project that it moved shows the Convert to DDEV recipe instead.
When you open the recipe, it checks the project and your Mac:
| Check | What it needs |
|---|---|
| Homebrew | Homebrew is installed. |
| DDEV | DDEV and Docker run, because the recipe exports the database from DDEV. DevWorkspace Pro can read .ddev/config.yaml. |
| Project | DDEV project type laravel or php, with the nginx-fpm web server. No extra DDEV services, config overrides, custom server files or container changes, except the ones in the table below. |
| Add-ons | Only ddev-laravel-queue and ddev-share-cf. |
| PHP | Homebrew has the PHP version that you pick, and Homebrew PHP has the PHP extensions that the project needs. |
| Database | MySQL or MariaDB, and Homebrew has the version that you pick. PostgreSQL projects stay in DDEV. |
| Host tools | DevWorkspace Pro knows each line of .ddev/web-build/Dockerfile*, or you marked the line as handled. |
| Ports | The HTTP and HTTPS ports of native sites are free. See Ports. |
| Names | No other native project uses <name>.test or the native database name. |
| Certificate authority | The DevWorkspace Pro CA can sign certificates. If it cannot, click Make a new CA in Preferences > Native PHP. |
| Disk | The disk has space for the dumps and the imports of all databases that move. |
Each failed check shows how to fix it. Convert to Native PHP stays disabled until all checks pass. Click Check again after you fix a problem.
Pick the PHP version and the Database version. The PHP version starts with the Default PHP version from Preferences > Native PHP. The database version starts with the version that DDEV runs, and you can pick a newer version of the same type, for example MySQL 8.0 to 8.4 or MariaDB 10.11 to 11.8. The checks run again after each pick. When all checks pass, the dialog shows Ready to convert with the PHP version, the database move and the URL, for example PHP 8.4 · MySQL 8.0 -> 8.4 · https://shop.test.
Under Good to know, notes tell you what changes, for example a PHP version that composer.json does not allow, or how many times macOS asks for your password.
These DDEV settings move with the project:
| In DDEV | After the move |
|---|---|
Queue workers (web_extra_daemons that run php artisan, for example from the ddev-laravel-queue add-on) | DevWorkspace Pro runs each worker on your Mac with queue:work. The queue is off after the move. Turn it on with Run queue on the Overview tab. A worker restarts when your code changes, so jobs use your latest code. See Queue workers. Other daemons do not run outside DDEV. |
| Other databases with tables, for example the database of a second Laravel connection | They move too. Each one gets the name <native database>_<DDEV name> on the native server, with the same character set and collation. For example, questions_bank of the shop project becomes shop_questions_bank. The notice lists them. Convert to DDEV moves them back under their DDEV names. |
| Test databases | They do not move. The recipe creates the ones your tests use, empty, on the native database server: the names in CREATE DATABASE lines of .ddev/commands/web/ scripts (for example from Additional Database), and DB_DATABASE in phpunit.xml, phpunit.xml.dist or .env.testing. Laravel parallel-testing copies, for example shop_testing_test_1, and leftovers named test, test_<anything> or t_ with 8 hex characters stay behind. The notice lists them. |
Vite (config.vite.yaml) | Vite runs on your Mac with npm run dev. The notice lists files that still name a .ddev.site host. |
| Tools in the DDEV image, for example ffmpeg or Chrome | The notice lists them. An AI agent can check and install them with the native PHP tools. |
Container paths in .env, for example a path that only the DDEV image has | The move adds .env lines with the path on your Mac. |
.env values that work only inside DDEV: host.docker.internal and /var/www/html paths | The move changes them to 127.0.0.1 and to the project folder on your Mac, and Convert to DDEV puts the DDEV values back. For a php project, the notice tells you what to change. A value with a .ddev.site host stays as it is, and the notice tells you to change it. |
ddev share-cf | It does not work after the move. Use Share on the project page. See Share a native site. |
| Hooks and custom DDEV commands | They do not run outside DDEV. |
Extra names (additional_fqdns and additional_hostnames in .ddev/config.yaml) | The site also answers at each name under .test, and at its subdomains. A name in additional_fqdns that ends in .test, for example shop-2.test, stays as it is. A name in additional_hostnames, for example admin, becomes admin.test. The notice lists the names. Other names, for example a real domain or a .ddev.site name, do not move, and the notice lists them too. Names that https://<name>.test already covers, for example acme.shop.test, need nothing. |
At the end, a red box says This removes the DDEV copy. Tick I understand. Convert to Native PHP stays disabled until you tick it.
The recipe does these steps:
- Backs up the
.envkeys that it changes, and writesRESTORE.txt, in.ddev-to-native-backup/. Git ignores this folder. - Installs the Homebrew packages that are missing.
- Puts the database client on your PATH, if your shell does not find
mysqlandmysqldump(for MariaDB, alsomariadbandmariadb-dump). The step output tells you why it runs. See Which PHP the command line uses. - Sets up
.testnames and HTTPS. On the first move, macOS asks for your password. See .test domains. - Adds the DevWorkspace Pro CA to each Firefox profile, if Firefox is installed. See Trust in other tools.
- Makes the site certificate.
- Starts the native services.
- Exports the DDEV database and each other database that moves, and records their tables and row counts. It also records the HTTP status of the DDEV site.
- Creates the native databases and imports the dumps. It also creates the empty test databases.
- Checks the data of each database. The tables must be the same as in DDEV, and the row counts of small tables must match. When DDEV and the native server run the same database version, the check also compares
CHECKSUM TABLEfor each table and names the first table whose data is different. If the DDEV database has no tables, the native database is empty too, and the dialog shows a notice to runphp artisan migrate. - Updates
.env:DB_HOST=127.0.0.1, the database port and name,DB_USERNAME=root, an emptyDB_PASSWORD,APP_URLandMAIL_MAILER=log. If.envhas a key more than once, the step changes every copy and names the lines in its output, so a later copy cannot undo the change. Other keys that point at a DDEV database change too. A key that holds the name of a database that moves gets its native name. In a key group whose_HOSTisdb, for exampleQUESTION_BANK_HOST, the host becomes127.0.0.1, a_PORTof3306becomes the native port, a_USERNAMEor_USERofdbbecomesroot, and a_PASSWORDofdbbecomes empty. Keys in other groups stay as they are. The step lists the keys it changed, and Convert to DDEV puts their DDEV values back. - Adds the site to nginx.
- Stops DDEV.
- Checks that the site answers from PHP over HTTPS, and that HTTP sends visitors to HTTPS. If the site gives a server error (HTTP 500 or higher) that DDEV did not give before the move, this step fails and shows the Laravel error, if the log has one. If DDEV gave a server error before the move too, the move goes on and the dialog shows a notice. HTTP 502 or 504 always fails this step, because PHP did not answer.
- Removes the DDEV copy:
ddev delete --omit-snapshot, then the containers, the database volume and the images of the project. - Deletes the
.ddevfolder of the project. The recipe does not back it up. If you want to keep your DDEV settings, copy the folder before you click Convert to Native PHP. The dialog says so before the move starts. With no.ddevfolder, addev startin the project folder, for example from a terminal or an IDE, cannot bring the DDEV copy back and change.envto the DDEV values. - Opens the project in DevWorkspace Pro as a native PHP project (Local PHP).
The dialog shows each step with its output. When macOS waits for your password, the dialog shows macOS is waiting for your password. A move that an AI agent started shows in the dialog too.
When the recipe finishes, the project runs at its .test URL, and .ddev-to-native-backup/ is gone. If Docker items are left, the dialog lists the command to remove each one. The Overview tab of the project shows the URL at once, with the real port, for example https://shop.test:8443. Copy it from URL under Project Information, or click Open Website. Click the arrow beside Open Website to see the HTTPS and HTTP URLs. After Convert to DDEV, the tab shows the DDEV URLs again.
If a step fails before the recipe removes the DDEV copy, the recipe puts .env back, removes the nginx site, and starts DDEV again if it was running. .ddev-to-native-backup/ stays with RESTORE.txt. Fix the problem and run the recipe again.
Convert to DDEV
Move a project that runs on native PHP back to DDEV, with its database. The recipe shows only on macOS for now, for projects that run on native PHP.
When you open the recipe, the dialog shows the URL, the PHP version, the database and the queue workers of the native site. It checks that DDEV and Docker run, and that no other DDEV project uses the same name. Fix any problem it lists, click Check again, then click Convert to DDEV. The project does not need a .ddev folder. The recipe:
- Creates the DDEV config with
ddev config: the project type, the docroot, the PHP version, and the database type and version of the native site. Extra names of the native site go intoadditional_fqdns. If the project has.ddev/config.yaml, for example one that you copied back, DDEV starts from it and the recipe skips this step. - Starts DDEV.
- Exports the native database, and each other database that the move to native PHP copied.
- Imports them into DDEV. Each other database gets its DDEV name back, with the same character set and collation.
- Checks the data of each database. The tables and the row counts must be the same as in the native database.
- Updates
.envwith the DDEV database, URL and Mailpit values, removes the lines that the move to native PHP added, and puts back the DDEV-only values that the move changed. - Removes the native site, its queue workers and its share.
- Checks the DDEV site.
- Opens the project as a DDEV project.
A new DDEV config has only those settings. Custom commands, add-ons, queue workers and other settings from the old .ddev folder do not come back. Copy them from your backup if you made one.
If a step fails before the recipe removes the native site, the recipe puts .env back and takes DDEV down again. When the recipe made the DDEV config, it also deletes the new .ddev folder. The native site keeps running.
The native database stays, and so do the other databases that the move to native PHP copied. Drop them in Preferences > Native PHP > Databases no site uses when you no longer need them.
Request a recipe
Open an issue on GitHub and describe the task you want to automate.
Troubleshooting
- The recipe is not available. The row shows the reason, for example Project is not running. Click the recipe to see the full reason. When the tool is already set up, for example a config file exists, the recipe shows Set up or Installed and a notification tells you.