README

Pre-release — Architecture by senior tech lead, implementation largely AI-assisted with human review. Not fully reviewed. Architecture may change before v1.0.0.

Framework-agnostic resource definition layer for PHP. Define your API resources once — fields, relations, actions, computed fields — and let consumer packages (OpenAPI, BFF, generic API) derive everything else.

Installation

composer require dandoetech/resource-registry

Quick Start

Define a resource by extending the Resource base class:

use DanDoeTech\ResourceRegistry\Resource;
use DanDoeTech\ResourceRegistry\Builder\ResourceBuilder;
use DanDoeTech\ResourceRegistry\Definition\FieldType;

class ProductResource extends Resource
{
    protected function define(ResourceBuilder $b): void
    {
        $b->key('product')
          ->label('Product')
          ->timestamps()
          ->field('name', FieldType::String, nullable: false, rules: ['required', 'max:120'])
          ->field('price', FieldType::Float, nullable: false, rules: ['min:0'])
          ->field('category_id', FieldType::Integer, nullable: false)
          ->belongsTo('category', foreignKey: 'category_id')
          ->hasMany('reviews')
          ->computed('category_name', FieldType::String, via: 'category.name')
          ->computed('orders_count', FieldType::Integer, via: 'count:orders')
          ->filterable(['name', 'price', 'category_name'])
          ->sortable(['name', 'price', 'created_at', 'orders_count'])
          ->searchable(['name'])
          ->action('create')
          ->action('update')
          ->action('delete');
    }
}

Use the registry to access resource definitions:

use DanDoeTech\ResourceRegistry\Registry\ArrayRegistryDriver;
use DanDoeTech\ResourceRegistry\Registry\Registry;

// For standalone/testing use, ArrayRegistryDriver accepts array configs
$driver = new ArrayRegistryDriver([
    'product' => [
        'label' => 'Product',
        'fields' => [
            new FieldDefinition('name', FieldType::String, nullable: false),
            new FieldDefinition('price', FieldType::Float, nullable: false),
        ],
        'actions' => [new ActionDefinition('create')],
    ],
]);
$registry = new Registry($driver);

$product = $registry->getResource('product');
echo $product->getLabel(); // "Product"

foreach ($product->getFields() as $field) {
    echo $field->getName() . ': ' . $field->getType()->value;
}

Laravel users: Use dandoetech/laravel-resource-registry for automatic class-based discovery, service provider binding, and Eloquent integration.

API Overview

Contracts

All consumer packages type against these interfaces, never concrete classes.

Enums

Core Classes

Value Objects

ResourceDefinition, FieldDefinition, RelationDefinition, ActionDefinition, ComputedFieldDefinition — final class implementations of their interfaces. Used internally by drivers and tests.

Computed Fields

Flat, derived columns for list views. Two strategies:

// Generic — system builds the query via relation metadata
->computed('category_name', FieldType::String, via: 'category.name')
->computed('orders_count', FieldType::Integer, via: 'count:orders')

// Custom — your resolver class handles the query
->computed('revenue', FieldType::Float, resolver: ProductRevenue::class)

Computed fields can be listed in filterable() and sortable() like regular fields.

Extending

Implement RegistryDriverInterface for custom backends:

use DanDoeTech\ResourceRegistry\Contracts\RegistryDriverInterface;

final class DatabaseRegistryDriver implements RegistryDriverInterface
{
    /** @return list<ResourceDefinitionInterface> */
    public function all(): array { /* ... */ }

    public function find(string $key): ?ResourceDefinitionInterface { /* ... */ }
}

Every interface has a getMeta(): array escape hatch for custom extensions.

Testing

composer install
composer test        # PHPUnit
composer qa          # cs:check + phpstan + test

License

MIT