PHP code example of abrha / laravel-data-docs

    
        
<?php
require_once('vendor/autoload.php');

/* Start to develop here. Best regards https://php-download.com/ */

    

abrha / laravel-data-docs example snippets

return [
    // ... other config

    'openapi' => [
        'enabled' => true,
        
        // IMPORTANT: Add the extended OpenAPI generator to properly merge
        // validation rules, formats, patterns, and other OpenAPI properties
        // extracted from Laravel Data attributes into the final specification
        'generators' => [
            \Abrha\LaravelDataDocs\OpenApi\ExtendedOpenApiGenerator::class,
        ],
    ],

    'strategies' => [
        'bodyParameters' => [
            \Abrha\LaravelDataDocs\Strategies\BodyParameters\GetFromRequestDTOStrategy::class,
            // ... other strategies
        ],
        'queryParameters' => [
            \Abrha\LaravelDataDocs\Strategies\QueryParameters\GetFromRequestDTOStrategy::class,
            // ... other strategies
        ],
        'responseFields' => [
            \Abrha\LaravelDataDocs\Strategies\ResponseDataStrategy::class,
            // ... other strategies
        ],
    ],
];

use Spatie\LaravelData\Data;
use Abrha\LaravelDataDocs\Attributes\Example;
use Abrha\LaravelDataDocs\Attributes\Hidden;

class CreateUserRequest extends Data
{
    public function __construct(
        #[Example('[email protected]')]
        public string $email,
        
        #[Example('John Doe')]
        public string $name,
        
        public int $age,
        
        #[Hidden]
        public bool $isAdmin = false,
    ) {}
}

class UserResponse extends Data
{
    public function __construct(
        public int $id,
        public string $email,
        public string $name,
        public int $age,
        public string $created_at,
    ) {}
}

use Abrha\LaravelDataDocs\Attributes\ResponseData;

class UserController extends Controller
{
    #[ResponseData(UserResponse::class)]
    public function store(CreateUserRequest $request)
    {
        $user = User::create($request->all());
        
        return UserResponse::from($user);
    }
    
    #[ResponseData(UserResponse::class)]
    public function show(User $user)
    {
        return UserResponse::from($user);
    }
}

use Abrha\LaravelDataDocs\Attributes\Hidden;

class UserData extends Data
{
    public function __construct(
        public string $name,
        
        #[Hidden]
        public bool $internalFlag = false,
        
        #[Hidden]
        public ?string $debugInfo = null,
    ) {}
}

use Abrha\LaravelDataDocs\Attributes\Example;

class ProductData extends Data
{
    public function __construct(
        #[Example('Premium Widget')]
        public string $name,
        
        #[Example(29.99)]
        public float $price,
        
        #[Example(['electronics', 'gadgets'])]
        public array $tags,
        
        #[Example(true)]
        public bool $inStock,
    ) {}
}

use Abrha\LaravelDataDocs\Attributes\QueryParameter;

class SearchRequest extends Data
{
    public function __construct(
        #[QueryParameter]
        public string $search,
        
        #[QueryParameter]
        public int $page = 1,
        
        #[QueryParameter]
        public int $perPage = 15,
        
        // This will be a body parameter
        public array $filters = [],
    ) {}
}

use Abrha\LaravelDataDocs\Attributes\ResponseData;

class PostController extends Controller
{
    #[ResponseData(PostResponse::class)]
    public function index()
    {
        return PostResponse::collection(Post::paginate());
    }
    
    #[ResponseData(PostResponse::class)]
    public function store(CreatePostRequest $request)
    {
        $post = Post::create($request->all());
        return PostResponse::from($post);
    }
}

use Spatie\LaravelData\Data;
use Spatie\LaravelData\Attributes\Validation\Email;
use Spatie\LaravelData\Attributes\Validation\Min;
use Spatie\LaravelData\Attributes\Validation\Max;
use Spatie\LaravelData\Attributes\Validation\Uuid;

class CreateUserRequest extends Data
{
    public function __construct(
        #[Email]
        public string $email,
        
        #[Min(3), Max(50)]
        public string $name,
        
        #[Min(18), Max(120)]
        public int $age,
        
        #[Uuid]
        public string $organizationId,
    ) {}
}

class AddressData extends Data
{
    public function __construct(
        public string $street,
        public string $city,
        public string $zipCode,
    ) {}
}

class UserData extends Data
{
    public function __construct(
        public string $name,
        public AddressData $address,
    ) {}
}

class OrderItemData extends Data
{
    public function __construct(
        public int $productId,
        public int $quantity,
        public float $price,
    ) {}
}

class OrderData extends Data
{
    public function __construct(
        public string $customerName,
        
        /** @var OrderItemData[] */
        public array $items,
    ) {}
}

// config/data-docs.php
return [
    'custom_types' => [
        App\ValueObjects\UUID::class => [
            'type' => 'string',
            'descriptions' => ['A valid UUID v4 identifier'],
            'pattern' => '^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$',
            'format' => 'uuid',
        ],
        
        App\ValueObjects\PhoneNumber::class => [
            'type' => 'string',
            'descriptions' => ['International phone number in E.164 format'],
            'pattern' => '^\+[1-9]\d{1,14}$',
            'minLength' => 10,
            'maxLength' => 15,
        ],
    ],
];

use Abrha\LaravelDataDocs\CustomTypeProcessing\CustomTypeProcessor;
use Abrha\LaravelDataDocs\Pipeline\Context\ParameterContext;

class UlidProcessor implements CustomTypeProcessor
{
    public function process(string $className, ParameterContext $context): void
    {
        $context->type = 'string';
        $context->descriptions = ['A valid ULID identifier'];
        $context->example = '01ARZ3NDEKTSV4RRFFQ69G5FAV';
        
        // You can add dynamic logic here
        // Access other context properties, generate examples, etc.
    }
}

use Abrha\LaravelDataDocs\CustomTypeProcessing\CustomTypeProcessorRegistry;
use Symfony\Component\Uid\Ulid;

public function register()
{
    $registry = CustomTypeProcessorRegistry::getInstance();
    $registry->register(Ulid::class, new UlidProcessor());
}

use Abrha\LaravelDataDocs\Attributes\DataDocsAttribute;
use Attribute;

#[Attribute(Attribute::TARGET_PROPERTY)]
class InEnumCases implements DataDocsAttribute
{
    public function __construct(
        public readonly string $enumClass,
    ) {}
}

use Abrha\LaravelDataDocs\AttributeProcessing\AttributeProcessor;
use Abrha\LaravelDataDocs\Pipeline\Context\ParameterContext;

class InEnumCasesProcessor implements AttributeProcessor
{
    public function process(object $attribute, ParameterContext $context): void
    {
        $enumClass = $attribute->enumClass;
        $cases = array_map(fn($case) => $case->value, $enumClass::cases());
        
        $context->descriptions[] = 'Must be one of: ' . implode(', ', $cases);
        $context->example = $cases[0] ?? null;
        
        // You can modify any aspect of the context
        // Add to descriptions, set examples, modify type, etc.
    }
}

use Abrha\LaravelDataDocs\AttributeProcessing\AttributeProcessorRegistry;

public function register()
{
    $attributeRegistry = AttributeProcessorRegistry::getInstance();
    $attributeRegistry->register(InEnumCases::class, new InEnumCasesProcessor());
}

use App\Enums\UserStatus;

class UserData extends Data
{
    public function __construct(
        public string $name,
        
        #[InEnumCases(UserStatus::class)]
        public string $status,
    ) {}
}

use Abrha\LaravelDataDocs\Pipeline\ParameterPipelineStage;
use Abrha\LaravelDataDocs\Pipeline\Context\ParameterContext;

class CustomValidationStage implements ParameterPipelineStage
{
    public function process(ParameterContext $context): ParameterContext
    {
        // Full access to context - can modify any aspect
        $attributes = $context->propertyAttrs;
        
        // Complex custom logic here
        if (isset($attributes[Deprecated::class])) {
            $deprecated = $attributes[Deprecated::class];
            $context->descriptions[] = "**DEPRECATED**: {$deprecated->reason}";
        }
        
        // You can even stop processing by setting isHidden
        if ($this->shouldHideProperty($context)) {
            $context->isHidden = true;
        }
        
        return $context;
    }
    
    private function shouldHideProperty(ParameterContext $context): bool
    {
        // Complex hiding logic based on multiple factors
        return false;
    }
}

use Abrha\LaravelDataDocs\Pipeline\PipelineFactory;

// Note: You'll need to customize how you create the pipeline
// This typically happens in a service provider or strategy
$pipeline = PipelineFactory::createDefault()
    ->addStage(new CustomValidationStage());

bash
php artisan scribe:generate