Development Environment Configuration

Purpose and Scope

This document explains the .gitignore patterns and local development setup for the Maho Composer Plugin project. The configuration supports team collaboration while allowing individual developer customization through excluded IDE files, dependency directories, and local override configurations.

For PHPStan analysis rules and configuration, see Static Analysis with PHPStan. For automated testing workflows, see Continuous Integration Workflows.

Overview

The .gitignore1-12 configuration excludes three categories of files:

1. IDE Files: .idea/ directory prevents PhpStorm workspace conflicts
2. Dependencies: vendor/ directory excludes Composer-managed packages
3. Local Configurations: PHPStan override files enable developer-specific customization

File Structure and Version Control Patterns

Diagram: Version Control Inclusion vs Exclusion Patterns

Sources: .gitignore1-12 composer.json1-29

IDE Configuration Exclusion

The .gitignore1-2 excludes PhpStorm's .idea/ directory to prevent IDE-specific workspace conflicts.

PhpStorm Workspace Directory

# PhpStorm
.idea

The .idea/ directory contains PhpStorm workspace files:

• Code style and inspection profiles
• Run/debug configurations
• File watchers and task definitions
• Editor-specific settings and window layouts
• Project-specific SDK and library mappings

Including .idea/ in version control would cause:

• Merge conflicts from concurrent IDE setting changes
• Forced IDE standardization across team members
• Exposure of local file system paths and credentials
• Repository bloat from binary workspace files

Developers using other IDEs (VS Code, Vim, etc.) create their own workspace files which should also be excluded via local .git/info/exclude entries.

Sources: .gitignore1-2

Dependency Management

The .gitignore4-5 excludes the vendor/ directory containing Composer-managed dependencies.

Composer Vendor Directory

# composer
/vendor

Dependency Installation Process

Diagram: Composer Dependency Resolution and Installation

Declared Dependencies

The composer.json6-15 declares:

Dependency Type	Package	Version Constraint	Purpose
Runtime	composer-plugin-api	^2.1	Plugin system interface
Runtime	composer-runtime-api	^2	Runtime package discovery
Development	phpstan/phpstan	^2.0	Static analysis engine
Development	phpstan/phpstan-strict-rules	^2.0	Additional strict rules
Development	phpstan/phpstan-deprecation-rules	^2.0	Deprecation detection
Development	composer/composer	^2.9.3	Type information for plugin development

The vendor/ directory is excluded because it:

• Contains regenerable files from composer.lock
• Differs between development (includes require-dev) and production environments
• Would add significant repository size (typically 10-50 MB for this project)
• Changes frequently with dependency updates

Sources: .gitignore4-5 composer.json6-15

PHPStan Configuration Pattern

The .gitignore7-12 implements a distributed configuration pattern allowing local PHPStan customization without affecting team baselines:

# PhpStan
.phpstan*.neon
phpstan*.neon
!.phpstan.dist.neon
!.phpstan.dist.*.neon

Configuration File Hierarchy

Diagram: PHPStan Configuration Loading and Override Chain

Sources: .gitignore7-12 .phpstan.dist.neon1-13

Pattern Matching Rules

The .gitignore7-12 patterns control which PHPStan configuration files are tracked:

Pattern	Effect	Matched Files
.phpstan*.neon	Ignore files starting with .phpstan	.phpstan.neon, .phpstan.local.neon, .phpstan.custom.neon
phpstan*.neon	Ignore files starting with phpstan (no leading dot)	phpstan.neon, phpstan.custom.neon, phpstan.local.neon
!.phpstan.dist.neon	Exception: Track this specific file	.phpstan.dist.neon (team baseline configuration)
!.phpstan.dist.*.neon	Exception: Track files with this pattern	.phpstan.dist.custom.neon, .phpstan.dist.ci.neon, .phpstan.dist.dev.neon

The exclamation mark (!) prefix negates the ignore pattern, creating an exception that forces Git to track the file despite matching an earlier ignore pattern.

Local Customization Example

Developers create local overrides without modifying the tracked .phpstan.dist.neon1-13 configuration:

Tracked Team Baseline (.phpstan.dist.neon):

Local Override (.phpstan.neon - ignored):

This pattern ensures:

• CI and all developers share the same baseline from .phpstan.dist.neon
• Local suppressions don't leak into version control
• Developers can experiment with stricter rules without affecting the team
• PHPStan's native includes: mechanism handles configuration merging

Sources: .gitignore7-12 .phpstan.dist.neon1-13

Development Workflow

Diagram: Developer Setup and Configuration Lifecycle

Sources: .gitignore1-12 composer.json10-15 .phpstan.dist.neon1-13

Local Development Best Practices

PHPStan Configuration Guidelines

Always include the team baseline when creating local PHPStan configurations:

Never modify .phpstan.dist.neon for temporary suppressions—this file defines the CI quality baseline and should only change through pull requests that affect the entire team.

Dependency Version Experimentation

Test alternative dependency versions locally without modifying composer.lock:

The vendor/ exclusion in .gitignore5 prevents accidental commits of experimental dependencies.

Cross-IDE Configuration Sharing

While .gitignore2 excludes .idea/, teams can share IDE-agnostic configuration:

1. EditorConfig: Create .editorconfig (tracked) for indent style, line endings, charset
2. Composer Scripts: Define scripts in composer.json16-20 for common tasks (e.g., composer analyse)
3. Documentation: Document recommended PHPStan plugins and IDE extensions in README.md

Sources: .gitignore1-12 composer.json1-29

Configuration Files Summary

File/Directory	Tracked	Purpose	Created By
.phpstan.dist.neon	✓	Team-wide PHPStan baseline	Manual (in repository)
.phpstan.dist.*.neon	✓	Optional team extensions	Manual (in repository)
.phpstan.neon	✗	Developer PHPStan overrides	Developer (optional)
phpstan*.neon	✗	Alternative local configs	Developer (optional)
.idea/	✗	PhpStorm workspace settings	PhpStorm IDE
vendor/	✗	Composer dependencies	composer install
composer.json	✓	Package definition	Manual (in repository)
composer.lock	✓	Locked dependency versions	composer install/update

Sources: .gitignore1-12 composer.json1-29