Troubleshooting

CLI Core package issues and fixes.

StubCompiler Issues

Stub not found

Problem: InvalidArgumentException: Stub not found: myStub

Cause: Stub file doesn't exist or wrong path.

Fix: Verify stub exists:

$stubsPath = '/path/to/stubs';
$compiler = new StubCompiler($stubsPath);

// Check available stubs
print_r($compiler->getAvailable());

// Ensure file exists
// Expected: /path/to/stubs/myStub.stub

Tokens not replaced

Problem: Output still contains {{token}} placeholders.

Cause: Token name mismatch or missing replacement.

Fix: Ensure exact token match:

// Stub: namespace {{namespace}};

// Bad: Wrong token name
$compiler->compile('stub', ['ns' => 'App']);

// Good: Correct token name
$compiler->compile('stub', ['namespace' => 'App']);

Empty output

Problem: Compiled content is empty.

Cause: Stub file is empty or unreadable.

Fix: Check file permissions and content:

cat /path/to/stubs/myStub.stub
ls -la /path/to/stubs/

FileWriter Issues

File already exists

Problem: RuntimeException: File already exists: /path/to/file.php

Cause: File exists and overwrite is disabled.

Fix: Enable overwrite or use writeIfNotExists:

// Option 1: Enable overwrite
$writer = new FileWriter(overwrite: true);
$writer->write($path, $content);

// Option 2: Skip existing
$writer->writeIfNotExists($path, $content);

// Option 3: Toggle overwrite
$writer->setOverwrite(true);

Could not create directory

Problem: RuntimeException: Could not create directory: /path/to/dir

Cause: Insufficient permissions or invalid path.

Fix: Check permissions:

# Check parent directory is writable
ls -la /path/to/

# Fix permissions if needed
chmod 755 /path/to/

Could not write file

Problem: RuntimeException: Could not write file: /path/to/file.php

Cause: Disk full, permission denied, or invalid path.

Fix:

# Check disk space
df -h

# Check directory permissions
ls -la /path/to/dir/

# Check for invalid characters in filename
echo $path | cat -v

Generator Issues

Files generated in wrong location

Problem: Files appear in unexpected directory.

Cause: Incorrect basePath or getOutputPath() implementation.

Fix: Debug paths:

class MyGenerator extends Generator
{
    protected function getOutputPath(string $name): string
    {
        $path = $this->basePath . '/app/' . $name . '.php';

        // Debug
        error_log("Output path: {$path}");

        return $path;
    }
}

Name conversion wrong

Problem: my-controller becomes MyController incorrectly.

Cause: Input format assumptions.

Fix: Use built-in helpers:

// These all produce 'MyThing':
$this->toClassName('my-thing');
$this->toClassName('my_thing');
$this->toClassName('myThing');

Windows-Specific Issues

Path separator issues

Problem: Paths don't work on Windows.

Cause: Hardcoded forward slashes.

Fix: Use DIRECTORY_SEPARATOR:

$path = $this->basePath . DIRECTORY_SEPARATOR . 'app' . DIRECTORY_SEPARATOR . 'File.php';

// Or normalize
$path = str_replace(['/', '\\'], DIRECTORY_SEPARATOR, $path);

File permission issues

Problem: dirPermissions parameter ignored on Windows.

Cause: Windows doesn't use Unix permissions.

Fix: This is expected on Windows. File creation should still work.

Related

• wpzylos.com — Full documentation
• Report Issues