Specify Laravel Package

Product Decisions This Supports

• Improved Developer Experience (DX) with Modern PHP Support:

  • PHP 8.1 compatibility and PHP 7.4+ requirement align with teams adopting newer PHP versions, reducing legacy tech debt. This makes specify a future-proof choice for projects migrating to modern PHP stacks.
  • GitHub Actions integration in the CI pipeline signals better maintainability and community support, reducing friction for teams evaluating open-source tools.

• Stronger Quality Assurance for PHP 8+ Projects:

  • Enables BDD-style testing in PHP 8.1 applications, where named arguments, union types, and attributes may complicate traditional assertions. specify’s declarative syntax helps offset PHP 8’s learning curve for test authors.
  • Ideal for high-assurance PHP 8+ projects (e.g., fintech, healthcare, or enterprise SaaS) where test clarity is critical for compliance or audits.

• Build vs. Buy Decision (Updated):

  • Buy: Now a clearer "buy" for teams using PHP 8.1+, as the package is actively maintained (GitHub Actions, PHP 8.1 support) and avoids reinventing BDD tooling.
  • Build: Only consider custom solutions if specify lacks deep integration with PHP 8.1+ features (e.g., attribute-based testing) or proprietary BDD extensions (e.g., custom reporters).

• Use Cases (Expanded):

  • PHP 8 Migration Projects: Refactor tests during upgrades to PHP 8.1+ while maintaining BDD readability.
  • Modern API Development: Write self-documenting tests for PHP 8.1 APIs (e.g., using attributes for routing).
  • Legacy System Modernization: Pair with PHP 8.1 upgrades to improve test maintainability in refactored codebases.
  • Team Onboarding: Reduce ramp-up time for junior devs or contractors working on PHP 8+ projects.

When to Consider This Package

• Adopt if:

  • Your team uses PHP 8.1+ and wants BDD-style tests without framework lock-in.
  • You’re migrating to PHP 8.1+ and need test readability to offset complexity (e.g., named arguments, union types).
  • You prioritize open-source tooling with active maintenance (GitHub Actions, PHP 8.1 support).
  • Your project has moderate to high test complexity (e.g., APIs, business logic) and uses PHPUnit/Codeception.

• Look elsewhere if:

  • You’re stuck on PHP 7.3 or lower (package now requires PHP 7.4+).
  • You need advanced BDD features (e.g., step definitions, hooks) beyond specify’s scope (consider Behat or Codeception’s native BDD).
  • Your team resists BDD in favor of unit-test-first or property-based testing (e.g., PHPUnit + Generators).
  • You require PHP 8.1-specific testing features (e.g., attribute-based test discovery) not supported by specify.

How to Pitch It (Stakeholders)

For Executives (Why Care?)

"This update makes specify a future-proof choice for our PHP 8.1+ roadmap. By adopting it, we’ll:

• Reduce technical debt in tests during our PHP 8.1 migration, making them easier to maintain (critical for [Project X]’s 2024 release).
• Improve onboarding for new hires/contractors with self-documenting BDD tests, cutting training time by ~20% (based on similar tools).
• Leverage active open-source maintenance (GitHub Actions, PHP 8.1 support) to avoid vendor lock-in.

Proposal: Pilot specify in [high-impact PHP 8.1 module] to validate test readability gains before full adoption. Budget needed: $0 (open-source) + 1 dev’s time for setup."

Key Ask:

• Approval to test specify in [Module Y] during the PHP 8.1 migration.
• Alignment on BDD as a standard for new PHP 8.1 features.

For Engineering (How It Works)

"specify 2.0.0 is now PHP 8.1-ready and better maintained (GitHub Actions). Here’s how it helps us:

• PHP 8.1 Compatibility: Write clean BDD tests even with named arguments, union types, or attributes.
• Zero Migration Risk: Works with existing PHPUnit/Codeception—no refactoring needed.
• Future-Proof: Active development (unlike stagnant alternatives).

Example (PHP 8.1 + specify):

// Traditional PHPUnit (PHP 8.1)
public function testCreateUserWithEmailAndPassword() {
    $user = User::create(['email' => 'test@example.com', 'password' => 'secret']);
    $this->assertDatabaseHas('users', ['email' => 'test@example.com']);
}

// With `specify` (BDD-style)
public function testUserCreation() {
    specify('creates a user with valid email and password', function () {
        User::create(['email' => 'test@example.com', 'password' => 'secret']);
        $this->seeRecord('users', ['email' => 'test@example.com']);
    });
}

Proposal: Start with [API module] to test adoption. If it reduces test flakiness by >20%, we’ll expand to all PHP 8.1 features."

Key Ask:

• 1 dev to lead the pilot in [Module Z].
• CI tweaks (if needed) for PHP 8.1 test execution.