DanieleGBX/starter_symfony_4

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

Symfony Starter 4

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

Setting Up a New Site

1. Download a copy of this repo (probably as a ZIP).
2. Remove or update the LICENSE file.
3. Install Composer locally.
4. Update composer.json: name, license (likely private) and description
5. Update package.json: name, version, git.url, license, private, script.dev-server
6. Composer install & update (locally): composer install && composer update (or without memory limit: php -d memory_limit=-1 /usr/local/bin/composer update)
7. Run yarn && yarn upgrade locally.
8. Find and make changes near @todo-symfony comments throughout the site.
9. Setup server:
   1. Upload the files (exclude files that are OS dependent like node_modules & .env or that are only for editing like .idea and a lot of what's in .gitignore).
   2. Install Composer
   3. Install PHP packages/vendors: php composer.phar install
   4. Update .env.
   5. Install NVM: https://github.com/creationix/nvm#install-script
   6. Run . ./node_setup.sh (this will setup node & install the JS packages).
   7. Run yarn dev or yarn build (for production) to compile JS & CSS files.
   8. Create event streams & projections tables from: https://github.com/prooph/pdo-event-store/tree/master/scripts/mysql
   9. Create one or more event streams with the command bin/console event-store:event-stream:create user && bin/console event-store:event-stream:create auth (and if using enquiry: bin/console event-store:event-stream:create enquiry)
   10. Run all projections once:
       1. bin/console event-store:projection:run user_projection -o
       2. bin/console event-store:projection:run user_token_projection -o
       3. bin/console event-store:projection:run enquiry_projection -o
   11. Create a user bin/console app:user:add & run user projection: bin/console event-store:projection:run user_projection -o
   12. Copy or recreate the templates in Postmark & update the template IDs (see @todo-symfony).
   13. Setup supervisord:
       1. Write supervisord config: bin/console app:supervisor:write-config
       2. Add site supervisord config to main config, for example files = /etc/supervisord/*.conf /home/user/supervisord.conf (as root)
       3. Tell supervisord to read the config: supervisorctl reread && supervisorctl update (as root)
       4. Ensure programs are running: supervisorctl status
   14. Setup mail spool: add cron task similar to: */15 * * * * cd /home/user/example.com/current && bin/console swiftmailer:spool:send --message-limit=10 --time-limit=45 >> var/log/mailer.log 2>&1 (this only sends error emails, runs every 15 minutes)
   15. Add logrotate cron: 30 4 * * 1 cd /home/user/example.com/current && logrotate app/config/packages/logrotate.conf --state var/logrotate-state (runs Mondays at 04:30 UTC)
10. Delete starter files: README.md (or update) and TEMPLATES.md.
11. Run composer test – will install PHPUnit & run PHP tests
12. Create new favicons: realfavicongenerator.net

Dev site can be accessed at https://[domain]/

System Requirements

• PHP 7.3+
• MySQL 5.7+
• Yarn

Commands

• Production JS/CSS build: yarn build
• Dev JS/CSS build: yarn dev
• Dev JS/CSS watch: yarn watch (files will not be versioned)
• Dev JS/CSS HMR server: yarn dev-server (see below)
• JS Tests (Jest): yarn test:unit
• E2E Tests (Cypress): yarn test:e2e
• Linting:
  • JS (ESLint): yarn lint:js or yarn lint:js:fix
  • CSS: yarn lint:css or yarn lint:css:fix
• PHP Tests (PhpUnit):
  • composer test
  • no memory limit php -d memory_limit=-1 bin/simple-phpunit
  • with coverage (HTML) composer test:coverage
• PHP CS: (must be installed first)
  • Dry run: composer cs
  • Fix: composer cs:fix
• PHP Static Analysis (PHPStan): composer static
• Projections:
  • All commands: bin/console event-store:projection
  • Run once: bin/console event-store:projection:run user_projection -o

Apache Config

The following is needed in the Apache VirtualHost for the Webpack Dev Server/HMR to work:

  ProxyPassMatch ^(\/dev-server\/.+$)|(sockjs-node) http://localhost:<port>
  ProxyPassReverse / http://localhost:<port>

You'll probably want to customize the port number in the Apache ProxyPass config and in package.json (script.dev-server) to be unique to each project if running multiple sites on one server.

Incorporated Libraries & Tools

• Frontend – full list of dependencies can be found in package.json
  • Vue – frontend framework
    • Vue Router – routing package for frontend
    • Vuex – helps to manage state
    • Vue Devtools – makes debugging in the browser easier
    • Vue Templates – the syntax for .vue files
    • Vue Test Utils – to help testing Vue components
  • Vue CLI – to manage & run the frontend compilation & testing
  • GraphQL – the communication (query) language for the API
    • Apollo Client through Vue Apollo – frontend GraphQL
  • SASS – CSS preprocessor (uses node-sass)
  • Webpack – compiles JS & CSS
    • Babel – transforms JS to work in all browsers
    • Webpack Encore – connects the frontend and backend and makes Webpack configuration simpler
    • PostCSS – transforms CSS
    • Autoprefixer – for adding browser prefixes
    • Purge CSS – removes unused CSS during the deployment process (not run in dev)
    • SVGO – optimizes SVG files
    • Bundle Analyzer – displays sizes/stats on the JS bundle size
  • Tailwind – utility first styling framework
  • Jest – JS unit testing
  • Cypress – end-to-end (e2e) testing
  • Lodash – helper functions for JS
  • date-fns – helper functions for Dates in JS
  • PortalVue – helps to manage things like modals
  • Vue-JS-Modal – for modals
  • Workbox – helps with configuration of service worker/PWA
  • 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)
  • 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
• Dev Tools
  • Vue Devtools
  • Apollo Devtools
  • GraphQiL is available at /graphiql