Getting Started

Minimal Steps to Begin

Installation:
```
composer require --dev jawira/skeleton
```
Add to composer.json under require-dev so it's only installed in development. Pin a version range (e.g. ^2.33) — target names have changed across minor releases (see Gotchas), so an unpinned install can silently break CI scripts.
Discover the current target names first:
```
phing -f vendor/jawira/skeleton/build.xml -l
```
This is the single most important step. Since v2.33.0 the former analysis:* targets have been renamed to check, and -l is the authoritative list for your installed version.

First Use Case: Initialize a .gitignore file:

phing -f vendor/jawira/skeleton/build.xml gitignore -Dforce=true

Key Files:
- vendor/jawira/skeleton/build.xml: the Phing build file with all targets.
- vendor/jawira/skeleton/build.properties: default property values you can override.
- README.md / release notes: quick reference for common targets (phpunit, cs:fix, check, composer:install).

Implementation Patterns

Workflows for Laravel Projects

Code Quality & Linting: Coding-standards targets are unchanged — cs:fix and cs:check still drive PHP-CS-Fixer:
```
phing -f vendor/jawira/skeleton/build.xml cs:check
```
- Laravel Tip: Prefer Laravel Pint for new projects; keep cs:* for repos that already standardised on the package's rule set.
Static Analysis (renamed in v2.33.0): The analysis:* targets are now check targets. Update any CI step or script that referenced analysis:*:
```
# before (≤ v2.32.x)
phing -f vendor/jawira/skeleton/build.xml analysis
# after (v2.33.0+)
phing -f vendor/jawira/skeleton/build.xml check
```
- Pattern: run check in CI and gate merges on it; it aggregates the static-analysis run rather than replacing cs:check.
Testing: Run PHPUnit via Phing as an alternative to php artisan test:
```
phing -f vendor/jawira/skeleton/build.xml phpunit
```
- Pattern: override phpunit.config to point at a Laravel-specific config, or pass --testsuite=Unit.
Dependency Management:
- composer:install / composer:update for installs.
- composer:audit to fail the build on known vulnerabilities.
- New in v2.33.0: a target that only checks outdated dependencies — non-failing, informational. Use it in a scheduled job or a "dependency hygiene" step rather than a gating CI job:
```
phing -f vendor/jawira/skeleton/build.xml composer:outdated
```
- Laravel Integration: keep composer install --prefer-dist for production and centralise flags in build.properties:
```
composer.flags=-n --prefer-dist
```
Docker & Deployment: dc:open wraps Docker Compose for local development:
```
phing -f vendor/jawira/skeleton/build.xml dc:open
```
- Laravel Tip: most teams get more from Laravel Sail; use the Phing target only where Sail isn't in play.
Git Operations: Generate/overwrite .gitignore or .gitattributes with gitignore -Dforce=true, optionally wired into a Composer post-install hook.

Integration Tips

Custom Properties: override defaults in build.properties (e.g. phpunit.config=phpunit.xml.dist).

Artisan Bridge: wrap Artisan in a custom <exec> target:

<target name="laravel:migrate">
    <exec command="php artisan migrate" />
</target>

CI/CD: after upgrading to v2.33.0, grep your workflows for analysis and switch to check:
```
- name: Static analysis
  run: phing -f vendor/jawira/skeleton/build.xml check
```

Gotchas and Tips

Pitfalls

Breaking rename: analysis:* → check (v2.33.0):
- Issue: Any pinned CI step, Composer script, or Makefile calling analysis or analysis:* will fail with an unknown-target error after upgrading.
- Fix: Re-run phing -l after the upgrade, replace analysis* with the corresponding check target, and grep the repo (rg 'analysis' composer.json .github/ Makefile) for stragglers.
check vs cs:check are different things:
- Issue: after the rename it's easy to assume check covers coding standards.
- Fix: treat cs:check (style) and check (static analysis) as separate CI steps; keep both in the pipeline.
Outdated-dependency check is informational:
- Issue: the new "only check outdated dependencies" target reports but is not a security gate; teams sometimes swap it in for composer:audit and lose vulnerability enforcement.
- Fix: keep composer:audit as the failing gate and use the outdated target for scheduled reports/renovation planning.
Phing vs. Laravel Ecosystem:
- Issue: Phing is non-standard in Laravel and can duplicate Artisan/Composer scripts.
- Fix: use the package for generic tooling and file operations; keep Laravel-specific work in Artisan, and consider composer exec for simple tool calls.
Force Overwrites:
- Issue: gitignore defaults to -Dforce=false and will skip existing files.
- Fix: pass -Dforce=true explicitly, or set the default in build.properties for the project.
Docker Compatibility:
- Issue: dc:open assumes Docker Compose v2 (docker compose).
- Fix: verify with docker compose version; use docker-compose syntax in custom targets for legacy hosts.
PHP-CS-Fixer Rules:
- Issue: package defaults may clash with Laravel's .editorconfig or Pint config.
- Fix: override the rules property or narrow cs.path to app,config.

Debugging Tips

List targets after any upgrade: phing -f ... -l — cheapest way to catch a rename like v2.33.0's before it hits CI.

Dry runs / verbose output:

phing -f vendor/jawira/skeleton/build.xml -d check
phing -f vendor/jawira/skeleton/build.xml -v composer:install

Property overrides via CLI to test variants without editing files:

phing -f vendor/jawira/skeleton/build.xml phpunit -Dphpunit.config=custom-phpunit.xml

Target dependencies: aggregated targets (e.g. check) chain others; inspect the <target depends="..."> declarations in build.xml when a nested task fails.

Extension Points

Custom targets: copy build.xml to the project root and add your own, e.g.

<target name="laravel:optimize">
    <exec command="php artisan optimize:clear" />
</target>

Property files: centralise paths and flags in build.properties
```
phpunit.bootstrap=vendor/autoload.php
cs.path=app,config
```

Post-install hooks: auto-generate scaffold files from composer.json

"scripts": {
    "post-install-cmd": [
        "phing -f vendor/jawira/skeleton/build.xml gitignore -Dforce=true"
    ]
}

Git hooks: integrate via CaptainHook (captainhook:install) for pre-commit runs of cs:fix/check.

Key Takeaway: v2.33.0 is a breaking rename — analysis:* is now check — so audit your scripts before upgrading, and keep composer:audit as your security gate while the new outdated-dependency check stays informational. Use jawira/skeleton as a scaffold for tooling and file operations, not a replacement for Laravel/Composer-native workflows.

Skeleton Laravel Package