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

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-default to .env.local and update the values where there are @todo-symfony comments.
Update composer.json: name, license (likely private) and description
Update package.json: name, version, git.url, license (probably delete), private
Update the port in vite.config.js (server.port and server.origin)
Remove or update the LICENSE file.
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)
Run yarn && yarn up -R "**".
Run yarn dev or yarn build (for production) to compile JS & CSS files.
Give executable perms to bin dir: chmod u+x bin/* (helpful, but optional)
Run/Start Lando site: lando start
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;
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).
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).
Create a user bin/console app:user:add (select role ROLE_SUPER_ADMIN) (or if using lando: lando console app:user:add).
Find and make changes near @todo-symfony comments throughout the site.
Delete starter files: README.md (or update) and TEMPLATES.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 where username is the email of an admin user.
Optional: Rename the project in PhpStorm.
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

Checkout the repo.
Copy .env.local-default to .env.local and update the values where there are @todo-symfony comments.
Run/Start Lando site: lando start
Composer install: lando composer install or composer install to run without Lando.
Ensure correct node version: nvm use
Run yarn.
Run yarn dev or yarn build (for 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.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)
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).
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).
Create a user bin/console app:user:add (select role ROLE_SUPER_ADMIN) (or if using Lando: lando console app:user:add).
Optional: Run composer test – will install PHPUnit & run PHP tests – or lando composer test if using Lando.
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

Commands

Run all checks: nvm use && bin/generate_schema && bin/check_full
- Notes: 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
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
- 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

Change version in composer.json & add polyfill for new PHP version, ie, symfony/polyfill-php84.
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
- .php-cs-fixer.dist.php – update the @PHP8#Migration version to match the current version.
Run lando rebuild to rebuild the Lando container with the new PHP version.
Run lando composer update or composer update to update the PHP dependencies. If running locally without Lando, ensure your local PHP version matches the new version.
Run the checks nvm use && 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.

xm / starter_symfony_4

Maintainers

Details