Conventions

Pull Requests

Each and every project has the following labels: needs-review, needs-work, suspended, waiting-for-dependencies, work-in-progress. There are a few rules and work-flows associated with each label:

• needs-review: A pull request is ready to be reviewed
• needs-work: Feedback has been provided and needs to be incorporated by the pull request author
• suspended: The pull request is momentarily suspended and is waiting for an decision to be made where most commonly a given features is no longer needed or simply postponed
• waiting-for-dependencies: This label is most commonly used when another pull request, there this one depends on, is still waiting to be merged (and released as a new version). Additionally to listing your dependencies in the pull request’s title, please also list them as part of your description, especially for things that aren’t necessarily under our own control, like dependencies on third-party projects. The pull request is usually not being reviewed and needs to be rebased first by the pull request author before it’s ready to be reviewed
• work-in-progress: A pull request where the author is still actively working on. Most commonly used to share a specific subset or feature of a pull request with a colleague or as an active reminder for the author himself/herself. work-in-progress pull requests are not being reviewed unless it’s explicitly requested with the needs-review label. Alternatively, you can also use the draft feature that lets you open your new pull request as a draft, which can’t be automatically/accidentally merged as it needs to be converted into a regular pull request first.

Directory Layout

• Only define the most global routes in config/routes.yaml, for example login and homepage (if required).
• All other routes: put them in separate files in config/app_routes/.

• Your main config/routes.yaml should only consist of imports of the app_routes (and the few global routes). First the global routes, than the imports.

  • Prefix all names of imports with _import.

Controllers

• Use service argument injection.
• For dependencies of private helper methods, you can extend the getSubscribedServices() implementation, to be able to fetch these services inside the private helper directly.

• Order your action arguments like this:

  1. Services (like models, Translator, helpers, …)
  2. Special symfony core variables (like Request)
  3. The parameters of your action, as defined in the routing
• Every public method in a controller must be an action (and should have a route pointing to it).

• Actions returning JSON must always return an object instead of an array

  1. You are forward compatible if you need an additional item in the future
  2. You don’t introduce local security issues, due to the way JSON constructs arrays in JavaScript

Routing

• Route import names should start with _import.*

Services

• Use single quotes and only quote when necessary.
• Sort service names alphabetically.

• Order in the file:

  1. _defaults
  2. Directory-based service definitions
  3. Regular service definitions
• Use autoconfiguration and autowiring.

• Explicitly list imported directories (allowlist) if you are importing from the root directory (like in a reusable bundle):

  Mayd\Core\:
      resource: '../../{Command,Config,Controller,...,User,Validation/Validator}/*'

• When only importing from src/, you can use a denylist (like in a regular app):

  App\:
      resource: '../src/*'
      exclude: '../src/{DependencyInjection,Entity,Migrations,Tests,Kernel.php}'

• Bind parameters via arguments.

  Service:
      $isDebug: '%kernel.debug%'

• Avoid using name-based bindings in _defaults, except for the parameters $projectDir (%kernel.project_dir%) and $isDebug (%kernel.debug%). These can be bound service-file-wide as shown:

  services:
      _defaults:
          bind:
              $isDebug: '%kernel.debug%'
              $projectDir: '%kernel.project_dir%'

Translations

• Don’t translate default Symfony validation messages (you should use the Becklyn RAD Bundle, as it improves some messages).

• Use translation keys instead of translation strings:

  {# GOOD #}
  {{ "example.message" | trans }}
  
  {# BAD #}
  {{ "This is a message" | trans }}

• In Twig, prefer {{ "text" | trans }} over {% trans %}text{% endtrans %}
• Use the yaml file format.

• Use the most readable structure: nesting vs flat

  app.test.key: "abc"
  app.test.key2: "def"
  
  # vs
  
  app:
      test:
          key: "abc"
          key2: "def"

Translation keys are named with the following rules:

If you are building a reusable bundle or encounter duplicate keys, you can qualify the entity part with a custom prefix.

Examples:

• mayd.locale.name.help
• customer.client.locale.name.help

Templates

• Don’t use the @Template annotation.
• Naming convention is lower kebab-case: for example @MyBundle/main-navigation/layout-left.html.twig.