feat: add functions

Author: calebdw

README.md

@@ -222,8 +222,82 @@ class RecentOrdersView extends View
 
 <!-- #### 💿 Materialized View -->
 <!---->
-<!-- #### 🛠 Function -->
-<!---->
+#### 📐 Function
+
+The `Function_` class is used to create functions in the database.
+
+> [!TIP]
+> The class is named `Function_` as `function` is a reserved keyword in PHP.
+
+In addition to the options above, you can use the following options to further customize the function:
+
+```php
+<?php
+
+namespace Database\Entities\Functions;
+
+use CalebDW\SqlEntities\Function_;
+
+class Add extends Function_
+{
+    /** If the function aggregates. */
+    protected bool $aggregate = false;
+
+    protected array $arguments = [
+        'integer',
+        'integer',
+    ];
+
+    /** The language the function is written in. */
+    protected string $language = 'SQL';
+
+    protected array $characteristics = [];
+
+    /** The function return type. */
+    protected string $returns = 'integer';
+
+    #[Override]
+    public function definition(): string
+    {
+        return <<<'SQL'
+            RETURN $1 + $2;
+            SQL;
+    }
+}
+```
+
+Loadable functions are also supported:
+
+```php
+<?php
+
+namespace Database\Entities\Functions;
+
+use CalebDW\SqlEntities\Function_;
+
+class Add extends Function_
+{
+    protected array $arguments = [
+        'integer',
+        'integer',
+    ];
+
+    /** The language the function is written in. */
+    protected string $language = 'c';
+
+    protected bool $loadable = true;
+
+    /** The function return type. */
+    protected string $returns = 'integer';
+
+    #[Override]
+    public function definition(): string
+    {
+        return 'c_add';
+    }
+}
+```
+
 <!-- #### 📤 Procedure -->
 <!---->
 <!-- #### ⚡ Trigger -->

src/Function_.php

@@ -0,0 +1,83 @@
+<?php
+
+declare(strict_types=1);
+
+namespace CalebDW\SqlEntities;
+
+use CalebDW\SqlEntities\Concerns\DefaultSqlEntityBehaviour;
+use CalebDW\SqlEntities\Contracts\SqlEntity;
+
+abstract class Function_ implements SqlEntity
+{
+    use DefaultSqlEntityBehaviour;
+
+    /** If the function aggregates. */
+    protected bool $aggregate = false;
+
+    /**
+     * The function arguments.
+     *
+     * @var list<string>
+     */
+    protected array $arguments = [];
+
+    /** The language the function is written in. */
+    protected string $language = 'SQL';
+
+    /** If the function is loadable. */
+    protected bool $loadable = false;
+
+    /**
+     * The function characteristics.
+     *
+     * @var list<string>
+     */
+    protected array $characteristics = [];
+
+    /** The function return type. */
+    protected string $returns = '';
+
+    /** The language the function is written in. */
+    public function aggregate(): bool
+    {
+        return $this->aggregate;
+    }
+
+    /**
+     * The function arguments.
+     *
+     * @return list<string>
+     */
+    public function arguments(): array
+    {
+        return $this->arguments;
+    }
+
+    /**
+     * The function characteristics.
+     *
+     * @return list<string>
+     */
+    public function characteristics(): array
+    {
+        return $this->characteristics;
+    }
+
+    /** The language the function is written in. */
+    public function language(): string
+    {
+        return $this->language;
+    }
+
+    /** If the function is loadable. */
+    public function loadable(): bool
+    {
+        return $this->loadable;
+    }
+
+    /** The function return type. */
+    public function returns(): string
+    {
+        return $this->returns;
+    }
+}

src/Grammars/Grammar.php

@@ -5,6 +5,7 @@
 namespace CalebDW\SqlEntities\Grammars;
 
 use CalebDW\SqlEntities\Contracts\SqlEntity;
+use CalebDW\SqlEntities\Function_;
 use CalebDW\SqlEntities\View;
 use Illuminate\Database\Connection;
 use Illuminate\Support\Str;
@@ -17,10 +18,12 @@ public function __construct(
     ) {
     }
 
+    /** Compile the SQL statement to create the entity. */
     public function compileCreate(SqlEntity $entity): string
     {
         $statement = match (true) {
-            $entity instanceof View => $this->compileViewCreate($entity),
+            $entity instanceof Function_ => $this->compileFunctionCreate($entity),
+            $entity instanceof View      => $this->compileViewCreate($entity),
 
             default => throw new InvalidArgumentException(
                 sprintf('Unsupported entity [%s].', $entity::class),
@@ -30,10 +33,12 @@ public function compileCreate(SqlEntity $entity): string
         return $this->clean($statement);
     }
 
+    /** Compile the SQL statement to drop the entity. */
     public function compileDrop(SqlEntity $entity): string
     {
         $statement = match (true) {
-            $entity instanceof View => $this->compileViewDrop($entity),
+            $entity instanceof Function_ => $this->compileFunctionDrop($entity),
+            $entity instanceof View      => $this->compileViewDrop($entity),
 
             default => throw new InvalidArgumentException(
                 sprintf('Unsupported entity [%s].', $entity::class),
@@ -47,10 +52,21 @@ public function compileDrop(SqlEntity $entity): string
     public function supportsEntity(SqlEntity $entity): bool
     {
         return match (true) {
-            $entity instanceof View        => true,
-            default                        => false,
+            $entity instanceof Function_ => true,
+            $entity instanceof View      => true,
+            default                      => false,
         };
     }
+
+    abstract protected function compileFunctionCreate(Function_ $entity): string;
+
+    protected function compileFunctionDrop(Function_ $entity): string
+    {
+        return <<<SQL
+            DROP FUNCTION IF EXISTS {$entity->name()}
+            SQL;
+    }
+
     abstract protected function compileViewCreate(View $entity): string;
 
     protected function compileViewDrop(View $entity): string
@@ -88,7 +104,12 @@ protected function compileCheckOption(string|true|null $option): string
     protected function clean(string $value): string
     {
         return Str::of($value)
-            ->replaceMatches('/ +/', ' ')
+            // remove extra spaces in between words
+            ->replaceMatches('/(?<=\S) {2,}(?=\S)/', ' ')
+            // remove trailing spaces at end of line
+            ->replaceMatches('/ +\n/', "\n")
+            // remove duplicate new lines
+            ->replaceMatches('/\n{2,}/', "\n")
             ->trim()
             ->value();
     }

src/Grammars/MariaDbGrammar.php

@@ -4,11 +4,33 @@
 
 namespace CalebDW\SqlEntities\Grammars;
 
+use CalebDW\SqlEntities\Function_;
 use CalebDW\SqlEntities\View;
 use Override;
 
 class MariaDbGrammar extends Grammar
 {
+    #[Override]
+    protected function compileFunctionCreate(Function_ $entity): string
+    {
+        $arguments       = $this->compileList($entity->arguments());
+        $aggregate       = $entity->aggregate() ? 'AGGREGATE' : '';
+        $characteristics = implode("\n", $entity->characteristics());
+        $definition      = $entity->toString();
+
+        if ($entity->loadable()) {
+            $arguments  = '';
+            $definition = "SONAME {$definition}";
+        }
+
+        return <<<SQL
+            CREATE OR REPLACE {$aggregate} FUNCTION {$entity->name()}{$arguments}
+            RETURNS {$entity->returns()}
+            {$characteristics}
+            {$definition}
+            SQL;
+    }
+
     #[Override]
     protected function compileViewCreate(View $entity): string
     {

src/Grammars/MySqlGrammar.php

@@ -4,11 +4,34 @@
 
 namespace CalebDW\SqlEntities\Grammars;
 
+use CalebDW\SqlEntities\Function_;
 use CalebDW\SqlEntities\View;
 use Override;
 
 class MySqlGrammar extends Grammar
 {
+    #[Override]
+    protected function compileFunctionCreate(Function_ $entity): string
+    {
+        $arguments       = $this->compileList($entity->arguments());
+        $aggregate       = '';
+        $definition      = $entity->toString();
+        $characteristics = implode("\n", $entity->characteristics());
+
+        if ($entity->loadable()) {
+            $aggregate  = $entity->aggregate() ? 'AGGREGATE' : '';
+            $arguments  = '';
+            $definition = "SONAME {$definition}";
+        }
+
+        return <<<SQL
+            CREATE {$aggregate} FUNCTION IF NOT EXISTS {$entity->name()}{$arguments}
+            RETURNS {$entity->returns()}
+            {$characteristics}
+            {$definition}
+            SQL;
+    }
+
     #[Override]
     protected function compileViewCreate(View $entity): string
     {

src/Grammars/PostgresGrammar.php

@@ -4,11 +4,45 @@
 
 namespace CalebDW\SqlEntities\Grammars;
 
+use CalebDW\SqlEntities\Function_;
 use CalebDW\SqlEntities\View;
 use Override;
 
 class PostgresGrammar extends Grammar
 {
+    #[Override]
+    protected function compileFunctionCreate(Function_ $entity): string
+    {
+        $arguments       = $this->compileList($entity->arguments());
+        $language        = $entity->language();
+        $definition      = $entity->toString();
+        $characteristics = implode("\n", $entity->characteristics());
+
+        $definition = match (true) {
+            $entity->loadable()             => "AS {$definition}",
+            strtolower($language) !== 'sql' => "AS \$function$\n{$definition}\n\$function$",
+            default                         => $definition,
+        };
+
+        return <<<SQL
+            CREATE OR REPLACE FUNCTION {$entity->name()}{$arguments}
+            RETURNS {$entity->returns()}
+            LANGUAGE {$language}
+            {$characteristics}
+            {$definition}
+            SQL;
+    }
+
+    #[Override]
+    protected function compileFunctionDrop(Function_ $entity): string
+    {
+        $arguments = $this->compileList($entity->arguments());
+
+        return <<<SQL
+            DROP FUNCTION IF EXISTS {$entity->name()}{$arguments}
+            SQL;
+    }
+
     #[Override]
     protected function compileViewCreate(View $entity): string
     {

src/Grammars/SQLiteGrammar.php

@@ -4,11 +4,30 @@
 
 namespace CalebDW\SqlEntities\Grammars;
 
+use CalebDW\SqlEntities\Contracts\SqlEntity;
+use CalebDW\SqlEntities\Function_;
 use CalebDW\SqlEntities\View;
 use Override;
+use RuntimeException;
 
 class SQLiteGrammar extends Grammar
 {
+    #[Override]
+    public function supportsEntity(SqlEntity $entity): bool
+    {
+        return match (true) {
+            $entity instanceof Function_ => false,
+
+            default => parent::supportsEntity($entity),
+        };
+    }
+
+    #[Override]
+    protected function compileFunctionCreate(Function_ $entity): string
+    {
+        throw new RuntimeException('SQLite does not support user-defined functions.');
+    }
+
     #[Override]
     protected function compileViewCreate(View $entity): string
     {