riverwaysoft/php-converter

Generates TypeScript & Dart out of your PHP DTO classes.

php-converter

Generates TypeScript & Dart out of your PHP DTO classes.

Why?

Statically typed languages like TypeScript or Dart are great because they allow catching bugs without even running your code. But unless there are well-defined contracts between the API and consumer apps, you may find yourself frequently adjusting outdated typings whenever the API changes. This library generates types for you, enabling you to move faster and encounter fewer bugs.

Requirements

PHP 8.0 or above

Quick start

1. Installation

composer require riverwaysoft/php-converter --dev

If the installation leads to dependency conflicts, consider using the standalone Phar version of the package.

2. Mark a few classes with the #[Dto] annotation to convert them into TypeScript or Dart.

use Riverwaysoft\PhpConverter\Filter\Attributes\Dto;

#[Dto]
class UserOutput
{
    public string $id;
    public int $age;
    public ?UserOutput $bestFriend;
    /** @var UserOutput[] */
    public array $friends;
}

4. Run the CLI command to generate TypeScript

vendor/bin/php-converter --from=/path/to/project/src --to=.

This will generate a file generated.ts with the following content:

type UserOutput = {
  id: string;
  age: number;
  bestFriend: UserOutput | null;
  friends: UserOutput[];
}

Features

• Supports all PHP data types including union types, nullable types, and enums.
• Supports PHP DocBlock types, e.g., User[], int[][]|null, and generics thanks to phpstan/phpdoc-parser
• Custom type resolvers (for instance, for DateTimeImmutable).
• Generate a single output file or multiple files (1 type per file).
• Option to override the generation logic.
• Flexible class filters with the option to use your own filters.
• Generate API client from Symfony or API Platform code.

Customization

If you'd like to customize the conversion process, you need to copy the config script to your project folder:

cp vendor/riverwaysoft/php-converter/bin/default-config.php config/ts-config.php

Now you can customize this config and run the php-converter using the following script:

vendor/bin/php-converter --from=/path/to/project/src --to=. --config=config/ts-config.php

Documentation

• Class filtering
• Customize output
• Unknown type resolvers
• Other languages support
• Troubleshooting
• Development
• Standalone installation

php-converter's Issues

Traverse files instead of using only inline PHP

Dart code generation improvements

1. Generate fromJSON + mappers:

class UserOutput {
  final String id;
  final Profile? profile;
  final FullName name

  UserOutput({
    required this.id,
    required this.name,
    this.profile,
  })
  
  factory UserOutput.fromJson(Map<String, dynamic> json) {
    return UserOutput(
      id: json['id'],
      name: FullName.fromJson(json['name']),
      profile: json['profile'] != null ? Profile.fromJson(json['profile']) : null,
  }
}

2. Investigate freezed: https://pub.dev/packages/freezed

Support query params in API endpoint generator

Suggest to update executable script if there is a new version

It should look similar to symfony CLI:

It should be only for phar

Support Map types, Records and literal types

Examples:

• array<int, string> // map
• 1|2|3 // literal type
• 'role_delete'|'remove_edit' // literal type
• array{id: int, key: string, author: User}

Performance - handle xdebug

https://github.com/composer/xdebug-handler

Provide memory & time usage

Example: https://github.com/ApiGen/ApiGen

Generate API Client for Dart

https://openapi-generator.tech/
https://clearpoint.digital/consulting/innovation/accelerate-flutter-development-with-contract-first-openapi-and-dart-code-generation/
https://apexive.com/post/openapi-generator

Make exception more verbose throughout the project

Use AST prettifier

Add PHPStan

Fix phpstan's complain about invalid data provider

https://github.com/riverwaysoft/dto-converter/actions/runs/4862942599/jobs/8669954147

Add phpstan/phpstan-deprecation-rules

https://github.com/phpstan/phpstan-deprecation-rules

Build PHAR executable

• Provide an option to build a PHAR executable. This executable will be used by frontend / mobile team without pulling backend

Built-in script to check if generated file is up-to-date

Currently the following bash can be used:

#!/bin/bash

set -e

GENERATED_FILE=generated.dart
PREV_GENERATED_FILE=current-generated.dart

cp $GENERATED_FILE $PREV_GENERATED_FILE
bin/php-converter.phar --from=./src --to=./ --config=./config/php-converter/dart-config.php

if diff -q $PREV_GENERATED_FILE $GENERATED_FILE; then
  echo "DTO ok"
  rm $PREV_GENERATED_FILE
else
  echo "Dto mismatch"
  rm $PREV_GENERATED_FILE
  exit 1
fi

Array support

Make a fallback to doc block for array types

• Entity[]

Support myclabs/php-enum

Generate full Api Platform iri for typescript

user: `/api/${string}`

to

user: `/api/users/${string}`

Union types

Extract axios API generator out of TypeScriptGenerator

Generate types from a remote repo

• It should be possible to generate types from a remote PHP repo

Fix PHPStan on CI

Append metadata for each dto type so we can distinguish if it's an API Platform's input for example

Investigate idea of generating PHP tests based on endpoints

Generate clickable @see links to the method implementation

Example:

/** @see FoodHierarchyController */
export const apiFoodHierarchyGet = (): Promise<FoodHierarchyNodeOutput[]> => {
  return axios
    .get<FoodHierarchyNodeOutput[]>(`/api/food_hierarchy`)
    .then((response) => response.data);
}

Such links only clickable in PHP files so they won't work in JS. But, we can still generate class and method so it's possible to go to the method by copying & globally searching the copied string:

/**
 * @see JobSheetMessagesApiController::createMessage
 */

Diff output for generated files

Consider using this library: https://github.com/jfcherng/php-diff/blob/v6/example/demo_cli.php

Support ApiPlatform Input converting

• Enums should be transformed into { key: { value: Enum } }
• DateTimeImmutable/DateTime should be converted to string as usual
• Doctrine ORM Embeddables should be typed manually inside dto-converter's config
• Nested inputs should be supported

Support nested DTO

Tests for CLI

We need end-to-end test that gets files from a directory, converts classes to TS/Dart then it checks that the file is created successfully + checks the generated diff.

For inspiration: http://www.inanzzz.com/index.php/post/c7jb/testing-symfony-console-command-with-phpunit

DateTime and DateTimeImmutable

Support PHP DocBlock for PHP versions less than 8

Replace kebab case / snake case with custom implementations

There is no need to use vendor package for simple things like kebab case / snake case conversion. The task is to remove jawira/case-converter from project and rewrite KebabCaseFileNameGenerator and SnakeCaseFileNameGenerator to use custom preg_replace_callback. Unit tests are required.

Support static & self

ApiResource generator improvements

• add optional filters query parameter that is going to work in GET requests
• for GET requests the result should be wrapped with CollectionResponse the same it is wrapped for dart OldEnum

Write documentation

Cover the following topics:

• How to customize class filtering
• How to customize output generation
• Error list & description what to do
• UnknownTypeResolver & how to write custom type resolver
• How to add a support for a new language (for example Golang) + Overview of the components
• Table of contents: https://raw.githubusercontent.com/ekalinin/github-markdown-toc/master/README.md

FAQ:

• How is it different from X?

Performance - Combine Dart & TypeScript conversion into 1 script

• use "begin diff" / "end diff" similar to rector

Performance - short-circuit traversal

https://github.com/nikic/PHP-Parser/blob/4.x/doc/component/Walking_the_AST.markdown#short-circuiting-traversal

Add "This file was autogenerated" warning

Class filters

• Allow to skip class by using PHPDoc / PHP Attribute
• Allow to include only classes with specific PHPDoc / PHP Attribute

Support PHP 8.1 Enums

At the moment only myclabs/enum is supported

Nullable types

class User
{
    public int $id;

    public string $name;

    public ?string $address;
}

Should be transformed to this

export type User = {
    int: number;
    name: string;
    address: string | null;
}

Provide an option to use TypeScript union types instead of Enum

At the moment dto-converter converts PHP enums to TS enums:

<?php

use MyCLabs\Enum\Enum;

class ColorEnum extends Enum
{
    private const RED = 0;
    private const GREEN = 1;
    private const BLUE = 2;
}

This will be converted to:

enum ColorEnum {
  RED = 0;
  GREEN = 1;
  BLUE = 2;
}

But it also makes sense to provide an option to convert PHP Enum to TypeScript union type if someone prefers union types over enums:

type ColorEnum = 0 | 1 | 2;

// or

type Gender = 'male' | 'female' | 'unkown';

This library already can generate union types but only when a specific condition is met: https://github.com/riverwaysoft/dto-converter/blob/8c35d6cafde77fac392ef702ee8dcf97c3d46ce1/src/Language/TypeScript/TypeScriptGenerator.php#L48

The task for PR:

1. Add a bool flag to TypeScriptGenerator's constructor. Something like preferUnionTypeOverEnum: https://github.com/riverwaysoft/dto-converter/blob/master/src/Language/TypeScript/TypeScriptGenerator.php#L21

It should be false by default.

2. If this flag is set to true - make an early return true from this function: https://github.com/riverwaysoft/dto-converter/blob/master/src/Language/TypeScript/TypeScriptGenerator.php#L61

3. Write a test for this feature. Please add it to EndToEndTest.php: https://github.com/riverwaysoft/dto-converter/blob/master/tests/EndToEndTest.php

Change license to MIT

Split generated output into different files

It should be possible to split the generated output (TypeScript or Dart) into different files. For example one class / enum per file with correct imports. To handle imports topological sort should be used.

Investigate idea of generating types based on PHPStan's evaluation

For example having this code it'd nice to generate types based on PHPStan's type output:

  #[Route('/items', name: 'items_index', methods:['get'] )]
    public function index(ManagerRegistry $doctrine): JsonResponse
    {
        $products = $doctrine
            ->getRepository(Proassist::class)
            ->findAll();
   
        $data = [];
   
        foreach ($products as $product) {
           $data[] = [
               'id' => $product->getId(),
               'name' => $product->getName(),
               'description' => $product->getDescription(),
           ];
        }
   
        return $this->json($data);
    }

PHPStan should known that the type of $data is array<{id: ..., 'name': ..., 'description': ...}>

PHPStan under the hood talk: https://www.youtube.com/watch?v=85Aq2rWpGQE

Example projects (appeared randomly in GitHub search):

• https://github.com/slawomirlewczyk/zadanie_rekrutacyjne/blob/master/symfony_api/src/Controller/ProassistController.php
• https://github.com/nodarchik/symfony-rest-api/blob/main/src/Controller/UserController.php
• https://github.com/igor-zlobine/domain-checker-api/blob/main/src/Controller/Api/DomainCheckController.php

Document how to exclude certain type for only 1 language

Proofread README

Test generated .dart and .ts files on CI

Provide ready to run examples

Similar to prisma: https://github.com/prisma/prisma-examples

Parse PHPDoc using a dedicated parser

Examples:

• number[][]
• number[]|null

Consider using this package: https://github.com/phpstan/phpdoc-parser

Generate enum formatters