zairakai / laravel-dev-tools
The unified and centralized development toolkit for Laravel projects - Pint, PHPStan, Rector, PHP Insights, git hooks, and GitLab CI pipeline templates
Package info
gitlab.com/zairakai/php-packages/laravel-dev-tools
Type:composer-plugin
pkg:composer/zairakai/laravel-dev-tools
Requires
- php: ^8.4
- composer-plugin-api: ^2.0
- composer/semver: ^3.6.0
- driftingly/rector-laravel: ^2.7.1
- larastan/larastan: ^3.15.0
- nikic/php-parser: ^5.9
- phpmetrics/phpmetrics: ^2.11
- stanislas-poisson/php-dev-tools: ^2.0
Requires (Dev)
- composer/composer: ^2.11.2
- ergebnis/composer-normalize: ^2.57
- illuminate/console: ^12.0 || ^13.0
- illuminate/database: ^12.0 || ^13.0
- illuminate/filesystem: ^12.0 || ^13.0
- illuminate/support: ^12.0 || ^13.0
- orchestra/testbench: ^10.0 || ^11.3
- phpunit/phpunit: ^12.5.44
Suggests
- enlightn/enlightn: Security and performance analysis (Laravel apps only)
- ergebnis/composer-normalize: Automated composer.json normalization
Provides
None
Conflicts
None
Replaces
None
- dev-main
- 5.3.0
- 5.2.0
- 5.1.0
- 5.0.1
- 5.0.0
- 4.13.0
- 4.12.1
- 4.12.0
- 4.11.0
- 4.10.0
- 4.9.1
- 4.9.0
- 4.8.0
- 4.7.0
- 4.6.0
- 4.5.0
- 4.4.0
- 4.3.2
- 4.3.1
- 4.3.0
- 4.2.0
- 4.1.1
- 4.1.0
- 4.0.0
- 3.0.1
- 3.0.0
- v2.2.0
- v2.1.6
- v2.1.5
- v2.1.4
- v2.1.3
- v2.1.2
- v2.1.1
- v2.1.0
- v2.0.5
- v2.0.4
- v2.0.3
- v2.0.2
- v2.0.1
- v2.0.0
- v1.3.1
- v1.3.0
- v1.2.0
- v1.1.0
- v1.0.0
- dev-develop
This package is auto-updated.
Last update: 2026-11-16 17:48:55 UTC
README
Laravel Dev Tools
One toolkit for the quality of the Laravel projects of Zairakai: Pint, PHPStan, Rector, PHP Insights, markdownlint, Git hooks, make targets and GitLab CI templates. It adapts to standalone packages and to full-stack applications, and it extends the rules of stanislas-poisson/php-dev-tools.
Documentation: laravel-dev-tools-8745c7.gitlab.io (this guide, and the reference of every class, read from the source).
The principle
A project does not copy the rules of the tools. It configures each tool in config/dev-tools/, in a file that extends the rules of the installed version, so the rules are always the ones of this package and the project only writes what is specific to it. That file is committed.
The root of the project holds only what an editor or an extension reads, because they look for the standard names at the root and never in config/. Such a file points at the one of config/dev-tools/, and at nothing else. A tool that no editor reads has no file at the root.
File of config/dev-tools/ | What it does | At the root |
|---|---|---|
phpstan.neon | includes config/library.neon (packages) or config/app.neon (applications), and the baseline. | phpstan.neon: thin, it includes the one of config/dev-tools/. |
.markdownlint.json | Extends config/.markdownlint.json, which extends the one of php-dev-tools. | .markdownlint.json: thin, it extends the one of config/dev-tools/. |
rector.php | Calls RectorBaseConfig::configure(). | None: no extension of an editor reads it, make rector does. |
phpinsights.php | Starts from config/phpinsights.php, then adds the overrides of the project. | None, as for Rector. |
pint.json | The complete file, which the project edits. Pint cannot extend a file: it is generated once from the rules of php-dev-tools and the Laravel layer of this package. | pint.json: a copy. |
phpunit.xml | The configuration of PHPUnit. PHPUnit cannot extend a file, and reads its paths from the folder of the file: the one of config/dev-tools/ goes up two folders (../../src). | phpunit.xml: a copy, with the paths of the root (src). |
.markdownlintignore | The one of php-dev-tools, copied (an ignore file cannot extend another). | .markdownlintignore: a copy. |
baseline.neon | The errors that PHPStan accepts. | None. |
The scripts and the make targets read config/dev-tools/. A copy at the root must say the same as its file of config/dev-tools/: make config-check checks it (it is part of make quality), and SYNC=true make config-check writes the copies again.
Requirements
PHP 8.4 or higher and Laravel 12 or 13.
Install
composer require --dev zairakai/laravel-dev-tools
For full-stack Laravel and Vue projects, add the JS tools, then publish the full-stack setup:
npm install --save-dev @zairakai/js-dev-tools
php artisan dev-tools:publish --fullstack
What the composer plugin does on install
The plugin adds a `setup-dev-tools` script to `composer.json` and runs it after each `composer install` and `composer update` (`scripts/setup-package.sh`). It also synchronizes the `ref` tags of the GitLab CI includes with the installed version. The setup: - creates the `Makefile` (PHP only, or full-stack when `package.json` is found), which delegates to `vendor/zairakai/laravel-dev-tools/tools/make/core.mk`, - creates `.editorconfig`, `config/dev-tools/baseline.neon` (the PHPStan baseline) and the PHPStan configuration of the project (`config/dev-tools/phpstan.neon`, with the thin `phpstan.neon` of the root), - merges the Composer scripts of the package (`composer cs`, `composer analyse`, `composer quality`, `composer spread:fix`...) into `composer.json`, without replacing the ones the project has.Usage
make quality # markdownlint + shellcheck + rector + pint + phpstan + insights
make quality-fast # pint + phpstan + markdownlint (fast CI check)
make quality-fix # markdownlint + rector + layout + pint + composer.json
make spread-fix # ternaries, arrays and calls on several lines (part of quality-fix)
make test # phpunit
make test-all # phpunit + bats
make ci # full pipeline simulation
make doctor # environment diagnostics
PHP Insights only reports: its sniffs are fixed by hand, following the handbook.
What is inside
| Tool | Responsibility | | :--- | :--- | | **Pint** | Laravel code style, on the rules of `php-dev-tools`. | | **PHPStan** | Static analysis at max level with Laravel-aware rules. | | **Rector** | Automated refactoring and modernization. | | **PHP Insights** | Architecture and code quality metrics. | | **PHPMetrics** | Code metrics report. | | **markdownlint** | Consistent documentation. | | **ShellCheck** | Validated shell scripts. | | **Git hooks** | `commit-msg`, `prepare-commit-msg`, `pre-commit` and `pre-push`, read in place by `git config core.hooksPath` (`make install-hooks`). | | **GitLab CI** | Reusable pipeline templates for Laravel apps and packages. | | **Makefile** | The same `make` targets for a package and for an application. | | **Full-stack** | Works with `@zairakai/js-dev-tools` for the JS and TS tools in one workflow. |Configuration examples for each tool
### PHPStan ```yaml includes: - vendor/zairakai/laravel-dev-tools/config/library.neon parameters: paths: - src - tests ``` ### Rector ```phpPublishing the configuration
`dev-tools:publish` writes the configuration of the project in `config/dev-tools/`, then the files that the editor reads at the root (thin files, or copies). A file is never overwritten unless `--force` is given, and a root file that the project already has is kept. `pint.json` is generated. ```bash php artisan dev-tools:publish --publish # everything php artisan dev-tools:publish --publish=quality # a group: quality, style, testing, hooks, governance php artisan dev-tools:publish --publish=pint # a single file: phpstan, baseline, rector, insights, # pint, markdownlint, markdownlintignore, phpunit, gitlab-ci php artisan dev-tools:publish --fullstack # Makefile for PHP and JS ``` `make setup-check` tells which files of the setup are missing or differ from what the package publishes now (it writes nothing, and exits with 1 when a file is missing or different). A file that differs can be a change of the project or a file late on the package: the check shows the difference, you decide what to keep. The setup also gives each project the Makefile, `.editorconfig`, the Composer scripts of the package and the block of the tools in `.gitignore` (the group `setup`: `--publish=setup`, or one key at a time: `makefile`, `editorconfig`, `composer-scripts`, `gitignore`). `make setup-check` and `make setup-update` cover them too. The CI file and the governance files are not checked: a project makes them its own when it publishes them. `make uninstall` (or `bash vendor/zairakai/laravel-dev-tools/scripts/uninstall-package.sh`) removes the files of the setup that are still what the package publishes. A file that the project changed is kept and named; the files of `config/dev-tools/` that were changed go only after confirmation (or `--force`). Everything that is removed is copied first in `.dev-tools-backup//`, under its path from the root, and that folder is kept: `cp -R .dev-tools-backup//. .` puts it all back. `--dry-run` lists the files and removes nothing. `make setup-update` publishes again the files that `make setup-check` reports (missing or different), and only those. A file of the project that it replaces is copied first in `.dev-tools-backup/`: nothing is merged, you put your own settings back from the copy. `DRY_RUN=true make setup-update` lists the files without writing. The governance files (`SECURITY.md`, `CONTRIBUTING.md`, `CODE_OF_CONDUCT.md`) are published only with `--publish=governance`. They are a base to complete: in `SECURITY.md`, the service desk, the security scope and the protection table hold a `TODO`. For a package without Artisan: ```bash bash vendor/zairakai/laravel-dev-tools/scripts/setup-package.sh --publish=gitlab-ci bash vendor/zairakai/laravel-dev-tools/scripts/setup-package.sh --fullstack ```GitLab CI pipeline templates
```yaml include: - project: 'zairakai/php-packages/laravel-dev-tools' ref: 1.0.0 # pin to a release tag for reproducible builds file: '.gitlab/ci/pipeline-php-package.yml' variables: CACHE_KEY: "my-package-v1" PACKAGIST_PACKAGE: "vendor/my-package" ``` Change `file` for the other templates: - `pipeline-php-package.yml`: security, install, validate, quality, test, publish, release, metrics. - `pipeline-laravel-app.yml`: security, install, validate, quality, test, deploy, metrics. - `pipeline-laravel-fullstack.yml`: the PHP and JS pipelines in a single include.Automatic updates
`vendor/bin/update-dependencies` keeps the requirements of a package up to date. The CI template runs it from the jobs `deps:update`, `deps:audit`, `deps:release`, `deps:tag` and `deps:cascade`: - `update`: `composer update -W`, `composer bump`, `composer normalize`, then a signed commit on a branch and a merge request into `develop`, merged when its pipeline succeeds. - `audit`: looks for security advisories in the lock file, one issue per advisory (an alert through ntfy when `NTFY_URL` is set), closed when the advisory is gone. With the group variable `AUTO_FIX=true`, an advisory that is high, critical or of unknown severity starts an update. - `release`: brings `develop` into `main` after an update. - `tag`: tags `main` (signed) only when a published range (`require`) changed. - `cascade`: after the publication on Packagist, starts the update of the projects that use the package. - `policy`: in the repository `dependency-policy`, lifts the entries of `php.json` whose condition is met, with a merge request into `main`. - `policy-check `: fails when the change since `` updates a package of the dependency policy. It only reads, so it runs on GitLab and on GitHub. - `dependabot-sync`: rewrites the ignore rules of `.github/dependabot.yml`, between `# BEGIN dependency-policy (composer)` and `# END dependency-policy (composer)`. It is started by a weekly schedule or by a pipeline with `UPDATE_DEPENDENCIES=true` (with `AUDIT_DEPENDENCIES=true` for a daily audit), and reads `.dependency-update.json` at the root of the project (`tag.when`: `runtime`, `always` or `never`; `tag.level`; `cascade.groups`). The group variables `GITLAB_TOKEN`, `GPG_PRIVATE_KEY_B64`, `RELEASE_SIGNER_NAME` and `RELEASE_SIGNER_EMAIL` are required.Versioning
The package follows [Semantic Versioning](https://semver.org/). **A major version** changes what a project writes or calls: - the names of the thin files of `stubs/`, and where `dev-tools:publish` and `setup-package.sh` write them, - the paths of the base files in `vendor/zairakai/laravel-dev-tools/` that a project includes or extends, - the Composer scripts and the `make` targets that the Git hooks and the pipelines run, - the lowest version of PHP or of Laravel. **A minor version** can add an option, and can add or tighten a rule, or raise the version of a tool: a project that was green can turn red. **A patch version** fixes a defect without changing what the tools ask for.Development
See CONTRIBUTING.md for the workflow and the quality standards. composer install and make install-hooks set the package up.
Statistics
Getting Help
Made with ❤️ by Zairakai