chore: Add partial base implementation

Author: ollieread

src/Concise.php

@@ -0,0 +1,115 @@
+<?php
+declare(strict_types=1);
+
+namespace Articulate\Concise;
+
+use Articulate\Concise\Contracts\EntityMapper;
+use Articulate\Concise\Contracts\Mapper;
+use Articulate\Concise\Contracts\Repository;
+use Illuminate\Foundation\Application;
+
+final class Concise
+{
+    /**
+     * @var \Illuminate\Foundation\Application
+     */
+    private Application $app;
+
+    /**
+     * @var array<class-string, \Articulate\Concise\Contracts\EntityMapper<*>>
+     */
+    private array $entityMappers = [];
+
+    /**
+     * @var array<class-string, \Articulate\Concise\Contracts\Mapper<*>>
+     */
+    private array $componentMappers = [];
+
+    public function __construct(Application $app)
+    {
+        $this->app = $app;
+    }
+
+    /**
+     * Register a class mapper.
+     *
+     * @template MapperObject of object
+     *
+     * @param \Articulate\Concise\Contracts\Mapper<MapperObject> $mapper
+     * @param bool                                               $overwrite
+     *
+     * @return bool
+     */
+    public function register(Mapper $mapper, bool $overwrite = false): bool
+    {
+        if ($mapper instanceof EntityMapper) {
+            if ($overwrite === false && isset($this->entityMappers[$mapper->class()])) {
+                return false;
+            }
+
+            $this->entityMappers[$mapper->class()] = $mapper;
+
+            return true;
+        }
+
+        if ($overwrite === false && isset($this->componentMappers[$mapper->class()])) {
+            return false;
+        }
+
+        $this->componentMappers[$mapper->class()] = $mapper;
+
+        return true;
+    }
+
+    /**
+     * Get a registered entity mapper for the provided class.
+     *
+     * @template EntityObject of object
+     *
+     * @param class-string<EntityObject> $class
+     *
+     * @return \Articulate\Concise\Contracts\EntityMapper<EntityObject>|null
+     */
+    public function entity(string $class): ?EntityMapper
+    {
+        /** @var \Articulate\Concise\Contracts\EntityMapper<EntityObject>|null $mapper */
+        $mapper = $this->entityMappers[$class] ?? null;
+
+        return $mapper;
+    }
+
+    /**
+     * Get an entity repository for the provided class.
+     *
+     * @template EntityObject of object
+     *
+     * @param class-string<EntityObject> $class
+     *
+     * @return \Articulate\Concise\Contracts\Repository<EntityObject>|null
+     *
+     * @throws \Illuminate\Contracts\Container\BindingResolutionException
+     */
+    public function repository(string $class): ?Repository
+    {
+        /** @var \Articulate\Concise\Contracts\EntityMapper<EntityObject>|null $mapper */
+        $mapper = $this->entity($class);
+
+        if ($mapper === null) {
+            return null;
+        }
+
+        $repository = $mapper->repository();
+
+        if ($repository === null) {
+            return new EntityRepository(
+                $mapper,
+                $this->app->make('db')->connection($mapper->connection()),
+            );
+        }
+
+        return $this->app->make($repository, [
+            'mapper'     => $mapper,
+            'connection' => $this->app->make('db')->connection($mapper->connection()),
+        ]);
+    }
+}

src/ConciseServiceProvider.php

@@ -3,12 +3,20 @@
 
 namespace Articulate\Concise;
 
+use Articulate\Concise\Support\ImplicitBindingSubstitution;
+use Illuminate\Routing\Router;
 use Illuminate\Support\ServiceProvider;
 
 class ConciseServiceProvider extends ServiceProvider
 {
     public function register(): void
     {
+        // Bind the main concise class
+        $this->app->singleton(Concise::class);
 
+        // Add our custom implicit binding substitution
+        $this->app->afterResolving(Router::class, function (Router $router) {
+            $router->substituteImplicitBindingsUsing($this->app->make(ImplicitBindingSubstitution::class));
+        });
     }
 }

src/Contracts/Criteria.php

@@ -0,0 +1,21 @@
+<?php
+
+namespace Articulate\Concise\Contracts;
+
+use Articulate\Concise\Query\Builder;
+
+/**
+ *
+ */
+interface Criteria
+{
+    /**
+     * @template EntityObject of object
+     *
+     * @param \Articulate\Concise\Query\Builder<EntityObject>          $query
+     * @param \Articulate\Concise\Contracts\EntityMapper<EntityObject> $mapper
+     *
+     * @return void
+     */
+    public function apply(Builder $query, EntityMapper $mapper): void;
+}

src/Contracts/EntityMapper.php

@@ -0,0 +1,45 @@
+<?php
+
+namespace Articulate\Concise\Contracts;
+
+/**
+ * Entity Mapper
+ *
+ * Entity mappers are more specific implementations of
+ * {@see \Articulate\Concise\Contracts\Mapper} that deal with entities stored in
+ * the database.
+ *
+ * @template EntityObject of object
+ *
+ * @extends  \Articulate\Concise\Contracts\Mapper<EntityObject>
+ */
+interface EntityMapper extends Mapper
+{
+    /**
+     * Get the custom repository class for the entity
+     *
+     * @return class-string<\Articulate\Concise\Contracts\Repository<EntityObject>>|null
+     */
+    public function repository(): ?string;
+
+    /**
+     * Get the connection the entity should use
+     *
+     * @return string|null
+     */
+    public function connection(): ?string;
+
+    /**
+     * Get the entities' database table
+     *
+     * @return string
+     */
+    public function table(): string;
+
+    /**
+     * Get the name of the identity field
+     *
+     * @return string
+     */
+    public function identity(): string;
+}

src/Contracts/Mapper.php

@@ -0,0 +1,45 @@
+<?php
+
+namespace Articulate\Concise\Contracts;
+
+/**
+ * Mapper
+ *
+ * Mappers are responsible for mapping between raw data and object representations.
+ *
+ * @template MapObject of object
+ */
+interface Mapper
+{
+    /**
+     * Get the class name this mapper represents.
+     *
+     * Returns the fully qualified class name of the object that this mapper is
+     * mapping.
+     *
+     * @return class-string<MapObject>
+     */
+    public function class(): string;
+
+    /**
+     * Convert a raw array to an object representation.
+     *
+     * @param array<string, mixed> $data
+     *
+     * @return object
+     *
+     * @phpstan-return MapObject
+     */
+    public function toObject(array $data): object;
+
+    /**
+     * Convert an object representation to raw data.
+     *
+     * @param object            $object
+     *
+     * @phpstan-param MapObject $object
+     *
+     * @return array<string, mixed>
+     */
+    public function toData(object $object): array;
+}

src/Contracts/Repository.php

@@ -0,0 +1,41 @@
+<?php
+
+namespace Articulate\Concise\Contracts;
+
+use Illuminate\Contracts\Pagination\Paginator;
+use Illuminate\Support\Collection;
+
+/**
+ * @template EntityObject of object
+ */
+interface Repository
+{
+    /**
+     * Get one record for the provided criteria.
+     *
+     * @param \Articulate\Concise\Contracts\Criteria ...$criteria
+     *
+     * @return object|null
+     *
+     * @phpstan-return EntityObject|null
+     */
+    public function getOne(Criteria ...$criteria): ?object;
+
+    /**
+     * Get many records for the provided criteria.
+     *
+     * @param \Articulate\Concise\Contracts\Criteria ...$criteria
+     *
+     * @return \Illuminate\Support\Collection<array-key, EntityObject>
+     */
+    public function getMany(Criteria ...$criteria): Collection;
+
+    /**
+     * Get a paginated collection of records for the provided criteria.
+     *
+     * @param \Articulate\Concise\Contracts\Criteria ...$criteria
+     *
+     * @return \Illuminate\Contracts\Pagination\Paginator<EntityObject>
+     */
+    public function getPaginated(Criteria ...$criteria): Paginator;
+}

src/Contracts/RoutableRepository.php

@@ -0,0 +1,21 @@
+<?php
+
+namespace Articulate\Concise\Contracts;
+
+/**
+ * @template EntityObject of object
+ *
+ * @requires \Articulate\Concise\Contracts\Repository<EntityObject>
+ */
+interface RoutableRepository
+{
+    /**
+     * @param string      $value
+     * @param string|null $binding
+     *
+     * @return object|null
+     *
+     * @phpstan-return EntityObject|null
+     */
+    public function getOneForRouting(string $value, ?string $binding = null): ?object;
+}

src/Criteria/ForIdentifier.php

@@ -0,0 +1,35 @@
+<?php
+declare(strict_types=1);
+
+namespace Articulate\Concise\Criteria;
+
+use Articulate\Concise\Contracts\Criteria;
+use Articulate\Concise\Contracts\EntityMapper;
+use Articulate\Concise\Query\Builder;
+
+final readonly class ForIdentifier implements Criteria
+{
+    private string|int $identifier;
+
+    public function __construct(string|int $identifier)
+    {
+        $this->identifier = $identifier;
+    }
+
+    /**
+     * @template EntityObject of object
+     *
+     * @param \Articulate\Concise\Query\Builder<EntityObject>          $query
+     * @param \Articulate\Concise\Contracts\EntityMapper<EntityObject> $mapper
+     *
+     * @return void
+     */
+    public function apply(Builder $query, EntityMapper $mapper): void
+    {
+        $query->where(
+            $query->qualifyColumn($mapper->identity()),
+            '=',
+            $this->identifier
+        );
+    }
+}

src/Criteria/WhereColumn.php

@@ -0,0 +1,37 @@
+<?php
+declare(strict_types=1);
+
+namespace Articulate\Concise\Criteria;
+
+use Articulate\Concise\Contracts\Criteria;
+use Articulate\Concise\Contracts\EntityMapper;
+use Articulate\Concise\Query\Builder;
+
+final class WhereColumn implements Criteria
+{
+    private string $column;
+
+    private string $operator;
+
+    private mixed  $value;
+
+    public function __construct(string $column, string $operator, mixed $value)
+    {
+        $this->column   = $column;
+        $this->operator = $operator;
+        $this->value    = $value;
+    }
+
+    /**
+     * @template EntityObject of object
+     *
+     * @param \Articulate\Concise\Query\Builder<EntityObject>          $query
+     * @param \Articulate\Concise\Contracts\EntityMapper<EntityObject> $mapper
+     *
+     * @return void
+     */
+    public function apply(Builder $query, EntityMapper $mapper): void
+    {
+        $query->where($this->column, $this->operator, $this->value);
+    }
+}