xm/starter_symfony_4

Starter for creating Symfony 4/5/6 sites at XM Media

dev-master 2025-08-19 23:14 UTC

Requires

• php: ~8.4.0
• ext-ctype: *
• ext-iconv: *
• ext-json: *
• ext-pcntl: *
• ext-pdo: *
• doctrine/doctrine-bundle: ^2.4
• doctrine/doctrine-migrations-bundle: ^3.1
• doctrine/orm: ^3.0
• egulias/email-validator: ^4.0
• knplabs/knp-paginator-bundle: ^6.0
• moneyphp/money: ^4.0
• nelmio/cors-bundle: ^2.3
• nesbot/carbon: ^3.0
• odolbeau/phone-number-bundle: ^4.0
• overblog/graphql-bundle: ^1.0
• pentatrion/vite-bundle: ^8.0
• phpdocumentor/reflection-docblock: ^5.2
• phpoffice/phpspreadsheet: ^5.0
• prooph/event-store-bus-bridge: ^3.3
• prooph/event-store-symfony-bundle: ^0.11
• prooph/pdo-event-store: 1.15.0
• ramsey/uuid: ^4.0
• ramsey/uuid-doctrine: ^2.0
• roave/security-advisories: dev-master
• scienta/doctrine-json-functions: ^6.0
• sentry/sentry-symfony: ^5.0
• 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: ^3.5
• symfony/postmark-mailer: *
• symfony/process: *
• symfony/property-access: *
• symfony/property-info: *
• symfony/proxy-manager-bridge: *
• symfony/runtime: *
• symfony/security-bundle: *
• symfony/serializer: *
• symfony/string: *
• symfony/templating: *
• symfony/translation: *
• symfony/twig-bundle: *
• symfony/validator: *
• symfony/web-link: *
• symfony/yaml: *
• symfonycasts/reset-password-bundle: ^1.20
• tecnickcom/tcpdf: ^6.6
• twig/extra-bundle: ^3.0
• twig/twig: ^3.5
• webmozart/assert: ^1.3
• 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
• liip/functional-test-bundle: ^4.1
• marc-mabe/php-enum-phpstan: ^3.0
• mockery/mockery: ^1.2
• overblog/graphiql-bundle: ^1.0
• phpstan/phpstan: ^2.0
• phpstan/phpstan-deprecation-rules: ^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: ^11.0
• 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: *

Conflicts

• symfony/symfony: *

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: *

MIT

README

Used to create new projects using Symfony 7 at XM Media.

Dev: https://symfonystarter.lndo.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

1. 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.
2. Copy .env.local-default to .env.local and update the values where there are @todo-symfony comments.
3. Update composer.json: name, license (likely private) and description
4. Update package.json: name, version, git.url, license (probably delete), private
5. Update the port in vite.config.js (server.port and server.origin)
6. Remove or update the LICENSE file.
7. Composer install & update: lando composer install && lando composer update (or remove lando to run without Lando or without memory limit: php -d memory_limit=-1 /usr/local/bin/composer update)
8. Run yarn && yarn up -R "**".
9. Run yarn dev or yarn build (for production) to compile JS & CSS files.
10. Give executable perms to bin dir: chmod u+x bin/* (helpful, but optional)
11. Run/Start Lando site: lando start
12. Create database with event streams & projections tables from db_create.sql using lando db-import db_create_sql.
    • If possible, set database collation to utf8mb4_bin: ALTER DATABASE <database_name> CHARACTER SET utf8mb4 COLLATE utf8mb4_bin;
13. 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 lando: lando console event-store:event-stream:create user && lando console event-store:event-stream:create auth).
14. Run all projections once: bin/console event-store:projection:run user_projection -o && bin/console event-store:projection:run auth_projection -o (or if using lando: lando console event-store:projection:run user_projection -o && lando console event-store:projection:run auth_projection -o).
15. Create a user bin/console app:user:add (select role ROLE_SUPER_ADMIN) (or if using lando: lando console app:user:add).
16. Find and make changes near @todo-symfony comments throughout the site.
17. Delete starter files: README.md (or update) and TEMPLATES.md.
18. Optional: Run composer test – will install PHPUnit & run PHP tests
19. Create new favicons: realfavicongenerator.net
20. Copy (use "Push to another server") or recreate the templates in Postmark. The templates are referenced by the aliases.
21. Optional: Run bin/console app:graphql:dump-schema <username> to update the GraphQL schema file where username is the email of an admin user.
22. Optional: Rename the project in PhpStorm.
23. Optional: Run npx @sentry/wizard@latest -i sourcemaps to configure Sentry to upload source maps for the frontend.

Local dev site can be accessed at: https://[domain]/

Setting Up Starter

1. Checkout the repo.
2. Copy .env.local-default to .env.local and update the values where there are @todo-symfony comments.
3. Run/Start Lando site: lando start
4. Composer install: lando composer install or composer install to run without Lando.
5. Ensure correct node version: nvm use
6. Run yarn.
7. Run yarn dev or yarn build (for production) to compile JS & CSS files.
8. Give executable perms to bin dir: chmod u+x bin/* (helpful, but optional)
9. Create database with event streams & projections tables from db_create.sql using lando db-import db_create_sql.
   • If possible, set database collation to utf8mb4_bin: ALTER DATABASE <database_name> CHARACTER SET utf8mb4 COLLATE utf8mb4_bin; This can be done through PhpMyAdmin (link provided by lando start command above or lando info)
10. 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 Lando: lando console event-store:event-stream:create user && lando console event-store:event-stream:create auth).
11. Run all projections once: bin/console event-store:projection:run user_projection -o && bin/console event-store:projection:run auth_projection -o (or if using lando: lando console event-store:projection:run user_projection -o && lando console event-store:projection:run auth_projection -o).
12. Create a user bin/console app:user:add (select role ROLE_SUPER_ADMIN) (or if using Lando: lando console app:user:add).
13. Optional: Run composer test – will install PHPUnit & run PHP tests – or lando composer test if using Lando.
14. Run bin/check to run all code tests/checks.

**Local dev site can be accessed at: https://symfonystarter.lndo.site

System Requirements

Server

• PHP 8.4
• MySQL 8.0

Locally for Development

• Lando
• Node 22
• nvm
• Yarn v4

Commands

• Check all code: bin/check
• Production JS/CSS build: yarn build
• Dev JS/CSS build: yarn dev (recommended command: nvm use && yarn && yarn dev)
• Preview production JS/CSS build: yarn preview
• JS Tests (Jest): yarn test:unit
• Linting:
  • JS (ESLint): yarn lint:js or yarn lint:js:fix
  • CSS: yarn lint:css or yarn lint:css:fix
• Install PHP packages: lando composer install or composer install
• Install JS packages: yarn
• PHP Tests (PhpUnit):
  • lando composer test or composer test
  • no memory limit php -d memory_limit=-1 bin/phpunit
  • with coverage (HTML) composer test:coverage
  • show deprecations composer test:deprecations
• PHP CS: (must be installed first)
  • Dry run: lando composer cs or composer cs
  • Fix: lando composer cs:fix or composer cs:fix
• PHP Static Analysis (PHPStan): lando composer static or composer static
• Projections:
  • Show all commands: bin/console event-store:projection
  • Run once: bin/console event-store:projection:run user_projection -o
• Makers (PHP):
  • Make aggregate root/model: bin/console make:model
  • Make projection: bin/console make:projection
• Upgrade JS packages: yarn up -R "**"
  • Upgrade a specific package: yarn up -R "package-name"
  • Upgrade major versions: yarn upgrade-interactive (ctrl+c to exit without changes)

Incorporated Libraries & Tools

• Lando – 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
  • SASS – CSS preprocessor (uses node-sass)
  • PostCSS – transforms CSS
  • Autoprefixer – for adding browser prefixes
  • SVGO – optimizes SVG files
  • Tailwind – utility first styling framework
  • Jest – JS unit testing
  • Lodash – helper functions for JS
  • date-fns – helper functions for Dates in JS
  • Vue Final Modal – for modals
  • Faker.js – for generating fake data in tests
  • ESLint – checks JS for conventions & errors
  • Stylelint – checks CSS for conventions & errors
• Backend – full list of dependencies can be found in composer.json
  • Symfony – backend framework
  • GraphQLBundle – provides GraphQL in PHP using graphql-php
    • GraphQiL is available at /graphiql (on dev only)
  • Doctrine – ORM
  • Doctrine Migrations – for database migrations
  • Nelmio CORS Bundle – for CORS
  • 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
  • Postmark – for sending email, contains email templates (currently setup under XM Media's account)
  • Cloudflare – DNS & CDN
• GitLab – deployment
• Sentry – error tracking
• Dev Tools
  • Vue Devtools
  • Apollo Devtools

Updating PHP version

1. Change version in composer.json & add polyfill for new PHP version, ie, symfony/polyfill-php84.
2. Update the PHP version in the following files:
   • .lando.yml
   • setup_dev.sh – 4 places
   • setup_prod.sh – 4 places
   • .gitlab-ci.yml – 2 places
3. Run lando rebuild to rebuild the Lando container with the new PHP version.
4. Run lando composer update or composer update to update the PHP dependencies.
5. Run the checks nvm use && bin/check_full.
6. Update version in README.md.