BuilderExtensions POC

Author: xwero

Eloquent/Attributes/BuilderExtension.php

@@ -0,0 +1,16 @@
+<?php
+
+namespace Illuminate\Database\Eloquent\Attributes;
+
+use Attribute;
+
+#[Attribute(Attribute::TARGET_METHOD | Attribute::TARGET_CLASS | Attribute::IS_REPEATABLE)]
+class BuilderExtension
+{
+    public mixed $identifiers;
+
+    public function __construct(mixed ...$identifiers)
+    {
+        $this->identifiers = $identifiers;
+    }
+}

Eloquent/Builder.php

@@ -136,6 +136,8 @@ class Builder implements BuilderContract
         'torawsql',
     ];
 
+    protected array $extensions = [];
+
     /**
      * Applied global scopes.
      *
@@ -203,6 +205,11 @@ public function withGlobalScope($identifier, $scope)
         return $this;
     }
 
+    public function addBuilderExtension($extension, $extensionType)
+    {
+        $this->extensions[$extension] = $extensionType;
+    }
+
     /**
      * Remove a registered global scope.
      *
@@ -1378,9 +1385,10 @@ protected function addUpdatedAtToUpsertColumns(array $update)
     /**
      * Delete records from the database.
      *
+     * @param null $id
      * @return mixed
      */
-    public function delete()
+    public function delete($id = null)
     {
         if (isset($this->onDelete)) {
             return call_user_func($this->onDelete, $this);
@@ -1423,6 +1431,26 @@ public function hasNamedScope($scope)
         return $this->model && $this->model->hasNamedScope($scope);
     }
 
+    public function hasLocalBuilderExtension($builderExtension) : bool
+    {
+        return $this->model && $this->model->hasLocalBuilderExtension($builderExtension);
+    }
+
+    public function hasRegularBuilderExtension($builderExtension) : bool
+    {
+        $regularBuilderExtensions = array_filter($this->extensions, function ($extensionType, $extension){
+            return $extensionType == BuilderExtensionType::REGULAR;
+        }, ARRAY_FILTER_USE_BOTH);
+
+        foreach ($regularBuilderExtensions as $extension => $extensionType) {
+            if(str_contains(strtolower($extension), strtolower($builderExtension))) {
+                return true;
+            }
+        }
+
+        return false;
+    }
+
     /**
      * Call the given local model scopes.
      *
@@ -1459,11 +1487,21 @@ public function scopes($scopes)
      */
     public function applyScopes()
     {
-        if (! $this->scopes) {
-            return $this;
+        $builder = clone $this;
+
+        $requiredBuilderExtensions = array_filter($this->extensions, function($extensionType, $extension) {
+            return $extensionType == BuilderExtensionType::REQUIRED;
+        }, ARRAY_FILTER_USE_BOTH);
+
+        if(count($requiredBuilderExtensions) > 0) {
+            foreach ($requiredBuilderExtensions as $extension => $extensionType) {
+                new $extension()->apply($builder);
+            }
         }
 
-        $builder = clone $this;
+        if (! $this->scopes) {
+            return $builder;
+        }
 
         foreach ($this->scopes as $identifier => $scope) {
             if (! isset($builder->scopes[$identifier])) {
@@ -1533,6 +1571,31 @@ protected function callNamedScope($scope, array $parameters = [])
         }, $parameters);
     }
 
+    protected function callLocalBuilderExtension($builderExtension, array $parameters = []) : Builder
+    {
+        $this->model->$builderExtension($this, $parameters);
+
+        return $this;
+    }
+
+    protected function callRegularBuilderExtension($builderExtension, array $parameters = []) : Builder
+    {
+        $regularBuilderExtensions = array_filter($this->extensions, function ($extensionType, $extension) use($builderExtension) {
+            return $extensionType == BuilderExtensionType::REGULAR &&
+                str_contains(strtolower($extension), strtolower($builderExtension));
+        }, ARRAY_FILTER_USE_BOTH);
+
+        if(count($regularBuilderExtensions) == 0) {
+            throw new \LogicException('callRegularBuilderExtension method called without extension exist chack.');
+        }
+
+        $extension = array_key_first($regularBuilderExtensions);
+
+        new $extension()->apply($this);
+
+        return $this;
+    }
+
     /**
      * Nest where conditions by slicing them at the given where count.
      *
@@ -2135,6 +2198,14 @@ public function __call($method, $parameters)
             return $callable(...$parameters);
         }
 
+        if($this->hasLocalBuilderExtension($method)) {
+            return $this->callLocalBuilderExtension($method, $parameters);
+        }
+
+        if($this->hasRegularBuilderExtension($method)) {
+            return $this->callRegularBuilderExtension($method, $parameters);
+        }
+
         if ($this->hasNamedScope($method)) {
             return $this->callNamedScope($method, $parameters);
         }

Eloquent/BuilderExtension.php

@@ -0,0 +1,8 @@
+<?php
+
+namespace Illuminate\Database\Eloquent;
+
+interface BuilderExtension
+{
+    public function apply(Builder &$builder);
+}

Eloquent/BuilderExtensionType.php

@@ -0,0 +1,11 @@
+<?php
+
+namespace Illuminate\Database\Eloquent;
+
+enum BuilderExtensionType : int
+{
+    case REGULAR = 0;
+    case REQUIRED = 1;
+
+    case LOCALE = 2;
+}

Eloquent/Model.php

@@ -11,6 +11,7 @@
 use Illuminate\Contracts\Support\CanBeEscapedWhenCastToString;
 use Illuminate\Contracts\Support\Jsonable;
 use Illuminate\Database\ConnectionResolverInterface as Resolver;
+use Illuminate\Database\Eloquent\Attributes\BuilderExtension;
 use Illuminate\Database\Eloquent\Attributes\Scope as LocalScope;
 use Illuminate\Database\Eloquent\Collection as EloquentCollection;
 use Illuminate\Database\Eloquent\Relations\BelongsToMany;
@@ -25,6 +26,7 @@
 use JsonException;
 use JsonSerializable;
 use LogicException;
+use ReflectionClass;
 use ReflectionMethod;
 use Stringable;
 
@@ -162,6 +164,8 @@ abstract class Model implements Arrayable, ArrayAccess, CanBeEscapedWhenCastToSt
      */
     protected static $globalScopes = [];
 
+    protected static array $builderExtensions = [];
+
     /**
      * The list of models classes that should not be affected with touch.
      *
@@ -300,6 +304,68 @@ protected static function booting()
     protected static function boot()
     {
         static::bootTraits();
+        static::bootBuilderExtensions();
+    }
+
+    protected static function bootBuilderExtensions()
+    {
+        static::$builderExtensions = [];
+        $reflectionClass = new ReflectionClass(static::class);
+
+        $classBuilderExtensions = $reflectionClass->getAttributes(BuilderExtension::class);
+
+        foreach ($classBuilderExtensions as $classBuilderExtension) {
+            $arguments = $classBuilderExtension->getArguments();
+            $argumentsCount = count($arguments);
+
+            if($argumentsCount == 0){
+                throw new LogicException('Builder Extension must have at least one argument');
+            }
+
+            if($argumentsCount > 2) {
+                throw new LogicException('Builder Extension has maximun two arguments');
+            }
+
+            if($argumentsCount == 1){
+                $argument = $arguments[0];
+
+                if(is_string($argument)){
+                    static::$builderExtensions[$argument] = BuilderExtensionType::REGULAR;
+                } elseif(is_array($argument)){
+                    if(is_string(array_key_first($argument))){
+                        foreach($argument as $extension => $extensionType){
+                            static::$builderExtensions[$extension] = $extensionType;
+                        }
+                    } else {
+                        foreach($argument as $extension){
+                            static::$builderExtensions[$extension] = BuilderExtensionType::REGULAR;
+                        }
+                    }
+                }
+            }
+
+            if($argumentsCount == 2){
+                static::$builderExtensions[$arguments[0]] = $arguments[1];
+            }
+        }
+
+        $methods = $reflectionClass->getMethods(\ReflectionMethod::IS_PUBLIC);
+
+        foreach ($methods as $method) {
+            $attributes = $method->getAttributes(BuilderExtension::class);
+
+            if(count($attributes) > 1){
+                throw new LogicException('a method can have only one BuilderExtension attribute');
+            }
+
+            if(count($attributes) == 1 && count($attributes[0]->getArguments()) > 0){
+                throw new LogicException('a method BuilderExtension attribute as no arguments');
+            }
+
+            if(count($attributes) == 1) {
+                static::$builderExtensions[$method->getName()] = BuilderExtensionType::LOCALE;
+            }
+        }
     }
 
     /**
@@ -366,6 +432,8 @@ public static function clearBootedModels()
         static::$booted = [];
 
         static::$globalScopes = [];
+
+        static::$builderExtensions = [];
     }
 
     /**
@@ -1522,7 +1590,7 @@ public static function query()
      */
     public function newQuery()
     {
-        return $this->registerGlobalScopes($this->newQueryWithoutScopes());
+        return $this->registerBuilderExtensions($this->registerGlobalScopes($this->newQueryWithoutScopes()));
     }
 
     /**
@@ -1544,7 +1612,7 @@ public function newModelQuery()
      */
     public function newQueryWithoutRelationships()
     {
-        return $this->registerGlobalScopes($this->newModelQuery());
+        return $this->registerBuilderExtensions($this->registerGlobalScopes($this->newModelQuery()));
     }
 
     /**
@@ -1562,6 +1630,19 @@ public function registerGlobalScopes($builder)
         return $builder;
     }
 
+    public function registerBuilderExtensions(Builder $builder)
+    {
+        $builderExtensions = array_filter(static::$builderExtensions, function($builderExtensionType, $builderExtension) {
+            return in_array($builderExtensionType, [BuilderExtensionType::REGULAR, BuilderExtensionType::REQUIRED]);
+        }, ARRAY_FILTER_USE_BOTH);
+
+        foreach ($builderExtensions as $builderExtension => $builderExtensionType) {
+            $builder->addBuilderExtension($builderExtension, $builderExtensionType);
+        }
+
+        return $builder;
+    }
+
     /**
      * Get a new query builder that doesn't have any global scopes.
      *
@@ -1633,6 +1714,11 @@ public function newPivot(self $parent, array $attributes, $table, $exists, $usin
             : Pivot::fromAttributes($parent, $attributes, $table, $exists);
     }
 
+    public Function hasBuilderExtension($name) : bool
+    {
+        return isset(static::$builderExtensions[$name]);
+    }
+
     /**
      * Determine if the model has a given scope.
      *
@@ -1645,6 +1731,11 @@ public function hasNamedScope($scope)
             static::isScopeMethodWithAttribute($scope);
     }
 
+    public function hasLocalBuilderExtension($name) : bool
+    {
+        return isset(static::$builderExtensions[$name]) && static::$builderExtensions[$name] == BuilderExtensionType::LOCALE;
+    }
+
     /**
      * Apply the given named scope if possible.
      *
@@ -1654,7 +1745,11 @@ public function hasNamedScope($scope)
      */
     public function callNamedScope($scope, array $parameters = [])
     {
-        if ($this->isScopeMethodWithAttribute($scope)) {
+        $localBuilderExtensions = array_filter(static::$builderExtensions, function($builderExtensionType, $builderExtension) {
+            return $builderExtensionType === BuilderExtensionType::LOCALE;
+        }, ARRAY_FILTER_USE_BOTH);
+
+        if ($this->isScopeMethodWithAttribute($scope) || in_array($scope, array_keys($localBuilderExtensions))) {
             return $this->{$scope}(...$parameters);
         }
 

composer.json

@@ -15,7 +15,7 @@
         }
     ],
     "require": {
-        "php": "^8.3",
+        "php": "^8.4",
         "ext-pdo": "*",
         "brick/math": "^0.11|^0.12",
         "illuminate/collections": "^13.0",