Add ExpressionValues (#112)

Author: HypeMC

CHANGELOG.md

@@ -7,9 +7,16 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [2.0.0] - xxxx-xx-xx
 
+### Added
+
+- `ExpressionValues` to enable resolution of route parameter values via expressions by @HypeMC
+  in https://github.com/sofascore/purgatory-bundle/pull/112
+
 ### Removed
 
 - Symfony v5 support by @HypeMC in https://github.com/sofascore/purgatory-bundle/pull/128
+- `InverseValuesAwareInterface`, use dedicated builder services instead by @HypeMC
+  in https://github.com/sofascore/purgatory-bundle/pull/123
 
 ## [1.3.0] - 2025-12-15
 

config/services.php

@@ -8,8 +8,10 @@
 use Sofascore\PurgatoryBundle\Cache\Configuration\ConfigurationLoader;
 use Sofascore\PurgatoryBundle\Cache\PropertyResolver\AssociationResolver;
 use Sofascore\PurgatoryBundle\Cache\PropertyResolver\EmbeddableResolver;
+use Sofascore\PurgatoryBundle\Cache\PropertyResolver\ExpressionLanguage\InverseRelationExpressionTransformer;
 use Sofascore\PurgatoryBundle\Cache\PropertyResolver\InverseValuesBuilder\CompoundInverseValuesBuilder;
 use Sofascore\PurgatoryBundle\Cache\PropertyResolver\InverseValuesBuilder\DynamicInverseValuesBuilder;
+use Sofascore\PurgatoryBundle\Cache\PropertyResolver\InverseValuesBuilder\ExpressionInverseValuesBuilder;
 use Sofascore\PurgatoryBundle\Cache\PropertyResolver\InverseValuesBuilder\PropertyInverseValuesBuilder;
 use Sofascore\PurgatoryBundle\Cache\PropertyResolver\MethodResolver;
 use Sofascore\PurgatoryBundle\Cache\PropertyResolver\PropertyResolver;
@@ -31,6 +33,7 @@
 use Sofascore\PurgatoryBundle\RouteParamValueResolver\CompoundValuesResolver;
 use Sofascore\PurgatoryBundle\RouteParamValueResolver\DynamicValuesResolver;
 use Sofascore\PurgatoryBundle\RouteParamValueResolver\EnumValuesResolver;
+use Sofascore\PurgatoryBundle\RouteParamValueResolver\ExpressionValuesResolver;
 use Sofascore\PurgatoryBundle\RouteParamValueResolver\PropertyValuesResolver;
 use Sofascore\PurgatoryBundle\RouteParamValueResolver\RawValuesResolver;
 use Sofascore\PurgatoryBundle\RouteProvider\AbstractEntityRouteProvider;
@@ -95,8 +98,8 @@
         ->set('sofascore.purgatory.subscription_resolver.association', AssociationResolver::class)
             ->tag('purgatory.subscription_resolver')
             ->args([
-                service('property_info.reflection_extractor'),
                 tagged_locator('purgatory.inverse_values_builder', defaultIndexMethod: 'for'),
+                service('sofascore.purgatory.inverse_relation_expression_transformer'),
             ])
 
         ->set('sofascore.purgatory.subscription_resolver.embeddable', EmbeddableResolver::class)
@@ -105,6 +108,11 @@
                 service('doctrine'),
             ])
 
+        ->set('sofascore.purgatory.inverse_relation_expression_transformer', InverseRelationExpressionTransformer::class)
+            ->args([
+                service('property_info.reflection_extractor'),
+            ])
+
         ->set('sofascore.purgatory.inverse_values_builder.compound', CompoundInverseValuesBuilder::class)
             ->tag('purgatory.inverse_values_builder')
             ->args([
@@ -114,6 +122,12 @@
         ->set('sofascore.purgatory.inverse_values_builder.dynamic', DynamicInverseValuesBuilder::class)
             ->tag('purgatory.inverse_values_builder')
 
+        ->set('sofascore.purgatory.inverse_values_builder.expression', ExpressionInverseValuesBuilder::class)
+            ->tag('purgatory.inverse_values_builder')
+            ->args([
+                service('sofascore.purgatory.inverse_relation_expression_transformer'),
+            ])
+
         ->set('sofascore.purgatory.inverse_values_builder.property', PropertyInverseValuesBuilder::class)
             ->tag('purgatory.inverse_values_builder')
 
@@ -240,6 +254,12 @@
                 service('sofascore.purgatory.property_accessor'),
             ])
 
+        ->set('sofascore.purgatory.route_parameter_resolver.expression', ExpressionValuesResolver::class)
+            ->tag('purgatory.route_param_value_resolver')
+            ->args([
+                service('sofascore.purgatory.expression_language')->nullOnInvalid(),
+            ])
+
         ->set('sofascore.purgatory.property_accessor', PurgatoryPropertyAccessor::class)
             ->args([
                 service('property_accessor'),

docs/complex-route-params.md

@@ -119,10 +119,31 @@ public function listAction(string $lang)
 In this example, multiple URLs are generated based on all values from the `LanguageCodes` enum and the raw value `XK`
 for the `lang` parameter.
 
+### Using Values Provided by an Expression
+
+You can also map route parameters to values provided dynamically using a **Symfony ExpressionLanguage** expression.
+This is useful when a route parameter cannot be mapped directly to a single property and needs to be composed or
+transformed.
+
+In these expressions, the entity is available as the `obj` variable:
+
+```php
+use Sofascore\PurgatoryBundle\Attribute\RouteParamValue\ExpressionValues;
+
+#[Route('/posts-by-author/{full_name}', name: 'posts_list_by_author', methods: 'GET')]
+#[PurgeOn(Author::class, routeParams: ['full_name' => new ExpressionValues('obj.firstName~"-"~obj.lastName')])]
+public function listAction(Author $author)
+{
+}
+```
+
+You can also add [custom Expression Language functions](custom-expression-language-functions.md) to extend the available
+expression syntax.
+
 ### Using Values Provided by a Service
 
-You can also map route parameters to values provided dynamically by a service. This is particularly useful when you need
-route parameters that depend on context or runtime information:
+As an alternative to expressions, route parameter values can be provided dynamically by a service. This is particularly
+useful when you need route parameters that depend on context or runtime information:
 
 ```php
 use Sofascore\PurgatoryBundle\Attribute\RouteParamValue\DynamicValues;

docs/custom-expression-language-functions.md

@@ -1,6 +1,7 @@
 # Custom Expression Language Functions
 
-You can add custom functions to the Expression Language for use with the `if` parameter.
+You can add custom Expression Language functions that can be used by expressions defined in `ExpressionValues` or the
+`if` parameter.
 
 ```php
 #[Route('/post/{id<\d+>}', name: 'post_details', methods: 'GET')]

docs/purge-subscriptions-using-yaml.md

@@ -58,6 +58,12 @@ posts_list:
             - !enum App\Enum\LanguageCodes
             - !raw XK
 
+# Using values provided by an expression
+posts_list_by_author:
+    class: App\Entity\Author
+    route_params:
+        full_name: !expression 'obj.firstName~"-"~obj.lastName'
+
 # Using values provided by a service
 posts_list:
     class: App\Entity\Post

phpstan-baseline.neon

@@ -42,6 +42,12 @@ parameters:
 			count: 1
 			path: src/Cache/RouteMetadata/YamlMetadataProvider.php
 
+		-
+			message: '#^Parameter \#1 \$expression of class Sofascore\\PurgatoryBundle\\Attribute\\RouteParamValue\\ExpressionValues constructor expects string\|Symfony\\Component\\ExpressionLanguage\\Expression, bool\|float\|int\|list\<bool\|float\|int\|string\|Symfony\\Component\\Yaml\\Tag\\TaggedValue\>\|string given\.$#'
+			identifier: argument.type
+			count: 1
+			path: src/Cache/RouteMetadata/YamlMetadataProvider.php
+
 		-
 			message: '#^Parameter \#1 \$property of class Sofascore\\PurgatoryBundle\\Attribute\\RouteParamValue\\PropertyValues constructor expects string, bool\|float\|int\|string\|Symfony\\Component\\Yaml\\Tag\\TaggedValue given\.$#'
 			identifier: argument.type

psalm-baseline.xml

@@ -23,6 +23,11 @@
       <code><![CDATA[$alias]]></code>
     </PossiblyUndefinedArrayOffset>
   </file>
+  <file src="src/Cache/PropertyResolver/InverseValuesBuilder/ExpressionInverseValuesBuilder.php">
+    <PossiblyUndefinedArrayOffset>
+      <code><![CDATA[$expression]]></code>
+    </PossiblyUndefinedArrayOffset>
+  </file>
   <file src="src/Cache/RouteMetadata/AttributeMetadataProvider.php">
     <PossiblyUndefinedArrayOffset>
       <code><![CDATA[$method]]></code>
@@ -38,6 +43,7 @@
     </ArgumentTypeCoercion>
     <InvalidArgument>
       <code><![CDATA[$value]]></code>
+      <code><![CDATA[$value]]></code>
     </InvalidArgument>
     <PossiblyInvalidArgument>
       <code><![CDATA[$value]]></code>

src/Attribute/RouteParamValue/ExpressionValues.php

@@ -0,0 +1,53 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Sofascore\PurgatoryBundle\Attribute\RouteParamValue;
+
+use Sofascore\PurgatoryBundle\Exception\LogicException;
+use Symfony\Component\ExpressionLanguage\Expression;
+
+final class ExpressionValues extends AbstractValues
+{
+    private readonly Expression $expression;
+
+    public function __construct(
+        string|Expression $expression,
+    ) {
+        $this->expression = self::normalizeExpression($expression);
+    }
+
+    /**
+     * @return list<Expression>
+     */
+    public function getValues(): array
+    {
+        return [$this->expression];
+    }
+
+    public function toArray(): array
+    {
+        return [
+            'type' => self::type(),
+            'values' => [(string) $this->expression],
+        ];
+    }
+
+    public static function type(): string
+    {
+        return 'expression';
+    }
+
+    private static function normalizeExpression(string|Expression $expression): Expression
+    {
+        if ($expression instanceof Expression) {
+            return $expression;
+        }
+
+        if (!class_exists(Expression::class)) {
+            throw new LogicException(\sprintf('You cannot use "%s" because the Symfony ExpressionLanguage component is not installed. Try running "composer require symfony/expression-language".', self::class));
+        }
+
+        return new Expression($expression);
+    }
+}

src/Cache/PropertyResolver/AssociationResolver.php

@@ -10,19 +10,16 @@
 use Doctrine\Persistence\Mapping\ClassMetadata;
 use Psr\Container\ContainerInterface;
 use Sofascore\PurgatoryBundle\Attribute\RouteParamValue\ValuesInterface;
+use Sofascore\PurgatoryBundle\Cache\PropertyResolver\ExpressionLanguage\InverseRelationExpressionTransformer;
 use Sofascore\PurgatoryBundle\Cache\PropertyResolver\InverseValuesBuilder\InverseValuesBuilderInterface;
 use Sofascore\PurgatoryBundle\Cache\RouteMetadata\RouteMetadata;
 use Sofascore\PurgatoryBundle\Cache\Subscription\PurgeSubscription;
-use Sofascore\PurgatoryBundle\Exception\PropertyNotAccessibleException;
-use Symfony\Component\ExpressionLanguage\Expression;
-use Symfony\Component\PropertyInfo\PropertyReadInfo;
-use Symfony\Component\PropertyInfo\PropertyReadInfoExtractorInterface;
 
 final class AssociationResolver implements SubscriptionResolverInterface
 {
     public function __construct(
-        private readonly PropertyReadInfoExtractorInterface $extractor,
         private readonly ContainerInterface $inverseValuesBuilderLocator,
+        private readonly InverseRelationExpressionTransformer $expressionTransformer,
     ) {
     }
 
@@ -76,10 +73,7 @@ public function resolveSubscription(
         }
 
         if (null !== $if = $routeMetadata->purgeOn->if) {
-            $expression = (string) $if;
-            $getter = $this->createGetter($associationClass, $associationTarget);
-            $inverseIf = str_replace('obj', 'obj.'.$getter, $expression);
-            $if = new Expression("obj.$getter !== null && ($inverseIf)");
+            $if = $this->expressionTransformer->transform($if, $associationClass, $associationTarget, 'false');
         }
 
         yield new PurgeSubscription(
@@ -111,19 +105,4 @@ private function getInverseValuesBuilderFor(ValuesInterface $values): ?InverseVa
 
         return $builder;
     }
-
-    private function createGetter(string $class, string $property): string
-    {
-        if (null === $readInfo = $this->extractor->getReadInfo($class, $property)) {
-            throw new PropertyNotAccessibleException($class, $property);
-        }
-
-        /** @var PropertyReadInfo::TYPE_* $type */
-        $type = $readInfo->getType();
-
-        return match ($type) {
-            PropertyReadInfo::TYPE_METHOD => $readInfo->getName().'()',
-            PropertyReadInfo::TYPE_PROPERTY => $readInfo->getName(),
-        };
-    }
 }

src/Cache/PropertyResolver/ExpressionLanguage/InverseRelationExpressionTransformer.php

@@ -0,0 +1,44 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Sofascore\PurgatoryBundle\Cache\PropertyResolver\ExpressionLanguage;
+
+use Sofascore\PurgatoryBundle\Exception\PropertyNotAccessibleException;
+use Symfony\Component\ExpressionLanguage\Expression;
+use Symfony\Component\PropertyInfo\PropertyReadInfo;
+use Symfony\Component\PropertyInfo\PropertyReadInfoExtractorInterface;
+
+/**
+ * @internal
+ */
+final class InverseRelationExpressionTransformer
+{
+    public function __construct(
+        private readonly PropertyReadInfoExtractorInterface $extractor,
+    ) {
+    }
+
+    public function transform(Expression $expression, string $class, string $property, string $fallback): Expression
+    {
+        $getter = $this->createGetter($class, $property);
+        $inverseExpression = str_replace('obj', 'obj.'.$getter, (string) $expression);
+
+        return new Expression("obj.$getter !== null ? ($inverseExpression) : $fallback");
+    }
+
+    private function createGetter(string $class, string $property): string
+    {
+        if (null === $readInfo = $this->extractor->getReadInfo($class, $property)) {
+            throw new PropertyNotAccessibleException($class, $property);
+        }
+
+        /** @var PropertyReadInfo::TYPE_* $type */
+        $type = $readInfo->getType();
+
+        return match ($type) {
+            PropertyReadInfo::TYPE_METHOD => $readInfo->getName().'()',
+            PropertyReadInfo::TYPE_PROPERTY => $readInfo->getName(),
+        };
+    }
+}