demos-europe / edt-paths
Tools to create paths between entities and entity properties.
Requires
- php: ^8.1
- demos-europe/edt-queries: ^0.26
- nikic/php-parser: ^4.14 || ^5
- phpdocumentor/reflection-docblock: ^5.1.0
- thecodingmachine/safe: ^2.4.0
Conflicts
- demos-europe/edt-access-definitions: <0.17.1
- demos-europe/edt-dql: <0.17.1
- demos-europe/edt-extra: <0.17.1
- demos-europe/edt-jsonapi: <0.17.1
- dev-main
- 0.26.0
- 0.25.0
- 0.24.42
- 0.24.41
- 0.24.40
- 0.24.39
- 0.24.38
- 0.24.37
- 0.24.36
- 0.24.35
- 0.24.34
- 0.24.33
- 0.24.32
- 0.24.31
- 0.24.30
- 0.24.29
- 0.24.28
- 0.24.27
- 0.24.26
- 0.24.25
- 0.24.24
- 0.24.23
- 0.24.22
- 0.24.21
- 0.24.20
- 0.24.19
- 0.24.18
- 0.24.17
- 0.24.16
- 0.24.15
- 0.24.14
- 0.24.13
- 0.24.12
- 0.24.11
- 0.24.10
- 0.24.9
- 0.24.8
- 0.24.7
- 0.24.6
- 0.24.5
- 0.24.4
- 0.24.3
- 0.24.2
- 0.24.1
- 0.24.0
- 0.23.6
- 0.23.5
- 0.23.4
- 0.23.3
- 0.23.2
- 0.23.1
- 0.23.0
- 0.22.3
- 0.22.2
- 0.22.1
- 0.22.0
- 0.21.4
- 0.21.3
- 0.21.2
- 0.21.1
- 0.21.0
- 0.20.1
- 0.19.0
- 0.18.0
- 0.17.5
- 0.16.1
- 0.16.0
- 0.15.1
- 0.15.0
- 0.14.1
- 0.14.0
- 0.13.2
- 0.13.1
- 0.13.0
- 0.12.23
- 0.12.22
- 0.12.21
- 0.12.20
- 0.12.19
- 0.12.18
- 0.12.17
- 0.12.16
- 0.12.15
- 0.12.14
- 0.12.13
- 0.12.12
- 0.12.11
- 0.12.10
- 0.12.9
- 0.12.8
- 0.12.7
- 0.12.6
- 0.12.5
- 0.12.4
- 0.12.3
- 0.12.2
- 0.12.1
- 0.12.0
- 0.11.2
- 0.11.1
- 0.11.0
- 0.10.0
- 0.9.0
- 0.8.0
- 0.7.1
- 0.7.0
- 0.6.4
- 0.6.3
- 0.6.2
- 0.6.1
This package is auto-updated.
Last update: 2024-10-20 20:36:49 UTC
README
Tools to create paths between entities and entity properties.
Provides PHP classes to enable you to use phpdoc tags to annotate classes as path segment and reference other path segments to define a directed graph, which can be used to build property paths for conditions and sort methods with IDE support.
Overview
This component enables you to mark classes as path segment and reference such classes in other classes as relationships.
To give an example suppose we have a class Comment
with a relationship to the class Article
which in turn has a relationship to the class Author
. If we want to build a path
using the property names of the relationships we could define an array like the following manually:
['article', 'author']
. For this you not only have to know the property names at the time
you write the path but also need to adjust all paths using a property when the name of the
property changes.
An alternative would be to define string constants in each class with the names of each
property. In this case you could do something like this [Comment::ARTICLE, Article::AUTHOR]
.
This way you can change the value of the constant without adjusting each path manually. Also,
your IDE can help you find each usage of a property in your application.
This component extends on these advantages and uses phpdoc @property-read
tags instead
of constants. As a result you can define the path with the following expression:
$comment→article→author→getAsNames()
. The result will be the same as in the examples above.
This way your IDE provides you with a list of available relationships at each segment and
can keep track of the usage of each @property-read
, allowing for easy property renaming.
To enable a class as path segment and add working @property-read
tags you only need to add
the PropertyAutoPathTrait
as use
inside your class. After that you can add @property-read
tags
with the type of the target class as shown below for the Article
class.
/** * @property-read Author $author * @property-read Comment $comments */ class Article { use \EDT\PathBuilding\PropertyAutoPathTrait; private $text; public function __construct(string $text) { $this->text = $text; } public function getText(): string { return $this->text; } }
By default, the constructor of your class will be ignored and a not fully initialized
instance will be returned. This means that you may
not be able to use the instances resulting from a path for anything else but further path
building. So the above class will work for $comment→article→authors→getAsNames()
but will
fail for $comment→article→getText()
.
However, if you pass a factory callback to the trait the path segments will be created using that callback, resulting in fully usable instances of your class. Such factory will depend on your system architecture. The following example can only give a rough idea, your solution may differ.
/** * @property-read Author $author * @property-read Comment $comments */ class Article { use \EDT\PathBuilding\PropertyAutoPathTrait; private $text; public function __construct(string $text, ArticleRepository $articleRepository) { $this->childCreateCallback = static function (string $class, $parent, string $parentPropertyName) use ($articleRepository) { if ($parent instanceof Comment) { $articleId = $parent->getArticleId(); $article = $articleRepository->getArticle($articleId); $article->setParent($parent); $article->setParentPropertyName($parentPropertyName); return $article; } if ($parent instanceof Author) { return $this->createChild($class, $parent, $parentPropertyName); } // ... more class checks }; $this->text = $text; } public function getText(): string { return $this->text; } }
Note that this example will fall back to the not fully initialized instances in case of
to-many relationships. This is the case because it would otherwise need to select an
Article
instance in case of paths like $author→articles
. Such paths can still be used
for further path building like $author→articles→comments→getAsNames()
. But like mentioned before it may fail
if methods of the actual class are used, like in the following access:
$author→articles→getText()
. This is a known limitation considered acceptable, as
the main usage is the building of paths, not a replacement of getters to fetch actual instances.
Supported tags
The example above uses the property-read
tag to add properties to your path class. This is the
default as it seems to make the most sense for the path building
use case, however you can change it to other tags if desired as shown below.
/** * @property Author $author * @property Comment $comments */ class Article { use \EDT\PathBuilding\PropertyAutoPathTrait; protected function getDocblockTraitEvaluator(): DocblockPropertyByTraitEvaluator { if (null === $this->docblockTraitEvaluator) { $this->docblockTraitEvaluator = PropertyEvaluatorPool::getInstance()->getEvaluator(PropertyAutoPathTrait::class, ['property']); // replaces the default 'property-read' } return $this->docblockTraitEvaluator; } }
You can set multiple tags too, as is shown below for the property-read
and property
tags.
/** * @property Author $author * @property Comment $comments */ class Article { use \EDT\PathBuilding\PropertyAutoPathTrait; protected function getDocblockTraitEvaluator(): DocblockPropertyByTraitEvaluator { if (null === $this->docblockTraitEvaluator) { $this->docblockTraitEvaluator = PropertyEvaluatorPool::getInstance()->getEvaluator(PropertyAutoPathTrait::class, ['property-read', 'property']); } return $this->docblockTraitEvaluator; } }
Supported tags are:
-
property
-
property-read
-
property-write
-
param
-
var
Credits and acknowledgements
Conception and implementation by Christian Dressler with many thanks to eFrane.