riverwaysoft/php-converter

Generates TypeScript & Dart out of your PHP DTO classes.

php-converter's Issues

Support query params in API endpoint generator

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;
}

Add phpstan/phpstan-deprecation-rules

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

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
 */

Parse PHPDoc using a dedicated parser

Examples:

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

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

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

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.

Support nested DTO

Proofread README

Investigate idea of generating PHP tests based on endpoints

Performance - handle xdebug

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

Performance - short-circuit traversal

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

Change license to MIT

Support myclabs/php-enum

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

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

Support PHP 8.1 Enums

At the moment only myclabs/enum is supported

Support static & self

Class filters

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

Add "This file was autogenerated" warning

Fix PHPStan on CI

Traverse files instead of using only inline PHP

Make exception more verbose throughout the project

Use AST prettifier

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}

Test generated .dart and .ts files on CI

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

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?

Fix phpstan's complain about invalid data provider

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

Document how to exclude certain type for only 1 language

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

Provide memory & time usage

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

Generate types from a remote repo

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

Diff output for generated files

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

Generate full Api Platform iri for typescript

user: `/api/${string}`

to

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

Union types

Provide ready to run examples

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

Support PHP DocBlock for PHP versions less than 8

Add PHPStan

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

DateTime and DateTimeImmutable

Performance - Combine Dart & TypeScript conversion into 1 script

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

Extract axios API generator out of TypeScriptGenerator

Build PHAR executable

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

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

Generate enum formatters

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.

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

Array support

Make a fallback to doc block for array types

• Entity[]

Suggest to update executable script if there is a new version

It should look similar to symfony CLI:

It should be only for phar

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