chore: Initial idea for a lightweight data mapper

Author: ollieread

src/Concerns/UsesTransactions.php

@@ -0,0 +1,66 @@
+<?php
+declare(strict_types=1);
+
+namespace Articulate\Concise\Concerns;
+
+use Closure;
+
+/**
+ * @phpstan-require-extends \Articulate\Concise\Support\BaseRepository
+ *
+ * @mixin \Articulate\Concise\Support\BaseRepository
+ */
+trait UsesTransactions
+{
+    /**
+     * Executes a given callback within a database transaction.
+     *
+     * @template RetType of mixed
+     *
+     * @param Closure(\Illuminate\Database\Connection): RetType $callback The callback function to execute within the transaction.
+     *
+     * @return mixed The result of the callback function execution.
+     *
+     * @throws \Throwable
+     */
+    protected function inTransaction(Closure $callback): mixed
+    {
+        return $this->connection()->transaction($callback);
+    }
+
+    /**
+     * Initiates a database transaction.
+     *
+     * @return void
+     *
+     * @throws \Throwable
+     */
+    protected function beginTransaction(): void
+    {
+        $this->connection()->beginTransaction();
+    }
+
+    /**
+     * Finalizes a database transaction, committing all changes made during the transaction.
+     *
+     * @return void
+     *
+     * @throws \Throwable
+     */
+    protected function commitTransaction(): void
+    {
+        $this->connection()->commit();
+    }
+
+    /**
+     * Rolls back the current database transaction, reverting any changes made
+     * during the transaction.
+     *
+     * @return void
+     * @throws \Throwable
+     */
+    protected function rollBackTransaction(): void
+    {
+        $this->connection()->rollBack();
+    }
+}

src/Concise.php

@@ -0,0 +1,231 @@
+<?php
+declare(strict_types=1);
+
+namespace Articulate\Concise;
+
+use Articulate\Concise\Contracts\EntityMapper;
+use Articulate\Concise\Contracts\Repository;
+use Closure;
+use Illuminate\Contracts\Foundation\Application;
+use Illuminate\Database\DatabaseManager;
+use InvalidArgumentException;
+
+final class Concise
+{
+    /**
+     * The Laravel application
+     *
+     * @var \Illuminate\Contracts\Foundation\Application
+     */
+    private Application $app;
+
+    /**
+     * @var \Articulate\Concise\IdentityMap
+     */
+    private IdentityMap $identities;
+
+    /**
+     * Entity mappers mapped by the entity class.
+     *
+     * @var array<class-string, \Articulate\Concise\Contracts\EntityMapper<*>>
+     */
+    private array $entityMappers = [];
+
+    /**
+     * Component mappers mapped by the component class.
+     *
+     * @var array<class-string, \Articulate\Concise\Contracts\Mapper<*>>
+     */
+    private array $componentMappers = [];
+
+    /**
+     * @var array<class-string, \Articulate\Concise\Contracts\Repository<*>>
+     */
+    private array $repositories = [];
+
+    public function __construct(Application $app)
+    {
+        $this->app        = $app;
+        $this->identities = new IdentityMap();
+    }
+
+    /**
+     * Get all entity mappers
+     *
+     * @return array<class-string, \Articulate\Concise\Contracts\EntityMapper<*>>
+     */
+    public function getEntityMappers(): array
+    {
+        return $this->entityMappers;
+    }
+
+    /**
+     * Registers the provided Mapper instance.
+     *
+     * @template ObjType of object
+     *
+     * @param class-string<\Articulate\Concise\Contracts\Mapper<ObjType>> $mapperClass The mapper class to register.
+     *
+     * @return self Returns the current instance for method chaining.
+     *
+     * @throws \Illuminate\Contracts\Container\BindingResolutionException
+     */
+    public function register(string $mapperClass): self
+    {
+        $mapper = $this->app->make($mapperClass);
+
+        if ($mapper instanceof EntityMapper) {
+            $this->entityMappers[$mapper->getClass()] = $mapper;
+        } else {
+            $this->componentMappers[$mapper->getClass()] = $mapper;
+        }
+
+        return $this;
+    }
+
+    /**
+     * Creates an entity of the given class for the give data
+     *
+     * @template EntityType of object
+     *
+     * @param class-string<EntityType> $class The fully qualified class name of the entity.
+     * @param array<string, mixed>     $data  The data to create the entity from.
+     *
+     * @return object The created entity
+     *
+     * @phpstan-return EntityType
+     *
+     * @throws InvalidArgumentException If no entity mapper is registered for the provided class.
+     */
+    public function entity(string $class, array $data): object
+    {
+        /** @var \Articulate\Concise\Contracts\EntityMapper<EntityType>|null $mapper */
+        $mapper = $this->entityMappers[$class] ?? null;
+
+        if ($mapper === null) {
+            throw new InvalidArgumentException("No entity mapper registered for {$class}.");
+        }
+
+        return $this->identified($mapper, $data);
+    }
+
+    /**
+     * Resolve and retrieve an identified entity
+     *
+     * @template EntityType of object
+     *
+     * @param \Articulate\Concise\Contracts\EntityMapper<EntityType> $mapper
+     * @param array<string, mixed>                                   $data
+     *
+     * @return object
+     *
+     * @phpstan-return EntityType
+     */
+    public function identified(EntityMapper $mapper, array $data): object
+    {
+        // Get the identity from the data
+        $identity = $mapper->identity($data);
+
+        // Retrieve an existing entity if one does exist
+        $existing = $this->identities->get($mapper->getClass(), $identity);
+
+        // If it does exist, return it instead
+        if ($existing !== null) {
+            return $existing;
+        }
+
+        // If it doesn't exist, create a new entity from the data
+        $entity = $mapper->toObject($data);
+
+        // And then map its identity
+        $this->identities->add($entity, $identity, $mapper->getClass());
+
+        return $entity;
+    }
+
+    /**
+     * Create a component of the given class for the given data.
+     *
+     * @template ComponentType of object
+     *
+     * @param class-string<ComponentType> $class The fully qualified class name of the component.
+     * @param array<string, mixed>        $data  The data to create the component from.
+     *
+     * @return object The created component
+     *
+     * @phpstan-return ComponentType
+     *
+     * @throws InvalidArgumentException If no component mapper is registered for the provided class.
+     */
+    public function component(string $class, array $data): object
+    {
+        /** @var \Articulate\Concise\Contracts\Mapper<ComponentType>|null $mapper */
+        $mapper = $this->componentMappers[$class] ?? null;
+
+        if ($mapper === null) {
+            throw new InvalidArgumentException("No component mapper registered for {$class}.");
+        }
+
+        // Components don't have "identities", so we can return this
+
+        return $mapper->toObject($data);
+    }
+
+    /**
+     * Get the data representation for the given object.
+     *
+     * @template ObjType of object
+     *
+     * @param object          $object The object to convert into a data array
+     *
+     * @phpstan-param ObjType $object
+     *
+     * @return array<string, mixed> The data
+     */
+    public function data(object $object): array
+    {
+        /** @var \Articulate\Concise\Contracts\Mapper<ObjType>|null $mapper */
+        $mapper = $this->entityMappers[$object::class] ?? $this->componentMappers[$object::class] ?? null;
+
+        if ($mapper === null) {
+            throw new InvalidArgumentException('No mapper registered for ' . $object::class . '.');
+        }
+
+        return $mapper->toData($object);
+    }
+
+    /**
+     * Get a repository instance for the given entity class.
+     *
+     * @template EntityType of object
+     *
+     * @param class-string<EntityType> $class
+     *
+     * @return \Articulate\Concise\Contracts\Repository<EntityType>
+     *
+     * @throws \Illuminate\Contracts\Container\BindingResolutionException
+     */
+    public function repository(string $class): Repository
+    {
+        $mapper = $this->entityMappers[$class] ?? null;
+
+        if ($mapper === null) {
+            throw new InvalidArgumentException('No mapper registered for ' . $class . '.');
+        }
+
+        $repository = $this->repositories[$class] ?? null;
+
+        if ($repository !== null) {
+            return $repository;
+            /** @phpstan-ignore return.type */
+        }
+
+        $repositoryClass = $mapper->repository();
+
+        return $this->repositories[$class] = new $repositoryClass(
+            $this,
+            $mapper,
+            $this->app->make(DatabaseManager::class)->connection($mapper->connection())
+        );
+    }
+}

src/ConciseServiceProvider.php

@@ -7,5 +7,25 @@
 
 class ConciseServiceProvider extends ServiceProvider
 {
+    public function register(): void
+    {
+        // Register the Concise class
+        $this->app->singleton(Concise::class, function () {
+            return new Concise($this->app);
+        });
 
+        // Register the mappers' repositories
+        $this->booted($this->registerRepositories(...));
+    }
+
+    protected function registerRepositories(Concise $concise): void
+    {
+        foreach ($concise->getEntityMappers() as $mapper) {
+            $repo = $mapper->repository();
+
+            if ($repo !== null) {
+                $this->app->bind($repo, fn () => $concise->repository($mapper->getClass()));
+            }
+        }
+    }
 }

src/Contracts/EntityMapper.php

@@ -0,0 +1,40 @@
+<?php
+
+namespace Articulate\Concise\Contracts;
+
+/**
+ * EntityMapper
+ *
+ * Defines an interface for mapping entities.
+ *
+ * @template EntityType of object
+ *
+ * @extends \Articulate\Concise\Contracts\Mapper<EntityType>
+ */
+interface EntityMapper extends Mapper
+{
+    /**
+     * Get the connection name the entity uses.
+     *
+     * @return string|null The connection name or null to use the default.
+     */
+    public function connection(): ?string;
+
+    /**
+     * Get the repository class name.
+     *
+     * @return class-string<\Articulate\Concise\Contracts\Repository<EntityType>>|null
+     */
+    public function repository(): ?string;
+
+    /**
+     * Get the identity from the provided data.
+     *
+     * @param array<string, mixed>|object             $data
+     *
+     * @phpstan-param array<string, mixed>|EntityType $data
+     *
+     * @return int|string
+     */
+    public function identity(array|object $data): int|string;
+}