Skip to content

Upgrade Guide ​

Upgrading From 2.8 ​

The release after 2.8 follows more of the code in toArray() and its helpers: variables you write more than once or inside a block, closure parameters, instanceof checks, and collection pipelines on any collection. Many values that published unknown now publish their type, and some types gain or lose | null to match what Laravel sends. Run php artisan ts:publish after you update, and check the changes below against your generated files.

null Added or Dropped ​

  • transform() closures: Laravel calls the closure only for a filled value, so its parameter no longer holds null. $this->transform($this->rating, fn ($rating) => $rating) publishes rating?: string, where it published string | null. The default closure still gets the blank value, null included.
  • A when() condition on a variable: $this->when($score, fn () => $score) drops null from $score in the value, so it publishes string, where it published string | null.
  • whenNotNull() with a closure or a first-class callable: a closure is never null, so Laravel always sends the key and what the closure returns. $this->whenNotNull(fn () => $this->rating) publishes rating: string | null, where it published rating?: string.
  • A collected whenLoaded() value: a value that hands a relation the package can't read to a resource's collection(), such as $this->whenLoaded('branches', CategoryResource::collection(...)) over a branches() method that declares no return type, publishes CategoryResource[], where it published CategoryResource[] | null.
  • A resource built inside map(): a resource built around a relation inside a map() that ends in ->all(), or inside an array a whenLoaded() closure returns, adds | null, as in { profile: ProfileResource | null }[]. It published the bare resource, though Laravel sends null there. See Nullable Relations.
  • Enum resources in a relation closure or a map(): EnumResource::make() or new EnumResource() of a nullable enum column inside a relation closure now adds | null where Laravel sends null: through ->all() or an array, as a resource wrap does. A map() of enum wraps kept as a Collection now publishes X[] where it published (X | null)[]. Laravel sends [] there for a null enum, which X[] doesn't admit, so end the chain with ->all() to get (X | null)[].
  • A column read on a new model: a model you build with new and no attributes reads each column as null, so (new Post)->title publishes string | null, where it published string. A model you fill, copy or create keeps the column's type. See Method Return Types.

Variables, Branches, and Narrowing ​

  • Variables written more than once: a variable you assign again, in sequence or inside an if, a loop, a try or a catch, publishes each value that can reach the read, such as string | number, where it published unknown. A variable a reference can write, or one you change with .=, ++ or another compound assignment, still publishes unknown. A variable assigned inside a block now publishes its type for the reads after it in that block, where it published unknown. See Local Variables and Narrowing.
  • Parameters written inside a block: a closure's or a helper's parameter publishes both the value it was passed and the value a write inside a block assigns, such as string | number, where it published only the value it was passed.
  • Returned variables built in branches: each branch of an if chain, and each loop, keeps its own value for a key, so a key re-set in an if publishes both types, such as number | string, where it published only its last write's type. A whole new array assigned in one branch replaces the keys only there, so a key that only one side holds publishes optional. See Building the Array in a Variable.
  • Arrays built in a variable outside toArray()'s return: a closure in value position, a helper you read as a value, and a local you read as a value now publish the keys their writes set, where they published unknown or unknown[]. A merge closure that returns such a variable now merges its keys.
  • + and unset() with a local: return ['id' => $this->id] + $defaults; now publishes the keys of $defaults too, and unset($data[$key]) now removes the key when $key is a local holding one string literal.
  • instanceof narrowing: an if narrows a variable inside its own block, in an elseif or else the earlier tests rule in, and after a guard nested in a loop or another if, up to the end of that block. A ternary narrows reads through a $this->prop chain in its arm. A resource method that the proven code calls reads the narrowed $this->resource. In a resource collection, an if narrows the items to the paginator it tests. These reads published unknown, null, or every class the variable could hold. See Narrowing With instanceof.
  • preg_match() and literal keys: $matches publishes string[] when the pattern names no group and the call passes no flags, where it published unknown. A literal key read on a variable holding an array shape, such as $row['b'], publishes that key's type.

Collections, Relations, and Query Calls ​

  • map() on any collection: a map() callback's parameter holds the collection's element on a local, a whenLoaded() parameter, getRelation(), a query's get() and collect() too, with or without a type hint. A class type hint types it whatever the collection holds. Reads through it published unknown. A model spread inside the callback, such as [...$comment->toArray(), 'flag' => true], publishes the model the variable holds, where it could name another model or none. See Collection Pipelines.
  • Keyed collections through a local: after keyBy(), sortBy(), filter() or another step that breaks the keys, a map() through a local or ending in ->all() publishes X[] | Record<string, X>, where it published X[].
  • Collections passed to a helper: a helper's parameter holds the collection's model, so $comments->first()?->content in its body publishes string | null, where it published unknown. only() and except() on a variable holding an Eloquent collection publish a list of its models, such as Comment[].
  • Relation calls the query answers: $this->comments()->count(), exists(), first()?->content, and other forwarded calls whose query method declares a return type publish it, such as number and boolean, where they published unknown. An aggregate such as max(), which declares mixed, stays unknown. In a model metadata provider, $model instanceof Post ? $model->comments()->count() : null publishes number | null, where it published null.
  • Relations only a @return declares: a relation method with no native return type whose @return names its relation class, such as @return Ancestors<static, static>, now publishes on the model's interface, and whenLoaded() over it is typed. It was left out. Laravel's Notifiable trait declares readNotifications() and unreadNotifications() this way, so a notifiable model now publishes read_notifications, unread_notifications, and their _count and _exists keys.
  • To-many relation subclasses: a relation whose class extends one of Laravel's to-many relations publishes a list such as Category[], whatever its name. In 2.8 a class name without "Many" published one model. A subclass that loads one model publishes Category | null.
  • Route-bound model relations: in page props, $post->author publishes User and $post->comments Comment[], where they published unknown. See What the Props Expression Can Be.

Other Values Now Typed ​

  • String helpers: Str::upper(), Str::lower() and other Laravel methods whose conditional @return is a string on every branch publish string, where they published unknown.
  • array_filter(): publishes the array you pass it, with its keys. Over a Record<string, string> cast it publishes Record<string, string>. Over a list it publishes string[] | Record<number, string> where the value is sent as-is, since a gap the filter leaves makes JSON write an object. It published unknown.
  • Integer ranges in docblocks: int<0, max>, int<1, 10> and other integer ranges in a @return or @property tag publish number, where they published unknown.
  • A first-class callable in a local: $label = $this->label(...), passed to when(), mergeWhen() or another conditional method, publishes what the call returns.
  • Loop-built keys in an accessor: a model accessor whose getter writes $totals['k'.$index] = $index in a foreach publishes { [key: `k${string}`]: unknown | undefined }, where it published unknown[]. Laravel sends an object, such as {"k1":1,"k2":2}.

Reassigned Values That No Longer Guess ​

  • json_decode() of a reassigned parameter: after $title = json_decode($title);, the parameter holds what json_decode() returns, so return $title; publishes unknown, where it published the parameter's old type, such as string. Any write that always runs replaces the value a parameter was passed, but a model parameter keeps its model past a write the package can't type. See Typing a Variable With @var.
  • find() on a reassigned closure parameter: after $author = $author->comments->find(1);, reads use Comment, so $author?->content publishes string | null, and $author->name publishes unknown, where it read User's name.
  • A merge closure's own variables: a variable a merge() closure assigns is its own, so the closure no longer reads the method's variable of the same name. With $label = 'x'; in toArray() and $label = $this->id; in the closure, the merged label publishes number, where it published string.

New Warnings ​

ts:publish now warns after its summary where it left out a value it can't type and only null or an empty array is left. It also warns where a parameter's writes, a returned array's branches, a merge's two sides or a spread helper's returns join and leave a value out. A class the generation cache serves prints none of them, so run php artisan ts:publish --fresh to see every one. See Values Left Out of a Union.

Upgrading From 2.7 ​

Version 2.8 changes what some #[TsCasts] entries publish, and what a merged model publishes. Numeric keys, list literals, enum cases, values built with new, top-level integer keys, casts, and classes with __toString() also now publish as Laravel sends them, and so do API resources and their collections in Inertia props. Some inferred types change too, where the package guessed a type, read the wrong class, or misread a docblock. Update @tolki/ts, run php artisan ts:publish, and check the changes below against your generated files.

Update @tolki/ts ​

The generated files import types that @tolki/types added in 1.9.0, such as the simple and cursor paginator types and the JSON:API document types. Update @tolki/ts to 1.0.3 or later, which requires that version:

bash
npm install @tolki/ts@latest

If you also install @tolki/types yourself, update it to ^1.9.0.

@tolki/types 1.9.0 types a paginator's from and to as number | null, because Laravel sends null for both on an empty page. Code that uses them as a number needs a null check.

#[TsCasts] Changes ​

Entries Publish Exactly What You Write ​

An entry that names an enum's type, over a key that wraps the enum in EnumResource::make(), used to publish the wrap. For example, 'status' => 'StatusType' published AsEnum<typeof Status>. It now publishes StatusType, as written. To keep the wrap, write it in the entry:

php
#[TsCasts(['status' => 'AsEnum<typeof Status>'])]

The Resource's Own Entries Win Over the Model's ​

An entry on toArray(), or on a method it spreads, now wins over the backing model's entry for the same key, as an entry on the resource class already did. See Overriding Property Types With #[TsCasts] for the full order.

An Entry Without 'optional' Keeps the Key's ? ​

An entry that leaves out 'optional' now keeps the flag the key gets without the entry, so a key can publish optional where it published required:

  • API resources: a resource entry keeps the ? from the model's entry for the same key.
  • Inertia shared data: an entry keeps the ? from the share() docblock's key?:, or, for a key the docblock doesn't name, the ? the package infers, such as for a key share() returns on only some paths. 'optional' also works here now.
  • Inertia page props: an entry on the controller method keeps the prop's own ?. 'optional' also works here now.

To keep such a key required, add 'optional' => false to its entry.

A Merged Model Publishes Its Keys ​

A merge of $this->resource, passed as it is or returned from a closure, now publishes the keys the model's toArray() writes, each optional behind a condition. See Merge Operations.

Interpolated Keys in Arrays Publish an Index Signature ​

A key built from literal text around a variable, written straight into the returned array, a merged array or a nested array, now publishes a template-literal index signature. It was left out before. Beside a key the pattern matches but whose type the signature can't take, tsc reports TS2411, and ts:publish warns and names the key. See Interpolated Keys.

Values Publish as Laravel Sends Them ​

These values now publish what Laravel sends, so some generated types change:

  • Numeric keys in API resources: a resource sends an array whose keys are all numeric as a list. A key whose method returns [1 => 'Basic', 2 => 'Pro'] published { "1": string; "2": string }, and now publishes string[]. A numeric key beside a named key stays, and a resource with $preserveKeys keeps every key. See Methods Declared as a Bare array.
  • Top-level integer keys on a page, shared data, or an event: Inertia merges shared data and page props, and Laravel merges a broadcastWith() payload, with array_merge(), which renumbers integer keys from 0. A top-level 42 => … key therefore publishes as "0" where it published "42", and a numeric #[TsCasts] key there moves the same way. ts:publish warns that you probably meant a string key. Nested keys keep theirs.
  • List literals: a bare array literal such as ['a', 'b'] publishes the list it encodes as, string[], as collect([...]) does. It published Record<string, unknown> before. A list holding an element the package can't type publishes unknown[].
  • Enum cases: a bare case such as 'status' => Status::Active publishes the enum's type alias, StatusType, in resources, page props, shared data, events, and model metadata. In a model metadata provider, such a case used to stop the run.
  • Resources built around null: new UserResource(null) publishes null, the value Laravel sends, where it published UserResource | null.
  • Values built with new: a value built in place publishes what json_encode() writes, so new DateTime() publishes the date object and new RuntimeException('x') publishes Record<string, never>. Both published unknown before. See Method Return Types for the values that stay unknown.

Casts and Serialized Classes ​

These types now follow what Laravel and json_encode() send:

  • decimal:N casts publish string, because Laravel returns a decimal cast as a string on every database. They published number. An uncast decimal or numeric column now follows the driver you publish on: string on MySQL, MariaDB and PostgreSQL, and number on SQLite and SQL Server. See Numbers.
  • timestamp casts publish number, the Unix timestamp Laravel sends, whatever timestamps_as_date is set to. They published string, or Date. A timestamp column without that cast, such as created_at, keeps its date type. See Dates & Times.
  • Classes with __toString() publish their public properties as a shape, or Record<string, never> when they have none, because json_encode() ignores __toString(). They published string. See DTO-Typed Accessors and Casts.
  • Plain DateTime values: a method or accessor that returns a DateTime or DateTimeImmutable publishes { date: string; timezone_type: number; timezone: string }, the object Laravel sends. It published string. Carbon dates still publish string. See Method Return Types.
  • Enum method values publish only what json_encode() writes, so an object's protected, private and hidden values no longer appear in a published enum. See Object and Array Values.

A custom_ts_mappings entry, #[TsCasts] or #[TsType] still overrides any of these types.

Resource Collections and Props ​

API resources and their collections now publish the response Laravel sends, so these types change:

  • A single resource in props: a page prop or shared value that holds one API resource, from new, make() or toResource(), publishes { data: PostResource }, because Laravel sends it under the data key. It published PostResource. Read its fields through data, such as props.post.data.title. After JsonResource::withoutWrapping(), it publishes the bare PostResource. See API Resources in Props.
  • Paginated resource props: a resource collection over simplePaginate() or cursorPaginate() publishes that paginator's own meta, such as JsonResourceSimplePaginator<PostResource> or PostCollection & ResourceCursorPagination. It published the paginate() types, JsonResourcePaginator<PostResource> and PostCollection & ResourcePagination, whose meta holds keys these paginators don't send, such as total. See Paginating Inline in the Render Call.
  • Collections after withoutWrapping(): a named collection with no toArray() of its own, or one whose toArray() returns the collected list, publishes a type alias of its list, such as export type PostCollection = PostResource[];. Code that reads its data key no longer compiles, because Laravel doesn't send that key. A collection that sets its own $wrap keeps it. See The Wrap Key Your App Sets.
  • Collections Laravel guesses: over an empty collection, an argument-less toResourceCollection() skips the guess and sends an empty list. When the guessed collection has its own toArray(), a key publishes UserCollection | never[] and a page prop publishes UserCollection | { data: never[] }, so check for the empty response before you read the collection's own keys. See Nested Resources.
  • JSON:API resources: a JsonApiResource subclass, from Laravel 12.45, publishes the resource object Laravel sends, with id, a type literal, attributes, and optional relationships, links and meta. As a prop, it publishes the JSON:API document, such as JsonApiDocument<PostResource, UserResource>. See JSON:API Resources.

EnumResource Responses ​

An EnumResource response now sends an array whose keys are all numeric but don't count up from 0 in order, such as [1 => 'a', 4 => 'b'] or ['01' => 'Jan'], as an object with those keys. That matches the published enum and its AsEnum type. The response used to send such an array as a list. If your frontend relies on the list, wrap the method's array in array_values(). See Object and Array Values.

A method that returns null for a case, or throws, is now sent as null, which matches the published enum. It was sent as an empty string, "". See Response Shape.

Inferred Types That No Longer Guess ​

These types now follow your code and what Laravel runs, so some generated types change.

Model Keys and Auth IDs ​

  • getKey() on a model the package can't inspect: on an abstract model, it publishes the key type the class declares, joined with the key types of its published subclasses, such as number | string. On a model whose table the package can't read, such as one whose table doesn't exist yet, it publishes the model's own key type. Both published string through $this->resource, and unknown otherwise. Where an abstract model works its key out in code, such as an overridden getKeyType(), it publishes unknown. modelKeys() on a collection of an abstract model lists the same key type, where it published (string | number)[]. See Method Return Types.
  • getKey() on a model built in place: after new, replicate(), replicateQuietly() or newInstance(), it adds | null, such as number | null. It was the bare key type.
  • getKey() with a null $primaryKey: publishes null. It was number.
  • auth()->id() and Auth::id(): for an auth model the package can't inspect, such as one whose table doesn't exist yet or one it can't create an instance of, they publish the model's key type with | null, such as number | null. They published string | null. Where code works out the key of a model the package can't create, they publish unknown. An auth model that overrides getAuthIdentifierName() or getAuthIdentifier() publishes unknown too, where it published its key type with | null. See Inertia.

Reads Through Properties, Helpers, and Variables ​

  • Calls and reads on $this->prop: a call or a property read on a relation or a property, such as $this->author->commentsCount(), types from the class author holds, and $this inside a relation's closure still means the resource. Before, such a read could use the wrong model, the resource's or the closure's. A method both classes declare now publishes the held class's return type, such as string where it published number. A method or column that only the wrong model declared published a type, where Laravel throws or sends null, and now publishes unknown. So does a property read through a to-many relation, such as $this->comments->id, where Laravel throws.
  • $this->resource->m(): publishes what $this->m() does, so a model method declared as a bare array publishes the shape its body returns. It was unknown[].
  • A model's toArray() as a value: $this->author->toArray() and $this->resource->toArray() publish Record<string, unknown>, and a relation's collection publishes Record<string, unknown>[]. They were unknown[]. On a relation, getCasts() publishes Record<string, string>, and getGlobalScopes(), getRelations() and relationsToArray() publish Record<string, unknown>, where each published unknown[].
  • Helper method parameters: a helper's body reads each parameter as its declared type, or as what each call passes when it has none, whether you spread the helper or use its result as a value. A first-class callable passed to whenLoaded(), such as $this->card(...), gets the loaded relation as its argument. These reads published unknown. See Methods Declared as a Bare array.
  • Helpers spread inside a closure: a spread helper's body no longer reads the closure's parameters or the relation it loads. A helper local named like a closure parameter, as in fn ($t) => [...$this->ownId()], keeps its own type, such as number where it published string. A helper parameter reads what the call passes instead of the loaded relation's model, so a column only that model has publishes unknown, where it published that column's type.
  • An enum or model in a helper's array: when you use the helper's result as a value, that value publishes unknown, and the rest of the shape keeps its types. The whole array was left untyped before.
  • Inertia actions and model metadata providers: a typed parameter you read, such as 'id' => $id from int $id, publishes its type, where it published unknown. A nullable model parameter read bare, such as 'post' => $post from ?Post $post = null, publishes Post | null, where it published Post. An abstract Model $model parameter read bare publishes unknown, where it published Model, a type no generated file exports.
  • A reassigned closure or action parameter: once you assign a closure parameter, or an Inertia action's model parameter, a value of another class, the reads after it use that class. They kept using the parameter's model, so a column only that model declares published its type, where it now publishes unknown. See Typing a Variable With @var.
  • More kinds of write: a catch, unset(), static or global now counts as a write to a local variable. So does a by-reference argument that can change the value's form, such as preg_match()'s $matches, settype(), sort() on an array that publishes as an object, or one of your own methods. Such a variable publishes unknown, where it published its first value's type. A by-reference built-in that keeps the value's form, such as sort() on a list or ksort(), keeps the type as before. A copy taken before such a call keeps the type it had. A closure that writes only its own parameter no longer changes an outer variable of the same name. See Local Variables and Narrowing.
  • Optional keys through ??, a ternary, or a default: a key whose value can be a missing conditional value stays optional, as $this->whenLoaded('author') ?? 'none' and $this->when($flag, $this->whenLoaded('author'), 'none') do. They were required. See Passing a Default Argument.

Docblock Tags ​

  • Docblock tags with spaces: a @return or @var tag is read whole, so @return string | null keeps its | null. It was cut at the first space. A $resource property tagged @var ?Post, or tagged with a model from the resource's own namespace that the file doesn't import, now finds its backing model.
  • Docblock shapes: list{int, string} publishes the tuple [number, string], object{a: int} publishes { a: number }, array<'a'|'b', int> publishes { a?: number; b?: number }, and quoted keys and a nested ?array{...} publish as written. Each was misread or ignored, such as list{int, string} read as number. A callable in a @return tag or inside a shape publishes unknown, where it published the first type inside it. A local @var accepts these forms too. See Typing array Casts With @property.
  • A bare class beside its container: @return User[]|User publishes User[] | User. It was User[]. A model enum column typed Status[]|Status publishes AsEnum<typeof Status>[] | AsEnum<typeof Status> in the model's {Model}Resource interface, where it published AsEnum<typeof Status>[].
  • @phpstan-type aliases inside a list or a shape: @property list<Row>|null publishes a list of the alias's shape, where it published unknown[] | null. A promoted constructor property's @var reads an alias too, where it published the property's native type. See Typing JSON Columns With @phpstan-type Aliases.
  • A nullable array column with a nested null: @property array{a: ?int} on a nullable column publishes { a: number | null } | null. It was { a: number | null }.

Generation Cache ​

The generation cache now rebuilds a class when anything it reads changes, such as an enum method a resource calls, a service, a cast, a value object, a helper function or a #[TsEnum] rename. Editing a published template clears the cache too. You can drop any --fresh you added for these. See When a Class Is Rebuilt.

A run limited by an --only-* flag, such as the one the Vite plugin makes on vite build, now keeps the cache of the features it skips. With the cache on, it also keeps those features in the globals and JSON files, as the last run that published them left them.

If you bind your own globals.writer_class or json.writer_class, $runner->enumGenerators and its siblings hold only the features a partial run published. Join each with its retained list to keep the rest, such as $runner->enumGenerators->concat($runner->retainedEnumGenerators), and do the same for models, resources, form requests and broadcast events.

The first run after you update rebuilds the whole cache, as it does after any package update.

Published Templates ​

If you published the package's templates, check these:

  • resource: needs no change. A resource file now imports AsEnum from @tolki/ts only when one of its types uses it, and a published copy does the same.
  • broadcast-event and globals: a copy published before this release prints an event's index signature as a quoted property name instead of a signature. Merge the package's new templates into your copies, as Publishing and Editing Templates describes.

Custom Inertia Analyzers ​

If your app binds its own subclass of InertiaPageAnalyzer or InertiaSharedDataAnalyzer in the container, update its overrides:

  • InertiaPageAnalyzer::buildPageData(), InertiaPageAnalyzer::buildTypeStringWithOverrides() and InertiaSharedDataAnalyzer::normalizeOverrideKeys() take new optional parameters. Add them to your override's signature, or PHP rejects the class.
  • InertiaPageAnalyzer::parseTsCastsFromMethod() and InertiaSharedDataAnalyzer::parseTsCastsFromMiddleware() also return an optionalOverrides map of each entry's 'optional' flag. An override that returns the old shape still works, but its entries' imports and 'optional' flags are ignored.

Custom Resource Transformers ​

If you subclass ResourceTransformer and read the protected castKeysWithImport() method or the $importedCastKeys property, move to the new cast record. Both are gone.

Docblock Helpers ​

If your code calls LaravelTsPublish::extractReturnTypeFromDocblock() or LaravelTsPublish::parseArrayShapeToTsTypes(), check what they return. Both keep their signatures, but they read docblocks as Docblock Tags describes:

  • extractReturnTypeFromDocblock() returns the whole type a tag spells, such as string | null for @return string | null, where it returned string.
  • parseArrayShapeToTsTypes() also reads object{...} shapes and quoted, numeric and hyphenated keys, which it left out, and returns a quoted key without its quotes.

Upgrading to 2.0 From 1.x ​

Version 2 aims to match everything Laravel Wayfinder provides, with a few things done differently.

New in Version 2 ​

Version 2 adds these features:

  • Route functions based on your routes and controllers, including return types for Inertia routes and Vue components, and pagination with the model or resource embedded automatically
  • Form request interfaces
  • Broadcast channels
  • Broadcast event interfaces
  • A Laravel Echo TypeScript augmentation
  • Global Inertia route response parameters
  • A Vite env augmentation file, built from the .env settings prefixed with VITE_
  • A generation cache that makes reruns of the full ts:publish command faster

Each feature's page in these docs shows the TypeScript it generates.

Follow these steps in order:

  1. Update to the v2 package release in Composer.
  2. Republish the config and views with --force. See Configuration Changes and Templates.
  3. Install @tolki/ts and remove @tolki/enum. See New npm Package.
  4. Update your Vite plugin import to @tolki/ts/vite.
  5. Remove your old generated data folder.
  6. Run a fresh publish with php artisan ts:publish --fresh.
  7. Fix the import paths in your app code to match the modular namespace output. See Modular Publishing Only.

Breaking Changes ​

Configuration Changes ​

The version 1 configuration was mostly flat. Version 2 has more features, so each main feature has its own config block.

Most version 1 settings move into their block, and the block name leaves the key: enum_template becomes enums.template, and publish_models becomes models.enabled.

If you published the config file, republish it with the --force flag:

bash
php artisan vendor:publish --tag="ts-publish-config" --force
Full Configuration Update List ​

The tables below map every key from the flat version 1 config to its version 2 block. The recommended path is to republish the config file, then use your project's git diff to find the customizations you need to reapply.

Show the Full Key-by-Key Migration Table
1) Pipeline Class Overrides Moved Under Each Feature Group ​
Old keyNew key
model_collector_classmodels.collector_class
model_generator_classmodels.generator_class
model_transformer_classmodels.transformer_class
model_writer_classmodels.writer_class
enum_collector_classenums.collector_class
enum_generator_classenums.generator_class
enum_transformer_classenums.transformer_class
enum_writer_classenums.writer_class
resource_collector_classresources.collector_class
resource_generator_classresources.generator_class
resource_transformer_classresources.transformer_class
resource_writer_classresources.writer_class
2) Shared Writer Overrides Renamed or Grouped ​
Old keyNew key
barrel_writer_classbarrel_writer_class (same key, still supported as a shared override)
globals_writer_classglobals.writer_class
json_writer_classjson.writer_class
watcher_json_writer_classwatcher.writer_class
3) Template Key Migration ​
Old keyNew key
model_templatemodels.template
enum_templateenums.template
resource_templateresources.template
globals_templateglobals.template

Version 2 also adds template keys for the new features:

New v2 template keys
routes.template
form_requests.template
broadcast_channels.template
broadcast_events.template
broadcast_events.index_template
broadcast_events.echo_augmentation.template
4) Feature Enable Flags Moved From Flat Keys to Grouped Keys ​
Old keyNew key
publish_enumsenums.enabled
publish_modelsmodels.enabled
publish_resourcesresources.enabled
output_globals_fileglobals.enabled
output_json_filejson.enabled
output_collected_files_jsonwatcher.enabled

Version 2 adds these feature toggles:

New v2 feature toggles
routes.enabled
form_requests.enabled
broadcast_channels.enabled
broadcast_events.enabled
inertia.enabled
vite_env.enabled
cache.enabled
5) Namespace and Casing Options Moved Under Feature Groups ​
Old keyNew key
models_namespacemodels.namespace
enums_namespaceenums.namespace
resources_namespaceresources.namespace
relationship_casemodels.relationship_case
enum_method_caseenums.method_case
nullable_relationsmodels.nullable_relations
relation_nullability_mapmodels.relation_nullability_map

The *.namespace keys have no effect in version 2. The globals file names each namespace after the class's PHP namespace, as described in Modular Publishing Only.

6) Include, Exclude, and Additional Directories Migrated Per Feature ​
Old keyNew key
additional_model_directoriesmodels.additional_directories
included_modelsmodels.included
excluded_modelsmodels.excluded
additional_enum_directoriesenums.additional_directories
included_enumsenums.included
excluded_enumsenums.excluded
additional_resource_directoriesresources.additional_directories
included_resourcesresources.included
excluded_resourcesresources.excluded

These new version 2 blocks use the same include, exclude, and additional directories pattern:

New v2 blocks using the same pattern
form_requests.*
broadcast_events.*
7) Enum Metadata and Options Renamed and Regrouped ​
Old keyNew key
enum_metadata_enabledenums.metadata_enabled
enums_use_tolki_packageenums.use_tolki_package
auto_include_enum_methodsenums.auto_include_methods
auto_include_enum_static_methodsenums.auto_include_static_methods
8) Output File Naming and Output Directory Keys Grouped ​
Old keyNew key
global_filenameglobals.filename
global_directoryglobals.output_directory
json_filenamejson.filename
json_output_directoryjson.output_directory
collected_files_json_filenamewatcher.filename
collected_files_json_output_directorywatcher.output_directory
9) Modular Publishing Setting Removed ​
Old keyStatus in v2
modular_publishingRemoved. Modular output is always on.
10) New Top-Level Config Groups in v2 ​

These blocks did not exist in the version 1 config:

New v2 top-level block
cache.*
routes.*
form_requests.*
broadcast_channels.*
broadcast_events.*
inertia.*
vite_env.*

Version 2 also adds this nested block:

New v2 nested block
broadcast_events.echo_augmentation.*
11) Keys That Stayed the Same ​

These keys are still top-level and need no migration:

KeyStatus
run_after_migrateUnchanged (still top-level)
output_to_filesUnchanged (still top-level)
output_directoryUnchanged (still top-level)
namespace_strip_prefixUnchanged (still top-level)
custom_ts_mappingsUnchanged (still top-level)
timestamps_as_dateUnchanged (still top-level)

ts_extends still exists, and version 2 adds sections beyond models and resources:

ts_extends keyv2 note
ts_extends.form_requestsNew section in v2
ts_extends.broadcast_eventsNew section in v2

New npm Package ​

To support functional routing as well as functional enums, install the new @tolki/ts package that goes with this Laravel package:

bash
npm install @tolki/ts

Then uninstall the previous @tolki/enum package. @tolki/ts supports both the version 1 functional enums and the new version 2 functional routing functions:

bash
npm uninstall @tolki/enum

If you use the Vite plugin, update its import path in your Vite config file:

typescript
import { laravelTsPublish } from "@tolki/ts/vite";

The build flag changed too. The Vite plugin from @tolki/enum calls ts:publish with the --only-enums option. The @tolki/ts Vite plugin calls it with --only-functional instead, which skips model and resource interfaces when building assets.

Templates ​

If you published and modified the Blade templates, publish them again and reapply your changes:

bash
php artisan vendor:publish --tag="laravel-ts-publish-views" --force

TsResourceCasts Attribute Removed ​

The TsResourceCasts attribute (AbeTwoThree\LaravelTsPublish\Attributes\TsResourceCasts) has been removed.

Replace every use with TsCasts (AbeTwoThree\LaravelTsPublish\Attributes\TsCasts), which now handles resources, trait methods, models, and form requests the same way. The constructor signature and array format are identical. Only the class name changes:

php
// Before
use AbeTwoThree\LaravelTsPublish\Attributes\TsResourceCasts;
#[TsResourceCasts(['field' => 'string'])]

// After
use AbeTwoThree\LaravelTsPublish\Attributes\TsCasts;
#[TsCasts(['field' => 'string'])]

Pipeline Customization ​

If you changed or extended a collector, generator, transformer, writer, or template in version 1, check that your changes still work with version 2. Then register your classes under the new *_class keys in each feature's block to override the package defaults. See Customizing the Pipeline.

Modular Publishing Only ​

In version 1, the default output was a flat directory, with a setting for modular publishing. Version 2 always publishes in the modular format, and there's no setting for a flat directory. With 7 large groups of features instead of 3, supporting both layouts was error-prone, so version 2 keeps only the modular one.

Update the import paths in your code to match the PHP namespace of each model, enum, and resource. Delete the data folder that holds your previous types, then run php artisan ts:publish --fresh, so the files you see match the version 2 output.

For example, take a model in this PHP namespace:

php
<?php

namespace App\Models\Users;

use Illuminate\Foundation\Auth\User as Authenticatable;

class User extends Authenticatable
{
    //
}

Its import path changes like this:

typescript
// Before
import type { User } from "@data/models";

// After
import type { User } from "@data/app/models/users";

If you use the globals file, its namespaces follow your PHP namespaces too. A version 1 flat-mode type such as models.User becomes app.models.users.User for the model above. See Global Declaration File.

New Command Options and Behavior ​

Version 2 adds more selective ts:publish flags and a cache control:

bash
# Every enabled feature except model and resource interfaces
php artisan ts:publish --only-functional

# One feature at a time
php artisan ts:publish --only-routes
php artisan ts:publish --only-form-requests
php artisan ts:publish --only-broadcast-channels
php artisan ts:publish --only-broadcast-events

# Rebuild the cache
php artisan ts:publish --fresh

These flags follow three rules:

  • You can pass only one --only-* flag per command.
  • --only-functional takes precedence and ignores other --only-* flags.
  • --fresh forces a full regeneration and cache rebuild.

See Limiting a Single Run With Flags for every flag.

New Config Groups in v2 ​

Besides reorganizing the existing model, enum, and resource keys, version 2 adds these config blocks:

  • routes.*
  • form_requests.*
  • broadcast_channels.*
  • broadcast_events.*
  • inertia.*
  • vite_env.*
  • cache.*

If you published a version 1 config, republish it and reapply your customizations to the new block structure.

New Generated Files You Should Expect ​

Depending on which features are enabled, version 2 generates these files beyond enums, models, and resources:

  • Route controller helper files
  • Form request TypeScript interfaces
  • Event parameter TypeScript interfaces
  • broadcast-channels.ts
  • broadcast-events.ts
  • echo-broadcast-events.d.ts, when the Echo augmentation is enabled
  • inertia-config.d.ts
  • vite-env.d.ts, or your configured filename

Make sure your tsconfig.json include patterns cover these generated declaration files.

Generation Cache ​

Version 2 adds a generation cache that skips unchanged classes after the first run:

  • Run php artisan ts:publish --fresh after upgrading.
  • Use --fresh any time you need to guarantee a full rebuild.

See Cache Generation for how the cache works.

Released under the MIT License.