[BSS-14] New Client Mechanism: Solution A vs Solution B

[shahmal1yev]

In this discussion, I will present two different solutions for the client mechanism. Each solution has its own advantages, requirements, and potential disadvantages. I look forward to your comments and feedback.

---

Solution A: Dynamic Finder and Class Loading

---

Requirements:

• Symfony\Component\Finder library

Description:
In this solution, Finder is used to dynamically locate classes in the file system, and they are automatically loaded based on the namespace structure. Paths are determined based on folder structure, and class names are resolved dynamically. When any method is called, the corresponding class is found, and necessary operations are performed.

Advantages:

• Completely dynamic solution based on folder structure.
• Automatic class finding reduces manual workload.

Disadvantages:

• Performance cost, especially in large projects.
• Debugging can be challenging if classes are not found or loaded incorrectly.
• IDE support and static analysis may be weak, making it difficult to catch errors in advance.

Code Example:

<?php

namespace Atproto;

use Atproto\Helpers\Arr;
use Symfony\Component\Finder\Finder;
use Symfony\Component\Finder\SplFileInfo;

class Client
{
    /**
     * @var array
     */
    protected array $paths = [];

    /**
     * Client constructor initializes paths by scanning the API directory.
     */
    public function __construct()
    {
        $this->initializePaths();
    }

    /**
     * Scans the API directory and populates the $paths array.
     */
    protected function initializePaths(): void
    {
        $finder = new Finder();

        try {
            foreach ($finder->files()->in(__DIR__ . "/API") as $file) { // "src/API"
                $this->processFile($file);
            }
        } catch (\Exception $e) {
            // Handle the exception (e.g., log the error)
            throw new \RuntimeException("Error scanning API directory: " . $e->getMessage());
        }
    }

    /**
     * Processes an individual file to extract and store its namespace and class information.
     *
     * @param SplFileInfo $file
     */
    protected function processFile($file): void
    {
        $relativePath = $file->getRelativePathname();
        $namespace = $this->extractNamespace($relativePath);
        $class = $this->extractClassName($relativePath);
        $path = $this->generatePath($relativePath);
        $fullNamespace = "$namespace\\$class";

        $this->updatePaths($path, $fullNamespace, lcfirst($class));
    }

    /**
     * Extracts the namespace from the file's relative path.
     *
     * @param string $relativePath
     * @return string
     */
    protected function extractNamespace(string $relativePath): string
    {
        $pieces = explode("/", $relativePath);
        return implode("\\", array_slice($pieces, 0, -1));
    }

    /**
     * Extracts the class name from the file's relative path.
     *
     * @param string $relativePath
     * @return string
     */
    protected function extractClassName(string $relativePath): string
    {
        $pieces = explode("/", $relativePath);
        return str_replace(".php", "", array_pop($pieces));
    }

    /**
     * Generates the path from the file's relative path.
     *
     * @param string $relativePath
     * @return string
     */
    protected function generatePath(string $relativePath): string
    {
        $pieces = explode("/", $relativePath);
        $lowerPieces = array_map('strtolower', array_slice($pieces, 0, -1));
        return implode(".", $lowerPieces);
    }

    /**
     * Updates the $paths array with the new class and namespace information.
     *
     * @param string $path
     * @param string $fullNamespace
     * @param string $className
     */
    protected function updatePaths(string $path, string $fullNamespace, string $className): void
    {
        $arr = [$className => $fullNamespace];

        if ($current = Arr::get($this->paths, $path)) {
            $arr = array_merge($arr, $current);
        }

        Arr::set($this->paths, $path, $arr);
    }

    /**
     * Handles dynamic method calls to instantiate and return the appropriate class.
     *
     * @param string $name
     * @param array $arguments
     * @return mixed
     */
    public function __call(string $name, array $arguments)
    {
        $called = array_column(debug_backtrace(), 'function');
        $path = implode(".", $called);

        if (is_array($request = Arr::get($this->paths, $path))) {
            return $this;
        }

        if (class_exists($request)) {
            return new $request(...$arguments);
        }

        throw new \BadMethodCallException("Class for path '$path' not found.");
    }
}

/var/www/blueskysdk (main) » ls -R src/API
src/API:
App  Com

src/API/App:
Bsky

src/API/App/Bsky:
Actor

src/API/App/Bsky/Actor:
GetProfile.php

src/API/Com:
Atrproto

src/API/Com/Atrproto:
Repo

src/API/Com/Atrproto/Repo:
CreateRecord.php  UploadBlob.php

// After constructing, the "paths" property of the Client object is equal to the following array:

array (
  'com' => 
  array (
    'atrproto' => 
    array (
      'repo' => 
      array (
        'createRecord' => 'Com\\Atrproto\\Repo\\CreateRecord',
        'uploadBlob' => 'Com\\Atrproto\\Repo\\UploadBlob',
      ),
    ),
  ),
  'app' => 
  array (
    'bsky' => 
    array (
      'actor' => 
      array (
        'getProfile' => 'App\\Bsky\\Actor\\GetProfile',
      ),
    ),
  ),
)

---

Solution B: Composer Autoload and Request Handler

---

Requirements:

• Composer autoloading (PSR-4 standard)
• Dependency Injection Container (optional)
• Fixed route structure (manual or from configuration file)

Description:
In this solution, instead of dynamic file search, Composer's PSR-4 autoloading mechanism is used to find classes. Classes are automatically loaded, and requests are routed using a RequestHandler structure. Route definitions can be moved to a configuration file, and class dependencies are managed automatically with a Dependency Injection Container.

Advantages:

• More efficient in terms of performance.
• Excellent IDE and static analysis support; easier code error detection.
• Automatic class loading with Composer autoloading.
• More modular and testable structure using Dependency Injection.

Disadvantages:

• Less flexible for dynamic configuration needs.
• Route definitions must be done manually.

Code Example:

<?php

namespace Atproto;

class Client
{
    protected array $routes = [];

    public function __construct()
    {
        $this->registerRoutes();
    }

    protected function registerRoutes(): void
    {
        $this->routes = [
            'app.bsky.actor.getProfile' => \Atproto\API\App\Bsky\Actor\GetProfile::class,
            // Other route definitions
        ];
    }

    public function handle(string $route, array $arguments = [])
    {
        if ($request = Arr::get($this->routes, $route, null)) {
            return new $request(...$arguments);
        }
        
        throw new \Exception("Route not found");
    }
}

---

Comparison Table:

Feature	Solution A	Solution B
Performance	Lower (dynamic file finding)	Higher (autoloading)
Flexibility	High (dynamic file structure)	Lower (manual route definitions)
IDE and Static Analysis Support	Weak	Strong
Management	Requires extensive dynamic file structure	More stable and manageable
Dependency Management	Manual management	Automated with DI Container
Error Management	Difficult to detect errors	Easier early error detection

Conclusion:

• Solution A may be preferred for a more dynamic structrure but can be weaker in performance and error management.
• Solution B offers a more manageable and performance-friendly solution for larger and a more stable structure.

I look forward to discussing which solution might be more suitable for the project and hearing your suggestions for further improving both approaches!

[shahmal1yev]

Solution C

Code Example

<?php

namespace Atproto;

use Atproto\Contracts\HTTP\RequestContract;
use Exception;

class Client
{
    protected array $path = [];

    public function __call(string $name, array $arguments): Client
    {
        $this->path[] = $name;

        return $this;
    }

    protected function refresh(): void
    {
        $this->path = [];
    }

    /**
     * @throws Exception
     */
    public function build(): RequestContract
    {
        $namespace = $this->namespace();

        if (! class_exists($namespace)) {
            throw new Exception("$namespace class does not exist.");
        }

        return new $namespace;
    }

    protected function namespace(): string
    {
        $prefix = 'Atproto\\API\\';
        $namespace = "$prefix" . implode('\\', array_map(
        'ucfirst',
            $this->path
        ));

        $this->refresh();

        return $namespace;
    }
}

Unit Tests

<?php

namespace Tests\Unit\Atproto;

use Atproto\API\App\Bsky\Actor\GetProfile;
use Atproto\API\Com\Atrproto\Repo\CreateRecord;
use Atproto\Client;
use Atproto\Contracts\HTTP\RequestContract;
use Exception;
use PHPUnit\Framework\TestCase;
use ReflectionClass;

class ClientTest extends TestCase
{
    protected Client $client;

    protected function setUp(): void
    {
        parent::setUp();
        $this->client = new Client();
    }

    public function testClientIsInstanceOfClient(): void
    {
        $this->assertInstanceOf(Client::class, $this->client);
    }

    public function testCallReturnsSameInterface(): void
    {
        $this->assertInstanceOf(
            Client::class,
            $this->client
                ->app()
                ->bsky()
                ->actor()
        );
    }

    public function testCallSavesPathToProperty(): void
    {
        $path = [
            'app',
            'bsky',
            'actor',
        ];

        foreach($path as $piece) {
            $this->client->$piece();
        }

        $expected = $path;
        $actual = $this->pathValue();

        $this->assertEquals($expected, $actual);
    }

    /**
     * @param  array  $pieces
     * @return RequestContract
     * @throws Exception
     */
    public function instanceOfRequestContract(array $pieces): \Atproto\Contracts\HTTP\RequestContract
    {
        foreach($pieces as $piece) {
            $this->client->$piece();
        }

        return $this->client->build();
    }

    /**
     * @throws Exception
     */
    public function testBuildReturnsCorrectInstanceOfRequestContract(): void
    {
        $pieces = ['app', 'bsky', 'actor', 'getProfile'];

        $actual = $this->instanceOfRequestContract($pieces);

        $this->assertInstanceOf(GetProfile::class, $actual);
    }

    public function testBuildThrowsExceptionWhenClassDoesNotExist(): void
    {
        $pieces = [
            'invalid',
            'request',
            'class',
            'path'
        ];

        $namespace = "Atproto\\API\\" . implode("\\", array_map('ucfirst', $pieces));

        $this->expectException(Exception::class);
        $this->expectExceptionMessage("$namespace class does not exist.");

        $this->instanceOfRequestContract($pieces);
    }

    /**
     * @throws Exception
     */
    public function testBuildRefreshesPathPropertyWhenRequestBuilt(): void
    {
        $getProfilePieces = ['app', 'bsky', 'actor', 'getProfile'];
        $createRecordPieces = ['com', 'atrproto', 'repo', 'createRecord'];

        $getProfile = $this->instanceOfRequestContract($getProfilePieces);
        $createRecord = $this->instanceOfRequestContract($createRecordPieces);

        $requests = [
            GetProfile::class => $getProfile,
            CreateRecord::class => $createRecord,
        ];

        foreach($requests as $expected => $actual) {
            $this->assertInstanceOf(RequestContract::class, $actual);
            $this->assertInstanceOf($expected, $actual);
        }

        $actual = $this->pathValue();

        $this->assertEmpty($actual);
    }

    protected function pathValue(): array
    {
        $reflection = new ReflectionClass($this->client);

        $property = $reflection->getProperty('path');

        $property->setAccessible(true);

        return $property->getValue($this->client);
    }
}

[shahmal1yev]

public function build(array $arguments = []): RequestContract
{
    $namespace = $this->namespace();

    if (! class_exists($namespace)) {
        throw new Exception("$namespace class does not exist.");
    }

    return new $namespace(...$arguments);
}

[shahmal1yev]

Development started in #10 🐘