Skip to content

Add support for expanding dot notation in Data objects and TypeScript transformer#1045

Closed
menthol wants to merge 3 commits intospatie:mainfrom
menthol:main
Closed

Add support for expanding dot notation in Data objects and TypeScript transformer#1045
menthol wants to merge 3 commits intospatie:mainfrom
menthol:main

Conversation

@menthol
Copy link
Copy Markdown

@menthol menthol commented Jun 22, 2025 •
edited
Loading

Description

This PR adds a new feature that allows dot notation in property names to be expanded into nested objects when using Data objects as resources and in TypeScript definitions. This is particularly useful when working with APIs that require or return nested JSON structures.

When using the MapOutputName or MapName attributes with dot notation (e.g., 'user.name'), the package can now generate nested arrays in the JSON output and nested TypeScript interfaces that match the structure of your JSON.

Configuration

The feature is controlled by a new configuration option in config/data.php:

'features' => [
    // Other features...
    'expand_dot_notation' => true, // Defaults to false if not specified
],

Benefits

  • Creates nested JSON structures from flat data objects when using Data objects as resources
  • Generates more intuitive TypeScript interfaces that match nested JSON structures
  • Improves readability and maintainability of both JSON output and TypeScript definitions
  • Makes it easier to work with APIs that expect nested data structures

Examples

Basic Example

class UserData extends Data
{
    public function __construct(
        #[MapOutputName('user.name')]
        public string $name,
        #[MapOutputName('user.profile.bio')]
        public string $userBio,
    ) {
    }
}

With expand_dot_notation enabled, this generates the following JSON:

{
    "user": {
        "name": "John Doe",
        "profile": {
            "bio": "Software developer"
        }
    }
}

Instead of the flat structure:

{
    "user.name": "John Doe",
    "user.profile.bio": "Software developer"
}

JSON:API Specification Example

When working with JSON:API specification, you often have relationships and attributes in a specific structure:

class ArticleData extends Data
{
    public function __construct(
        public int $id,
        #[MapOutputName('attributes.title')]
        public string $title,
        #[MapOutputName('attributes.content')]
        public string $content,
        #[MapOutputName('attributes.published_at')]
        public Carbon $publishedAt,
        #[MapOutputName('relationships.author.data')]
        public UserData $author,
        #[MapOutputName('relationships.comments.data')]
        public DataCollection $comments,
    ) {
    }
}

With expand_dot_notation enabled, this generates a JSON structure that perfectly matches the JSON:API specification:

{
    "id": 1,
    "attributes": {
        "title": "My First Article",
        "content": "This is the content of my article",
        "published_at": "2023-01-15T10:00:00Z"
    },
    "relationships": {
        "author": {
            "data": {
                "id": 1,
                "attributes": {
                  "name": "John Doe"
                }
            }
        },
        "comments": {
            "data": [
                {
                    "id": 1,
                    "attributes": {
                      "body": "Great article!"
                    }
                }
            ]
        }
    }
}

@menthol menthol changed the title Add feature to expand dot notation into nested arrays Add support for expanding dot notation in Data objects and TypeScript transformer Jun 22, 2025
@menthol menthol force-pushed the main branch 4 times, most recently from c80deda to 42f0b31 Compare June 28, 2025 06:32
@rubenvanassche
Copy link
Copy Markdown
Member

rubenvanassche commented Oct 16, 2025

Like the idea, thanks for the PR!

Few remarks:

  • Can you remove the config setting? I'm not that big of a fan of extra config
  • Instead add a property to the existing MapOutputName called $expandDotNotation which is default false (I think in v5 this may be true but I don't want breaking code)
  • Feel free to create a MapDotExpandedOutputName attribute which is basically the MapOutputName attribute but extended and that bool true
  • Also take a look at the EmptyDataResolver since we probably need the logic also over there

If that's all resolved this one can me merged, note myself to check the docs and see how they fit in once merging.

@menthol
Copy link
Copy Markdown
Author

menthol commented Oct 16, 2025

I will update this PR as soon as possible

@menthol menthol force-pushed the main branch 2 times, most recently from 594b7a2 to 208c2a8 Compare October 25, 2025 05:37
@menthol
Copy link
Copy Markdown
Author

menthol commented Oct 25, 2025

@rubenvanassche done

@menthol
Add feature to expand dot notation into nested arrays
e5927f4 
- Introduced `expand_dot_notation` configuration in `data.php`, defaulting to `false`.
- Updated `TransformedDataResolver` to handle dot notation expansion using `Arr::set()`.
- Added documentation on nested data transformation with examples.
- Implemented tests for both enabled and disabled dot notation expansion.
@menthol
Add support for expanding dot notation in TypeScript transformer.
8761909
@menthol
Fix support for expanding dot notation in property mapping.
a23b0d8 
- Introduced `MapDotExpandedName` and `MapDotExpandedOutputName` attributes for handling nested data transformations.
- Updated `MapName`, `MapOutputName`, and name resolver logic to support `expandDotNotation` functionality.
- Modified tests and documentation to reflect new features.
@rubenvanassche
Copy link
Copy Markdown
Member

rubenvanassche commented Apr 10, 2026 •
edited
Loading

Hi @menthol, we're really sorry for leaving this PR hanging for so long and then not merging it, that's not fair to you and the effort you put into this.

In the meantime we've released v3 of typescript-transformer and are phasing out v2 support. The v3 architecture no longer uses Data* classes for building the TypeScript output but works with plain PHP instead, which makes it difficult to fit this in as-is.

The data transformation side (expanding dot notation in output) is a nice feature though. You're welcome to give it another shot targeting v3 of the typescript-transformer, the changes would need to go in the DataClassTransformer/DataClassPropertyProcessor in laravel-typescript-transformer.

A few pointers if you do:

  • We'd prefer keeping just the expandDotNotation parameter on the existing MapOutputName/MapName attributes rather than adding new dedicated attributes
  • The v3 TypeScript expansion would need to happen in DataClassTransformer::getTypeScriptNode() by post-processing the collected properties into nested TypeScriptObject nodes

Going to close this for now. Thanks for the effort, and again sorry for the wait!

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

2 participants

@menthol @rubenvanassche