Skip to main content
Property name mapping can be configured with MapOutputName, MapInputName, and MapName attributes. This guide clarifies when to use which name.

​
In the Data Object

class UserData extends Data
{
    public function __construct(
        #[MapName('favorite_song')] // name mapping
        public Lazy|SongData $song,
        #[RequiredWith('song')] // Use the original name in validation rules
        public string $title,
    ) {
    }

    public static function allowedRequestExcept(): ?array
    {
        return [
            'song', // Use the original name
        ];
    }
    
    public function rules(ValidContext $context): array {
        return  [
            'song' => 'required', // Use the original name
        ];
    }
}
In data class definitions, always use the original property name for:
  • Validation rules
  • Allowed request includes/excludes/excepts/only
  • Custom rules methods

​
When Creating a Data Object

You can use either the mapped or original name: 
UserData::from([
    'favorite_song' => ..., // Mapped name works
    'title' => 'some title'
]);

UserData::from([
    'song' => ..., // Original name also works
    'title' => 'some title'
]);

​
When Adding Includes/Excludes

Always use the original name: 
UserData::from(User::first())->except('song'); // Not 'favorite_song'

​
In Request Query Parameters

You can use either the mapped or original name: 
https://spatie.be/my-account?except[]=favorite_song
https://spatie.be/my-account?except[]=song
Both will work.

​
When Validating

Always use the original name: 
$data = [
    'favorite_song' => 123,
    'title' => 'some title',
];

UserData::validate($data);
UserData::getValidationRules($data);

​
Summary Table

ContextUse OriginalUse MappedUse Either
Data class definitions (rules, allowed, etc.)✓
Creating data objects✓
Includes/excludes/except/only✓
Request query parameters✓
Validation✓
When in doubt, use the original property name. It always works in internal contexts.

Build docs developers (and LLMs) love

Get started for freeTalk to us