Přeskočit na obsah
iD-SIGN
Ptejte se

Lokální vývoj Symfony v DDEV

DDEV rozjede Symfony projekt jedním příkazem. Ukážeme, jak ho nastavit, aby měl každý vývojář stejné verze PHP, databáze, Node i rozšíření jako produkce. Rovněž kam patří služby, démoni a limity a které jeho možnosti ušetří vlastní skripty.

20 min čtenívydáno 11/2026

V tomto článku 16 kapitol
  1. Základ konfigurace
  2. Co patří do gitu
  3. Proměnné prostředí a .env
  4. Co DDEV přináší navíc
  5. Rozšíření PHP a web image
  6. Databáze
  7. Vite a HMR
  8. Messenger a Scheduler
  9. Další služby
  10. Shoda s produkcí
  11. Hooks a vlastní příkazy
  12. Testy
  13. Více kopií projektu vedle sebe
  14. macOS a Windows
  15. Přístup z místní sítě a sdílení ven
  16. Časté ohnutí a lepší cesta

DDEV spouští pro každý projekt vlastní sadu kontejnerů: web s nginx a PHP-FPM, databázi, Mailpit a router, který projekt vystaví na https://<projekt>.ddev.site s platným certifikátem. Na počítači stačí Docker a ddev. PHP, Composer ani Node na hostiteli nepotřebujete a nemají se tam ani spouštět.

Nový projekt založí ddev config --project-type=symfony --docroot=public a ddev start, Symfony do něj pak nainstaluje ddev composer create-project symfony/skeleton. V existujícím repozitáři stačí spustit ddev config v jeho kořeni.

DDEV je snadné začít používat a snadné ohnout: vlastní skript místo volby v config.yaml, ručně pouštěný kontejner vedle projektu, kopie konfigurace webserveru. Tady je, co DDEV umí samo a kde se vyplatí ho rozšířit.

Základ konfigurace

Verze PHP, databáze a Node zapište podle produkce, ať má každý vývojář stejné prostředí jako produkce.

yaml
name: projekt
type: symfony
docroot: public
php_version: "8.5"          # jako produkce
webserver_type: nginx-fpm
database:
    type: postgres
    version: "18"           # jako produkce
timezone: Europe/Prague     # jinak se odvodí z hostitele
nodejs_version: "24"
corepack_enable: true
composer_version: "2"
webimage_extra_packages:
    - php${DDEV_PHP_VERSION}-imagick
use_dns_when_possible: true

type: symfony doinstaluje do kontejneru Symfony CLI, přidá ddev console jako zkratku pro bin/console a zapisuje připojení k databázi a poště do .env.local (viz další kapitola). U typu php nic z toho není. docroot: public uveďte výslovně.

timezone vyplňte vždy. Bez ní si DDEV zónu odvodí z hostitele, takže dva vývojáři můžou mít různé prostředí a nevědí o tom. Data a plánované úlohy se pak chovají jinak než v produkci.

ddev config vygeneruje config.yaml se stovkami řádků zakomentované nápovědy. Smažte ji. Vlastní nastavení se v ní ztratí a v diffu je hůř vidět, co se změnilo. Nápovědu najdete v dokumentaci a v ddev config --help.

Proti příliš staré verzi DDEV u kolegů chrání ddev_version_constraint: '>= 1.25' (konkrétní verzi doplňte podle funkcí, které projekt používá). Starší DDEV pak projekt nespustí a řekne proč.

Co patří do gitu

Do repozitáře patří config.yaml, docker-compose.*.yaml, commands/, web-build/, db-build/, php/, nginx/ a soubory add-onů. Vygenerované soubory a osobní nastavení si DDEV ignoruje sám vlastním .ddev/.gitignore, mezi nimi config.local.yaml a .ddev/.env.local.

config.local.yaml je místo pro to, co se liší počítač od počítače: adresa pro přístup z místní sítě, jiný název kopie projektu, vypnutý hook. Hodnoty se slučují s config.yaml. Když je potřebujete přepsat, ne doplnit (seznam hostname, hooks), dejte do souboru override_config: true.

Proměnné prostředí a .env

U typu symfony DDEV při každém ddev start zapíše do .env.local (v composer_root) připojení k databázi a poště: DATABASE_URL, MAILER_DSN=smtp://127.0.0.1:1025, MAILER_WEB_URL s adresou Mailpitu a několik pomocných klíčů. Čerstvý klon tak funguje po ddev start bez ručního nastavování.

Z toho plynou tři pravidla:

  • Vlastní DATABASE_URL nebo MAILER_DSN do .env.local nepište, DDEV ho při příštím startu přepíše. Ostatní řádky souboru nechává být, tajné klíče a osobní odchylky tam patří dál.
  • Návod „doplňte si MAILER_DSN do .env.local“ je zbytečný, DDEV to dělá sám.
  • Kdo chce .env.local spravovat sám, nastaví disable_settings_management: true a hodnoty zapíše třeba ddev dotenv set .env.local --database-url=….

Ostatní hodnoty pro vývoj, které nejsou tajné (DEFAULT_URI=https://projekt.ddev.site, adresy lokálních služeb), se vyplatí verzovat v .env.dev.

.env.local se v prostředí test nenačítá, hodnoty od DDEV tedy testy nevidí. Adresa testovací databáze patří do .env.test:

bash
# .env.test
DATABASE_URL="postgresql://db:db@db:5432/db?serverVersion=18&charset=utf8"

web_environment přebije soubory .env. web_environment v config.yaml a .ddev/.env.web nastavují proměnné prostředí celého web kontejneru, bez ohledu na APP_ENV. Jsou to skutečné proměnné prostředí a Symfony je hodnotami ze souborů .env* nepřepisuje. Když tam bude DATABASE_URL, dostanou ji i testy a hodnota z .env.test se neuplatní. Úprava v .env.local se také neprojeví, hodnota se mění jen v config.yaml a přes ddev restart.

Do web_environment proto patří jen to, co má dostat každý proces v kontejneru bez ohledu na prostředí Symfony, třeba COMPOSER_AUTH. Hodnoty, které se mezi dev a test liší, patří do .env.dev a .env.test.

Co DDEV přináší navíc

Kromě webu a databáze má DDEV sadu nástrojů, kvůli kterým se nevyplatí stavět vlastní. Stačí o nich vědět.

Mailpit zachytí všechnu poštu z projektu. Běží přímo ve web kontejneru na 127.0.0.1:1025, rozhraní otevře ddev mailpit. MAILER_DSN na něj nasměruje DDEV sám v .env.local. Kdo ho vypnul přes disable_settings_management, musí ho zapsat ručně, jinak výchozí null://null z receptu poštu zahodí. U zprávy ukáže zdroj, přílohy a záložku HTML Check, která vypíše, co z HTML a CSS nepodporují jednotliví poštovní klienti. Na šablony e-mailů je to rychlejší kontrola než posílání do skutečných schránek. Vlastní kontejner s Mailpitem je zbytečný druhý exemplář.

Import a export databáze bez znalosti klienta databáze:

bash
ddev import-db --file=dump.sql.gz          # také .sql, .zip, .tar.gz, .zst
gzip -dc dump.sql.gz | ddev import-db      # ze standardního vstupu
ddev import-db --database=druha --file=…   # do jiné databáze
ddev import-db --no-drop --file=…          # bez smazání stávajících dat
ddev export-db --file=/tmp/db.sql.zst      # komprese podle přípony
ddev psql                                  # nebo ddev mysql

Na částečný přenos (jen několik tabulek) stačí přesměrovat dump do ddev psql. Přes docker exec ddev-<projekt>-db chodit nemusíte.

Snapshoty jsou rychlejší než dump, protože kopírují soubory databáze: ddev snapshot --name pred-importem, zpět ddev snapshot restore pred-importem (nebo --latest), přehled ddev snapshot --list. Udělejte si ho před každou riskantní operací: hromadný import, doctrine:fixtures:load bez --append, ruční zásah do dat, zkouška migrace. Leží v .ddev/db_snapshots/ a do gitu nejdou. Obnovit jde jen do stejného druhu a verze databáze.

  • Snapshot pojmenovaný seed použije DDEV automaticky pro každou novou databázi projektu, třeba po ddev delete.
  • ddev start --reset-database začne s prázdnou databází a tu původní předtím uloží snapshotem.

Klient databáze s grafickým rozhraním. Klient nainstalovaný na počítači spustí DDEV rovnou s připojením na aktuální port: ddev dbeaver na všech systémech, ddev tableplus na macOS a ve WSL2. Příkaz nabídne, jen když aplikaci na obvyklém místě najde. Kdo používá jiný klient, nastaví si pevný host_db_port. Bez instalace na počítač poslouží webový Adminer jako add-on (ddev add-on get ddev/ddev-adminer, pak ddev adminer).

ddev pull stáhne databázi a soubory z hostingu přes provider v .ddev/providers/. Dump z produkce dnes ale obvykle připraví CI nebo deployer, a ten se pak nahraje přes ddev import-db. ddev auth ssh předá kontejneru klíče z hostitele, třeba pro Composer se soukromými repozitáři přes SSH.

Produkční data obvykle obsahují osobní údaje. Na počítač vývojáře patří jen to, co práce vyžaduje: obsah bez uživatelů (pg_dump --table=…), nebo dump, který osobní údaje cestou anonymizuje.

Nahrané soubory. Adresáře z upload_dirs plní ddev import-files.

Ladění a výkon:

  • ddev xdebug on a off přepíná Xdebug bez restartu, ddev xdebug status ukáže stav. Zapnutý zpomaluje každý požadavek, proto ne xdebug_enabled: true v configu. V IDE mapujte celý projekt na /var/www/html, ne jen docroot. Když se debugger nepřipojí, ddev utility xdebug-diagnose řekne proč.
  • ddev xhprof a ddev xhgui zapnou profilování a jeho rozhraní. Na otázku „proč je tahle stránka pomalá“ to stačí bez Blackfire.
  • ddev logs -f sleduje výstup webserveru, PHP a démonů, ddev logs -s db databáze.

Přehled a přístup:

  • ddev describe vypíše adresy, porty a služby projektu, ddev launch otevře web, ddev tui interaktivní přehled.
  • ddev share vystaví projekt na veřejnou adresu, výchozí přes ngrok, --provider=cloudflared bez účtu. Hodí se na ukázku klientovi nebo test webhooku. Adresa je veřejná, dokud tunel běží.
  • Plugin DDEV Integration pro PhpStorm nastaví interpret PHP, databázi a Node podle běžícího projektu.

Drobnosti, které ušetří čas:

  • Cache Composeru je sdílená mezi projekty, druhá instalace stejných balíčků jde z disku.
  • .ddev/homeadditions/ se nakopíruje do domovského adresáře v kontejneru. Hodí se na společné aliasy (.bash_aliases) celého týmu. Osobní věci (.gitconfig, historie) patří do ~/.ddev/homeadditions/ na hostiteli.
  • ddev composer, ddev npm, ddev yarn, ddev php a ddev console spouštějí nástroje v kontejneru. Na hostiteli PHP ani Node nepotřebujete a verze se tak nerozjedou.

Rozšíření PHP a web image

Balíčky z Debianu, typicky rozšíření PHP, se přidávají v config.yaml. Proměnná drží balíček u zvolené verze PHP:

yaml
webimage_extra_packages:
    - php${DDEV_PHP_VERSION}-imagick
    - php${DDEV_PHP_VERSION}-pcov
    - chromium
    - chromium-driver

Na složitější úpravy je .ddev/web-build/Dockerfile.<účel>. Každá úprava do vlastního souboru, aby bylo vidět, proč tam je. Hodí se například na nastavení jen pro PHP-FPM (viz Limity) nebo na dotažení balíčků PHP na nejnovější opravnou verzi. Web image může nést starší opravné vydání PHP, než má repozitář balíčků, a roave/security-advisories pak zablokuje composer update:

dockerfile
# .ddev/web-build/Dockerfile.php-upgrade
RUN apt-get update \
    && apt-get install -y --only-upgrade $(dpkg-query -W -f='${db:Status-Status} ${Package}\n' "php${DDEV_PHP_VERSION}-*" | awk '$1 == "installed" { print $2 }') \
    && rm -rf /var/lib/apt/lists/*

Změna se projeví po ddev restart. Když je potřeba sestavit image bez cache, ddev utility rebuild.

Web image má jen několik locale a české mezi nimi není. Kdo potřebuje setlocale() nebo strftime s cs_CZ, přidá do webimage_extra_packages balíček locales-all. Intl a ICU na to nepotřebuje.

Databáze

Stejný druh a hlavní verze databáze jako v produkci, jinak se rozdíly v SQL, řazení nebo JSON funkcích ukážou až po nasazení.

Rozšíření databáze (pgvector, PostGIS, slovník pro fulltext) se doinstalují přes .ddev/db-build/Dockerfile nad obrazem, ze kterého DDEV databázi staví:

dockerfile
# .ddev/db-build/Dockerfile
RUN apt-get update \
    && DEBIAN_FRONTEND=noninteractive apt-get install -y --no-install-recommends \
        "postgresql-${PG_MAJOR}-pgvector" "postgresql-${PG_MAJOR}-postgis-3" \
    && rm -rf /var/lib/apt/lists/*

Image jen dodá binárky. CREATE EXTENSION IF NOT EXISTS patří do migrace Doctrine, aby databázi v DDEV, v testech i v produkci zakládala stejná cesta. Skript v docker-entrypoint-initdb.d proběhne jen při prvním založení databáze a v produkci vůbec.

Build context je adresář .ddev/db-build/. Soubory sdílené s produkčním Dockerfile (skript, seznam stopslov) tam musí ležet jako kopie, symlink ven nefunguje. Shodu kopií pohlídá jednořádkový diff v CI.

Řazení a locale. PostgreSQL v DDEV vzniká s locale z glibc, kde diakritika splývá se základním písmenem. Když produkce zakládá cluster s ICU a českým locale, řadí jinak a rozdíl se ukáže až v produkci. Pomůže přepsat proměnnou databázového kontejneru:

yaml
# .ddev/docker-compose.postgres-locale.yaml
services:
  db:
    environment:
      POSTGRES_INITDB_ARGS: "--locale-provider=icu --icu-locale=cs-CZ"

Platí jen při prvním založení clusteru. Na existující databázi je potřeba ddev delete -O a data nahrát znovu. Ověření: ddev psql -U db -d db -tAc "select datlocprovider, datlocale from pg_database where datname = current_database()" má vrátit i|cs-CZ.

Testovací databáze vedle vývojové. Doctrine k názvu přidá příponu:

yaml
# config/packages/doctrine.yaml
when@test:
    doctrine:
        dbal:
            dbname_suffix: '_test%env(default::TEST_TOKEN)%'

Jednou ji založit (ddev console doctrine:database:create --env=test --if-not-exists) a po každé migraci aktualizovat (ddev console doctrine:migrations:migrate --env=test -n). TEST_TOKEN oddělí databáze souběžných procesů ParaTestu.

Port databáze na hostiteli se mění s každým restartem. Pro klienta v IDE ho zjistí ddev describe, nebo ho napevno nastaví host_db_port v config.local.yaml, každému projektu jiný.

Import, export a snapshoty jsou v kapitole Co DDEV přináší navíc.

Vite a HMR

Vite běží v kontejneru, prohlížeč na hostiteli. Aby HMR fungovalo, port musí projít routerem a Vite musí znát veřejnou adresu projektu:

yaml
# .ddev/config.yaml
web_extra_exposed_ports:
    - name: vite
      container_port: 5173
      http_port: 5172
      https_port: 5173

Vyplňte všechna tři pole, bez https_port se router nespustí.

javascript
// vite.config.js
import { resolve } from 'node:path'

const origin = `${process.env.DDEV_PRIMARY_URL_WITHOUT_PORT}:5173`

export default defineConfig({
    server: {
        host: '0.0.0.0',
        port: 5173,
        strictPort: true,
        origin,
        cors: { origin: /https?:\/\/([A-Za-z0-9\-.]+)?(\.ddev\.site)(?::\d+)?$/ },
        watch: {
            ignored: [resolve('vendor/**'), resolve('var/**')],
        },
    },
})
  • Adresu berte z DDEV_PRIMARY_URL_WITHOUT_PORT, ne natvrdo. Konfigurace pak funguje i v kopii projektu pod jiným jménem.
  • Vite sleduje celý kořen projektu. vendor/ a var/ vyčerpají limit sledovaných souborů, proto je vynechejte. Cesty musí být absolutní: projekt leží v kontejneru pod /var/www/html, takže vzor /var/ by vyřadil všechno.
  • Změnu Twigu nebo PHP Vite nezná. Krátký plugin, který při jejich změně pošle full-reload, ušetří ruční obnovování stránky.

Spouštět jde ručně (ddev npm run dev, výstup máte před očima), nebo automaticky s projektem přes web_extra_daemons. Výstup démona ukáže ddev logs -s web.

Messenger a Scheduler

Konzument front a plánovač jsou dlouho běžící procesy. DDEV je umí spouštět s projektem:

yaml
web_extra_daemons:
    - name: messenger
      command: 'while true; do bin/console messenger:consume async scheduler_default --time-limit=3600 --memory-limit=256M -vv; done'
      directory: /var/www/html

Démon drží načtený kód. Po změně handleru běží stará verze, dokud ho nerestartujete (ddev exec supervisorctl restart 'webextradaemons:*'). Možnosti:

  • Spouštět ho přes Symfony CLI, které ho při změně kódu restartuje samo: symfony run --watch=config,src,templates,vendor bin/console messenger:consume async -vv jako command démona.
  • Zprávy v dev směrovat na sync:// a konzumenta pouštět jen při ladění front (ddev console messenger:consume async -vv).

Stav plánovače a zámky potřebují sdílené úložiště (Redis, databáze). Bez něj začne plánovač po restartu od „teď“ a zmeškané běhy nedohání. Ve vývoji je to v pořádku, jen o tom vědět.

Další služby

Nejdřív add-on. ddev add-on get ddev/ddev-redis (dále OpenSearch, Elasticsearch, RabbitMQ, Solr, Adminer a další) přidá službu, která se spouští a zastavuje s projektem a kterou někdo udržuje. Úpravy add-onu do vlastního souboru, třeba .ddev/docker-compose.redis_extra.yaml. Soubory add-onu s #ddev-generated neupravujte, příští aktualizace by je přepsala.

Vlastní služba, když add-on není:

yaml
# .ddev/docker-compose.overpass.yaml
services:
  overpass:
    container_name: ddev-${DDEV_SITENAME}-overpass
    image: wiktorn/overpass-api
    restart: "no"
    expose:
      - "80"
    environment:
      - VIRTUAL_HOST=${DDEV_HOSTNAME}
      - HTTP_EXPOSE=12344:80
      - HTTPS_EXPOSE=12345:80
    volumes:
      - overpass_data:/db

volumes:
  overpass_data:
  • container_name podle konvence ddev-${DDEV_SITENAME}-…. Štítky com.ddev.site-name a com.ddev.approot doplňuje DDEV sám, starší verze je potřebovaly ručně, jinak ddev stop kontejner nechal běžet.
  • Webové rozhraní služby vystavte přes router (VIRTUAL_HOST, HTTP_EXPOSE, HTTPS_EXPOSE), ne přes ports. Router zvládne víc projektů naráz bez kolize portů.
  • ports jen pro ne-HTTP službu, kterou potřebuje proces na hostiteli, a vždy s 127.0.0.1: na začátku. Bez něj Docker publikuje port na všechna rozhraní a jeho pravidla obejdou i firewall hostitele. Redis bez hesla by pak četl a zapisoval kdokoli ze stejné sítě.
  • Volume s daty, jejichž příprava trvá dlouho (index map, import číselníků), pojmenujte. Přežije ddev restart a dá se zkopírovat do jiné kopie projektu.

Mailpit, Xdebug, XHProf a sdílení ven DDEV už má (viz Co DDEV přináší navíc). Nepřidávejte je znovu.

Služba na hostiteli. Proces, který běží na hostiteli (například Ollama kvůli GPU), je z kontejneru dostupný přes host.docker.internal. Musí poslouchat i mimo loopback (OLLAMA_HOST=0.0.0.0).

Frontend v DDEV, ne vedle. Samostatná frontendová aplikace (Next.js, Nuxt) jde spustit jako další web_extra_daemons s vlastním web_extra_exposed_ports. Když ji pustíte na hostiteli kvůli localhost:3000 v OAuth redirect_uri, máte dvě prostředí, porty publikované ven a dvojí návod. Jednodušší je zaregistrovat redirect_uri na adrese z DDEV.

Shoda s produkcí

DDEV má výchozí hodnoty pro vývoj: memory_limit 1024M, upload_max_filesize a post_max_size 100M, max_execution_time 600 s, nginx bez limitu velikosti požadavku. Požadavek, který produkce odmítne, tak lokálně projde a větev s chybovou hláškou nikdo nevyzkouší. Limity z produkce proto nastavte i v DDEV. PHP načte každý soubor .ddev/php/*.ini, nginx každý .ddev/nginx/*.conf, název souboru je na vás. Projeví se po ddev restart. Ukázka je jen příklad s výchozími hodnotami PHP, v projektu je nahraďte hodnotami z jeho produkce:

bash
; .ddev/php/limits.ini — příklad, platí pro CLI i FPM
; výchozí hodnoty PHP, nahraďte hodnotami z produkce
upload_max_filesize = 2M
post_max_size = 8M
max_execution_time = 30
nginx
# .ddev/nginx/limits.conf — příklad, DDEV ho vloží na konec bloku server
# stejně jako post_max_size v PHP
client_max_body_size 8m;
  • Přebírat celý nginx_full/nginx-site.conf kvůli jedné direktivě znamená starat se o konfiguraci, kterou by jinak udržoval DDEV.
  • .ddev/php/*.ini platí pro CLI i FPM naráz. CLI ale může potřebovat vyšší limity, například memory_limit kvůli PHPStanu nebo dávkovým importům. Nastavení jen pro FPM zapečte do image:
dockerfile
# .ddev/web-build/Dockerfile.fpm-limits
RUN printf 'memory_limit = 256M\n' > /etc/php/${DDEV_PHP_VERSION}/fpm/conf.d/zz-limits.ini
  • Shodu hodnot mezi .ddev/, produkčním Dockerfile a Caddyfile může hlídat obyčejný test, který soubory přečte a porovná. Pozor na jednotky: 30MB v Caddy je 30 × 1000², 30M v PHP a 30m v nginx 30 × 1024².

Jiný runtime v produkci. Když produkce běží na FrankenPHP v worker módu, DDEV s nginx a PHP-FPM únik stavu mezi požadavky neukáže. Pravidla pro worker mód (bez stavu ve službách, ResetInterface) dodržujte od začátku. Lokálně jde worker mód vyzkoušet s add-onem ddev/ddev-frankenphp, který sám přepne webserver_type: generic. Má to svou cenu:

  • Worker mód se zapíná v FRANKENPHP_CONFIG. Kernel pak přežívá mezi požadavky, takže změna v src/ nebo config/ se projeví až po restartu workeru (ddev exec supervisorctl restart 'webextradaemons:*'). Restart při změně zařídí direktiva watch, jen s cestami ke zdrojům. Výchozí vzor sleduje celý projekt včetně var/cache/, kam Symfony za běhu zapisuje PHP soubory.
yaml
# .ddev/docker-compose.frankenphp_extra.yaml
services:
  web:
    environment:
      FRANKENPHP_CONFIG: |
        worker {
          file ./public/index.php
          watch ./src/**/*.php
          watch ./config/**/*.{php,yaml}
          watch ./.env*
        }
  • PHP je ZTS build z jiného repozitáře, jen od verze 8.2. Rozšíření se instalují jako php-zts-…, ta, která v něm nejsou, se kompilují přes PIE.
  • CLI i web sdílejí jednu konfiguraci PHP. Limity jen pro web patří do php_ini ve FRANKENPHP_CONFIG. Místo .ddev/nginx/ se upravuje Caddyfile.

Výchozím prostředím týmu proto zůstává FPM a worker mód se zapíná cíleně, když je podezření na únik stavu.

IP klienta. DDEV předává PHP HTTPS=on, takže Symfony generuje adresy s https:// i bez nastavení proxy. REMOTE_ADDR je ale adresa routeru. Když na IP záleží (rate limiter, logy), nastavte trusted_proxies stejně jako za proxy v produkci.

Produkční image staví vlastní Dockerfile. DDEV je vývojové prostředí, ne předloha produkce. Co musí sedět mezi nimi, ať je napsané na obou místech a hlídané testem.

Hooks a vlastní příkazy

post-start proběhne při každém ddev start. Patří tam jen to, bez čeho aktuální kód nepoběží, a musí být idempotentní:

yaml
hooks:
    post-start:
        - composer: install
        - exec: bin/console doctrine:migrations:migrate --no-interaction --allow-no-migration

Stahování překladů, import číselníků z externího zdroje nebo build assetů v hooku start zpomalí na minuty a při výpadku sítě selže. Selhání hooku start ve výchozím nastavení nezastaví (fail_on_hook_fail: false), takže chyba snadno zapadne. Takové kroky patří do vlastního příkazu.

Vlastní příkazy jsou skripty v .ddev/commands/web/ (běží v kontejneru) nebo .ddev/commands/host/ (na hostiteli). Hlavička je nápověda pro ddev help:

bash
#!/usr/bin/env bash
## Description: Připraví projekt po klonu: závislosti, databáze, číselníky, překlady
## Usage: setup
## Example: "ddev setup"
set -euo pipefail

composer install
bin/console doctrine:migrations:migrate -n --allow-no-migration
bin/console app:codelist:import
bin/console translation:pull crowdin --force
npm ci && npm run build

Vhodné kandidáty: ddev setup po klonu, ddev test-db na založení a migraci testovací databáze, ddev e2e na end-to-end testy. Makefile pak volá ddev exec nebo vlastní příkazy a nemusí znát cesty uvnitř kontejneru.

Skript v .ddev/web-entrypoint.d/*.sh se sourcuje při startu kontejneru ještě před PHP-FPM. Běží ve shellu startovacího skriptu, takže nenastavujte vlastní set a pamatujte, že exit 1 ukončí start celého kontejneru. Většinu toho, co se tam píše, zvládne čistěji web-build/Dockerfile.

Testy

PHPUnit běží v kontejneru: ddev exec vendor/bin/phpunit. Pokrytí měří PCOV z webimage_extra_packages, rychlejší než Xdebug. Omezte ho na zdrojový kód, jinak prochází i vendor/ a node_modules/:

bash
; .ddev/php/pcov.ini
pcov.directory = /var/www/html/src

Xdebug zapínejte jen na ladění (ddev xdebug on, ddev xdebug off). Zapnutý zpomaluje každý požadavek.

End-to-end testy s Pantherem jdou celé v DDEV:

  • Chromium a chromedriver z webimage_extra_packages. Chrome v kontejneru potřebuje PANTHER_NO_SANDBOX=1 a PANTHER_CHROME_ARGUMENTS="--disable-dev-shm-usage" v .env.test.
  • Druhá adresa projektu přes additional_hostnames: [test.projekt] a vlastní blok server v .ddev/nginx_full/test-env.conf, který předá PHP-FPM fastcgi_param APP_ENV test. Hlavní adresa dál slouží vývoji, testovací běží proti testovací databázi s falešnými platebními bránami a hodinami.
  • Testovací dvojníci musí být zapojení v konfiguraci prostředí test. self::getContainer()->set() v testu změní jen kontejner testu, ne ten, který obsluhuje požadavky prohlížeče. Stav mezi procesy si předávají přes soubory.
  • Před sadou zahřát několik požadavků na testovací adresu, aby se kontejner načetl do OPcache ve všech workerech FPM. Jinak první testy náhodně padají na timeoutu.
  • Celé to zabalit do příkazu ddev e2e.

Více kopií projektu vedle sebe

Dvě rozpracované větve najednou, frontend nové funkce proti její verzi backendu, review cizí větve, agent nebo dlouhá sada testů vedle práce. Přepínat větve v jednom adresáři znamená pokaždé přepnout i databázi, protože každá větev má jiné migrace. Lepší je mít každou větev ve vlastním adresáři (git worktree) jako vlastní DDEV projekt s vlastní databází. Dvě kopie se stejným name se o kontejnery přou.

Jméno podle adresáře. Když config.yaml nemá name, projekt se jmenuje podle adresáře. Každý klon i git worktree má pak vlastní kontejnery, adresu a databázi bez dalšího nastavování. Aby ddev config jméno do souboru sám nezapsal, nastavte ddev config global --omit-project-name-by-default=true. Když jméno v config.yaml zůstat musí, přepíše ho kopie v config.local.yaml:

yaml
override_config: true
name: projekt2
additional_hostnames: [test.projekt2]
additional_fqdns: []

Nic se jménem nebo portem natvrdo. Kopie se neperou, jen když sdílená konfigurace nedrží nic, co musí být v každé kopii jiné:

  • Adresa projektu v kódu a ve vite.config.js → proměnné prostředí DDEV_PRIMARY_URL a DDEV_PRIMARY_URL_WITHOUT_PORT. DDEV je nastaví ve web kontejneru, ve vlastních příkazech a při dosazování do compose souborů. V shellu hostitele nejsou.
  • additional_hostnames se jménem projektu a pevné porty (host_db_port, host_https_port) → config.local.yaml, jinak porty přidělí DDEV.
  • Port vlastní služby publikovaný na hostitele → proměnná s výchozí hodnotou v compose a jiná hodnota pro každou kopii v gitignorovaném .ddev/.env.*.local. Soubor, jehož jméno neodpovídá žádné službě, se jen dosadí do compose a do kontejnerů se nedostane:
yaml
# .ddev/docker-compose.redis_extra.yaml
services:
  redis:
    ports:
      - "127.0.0.1:${REDIS_HOST_PORT:-6379}:6379"
bash
ddev dotenv set .ddev/.env.ports.local --redis-host-port 6380

Frontend se svou verzí backendu. Frontend ve větvi potřebuje backend ze stejné větve, ne ten, který zrovna běží v hlavním adresáři.

  • Frontend a backend v jednom repozitáři: worktree obsahuje obojí ve správné verzi. Když frontend běží v DDEV přes web_extra_daemons a web_extra_exposed_ports jako Vite, najde backend své kopie přes DDEV_PRIMARY_URL a služby jako Redis přes jméno služby (redis:6379) bez publikovaného portu. Kopie si nemají co přebírat a nová nepotřebuje žádné nastavení.
  • Frontend na hostiteli proměnné DDEV nevidí, takže každá kopie musí publikovat jiný port služeb, které frontend potřebuje, a jeho .env.local musí mířit na adresu a porty backendu své kopie. Funguje to, ale každá kopie znamená ruční nastavení na dvou místech. Když frontend na hostiteli drží adresa registrovaná natvrdo, třeba OAuth redirect_uri na localhost:3000, vyplatí se ji v lokálních datech odvodit z DDEV_PRIMARY_URL a frontend přesunout do DDEV.
  • Frontend a backend v různých repozitářích: worktree backendu pojmenovat podle větve, aby měl předvídatelnou adresu (https://<vetev>-api.ddev.site), a frontend té větve nasměrovat na ni.

Data do nové kopie:

  1. Zkopírovat ignorované soubory (.env.local, auth.json, nahraná data).
  2. Databázi přenést snapshotem: ddev snapshot --name copy ve zdroji, přesunout soubor z .ddev/db_snapshots/ a v kopii ddev snapshot restore copy.
  3. Pojmenované volume s drahými daty zkopírovat přes docker run --rm -v zdroj:/from:ro -v cil:/to … cp -a /from/. /to/.

Celé to patří do jednoho skriptu, který kopii založí stejně pokaždé. Nepoužívané kopie zastaví ddev stop, všechno naráz ddev poweroff.

macOS a Windows

Na Linuxu a ve WSL2 jdou soubory do kontejneru přímo. Na macOS a Windows DDEV ve výchozím stavu synchronizuje přes Mutagen:

  • Adresáře, které se nemají synchronizovat (nahraná data, node_modules), dejte do upload_dirs, pak ddev mutagen reset.
  • Git pouštějte na hostiteli. Po přepnutí větve pomůže ddev mutagen sync, nejlépe z git hooku post-checkout.
  • performance_mode necommitujte. Patří do globální konfigurace nebo config.local.yaml, kolega na jiném systému ho nechce.
  • Ve WSL2 musí projekt ležet v souborovém systému Linuxu, ne na /mnt/c. Rozdíl v rychlosti je řádový.

Přístup z místní sítě a sdílení ven

Projekt je standardně dostupný jen z vlastního počítače. Z jiného zařízení v síti, třeba telefonu, tabletu nebo počítače kolegy, se k němu dostanete takto:

  • Router musí poslouchat na všech rozhraních: ddev config global --router-bind-all-interfaces=true. Firewall počítače musí pustit porty 80 a 443.
  • Adresa s IP počítače přes nip.io do config.local.yaml (IP se liší počítač od počítače):
yaml
additional_fqdns:
    - projekt.192.168.0.10.nip.io
  • Některé routery a DNS filtry odpovědi s místní IP zahazují (ochrana proti DNS rebinding). Pak pomůže záznam v hosts druhého zařízení nebo jiný DNS server.
  • Druhé zařízení nezná certifikační autoritu z mkcert, takže HTTPS bude hlásit chybu. Buď ji tam nainstalovat, nebo zkoušet přes HTTP, pokud aplikace HTTPS nevynucuje.
  • Mimo místní síť pomůže ddev share.

Časté ohnutí a lepší cesta

  • Vlastní kontejner s Mailpitem → vestavěný Mailpit a smtp://127.0.0.1:1025.
  • Ručně psaný Redis v compose → ddev add-on get ddev/ddev-redis a úpravy v _extra souboru.
  • Kopie nginx-site.conf kvůli jedné direktivě → soubor v .ddev/nginx/.
  • Natvrdo zapsaná adresa projektu ve vite.config.js → DDEV_PRIMARY_URL_WITHOUT_PORT.
  • docker exec ddev-projekt-db psql v návodech → ddev psql, ddev import-db, ddev snapshot.
  • Port databáze opisovaný do dokumentace → ddev describe nebo host_db_port.
  • Build a stahování z externích služeb v post-start → vlastní příkaz ddev setup.
  • DATABASE_URL nebo MAILER_DSN ručně v .env.local nebo ve web_environment → nechat na DDEV, testům .env.test.
  • Frontend na hostiteli vedle DDEV → web_extra_daemons a web_extra_exposed_ports.
  • Init SQL skript na CREATE EXTENSION → migrace Doctrine.
  • Upozornění „po stažení změn spusťte ddev restart“ v README → zvyk po každé změně v .ddev/. DDEV sám při startu vypíše, že našel vlastní konfiguraci, a připomene restart. Co přesně z .ddev/ platí a v jakém pořadí, vypíše ddev utility check-custom-config.

Štítky Backend, PHP

Sdílet LinkedIn Facebook

Potřebujete víc než článek?

Stačí pár vět o tom, co řešíte.