Start of database schemas + migrations

docs/migrations.md

@@ -0,0 +1,103 @@
+---
+id: migrations
+title: migrations
+slug: /migrations
+---
+
+Get your desired schema applied to a database by running migrations. Migrations
+are split into two parts: a constructive part and a destructive part. The
+constructive part is meant to be run automatically, it should no break any
+existing code. When this is done and the new code has been deployed and no old
+is live anymore, the destructive part can be run manually.
+
+This makes sure database changes related to each are colocated in the same
+migration, but can be run on different times. Replacing one feature for another
+would be a great use case.
+
+## Migration class
+
+Migrations are created by creating a class that extends
+`Access\Migrations\Migration`. This class has two abstract methods that you
+need to override to make the migration functional: `constructive` and
+`revertConstructive`.
+
+```php
+class SomeMigration extends Migration
+{
+    public function constructive(SchemaChanges $schemaChanges): void
+    {
+        $schemaChanges->createTable('users');
+    }
+
+    public function revertConstructive(SchemaChanges $schemaChanges): void
+    {
+        $schemaChanges->dropTable('users');
+    }
+}
+```
+
+The `SchemaChanges` argument is used to add changes you the migration will
+apply to the database.
+
+## Migrator
+
+Once the migration is created, it needs to be executed. For this, the
+`Migrator` class exists. First the table that keep track of which migrations
+are already executed needs to be created.
+
+```php
+$db = ...;
+$migrator = new Migrator($db);
+$migrator->init();
+```
+
+After the migrator has been initialized, the first migration can be run:
+
+```php
+$migration = new SomeMigration();
+$result = $migrator->constructive($migration);
+```
+
+The `$result` will be a `MigrationResult` that contains a status and the
+queries that have been executed.
+
+## Checkpoints
+
+When developing migrations it can be a hassle if one of the queries fails for
+one reason or another. The database is in an inconsistent state and running a
+migration again might no be possible because one of the queries in the
+migration _did_ succeed. By using a checkpoint when running a migration it is
+possible to skip some steps of a migration. A checkpoint is a simple number
+that counts executed steps of a migration, nothing more, nothing less.
+
+A failed `MigrationResult` will contain a checkpoint that tells which queries
+did succeeed, passing that checkpoint to any of the migrator methods will point
+to the same step. Without any changes to the migration and/or database, and
+passing the checkpoint from the result to the mgirator will fail on exactly the
+same query.
+
+```php
+$migration = new SomeMigration();
+
+// Skip first step/query of the migration
+$checkpoint = new Checkpoint(1);
+
+$result = $migrator->constructive($migration, $checkpoint);
+```
+
+## Migrations lifecycle
+
+Migrations go through a specific lifecycle.
+
+```mermaid
+stateDiagram-v2
+[*] --> NotInitialized
+NotInitialized --> Initialized : init()
+Initialized --> ConstructiveExecuted : constructive()
+ConstructiveExecuted --> ConstructiveReverted : revertConstructive()
+ConstructiveExecuted --> DestructiveExecuted : destructive()
+ConstructiveReverted --> ConstructiveExecuted : constructive()
+DestructiveExecuted --> DestructiveReverted : revertDestructive()
+DestructiveReverted --> DestructiveExecuted : destructive()
+DestructiveReverted --> ConstructiveReverted : revertConstructive()
+```

src/Cascade/CascadeDeleteResolver.php

@@ -19,9 +19,9 @@
 use Access\Database;
 use Access\DeleteKind;
 use Access\Entity;
+use Access\Exception\NotSupportedException;
 use Access\Query;
-use Access\Statement;
-use Exception;
+use Access\Schema\Type;
 
 /**
  * Resolve the order of cascading delete operations
@@ -269,30 +269,36 @@ private function dependsOn(
 
     private function deleteFields(Entity $entity, DeleteKind $kind): void
     {
-        $fields = $entity::fields();
+        $fields = $entity::getTableSchema()->getFields();
         $values = $entity->getValues();
 
-        foreach ($fields as $fieldName => $relation) {
+        foreach ($fields as $field) {
+            $type = $field->getType();
+
+            // only fields marked as a reference
+            if (!$type instanceof Type\Reference) {
+                continue;
+            }
+
             // skip fields that are not set (or `null`)
-            if (!isset($values[$fieldName])) {
+            if (!isset($values[$field->getName()])) {
                 continue;
             }
 
-            /** @var Cascade|null $cascade */
-            $cascade = $relation['cascade'] ?? null;
+            $cascade = $type->getCascade();
 
             if ($cascade === null) {
                 continue;
             }
 
-            if (!isset($relation['target'])) {
-                continue;
-            }
+            $target = $type->getTarget();
 
-            $target = $relation['target'];
+            if (!is_string($target) || !is_subclass_of($target, Entity::class)) {
+                throw new NotSupportedException('Cascading delete only works for entity relations');
+            }
 
             if ($cascade->shouldCascadeDelete($kind, $target)) {
-                $r = $this->find($target, 'id', $values[$fieldName], $kind);
+                $r = $this->find($target, 'id', $values[$field->getName()], $kind);
 
                 $this->resolveRelation($r, $kind, $target, $cascade);
             }
@@ -371,8 +377,7 @@ private function delete(string $klass, array $ids): bool
             'id IN (?)' => $ids,
         ]);
 
-        $stmt = new Statement($this->db, $this->db->getProfiler(), $query);
-        $gen = $stmt->execute();
+        $gen = $this->db->executeStatement($query);
         $updated = $gen->getReturn() > 0;
 
         return $updated;
@@ -394,8 +399,7 @@ private function softDelete(string $klass, array $ids): bool
             'id IN (?)' => $ids,
         ]);
 
-        $stmt = new Statement($this->db, $this->db->getProfiler(), $query);
-        $gen = $stmt->execute();
+        $gen = $this->db->executeStatement($query);
         $updated = $gen->getReturn() > 0;
         return $updated;
     }

src/Clause/Condition/Raw.php

@@ -34,4 +34,12 @@ public function __construct(string $condition, mixed $value = null)
     {
         parent::__construct($condition, self::KIND_RAW, $value);
     }
+
+    /**
+     * Return the condition as string
+     */
+    public function getCondition(): string
+    {
+        return $this->getField()->getName();
+    }
 }

src/Clause/Filter/Filter.php

@@ -25,8 +25,6 @@ abstract class Filter implements FilterInterface
 {
     /**
      * Filter given collection in place based on this filter clause
-     *
-     * @param Collection $collection Collection to filter
      */
     public function filterCollection(Collection $collection): Collection
     {

src/Clause/Filter/FilterItemResult.php

@@ -0,0 +1,41 @@
+<?php
+
+/*
+ * This file is part of the Access package.
+ *
+ * (c) Tim <me@justim.net>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+declare(strict_types=1);
+
+namespace Access\Clause\Filter;
+
+/**
+ * Controls the flow of filtering a list of items
+ *
+ * `FilterItemResult::Done` indicates that no further items should be considered
+ *
+ * @author Tim <me@justim.net>
+ */
+enum FilterItemResult
+{
+    /**
+     * The item should be included
+     */
+    case Include;
+
+    /**
+     * The item should be excluded
+     */
+    case Exclude;
+
+    /**
+     * The filtering is done, no further items will be considered
+     *
+     * The current item will be excluded
+     */
+    case Done;
+}

src/Clause/Filter/Unique.php

@@ -34,7 +34,7 @@ public function __construct(string $fieldName)
      * Create the finder function for this filter clause
      *
      * @return callable
-     * @psalm-return callable(\Access\Entity): scalar
+     * @psalm-return callable(\Access\Entity): (FilterItemResult|bool)
      */
     public function createFilterFinder(): callable
     {

src/Clause/FilterInterface.php

@@ -13,6 +13,7 @@
 
 namespace Access\Clause;
 
+use Access\Clause\Filter\FilterItemResult;
 use Access\Collection;
 
 /**
@@ -25,15 +26,19 @@ interface FilterInterface extends ClauseInterface
     /**
      * Filter given collection in place based on this filter clause
      *
-     * @param Collection $collection Collection to filter
+     * @psalm-template TEntity of \Access\Entity
+     * @param Collection $collection The collection to filter
+     * @psalm-param Collection<TEntity> $collection The collection to filter
+     * @return Collection The filtered collection
+     * @psalm-return Collection<TEntity> The filtered collection
      */
     public function filterCollection(Collection $collection): Collection;
 
     /**
      * Create the finder function for this filter clause
      *
      * @return callable
-     * @psalm-return callable(\Access\Entity): scalar
+     * @psalm-return callable(\Access\Entity): (FilterItemResult|bool)
      */
     public function createFilterFinder(): callable;
 }

src/Clause/Limit.php

@@ -0,0 +1,107 @@
+<?php
+
+/*
+ * This file is part of the Access package.
+ *
+ * (c) Tim <me@justim.net>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+declare(strict_types=1);
+
+namespace Access\Clause;
+
+use Access\Collection;
+use Access\Query\QueryGeneratorState;
+
+/**
+ * Limit the number of entities
+ *
+ * @author Tim <me@justim.net>
+ */
+class Limit implements LimitInterface
+{
+    /**
+     * The limit of number of entities
+     */
+    private int $limit;
+
+    /**
+     * Starting offset
+     */
+    private ?int $offset = null;
+
+    public function __construct(int $limit, ?int $offset = null)
+    {
+        $this->limit = $limit;
+        $this->offset = $offset;
+    }
+
+    /**
+     * Get the current limit
+     */
+    public function getLimit(): int
+    {
+        return $this->limit;
+    }
+
+    /**
+     * Set a new limit
+     */
+    public function setLimit(int $limit): void
+    {
+        $this->limit = $limit;
+    }
+
+    /**
+     * Get the current offset
+     */
+    public function getOffset(): ?int
+    {
+        return $this->offset;
+    }
+
+    /**
+     * Set a new offset
+     */
+    public function setOffset(?int $offset): void
+    {
+        $this->offset = $offset;
+    }
+
+    /**
+     * {@inheritdoc}
+     */
+    public function limitCollection(?Collection $collection): void
+    {
+        if ($collection === null) {
+            return;
+        }
+
+        $collection->limit($this);
+    }
+
+    /**
+     * {@inheritdoc}
+     */
+    public function getConditionSql(QueryGeneratorState $state): string
+    {
+        $limitSql = " LIMIT {$this->limit}";
+
+        if ($this->offset !== null) {
+            $limitSql .= " OFFSET {$this->offset}";
+        }
+
+        return $limitSql;
+    }
+
+    /**
+     * {@inheritdoc}
+     */
+    public function injectConditionValues(QueryGeneratorState $state): void
+    {
+        // no values to inject
+    }
+}