zairakai/laravel-dev-tools

One unified toolkit to set up Laravel quality tooling. Context-aware by default — it adapts to both standalone packages and full-stack applications.

Documentation: laravel-dev-tools-8745c7.gitlab.io

---

Why zairakai/laravel-dev-tools?

Concept	Benefit
Unified Logic	The same quality gate for all your projects. Only the target (package or app) changes, not the rigor.
Concentrated Configs	Centralized, opinionated configurations for PHPStan, Rector, Pint, and PHP Insights. Avoid configuration drift across projects.
Unified Workflow	One set of make commands to rule them all. Whether it's a small package or a full-stack app, the quality gate remains the same.
Auto-Syncing CI	Automatically updates GitLab CI ref tags in your .gitlab-ci.yml when you update the package. Keep your pipelines current without manual effort.
Zero Friction	Automated setup via composer plugin and shell scripts handles the heavy lifting on install.

---

Features

Tool	Responsibility
Pint	Opinionated Laravel code style enforcer.
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.
GitLab CI	Reusable pipeline templates for Laravel apps and packages.
Makefile	Unified make quality, make test, make ci targets (delegated to core).
Full-stack	Integrates with @zairakai/js-dev-tools for JS/TS tooling in one unified workflow.

On install, the composer plugin:

• creates Makefile (PHP-only or full-stack if package.json is detected, delegating to vendor/zairakai/laravel-dev-tools/tools/make/core.mk)
• creates .editorconfig
• creates config/dev-tools/baseline.neon for PHPStan
• adds necessary scripts to composer.json
• registers the automatic GitLab CI ref synchronization

---

Install

composer require --dev zairakai/laravel-dev-tools

For full-stack Laravel + Vue projects:

composer require --dev zairakai/laravel-dev-tools
npm install --save-dev @zairakai/js-dev-tools
php artisan dev-tools:publish --fullstack

---

Usage

make quality        # pint + phpstan + rector + insights + markdownlint + shellcheck
make quality-fast   # pint + phpstan + markdownlint (fast CI check)
make quality-fix    # auto-fix (rector + pint + markdownlint)
make test           # phpunit
make test-coverage  # phpunit with coverage report (requires PCOV or Xdebug)
make test-all       # phpunit + bats
make ci             # full pipeline simulation
make doctor         # environment diagnostics

---

Configuration

The package provides a set of opinionated configurations that you can use as-is or extend in your project.

PHPStan

Create phpstan.neon in your project root:

includes:
    - vendor/zairakai/laravel-dev-tools/config/base.neon

parameters:
    paths:
        - src
        - tests

Rector

Create rector.php in your project root:

<?php

declare(strict_types=1);

use Rector\Config\RectorConfig;

return static function (RectorConfig $rectorConfig): void
{
    $rectorConfig->import(__DIR__ . '/vendor/zairakai/laravel-dev-tools/config/rector.base.php');

    $rectorConfig->paths([
        __DIR__ . '/src',
        __DIR__ . '/tests',
    ]);
};

PHP Insights

Create insights.php in your project root:

<?php

declare(strict_types=1);

return require 'vendor/zairakai/laravel-dev-tools/config/insights.base.php';

---

Publishing configs

Publish config files to config/dev-tools/ (never overwritten unless --force):

# All at once
php artisan dev-tools:publish --publish

# By group
php artisan dev-tools:publish --publish=quality
php artisan dev-tools:publish --publish=style
php artisan dev-tools:publish --publish=testing
php artisan dev-tools:publish --publish=hooks

# Single files
php artisan dev-tools:publish --publish=phpstan
php artisan dev-tools:publish --publish=baseline
php artisan dev-tools:publish --publish=rector
php artisan dev-tools:publish --publish=insights
php artisan dev-tools:publish --publish=pint
php artisan dev-tools:publish --publish=markdownlint
php artisan dev-tools:publish --publish=phpunit
php artisan dev-tools:publish --publish=gitlab-ci

# Full-stack Makefile (PHP + JS)
php artisan dev-tools:publish --fullstack

For standalone packages (without artisan):

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

# Laravel package pipeline
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"

# Laravel application pipeline
include:
  - project: 'zairakai/php-packages/laravel-dev-tools'
    ref: 1.0.0          # pin to a release tag for reproducible builds
    file: '.gitlab/ci/pipeline-laravel-app.yml'

variables:
  CACHE_KEY: "my-app-v1"

# Laravel + Vue full-stack pipeline (PHP + JS in one include)
include:
  - project: 'zairakai/php-packages/laravel-dev-tools'
    ref: 1.0.0          # pin to a release tag for reproducible builds
    file: '.gitlab/ci/pipeline-laravel-fullstack.yml'

variables:
  CACHE_KEY: "my-app-v1"

Available templates:

• pipeline-php-package.yml — security → install → validate → quality → test → publish → release
• pipeline-laravel-app.yml — security → install → validate → quality → test → deploy → metrics
• pipeline-laravel-fullstack.yml — aggregates PHP + JS pipelines via a single include

---

Automatic updates

The tool vendor/bin/update-dependencies (PHP, so nothing to add to the PHP image) keeps the requirements of a package up to date. The CI template runs it from the jobs deps:update, 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.
• 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.

It is started by a weekly schedule or by a pipeline with UPDATE_DEPENDENCIES=true, 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.

Development

make quality        # full quality check
make quality-fast   # fast check (pint + phpstan + markdownlint)
make test           # run tests
make doctor         # environment diagnostics

---

Statistics

Contributing

Contributions are welcome. Please read CONTRIBUTING.md for the project-specific workflow and quality standards.

---

Getting Help

Made with ❤️ by Zairakai