Skip to content

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

Cloudflare Tunnel
Share your local site publicly via Cloudflare Tunnel
Not set up
Rector
Instant refactoring tool for PHP code
Running
Prettier PHP
Install prettier and @prettier/plugin-php
Set up
Laravel Pint
Opinionated PHP code style fixer for minimalists
Not set up
Laravel Upgrade
Upgrade your Laravel project to a newer version using Rector
Project is not running

This computer same for every project

Whisper CLI
Local speech-to-text for Voice-to-Text feature
Installed

Rector

Verifying PHP version

Installing Rector

./composer.json has been updated
Running composer update rector/rector
Updating dependencies
- Locking phpstan/phpstan (2.1.17)
- Locking rector/rector (2.1.0)
Downloading rector/rector (2.1.0)

Creating Rector configuration

Close
The Recipes panel, and the Rector recipe with its steps and live output.

Run a recipe ​

  1. Click Recipes at the right end of the project tab bar. The Recipes panel opens.
  2. Click a recipe. The dialog shows the steps.
  3. 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:

StateMeaning
RunningThe recipe runs now. Click the recipe to see the steps and the live output.
FinishedThe recipe is complete. Click the recipe to see the result and next steps.
FailedThe recipe stopped with an error. Click the recipe to see the output.
Installed, Set up or Up to dateThe recipe has nothing left to do.
Not installed or Not set upThe tool is not in the project or on your computer yet.
Update availableA newer DDEV version is out. Only on Upgrade DDEV.
A reason, for example Project is not runningThe 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:

GroupRecipesState
This projectThe recipes that apply to this project. They run in this project only.For each project
This computerUpgrade 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:

  1. cloudflared. On macOS, the recipe installs it with Homebrew.
  2. 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:

  1. Stops all projects (ddev poweroff).
  2. Runs the upgrade command for your install method, for example brew upgrade ddev/ddev/ddev or 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.
  3. Removes old DDEV images (ddev delete images -y) to free disk space.
  4. 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:

  1. Writes a script to .ddev/commands/web/create_additional_database.sh.
  2. Adds the script as a DDEV post-start hook 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:

CheckWhat it needs
DockerDocker is installed and running, and docker compose up --wait works.
DDEVDDEV is installed and has the commands that the recipe uses (ddev add-on get, ddev config --web-environment-add).
bash and gzipThe recipe runs in bash. On Windows, use WSL 2.
Sail dataThe Sail database (and MongoDB) container or volume exists.
Database versionDDEV supports the database version that Sail runs. The recipe asks DDEV which versions it supports.
PortsNo 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.
DiskThe disk has space for the database dump.
HostnameThe 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:

  1. Copies .env (and the Vite config, if the recipe changes it) to the temporary folder .sail-to-ddev-backup/. Git ignores this folder.
  2. 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.
  3. Dumps MongoDB to .sail-to-ddev-backup/mongodb.archive.gz and records the list of collections, if the project has a MongoDB service.
  4. Stops Sail.
  5. Runs ddev config with the PHP version, the database type and version, and the Node.js version of the Sail setup.
  6. Installs the DDEV add-ons for the Sail services, for example Redis, Memcached, MongoDB, Meilisearch, Typesense, RabbitMQ and Selenium.
  7. Configures Vite, if vite.config.js has the standard Laravel shape. The recipe exposes port 5173 in DDEV and sets VITE_DEV_SERVER_ORIGIN in the DDEV web container from the project URL that ddev describe shows. The Vite config uses the DDEV server settings only when this variable is set.
  8. Starts DDEV and imports the database with ddev import-db.
  9. Restores the MongoDB dump into the MongoDB service that ddev describe shows, and sets MONGODB_URI in .env to it.
  10. Removes the Sail-only keys from .env, for example APP_PORT, FORWARD_DB_PORT, WWWUSER and WWWGROUP.
  11. 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.
  12. 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, the docker/ folder or vendor/laravel/sail, because they are project code. It does not remove Docker images.
  13. 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:

CheckWhat it needs
HomebrewHomebrew is installed.
DDEVDDEV and Docker run, because the recipe exports the database from DDEV. DevWorkspace Pro can read .ddev/config.yaml.
ProjectDDEV 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-onsOnly ddev-laravel-queue and ddev-share-cf.
PHPHomebrew has the PHP version that you pick, and Homebrew PHP has the PHP extensions that the project needs.
DatabaseMySQL or MariaDB, and Homebrew has the version that you pick. PostgreSQL projects stay in DDEV.
Host toolsDevWorkspace Pro knows each line of .ddev/web-build/Dockerfile*, or you marked the line as handled.
PortsThe HTTP and HTTPS ports of native sites are free. See Ports.
NamesNo other native project uses <name>.test or the native database name.
Certificate authorityThe DevWorkspace Pro CA can sign certificates. If it cannot, click Make a new CA in Preferences > Native PHP.
DiskThe 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 DDEVAfter 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 connectionThey 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 databasesThey 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 ChromeThe 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 hasThe move adds .env lines with the path on your Mac.
.env values that work only inside DDEV: host.docker.internal and /var/www/html pathsThe 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-cfIt does not work after the move. Use Share on the project page. See Share a native site.
Hooks and custom DDEV commandsThey 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:

  1. Backs up the .env keys that it changes, and writes RESTORE.txt, in .ddev-to-native-backup/. Git ignores this folder.
  2. Installs the Homebrew packages that are missing.
  3. Puts the database client on your PATH, if your shell does not find mysql and mysqldump (for MariaDB, also mariadb and mariadb-dump). The step output tells you why it runs. See Which PHP the command line uses.
  4. Sets up .test names and HTTPS. On the first move, macOS asks for your password. See .test domains.
  5. Adds the DevWorkspace Pro CA to each Firefox profile, if Firefox is installed. See Trust in other tools.
  6. Makes the site certificate.
  7. Starts the native services.
  8. 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.
  9. Creates the native databases and imports the dumps. It also creates the empty test databases.
  10. 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 TABLE for 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 run php artisan migrate.
  11. Updates .env: DB_HOST=127.0.0.1, the database port and name, DB_USERNAME=root, an empty DB_PASSWORD, APP_URL and MAIL_MAILER=log. If .env has 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 _HOST is db, for example QUESTION_BANK_HOST, the host becomes 127.0.0.1, a _PORT of 3306 becomes the native port, a _USERNAME or _USER of db becomes root, and a _PASSWORD of db becomes 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.
  12. Adds the site to nginx.
  13. Stops DDEV.
  14. 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.
  15. Removes the DDEV copy: ddev delete --omit-snapshot, then the containers, the database volume and the images of the project.
  16. Deletes the .ddev folder 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 .ddev folder, a ddev start in the project folder, for example from a terminal or an IDE, cannot bring the DDEV copy back and change .env to the DDEV values.
  17. 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:

  1. 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 into additional_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.
  2. Starts DDEV.
  3. Exports the native database, and each other database that the move to native PHP copied.
  4. Imports them into DDEV. Each other database gets its DDEV name back, with the same character set and collation.
  5. Checks the data of each database. The tables and the row counts must be the same as in the native database.
  6. Updates .env with 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.
  7. Removes the native site, its queue workers and its share.
  8. Checks the DDEV site.
  9. 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.

DevWorkspace Pro - One workspace for every project