Implement initial version

.github/workflows/test.yaml

@@ -0,0 +1,63 @@
+name: Run tests
+on:
+  push:
+    branches:
+    # Only mainline branches, features etc are covered on the pull_request trigger
+    - '*.x'
+  pull_request:
+  schedule:
+  # Build every Monday morning in case of external issues
+  - cron: '0 8 * * 1'
+
+jobs:
+  run-tests:
+    runs-on: ubuntu-latest
+    name: Run tests
+    strategy:
+      fail-fast: false
+      matrix:
+        php_version:
+        - '8.3'
+        - '8.4'
+        dependencies:
+        - 'default'
+        include:
+        - php_version: '8.3'
+          dependencies: 'lowest'
+
+    steps:
+    - name: Setup PHP
+      uses: shivammathur/setup-php@v2
+      with:
+        php-version: ${{ matrix.php_version }}
+        tools: composer:v2
+
+    - name: Checkout
+      uses: actions/checkout@v4
+
+    - name: Get Composer Cache Directory
+      id: composer-cache
+      run: |
+        echo "::set-output name=dir::$(composer config cache-files-dir)"
+
+    - uses: actions/cache@v4
+      with:
+        path: ${{ steps.composer-cache.outputs.dir }}
+        key: ${{ runner.os }}-composer-${{ matrix.dependencies }}-${{ hashFiles('**/composer.lock') }}
+        restore-keys: |
+          ${{ runner.os }}-composer-${{ matrix.dependencies }}
+
+    - name: Install composer dependencies
+      env:
+        DEPENDENCIES: ${{ matrix.dependencies }}
+      run: |
+        if [ $DEPENDENCIES == 'lowest' ]
+        then
+          composer update --prefer-lowest --no-interaction --no-progress
+        else
+          composer install --no-interaction --no-progress
+        fi
+
+    - name: Run unit tests
+      run: |
+        vendor/bin/phpunit

composer.json

@@ -27,7 +27,7 @@
     },
     "autoload-dev": {
         "psr-4": {
-            "test\\unit\\Ingenerator\\StubObjects\\": "test"
+            "test\\": "test/"
         }
     },
     "config": {

phpunit.xml

@@ -18,5 +18,8 @@
         <testsuite name="unit">
             <directory>test/unit</directory>
         </testsuite>
+        <testsuite name="integration">
+            <directory>test/integration</directory>
+        </testsuite>
     </testsuites>
 </phpunit>

src/Attribute/StubAs.php

@@ -0,0 +1,11 @@
+<?php
+declare(strict_types=1);
+
+namespace Ingenerator\StubObjects\Attribute;
+
+use Ingenerator\StubObjects\StubbingContext;
+
+interface StubAs
+{
+    public function cast(string $property, mixed $value, StubbingContext $context): mixed;
+}

src/Attribute/StubAs/StubAsCollection.php

@@ -0,0 +1,44 @@
+<?php
+
+namespace Ingenerator\StubObjects\Attribute\StubAs;
+
+use Attribute;
+use Doctrine\Common\Collections\ArrayCollection;
+use Doctrine\Common\Collections\Collection;
+use Ingenerator\StubObjects\Attribute\StubAs;
+use Ingenerator\StubObjects\StubbingContext;
+
+#[Attribute(Attribute::TARGET_CLASS)]
+class StubAsCollection implements StubAs
+{
+    public function __construct(
+        private readonly string $collection_class,
+        private readonly string $item_class,
+    ) {
+
+    }
+
+    public function cast(string $property, mixed $value, StubbingContext $context): mixed
+    {
+        // @todo also need an integration test covering this
+        if ($value === NULL) {
+            return $value;
+        }
+
+        if (($this->collection_class !== 'array') && $value instanceof $this->collection_class) {
+            // Assume they have built the collection object with the expected items
+            return $value;
+        }
+
+        $items = array_map(
+            fn($v) => $v instanceof $this->item_class ? $v : $context->stub_objects->stub($this->item_class, $v),
+            $value
+        );
+
+        return match ($this->collection_class) {
+            'array' => $items,
+            Collection::class => new ArrayCollection($items)
+        };
+    }
+
+}

src/Attribute/StubAs/StubAsDateTime.php

@@ -0,0 +1,30 @@
+<?php
+declare(strict_types=1);
+
+namespace Ingenerator\StubObjects\Attribute\StubAs;
+
+use Attribute;
+use DateTimeImmutable;
+use Ingenerator\StubObjects\Attribute\StubAs;
+use Ingenerator\StubObjects\StubbingContext;
+use InvalidArgumentException;
+
+#[Attribute(Attribute::TARGET_PROPERTY)]
+class StubAsDateTime implements StubAs
+{
+    public function cast(string $property, mixed $value, StubbingContext $context): mixed
+    {
+        // @todo sanity checks for the potential types of input
+        // @todo support our DateParam syntax
+        if (($value === NULL) || ($value instanceof DateTimeImmutable)) {
+            return $value;
+        }
+
+        if ($value === '') {
+            throw new InvalidArgumentException('Cannot stub a DateTime value from an empty string');
+        }
+
+        return new DateTimeImmutable($value);
+    }
+
+}

src/Attribute/StubAs/StubAsJsonEncoded.php

@@ -0,0 +1,22 @@
+<?php
+
+namespace Ingenerator\StubObjects\Attribute\StubAs;
+
+use Attribute;
+use Ingenerator\StubObjects\Attribute\StubAs;
+use Ingenerator\StubObjects\StubbingContext;
+
+#[Attribute(Attribute::TARGET_PROPERTY)]
+class StubAsJsonEncoded implements StubAs
+{
+    public function cast(string $property, mixed $value, StubbingContext $context): mixed
+    {
+        // @todo test this, also do we definitely want it in core?? And if we do would we ever guess it?
+        if (($value === null) || is_string($value)) {
+            return $value;
+        }
+
+        return json_encode($value, JSON_THROW_ON_ERROR);
+    }
+
+}

src/Attribute/StubAs/StubAsStubObject.php

@@ -0,0 +1,27 @@
+<?php
+
+namespace Ingenerator\StubObjects\Attribute\StubAs;
+
+use Attribute;
+use Ingenerator\StubObjects\Attribute\StubAs;
+use Ingenerator\StubObjects\StubbingContext;
+
+#[Attribute(Attribute::TARGET_PROPERTY)]
+class StubAsStubObject implements StubAs
+{
+    public function __construct(private readonly string $as_class)
+    {
+
+    }
+
+    public function cast(string $property, mixed $value, StubbingContext $context): mixed
+    {
+        // @todo: direct tests for the stubAs methods
+        if (($value instanceof $this->as_class) || ($value === NULL)) {
+            return $value;
+        }
+
+        return $context->stub_objects->stub($this->as_class, $value);
+    }
+
+}

src/Attribute/StubDefault.php

@@ -0,0 +1,9 @@
+<?php
+declare(strict_types=1);
+
+namespace Ingenerator\StubObjects\Attribute;
+
+interface StubDefault
+{
+    public function getValue(array $specified_values): mixed;
+}

src/Attribute/StubDefault/StubDefaultNull.php

@@ -0,0 +1,14 @@
+<?php
+
+namespace Ingenerator\StubObjects\Attribute\StubDefault;
+
+use Ingenerator\StubObjects\Attribute\StubDefault;
+
+class StubDefaultNull implements StubDefault
+{
+    public function getValue(array $specified_values): mixed
+    {
+        return NULL;
+    }
+
+}

src/Attribute/StubDefault/StubDefaultRandomString.php

@@ -0,0 +1,26 @@
+<?php
+
+namespace Ingenerator\StubObjects\Attribute\StubDefault;
+
+use Attribute;
+use Ingenerator\StubObjects\Attribute\StubDefault;
+use Random\Randomizer;
+
+#[Attribute(Attribute::TARGET_PROPERTY)]
+readonly class StubDefaultRandomString implements StubDefault
+{
+    public const ALPHANUMERIC = 'abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ12345678';
+
+    public function __construct(
+        private int $length = 16,
+        private string $chars = self::ALPHANUMERIC,
+        private Randomizer $randomizer = new Randomizer()
+    ) {
+
+    }
+
+    public function getValue(array $specified_values): string
+    {
+        return $this->randomizer->getBytesFromString($this->chars, $this->length);
+    }
+}

src/Attribute/StubDefault/StubDefaultSequentialId.php

@@ -0,0 +1,19 @@
+<?php
+declare(strict_types=1);
+
+namespace Ingenerator\StubObjects\Attribute\StubDefault;
+
+use Attribute;
+use Ingenerator\StubObjects\Attribute\StubDefault;
+
+#[Attribute(Attribute::TARGET_PROPERTY)]
+class StubDefaultSequentialId implements StubDefault
+{
+    private static int $next_id = 1;
+
+    public function getValue(array $specified_values): int
+    {
+        return ++self::$next_id;
+    }
+
+}

src/Attribute/StubDefault/StubDefaultValue.php

@@ -0,0 +1,22 @@
+<?php
+declare(strict_types=1);
+
+namespace Ingenerator\StubObjects\Attribute\StubDefault;
+
+use Attribute;
+use Ingenerator\StubObjects\Attribute\StubDefault;
+
+#[Attribute(Attribute::TARGET_PROPERTY)]
+readonly class StubDefaultValue implements StubDefault
+{
+    public function __construct(private mixed $value)
+    {
+
+    }
+
+    public function getValue(array $specified_values): mixed
+    {
+        return $this->value;
+    }
+
+}

src/Attribute/StubFactory.php

@@ -0,0 +1,26 @@
+<?php
+declare(strict_types=1);
+
+namespace Ingenerator\StubObjects\Attribute;
+
+use Attribute;
+use Ingenerator\StubObjects\Factory\CallableStubFactory;
+
+#[Attribute(Attribute::TARGET_CLASS)]
+readonly class StubFactory
+{
+    public CallableStubFactory $factory;
+
+    public function __construct(
+        callable $factory,
+    ) {
+        // We can't use the first-class callable syntax in an attribute definition, so we have to pass
+        // legacy callables (e.g. [SomeClass::class, 'methodToCall']) and convert them here
+        $this->factory = new CallableStubFactory($factory(...));
+    }
+
+    public function getFactory(): CallableStubFactory
+    {
+        return $this->factory;
+    }
+}

src/Attribute/StubMergeDefaultsWith.php

@@ -0,0 +1,16 @@
+<?php
+
+namespace Ingenerator\StubObjects\Attribute;
+
+use Attribute;
+use Ingenerator\StubObjects\StubFinalValuesMerger;
+
+#[Attribute(Attribute::TARGET_CLASS)]
+class StubMergeDefaultsWith
+{
+
+    public function __construct(public readonly StubFinalValuesMerger $merger)
+    {
+    }
+
+}

src/Attribute/StubMockClass.php

@@ -0,0 +1,17 @@
+<?php
+declare(strict_types=1);
+
+namespace Ingenerator\StubObjects\Attribute;
+
+use Attribute;
+
+#[Attribute(Attribute::TARGET_CLASS)]
+readonly class StubMockClass
+{
+
+    public function __construct(public string $class)
+    {
+
+    }
+
+}