#Migrating IDs

Refine is a paid package. To purchase, head to hammerstone.dev.

Every condition has an id that should never change, as we've discussed in other places in the docs.

Every time you create a condition, you're giving it an id:

TextCondition::make('name');

These ids are important because it's how the frontend and backend communicate, but it's also the way that stabilized filters know where to apply their data. When the filter data is stored, it stores the condition ids alongside the data.

Despite your best efforts, there are just going to be times when you have to change a condition's id and you simply can't afford to invalidate all stored filters.

To allow for this, there is a conditionMigrationMap on the filter that you can use to accomplish this.

Let's take the name condition from above and assume that we need to change the id to employee_name for some reason. To make sure all the stored filters still work correctly, we would map name (the old id) to employee_name (the new id) in the conditionMigrationMap:

class EmployeeFilter extends Filter
{
    public function initialQuery()
    {
        return Employee::query();
    }
 
    public function conditions()
    {
        return [
            TextCondition::make('employee_name')
        ];
    }
 
    protected function conditionMigrationMap()
    {
        return [
            // There used to be a condition with an ID of
            // "name", but now it's "employee_name".
            'name' => 'employee_name'
        ];
    }
}

Now anytime data comes in attached to a condition id of name it will transparently be switched to employee_name.