Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/matt-allan/laravel-code-style
Automatic code formatting for Laravel projects
https://github.com/matt-allan/laravel-code-style
code-style formatter laravel php
Last synced: about 1 month ago
JSON representation
Automatic code formatting for Laravel projects
- Host: GitHub
- URL: https://github.com/matt-allan/laravel-code-style
- Owner: matt-allan
- License: mit
- Archived: true
- Created: 2019-04-22T19:44:16.000Z (over 5 years ago)
- Default Branch: main
- Last Pushed: 2022-02-09T15:06:52.000Z (almost 3 years ago)
- Last Synced: 2024-11-16T02:49:48.850Z (about 1 month ago)
- Topics: code-style, formatter, laravel, php
- Language: PHP
- Homepage: https://mattallan.me/posts/automate-code-formatting-for-laravel-projects/
- Size: 103 KB
- Stars: 404
- Watchers: 11
- Forks: 33
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: .github/CONTRIBUTING.md
- License: LICENSE.md
Awesome Lists containing this project
README
## Laravel Code Style
[](http://choosealicense.com/licenses/mit/)
[](https://packagist.org/packages/matt-allan/laravel-code-style)
> ⚠️ This package is no longer maintained. See [Jubeki/laravel-code-style](https://github.com/Jubeki/laravel-code-style) for a maintained fork.
This package provides automatic code style checking and formatting for Laravel applications and packages. Your code is formatted following Laravel's code style guide.
The package adds the [php-cs-fixer](https://github.com/FriendsOfPhp/PHP-CS-Fixer) tool and a community maintained ruleset to your application. The ruleset is a best effort attempt to match the code style the Laravel framework itself uses. Check out an [example](./examples/User.php) to see what the code style looks like.
You might want to use this package if you are writing a Laravel application, package or tutorial and you want to match the framework's code style.
If you are wondering why this package exists you can [read the announcement post](https://mattallan.me/posts/automate-code-formatting-for-laravel-projects/).
## Installation
> ⚠️ These docs are for the latest version. If you are using an older version you can find the docs for previous releases [here](#releases).
Require this package with composer. It is recommended to only require the package for development.
```shell
composer require matt-allan/laravel-code-style --dev
```
The service provider will be automatically registered using [package discovery](https://laravel.com/docs/5.8/packages#package-discovery).
If you don't use auto-discovery you should add the service provider to the providers array in `config/app.php`.
```php
// existing providers...
MattAllan\LaravelCodeStyle\ServiceProvider::class,
```
Once the package is installed you should publish the configuration.
```shell
php artisan vendor:publish --provider="MattAllan\LaravelCodeStyle\ServiceProvider"
```
Publishing the config will add a `.php-cs-fixer.dist.php` configuration file to the root of your project. You may customize this file as needed. The `.php-cs-fixer.dist.php` file should be committed to version control.
A cache file will be written to `.php_cs.cache` in the project root the first time you run the fixer. You should ignore this file so it is not added to your version control system.
```shell
echo '.php_cs.cache' >> .gitignore
```
## Usage
Once the package is installed you can check and fix your code formatting with the `php-cs-fixer` command. The command will be available in Composer's `vendor/bin` directory.
### Fixing
To automatically fix the code style of your project you may use the `php-cs-fixer fix` command.
```shell
vendor/bin/php-cs-fixer fix
```
This will automatically fix the code style of every file in your project.
By default only the file names of every file fixed will be shown. To see a full diff of every change append the `--diff` flag.
```shell
vendor/bin/php-cs-fixer fix --diff
```
### Checking
If you would like to check the formatting without actually altering any files you should use the `fix` command with the `--dry-run` flag.
```shell
vendor/bin/php-cs-fixer fix --dry-run --diff
```
In dry-run mode any violations will [cause the command to return a non-zero exit code](https://github.com/FriendsOfPhp/PHP-CS-Fixer#exit-code). You can use this command to fail a CI build or git commit hook.
### Composer script
To make checking and fixing code style easier for contributors to your project it's recommended to add the commands as a [composer script](https://getcomposer.org/doc/articles/scripts.md).
The following example allows anyone to check the code style by calling `composer check-style` and to fix the code style with `composer fix-style`.
```javascript
{
// ...
"scripts": {
"check-style": "php-cs-fixer fix --dry-run --diff",
"fix-style": "php-cs-fixer fix"
}
}
```
### More Options
For a complete list of options please consult the [php-cs-fixer documentation](https://github.com/FriendsOfPhp/PHP-CS-Fixer#usage).
## Configuration
The default configuration is published as `.php-cs-fixer.dist.php` in the project root. You can customize this file to change options such as the paths searched or the fixes applied.
### Paths
You can change the paths searched for PHP files by chaining method calls onto the `PhpCsFixer\Finder` instance being passed to the `MattAllan\LaravelCodeStyle\Config::setFinder` method.
For example, to search the `examples` directory you would append `->in('examples')`:
```php
setFinder(
PhpCsFixer\Finder::create()
->in(app_path())
// ...
->in('examples')
)
// ...
```
The default paths are setup for a Laravel application. If you are writing a package the path helper functions will not available and you will need to change the paths as necessary, i.e. `PhpCsFixer\Finder::create()->in(__DIR__)`.
For a complete list of options refer to the [Symfony Finder documentation](https://symfony.com/doc/current/components/finder.html).
### Rules
By default only the `@Laravel` preset is enabled. This preset enforces the [PSR-2 standard](https://github.com/php-fig/fig-standards/blob/master/accepted/PSR-2-coding-style-guide.md) as well as nearly 100 other rules such as ordering use statements alphabetically and requiring trailing commas in multiline arrays.
A `@Laravel:risky` preset is also available. The `@Laravel:risky` preset enables rules that may change code behavior. To enable risky rules you need to add the preset and set `isRiskyEnabled` to true.
```php
return (new MattAllan\LaravelCodeStyle\Config())
->setFinder(
// ...
)
->setRules([
'@Laravel' => true,
'@Laravel:risky' => true,
])
->setRiskyAllowed(true);
```
It is possible to override a specific rule from the preset. For example, you could disable the `no_unused_imports` rule like this:
```php
return (new MattAllan\LaravelCodeStyle\Config())
->setFinder(
// ...
)
->setRules([
'@Laravel' => true,
'no_unused_imports' => false,
]);
```
For a complete list of available rules please refer to the [php-cs-fixer documentation](https://github.com/FriendsOfPhp/PHP-CS-Fixer#usage).
## Continuous Integration
To automatically fix the code style when someone opens a pull request or pushes a commit check out [StyleCI](https://styleci.io). StyleCI wrote many of the open source fixer rules this package depends on and StyleCI's Laravel preset is the official definition of Laravel's code style.
## Editor Support
Any editor plugin for php-cs-fixer will work. Check the [php-cs-fixer readme](https://github.com/FriendsOfPhp/PHP-CS-Fixer#helpers) for more info.
## How It Works
Laravel does not publish an official php-cs-fixer ruleset. To create the rule set we compare StyleCI's preset to the available php-cs-fixer rules. In some cases StyleCI is using a rule that is no longer available. For these rules we have to dig through the git history of php-cs-fixer and determine which rule replaced the deprecated rule.
It isn't possible to add your own presets to php-cs-fixer. Instead `PhpCsFixer\Config` is extended to search the rules for our custom presets and merge the rules if they are found.
To ensure the rules stay in sync an automated test formats the entire Laravel framework and compares the results. If an existing Laravel file does not match our rule set the build is failed.
## Releases
When Laravel changes the code style a new major release is created for this package. You will need to edit the version constraint in your `composer.json` to pull in the updated rules. If you would like your code style to match a previous version of Laravel you may pull in an older release of this package.
Laravel | Code Style
:---------|:----------
5.x | [0.4.x](https://github.com/matt-allan/laravel-code-style/tree/0.4.0)
6.x-7.x | [0.5.x](https://github.com/matt-allan/laravel-code-style/tree/0.5.0)
8.x | [0.6.x](https://github.com/matt-allan/laravel-code-style/tree/0.6.0)
## Change log
Please see [CHANGELOG](CHANGELOG.md) for more information on what has changed recently.
## Testing
``` bash
$ composer test
```
## Contributing
Please see [CONTRIBUTING](./.github/CONTRIBUTING.md) for details.
## Credits
- [Matt Allan](https://github.com/matt-allan)
- [All Contributors](../../contributors)
## License
The MIT License (MIT). Please see [License File](LICENSE.md) for more information.