README

PHP包，用于为Eloquent模型、路由、Spatie Settings生成自动的TypeScript类型。

如果您想使用与Inertia相关的辅助工具，可以安装相关的NPM包。

因为您需要PHP和TypeScript。

特性

• 💽 支持的Laravel驱动程序：MySQL、MariaDB、PostgreSQL、SQLite、SQL Server、MongoDB
• 💬 为Eloquent模型生成TS类型
• 👭 为Eloquent关系生成TS类型
• 🪄 为casts（包括原生enum支持）生成TS类型
• 📝 为appends和所有accessors生成TS类型
  • Illuminate\Database\Eloquent\Casts\Attribute与PHPDoc
  • get*Attribute方法
• #️⃣ 为counts生成TS类型
• 📖 可为Laravel分页生成pagination TS类型
• 💾 可从Eloquent模型生成简单的PHP类
• ⚙️ 为spatie/laravel-settings生成TS类型
• 🛣 为Laravel路由生成TS类型
  • 扫描路由参数
  • 对于Inertia，您可以安装@kiwilan/typescriptable-laravel NPM包来使用一些辅助工具
• ✅ 多个命令来生成类型
  • php artisan typescriptable 用于模型、设置和路由（即使您不使用所有功能也是安全的）
  • php artisan typescriptable:eloquent 用于Eloquent模型
  • php artisan typescriptable:settings 用于spatie/laravel-settings
  • php artisan typescriptable:routes 用于Laravel路由

路线图

• 添加calebporzio/sushi的解析器
• 添加spatie/laravel-permission的解析器

安装

此版本需要PHP 8.2+并且支持Laravel 11。

警告

Laravel 11已删除Doctrine DBAL。对于以前的Laravel版本，您可以使用1.12.03版本。

您可以通过composer安装此包

在 Laravel v11+ 和 PHP 8.2 中

composer require kiwilan/typescriptable-laravel

在 Laravel v9-10 和 PHP 8.1 中

composer require kiwilan/typescriptable-laravel:1.12.03

关于TypeScript

如果您想使用 .d.ts 文件，您需要在您的Laravel项目中使用TypeScript，您必须创建一个 tsconfig.json 文件并在 include 中添加 .d.ts 路径

注意

如果您将路径更改到config或带有选项，请适配路径。

{
    "compilerOptions": {
        "types": ["vite/client"]
    },
    "include": [
        "resources/js/**/*.ts",
        "resources/js/**/*.d.ts",
        "resources/js/**/*.vue", // If you use Vue
        "*.d.ts",
        "vite.config.ts"
    ]
}

{
    "compilerOptions": {
        "target": "esnext",
        "jsx": "preserve",
        "module": "ESNext",
        "moduleResolution": "Node",
        "paths": {
            "@/*": ["./resources/js/*"],
            "@": ["./resources/js"],
            "~": ["./"],
            "~/*": ["./*"]
        },
        "types": ["vite/client"],
        "allowJs": true,
        "strict": true,
        "noEmit": true,
        "esModuleInterop": true,
        "forceConsistentCasingInFileNames": true,
        "isolatedModules": true,
        "skipLibCheck": true
    },
    "include": [
        "resources/js/**/*.ts",
        "resources/js/**/*.d.ts",
        "resources/js/**/*.vue",
        "*.d.ts",
        "vite.config.ts"
    ]
}

关于NPM包 @kiwilan/typescriptable-laravel

NPM包是可选的，您可以使用仅PHP的包。它是为 Vite 和 laravel-vite-plugin 以及 Inertia（仅适用于 Vue 3）构建的。它支持SSR。

此包添加了一些辅助器，用于在Vue组件中使用TypeScript完全类型化的Laravel路由，以及一些与Vue一起使用的可组合组件。安装此包的最佳设置是使用 Jetstream，一个Laravel启动套件，并且需要 tightenco/ziggy。

请在此处阅读完整文档：@kiwilan/typescriptable-laravel。

配置

您可以发布配置文件

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

以下是一个配置示例：config/typescriptable.php。

重要

您可以使用 artisan 或 parser 配置 engine.eloquent 以更改解析器引擎。默认情况下，它使用与 model:show 命令一起的 artisan 命令。由于 artisan 引擎比 parser 引擎更可靠且更快，因此它是默认引擎。与MongoDB一起，引擎无关紧要，因为MongoDB数据库不能像关系数据库那样被解析。

用法

php artisan typescriptable

带有选项

• --M|models: 生成模型类型。
• --R|routes: 生成路由类型。
• --S|settings: 生成设置类型。

Eloquent模型

使用所有模型类型生成 resources/js/types-eloquent.d.ts 文件。

php artisan typescriptable:eloquent

可以在 config/typescriptable.php 文件中设置选项。

Spatie设置

如果您使用 spatie/laravel-settings，您可以生成包含所有设置类型的 resources/js/types-settings.d.ts 文件。

php artisan typescriptable:settings

可以在 config/typescriptable.php 文件中设置选项。

路由

生成包含所有路由类型的 resources/js/types-routes.d.ts 文件以及用于路由引用的 resources/js/routes.ts。

php artisan typescriptable:routes

可以在 config/typescriptable.php 文件中设置选项。

Eloquent列表

使用 eloquent:list 命令显示所有Eloquent模型。

php artisan eloquent:list

模型是从 config/typescriptable.php 中的 eloquent.directory 变量解析的。

高级

MongoDB

kiwilan/typescriptable-laravel 支持 MongoDB 和 mongodb/laravel-mongodb。由于MongoDB的结构，TypeScript转换与SQL数据库不同，精度较低。如果您想提高它，您可以添加 一个问题。

数据库不会像与关系数据库那样进行解析。该包将解析 key、fillable 和 hidden 以获取所有字段。如果某些字段缺失，您可以 手动覆盖它们。所有关系和访问器都受支持。

数据库前缀

您可以在 config/database.php 文件中使用 prefix 变量。

'connections' => [
    'YOUR_DATABASE_CONNECTION' => [
        'prefix' => '',
    ],
],

覆盖模型

kiwilan/typescriptable-laravel 将覆盖许多情况，但如果您想覆盖某些模型，您可以创建一个类似于 resources/js/types/index.ts 的类型并扩展 Model 类型。

export interface BookAdvanced extends App.Models.Book {
    pivot: {
        created_at: string;
        updated_at: string;
    };
}

当您需要使用高级类型时，可以在代码中导入自定义类型。

<script setup lang="ts">
import { ref } from "vue";
import { BookAdvanced } from "@/types";

const book = ref<BookAdvanced>();
</script>

打印PHP类

如果您想打印PHP类，可以使用 --php-path 选项与 php artisan typescriptable:eloquent 命令。

php artisan typescriptable:eloquent --php-path=app/print

这些类将根据Eloquent模型生成为真实的PHP类。

示例

查看 示例文档。

测试

创建一个包含您的数据库配置的 .env 文件

cp .env.example .env

然后您可以运行测试

composer test

注意

您可以通过查看 此代码片段 获取Docker数据库配置。

更新日志

请参阅 更新日志 了解最近的变化信息。

鸣谢

• Spatie：为 spatie/package-skeleton-laravel
• Ewilan Riviere：包作者

许可证

MIT许可证（MIT）。请参阅 许可证文件 了解更多信息。