Search by

zairakai / laravel-dev-tools

zairakai

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

Issues

Documentation

Type:composer-plugin

pkg:composer/zairakai/laravel-dev-tools

Fund package maintenance!

Patreon

Other

Statistics

Installs: 858

Dependents: 6

Suggesters: 0

Stars: 0

5.5.0 2026-11-18 22:47 UTC

README

Laravel Dev Tools

Laravel Dev Tools

Main Coverage

GitLab Release Packagist Docs Downloads License

PHP Laravel Static Analysis Code Style

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 doesAt the root
phpstan.neonincludes config/library.neon (packages) or config/app.neon (applications), and the baseline.None: no extension of an editor reads it, make phpstan does.
.markdownlint.jsonExtends config/.markdownlint.json, which extends the one of php-dev-tools..markdownlint.json: thin, it extends the one of config/dev-tools/.
rector.phpCalls RectorBaseConfig::configure().None: no extension of an editor reads it, make rector does.
phpinsights.phpStarts from config/phpinsights.php, then adds the overrides of the project.None, as for Rector.
pint.jsonThe 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.None: the extension of an editor takes its path in its settings (laravel-pint.configPath).
phpunit.xmlThe 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).None: no extension of an editor runs the tests, make test does.
baseline.neonThe errors that PHPStan accepts.None.
phpstan-local.neonA local override of PHPStan, read before phpstan.neon when it exists (scripts/config.sh).None.
phpcs.xmlOptional, and not published: make spread-fix uses config/phpcs.xml of this package (the ternary on several lines). A project that wants more rules writes this file, and starts it with <rule ref="../../vendor/zairakai/laravel-dev-tools/config/phpcs.xml"/>, otherwise it replaces the rule of the package instead of adding to it.None: no extension of an editor reads it, make spread-fix does.
(none).markdownlintignore: the one of php-dev-tools. An ignore file cannot extend another and the tool reads it from the root..markdownlintignore: the only file, at the root.

The scripts and the make targets read config/dev-tools/. make config-check checks that the thin file points there and that no file is where no tool reads it: a phpstan.neon, phpunit.xml, pint.json or rector.php at the root, a .markdownlintignore in config/dev-tools/ (it is part of make quality).

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`), - 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 ```php
Publishing the configuration `dev-tools:publish` writes the configuration of the project in `config/dev-tools/`, then the files that the editor or the tool reads at the root (the thin `.markdownlint.json` and `.markdownlintignore`). 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 check also runs by itself after `composer update`, for information only (it never fails the update): the plugin lists the files that are late and says to run `make setup-update`. 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. In a full-stack project (this package and `@zairakai/js-dev-tools` with `fullstack.mk`), `make setup-check`, `make setup-update` and `make uninstall` run this package's script first, then the JS package's: the JS files of the setup are checked, updated and removed the same way. The two checks run one after the other, so `make -k setup-check` reports both when the first one fails. 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 or critical starts an update (an unknown severity counts as a medium one). - `audit-check `: reads the report of `composer audit --format=json` and fails on an advisory of that same level (high or critical; an unknown severity counts as a medium one, it does not block). `make security-audit` and the job `php:quality:security` use it on every pipeline, so the audit shown in the pipeline and the daily audit that fixes have one level, set in one place. The job is for information: it does not block the pipeline (`allow_failure`). In a full-stack project, the JS audit runs after this one with the same level. - `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

Statistics of laravel-dev-tools

Getting Help

License Security Policy Issues

Made with ❤️ by Zairakai