vix / syntra
Syntra — unified CLI for PHP project health checks, code refactoring, and extensible framework integrations.
Requires
- php: ^8.2
- nikic/php-parser: ^4.15
- psr/container: ^2.0
- symfony/console: ^5.4 || ^6.0 || ^7.0
- symfony/filesystem: ^5.4 || ^6.0 || ^7.0
- symfony/process: ^5.4 || ^6.0 || ^7.0
Requires (Dev)
- peckphp/peck: ^0.1.3
- phpstan/phpstan: ^2.1
- phpunit/phpunit: ^10.5
Suggests
- friendsofphp/php-cs-fixer: Required for code style fixes
- phpstan/phpstan: Required for static analysis
- phpunit/phpunit: Required for running tests
- rector/rector: Required for code refactoring
- dev-main
- 1.5.5
- 1.5.0
- 1.0.0
- dev-codex/fix-refactor-all-command-path-issue
- dev-codex/introduce-reusable-component-for-file-scanning
- dev-codex/add-branch-alias-and-funding-information
- dev-codex/generate-php-docs-for-methods
- dev-codex/add-command-to-rewrite-dispatch-syntax
- dev-codex/implement-laravel-rule-to-replace-redirect
This package is auto-updated.
Last update: 2025-07-25 21:33:15 UTC
README
Syntra is a unified CLI tool for PHP projects, designed to streamline health checks, code refactoring, and framework integrations. It automates routine tasks, enforces coding standards, and provides a modular architecture for extensibility.
🚀 Features
- Health Checks: Verify project stability with Composer, PHPStan, PHPUnit, and security audits.
- Code Refactoring: Automatically fix code with custom refactorers, Rector, and PHP-CS-Fixer.
- Static Analysis: Detect todos, long methods, and unsafe debug calls.
- Typo Detection: Spot misspellings in files and identifiers using Aspell (via Peck). Requires the
aspell
binary. - Framework Support: Built-in tooling for Yii (Laravel, Symfony planned).
- Extensibility: Generate and register new commands using stubs.
- In-Memory Caching: Reuses previously scanned file lists for faster repeated command execution.
- Cache Reset: Call
Cache::clearAll()
to manually reset cached file lists when working with temporary directories or tests. - No-Cache Option: Use
--no-cache
to disable caching for a single command run. - Facades: Convenient static access to common services.
- Progress Indicators: Choose between spinner, progress bar, bouncing, or none via the
ProgressIndicatorType
enum. - Output Logging: Use
--output-file=FILE
to save command output.
📦 Installation
composer require --dev vix/syntra
🚀 Quick Start
-
Install Syntra in your PHP project:
composer require --dev vix/syntra
-
Initialize Syntra:
vendor/bin/syntra general:init
-
Run your first health check:
vendor/bin/syntra health:all
-
Explore available commands:
vendor/bin/syntra list
📋 Usage
Run Syntra commands using the CLI:
vendor/bin/syntra [command] [options]
Basic Examples
# Run health checks on current project vendor/bin/syntra health:all # Find TODO comments in specific directory vendor/bin/syntra analyze:find-todos /path/to/project # Detect typos in your project vendor/bin/syntra analyze:find-typos /path/to/project # Requires `aspell` to be installed and accessible in your PATH # Fix code style with dry-run (preview changes) vendor/bin/syntra refactor:cs-fixer --dry-run # Generate a new command vendor/bin/syntra general:generate-command --group=analyze --cli-name=analyze:custom # Generate route docs and count usage (markdown includes a Refs column) vendor/bin/syntra general:generate-docs --count-refs
Common Options
All commands support these standard options (with an optional [path]
argument to specify the project root):
--dry-run
/-d
: Preview changes without applying them--force
/-f
: Force execution, ignore warnings (refactor commands only)--no-progress
: Disable progress output--no-cache
: Disable file caching (useful for temporary directories)--fail-on-warning
: Return exit code 1 if warnings were found--ci
: CI mode, implies--no-progress
and--fail-on-warning
--output-file=FILE
: Write all command output to FILE--help
/-h
: Display help for the command--quiet
/-q
: Only show errors--verbose
/-v/-vv/-vvv
: Increase verbosity level
⚙️ Commands
🔍 Analyze
Command | Description | Options |
---|---|---|
analyze:find-todos |
Scans project files and collects all TODO, FIXME, @todo, @deprecated comments | [path] , --dry-run , --no-cache |
analyze:find-debug-calls |
Checks that var_dump, dd, print_r, eval, and other calls prohibited in production | [path] , --dry-run , --no-cache |
analyze:find-long-methods |
Finds all methods or functions that exceed a specified number of lines | [path] , --dry-run , --max , --no-cache |
analyze:find-bad-practices |
Detects bad practices in code like magic numbers, nested ternaries | [path] , --dry-run , --no-cache |
analyze:find-typos |
Detects misspellings in filenames and PHP identifiers | [path] , --dry-run , --no-cache |
analyze:strict-types |
Calculates percentage of files declaring strict_types=1 |
[path] , --dry-run , --no-cache |
analyze:all |
Runs all enabled analyze commands sequentially | [path] , --dry-run , --no-cache |
🏥 Health
Command | Description | Options |
---|---|---|
health:composer |
Check Composer dependencies for updates | [path] , --dry-run , --no-cache |
health:php-version |
Validate PHP version requirement in composer.json | [path] , --dry-run , --no-cache |
health:phpstan |
Run PHPStan static analysis | [path] , --dry-run , --no-cache |
health:phpunit |
Execute PHPUnit tests | [path] , --dry-run , --no-cache |
health:security |
Check Composer dependencies for known vulnerabilities | [path] , --dry-run , --no-cache |
health:all |
Run all health checks (composer, phpstan, phpunit, security) | [path] , --dry-run , --no-cache |
Additional checks to consider
- Ensure an
.editorconfig
file is present for consistent formatting - Run PHP-CS-Fixer in dry-run mode to enforce PSR-12 style
- Check strict types declarations using
analyze:strict-types
- Verify Composer package licenses match your project policy
🔧 Refactor
Command | Description | Danger Level | Options |
---|---|---|---|
refactor:cs-fixer |
Fixes code style using php-cs-fixer for the selected files | 🟢 LOW | [path] , --dry-run , --no-cache , --force |
refactor:imports |
Fixes incorrect order of docblocks and import statements | 🟢 LOW | [path] , --dry-run , --no-cache , --force |
refactor:var-comments |
Standardizes @var comments to /** @var Type $var */ |
🟢 LOW | [path] , --dry-run , --no-cache , --force |
refactor:docblocks |
Adds a file-level PHPDoc block and class PHPDoc blocks if missing | 🟡 MEDIUM | [path] , --dry-run , --no-cache , --force , --author , --link , --category |
refactor:rector |
Runs Rector for automated refactoring | 🔴 HIGH | [path] , --dry-run , --no-cache , --force |
refactor:all |
Runs all enabled refactor commands sequentially | 🔴 HIGH | [path] , --dry-run , --no-cache , --force , --framework |
🧠 General
Command | Description | Options |
---|---|---|
general:generate-command |
Generates a scaffold for a new Symfony Console command | [path] , --dry-run , --no-cache , --group , --cli-name , --desc |
general:generate-docs |
Scans project controllers and generates a markdown file listing all action routes with their parameters (framework detected automatically) | [path] , --controller-dir , --dry-run , --no-cache , --count-refs |
🧩 Yii Framework Extensions
Command | Description | Danger Level | Options |
---|---|---|---|
yii:all |
Runs all Yii-specific Rector refactorings in sequence | 🟢 LOW | [path] , --dry-run , --force |
yii:find-shortcuts |
Converts Model::find()->where([...])->one()/all() or Model::find()->where([...])->limit(1)->one()/all() into Model::findOne([...]) or findAll([...]) |
🟢 LOW | [path] , --dry-run , --force |
yii:find-one-id |
Replaces Model::findOne(['id' => $id]) with Model::findOne($id) |
🟢 LOW | [path] , --dry-run , --force |
yii:find-all-id |
Replaces Model::findAll(['id' => $id]) with Model::findAll($id) |
🟢 LOW | [path] , --dry-run , --force |
yii:update-shortcut |
Replaces Model::find()->where([...])->update([...]) with Model::updateAll([...], [...]) |
🟢 LOW | [path] , --dry-run , --force |
yii:delete-shortcut |
Replaces Model::find()->where([...])->delete() with Model::deleteAll([...]) |
🟢 LOW | [path] , --dry-run , --force |
yii:can-helpers |
Replaces can()/!can() chains with canAny() , canAll() , cannotAny() , or cannotAll() |
🟢 LOW | [path] , --dry-run , --force |
yii:check-translations |
Checks Yii::t translations: finds missing and unused keys across all categories | N/A | [path] , --dry-run , --lang |
yii:convert-access-chain |
Replaces user->identity->hasAccessChain/hasNoAccessChain with user->canAny/cannotAny |
N/A | [path] , --dry-run , --no-cache |
yii:user-findone-to-identity |
Replaces redundant User::findOne(...) lookups for current user with Yii::$app->user->identity |
N/A | [path] , --dry-run , --no-cache |
🧩 Laravel Framework Extensions
Command | Description | Danger Level | Options |
---|---|---|---|
laravel:all |
Runs all Laravel-specific Rector refactorings in sequence | 🟢 LOW | [path] , --dry-run , --force |
📁 Configuration
Configuration is defined in PHP via syntra.php
, allowing you to enable/disable commands or set options per tool. Example:
The default group names are provided as enum cases in Vix\Syntra\Enums\CommandGroup
.
use Vix\Syntra\Enums\CommandGroup; return [ CommandGroup::REFACTOR->value => [ PhpCsFixerRefactorer::class => [ 'enabled' => true, 'config' => __DIR__ . '/config/php_cs_fixer.php', ], ], CommandGroup::YII->value => [ YiiFindShortcutsCommand::class => true, ], ];
The PHPStan health check reads from config/phpstan.neon
by default, so tweak that file to customize analysis settings.
You can customize the list of debug function names or TODO tags by editing the debug_functions
and todo_tags
arrays for their commands in config.php
.
💡 Tips & Best Practices
Safety First
- Always use
--dry-run
first to preview changes before applying them - Commit your code to version control before running refactor commands
- Start with analysis commands (
analyze:*
) to understand your codebase - Use health checks regularly in your CI/CD pipeline
Workflow Recommendations
-
Daily Health Checks:
# Run everything vendor/bin/syntra health:all # Or individually vendor/bin/syntra health:composer vendor/bin/syntra health:phpstan vendor/bin/syntra health:phpunit vendor/bin/syntra health:security
-
Code Analysis Before Refactoring:
vendor/bin/syntra analyze:find-todos vendor/bin/syntra analyze:find-debug-calls vendor/bin/syntra analyze:find-long-methods vendor/bin/syntra analyze:find-typos # Aspell must be installed
-
Safe Refactoring Order (with
--dry-run
first):# Low risk first vendor/bin/syntra refactor:imports --dry-run vendor/bin/syntra refactor:var-comments --dry-run vendor/bin/syntra refactor:cs-fixer --dry-run # Higher risk last vendor/bin/syntra refactor:docblocks --dry-run vendor/bin/syntra refactor:rector --dry-run
-
Framework-Specific Optimizations (Yii example):
vendor/bin/syntra yii:find-shortcuts --dry-run vendor/bin/syntra yii:find-one-id --dry-run vendor/bin/syntra yii:check-translations
Integration with CI/CD
Add to your CI pipeline:
# .github/workflows/syntra.yml - name: Run Syntra Health Checks run: | vendor/bin/syntra health:all vendor/bin/syntra analyze:find-debug-calls vendor/bin/syntra analyze:find-typos # install aspell via your package manager before running # Fail the pipeline on warnings vendor/bin/syntra health:composer --ci
Running Tests
Execute the PHPUnit test suite locally or in CI:
vendor/bin/phpunit
Release Workflow
-
Ensure the test suite passes:
vendor/bin/phpunit
-
Tag the commit with the new semantic version:
git tag -a vX.Y.Z -m "Release X.Y.Z" git push origin vX.Y.Z
Syntra reads its version from Composer's installed package metadata or the most recent Git tag. Creating a tag is all that's required to set the application version for releases.
🤝 Contributing
Feel free to fork and contribute your own health checks, refactorers, or extensions via pull requests!
📄 License
Syntra is open-source software licensed under the MIT License.