Skip to content
Awesome GitHub Copilot

Php Symfony

Php Symfony

Symfony development standards aligned with official Symfony Best Practices

Documentation

Symfony Development Instructions

Instructions for developing Symfony applications following the official Symfony Best Practices and core framework philosophy.

Project Context

  • Symfony (latest stable or LTS)
  • Default Symfony directory structure
  • Autowiring and autoconfiguration enabled
  • Doctrine ORM when persistence is needed
  • Twig for templating
  • Symfony Forms, Validator, Security, Messenger as needed
  • PHPUnit for testing
  • Attribute-based configuration where supported

Project Structure

  • Use the default Symfony directory structure
  • Do not create bundles for application code
  • Organize application code using PHP namespaces
  • Keep configuration in config/, application code in src/, templates in templates/

Configuration

Environment Configuration

  • Use environment variables for infrastructure-related configuration
  • Use .env files to define environment-specific values
  • Do not use environment variables to control application behavior

Sensitive Configuration

  • Store secrets (API keys, credentials) using Symfony Secrets
  • Never commit secrets to the repository

Application Configuration

  • Use parameters in config/services.yaml for application behavior configuration
  • Override parameters per environment only when needed
  • Prefix parameters with app. to avoid collisions
  • Use short, descriptive parameter names
  • Use PHP constants for configuration values that rarely change

Services & Dependency Injection

  • Use dependency injection exclusively
  • Prefer constructor injection
  • Use autowiring and autoconfiguration by default
  • Keep services private whenever possible
  • Avoid accessing services via $container->get()
  • Use YAML as the preferred format for service configuration
  • Use interfaces where it improves decoupling or clarity

Controllers

  • Extend AbstractController
  • Keep controllers thin and focused on glue code
  • Do not place business logic in controllers
  • Use attributes to configure routing, caching, and security
  • Use dependency injection for services
  • Use Entity Value Resolvers when convenient and appropriate
  • Perform complex queries explicitly via repositories when needed

Doctrine & Persistence

  • Use Doctrine entities as plain PHP objects
  • Define Doctrine mapping using PHP attributes
  • Use repositories for querying data
  • Avoid putting business logic in repositories
  • Use migrations for all schema changes

Templates (Twig)

  • Use snake_case for template names, directories, and variables
  • Prefix template fragments with an underscore
  • Keep templates focused on presentation
  • Avoid business logic in Twig templates
  • Escape output by default
  • Avoid using |raw unless content is trusted and sanitized

Forms

  • Define forms as PHP classes
  • Do not build forms directly in controllers
  • Add form buttons in templates, not in form classes
  • Define validation constraints on the underlying object
  • Use a single controller action to render and process each form
  • Define submit buttons in controllers only when multiple submits are required

Validation

  • Use Symfony Validator constraints
  • Validate data at application boundaries
  • Prefer object-level validation over form-only validation when reuse is needed

Internationalization

  • Use XLIFF for translation files
  • Use translation keys instead of literal content strings
  • Use descriptive keys that express purpose, not location

Security

  • Prefer a single firewall unless multiple systems are required
  • Use the auto password hasher
  • Use voters for complex authorization logic
  • Avoid complex security expressions in attributes

Web Assets

  • Use AssetMapper to manage web assets
  • Avoid unnecessary frontend build complexity unless required

Asynchronous Processing

  • Use Symfony Messenger for async and background tasks
  • Keep message handlers small and focused
  • Configure failure transports for failed messages

Testing

  • Write functional tests using WebTestCase
  • Add smoke tests to ensure all public URLs respond successfully
  • Hard-code URLs in functional tests instead of generating routes
  • Use unit tests where appropriate for isolated logic
  • Add more specific tests incrementally as the application evolves

General Guidelines

  • Prefer clarity over abstraction
  • Follow Symfony conventions before introducing custom patterns
  • Keep configuration explicit and readable
  • Avoid premature optimization
  • Use Symfony Demo as a reference implementation