chore: PHPStan fixes

Author: ollieread

README.md

@@ -1,4 +1,4 @@
-<img src="articulate.png">
+<img src="articulate.png" width="100%">
 
 ![Packagist Version](https://img.shields.io/packagist/v/articulate/concise)
 ![Packagist PHP Version Support](https://img.shields.io/packagist/php-v/articulate/concise)
@@ -11,7 +11,11 @@
 ![Static Analysis](https://github.com/articulate-laravel/concise/actions/workflows/static-analysis.yml/badge.svg)
 
 # Articulate: Concise
-### A super lightweight data mapper ORM for Laravel
+Articulate: Concise is a super lightweight data mapper ORM for Laravel.
+It exists as a package entirely because I wondered how lightweight of a solution I can build, that gives me the 
+benefit of a data mapper ORM, without using a full ORM.
 
-This package is currently under development.
-Check back in the future for updates.
+Concise is extensible and flexible, and will most likely serve as the basis for Articulate in the future, but it comes
+with many sensible defaults, and a sprinkle of magic that'll simplify using it based on certain conventions.
+It also comes with a driver for Laravel's auth functionality,
+and route entity binding (route model binding but for concise entities).

src/Concerns/SupportsAuth.php

@@ -90,12 +90,12 @@ public function findByCredentials(#[SensitiveParameter] array $credentials): ?ob
     {
         $credentials = array_filter(
             $credentials,
-            fn ($key) => ! str_contains($key, 'password'),
+            static fn ($key) => ! str_contains($key, 'password'),
             ARRAY_FILTER_USE_KEY
         );
 
         if (empty($credentials)) {
-            return;
+            return null;
         }
 
         // First we will add each credential element to the query as a where clause.

src/Concise.php

@@ -142,6 +142,10 @@ public function identified(EntityMapper $mapper, array $data): object
         // Get the identity from the data
         $identity = $mapper->identity($data);
 
+        if ($identity === null) {
+            throw new InvalidArgumentException('No identity could be found in the provided data.');
+        }
+
         // Retrieve an existing entity if one does exist
         $existing = $this->identities->get($mapper->class(), $identity);
 
@@ -237,14 +241,7 @@ public function repository(string $class): Repository
         }
 
         $repositoryClass = $mapper->repository();
-
-        /**
-         * This has to be here because Application::make() expects a 'string',
-         * not a 'class-string', which is...well, yeah, you know exactly what it
-         * is.
-         *
-         * @phpstan-ignore argument.type
-         */
+        
         return $this->repositories[$class] = new $repositoryClass(
             concise   : $this,
             mapper    : $mapper,

src/Contracts/AuthRepository.php

@@ -47,7 +47,7 @@ public function findByRememberToken(#[SensitiveParameter] string $token): ?objec
     /**
      * Find an identity by its credentials
      *
-     * @param array $credentials
+     * @param array<string, mixed> $credentials
      *
      * @return object|null
      *

src/Contracts/EntityMapper.php

@@ -42,6 +42,8 @@ public function table(): string;
      * @phpstan-param array<string, mixed>|EntityType $data
      *
      * @return int|string|null
+     *
+     * @TODO Think about a better way to handle this
      */
     public function identity(array|object $data): int|string|null;
 }

src/Contracts/Identity.php

@@ -0,0 +1,10 @@
+<?php
+
+namespace Articulate\Concise\Contracts;
+
+use Stringable;
+
+interface Identity extends Stringable
+{
+    public function toKey(): string|int;
+}

src/Support/BaseEntityMapper.php

@@ -64,6 +64,8 @@ public function table(): string
      * @phpstan-param array<string, mixed>|EntityType $data
      *
      * @return int|string|null
+     *
+     * @TODO: Think about a better implementation for this
      */
     public function identity(object|array $data): int|string|null
     {

src/Support/DiscoverMappers.php

@@ -0,0 +1,93 @@
+<?php
+declare(strict_types=1);
+
+namespace Articulate\Concise\Support;
+
+use Articulate\Concise\Contracts\Mapper;
+use Illuminate\Support\Str;
+use ReflectionClass;
+use ReflectionException;
+use SplFileInfo;
+use Symfony\Component\Finder\Finder;
+
+class DiscoverMappers
+{
+    /**
+     * The callback to be used to guess class names.
+     *
+     * @var callable(SplFileInfo, string): class-string|null
+     */
+    public static $guessClassNamesUsingCallback;
+
+    /**
+     * Get all the mappers by searching the given mapper directory.
+     *
+     * @param string $mapperPath
+     * @param string $basePath
+     *
+     * @return array<class-string<\Articulate\Concise\Contracts\EntityMapper<*>>>
+     */
+    public static function within(string $mapperPath, string $basePath): array
+    {
+        $possibleMappers = Finder::create()->files()->in($mapperPath);
+        $foundMappers    = [];
+
+        foreach ($possibleMappers as $possibleMapper) {
+            try {
+                $reflection = new ReflectionClass(
+                    static::classFromFile($possibleMapper, $basePath)
+                );
+            } catch (ReflectionException) {
+                continue;
+            }
+
+            if (! $reflection->isInstantiable()) {
+                continue;
+            }
+
+            if ($reflection->implementsInterface(Mapper::class)) {
+                $foundMappers[] = $reflection->name;
+            }
+        }
+
+        /** @var array<class-string<\Articulate\Concise\Contracts\EntityMapper<*>>> $foundMappers */
+
+        return $foundMappers;
+    }
+
+    /**
+     * Extract the class name from the given file path.
+     *
+     * @param \SplFileInfo $file
+     * @param string       $basePath
+     *
+     * @return class-string
+     */
+    protected static function classFromFile(SplFileInfo $file, string $basePath): string
+    {
+        if (static::$guessClassNamesUsingCallback) {
+            return call_user_func(static::$guessClassNamesUsingCallback, $file, $basePath);
+        }
+
+        $class = trim(Str::replaceFirst($basePath, '', $file->getRealPath()), DIRECTORY_SEPARATOR);
+
+        /** @phpstan-ignore return.type */
+        return ucfirst(Str::camel(str_replace(
+            [DIRECTORY_SEPARATOR, ucfirst(basename(app()->path())) . '\\'],
+            ['\\', app()->getNamespace()],
+            ucfirst(Str::replaceLast('.php', '', $class))
+        )));
+    }
+
+    /**
+     * Specify a callback to be used to guess class names.
+     *
+     * @param callable(SplFileInfo, string): class-string $callback
+     *
+     * @return void
+     */
+    public static function guessClassNamesUsing(callable $callback): void
+    {
+        static::$guessClassNamesUsingCallback = $callback;
+    }
+}

src/Support/MapperServiceProvider.php

@@ -4,21 +4,155 @@
 namespace Articulate\Concise\Support;
 
 use Articulate\Concise\Concise;
+use Illuminate\Support\Arr;
+use Illuminate\Support\Collection;
 use Illuminate\Support\ServiceProvider;
 
-abstract class MapperServiceProvider extends ServiceProvider
+class MapperServiceProvider extends ServiceProvider
 {
     /**
      * @var array<class-string, class-string<\Articulate\Concise\Contracts\EntityMapper<*>>>
      */
     protected array $mappers = [];
 
+    /**
+     * Indicates if mappers should be discovered.
+     *
+     * @var bool
+     */
+    protected static bool $shouldDiscoverMappers = true;
+
+    /**
+     * The configured mapper discovery paths.
+     *
+     * @var array<string>
+     */
+    protected static array $mapperDiscoveryPaths = [];
+
     public function register(): void
     {
         $this->app->afterResolving(Concise::class, function (Concise $concise) {
-            foreach ($this->mappers as $mapper) {
+            $mappers = $this->getMappers();
+
+            foreach ($mappers as $mapper) {
+                /** @phpstan-ignore argument.type */
                 $concise->register($mapper);
             }
         });
     }
+
+    /**
+     * @return array<class-string<\Articulate\Concise\Contracts\Mapper<*>>>
+     */
+    private function getMappers(): array
+    {
+        return array_merge(
+            $this->discoveredMappers(),
+            $this->mappers
+        );
+    }
+
+    /**
+     * Get the discovered mappers for the application.
+     *
+     * @return array<class-string<\Articulate\Concise\Contracts\Mapper<*>>>
+     */
+    protected function discoveredMappers(): array
+    {
+        return $this->shouldDiscoverMappers()
+            ? $this->discoverMappers()
+            : [];
+    }
+
+    /**
+     * Determine if mappers should be automatically discovered.
+     *
+     * @return bool
+     */
+    public function shouldDiscoverMappers(): bool
+    {
+        return get_class($this) === __CLASS__ && static::$shouldDiscoverMappers === true;
+    }
+
+    /**
+     * Discover the mappers for the application.
+     *
+     * @return array<class-string<\Articulate\Concise\Contracts\Mapper<*>>>
+     */
+    public function discoverMappers(): array
+    {
+        return (new Collection($this->discoverMappersWithin()))
+            /** @phpstan-ignore argument.type */
+            ->flatMap(function (string $directory) {
+                return glob($directory, GLOB_ONLYDIR);
+            })
+            ->reject(function (string $directory) {
+                return ! is_dir($directory);
+            })
+            ->reduce(function ($discovered, $directory) {
+                return array_merge_recursive(
+                    $discovered,
+                    DiscoverMappers::within($directory, $this->mapperDiscoveryBasePath())
+                );
+            }, []);
+    }
+
+    /**
+     * Get the directories that should be used to discover mappers.
+     *
+     * @return array<string>
+     */
+    protected function discoverMappersWithin(): array
+    {
+        return static::$mapperDiscoveryPaths ?? [
+            $this->app->path('Mappers\Components'),
+            $this->app->path('Mappers\Entities'),
+        ];
+    }
+
+    /**
+     * Add the given mapper discovery paths to the application's mapper discovery paths.
+     *
+     * @param string|array<string> $paths
+     *
+     * @return void
+     */
+    public static function addMapperDiscoveryPaths(array|string $paths): void
+    {
+        static::$mapperDiscoveryPaths = array_values(array_unique(
+            array_merge(static::$mapperDiscoveryPaths, Arr::wrap($paths))
+        ));
+    }
+
+    /**
+     * Set the globally configured mapper discovery paths.
+     *
+     * @param array<string> $paths
+     *
+     * @return void
+     */
+    public static function setMapperDiscoveryPaths(array $paths): void
+    {
+        static::$mapperDiscoveryPaths = $paths;
+    }
+
+    /**
+     * Get the base path to be used during mapper discovery.
+     *
+     * @return string
+     */
+    protected function mapperDiscoveryBasePath(): string
+    {
+        return base_path();
+    }
+
+    /**
+     * Disable mapper discovery for the application.
+     *
+     * @return void
+     */
+    public static function disableMapperDiscovery(): void
+    {
+        static::$shouldDiscoverMappers = false;
+    }
 }