[TASK] Migrate from Services.yaml to Services.php (#1286)

* Migrate existing configuration from yaml to php.
* Document why we did the switch and that using yaml or both is totally
  valid and conforms to best practices.
* Document why we are not using attributes but only `Services.php`
  right now.

Resolves: #1172
Relates: #1237

Configuration/Services.php

@@ -0,0 +1,15 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Symfony\Component\DependencyInjection\Loader\Configurator;
+
+return static function (ContainerConfigurator $containerConfigurator) {
+    $services = $containerConfigurator->services()
+        ->defaults()
+        ->autowire()
+        ->autoconfigure();
+
+    $services->load('TTN\\Tea\\', '../Classes/*')
+        ->exclude('../Classes/Domain/Model/*');
+};

Configuration/Services.yaml

@@ -1,9 +0,0 @@
-services:
-  _defaults:
-    autowire: true
-    autoconfigure: true
-    public: false
-
-  TTN\Tea\:
-    resource: '../Classes/*'
-    exclude: '../Classes/Domain/Model/*'

Documentation/DivergencesToTypo3Core.rst

@@ -0,0 +1,14 @@
+.. include:: /Includes.rst.txt
+
+.. _divergencesToTypo3Core:
+
+=========================
+Divergences to TYPO3 Core
+=========================
+
+A list of all divergences to the TYPO3 core and why we decided to diverge.
+
+.. toctree::
+   :glob:
+
+   DivergencesToTypo3Core/*

Documentation/DivergencesToTypo3Core/Attributes.rst

@@ -0,0 +1,11 @@
+.. include:: /Includes.rst.txt
+
+.. _attributes:
+
+Attributes
+==========
+
+TYPO3 also extends the availability of registering services via attributes.
+We will prefer the attributes over Services files.
+But we won't use both at once and still need Services files as long as PHP 7.4 is supported.
+Attributes will be used in favor of Services files once we drop unsupported PHP versions.

Documentation/DivergencesToTypo3Core/ServicesFiles.rst

@@ -0,0 +1,28 @@
+.. include:: /Includes.rst.txt
+
+.. _servicesFiles:
+
+Services Files
+==============
+
+We choose to use :file:`Services.php` instead of :file:`Services.yaml`.
+It still is completely fine to use YAML files over PHP files or even mix both.
+Some things are way shorter to write with the YAML syntax.
+
+We prefer the PHP file over YAML for the following reasons:
+
+- Static Code Analysis
+
+  Static code analysis tools, like PHPStan, can analyse the PHP source code base.
+  They typically don't support other files like YAML.
+  Those tools report issues for not found classes, e.g. due to typos.
+
+- Auto completion
+
+  Modern tooling like IDEs and Language Servers provide auto completion for PHP source files out of the box.
+  That way programmers can discover APIs and write more robust code faster.
+
+- Automatic code migration
+
+  PHP Code can be auto migrated via tools like rector.
+  E.g. renaming a class can be applied to PHP code, but no current tool for yaml exists.

Documentation/Index.rst

@@ -51,6 +51,7 @@ continuous integration.
    ContinuousIntegration
    Documentation
    Security
+   DivergencesToTypo3Core
 
 .. Meta Menu