README

Transpose is a package designed to streamline the creation of types for your Laravel application across different languages by introducing standardized data types, which can then be consumed by a writer of your choice.

Installation

You can install the package via composer:

composer require strucura/transpose

Configuration:

You can publish the config file with:

php artisan vendor:publish --tag="transpose-config"

Registering Transpositions

To register a transposition, you need to define it in the transpose.php configuration file. A transposition consists of discovery paths, discovery conditions, transformers, and a writer.

Example configuration:

use Illuminate\Http\Resources\Json\JsonResource;
use Spatie\StructureDiscoverer\Support\Conditions\ConditionBuilder;
use Strucura\Transpose\Builders\TranspositionBuilder;
use Strucura\Transpose\Transformers\BackedEnumDataTypeTransformer;
use Strucura\Transpose\Transformers\JsonResourceDataTypeTransformer;
use Strucura\Transpose\Writers\TypeScriptWriter;

return [
    'transpositions' => [
        TranspositionBuilder::make('TypeScript')
            ->discoveryPaths([
                app_path(''),
            ])
            ->discoveryConditions([
                ConditionBuilder::create()->enums(),
                ConditionBuilder::create()
                    ->classes()
                    ->extending(JsonResource::class),
            ])
            ->transformers([
                BackedEnumDataTypeTransformer::class,
                JsonResourceDataTypeTransformer::class,
            ])
            ->writer(TypeScriptWriter::class)
            ->writesTo(base_path('resources/js/types.ts')),
    ],
];

For more information on discovery conditions, please refer to the php-structure-discoverer package.

Transformers and Writers

Transformers take concepts within your application like ENUMs and JsonResources and map them to a standardized set of data types. From there, a writer will be utilized to handle writing your language-specific conversion of those data types. There are several default writers and transformers included by default that will handle conversions of Laravel JSON Resources as well as Backed ENUMS to TypeScript. You can generate your types with:

php artisan transpose {transposition} // php artisan transpose TypeScript

Attributes

DefineObjectProperties

The DefineObjectProperties attribute allows developers to manually assign properties to an object for edge cases where automated property assignment is not possible.

use Strucura\Transpose\Attributes\DefineProperties;
use Strucura\Transpose\Properties\PrimitiveProperty;
use Strucura\Transpose\Enums\PrimitivesEnum;

#[DefineProperties([
    new PrimitiveProperty('property1', PrimitivesEnum::String),
    new PrimitiveProperty('property2', PrimitivesEnum::Integer),
])]
class MyClass
{
    // Class implementation
}

DerivePropertiesFromModel

The DerivePropertiesFromModel attribute allows developers to derive properties from a model.

use Strucura\Transpose\Attributes\DerivePropertiesFromModel;

#[DerivePropertiesFromModel(MyModel::class)]
class MyClass
{
    // Class implementation
}

Security Vulnerabilities

If you discover any security-related issues, please email security@strucura.com instead of using the issue tracker.

Credits

License

The MIT License (MIT). Please see License File for more information.

strucura / transpose

Maintainers

Details