Artisan command to convert from mad-web/laravel-enum to webfox/laravel-backed-enums

[Jim-Webfox]

Migrating from mad-web/laravel-enum to webfox/laravel-backed-enums

This document outlines a process for migrating Laravel projects from mad-web/laravel-enum to webfox/laravel-backed-enums.

Motivation:

Many of our projects currently use mad-web/laravel-enum, and we aim to transition them to webfox/laravel-backed-enums for improved functionality and maintainability.

Assumptions:

• Enums are defined using the old class format with const declarations (e.g., const VALUE = 'value';).
• webfox/laravel-backed-enums is already installed in the project (composer require webfox/laravel-backed-enums).
• Enums are located in the app/Enums directory.

Functionality:

This process automates the following changes:

1. Enum Conversion: Converts existing mad-web/laravel-enum classes to webfox/laravel-backed-enums, generating the necessary cases based on the existing const values. For example:

   // Old (mad-web/laravel-enum)
   class Status extends Enum
   {
       const PENDING = 'pending';
       const APPROVED = 'approved';
       const REJECTED = 'rejected';
   }
   
   // New (webfox/laravel-backed-enums)
   enum Status: string implements BackedEnum 
   {
       use IsBackedEnum;
       
       case PENDING = 'pending';
       case APPROVED = 'approved';
       case REJECTED = 'rejected';
   }

2. Usage Updates: Modifies all usages of the enums to be compatible with webfox/laravel-backed-enums. This includes changing how enum values are accessed. For example:

   // Old Usage
   $status = Status::PENDING; // 'pending'
   
   //New Usage
   $status = Status::PENDING->value; // 'pending'

Command

<?php

namespace App\Console\Commands;

use Illuminate\Support\Str;
use Illuminate\Console\Command;
use Illuminate\Support\Facades\File;

class ConvertToBackedEnums extends Command
{
    protected $signature = 'app:convert-enums';
    protected $description = 'Convert mad-web/laravel-enum to webfox/laravel-backed-enums';

    public function handle()
    {
        $enumFiles = File::glob(app_path('Enums/*.php'));

        foreach ($enumFiles as $enumFile) {
            $this->convertEnum($enumFile);
        }

        $this->info('Enums converted successfully!');
    }

    protected function convertEnum(string $enumFile)
    {
        $className = basename($enumFile, '.php');
        $namespace = 'App\Enums';

        $oldEnumContent = file_get_contents($enumFile);

        preg_match_all('/const\s+([a-zA-Z_]+)\s*=\s*(.*?);/s', $oldEnumContent, $matches, PREG_SET_ORDER);

        $newEnumContent = $this->generateBackedEnumStub($namespace, $className);

        $cases = [];
        $type  = 'string';

        foreach ($matches as $match) {
            $caseName = $match[1];
            $value    = trim($match[2], "'");
            if (Str::startsWith($caseName, '__')) {
                continue;
            }
            if (is_numeric($value)) {
                $type = 'int';
            }
            $cases[] = $type === 'string' ? "    case {$caseName} = '{$value}';" : "    case {$caseName} = {$value};";
        }

        $newEnumContent = str_replace('*/', "*/ \n" . implode("\n", $cases), $newEnumContent);
        $newEnumContent = str_replace('{{ type }}', $type, $newEnumContent);

        $newEnumPath = app_path("Enums/{$className}.php");
        File::put($newEnumPath, $newEnumContent);

        $this->replaceEnumUsages($className, $namespace);

    }

    protected function generateBackedEnumStub(string $namespace, string $className): string
    {
        return str_replace(
            ['{{ namespace }}', '{{ class }}'],
            [$namespace, $className],
            file_get_contents(base_path('vendor/webfox/laravel-backed-enums/stubs/laravel-backed-enum.stub'))
        );
    }

    protected function replaceEnumUsages(string $className, string $namespace)
    {
        $oldEnumContent = file_get_contents(app_path("Enums/{$className}.php"));
        preg_match_all('/case\s+([a-zA-Z_]+)\s*=\s*(.*?);/s', $oldEnumContent, $matches, PREG_SET_ORDER);
        $caseNames = collect($matches)->map(function ($match) {
            if (Str::startsWith($match[1], '__')) {
                return null;
            }
            return $match[1];
        })->filter(fn($caseName) => $caseName !== null)->toArray();

        $projectPaths = [
            app_path()
        ];

        $potentialFilesToCheck = [];
        foreach ($projectPaths as $path) {
            $files = File::allFiles($path);
            foreach ($files as $file) {
                $content = file_get_contents($file->getPathname());
                
                $valuesSearch = $className . '::values()';

                $valuesReplace = $className . '::map()';

                if (Str::contains($content, $valuesSearch)) {
                    $content = str_replace($valuesSearch, $valuesReplace, $content);
                }


                if (Str::contains($content, $className)) {

                    $newContent = $content;

                    foreach ($caseNames as $caseName) {
                        $search = $className . '::' . $caseName;

                        $replace = $className . '::' . $caseName . '->value';

                        if (Str::contains($newContent, $search)) {
                            $newContent = str_replace($search, $replace, $newContent);
                        }
                    }

                    foreach ($caseNames as $caseName) {
                        $search = $className . '::' . $caseName . '->getValue()';

                        $replace = $className . '::' . $caseName . '->value';

                        if (Str::contains($newContent, $search)) {
                            $newContent = str_replace($search, $replace, $newContent);
                        }
                    }


                    if ($newContent !== $content) {
                        file_put_contents($file->getPathname(), $newContent);
                        $this->info("Updated {$file->getPathname()}");
                    }
                }

                if (Str::contains($content, "->getValue()") && !Str::contains($content, $className)) {
                    $potentialFilesToCheck[] = $file->getPathname();
                }

            }
        }

        $this->warn("Please check the following files for usage of ->getValue() method:");
        foreach ($potentialFilesToCheck as $file) {
            $this->warn($file);
        }

        $this->newLine(4);
    }
}

 `

[Jim-Webfox]

As I find more aspects that can be changed, I will keep updating this command.