kiwilan/typescriptable-laravel

PHP package for Laravel to type Eloquent models, routes, Spatie Settings with autogenerated TypeScript. If you want to use some helpers with Inertia, you can install associated NPM package.

2.0.06 2024-04-15 15:27 UTC

Requires

• php: ^8.2
• illuminate/contracts: ^11.0
• illuminate/database: ^11.0
• illuminate/support: ^11.0
• spatie/laravel-package-tools: ^1.16.3

Requires (Dev)

• larastan/larastan: ^2.8.0
• laravel/pint: ^1.0
• nunomaduro/collision: ^8.0
• orchestra/testbench: ^9.0
• pestphp/pest: ^2.8.1
• pestphp/pest-plugin-laravel: *
• phpstan/extension-installer: ^1.1
• phpstan/phpstan-deprecation-rules: ^1.0
• phpstan/phpstan-phpunit: ^1.0
• spatie/laravel-ray: ^1.26
• vlucas/phpdotenv: ^5.5

MIT

• Kiwilan

• php
• routes
• model
• laravel
• eloquent
• typescript
• ts
• vue
• inertia
• kiwilan
• typescriptable-laravel

README

PHP package for Laravel to type Eloquent models, routes, Spatie Settings with autogenerated TypeScript.

If you want to use some helpers with Inertia, you can install associated NPM package.

Note

• kiwilan/typescriptable-laravel: current PHP package for Laravel.
• @kiwilan/typescriptable-laravel: optional NPM package to use with Vite and Inertia to have some helpers, if you want to know more about, check documentation.
• ziggy is NOT REQUIRED

Features

• 💽 All Laravel databases are supported: MySQL, PostgreSQL, SQLite, SQL Server
• 💬 Generate TS types for Eloquent models
• 👭 Generate TS types for Eloquent relations
• 🪄 Generate TS types for casts (include native enum support)
• 📅 Generate TS types for dates
• 📝 Generate TS types for appends with accessors
  • Partial for Illuminate\Database\Eloquent\Casts\Attribute
  • Old way get*Attribute methods are totally supported
• #️⃣ Generate TS types for counts
• 📖 Can generate pagination TS types for Laravel pagination
• 💾 Can generate simple PHP classes from Eloquent models
• ⚙️ Generate TS types for spatie/laravel-settings
• 🛣 Generate TS types for Laravel routes
  • Scan route parameters
  • For Inertia, you can install @kiwilan/typescriptable-laravel NPM package to use some helpers
• ✅ Multiple commands to generate types
  • php artisan typescriptable for models, settings and routes (safe even if you don't use all)
  • php artisan typescriptable:models for Eloquent models
  • php artisan typescriptable:settings for spatie/laravel-settings
  • php artisan typescriptable:routes for Laravel routes

Roadmap

• Improve Casts\Attribute methods
• Add parser for calebporzio/sushi
• Add parser for spatie/laravel-permission
• Add parser for mongodb

Installation

This version requires PHP 8.2+ and supports Laravel 11.

Warning

Laravel 11 dropped Doctrine DBAL. For previous Laravel versions, you can use 1.12.03 version.

Version	L9	L10	L11
1.12.03	✅	✅	❌
2.0.0	❌	❌	✅

You can install the package via composer:

With Laravel v11+ and PHP 8.2

composer require kiwilan/typescriptable-laravel

With Laravel v9-10 and PHP 8.1

composer require kiwilan/typescriptable-laravel:1.12.03

About TypeScript

If you want to use .d.ts files, you need to use TypeScript in your Laravel project, you have to create a tsconfig.json file and add .d.ts paths in compilerOptions.types:

Note

If you change paths into config or with options, adapt paths.

{
    "compilerOptions": {
        "typeRoots": ["./node_modules/@types", "resources/**/*.d.ts"]
    },
    "include": ["resources/**/*.d.ts"]
}

Configuration

You can publish the config file

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

Usage

php artisan typescriptable

With options:

• --M|models: Generate Models types.
• --R|routes: Generate Routes types.
• --S|settings: Generate Settings types.

Eloquent Models

Generate resources/js/types-models.d.ts file with all models types.

php artisan typescriptable:models

With options:

• --M|models-path: Path to models directory.
• --O|output-path: Path to output.
• --P|php-path: Path to output PHP classes, if null will not print PHP classes.

Spatie Settings

If you use spatie/laravel-settings, you can generate resources/js/types-settings.d.ts file with all settings types.

php artisan typescriptable:settings

With options:

• --S|settings-path: Path to settings directory.
• --O|output-path: Path to output.

Routes

Generate resources/js/types-routes.d.ts file with all routes types and resources/js/routes.ts for routes references.

php artisan typescriptable:routes

With options:

• --R|routes-path: Path to routes directory.
• --O|output-path: Path to output.

Troubleshooting

Database prefix

If you have a database prefix, you can add it in config/typescriptable.php file with DB_PREFIX env variable.

return [
    'database_prefix' => env('DB_PREFIX', ''),
];

Or you can use DB_PREFIX into config/database.php file.

'prefix' => env('DB_PREFIX', ''),

Two configs works.

Override models

kiwilan/typescriptable-laravel will cover many cases, but if you want to override some models, you can just create a type like resources/js/types/index.ts and extends Model type.

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

And you can import custom type in your code when you need to use advanced type.

Examples

Check examples documentation.

Testing

Create a .env file with your database configuration

cp .env.example .env

And you can run tests

composer test

Docker database

Note

To install this on M1 Mac, you need to enable Use Rosetta for x86/amd64 emulation on Apple Silicon in Docker preferences.

To install MySQL with Docker

docker run --name mysql \
    -e MYSQL_ROOT_PASSWORD=root \
    -e MYSQL_USER=testing \
    -e MYSQL_PASSWORD=testing \
    -e MYSQL_DATABASE=testing \
    -p 3306:3306 \
    -d \
    mysql:8.0

To install PostgreSQL with Docker

docker run --name postgresql \
    -e POSTGRES_USER=testing \
    -e POSTGRES_PASSWORD=testing \
    -e POSTGRES_DB=testing \
    -p 5432:5432 \
    -d \
    postgres:15.4

To install SQL Server with Docker

Warning

If you have an error like this: "An invalid attribute was designated on the PDO object", you have to update msphpsql driver. Check laravel/framework#47937 for more information.

docker run -e "ACCEPT_EULA=Y" -e "MSSQL_SA_PASSWORD=12345OHdf%e" \
  -p 1433:1433 \
  --name sqlserver \
  --hostname sqlserver \
  -d \
  mcr.microsoft.com/mssql/server:2022-latest

Changelog

Please see CHANGELOG for more information on what has changed recently.

Credits

• Spatie: for spatie/package-skeleton-laravel
• Ewilan Riviere: Author package

License

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