Fractor Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require a9f/fractor
   

   Requires PHP 8.1+ and Laravel 9+ (or standalone CLI usage).

2. First Use Case Run a basic refactoring command (e.g., for PHP files):

   php artisan fractor:refactor --type=php --rule=example-rule
   

   (Note: Default rules aren’t included; see Implementation Patterns for rule integration.)

3. Key Files to Explore

   • config/fractor.php: Core configuration (paths, default rules).
   • app/Console/Commands/FractorCommand.php: CLI entry point.
   • src/RefactorableInterface.php: Contract for refactorable files.

Implementation Patterns

Workflow: Refactoring Files

1. Define a Rule Create a custom rule class (e.g., app/Rules/UpdateNamespaceRule) implementing Fractor\Rule\RuleInterface:

   use Fractor\Rule\RuleInterface;
   use Fractor\File\Refactorable;
   
   class UpdateNamespaceRule implements RuleInterface {
       public function apply(Refactorable $file): void {
           $file->replaceNamespace('Vendor\\NewNamespace');
       }
   }
   

2. Register the Rule Bind it in config/fractor.php under rules or use a service provider:

   Fractor::registerRule('update-namespace', UpdateNamespaceRule::class);
   

3. Execute via Artisan

   php artisan fractor:refactor --type=php --rule=update-namespace --path=app/Models
   

4. Batch Processing Use --batch to process files sequentially with rollback safety:

   php artisan fractor:refactor --batch --dry-run
   

Integration Tips

• Laravel Events: Trigger refactoring after file changes (e.g., filesystem.updated).
• Git Hooks: Integrate with post-checkout or post-merge to auto-fix files.
• Custom File Types: Extend Fractor\File\Refactorable for non-PHP files (e.g., YAML, JSON).

Gotchas and Tips

Pitfalls

1. Rule Dependencies

   • Rules may fail silently if they assume file structure (e.g., use statements). Always test with --dry-run.
   • Fix: Validate file content before applying rules:

     if (!$file->hasNamespace()) return;
     

2. Path Handling

   • Relative paths in --path are resolved from the project root, not the command’s working directory.
   • Tip: Use absolute paths or realpath() for clarity.

3. Stateful Refactoring

   • Avoid rules that modify files in-place without backup (e.g., file_put_contents). Use Refactorable::save() for atomic changes.

4. Performance

   • Large directories (>10K files) may hit memory limits. Use --chunk=100 to process in batches.

Debugging

• Dry Run Mode

  php artisan fractor:refactor --dry-run --verbose
  

  Shows changes without modifying files.

• Log Output Enable debug mode in config/fractor.php:

  'debug' => env('FRACTOR_DEBUG', false),
  

Extension Points

1. Custom File Analyzers Override Fractor\File\Analyzer\AnalyzerInterface to parse domain-specific files (e.g., Blade templates).

2. Pre/Post-Refactor Hooks Bind events in a service provider:

   Fractor::beforeRefactor(function (Refactorable $file) {
       // Validate file before changes
   });
   

3. Rule Validation Add metadata to rules for dynamic filtering:

   class MyRule implements RuleInterface {
       public static function supports(string $filePath): bool {
           return str_ends_with($filePath, '.php') && file_exists($filePath);
       }
   }