TPsoft.org/APIlite
3
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

added return structure

Browse Source
This commit is contained in:
Igor Miňo
2026-03-29 13:37:14 +02:00
parent 951fe36da3
commit 1f32935a29
4 changed files with 243 additions and 17 deletions
Download Patch File Download Diff File Expand all files Collapse all files

135
src/APIlite.php
View File

@ -87,7 +87,8 @@ class APIlite
'doc' => null,
'description' => null,
'params' => array(),
'return' => null
'return' => null,
'return_structure' => null
);
$docComment = $ref_method->getDocComment();
if ($docComment) {
@ -115,27 +116,129 @@ class APIlite
}
if ($ref_method->hasReturnType()) {
$ref_type = $ref_method->getReturnType();
if ($ref_type instanceof \ReflectionNamedType) {
$method['return'] = $ref_type->getName();
}
if ($ref_type instanceof \ReflectionUnionType
|| $ref_type instanceof \ReflectionIntersectionType )
{
$types = $ref_type->getTypes();
$method['return'] = [];
foreach ($types as $type) {
if ($type instanceof \ReflectionNamedType) {
$method['return'][] = $type->getName();
}
}
}
$method['return'] = $this->reflectionTypeToNames($ref_type, $ref_method->getDeclaringClass());
$method['return_structure'] = $this->reflectionTypeToStructure($ref_type, $ref_method->getDeclaringClass());
}
$this->methods[] = $method;
}
return true;
}
private function reflectionTypeToNames(?\ReflectionType $ref_type, ?\ReflectionClass $context_class = null): string|array|null
{
if ($ref_type instanceof \ReflectionNamedType) {
$type_name = $this->resolveTypeName($ref_type->getName(), $context_class);
if ($ref_type->allowsNull() && strtolower($type_name) !== 'null' && strtolower($type_name) !== 'mixed') {
return array($type_name, 'null');
}
return $type_name;
}
if ($ref_type instanceof \ReflectionUnionType || $ref_type instanceof \ReflectionIntersectionType) {
$types = array();
foreach ($ref_type->getTypes() as $type) {
if (!$type instanceof \ReflectionNamedType) {
continue;
}
$one_type = $this->reflectionTypeToNames($type, $context_class);
if (is_array($one_type)) {
$types = array_merge($types, $one_type);
} else if (is_string($one_type)) {
$types[] = $one_type;
}
}
$types = array_values(array_unique($types));
return empty($types) ? null : $types;
}
return null;
}
private function reflectionTypeToStructure(?\ReflectionType $ref_type, ?\ReflectionClass $context_class = null, array $visited = array()): array|null
{
if ($ref_type instanceof \ReflectionNamedType) {
return $this->classTypeStructure(
$this->resolveTypeName($ref_type->getName(), $context_class),
$visited
);
}
if ($ref_type instanceof \ReflectionUnionType || $ref_type instanceof \ReflectionIntersectionType) {
$structures = array();
foreach ($ref_type->getTypes() as $type) {
if (!$type instanceof \ReflectionNamedType) {
continue;
}
$structure = $this->reflectionTypeToStructure($type, $context_class, $visited);
if (!is_null($structure)) {
$structures[] = $structure;
}
}
return count($structures) > 0 ? $structures : null;
}
return null;
}
private function classTypeStructure(string $type_name, array $visited = array()): array|null
{
$type_name = ltrim($type_name, '\\');
if ($this->isBuiltinTypeName($type_name) || !class_exists($type_name)) {
return null;
}
if (in_array($type_name, $visited, true)) {
return array(
'type' => $type_name,
'recursive' => true,
'properties' => array()
);
}
$visited[] = $type_name;
$refClass = new \ReflectionClass($type_name);
$properties = array();
foreach ($refClass->getProperties(\ReflectionProperty::IS_PUBLIC) as $ref_property) {
if ($ref_property->isStatic()) {
continue;
}
$property_type = $ref_property->getType();
$properties[] = array(
'name' => $ref_property->getName(),
'type' => $this->reflectionTypeToNames($property_type, $refClass),
'nullable' => is_null($property_type) ? true : $property_type->allowsNull(),
'type_structure' => $this->reflectionTypeToStructure($property_type, $refClass, $visited)
);
}
return array(
'type' => $type_name,
'properties' => $properties
);
}
private function resolveTypeName(string $type_name, ?\ReflectionClass $context_class = null): string
{
$type_name = ltrim($type_name, '\\');
if (is_null($context_class)) {
return $type_name;
}
switch (strtolower($type_name)) {
case 'self':
case 'static':
return $context_class->getName();
case 'parent':
$parent = $context_class->getParentClass();
return $parent ? $parent->getName() : $type_name;
default:
return $type_name;
}
}
private function isBuiltinTypeName(string $type_name): bool
{
return in_array(strtolower(ltrim($type_name, '\\')), array(
'array', 'bool', 'boolean', 'callable', 'closure', 'false', 'float', 'int', 'integer',
'iterable', 'mixed', 'never', 'null', 'object', 'resource', 'scalar', 'string',
'true', 'void'
), true);
}
private function parseDescription(string $doc): string
{
$lines = explode("\n", $doc);

48
src/help.tpl.php
View File

@ -1,3 +1,50 @@
<?php
$formatTypeLabel = function (mixed $type): string {
if (is_array($type)) {
return implode(' | ', array_map(function ($item) {
return is_string($item) ? $item : 'mixed';
}, $type));
}
return is_string($type) ? $type : 'mixed';
};
$renderTypeStructure = function (mixed $structure) use (&$renderTypeStructure, $formatTypeLabel): string {
if (!is_array($structure)) {
return '';
}
$structures = (array_key_exists('type', $structure) && array_key_exists('properties', $structure))
? array($structure)
: $structure;
$html = '';
foreach ($structures as $item) {
if (!is_array($item) || !isset($item['type'])) {
continue;
}
$html .= '<div style="margin-top: 1rem; padding: 1rem; background: #f8fafc; border: 1px solid #e1e5e9; border-radius: 8px;">';
$html .= '<div style="font-weight: 600; margin-bottom: 0.75rem;">' . htmlspecialchars($item['type']) . '</div>';
if (!empty($item['recursive'])) {
$html .= '<div style="color: #64748b;">Recursive reference</div>';
} else if (!empty($item['properties']) && is_array($item['properties'])) {
$html .= '<ul style="margin: 0; padding-left: 1.25rem;">';
foreach ($item['properties'] as $property) {
if (!is_array($property) || !isset($property['name'])) {
continue;
}
$html .= '<li style="margin-bottom: 0.5rem;">';
$html .= htmlspecialchars((string) $property['name']);
$html .= '<code class="parameter-type">' . htmlspecialchars($formatTypeLabel($property['type'] ?? null)) . '</code>';
$html .= $renderTypeStructure($property['type_structure'] ?? null);
$html .= '</li>';
}
$html .= '</ul>';
} else {
$html .= '<div style="color: #64748b;">No public properties</div>';
}
$html .= '</div>';
}
return $html;
};
?>
<!DOCTYPE html>
<html lang="en">
@ -461,6 +508,7 @@
<?php if (is_array($method['return'])) foreach ($method['return'] as $return) { ?>
<code class="parameter-type"><?php echo $return; ?></code>
<?php } ?>
<?php echo $renderTypeStructure($method['return_structure'] ?? null); ?>
</div>

75
src/typescript.tpl.php
View File

@ -33,6 +33,65 @@ $mapUnionType = function (mixed $type) use ($mapType): string {
return $mapType(is_string($type) ? $type : null);
};
$normalizeTypeStructures = function (mixed $structure): array {
if (!is_array($structure)) {
return array();
}
if (array_key_exists('type', $structure) && array_key_exists('properties', $structure)) {
return array($structure);
}
return array_values(array_filter($structure, 'is_array'));
};
$findTypeStructure = function (?string $type, mixed $structure) use ($normalizeTypeStructures): array|null {
if (!is_string($type) || $type === '') {
return null;
}
$type = ltrim($type, '\\');
foreach ($normalizeTypeStructures($structure) as $one_structure) {
if (($one_structure['type'] ?? null) === $type) {
return $one_structure;
}
}
return null;
};
$mapTypeWithStructure = null;
$mapUnionTypeWithStructure = null;
$mapTypeWithStructure = function (?string $type, mixed $structure) use ($mapType, &$mapUnionTypeWithStructure): string {
if (is_array($structure) && array_key_exists('type', $structure) && array_key_exists('properties', $structure)) {
$properties = array();
foreach (($structure['properties'] ?? array()) as $property) {
if (!is_array($property) || !isset($property['name'])) {
continue;
}
$propertyType = $mapUnionTypeWithStructure($property['type'] ?? null, $property['type_structure'] ?? null);
if (!empty($property['nullable']) && strpos($propertyType, 'null') === false) {
$propertyType .= ' | null';
}
$properties[] = $property['name'] . ': ' . $propertyType;
}
return empty($properties) ? 'Record<string, unknown>' : '{ ' . implode('; ', $properties) . ' }';
}
return $mapType($type);
};
$mapUnionTypeWithStructure = function (mixed $type, mixed $structure) use ($mapType, $findTypeStructure, &$mapTypeWithStructure): string {
if (is_array($type)) {
$parts = array();
foreach ($type as $singleType) {
$typeName = is_string($singleType) ? $singleType : null;
$parts[] = $mapTypeWithStructure($typeName, $findTypeStructure($typeName, $structure));
}
$parts = array_values(array_unique($parts));
return empty($parts) ? 'unknown' : implode(' | ', $parts);
}
return $mapTypeWithStructure(is_string($type) ? $type : null, $structure);
};
?>
/**
* Generated by APIlite
@ -66,6 +125,20 @@ export interface APIliteMethodDoc {
description: string | null;
params: APIliteMethodParam[];
return: string | string[] | null;
return_structure: APIliteTypeStructure | APIliteTypeStructure[] | null;
}
export interface APIliteTypeStructureProperty {
name: string;
type: string | string[] | null;
nullable: boolean;
type_structure: APIliteTypeStructure | APIliteTypeStructure[] | null;
}
export interface APIliteTypeStructure {
type: string;
recursive?: boolean;
properties: APIliteTypeStructureProperty[];
}
export interface APIliteHelpResponse {
@ -149,7 +222,7 @@ class <?php echo $this->apiName; ?> {
$paramsSignature[] = $param['name'] . ($param['optional'] ? '?' : '') . ': ' . $paramType;
$paramsPayload[] = $param['name'];
}
$returnType = $mapUnionType($method['return']);
$returnType = $mapUnionTypeWithStructure($method['return'], $method['return_structure'] ?? null);
?>
<?php echo $method['name']; ?>(<?php echo implode(', ', $paramsSignature); ?>): Promise<APIliteActionResponse<<?php echo $returnType; ?>>> {
return this.callPromise<APIliteActionResponse<<?php echo $returnType; ?>>>('<?php echo $method['name']; ?>', { <?php echo implode(', ', $paramsPayload); ?> });