xm / starter_symfony_4
Starter for creating Symfony 4/5/6 sites at XM Media
Requires
- php: ~8.5.0
- ext-ctype: *
- ext-iconv: *
- ext-json: *
- ext-mbstring: *
- ext-pcntl: *
- ext-pdo: *
- ext-zlib: *
- doctrine/doctrine-bundle: ^3.0
- doctrine/doctrine-migrations-bundle: ^4.0
- doctrine/orm: ^3.0
- egulias/email-validator: ^4.0
- knplabs/knp-paginator-bundle: ^6.0
- moneyphp/money: ^4.0
- nesbot/carbon: ^3.0
- odolbeau/phone-number-bundle: ^4.0
- overblog/graphql-bundle: ^1.0
- pentatrion/vite-bundle: ^8.0
- phpoffice/phpspreadsheet: ^5.0
- prooph/event-store-bus-bridge: ^3.3
- prooph/event-store-symfony-bundle: ^0.12
- prooph/pdo-event-store: ^1.15.0
- ramsey/uuid: ^4.0
- ramsey/uuid-doctrine: ^2.0
- scienta/doctrine-json-functions: ^6.0
- sentry/sentry-symfony: ^5.14
- symfony/asset: *
- symfony/console: *
- symfony/doctrine-messenger: *
- symfony/dotenv: *
- symfony/expression-language: *
- symfony/flex: ^2.0
- symfony/form: *
- symfony/framework-bundle: *
- symfony/http-client: *
- symfony/mailer: *
- symfony/messenger: *
- symfony/monolog-bundle: ^4.0
- symfony/postmark-mailer: *
- symfony/process: *
- symfony/property-access: *
- symfony/property-info: *
- symfony/rate-limiter: *
- symfony/runtime: *
- symfony/security-bundle: *
- symfony/serializer: *
- symfony/string: *
- symfony/translation: *
- symfony/twig-bundle: *
- symfony/validator: *
- symfony/yaml: *
- symfonycasts/reset-password-bundle: ^1.20
- tecnickcom/tcpdf: ^7.0
- twig/extra-bundle: ^3.0
- twig/twig: ^3.5
- webmozart/assert: ^2.4
- xm/symfony-bundle: ^2.0
Requires (Dev)
- ekino/phpstan-banned-code: ^3.0
- ergebnis/composer-normalize: ^2.43
- fakerphp/faker: ^1.8
- friendsofphp/php-cs-fixer: ^3.0
- jetbrains/phpstorm-attributes: ^1.0
- mockery/mockery: ^1.2
- phpstan/phpstan: ^2.0
- phpstan/phpstan-deprecation-rules: ^2.0
- phpstan/phpstan-doctrine: ^2.0
- phpstan/phpstan-mockery: ^2.0
- phpstan/phpstan-phpunit: ^2.0
- phpstan/phpstan-symfony: ^2.0
- phpstan/phpstan-webmozart-assert: ^2.0
- phpunit/phpunit: ^13.2
- rector/rector: ^2.0
- symfony/apache-pack: ^1.0
- symfony/browser-kit: *
- symfony/css-selector: *
- symfony/debug-bundle: *
- symfony/maker-bundle: ^1.0
- symfony/phpunit-bridge: *
- symfony/stopwatch: *
- symfony/web-profiler-bundle: *
Suggests
None
Provides
None
Conflicts
Replaces
- paragonie/random_compat: ^2.0
- symfony/polyfill-ctype: *
- symfony/polyfill-iconv: *
- symfony/polyfill-php56: *
- symfony/polyfill-php70: *
- symfony/polyfill-php71: *
- symfony/polyfill-php72: *
- symfony/polyfill-php73: *
- symfony/polyfill-php74: *
- symfony/polyfill-php80: *
- symfony/polyfill-php81: *
- symfony/polyfill-php82: *
- symfony/polyfill-php83: *
- symfony/polyfill-php84: *
- symfony/polyfill-php85: *
This package is auto-updated.
Last update: 2026-11-16 03:25:39 UTC
README
Used to create new projects using Symfony 7 at XM Media.
Local/Dev: https://symfonystarter.ddev.site @todo-symfony
Staging: @todo-symfony
Production: @todo-symfony
Setting Up a New Site
Note: Make sure your git configuration is set to use the correct line endings: git config --global core.autocrlf input && git config --global core.eol lf
- Create a new project:
composer create-project xm/starter_symfony_4 project-name --stability=dev --no-install --remove-vcs
To run this, Composer needs to be installed globally. If you don't have Composer installed, follow the instructions at getcomposer.org/download. - Copy
.env.local-templateto.env.localand update the values where there are@todo-symfonycomments. - Update
composer.json:name,license(likelyproprietary) anddescription - Update
package.json:name,version,git.url,license(probably delete),private - Update the project
namein.ddev/config.yaml(the local site ishttps://<name>.ddev.site) - Remove or update the
LICENSEfile. - Run/Start the DDEV site:
ddev start - Composer install & update:
ddev composer install && ddev composer update(or without DDEV or without memory limit:php -d memory_limit=-1 /usr/local/bin/composer update) - Run
ddev yarn install && ddev yarn up -R "**". - Run
ddev yarn dev(dev) orddev yarn build(production) to compile JS & CSS files. - Give executable perms to bin dir:
chmod u+x bin/*(helpful, but optional) - Create database with event streams & projections tables from
db_create.sqlusingddev import-db --file=db_create.sql.- DDEV sets the database collation to
utf8mb4_0900_binon start (.ddev/mysql/collation.cnf& thepost-starthook in.ddev/config.yaml)
- DDEV sets the database collation to
- Create the required event streams with the command:
bin/console event-store:event-stream:create user && bin/console event-store:event-stream:create auth(or if using DDEV:ddev console event-store:event-stream:create user && ddev console event-store:event-stream:create auth). - Run all projections once:
bin/console app:projection:run user -o && bin/console app:projection:run auth -o && bin/console app:projection:run auth_log -o(or if using DDEV:ddev console app:projection:run user -o && ddev console app:projection:run auth -o && ddev console app:projection:run auth_log -o). - Create a user
bin/console app:user:add(select roleROLE_SUPER_ADMIN) (or if using DDEV:ddev console app:user:add). - Find and make changes near
@todo-symfonycomments throughout the site. - Delete starter files:
README.md(or update) andTEMPLATES.md. - Optional: Run
composer test– will install PHPUnit & run PHP tests - Create new favicons: realfavicongenerator.net
- Copy (use "Push to another server") or recreate the templates in Postmark. The templates are referenced by the aliases.
- Optional: Run
bin/console app:graphql:dump-schema <username>to update the GraphQL schema file whereusernameis the email of an admin user. - Optional: Rename the project in PhpStorm.
- Update the Sentry
org&projectinvite.config.mjs. Source maps are uploaded by the deploy when theSENTRY_AUTH_TOKENCI variable is set (bin/setup_gitlab_ci_varsasks for it).
Local dev site can be accessed at: https://[domain]/
Setting Up Starter
- Checkout the repo.
- Copy
.env.local-templateto.env.localand update the values where there are@todo-symfonycomments. - Run/Start the DDEV site:
ddev start - Composer install:
ddev composer installorcomposer installto run without DDEV. - Run
ddev yarn install. - Run
ddev yarn dev(dev) orddev yarn build(production) to compile JS & CSS files. - Give executable perms to bin dir:
chmod u+x bin/*(helpful, but optional) - Create database with event streams & projections tables from
db_create.sqlusingddev import-db --file=db_create.sql.- DDEV sets the database collation to
utf8mb4_0900_binon start (.ddev/mysql/collation.cnf& thepost-starthook in.ddev/config.yaml)
- DDEV sets the database collation to
- Create the required event streams with the command:
bin/console event-store:event-stream:create user && bin/console event-store:event-stream:create auth(or if using DDEV:ddev console event-store:event-stream:create user && ddev console event-store:event-stream:create auth). - Run all projections once:
bin/console app:projection:run user -o && bin/console app:projection:run auth -o && bin/console app:projection:run auth_log -o(or if using DDEV:ddev console app:projection:run user -o && ddev console app:projection:run auth -o && ddev console app:projection:run auth_log -o). - Create a user
bin/console app:user:add(select roleROLE_SUPER_ADMIN) (or if using DDEV:ddev console app:user:add). - Optional: Run
composer test– will install PHPUnit & run PHP tests – orddev composer testif using DDEV. - Run
bin/checkto run all code tests/checks.
**Local dev site can be accessed at: https://symfonystarter.ddev.site
Setting Up a Server
bin/setup_staging.sh & bin/setup_prod.sh run on the server. The other setup scripts run locally.
For sites on an InterWorx server, bin/provision_site (run locally) does the whole setup:
1Password items, the SiteWorx account, the database, setup_staging.sh/setup_prod.sh, shared/.env.local
(the repo's .env with the environment, app secret, database & request context filled in), the Messenger worker
& log rotation cron jobs, the GitLab CI/CD variables and the CI public key in the site user's ~/.ssh/authorized_keys.
- Requires an ssh Host with passwordless sudo,
opsigned in,glabauthenticated andjqinstalled. - It asks whether you're provisioning staging or production, then prompts for everything else and shows a summary before making any changes.
- The remaining manual steps (DNS record, SSL certificate, completing
shared/.env.local, first deploy, database) are printed at the end. The DNS record doesn't need to exist beforehand — it's only needed before generating the SSL certificate.
To do it by hand instead:
- Upload
bin/setup_staging.sh(orbin/setup_prod.sh) to the domain dir, where thehtmldir is, and run it:bash ./setup_staging.sh. It creates thereleases/sharedstructure & the links (html→current/public), switches PHP to the minimum version if it's older and installs oh-my-zsh (plus nvm & Composer on staging).- The staging script can be run more than once. The prod script stops if the
releasesdir already exists.
- The staging script can be run more than once. The prod script stops if the
- Fill in
shared/.env.localon the server. The script creates it empty, and each deploy copies it into the release. - Locally, run
bin/setup_gitlab_ci_vars <group/project>once per scope (staging, production) to set the GitLab CI/CD variables. It needsglab(authenticated) &jq. If it generates an SSH key, add the public key it prints to the server's~/.ssh/authorized_keys. See--helpfor the options that pre-fill its prompts. - Run the deploy job in GitLab.
Cron Jobs
bin/provision_site adds the Messenger worker & log rotation jobs. To add them by hand, or any others, add them in
SiteWorx (Cron), replacing [site_base] with the domain dir, where current is:
- Start a Messenger worker every 5 minutes, unless one's running (
flock). The worker exits after an hour, or when a deploy runsmessenger:stop-workers, & the next run starts a new one:*/5 * * * * cd [site_base]/current && flock -n var/messenger.lock bin/console messenger:consume async --time-limit=3600 --memory-limit=128M --quiet 2>&1 - Rotate the logs in
var/log/(config/packages/logrotate.conf), every Monday at 3am.var/is shared between releases, so the state file is kept across deploys:0 3 * * 1 cd [site_base]/current && /usr/sbin/logrotate config/packages/logrotate.conf --state var/logrotate-state
Environments
dev– local development, via DDEVtest– automated testsstaging– the site customers preview & test on, set up withbin/setup_staging.shprod– the live site, set up withbin/setup_prod.sh
staging is a customer-facing site, so it's configured to behave like prod, not like dev:
.env.stagingsetsAPP_DEBUG=0. Symfony treats every env exceptprodas a debug env by default (Dotenv::bootEnv()), which would expose stack traces & slow the site down- The
when@prodblocks inconfig/packages/are shared withstagingthrough a YAML anchor (when@prod: &prod/when@staging: *prod), so the two can't drift apart. This covers monolog handlers, Sentry, the doctrine query/result caches & the router'sstrict_requirements SentryBundleis enabled for bothprod&staginginconfig/bundles.phpframework.disallow_search_engine_indexis on forstagingso the preview site isn't indexed- The GitLab
deploy to stagingjob installs & builds the same waydeploy to proddoes (composer install --no-dev,yarn build)
Anything genuinely staging-only belongs in a when@staging block of its own, below the alias.
TRUSTED_PROXIES must be set per environment, in that environment's own .env.local
(on the servers: shared/.env.local). It applies in every env, not just dev — deployed sites
sit behind a proxy/CDN, and without it the client IP recorded in the auth log & the scheme used
for cookie security come from the proxy rather than the real client. It defaults to empty (trust
nothing). Set it no wider than the proxies actually in front of the app:
- behind Cloudflare only – the Cloudflare IP ranges
- behind a local reverse proxy –
private_ranges - a single proxy on the same box (DDEV's router does this) –
127.0.0.1,REMOTE_ADDR
System Requirements
Server
- PHP 8.5
- MySQL 8.4
Locally for Development
Run yarn through ddev yarn so the Node version matches .nvmrc. node_modules is synced
between the host & the container, so one ddev yarn install serves both. Host yarn still works,
but the Node version is then up to you.
Commands
- Run all checks:
bin/check_full- Note: this generates the GQL schema first, because within the checks we validate the graphql operations files
- Check all code:
bin/check - Generate GQL schema:
bin/generate_schema - Dev JS/CSS server with HMR:
ddev yarn dev(stop with Ctrl-C)- Stop one left running in the container:
ddev exec pkill -f '[v]ite/bin/vite.js' - Assets are proxied through Apache at
https://[domain]/vite-dev/, same-origin with the site (needed for the SVG icon sprites) — the Vite port isn't exposed. See.ddev/web-build/apache-vite.conf - A
503on a/vite-dev/…asset means the dev server isn't running
- Stop one left running in the container:
- Compile check:
ddev yarn build:check- Builds to
node_modules/.build-check, so it's safe to run while the dev server is running
- Builds to
- Production JS/CSS build:
ddev yarn build- Don't use this to verify a change — it rewrites
public/build, clobbering the manifest a running dev server relies on
- Don't use this to verify a change — it rewrites
- Preview a production build:
ddev yarn preview- Serves
public/buildathttps://[domain]:4173/build/, mirroring the production paths
- Serves
- JS Tests (Vitest):
ddev yarn test:unit - Linting:
- JS (ESLint):
ddev yarn lint:jsorddev yarn lint:js:fix - CSS:
ddev yarn lint:cssorddev yarn lint:css:fix
- JS (ESLint):
- Messenger worker:
ddev messenger– processes theasyncqueue (e.g. notification emails) until stopped with Ctrl-C, restarting on code changes - Install PHP packages:
ddev composer installorcomposer install - Install JS packages:
ddev yarn install— also the fix forCouldn't find the node_modules state file - PHP Tests (PhpUnit):
ddev composer testorcomposer test- no memory limit
php -d memory_limit=-1 bin/phpunit - with coverage (HTML)
composer test:coverage - show deprecations
composer test:deprecations
- PHP CS:
- Dry run:
ddev composer csorcomposer cs - Fix:
ddev composer cs:fixorcomposer cs:fix
- Dry run:
- PHP Static Analysis (PHPStan):
ddev composer staticorcomposer static - Symfony diagnostics (Symfony Language Tools):
symfony lsp:check- Checks routes, services, Twig, translations & bundle config; runs on the host, not in DDEV
--source-onlyskips booting the app (what CI uses).symfony-lsp.jsonruns the app throughddev exec php(ddev phpwould sync Mutagen on every call), so runtime analysis doesn't depend on the host's PHP version — editors share this config too- The Symfony CLI downloads & caches the Language Tools binary itself, outside the repo
- Projections:
- Show all commands:
bin/console event-store:projection - Run once:
bin/console event-store:projection:run user_projection -o
- Show all commands:
- Makers (PHP):
- Make aggregate root/model (including its projection):
bin/console make:model
- Make aggregate root/model (including its projection):
- Upgrade JS packages:
ddev yarn up -R "**"- Upgrade a specific package:
ddev yarn up -R "package-name" - Upgrade major versions:
ddev yarn upgrade-interactive(ctrl+c to exit without changes) - Upgrade a package, ignoring the age gate:
ddev yarn up:bypass <package>
- Upgrade a specific package:
Incorporated Libraries & Tools
- DDEV – local dev environment
- Frontend – full list of dependencies can be found in package.json
- Vue – frontend framework
- Vue Router – routing package for frontend
- Vue Templates – the syntax for .vue files
- Vue Test Utils – to help testing Vue components
- Pinia - global state management
- Vite – frontend build tool
- Vitest – to manage & run the frontend testing
- GraphQL – the communication (query) language for the API
- Apollo Client through Vue Apollo – frontend GraphQL
- SVGO – optimizes SVG files
- Tailwind – utility first styling framework
- Lodash – helper functions for JS
- date-fns – helper functions for Dates in JS
- Faker.js – for generating fake data in tests
- ESLint – checks JS for conventions & errors
- Stylelint – checks CSS for conventions & errors
- Vue – frontend framework
- Backend – full list of dependencies can be found in composer.json
- Symfony – backend framework
- GraphQLBundle – provides GraphQL in PHP using graphql-php
- Doctrine – ORM
- Doctrine Migrations – for database migrations
- Symfony Messenger – for async messaging
- Symfony Mailer – for sending emails
- Symfony Security – for authentication & authorization
- Twig – server side templating language (limited use)
- Prooph PDO Event Store & Bridge/Bundle – for doing Event Sourcing
- Doctrine – for reading from read models
- PhpUnit – for running PHP tests
- PHP CS – PHP coding standards analyzer & fixer
- PHPStan – static analysis of PHP
- Symfony Language Tools – Symfony aware diagnostics (routes, services, Twig, translations, config), in the editor & in CI
- Postmark – for sending email, contains email templates (currently setup under XM Media's account)
- Cloudflare – DNS & CDN
- GitLab – deployment
- Sentry – error tracking
- Dev Tools
Updating PHP version
- Change version in
composer.json& add polyfill for new PHP version, ie,symfony/polyfill-php85. - Update the PHP version in the following files:
.ddev/config.yamlbin/setup_staging.sh&bin/setup_prod.sh– 4 places each.gitlab-ci.yml– 2 places.github/workflows/ci.yml– 1 place.php-cs-fixer.dist.php– update the@PHP8#Migrationversion to match the current version.~/.bashrcand/or~/.zshrcon the servers
- Run
ddev restartto switch the DDEV container to the new PHP version. - Run
ddev composer updateorcomposer updateto update the PHP dependencies. If running locally without DDEV, ensure your local PHP version matches the new version. - Run the checks
bin/check_full. - Update version in
README.md.
User Actions & Fields
User – Verified
Email address is verified. When the user is added by admin, this is always set to true. When a user registers themselves, this is set to false until they verify their email.
User – Active
User is active and can log in. When the user is added by admin, this is set to true when they're sent an invitation (invite) or false until they activate their account & set their password. When a user registers themselves, this is set to true.
Send Activation
Sends email to user to activate their account by entering their password. Uses a reset token and sets their account to active when complete.
Send Verification
For email/user verification after registering. Sends email to user to activate their account. They don't need to enter a password (already set on registration form). Uses a reset token and sets their account to verified when complete.