Style

Files

• All files are saved as UTF-8 without BOM.
• Superfluous whitespace at the end of a line has to be removed. The only exceptions are file formats where whitespace makes a functional difference (e.g. Markdown).
• All files end in an empty new line (technically they end with the new line character).

Indentation

• All files are indented with four spaces – no tabs.
• The maximum (non-strict) limit of characters in one line is 120.

• A line broken up into multiple lines are indented twice (= 8 blank spaces).

  <?php
  function iAmAVeryLongFunctionName (LongClassName $longClassName,
      VeryLongClassName $veryLongClassName)
  {
      // ...
  }

Parentheses

• Opening and closing braces belong on a new line.

  do
  {
      // ...
  }
  while (/* ... */);
  
  if (/* ... */)
  {
      // ...
  }
  elseif (/* ... */)
  {
      // ...
  }
  else
  {
      // ...
  }

• Only one statement per line. (The only exceptions are language constructs like for-loops).
• Comments belong into their own line, with the only exception being argument comments on calls with multiple arguments.

• Function declarations: a single whitespace belongs between the function name and the parentheses.

  function test ($arg)
  {
      // ...
  }

• Function call: no whitespace between the function name and the parentheses.

  test(5);

Calls with Config Parameters

Function calls, which use arrays or js-objects, can be written in a special way. Arguments are being listed normally and the array argument is being indented. This way of listing the arguments is only permitted if the array/object is the first or last parameter and if it’s the only array/object in the list of arguments.

PHP:

<?php

$this->render("@MyBundle/template.html.twig", [
    "var1" => "a",
    "var2" => "b",
]);

$this->someMethod([
    "var1" => "a",
    "var2" => "b",
], $a, $b);

JavaScript:

$.ajax({
    a: 1,
    b: 2
});

$("a").animate({
    height: 20,
    width: 20
}, 200, onComplete);

This rule is only optional and these examples may be written in a longer form too. This rule becomes mandatory after the arguments contain multiple arrays/objects.

someFunction(
    {
        a: 1,
        b: 2
    },
    {
        c: 3,
        d: 4
    }
);

$("a").animate(
    {
        height: 20,
        width: 20
    },
    200,
    onComplete
);

Versioning

Own projects use Semantic Versioning.

For packages installed via package managers (like Composer, npm, etc…) that use SemVer, use the short form of the version number: ^2.4 (to get all versions compatible with 2.4).

URIs

• All URIs only use lowercase characters and words divided by a hyphen.
• This also includes static directly accessible assets like images, css- and js-files.
• The only exception to this are files automatically generated by an external tool.

Universal Naming Conventions

• Classes, Interfaces, Traits and Namespaces: StudlyCaps
• Methods, Properties and Variables: camelCase
• Constants: ALL_UPPER_CASE
• Keywords are written in lowercase: true, false, null

Example:

<?php
$storeSomething = MyClass::VARIABLE_ID;

$object = new \Becklyn\Test\MyClass();
$object->doSomething();

Method- and Function Calls

• No whitespace between function name and parentheses.

  <?php
  test(5);
  $fibonacci->calc(10);

• Long argument lists are allowed to be split into multiple lines. Each argument as well as the closing parentheses have to be written on their own line. Comments after each argument are allowed.

  <?php
  imagecopyresampled(
      $newImage, // $dst_image,
      $resource, // $src_image
      $destX,    // $dst_x
      $destY,    // $dst_y
      $srcX,     // $src_x
      $srcY,     // $src_y
      $destW,    // $dst_w
      $destH,    // $dst_h
      $srcW,     // $src_w
      $srcH      // $src_h
  );

Other Language Constructs

Code Comments

• PHP: all code must be commented with PHPDoc.
• JS: all code must be commented with JSDoc.
• SCSS: reusable mixins must be commented with SassDoc.

Package Manager

All php projects must use composer. All JS projects must use npm. Own, reusable components should be published over composer or npm.

The lock files of package managers should be committed into the project repository. The lock files of reusable libraries must not be committed.

{
    "type": "project",
    "license": "proprietary",
    "require": {
        "php": "^7.2"
    },
    "config": {
        "preferred-install": {
            "*": "dist"
        },
        "sort-packages": true
    }
}

Strict Types

The “strict types”-mode has to be used. The declare-statement is written after the opening <?php-tag on the same line:

<?​php declare(strict_types=1);

class TestClass
{
    // ...
}

Namespaces

• Source code must use namespaces. No names are defined in the global scope.

• No leading \ before the class name of a use statement.

  <?php
  use Test\Example;

• All names have to be imported.

• Exceptions:

  • Classes in the global scope mustn’t be imported: \Exception
  • Functions in the global scope have to be called with their FQN like: \array_map(...)
• Namespace scheme for general projects: \Becklyn\$Component\...

Annotations

If annotations are used they are handled like class constructors, which means the parentheses belong to the constructor call:

<?php

/**
 * @Test()
 */
public function test ()
{
}

Autoloader

PSR-4 is used as autoloader. The tests used in the autoloader in composer have to be split:

{
    "autoload": {
        "psr-4": {
            "App\\": "src/"
        }
    },
    "autoload-dev": {
        "psr-4": {
            "App\\Tests\\": "tests/"
        }
    }
}

Formatting

• Only one selector per line; multiple selectors should be split and written into multiple lines.

  /* GOOD */
  a,
  input[type="text"],
  .test-element {
      color: red;
  }
  
  /* BAD */
  a, input[type="text"], .test-element {
      color: red;
  }

• One declaration per line.

  /* GOOD */
  a {
      color: red;
      background-color: blue;
  }
  
  /* BAD */
  a {
      color: red; background-color: blue;
  }

• All values have to be written with lowercase characters.
• Colors are either being defined by their shortest hex code and with lowercase characters, or via the color functions rgba() and hsl().
• Double quotes should always be used.
• Attribute selectors like input[type="text"] have to be written with double quotes.
• Opening braces belong on the same line as their selector.
• There has to be a single space between selectors and opening braces.
• The content of a block has to be indented once.
• Closing braces have to be aligned with the start of their selectors.

• All names including but not limited to class names, variable names, mixin names and placeholder names have to be written in kebap-case

  .page-tree {
      .page-tree-title {
          // ...
      }
  }

• Modifier classes should be prefixed with is- or has-. The prefix may be modified to satisfy the English grammar.

  .widget {
      &:hover,
      &.is-hover {
          // ...
      }
  
      &.is-selected {
          // ...
      }
  
      // modified prefix
      &.has-children {
          // ...
      }
  }

Order

The order within an element is as follows:

1. @extend
2. Local variable definitions
3. @include without a body
4. Definitions of this element
5. @include with a body.
6. Modifiers for this element (e.g pseudo classes) and nested child definitions sorted into an understandable order.

Example:

.some-selector {
    @extend .placeholder;

    background-color: red;
}

.some-other-selector {
    $my-var: 123;
    $another-var: 234;

    @include example-mixin;
    @include example-mixin-with-parameters($my-var, $another-var);

    border: 1px solid red;
    color: red;
    background-color: white;

    @include example-mixin-with-a-body {
        display: none;
    }

    @include example-mixin-with-a-body-and-parameters($my-var, $another-var) {
        display: none;
    }

    a {
        // ...
    }

    &:hover {
        // ...
    }

    &.is-selected {
        // ...

        a {
            // ...
        }
    }
}

Style definitions may be grouped to improve readability:

.selector {
    /* Positioning */
    position: absolute;
    z-index: 10;
    top: 0;
    right: 0;
    bottom: 0;
    left: 0;

    /* Display & Box Model */
    display: inline-block;
    overflow: hidden;
    box-sizing: border-box;
    width: 100px;
    height: 100px;
    padding: 10px;
    border: 10px solid #333;
    margin: 10px;

    /* Other */
    background: #000;
    color: #fff;
    font-family: sans-serif;
    font-size: 16px;
    text-align: right;
}

Long comma separated values may be split up into multiple lines. If this is done every line may only contain one value indented once beginning with in the first line after the property name.

.selector {
    background-image:
        linear-gradient(#fff, #ccc),
        linear-gradient(#f3c, #4ec);
    box-shadow:
        1px 1px 1px #000,
        2px 2px 1px 1px #ccc inset;
}

The definitions for the element should be grouped and roughly in the following order:

1. content
2. Core properties (display, padding)
3. Positioning (position, left, …)
4. Coloring (background, text, border)

Directory Structure

All files excluding the entry files have to be prefixed with an underscore _.

The directory structure looks like this (logically grouped and not ordered alphabetically):

.
└── scss
    ├── base/                   <-- base data (fonts, global reset, %placeholder definitions, etc..)
    |   ├── _content.scss       <-- .content class
    |   ├── _fonts.scss         <-- font definitions
    |   └── _global.scss        <-- global definitions
    |
    ├── helper/                 <-- helper files. Mustn't have side effects
    |   ├── _grid.scss          <-- (optional) if a grid layout exists
    |   ├── _mixins.scss
    |   └── _variables.scss
    |
    ├── atom/                   <-- common atom/molecule/organism structure
    ├── molecule/
    ├── organism/
    ├── template/               <-- page templates
    |   └── __default.scss      <-- default template - is always active and has no selector
    |
    ├── vendor/                 <-- external libraries
    └── app.scss                <-- entry file

Atomic Design

Components should be simple, modular and reusable hence why those components should be broken into the smallest reusable pieces (atoms).

.list {
    .list-entry {
        .entry-action {
            .action-icon {
                //some style
            }
        }
    }
}

// base/__placeholders.scss
%content-container {
    width: 100%;
    max-width: $content-width;
    margin: 0 auto;
}

// helper/_mixins.scss
@mixin content-container {
    @extend %content-container;
}

// Reset
@import "~samos/reset";

// vendor
@import "vendor/abc";

// Base
@import "base/fonts";
@import "base/global";
@import "base/content";

// Atoms
@import "atom/...";

// Molecules
@import "molecule/...";

// Organisms
@import "organism/...";

// Templates
@import "template/_default";
@import "template/...";

Data Types

The correct data type should always be used. Common mistakes include but are not limited to:

• Zip codes should always be stored as a string of characters instead of a number. This has to do with some countries having letters or leading zeros in their zip code.
• House numbers should always be stored as a string of characters because they can include symbols e.g. / or -.
• Numbers with a fixed number of digits after the comma should be stored as integers. Normally this is just a transformation to the lowest possible unit, for money it’s “5€” = “500ct”. This measure is necessary to prevent rounding problems on mathematical operations.

Conventions

• YAML files have the .yaml file extension.
• The files are named services.yaml and routes.yaml if they are needed.

Project Directory Structure

The directory structure is based on the Symfony 4 directory structure:

.
├── assets/         <-- assets that needs to be processed (SCSS, TypeScript, JavaScript, ...)
├── bin/
├── build/
|   ├── css/        <-- compiled from SCSS
|   ├── font/       <-- fonts
|   ├── img/        <-- images
|   └── js          <-- compiled from TS/JS
├── config/
├── node_modules/   <-- NPM vendors
├── public/         <-- web directory root
├── src/            <-- components
├── storage/        <-- project specific storage (everything outside of the main framework)
├── templates/      <-- templates
├── tests/          <-- all test cases
├── var/
|   ├── cache/      <-- (Symfony Core: cache)
|   ├── logs/       <-- (Symfony Core: logs)
|   └── sessions/   <-- (Symfony Core: sessions)
├── vendor/         <-- Composer vendors
└── ...             <-- default files

An entry in the AssetsBundle is made for the namespace @app which corresponds to the “build” directory.

• Avoid grouping components by their function (\Service\ oder \Helper\). Group by component instead (\File\ oder \Path\).

• Exceptions:

  • Entity
  • Listener
  • Model
  • Twig
• The template files as well as the directories they are located in are written in kebab-case (e.g. admin\my-entity\my-action.html.twig).
• The use of SensioFrameworkExtraBundle with the @Security() annotation is allowed.
• The use of the @Template() annotation is prohibited.

package.json

• All build dependencies (especially kaba) are to be listed under devDependencies.
• Set "private": true.
• Don’t use name and version.
• Version number should comply to semver (^).