Skip to content

AGENTS.md

Latest commit

 

History

History
113 lines (96 loc) · 5.62 KB

AGENTS.md

File metadata and controls

113 lines (96 loc) · 5.62 KB

AI Contribution Guidelines

Welcome, 🤖 AI assistant! Please follow these guidelines when contributing to this repository:

General Guidelines

  • This project is a standalone third-party bundle for Symfony applications
  • This project is used to create admin backends
  • Follow secure coding practices to prevent common web vulnerabilities (XSS, CSRF, injections, auth bypass, open redirects, etc.)
  • Code must be compatible with Symfony 5.4, 6.x and 7.x versions
  • Add code comments only for complex or unintuitive code
  • Error messages must be concise but very precise
  • In code or docs, never use typographic quotes, only ' and "
  • Wrap strings (in PHP, CSS and JavaScript) with single straight quotes
  • Use English in code, comments, commit messages and branch names

Documentation

  • User documentation is stored in the doc/ directory
  • Use reStructuredText syntax for documentation
  • Use these heading symbols: =, -, ~, ., " for levels 1–5
  • Break lines at ~72–78 characters for readability
  • Prefer :: over .. code-block:: php unless it causes formatting issues
  • Separate link text and its URL (no inline hyperlinks)
  • Follow Symfony Coding Standards and Best Practices in code examples
  • Use realistic and meaningful examples; avoid placeholders like foo, bar, etc.
  • Use Acme for vendor names and example.com / example.org / example.net for URLs
  • Break code lines >85 characters; use ... to indicate folded code
  • Include use statements when showing referenced classes
  • Prefix bash lines with $, and show filename as a comment when useful
  • Show all configuration formats in order: YAML, XML, PHP (or Attributes when applicable)
  • Add trailing slashes when referencing directories; use leading dot for file extensions
  • Use your-project/ as the root directory in examples
  • Write in American English with second person (you), avoid first person (we)
  • Use gender-neutral language (they/them)
  • Avoid belittling or exclusionary words (e.g. "just", "obviously", "easy")
  • Contractions are allowed (e.g. "it's", "you're")

Commands

  • Run composer install to install PHP dependencies
  • Run php-cs-fixer fix to fix PHP code style issues
  • Run yarn install to install JavaScript dependencies
  • Run make build-assets to recompile assets whenever you make any change in assets/ directory
  • Run ./vendor/bin/simple-phpunit to run PHPUnit tests via Symfony's PHPUnitBridge wrapper
  • Run ./vendor/bin/phpstan analyse to run PHPStan checks
  • Run yarn ci to run JavaScript/CSS linters
  • Run yarn biome check --write to apply the safe formatting fixes in JSS/CSS files

PHP Code

  • Use modern PHP 8.1 syntax and features
  • Avoid using deprecated Symfony or PHP features
  • Apply these Symfony coding standards and best practices:
    • Follow PSR-1, PSR-2, PSR-4, and PSR-12 coding standards.
    • Use Yoda conditions for comparisons (e.g. if (null === $value)).
    • Always use strict (===) and not loose (==) comparisons.
    • Use one class per file (unless private/internal).
    • Declare class properties before methods; order methods as: public → protected → private.
    • Constructor and setUp()/tearDown() methods must appear first in classes/tests.
    • Use braces {} in all control structures, even for one-liners.
    • Add a blank line before return, unless it's the only line in the block.
    • In multi-line arrays, use trailing commas.
    • Avoid else, elseif, or break after a block that returns or throws.
    • Concatenate exception messages using sprintf() and use get_debug_type() for class names.
    • Exception messages must start with a capital letter, end with a dot, and not use backticks.
    • Use return null; for nullable returns and return; for void functions.
    • Use parentheses when instantiating classes, even without arguments.
    • Do not add void return types to test methods.
    • Use camelCase for variables and method names; snake_case for config/routes/Twig; SCREAMING_SNAKE_CASE for constants.
    • Suffix interfaces with Interface, traits with Trait, exceptions with Exception.
    • Prefix abstract classes with Abstract, except for test cases.
    • Use UpperCamelCase for PHP class, interface, trait, and enum names.
    • Use snake_case for Twig templates and assets (e.g. .html.twig, .scss).
    • Add use statements for all non-global classes.
    • In PHPDoc:
      • Avoid @return if method returns void.
      • Don't use one-line docblocks.
      • Group annotations by type.
      • Put null last in union types.
  • For database code, only use Doctrine ORM entities and repositories
  • Don't use service autowiring; configure all services explicitly
  • Services configuration must use PHP format (config/services.php)
  • Translations must be in PHP format (translations/*.php)
  • Handle exceptions explicitly and avoid silent catch blocks

Twig Templates

  • Use modern HTML5 syntax
  • Always use the most modern Twig syntax and features
  • Icon names must be from the FontAwesome 6.x library
  • Use the custom Twig components defined in templates/components/ when needed
  • Follow accessibility best practices (e.g. `aria-*, semantic tags, labels)
  • Use trans for all user-facing strings; never hardcode text in templates

JavaScript

  • Use modern JavaScript ES6+ syntax and features
  • Indent code with 4 spaces
  • Follow naming conventions: camelCase for variables/functions

CSS

  • Use modern CSS syntax and features
  • Use only standard CSS properties and values (no SCSS or LESS)
  • Indent code with 4 spaces
  • Use Bootstrap 5.3 classes and utilities
  • Use logical CSS properties (e.g. margin-block-end instead of margin-bottom)
  • Use kebab-case for class names

Thanks for contributing! 🙇‍♂️