zairakai/laravel-dev-tools

README

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

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: v1.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: v1.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: v1.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

Development

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

Contributing

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

Getting Help

Made with ❤️ by Zairakai