Makefile Laravel Package

Getting Started

Start by installing the package via Composer: composer require --dev fidry/makefile. Then, create a test class (e.g., tests/MakefileTest.php) extending Fidry\Makefile\Test\BaseMakefileTestCase. Implement getMakefilePath() to point to your project’s Makefile, and getExpectedHelpOutput() to define the expected output of make help. To generate the expected output, run make help locally, capture the ANSI-colored output (e.g., make help | pbcopy), and paste it into the test. The test will then validate that future changes to the Makefile preserve conventions like ##-commented targets, correct ordering, and consistent formatting.

Implementation Patterns

• Validate help documentation consistency: Use getExpectedHelpOutput() to enforce that all .PHONY targets have ## comments and appear in a specific order—critical for onboarding and CI gatekeeping.
• Integrate into CI: Add the test to your CI pipeline (phpunit tests/MakefileTest.php) to block PRs that break Makefile conventions (e.g., undocumented targets, duplicate targets, or broken make help formatting).
• Layer convention enforcement with test assertions: Extend BaseMakefileTestCase to add custom checks using the exposed parsedRules (an array of Rule objects), e.g., enforce that test always depends on cs and phpunit.
• Use as a de facto Makefile linter: While the core library only validates make help output, its parser can be reused for ad-hoc checks (e.g., disallow sudo in commands, require vendor: to depend on composer.lock in apps).

Gotchas and Tips

• ANSI escaping is fragile: The help output includes color codes (e.g., \033[33m); copy-paste from actual terminal output to avoid mismatched escapes. Use make help 2>&1 | cat -v to see raw control characters.
• PHP 8.3+ requirement: This package drops support for older PHP versions, so ensure your dev/CI environment meets this—Laravel 9 projects won’t be able to adopt it without upgrading.
• Limited parser robustness: Complex Makefiles (e.g., multiline recipes with shell heredocs, conditionals, or advanced variable expansion) may parse incorrectly or cause test flakiness. Test edge cases early.
• No runtime impact, but high maintenance risk: Since it’s a dev-only dependency with minimal adoption (10 stars), verify maintainer responsiveness before committing long-term. Check GitHub issues and recent commits.
• touch -c artifacts may confuse tests: The README’s vendor target uses touch -c, which creates timestamp files. Ensure tests run in an isolated temp directory or that your CI doesn’t have stale .phar/vendor artifacts causing false positives.