README

Comprehensive development tooling for Laravel projects. This package provides opinionated, reusable, and production‑ready tooling to standardize code quality, Git workflows, and CI execution across projects.

It is designed to be zero‑config by default, while still allowing opt‑in customization when needed.

Features

🧰 Makefile Tooling — Reusable Make targets for code quality, testing, CI, and Git operations
🧽 Laravel Pint — Opinionated code style enforcement with shared configuration
🧮 PHPStan — Static analysis with curated rules and sensible defaults
🧹 Git Helpers — Branch update and cleanup automation
🪝 Git Hooks (Optional) — Versioned hooks enforcing quality gates locally
🎼 Composer Normalize (Optional) — Consistent composer.json formatting
⚙️ Artisan Utility Commands — Laravel commands for common development tasks

Installation

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

Quick Start

Publish the configuration to your Laravel project:

php artisan dev-tools:publish

This creates:

Makefile — Includes all shared Make targets
pint.json — Symlink to vendor/zairakai/laravel-dev-tools/config/pint/pint.json
phpstan.neon — Symlink to vendor/zairakai/laravel-dev-tools/phpstan.neon
.editorconfig — Symlink to vendor/zairakai/laravel-dev-tools/.editorconfig
config/enlightn.php — Copied from stub (uses Laravel helpers, cannot be symlinked)

Why symlinks?
They keep your project automatically up‑to‑date with package improvements while remaining fully visible to your IDE.

Make Targets Reference

📚 Help

Target	Description
`make help`	Display all available targets with descriptions

🎨 Code Style

Target	Description
`make pint`	Dry‑run Pint on dirty files only
`make pint-fix`	Fix code style on dirty files

🔍 Static Analysis

Target	Description
`make analyse`	Run PHPStan static analysis
`make analyse-baseline`	Generate or refresh PHPStan baseline

🧪 Testing

Target	Description
`make test`	Run all tests (no coverage)
`make test-unit`	Run unit tests only
`make test-feature`	Run feature tests only
`make test-coverage`	Run tests with coverage report
`make test-ci`	Run tests in CI mode (strict)

🔒 Security & Performance (Enlightn)

Target	Description
`make enlightn`	Run security and performance analysis
`make enlightn-ci`	Run Enlightn in CI mode (strict)

Note: Enlightn requires a full Laravel application environment. It will gracefully exit with an informative message when run in package context. Install with: composer require --dev enlightn/enlightn

✅ Quality Gates

Target	Description
`make quality`	Run CI-level quality checks (code style + static analysis)
`make quality-full`	Run ALL quality checks (style + analysis + rector + phpmd + insights)
`make ci`	Alias for `quality` (CI-compatible)

🎼 Composer

Target	Description
`make composer-install`	Install Composer dependencies
`make composer-update`	Update Composer dependencies
`make composer-normalize`	Validate and fix `composer.json` formatting
`make composer-validate`	Validate `composer.json` schema

🛠️ Utilities

Target	Description
`make doctor`	Run environment diagnostics
`make git-update`	Fast‑forward all local branches tracking a remote
`make git-cleanup`	Remove local branches with deleted remotes

Artisan Commands

`dev-tools:publish`

Publish configuration files and optional tooling to your project root.

# Interactive (recommended)
php artisan dev-tools:publish

# Overwrite existing files
php artisan dev-tools:publish --force

# Install Git hooks
php artisan dev-tools:publish --with-hooks

# Install composer-normalize without prompt
php artisan dev-tools:publish --with-normalize --no-interaction

What gets created:

Makefile
pint.json (symlink or copy)
phpstan.neon (symlink or copy)
.githooks/ directory (optional)

Windows note: If symlinks are not supported, files are copied instead.

Git Hooks (Optional)

This package can install versioned Git hooks stored in .githooks/ and enabled via core.hooksPath.

Hooks are fully versioned and can be reviewed like any other source file.

Installed hooks:

pre-commit — Pint on staged files only
commit-msg — Conventional commit message validation
pre-push — Full quality gate (Pint + PHPStan)
prepare-commit-msg — Auto‑prefix commit messages from branch name

To disable a hook:

mv .githooks/pre-push .githooks/pre-push.disabled

Composer Normalize (Optional)

The package can optionally install ergebnis/composer-normalize to ensure consistent composer.json formatting across teams.

Benefits:

Deterministic key ordering
Cleaner diffs
Enforced schema compliance

Once installed, available Make target:

make composer-normalize
make composer-validate

Configuration Details

Symlinked Configuration

By default, configs are symlinked to the vendor package:

pint.json → vendor/zairakai/laravel-dev-tools/config/pint/pint.json
phpstan.neon → vendor/zairakai/laravel-dev-tools/phpstan.neon

Note: config/enlightn.php is copied (not symlinked) because it uses Laravel helpers incompatible with symlinking.

Benefits:

Always up‑to‑date
IDE‑friendly
No configuration drift
Zero maintenance

Override Configuration (Optional)

Delete the symlink and create your own file to customize rules.

Custom Pint Rules

rm pint.json
cat > pint.json <<'EOF'
{
  "preset": "laravel"
}
EOF

Custom PHPStan Configuration

rm phpstan.neon
cat > phpstan.neon <<'EOF'
includes:
  - vendor/zairakai/laravel-dev-tools/phpstan.neon

parameters:
  paths:
    - app
    - tests
EOF

CI/CD Integration

GitLab CI

code-quality:
  stage: test
  script:
    - composer install --no-interaction --prefer-dist
    - make quality

GitHub Actions

- name: Code Quality
  run: |
    composer install --no-interaction --prefer-dist
    make quality

Requirements

PHP 8.3, 8.4
Laravel 11.x, 12.x
GNU Make (or compatible)

Compatibility

This package is designed for library and application development. It includes:

Minimal illuminate dependencies (console, support, database, filesystem)
Laravel Pint and PHPStan as dev dependencies
No framework-specific requirements (works in non-Laravel Composer packages)

Documentation

TESTING.md - Testing philosophy, coverage strategy (100%), and manual testing scenarios
CONTRIBUTING.md - Contribution guidelines and workflow
SECURITY.md - Security policies and vulnerability reporting
CODE_OF_CONDUCT.md - Community standards and expectations

Contributing

This tooling is optimized for Zairakai projects. For changes:

Read the Code Of Conduct
Read the contributing
Test with multiple Laravel projects
Ensure backward compatibility
Follow semantic versioning

Support

Discord - Community discussions (🖥️・Developers role)
Report Issues

License

MIT License - see LICENSE file for details.

Built with ❤️ by the Zairakai team for Laravel + Vue.js developers

zairakai / laravel-dev-tools

Maintainers

Details