OpenAPI

OpenAPIによるスキーマ駆動開発
フロントエンド側はOpenAPI Generatorなどでクライアントコード生成
バックエンド側はopenapi-psr7-validatorやSpectatorでテスト

LaravelからTypeScriptコードを自動生成して
効率良く型安全なフロントエンド開発を目指す

PHP Conference Fukuoka 2023

Urata Daiki / @daiki7nohe

浦田　大貴（ウラタ　ダイキ）

フロントエンド/モバイルアプリエンジニア

Fusic

@daiki7nohe
github.com/7nohe
PHPカンファレンス福岡2019で登壇
- JAMstackアーキテクチャを用いたモダンWebサイト開発

LaravelでTypeScript？

モダンフロントエンド開発においてVue/ReactなどはLaravelにも必要
Laravel BreezeでもTypeScriptをサポート

php artisan breeze:install vue --typescript
php artisan breeze:install vue --typescript

Laravel→Vueのデータ受け渡しが容易

Laravel

class UsersController
{
    public function index()
    {
        $users = User::active()
            ->orderByName()
            ->get(['id', 'name', 'email']);

        return Inertia::render('Users', [
            'users' => $users
        ]);
    }
}
class UsersController
{
    public function index()
    {
        $users = User::active()
            ->orderByName()
            ->get(['id', 'name', 'email']);

        return Inertia::render('Users', [
            'users' => $users
        ]);
    }
}

Vue3

<!-- Users.vue -->
<script setup lang="ts">
import Layout from './Layout'
import { Link, Head } from '@inertiajs/vue3'

defineProps({ users: User[] })
</script>

<template>
  <Layout>
    <Head title="Users" />
    <div v-for="user in users" :key="user.id">
      <Link :href="`/users/${user.id}`">
        {{ user.name }}
      </Link>
      <div>{{ user.email }}</div>
    </div>
  </Layout>
</template>
<!-- Users.vue -->
<script setup lang="ts">
import Layout from './Layout'
import { Link, Head } from '@inertiajs/vue3'

defineProps({ users: User[] })
</script>

<template>
  <Layout>
    <Head title="Users" />
    <div v-for="user in users" :key="user.id">
      <Link :href="`/users/${user.id}`">
        {{ user.name }}
      </Link>
      <div>{{ user.email }}</div>
    </div>
  </Layout>
</template>

👍

でもやっぱり別言語

Laravel

class UsersController
{
    public function index()
    {
        $users = User::active()
            ->orderByName()
            ->get(['id', 'name', 'email']);

        return Inertia::render('Users', [
            'users' => $users
        ]);
    }
}
class UsersController
{
    public function index()
    {
        $users = User::active()
            ->orderByName()
            ->get(['id', 'name', 'email']);

        return Inertia::render('Users', [
            'users' => $users
        ]);
    }
}

PHP

Vue3

<script setup lang="ts">
import Layout from './Layout'
import { Link, Head } from '@inertiajs/vue3'

defineProps({ users: Users[] })
</script>

<template>
  <Layout>
    <Head title="Users" />
    <div v-for="user in users" :key="user.id">
      <Link :href="`/users/${user.id}`">
        {{ user.name }}
      </Link>
      <div>{{ user.email }}</div>
    </div>
  </Layout>
</template>
<script setup lang="ts">
import Layout from './Layout'
import { Link, Head } from '@inertiajs/vue3'

defineProps({ users: Users[] })
</script>

<template>
  <Layout>
    <Head title="Users" />
    <div v-for="user in users" :key="user.id">
      <Link :href="`/users/${user.id}`">
        {{ user.name }}
      </Link>
      <div>{{ user.email }}</div>
    </div>
  </Layout>
</template>

TypeScript

😢

Laravelから受け取るデータは型安全なのか？

postsテーブルを作成

Laravel

// Migration file
Schema::create('posts', function (Blueprint $table) {
    $table->id();
    $table->string('title');
    $table->string('body');
    $table->timestamps();
});

// Model class
class Post extends Model {}
// Migration file
Schema::create('posts', function (Blueprint $table) {
    $table->id();
    $table->string('title');
    $table->string('body');
    $table->timestamps();
});

// Model class
class Post extends Model {}

TypeScript

type Post = {
    id: number;
    title: string;
    body: string;
    created_at?: string;
    updated_at?: string;
};
type Post = {
    id: number;
    title: string;
    body: string;
    created_at?: string;
    updated_at?: string;
};

slugカラムを追加

Laravel

public function up()
{
    Schema::table('posts', function (Blueprint $table) {
        $table->string('slug')->nullable()->after('body');
    });
}

public function down()
{
    Schema::table('posts', function (Blueprint $table) {
        $table->dropColumn('slug');
    });
}
public function up()
{
    Schema::table('posts', function (Blueprint $table) {
        $table->string('slug')->nullable()->after('body');
    });
}

public function down()
{
    Schema::table('posts', function (Blueprint $table) {
        $table->dropColumn('slug');
    });
}

TypeScript

body→contentにカラム名を変更

Laravel

public function up()
{
    Schema::table('posts', function (Blueprint $table) {
        $table->renameColumn('body', 'content');
    });
}

public function down()
{
    Schema::table('posts', function (Blueprint $table) {
        $table->renameColumn('content', 'body');
    });
}
public function up()
{
    Schema::table('posts', function (Blueprint $table) {
        $table->renameColumn('body', 'content');
    });
}

public function down()
{
    Schema::table('posts', function (Blueprint $table) {
        $table->renameColumn('content', 'body');
    });
}

TypeScript

Laravel

class PostsController
{
    public function index()
    {
        $posts = Post::all();
        return Inertia::render('Posts', [
            'posts' => $posts
        ]);
    }
}
class PostsController
{
    public function index()
    {
        $posts = Post::all();
        return Inertia::render('Posts', [
            'posts' => $posts
        ]);
    }
}

Vue

<!-- Posts.vue -->
<script setup lang="ts">
import { Post } from '@/types/model'
import { Link, Head } from '@inertiajs/vue3'

defineProps({ posts: Post[] })
</script>

<template>
  <div>
    <h1>投稿データ一覧</h1>
    <ul>
      <li v-for="post in posts" :key="post.id">
        <h2>{{ post.title }}</h2>
        <p>{{ post.conetnt }}</p>
      </li>
    </ul>
  </div>
</template>
<!-- Posts.vue -->
<script setup lang="ts">
import { Post } from '@/types/model'
import { Link, Head } from '@inertiajs/vue3'

defineProps({ posts: Post[] })
</script>

<template>
  <div>
    <h1>投稿データ一覧</h1>
    <ul>
      <li v-for="post in posts" :key="post.id">
        <h2>{{ post.title }}</h2>
        <p>{{ post.conetnt }}</p>
      </li>
    </ul>
  </div>
</template>

😇

内容が表示されない

postsの中身

[
  {
    "id": 1,
    "title": "タイトル1",
    "content": "内容1",
    "slug": "post-1",
    "created_at": "2023-06-18 10:00:00",
    "updated_at": "2023-06-18 12:30:00"
  },
  {
    "id": 2,
    "title": "タイトル2",
    "content": "内容2",
    "slug": "post-2",
    "created_at": "2023-06-19 09:15:00",
    "updated_at": "2023-06-20 14:20:00"
  },
  {
    "id": 3,
    "title": "タイトル3",
    "content": "内容3",
    "slug": "post-3",
    "created_at": "2023-06-21 16:45:00",
    "updated_at": "2023-06-21 18:10:00"
  }
]
[
  {
    "id": 1,
    "title": "タイトル1",
    "content": "内容1",
    "slug": "post-1",
    "created_at": "2023-06-18 10:00:00",
    "updated_at": "2023-06-18 12:30:00"
  },
  {
    "id": 2,
    "title": "タイトル2",
    "content": "内容2",
    "slug": "post-2",
    "created_at": "2023-06-19 09:15:00",
    "updated_at": "2023-06-20 14:20:00"
  },
  {
    "id": 3,
    "title": "タイトル3",
    "content": "内容3",
    "slug": "post-3",
    "created_at": "2023-06-21 16:45:00",
    "updated_at": "2023-06-21 18:10:00"
  }
]

Vue

<script setup lang="ts">
import { Post } from '@types/model'
import { Link, Head } from '@inertiajs/vue3'

defineProps({ posts: Post[] })
</script>

<template>
  <div>
    <h1>投稿データ一覧</h1>
    <ul>
      <li v-for="post in posts" :key="post.id">
        <h2>{{ post.title }}</h2>
        <p>{{ post.conetnt }}</p>
      </li>
    </ul>
  </div>
</template>
<script setup lang="ts">
import { Post } from '@types/model'
import { Link, Head } from '@inertiajs/vue3'

defineProps({ posts: Post[] })
</script>

<template>
  <div>
    <h1>投稿データ一覧</h1>
    <ul>
      <li v-for="post in posts" :key="post.id">
        <h2>{{ post.title }}</h2>
        <p>{{ post.conetnt }}</p>
      </li>
    </ul>
  </div>
</template>

Typo

手動の型定義ではバグを生む可能性がある

列挙型（Enum）は？

PHP 8.1

enum Color: int {
    case RED = 1;
    case GREEN = 2;
    case BLUE = 3;
}
enum Color: int {
    case RED = 1;
    case GREEN = 2;
    case BLUE = 3;
}

PHPとTypeScriptで似たようなコード
コードの2重管理

TypeScript

enum Color {
    RED = 1,
    GREEN = 2,
    BLUE = 3
}
enum Color {
    RED = 1,
    GREEN = 2,
    BLUE = 3
}

ルーティングは？

Laravel

// routes/web.php
Route::get('/dashboard', DashboardController::class)
    ->name('dashboard');

// app/Http/Controllers/DashboardController.php
class DashboardController extends Controller
{
    public function __invoke()
    {
        return Inertia::render('Dashboard');
    }
}
// routes/web.php
Route::get('/dashboard', DashboardController::class)
    ->name('dashboard');

// app/Http/Controllers/DashboardController.php
class DashboardController extends Controller
{
    public function __invoke()
    {
        return Inertia::render('Dashboard');
    }
}

Vue

<script setup lang="ts">
import { Link } from '@inertiajs/vue3';
</script>

<template>
  <div class="container">
    <a href="/dashboard">Dashboard</a>

    <!-- ziggy -->
    <a :href="route('dashboard')">Dashboard</a>

    <!-- Inertia + ziggy -->
    <Link :href="route('dashboard')">Dashboard</Link>
  </div>
</template>
<script setup lang="ts">
import { Link } from '@inertiajs/vue3';
</script>

<template>
  <div class="container">
    <a href="/dashboard">Dashboard</a>

    <!-- ziggy -->
    <a :href="route('dashboard')">Dashboard</a>

    <!-- Inertia + ziggy -->
    <Link :href="route('dashboard')">Dashboard</Link>
  </div>
</template>

パスの変更

Laravel

Vue

dashboardへのリンクを使用している箇所を洗い出し、この修正を適用しなければならない
typoに気をつけなければならない
fetch APIやaxiosなどのHTTPリクエストも同様
ziggy-jsでは名前付きルーティングの値が正しいか事前にTSで検知できない

問題まとめ

LaravelのモデルとVueのprops型の齟齬
PHPのEnumとTypeScriptのEnumの齟齬
LaravelのルーティングとVueのパスの齟齬

別言語間で似たコードの重複が原因

解決策は？

OpenAPI

OpenAPIによるスキーマ駆動開発
フロントエンド側はOpenAPI Generatorなどでクライアントコード生成
バックエンド側はopenapi-psr7-validatorやSpectatorでテスト

Good 👍

コード自動生成でTypeScript側の手動型定義が不要
Laravel側もAPIスキーマの仕様と正しく実装されてるかテストするのでフロントエンド側との齟齬も起きない
フロントエンドとバックエンドが完全分離した大規模アプリなら有り

Bad 👎

APIスキーマのメンテコストがかかるので、小規模やモノリシックなアプリの場合は開発速度が下がる可能性も
InertiaのようにJS側のHTTPリクエスト処理を省略したアプリにはそもそも使えない

もっと効率よく、かつ（それなりに）型安全なフロントエンド開発がしたい！

LaravelのコードからTypeScriptの型を自動生成する

モデル、列挙型、ルーティングなどフロントエンド側で必要そうな型情報を提供する
メンテコストなしの開発効率重視
生成された型は必要であれば拡張、補足して使用する

Laravel → TypeScriptできるライブラリ

Enum/ルーティング未対応だったり、そもそもComposerパッケージ…

自分でも型Generatorが作れないか？

モデル情報をTypeScript側に渡せないか？

php artisan model:show

$ php artisan model:show Post
App\Models\Post ..................................................  
Database ................................................... mysql  
Table ...................................................... posts  

Attributes ........................................... type / cast  
id increments, unique ...................... bigint unsigned / int  
title ................................................ string(255)  
body ................................................. string(255)  
type ................................. string / App\Enums\PostType  
user_id .......................................... bigint unsigned  
created_at nullable .......................... datetime / datetime  
updated_at nullable .......................... datetime / datetime  

Relations ........................................................  
author BelongsTo ................................. App\Models\User  

Observers ........................................................
$ php artisan model:show Post
App\Models\Post ..................................................  
Database ................................................... mysql  
Table ...................................................... posts  

Attributes ........................................... type / cast  
id increments, unique ...................... bigint unsigned / int  
title ................................................ string(255)  
body ................................................. string(255)  
type ................................. string / App\Enums\PostType  
user_id .......................................... bigint unsigned  
created_at nullable .......................... datetime / datetime  
updated_at nullable .......................... datetime / datetime  

Relations ........................................................  
author BelongsTo ................................. App\Models\User  

Observers ........................................................

JSONとしても出力できる

$ php artisan model:show Post --json > Post.json
$ php artisan model:show Post --json > Post.json

JSONならNode.js側でも扱える
Node.js側でmodel:showコマンドを叩く

生成例

{
    "class": "App\\Models\\Post",
    "database": "mysql",
    "table": "posts",
    "policy": null,
    "attributes": [
        {
            "name": "id",
            "type": "bigint unsigned",
            "increments": true,
            "nullable": false,
            "default": null,
            "unique": true,
            "fillable": false,
            "hidden": false,
            "appended": null,
            "cast": "int"
        },
        {
            "name": "title",
            "type": "string(255)",
            "increments": false,
            "nullable": false,
            "default": null,
            "unique": false,
            "fillable": false,
            "hidden": false,
            "appended": null,
            "cast": null
        },
        {
            "name": "body",
            "type": "string(255)",
            "increments": false,
            "nullable": false,
            "default": null,
            "unique": false,
            "fillable": false,
            "hidden": false,
            "appended": null,
            "cast": null
        },
        {
            "name": "type",
            "type": "string",
            "increments": false,
            "nullable": false,
            "default": null,
            "unique": false,
            "fillable": false,
            "hidden": false,
            "appended": null,
            "cast": "App\\Enums\\PostType"
        },
        {
            "name": "user_id",
            "type": "bigint unsigned",
            "increments": false,
            "nullable": false,
            "default": null,
            "unique": false,
            "fillable": false,
            "hidden": false,
            "appended": null,
            "cast": null
        },
        {
            "name": "created_at",
            "type": "datetime",
            "increments": false,
            "nullable": true,
            "default": null,
            "unique": false,
            "fillable": false,
            "hidden": false,
            "appended": null,
            "cast": "datetime"
        },
        {
            "name": "updated_at",
            "type": "datetime",
            "increments": false,
            "nullable": true,
            "default": null,
            "unique": false,
            "fillable": false,
            "hidden": false,
            "appended": null,
            "cast": "datetime"
        }
    ],
    "relations": [
        {
            "name": "author",
            "type": "BelongsTo",
            "related": "App\\Models\\User"
        }
    ],
    "observers": []
}
{
    "class": "App\\Models\\Post",
    "database": "mysql",
    "table": "posts",
    "policy": null,
    "attributes": [
        {
            "name": "id",
            "type": "bigint unsigned",
            "increments": true,
            "nullable": false,
            "default": null,
            "unique": true,
            "fillable": false,
            "hidden": false,
            "appended": null,
            "cast": "int"
        },
        {
            "name": "title",
            "type": "string(255)",
            "increments": false,
            "nullable": false,
            "default": null,
            "unique": false,
            "fillable": false,
            "hidden": false,
            "appended": null,
            "cast": null
        },
        {
            "name": "body",
            "type": "string(255)",
            "increments": false,
            "nullable": false,
            "default": null,
            "unique": false,
            "fillable": false,
            "hidden": false,
            "appended": null,
            "cast": null
        },
        {
            "name": "type",
            "type": "string",
            "increments": false,
            "nullable": false,
            "default": null,
            "unique": false,
            "fillable": false,
            "hidden": false,
            "appended": null,
            "cast": "App\\Enums\\PostType"
        },
        {
            "name": "user_id",
            "type": "bigint unsigned",
            "increments": false,
            "nullable": false,
            "default": null,
            "unique": false,
            "fillable": false,
            "hidden": false,
            "appended": null,
            "cast": null
        },
        {
            "name": "created_at",
            "type": "datetime",
            "increments": false,
            "nullable": true,
            "default": null,
            "unique": false,
            "fillable": false,
            "hidden": false,
            "appended": null,
            "cast": "datetime"
        },
        {
            "name": "updated_at",
            "type": "datetime",
            "increments": false,
            "nullable": true,
            "default": null,
            "unique": false,
            "fillable": false,
            "hidden": false,
            "appended": null,
            "cast": "datetime"
        }
    ],
    "relations": [
        {
            "name": "author",
            "type": "BelongsTo",
            "related": "App\\Models\\User"
        }
    ],
    "observers": []
}

route:listコマンドにもjsonオプションがある

$ php artisan route:list --json > route.json
$ php artisan route:list --json > route.json

[
    {
        "domain": null,
        "method": "GET|HEAD",
        "uri": "\/",
        "name": null,
        "action": "Closure",
        "middleware": [
            "web"
        ]
    },
    {
        "domain": null,
        "method": "GET|HEAD",
        "uri": "dashboard",
        "name": "dashboard",
        "action": "App\\Http\\Controllers\\DashboardController",
        "middleware": [
            "web",
            "App\\Http\\Middleware\\Authenticate",
            "Illuminate\\Auth\\Middleware\\EnsureEmailIsVerified"
        ]
    },
]
[
    {
        "domain": null,
        "method": "GET|HEAD",
        "uri": "\/",
        "name": null,
        "action": "Closure",
        "middleware": [
            "web"
        ]
    },
    {
        "domain": null,
        "method": "GET|HEAD",
        "uri": "dashboard",
        "name": "dashboard",
        "action": "App\\Http\\Controllers\\DashboardController",
        "middleware": [
            "web",
            "App\\Http\\Middleware\\Authenticate",
            "Illuminate\\Auth\\Middleware\\EnsureEmailIsVerified"
        ]
    },
]

JSONを解析してコード生成すればできそう！

列挙型（Enum）は？

純粋なPHP構文のため、artisanコマンドでJSONに出力できない
npmパッケージのphp-parserを使用
抽象構文木（AST）を解析してTypeScriptのEnumに変換する

import { Engine } from "php-parser";
import fs from "fs";

const parser = new Engine({});
const phpFile = fs.readFileSync("./example.php"); // '<?php echo "Hello World";'
console.log(parser.parseCode(phpFile));
import { Engine } from "php-parser";
import fs from "fs";

const parser = new Engine({});
const phpFile = fs.readFileSync("./example.php"); // '<?php echo "Hello World";'
console.log(parser.parseCode(phpFile));

AST output

{
  'kind': 'program',
  'children': [
    {
      'kind': 'echo',
      'arguments': [
        {
          'kind': 'string',
          'isDoubleQuote': true,
          'value': 'Hello World'
        }
      ]
    }
  ]
}
{
  'kind': 'program',
  'children': [
    {
      'kind': 'echo',
      'arguments': [
        {
          'kind': 'string',
          'isDoubleQuote': true,
          'value': 'Hello World'
        }
      ]
    }
  ]
}

コード生成について

TypeScript Compiler API

TypeScriptコードの解析、トランスパイル、コード生成ができる
factory関数でASTを作成、printerでコードを出力
正しい構文のコードが生成できる

factoryでAST作成

import ts from "typescript"

function makeFactorialFunction() {
  const functionName = ts.factory.createIdentifier("factorial");
  const paramName = ts.factory.createIdentifier("n");
  const parameter = ts.factory.const parameter = ts.factory.createParameterDeclaration(
    /*modifiers*/ undefined,
    /*dotDotDotToken*/ undefined,
    paramName
  );

  // 省略
  
  return ts.factory.createFunctionDeclaration(
    /*modifiers*/ [ts.factory.createToken(ts.SyntaxKind.ExportKeyword)],
    /*asteriskToken*/ undefined,
    functionName,
    /*typeParameters*/ undefined,
    [parameter],
    /*returnType*/ ts.factory.createKeywordTypeNode(ts.SyntaxKind.NumberKeyword),
    ts.factory.createBlock(statements, /*multiline*/ true)
  );
}
import ts from "typescript"

function makeFactorialFunction() {
  const functionName = ts.factory.createIdentifier("factorial");
  const paramName = ts.factory.createIdentifier("n");
  const parameter = ts.factory.const parameter = ts.factory.createParameterDeclaration(
    /*modifiers*/ undefined,
    /*dotDotDotToken*/ undefined,
    paramName
  );

  // 省略
  
  return ts.factory.createFunctionDeclaration(
    /*modifiers*/ [ts.factory.createToken(ts.SyntaxKind.ExportKeyword)],
    /*asteriskToken*/ undefined,
    functionName,
    /*typeParameters*/ undefined,
    [parameter],
    /*returnType*/ ts.factory.createKeywordTypeNode(ts.SyntaxKind.NumberKeyword),
    ts.factory.createBlock(statements, /*multiline*/ true)
  );
}

printerで出力

const resultFile = ts.createSourceFile(
  "someFileName.ts",
  "",
  ts.ScriptTarget.Latest,
  /*setParentNodes*/ false,
  ts.ScriptKind.TS
);

const printer = ts.createPrinter({ newLine: ts.NewLineKind.LineFeed });

const result = printer.printNode(ts.EmitHint.Unspecified, makeFactorialFunction(), resultFile);
console.log(result);
const resultFile = ts.createSourceFile(
  "someFileName.ts",
  "",
  ts.ScriptTarget.Latest,
  /*setParentNodes*/ false,
  ts.ScriptKind.TS
);

const printer = ts.createPrinter({ newLine: ts.NewLineKind.LineFeed });

const result = printer.printNode(ts.EmitHint.Unspecified, makeFactorialFunction(), resultFile);
console.log(result);

出力結果

export function factorial(n): number {
    if (n <= 1) {
        return 1;
    }
    return n * factorial(n - 1);
}
export function factorial(n): number {
    if (n <= 1) {
        return 1;
    }
    return n * factorial(n - 1);
}

Laravel（PHP） → JSON/AST → TypeScript Compiler API → TypeScript

Laravel Typegen

特徴

LaravelのモデルからTypeScriptの型生成
リレーション対応
Enum対応
LaravelのフォームリクエストからTypeScriptの型生成
Laravelのルーティングからziggy-js用の型定義ファイル生成
composerではなくnpmのパッケージ（Laravel側に影響しない）

使い方

インストール

$ npm install -D @7nohe/laravel-typegen
$ npm install -D @7nohe/laravel-typegen

package.json編集

{
    "scripts": {
        "typegen": "laravel-typegen"
    },
}
{
    "scripts": {
        "typegen": "laravel-typegen"
    },
}

実行

$ npm run typegen
$ npm run typegen

モデルの型生成

<?php

namespace App\Models;

use App\Enums\PostType;
use Illuminate\Database\Eloquent\Factories\HasFactory;
use Illuminate\Database\Eloquent\Model;

class Post extends Model
{
    use HasFactory;

    protected $casts = [
        'type' => PostType::class,
    ];

    public function author()
    {
        return $this->belongsTo(User::class);
    }
}
<?php

namespace App\Models;

use App\Enums\PostType;
use Illuminate\Database\Eloquent\Factories\HasFactory;
use Illuminate\Database\Eloquent\Model;

class Post extends Model
{
    use HasFactory;

    protected $casts = [
        'type' => PostType::class,
    ];

    public function author()
    {
        return $this->belongsTo(User::class);
    }
}

TypeScript（自動生成）

export type Post = {
    id: number;
    title: string;
    body: string;
    type: PostType;
    user_id: number;
    created_at?: string;
    updated_at?: string;
    author?: User;
};
export type Post = {
    id: number;
    title: string;
    body: string;
    type: PostType;
    user_id: number;
    created_at?: string;
    updated_at?: string;
    author?: User;
};

Enum（PHP8.1）

<?php declare(strict_types=1);

namespace App\Enums;

enum PostType: int
{
    case Public = 10;
    case Private = 20;
}
<?php declare(strict_types=1);

namespace App\Enums;

enum PostType: int
{
    case Public = 10;
    case Private = 20;
}

Laravel Enum

<?php declare(strict_types=1);

namespace App\LaravelEnums;

use BenSampo\Enum\Enum;

final class PostType extends Enum
{
    const Public = 10;
    const Private = 20;
}
<?php declare(strict_types=1);

namespace App\LaravelEnums;

use BenSampo\Enum\Enum;

final class PostType extends Enum
{
    const Public = 10;
    const Private = 20;
}

TypeScript（自動生成）

export enum PostType {
    Public = 10,
    Private = 20
}
export enum PostType {
    Public = 10,
    Private = 20
}

ルーティングの型生成

// routes/web.php
Route::resource('posts', PostsController::class);
// routes/web.php
Route::resource('posts', PostsController::class);

$ php artisan route:list
  GET|HEAD        posts .................. posts.index › PostsController@index
  POST            posts .................. posts.store › PostsController@store
  GET|HEAD        posts/create ......... posts.create › PostsController@create
  GET|HEAD        posts/{post} ............. posts.show › PostsController@show
  PUT|PATCH       posts/{post} ......... posts.update › PostsController@update
  DELETE          posts/{post} ....... posts.destroy › PostsController@destroy
  GET|HEAD        posts/{post}/edit ........ posts.edit › PostsController@edit
$ php artisan route:list
  GET|HEAD        posts .................. posts.index › PostsController@index
  POST            posts .................. posts.store › PostsController@store
  GET|HEAD        posts/create ......... posts.create › PostsController@create
  GET|HEAD        posts/{post} ............. posts.show › PostsController@show
  PUT|PATCH       posts/{post} ......... posts.update › PostsController@update
  DELETE          posts/{post} ....... posts.destroy › PostsController@destroy
  GET|HEAD        posts/{post}/edit ........ posts.edit › PostsController@edit

TypeScript（自動生成）

export type RouteParams = {
    "dashboard": {};
    "posts.index": {};
    "posts.store": {};
    "posts.create": {};
    "posts.show": {
        post: string;
    };
    "posts.update": {
        post: string;
    };
    "posts.destroy": {
        post: string;
    };
    "posts.edit": {
        post: string;
    };
};
export type RouteParams = {
    "dashboard": {};
    "posts.index": {};
    "posts.store": {};
    "posts.create": {};
    "posts.show": {
        post: string;
    };
    "posts.update": {
        post: string;
    };
    "posts.destroy": {
        post: string;
    };
    "posts.edit": {
        post: string;
    };
};

さらにziggy-jsのroute()の型を上書きする型定義ファイル（route.d.ts）を生成

ルーティング名、パラメーターのミスを検知

// OK
route('posts.show', { post: post.id })

// TS Error: Argument of type '{ id: string; }' is not assignable to parameter of type '{ post: string; }'
route('posts.show', { id: post.id })

// TS Error: Argument of type '"post.show"' is not assignable to parameter of type 'keyof RouteParams'.ts
route('posts.detail', { post: post.id })
// OK
route('posts.show', { post: post.id })

// TS Error: Argument of type '{ id: string; }' is not assignable to parameter of type '{ post: string; }'
route('posts.show', { id: post.id })

// TS Error: Argument of type '"post.show"' is not assignable to parameter of type 'keyof RouteParams'.ts
route('posts.detail', { post: post.id })

フォームリクエストからの型生成

Laravel

<?php

namespace App\Http\Requests\Auth;

use Illuminate\Foundation\Http\FormRequest;

class LoginRequest extends FormRequest
{
    public function rules()
    {
        return [
            'email' => ['required', 'string', 'email'],
            'password' => ['required', 'string'],
        ];
    }
}
<?php

namespace App\Http\Requests\Auth;

use Illuminate\Foundation\Http\FormRequest;

class LoginRequest extends FormRequest
{
    public function rules()
    {
        return [
            'email' => ['required', 'string', 'email'],
            'password' => ['required', 'string'],
        ];
    }
}

TypeScript（自動生成）

export type LoginRequest = {
    email: string;
    password: string;
};
export type LoginRequest = {
    email: string;
    password: string;
};

Axiosでの使用例


const res = await axios.post<
    LoginResponse,
    AxiosResponse<LoginResponse, LoginRequest>,
    LoginRequest
>("/login", {
    email: "test@example.com",
    password: "password",
});

const res = await axios.post<
    LoginResponse,
    AxiosResponse<LoginResponse, LoginRequest>,
    LoginRequest
>("/login", {
    email: "test@example.com",
    password: "password",
});

POSTリクエストの型強化に利用可能

デモ

問題おさらい

~~LaravelのモデルとVueのprops型の齟齬~~
~~PHPのEnumとTypeScriptのEnumの齟齬~~
~~LaravelのルーティングとVueのパスの齟齬~~

Laravelをベースに自動生成することでより信頼できる型が得られた😊

実案件へ導入してみて

規模
- 10画面くらい
- ダッシュボード、一覧（検索あり）、詳細画面（UIが少し複雑）など
技術スタック
- Laravel10 + Breeze(Inertia + Vue3) + TypeScript

よかった点
- 自分で型定義する事が少なかった
- バックエンドの実装を確認する手間が少なかった
つまずいた点
- モデル（DBテーブル）と実際に渡ってくるpropsの形にずれがあると自分で補足する必要がある
- PivotやAccessorなど自動生成で拾えないフィールドもあった

Laravel

public function fullName(): Attribute
{
    return new Attribute(
        get: fn () => $this->first_name .' ' . $this->last_name
    );
}
public function fullName(): Attribute
{
    return new Attribute(
        get: fn () => $this->first_name .' ' . $this->last_name
    );
}

TypeScript

type UserWithFullName = User & {
    full_name: string;
};
type UserWithFullName = User & {
    full_name: string;
};

Intersection Typesなどで補足する必要あり

【おまけ】多言語対応

LaravelとVueで翻訳ファイルを共通化したい
Laravelではjsonファイルが扱える

/lang
    en.json
    ja.json
/lang
    en.json
    ja.json

Vue i18nなどでもこのjsonを読み込んで共通利用する
laravel-vue-i18nとかも便利

翻訳漏れのミスを防ぐ

import { createI18n } from 'vue-i18n'
import enUS from './locales/en-US.json'

// 'en-US'がベースとなり他言語ファイルの翻訳漏れに気づける！
type MessageSchema = typeof enUS

const i18n = createI18n<[MessageSchema], 'en-US' | 'ja-JP'>({
  locale: 'en-US',
  messages: {
    'en-US': enUS
  }
})
import { createI18n } from 'vue-i18n'
import enUS from './locales/en-US.json'

// 'en-US'がベースとなり他言語ファイルの翻訳漏れに気づける！
type MessageSchema = typeof enUS

const i18n = createI18n<[MessageSchema], 'en-US' | 'ja-JP'>({
  locale: 'en-US',
  messages: {
    'en-US': enUS
  }
})

参考: Type-safe resources with schema

【おまけ】Laravel Zodgen

これも自作ライブラリ
LaravelのForm RequestクラスからZodスキーマが生成できる
コアの解析処理はLaravel Typegenでも使用

Laravel

<?php

namespace App\Http\Requests;

use Illuminate\Foundation\Http\FormRequest;

class StorePostRequest extends FormRequest
{
    public function rules(): array
    {
        return [
            'title' => 'required|string|max:255',
            'body' => 'required|string',
        ];
    }
}
<?php

namespace App\Http\Requests;

use Illuminate\Foundation\Http\FormRequest;

class StorePostRequest extends FormRequest
{
    public function rules(): array
    {
        return [
            'title' => 'required|string|max:255',
            'body' => 'required|string',
        ];
    }
}

Zod

export const StorePostRequest = z.object({
    title: z.string().max(255).nonempty(),
    body: z.string().nonempty()
});
export const StorePostRequest = z.object({
    title: z.string().max(255).nonempty(),
    body: z.string().nonempty()
});

生成したZodスキーマはReact Hook FormやVeeValidateなどでの利用を想定
クライアントサイドバリデーションを効率よく実装でき、UXの向上が期待できる

まとめ

LaravelからTypeScriptの型自動生成でバックエンドとフロントエンドのミスコミュニケーションを軽減できる
小規模やInertiaアプリではこの手法がスピードを落とさず型安全な開発ができる
LaravelからTypeScriptの型生成はartisanコマンド、PHPパーサー、TypeScript Compiler APIの組み合わせで実現できる

OpenAPI

Good 👍

Bad 👎

LaravelからTypeScriptコードを自動生成して 効率良く型安全なフロントエンド開発を目指す

PHP Conference Fukuoka 2023

浦田 大貴（ウラタ ダイキ）

Table of contents

LaravelでTypeScript？

Laravel→Vueのデータ受け渡しが容易

Laravel

Vue3

でもやっぱり別言語

Laravel

Vue3

Laravelから受け取るデータは型安全なのか？

postsテーブルを作成

Laravel

TypeScript

slugカラムを追加

Laravel

TypeScript

body→contentにカラム名を変更

Laravel

TypeScript

Laravel

Vue

postsの中身

Vue

手動の型定義ではバグを生む可能性がある

列挙型（Enum）は？

PHP 8.1

TypeScript

ルーティングは？

Laravel

Vue

パスの変更

Laravel

Vue

問題まとめ

解決策は？

OpenAPI

Good 👍

Bad 👎

もっと効率よく、かつ（それなりに）型安全なフロントエンド開発がしたい！

LaravelのコードからTypeScriptの型を自動生成する

Laravel → TypeScriptできるライブラリ

自分でも型Generatorが作れないか？

モデル情報をTypeScript側に渡せないか？

php artisan model:show

JSONとしても出力できる

生成例

route:listコマンドにもjsonオプションがある

JSONを解析してコード生成すればできそう！

列挙型（Enum）は？

コード生成について

TypeScript Compiler API

factoryでAST作成

printerで出力

出力結果

Laravel（PHP） → JSON/AST → TypeScript Compiler API → TypeScript

Laravel Typegen

特徴

使い方

モデルの型生成

TypeScript（自動生成）

Enum（PHP8.1）

Laravel Enum

TypeScript（自動生成）

ルーティングの型生成

TypeScript（自動生成）

ルーティング名、パラメーターのミスを検知

フォームリクエストからの型生成

Laravel

TypeScript（自動生成）

Axiosでの使用例

デモ

問題おさらい

実案件へ導入してみて

Laravel

TypeScript

LaravelからTypeScriptコードを自動生成して
効率良く型安全なフロントエンド開発を目指す

浦田　大貴（ウラタ　ダイキ）