Merge pull request #77 from kiwilan/develop

v3.1.0

README.md

@@ -12,22 +12,20 @@
 [![laravel][laravel-src]][laravel-href]
 [![npm][npm-version-src]][npm-version-href]
 
-PHP package for Laravel **to type Eloquent models**, **routes**, [**Spatie Settings**](https://github.com/spatie/laravel-settings) with **autogenerated TypeScript**.
+PHP package for Laravel to type [**Eloquent models**](https://laravel.com/docs/master/eloquent), [**routes**](https://laravel.com/docs/master/routing), [**Spatie Settings**](https://github.com/spatie/laravel-settings) with **autogenerated TypeScript**.
 
-If you want to use some helpers with [Inertia](https://inertiajs.com/), you can install [associated NPM package](https://github.com/kiwilan/typescriptable-laravel/blob/main/plugin/README.md).
+If you want to use some helpers with [Inertia](https://inertiajs.com/), you can install [associated NPM package](#about-npm-package-kiwilantypescriptable-laravel).
 
-> [!NOTE]
->
-> -   [`kiwilan/typescriptable-laravel`](https://packagist.org/packages/kiwilan/typescriptable-laravel): current PHP package for [Laravel](https://laravel.com/).
-> -   [`@kiwilan/typescriptable-laravel`](https://github.com/kiwilan/typescriptable-laravel/blob/main/plugin/README.md): optional NPM package to use with [Vite](https://vitejs.dev/) and [Inertia](https://inertiajs.com/) to have some helpers, if you want to know more about, [check documentation](https://github.com/kiwilan/typescriptable-laravel/blob/main/plugin/README.md).
-> -   [`tightenco/ziggy`](https://github.com/tighten/ziggy) is required **only** for [`@kiwilan/typescriptable-laravel`](https://github.com/kiwilan/typescriptable-laravel/blob/main/plugin/README.md) (NPM package)
+![Eldorado Road Both Scene](https://i.giphy.com/1ffOwHDZehVb6JlRid.webp)
+
+> Because you need PHP and Typescript.
 
 ## Features
 
--   💽 All Laravel databases are supported: MySQL, MariaDB, PostgreSQL, SQLite, SQL Server, [MongoDB](https://github.com/mongodb/laravel-mongodb)
+-   💽 Supported Laravel drivers: MySQL, MariaDB, PostgreSQL, SQLite, SQL Server, [MongoDB](https://github.com/mongodb/laravel-mongodb)
 -   💬 Generate TS types for [Eloquent models](https://laravel.com/docs/master/eloquent)
 -   👭 Generate TS types for [Eloquent relations](https://laravel.com/docs/master/eloquent-relationships)
--   🪄 Generate TS types for [`casts`](https://laravel.com/docs/11.x/eloquent-mutators#attribute-casting) (include native `enum` support)
+-   🪄 Generate TS types for [`casts`](https://laravel.com/docs/master/eloquent-mutators#attribute-casting) (include native `enum` support)
 -   📝 Generate TS types for `appends` and all [`accessors`](https://laravel.com/docs/master/eloquent-mutators#accessors-and-mutators)
     -   `Illuminate\Database\Eloquent\Casts\Attribute` with PHPDoc
     -   [`get*Attribute`](https://laravel.com/docs/8.x/eloquent-mutators#defining-an-accessor) methods
@@ -44,10 +42,6 @@ If you want to use some helpers with [Inertia](https://inertiajs.com/), you can
     -   `php artisan typescriptable:settings` for `spatie/laravel-settings`
     -   `php artisan typescriptable:routes` for Laravel routes
 
-![Eldorado Road Both Scene](https://i.giphy.com/1ffOwHDZehVb6JlRid.webp)
-
-> Because you need PHP and Typescript.
-
 ### Roadmap
 
 -   [ ] Add parser for [calebporzio/sushi](https://github.com/calebporzio/sushi)
@@ -146,7 +140,7 @@ Here is a complete `tsconfig.json` file example (you can adapt paths):
 
 NPM package is fully optional, you can use only PHP package. It's built for [Vite](https://vitejs.dev/) with [`laravel-vite-plugin`](https://github.com/laravel/vite-plugin) and [Inertia](https://inertiajs.com/) (only for [Vue 3](https://vuejs.org/)). It's SSR compatible.
 
-This package add some helpers to use **Laravel routes** fully typed with TypeScript into Vue components and some composables to use with Vue.
+This package add some helpers to use **Laravel routes** fully typed with TypeScript into Vue components and some composables to use with Vue. The best setup to install this package is to use [Jetstream](https://jetstream.laravel.com), a Laravel starter kit and [`tightenco/ziggy`](https://github.com/tighten/ziggy) is required.
 
 Read full documentation here: [`@kiwilan/typescriptable-laravel`](https://github.com/kiwilan/typescriptable-laravel/blob/main/plugin/README.md).
 
@@ -158,9 +152,11 @@ You can publish the config file
 php artisan vendor:publish --tag="typescriptable-config"
 ```
 
+A config example is available here: [config/typescriptable.php](https://github.com/kiwilan/typescriptable-laravel/blob/main/config/typescriptable.php).
+
 > [!IMPORTANT]
 >
-> You can configure `engine.eloquent` with `artisan` or `parser` to change parser engine. By default, it uses `artisan` command with [`model:show`](https://blog.laravel.com/laravel-new-model-show-command) command. `artisan` is default engine because it's more reliable and faster than `parser` engine.
+> You can configure `engine.eloquent` with `artisan` or `parser` to change parser engine. By default, it uses `artisan` command with [`model:show`](https://blog.laravel.com/laravel-new-model-show-command) command. `artisan` is default engine because it's more reliable and faster than `parser` engine. With MongoDB, the engine doesn't matter because MongoDB database can't be parsed like relational databases.
 
 ## Usage
 
@@ -182,12 +178,6 @@ Generate `resources/js/types-eloquent.d.ts` file with all models types.
 php artisan typescriptable:eloquent
 ```
 
-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`](https://github.com/spatie/laravel-settings), you can generate `resources/js/types-settings.d.ts` file with all settings types.
@@ -196,11 +186,6 @@ If you use [`spatie/laravel-settings`](https://github.com/spatie/laravel-setting
 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.
@@ -209,22 +194,23 @@ Generate `resources/js/types-routes.d.ts` file with all routes types and `resour
 php artisan typescriptable:routes
 ```
 
-With options:
+### Eloquent listing
 
--   --`R`|`routes-path`: Path to routes directory.
--   --`O`|`output-path`: Path to output.
+Show all Eloquent models with `eloquent:list` command.
 
-## More
+```bash
+php artisan eloquent:list
+```
+
+## Advanced
 
 ### MongoDB
 
 `kiwilan/typescriptable-laravel` supports [MongoDB](https://github.com/mongodb/laravel-mongodb) with `mongodb/laravel-mongodb`. Due to the MongoDB structure, Typescript conversion aren't the same as SQL databases, precision is lower. If you want to improve it, you can add [an issue](https://github.com/kiwilan/typescriptable-laravel/issues/new/choose).
 
 Database isn't parsed like with relational databases. The package will parse `key`, `fillable` and `hidden` to get all fields. If some fields are missing, you can [override them manually](https://github.com/kiwilan/typescriptable-laravel#override-models). All relations and accessors are supported.
 
-### Troubleshooting
-
-#### Database prefix
+### Database prefix
 
 You can use `prefix` variable into `config/database.php` file.
 
@@ -236,7 +222,7 @@ You can use `prefix` variable into `config/database.php` file.
 ],
 ```
 
-#### Override models
+### 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.
 
@@ -260,10 +246,22 @@ const book = ref<BookAdvanced>();
 </script>
 ```
 
+### Print PHP classes
+
+If you want to print PHP classes, you can use `--php-path` option with `php artisan typescriptable:eloquent` command.
+
+```bash
+php artisan typescriptable:eloquent --php-path=app/print
+```
+
+These classes will be generated from Eloquent models as real PHP classes.
+
 ### Examples
 
 Check [examples](docs/examples.md) documentation.
 
+![Example output](tests/docs/example.gif)
+
 ### Testing
 
 Create a `.env` file with your database configuration

composer.json

@@ -1,7 +1,7 @@
 {
   "name": "kiwilan/typescriptable-laravel",
   "description": "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.",
-  "version": "3.0.0",
+  "version": "3.1.0",
   "keywords": [
     "kiwilan",
     "laravel",

config/typescriptable.php

@@ -13,7 +13,7 @@
     ],
 
     /**
-     * The path to the output directory.
+     * The path to the output directory for all the types.
      */
     'output_path' => resource_path('js'),
 
@@ -29,6 +29,8 @@
         /**
          * The path to print PHP classes if you want to convert Models to simple classes.
          * If null will not print PHP classes.
+         *
+         * @example `app_path('Raw')`
          */
         'php_path' => null,
         /**
@@ -51,6 +53,10 @@
          * The path to the settings directory.
          */
         'directory' => app_path('Settings'),
+        /**
+         * Extended class for the settings.
+         */
+        'extends' => 'Spatie\LaravelSettings\Settings',
         /**
          * Settings to skip.
          */
@@ -62,8 +68,22 @@
      * Options for the routes.
      */
     'routes' => [
-        'filename' => 'types-routes.d.ts',
-        'filename_list' => 'routes.ts',
+        /**
+         * The path to the routes types.
+         */
+        'types' => 'types-routes.d.ts',
+        /**
+         * The path to the routes list.
+         */
+        'list' => 'routes.ts',
+        /**
+         * Whether to print the list of routes.
+         */
+        'print_list' => true,
+        /**
+         * Add routes to `window` from list, can be find with `window.Routes`.
+         */
+        'add_to_window' => true,
         /**
          * Use routes `path` instead of `name` for the type name.
          */
@@ -73,19 +93,21 @@
          */
         'skip' => [
             'name' => [
-                '__clockwork.*',
                 'debugbar.*',
                 'horizon.*',
                 'telescope.*',
                 'nova.*',
                 'lighthouse.*',
-                'livewire.*',
-                'ignition.*',
                 'filament.*',
                 'log-viewer.*',
+                'two-factor.*',
             ],
             'path' => [
-                'api/*',
+                '_ignition/*',
+                '__clockwork/*',
+                'clockwork/*',
+                'two-factor-challenge',
+                'livewire',
             ],
         ],
     ],