PoC blog

README.md

@@ -22,34 +22,34 @@ https://qossmic.github.io/deptrac
 You can install Deptrac via Composer. We recommend using the
 [deptrac-shim](https://github.com/qossmic/deptrac-shim) package for this:
 
-```bash
-composer require --dev qossmic/deptrac-shim
+```console
+$ composer require --dev qossmic/deptrac-shim
 ```
 
 Alternatively, you can also use [PHIVE](docs/index.md#phive) or download the
-[PHAR](docs/index.md#phar) attached to each release on GitHub.  
-We strongly advise against using the deptrac package directly as a composer dependency. 
+[PHAR](docs/index.md#phar) attached to each release on GitHub.
+We strongly advise against using the deptrac package directly as a composer dependency.
 We update dependencies regularly, which might cause disruptions in your project.
 
 Once you have downloaded/installed deptrac, you will need to create a
 [configuration file](docs/index.md#configuration), where you define your layers and
-communication ruleset. This configuration file is written in YAML and, by default, 
+communication ruleset. This configuration file is written in YAML and, by default,
 is stored with the name `deptrac.yaml` in your project's root directory.
 
 Deptrac can generate a template for you, using the `init` command.
 
-```bash
-vendor/bin/deptrac init
+```console
+$ vendor/bin/deptrac init
 ```
 
 When you have this file, you can analyse your code by
-running the analyse command:
+running the `analyse` command:
 
-```bash
-vendor/bin/deptrac
+```console
+$ vendor/bin/deptrac
 
 # which is equivalent to
-vendor/bin/deptrac analyse --config-file=deptrac.yaml
+$ vendor/bin/deptrac analyse --config-file=deptrac.yaml
 ```
 
 In order to run Deptrac you need at least PHP 8.1.

docs/CODE_OF_CONDUCT.md

@@ -8,6 +8,6 @@ harassment and will take action against any individual who is not acting
 professionally. This can range from reprimanding them privately to blocking them
 from interacting with the repository.
 
-[QOSSMIC](qossmic.com) as owner is responsible for upholding the code of conduct
+[QOSSMIC](https://qossmic.com) as owner is responsible for upholding the code of conduct
 and should be contacted if you have any issues. Please use the following email
 for this: [wecare@qossmic.com](mailto:wecare@qossmic.com?subject=Deptrac)

docs/CONTRIBUTING.md

@@ -25,8 +25,8 @@ your merge request can be accepted.
 You can install all tools needed for developing Deptrac using the Makefile by
 running the following command:
 
-```bash
-make composer-install
+```console
+$ make composer-install
 ```
 
 ## Pipeline
@@ -93,8 +93,8 @@ make infection
 You can build the `deptrac.phar` both to ensure it works, as well as for using
 it to analyse your existing projects to see if your changes work as expected.
 
-```bash
-make build
+```console
+$ make build
 ```
 
 This will create an executable file `deptrac.phar` in the current directory.

docs/blog.md

@@ -0,0 +1,23 @@
+---
+hide:
+  - navigation
+  - toc
+---
+
+# Blog
+
+---
+<!--- Blog post template to copy-paste right below
+
+## [<Blog post title>](blog/<filename>.md)
+
+<Date> - <X> min read
+
+---
+-->
+
+## [Dynamic Deptrac configuration with PHP config file](blog/2023-05-11_PHP_configuration.md)
+
+May 11, 2023 - 5 min read
+
+---

docs/blog/.template.md

@@ -0,0 +1,26 @@
+---
+hide:
+  - navigation
+  - toc
+---
+
+# TITLE
+
+DATE (formatted as Sep 11, 2023) - X min read
+
+---
+
+SLUG
+
+---
+
+BLOG POST CONTENT
+
+---
+<!--- Optional sponsor plug
+
+Do you like Deptrac and use it every day? [Consider supporting further development of Deptrac by sponsoring me on GitHub Sponsors](URL TO SPONSOR PAGE). I’d really appreciate it!
+
+-->
+
+Author: [GITHUB NAME](GITHUB PROFILE LINK)

docs/blog/2023-05-11_PHP_configuration.md

@@ -0,0 +1,113 @@
+---
+hide:
+  - navigation
+  - toc
+---
+
+# Dynamic Deptrac configuration with PHP config file
+
+May 11, 2023 - 5 min read
+
+---
+
+Do you copy-paste deptrac config every time you need to
+add a layer? Do you have a large existing project that has similar structure across its architecture? With PHP config files you can significantly cut down the amount of time spend on creating and maintaining your deptrac configuration.
+
+---
+
+For a long time, Deptrac was only supporting a `yaml` configuration. Thanks to the effort by [grennadi](https://github.com/gennadigennadigennadi) you can now use Symfony config builders to create a dynamic deptrac configuration using PHP. Let's take a look at how to do it.
+
+Start by creating a `deptrac.config.php` file in the root of the project:
+
+```php
+<?php
+
+use Qossmic\Deptrac\Contract\Config\DeptracConfig;
+use Symfony\Component\DependencyInjection\Loader\Configurator\ContainerConfigurator;
+
+return static function (DeptracConfig $config, ContainerConfigurator $containerConfigurator): void {
+
+};
+```
+
+> All the required classes you might need for config definition exist in the `Qossmic\Deptrac\Contract\Config` namespace and are covered by the [backwards compatibility promise,](../bc_policy.md) so you don't need to worry your configuration will suddenly stop working without warning.
+
+Then define the shared configuration for the project like `paths` to the analysed files and the used `analysers`:
+
+```php
+    $config
+        ->paths('src')
+        ->analysers(
+            EmitterType::CLASS_TOKEN,
+            EmitterType::FUNCTION_TOKEN,
+            EmitterType::FUNCTION_CALL,
+        );
+```
+
+Continue by defining some layers:
+
+```php
+    $config
+        ->layers(
+            $dependency = Layer::withName('Dependency')->collectors(
+                DirectoryConfig::create('src/Core/Dependency/.*')
+            ),
+            $dependencyInjection = Layer::withName('DependencyInjection')->collectors(
+                DirectoryConfig::create('src/Supportive/DependencyInjection/.*')
+            ),
+            $inputCollector = Layer::withName('InputCollector')->collectors(
+                DirectoryConfig::create('src/Core/InputCollector/.*')
+            ),
+            $layer = Layer::withName('Layer')->collectors(
+                DirectoryConfig::create('src/Core/Layer/.*')
+            ),
+            $file = Layer::withName('File')->collectors(
+                DirectoryConfig::create('src/Supportive/File/.*')
+            ),
+        );
+```
+
+You can use all the collectors you find in the [collectors' documentation](../collectors.md). Use the appropriate config class in the  `Qossmic\Deptrac\Contract\Config\Collector\` namespace.
+
+Notice that we assign all the layer configs to a variable. This is important to define rulesets between the layers:
+
+```php
+    $config
+        ->rulesets(
+            Ruleset::forLayer($inputCollector)->accesses($file),
+            #...
+        );
+```
+
+You can also define configuration for the formatters if you need to, again re-using the previously defined layers to ensure you don't have a typo in your definition:
+
+```php
+    $config
+        ->formatters(
+            GraphvizConfig::create()
+                ->pointsToGroup(true)
+                ->groups('Supportive', $file, $dependencyInjection)
+                ->groups('Core', $dependency, $inputCollector, $layer)
+        );
+```
+
+Last, but not least, you can also plug in any extension you write like custom collectors, rules or commands. For example a custom suppression of violations when depending on contract classes:
+
+```php
+    $services = $containerConfigurator->services();
+    $services->set(IgnoreDependenciesOnContract::class)
+        ->tag('kernel.event_subscriber');
+```
+
+To tie it all together, you have to specify that you want deptrac to you your php config file, for example like this:
+
+```console
+$ php deptrac.php -c deptrac.config.php
+```
+
+As you can see this feature allows you to use the full expressive power of PHP to create dynamic configuration on the fly.
+
+---
+Do you like Deptrac and use it every day? [Consider supporting further development of Deptrac by sponsoring me on GitHub Sponsors](https://github.com/sponsors/patrickkusebauch). I’d really appreciate it!
+
+Author: [patrickkusebauch](https://github.com/patrickkusebauch)

docs/collectors.md

@@ -232,7 +232,7 @@ very useful by itself (unless you want to have tokens in multiple layers), but
 it is very useful to exclude classes in combination with
 the [`bool` Collector](#bool-collector):
 
-```yml
+```yaml
 deptrac:
   layers:
     - name: SubDomain

docs/concepts.md

@@ -84,8 +84,8 @@ configuration:
 (Make sure that [*Graphviz*](/#optional-dependency-graphviz) (dot) is
 installed on your system)
 
-```bash
-php deptrac.phar analyse --config-file=examples/ModelController1.depfile.yaml
+```console
+$ php deptrac.phar analyse --config-file=examples/ModelController1.depfile.yaml
 ```
 
 After Deptrac has finished, an image should be opened:
@@ -94,7 +94,7 @@ After Deptrac has finished, an image should be opened:
 
 On your command line Deptrac will produce this output:
 
-```bash
+```console
 Start to create an AstMap for 2 Files.
 ..
 AstMap created.
@@ -172,7 +172,7 @@ After running Deptrac we will get this result:
 
 ![ModelController1](examples/ControllerServiceRepository1.png)
 
-```bash
+```console
 Start to create an AstMap for 3 Files.
 ...
 AstMap created.
@@ -257,13 +257,13 @@ class SomeController
 
 After running Deptrac for this example
 
-```bash
-php deptrac.phar analyse --config-file=examples/ModelController2.depfile.yaml
+```console
+$ php deptrac.phar analyse --config-file=examples/ModelController2.depfile.yaml
 ```
 
 we will get this output:
 
-```bash
+```console
 Start to create an AstMap for 2 Files.
 ..
 AstMap created.
@@ -309,8 +309,8 @@ values (`Core\CoreClass`) are dependency tokens.
 
 Matched violations will be marked as skipped:
 
-```bash
-php deptrac.phar analyse --config-file=examples/SkipViolations.yaml --report-skipped
+```console
+$ php deptrac.phar analyse --config-file=examples/SkipViolations.yaml --report-skipped
 1/1 [▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓] 100%
 
 [SKIPPED] Library\LibClass must not depend on Core\CoreClass (Library on Core)

docs/debugging.md

@@ -9,8 +9,8 @@ easily combined with other tools like `wc` or `grep`.
 With the `debug:layer`-command you can list all tokens which are matched in
 a specific layer. This command only shows tokens that would be emitted by your analyser configuration.
 
-```bash
-php deptrac.phar debug:layer --config-file=examples/DirectoryLayer.depfile.yaml Layer1
+```console
+$ php deptrac.phar debug:layer --config-file=examples/DirectoryLayer.depfile.yaml Layer1
 
 examples\Layer1\AnotherClassLikeAController
 examples\Layer1\SomeClass
@@ -21,8 +21,8 @@ examples\Layer1\SomeClass2
 
 The `debug:token` (previously `debug:class-like`)-command will let you know which layers a specified token belongs to. Since you can specify the token type, this commands ignores your analyser configuration for emitted token types.
 
-```bash
-php deptrac.phar debug:token --config-file=examples/DirectoryLayer.depfile.yaml 'examples\Layer1\AnotherClassLikeAController' class-like
+```console
+$ php deptrac.phar debug:token --config-file=examples/DirectoryLayer.depfile.yaml 'examples\Layer1\AnotherClassLikeAController' class-like
 
 Controller
 Layer1
@@ -34,8 +34,8 @@ With the `debug:unassigned`-command you list all tokens in your path that are
 not assigned to any layer. This is useful to test that your collector
 configuration for layers is correct.  This command only shows tokens that would be emitted by your analyser configuration.
 
-```bash
-php deptrac.phar debug:unassigned --config-file=examples/DirectoryLayer.depfile.yaml
+```console
+$ php deptrac.phar debug:unassigned --config-file=examples/DirectoryLayer.depfile.yaml
 
 examples\Layer1\AnotherClassLikeAController
 examples\Layer1\SomeClass
@@ -46,8 +46,8 @@ examples\Layer1\SomeClass2
 
 With the `debug:dependencies`-command you can see all dependencies of your layer. You can optionally specify a target layer to get only dependencies from one layer to the other:
 
-```bash
-php deptrac.phar debug:dependencies debug:dependencies Ast InputCollector
+```console
+$ php deptrac.phar debug:dependencies debug:dependencies Ast InputCollector
 
   Qossmic\Deptrac\Core\Ast\AstMapExtractor depends on Qossmic\Deptrac\Core\InputCollector\InputCollectorInterface (InputCollector)
   .../deptrac/src/Core/Ast/AstMapExtractor.php:15
@@ -64,8 +64,8 @@ With the `debug:unused`-command you list all the rulesets that are not being use
 You can optionally specify a limit (`--limit=<int>`) of how many times can be the ruleset used to be considered unused. This is useful
 if you want to find dependencies that are barely used and may be a prime candidate to get rid of.
 
-```bash
-php deptrac.phar debug:unused --limit=10
+```console
+$ php deptrac.phar debug:unused --limit=10
 
   Analyser layer is dependent Layer layer 5 times
   Ast layer is dependent File layer 9 times

docs/formatters.md

@@ -4,8 +4,8 @@ Deptrac has support for different output formatters with various options.
 
 You can get a list of available formatters by running
 
-```bash
-php deptrac.php analyse --help
+```console
+$ php deptrac.php analyse --help
 ```
 
 ## Baseline Formatter