diff --git a/docs/README.instructions.md b/docs/README.instructions.md index ac08e93b..5a6379d9 100644 --- a/docs/README.instructions.md +++ b/docs/README.instructions.md @@ -154,6 +154,7 @@ Team and project-specific instructions to enhance GitHub Copilot's behavior for | [Style Components with Modern Theming (Preview)](../instructions/pcf-fluent-modern-theming.instructions.md)
[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/instructions?url=vscode%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fpcf-fluent-modern-theming.instructions.md)
[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/instructions?url=vscode-insiders%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fpcf-fluent-modern-theming.instructions.md) | Style components with modern theming using Fluent UI | | [Svelte 5 and SvelteKit Development Instructions](../instructions/svelte.instructions.md)
[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/instructions?url=vscode%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fsvelte.instructions.md)
[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/instructions?url=vscode-insiders%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fsvelte.instructions.md) | Svelte 5 and SvelteKit development standards and best practices for component-based user interfaces and full-stack applications | | [Swift MCP Server Development Guidelines](../instructions/swift-mcp-server.instructions.md)
[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/instructions?url=vscode%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fswift-mcp-server.instructions.md)
[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/instructions?url=vscode-insiders%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fswift-mcp-server.instructions.md) | Best practices and patterns for building Model Context Protocol (MCP) servers in Swift using the official MCP Swift SDK package. | +| [Symfony Development Instructions](../instructions/php-symfony.instructions.md)
[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/instructions?url=vscode%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fphp-symfony.instructions.md)
[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/instructions?url=vscode-insiders%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fphp-symfony.instructions.md) | Symfony development standards aligned with official Symfony Best Practices | | [Taming Copilot](../instructions/taming-copilot.instructions.md)
[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/instructions?url=vscode%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Ftaming-copilot.instructions.md)
[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/instructions?url=vscode-insiders%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Ftaming-copilot.instructions.md) | Prevent Copilot from wreaking havoc across your codebase, keeping it under control. | | [TanStack Start with Shadcn/ui Development Guide](../instructions/tanstack-start-shadcn-tailwind.instructions.md)
[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/instructions?url=vscode%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Ftanstack-start-shadcn-tailwind.instructions.md)
[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/instructions?url=vscode-insiders%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Ftanstack-start-shadcn-tailwind.instructions.md) | Guidelines for building TanStack Start applications | | [Task Plan Implementation Instructions](../instructions/task-implementation.instructions.md)
[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/instructions?url=vscode%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Ftask-implementation.instructions.md)
[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/instructions?url=vscode-insiders%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Ftask-implementation.instructions.md) | Instructions for implementing task plans with progressive tracking and change record - Brought to you by microsoft/edge-ai | diff --git a/instructions/php-symfony.instructions.md b/instructions/php-symfony.instructions.md new file mode 100644 index 00000000..e700764a --- /dev/null +++ b/instructions/php-symfony.instructions.md @@ -0,0 +1,122 @@ +--- +description: "Symfony development standards aligned with official Symfony Best Practices" +applyTo: "**/*.php, **/*.yaml, **/*.yml, **/*.xml, **/*.twig" +--- + +# 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