Php Project Guide

PHP Project Guide

Foundational knowledge for working effectively on any PHP project in PhpStorm. Provides project detection, coding standards, testing patterns, framework guidance, and MCP tool usage.

Quick Start: First Interaction with a PHP Project

Run these steps when encountering a new PHP project for the first time.

1. Detect PHP environment

get_php_project_config()

Returns the configured PHP language level, interpreter details (name, path, local/remote), and runtime information (exact PHP version, loaded extensions, php.ini path, debuggers). Use this to understand the PHP environment before generating code.

2. Identify dependencies and framework

get_composer_dependencies()

This returns all installed packages with exact versions from composer.lock. Use it to determine:

• Framework: laravel/framework, symfony/framework-bundle, or neither
• Test framework: phpunit/phpunit, pestphp/pest, codeception/codeception
• Static analysis: phpstan/phpstan, vimeo/psalm
• Code style: friendsofphp/php-cs-fixer, squizlabs/php_codesniffer

Use the optional nameFilter glob parameter to search for specific packages (e.g., nameFilter: "laravel/*").

3. Route to framework-specific guidance

PhpStorm MCP Tools Quick Reference

Code Analysis

Code Search

Code Intelligence

File Operations

Execution

See references/mcp-tools-reference.md for detailed parameters and usage patterns.

Documentation Lookup

When you need documentation beyond what these references provide:

• Context7 MCP: Use resolve-library-id then query-docs for any PHP framework or library — returns up-to-date docs and code examples
• PHP official docs: https://www.php.net/manual
• PhpStorm help: https://www.jetbrains.com/help/phpstorm/
• phpstorm-stubs: https://github.com/JetBrains/phpstorm-stubs — PHP built-in function signatures and type info

Reference Documents

Composer Dependency Management

Core Files

Common Commands

install vs update

• `composer install`: Reads composer.lock and installs those exact versions. Use in CI/CD and deployment. If no lock file exists, behaves like update.
• `composer update`: Resolves constraints in composer.json, finds newest matching versions, updates composer.lock. Use during development when you want newer versions.

Version Constraints

Recommendation: Use ^ (caret) for most dependencies. It follows semantic versioning and allows safe updates.

Autoloading

When dump-autoload Is Needed

• After adding a new PSR-4 root in composer.json
• After adding files to classmap or files autoload sections
• After manually placing files outside PSR-4 conventions
• Not needed after creating new classes within existing PSR-4 namespaces (the autoloader resolves these dynamically)

Autoload Types

Using get_composer_dependencies

The get_composer_dependencies MCP tool returns all Composer packages installed in the project with their exact versions. It reads from already-indexed composer.lock data — no disk I/O or network calls. In monorepo setups, packages from all composer.json sub-projects are included.

Use the optional nameFilter glob parameter to search for specific packages:

• nameFilter: "laravel/*" — find all Laravel packages
• nameFilter: "*phpunit*" — find PHPUnit-related packages
• nameFilter: "symfony/console" — find a specific package

Use this to:

• Detect which framework is installed
• Check if a specific library is available before suggesting its use
• Verify package versions for compatibility

Security

Run composer audit to check for known vulnerabilities in dependencies. This checks against the PHP Security Advisories Database.

Monorepo Considerations

In monorepo setups, get_composer_dependencies includes packages from all composer.json sub-projects:

• Each sub-project has its own dependency tree
• Sub-projects may have different PHP version requirements
• Use the composer.json closest to the file being edited

External References

• Composer docs: https://getcomposer.org/doc/
• Packagist (package registry): https://packagist.org/
• Version constraints: https://getcomposer.org/doc/articles/versions.md
• Composer security advisories: https://github.com/FriendsOfPHP/security-advisories

Laravel Framework Guide

Directory Structure Quick Reference

Key Concepts

Eloquent Models

• Located in app/Models/ by convention
• Class name is singular (User), table name is plural (users) by default
• `$fillable`: Whitelist of mass-assignable attributes
• `$guarded`: Blacklist of non-mass-assignable attributes
• `$casts`: Attribute type casting (e.g., 'email_verified_at' => 'datetime')

Before writing any Eloquent code, verify the actual schema by reading migration files or using php artisan model:show.

Migrations

Located in database/migrations/. File names include timestamps for ordering:

2024_01_15_000000_create_users_table.php

Read migration files to understand the actual database schema when php artisan model:show is not available.

Routes

Route model binding: Route::get('/users/{user}', ...) automatically resolves {user} to a User model instance.

Controllers

• Located in app/Http/Controllers/
• Resource controllers provide CRUD methods: index, create, store, show, edit, update, destroy
• Invocable controllers have a single __invoke() method

Form Requests

• Located in app/Http/Requests/
• Encapsulate validation rules and authorization logic
• Method rules() returns validation rules array
• Method authorize() returns boolean for authorization

Blade Templates

• Located in resources/views/
• Use .blade.php extension
• Directives: @if, @foreach, @extends, @section, @yield, @include, @component
• Echo: {{ $variable }} (escaped), {!! $html !!} (raw)

Service Container and Dependency Injection

• Laravel auto-resolves constructor dependencies via the service container
• Prefer constructor injection over facades for testability
• Facades (e.g., Cache::get()) are static proxies to container-resolved instances
• Service providers in app/Providers/ register bindings

Essential Artisan Commands

Structural Search Patterns for Laravel

Use search_structural with fileType: "PHP" to find common Laravel patterns. Pattern variables use $name$ syntax:

Environment Configuration

• .env — local environment variables (gitignored, never commit)
• .env.example — template with placeholder values (committed)
• Access via env('KEY') (only in config files) or config('app.key') (everywhere else)

External References

• Laravel docs: https://laravel.com/docs/
• Larastan (PHPStan for Laravel): https://github.com/larastan/larastan
• Laravel Pint (code style): https://laravel.com/docs/pint

Symfony Framework Guide

Directory Structure Quick Reference

Key Concepts

Service Container and Autowiring

Symfony's core is its dependency injection container.

• Autowiring: Services are automatically resolved by type-hinting constructor parameters
• `config/services.yaml`: Configures service registration and argument binding
• Services in src/ are auto-registered by default
• Tags: Mark services for specific purposes (e.g., kernel.event_subscriber)

Configuration

Symfony supports YAML, PHP, and XML configuration:

• config/packages/ — per-bundle settings (e.g., doctrine.yaml, security.yaml)
• config/services.yaml — service definitions and parameters
• config/routes.yaml — route imports (or use PHP attributes on controllers)
• config/bundles.php — registered bundles

Doctrine ORM

Symfony's default database layer.

Entities (src/Entity/):

• Annotated PHP classes mapped to database tables
• Use #[ORM\Entity], #[ORM\Column], #[ORM\Id] attributes
• Naming: entity User maps to table user by default

Repositories (src/Repository/):

• Custom query methods extending ServiceEntityRepository
• Injected via autowiring: type-hint UserRepository in constructors

Migrations (migrations/):

• Generated with php bin/console make:migration
• Applied with php bin/console doctrine:migrations:migrate

Routing

Two main styles:

PHP Attributes (preferred):

#[Route('/users/{id}', name: 'user_show', methods: ['GET'])]
public function show(User $user): Response { ... }

YAML (config/routes.yaml):

user_show:
    path: /users/{id}
    controller: App\Controller\UserController::show
    methods: [GET]

Twig Templates

• Located in templates/
• Extension: .html.twig
• Syntax: {{ variable }} for output, {% block %} for structure, {# comment #}
• Inheritance: {% extends 'base.html.twig' %} with {% block content %}...{% endblock %}

Console Commands

• Located in src/Command/
• Extend Symfony\Component\Console\Command\Command
• Auto-registered via service container

Forms and Validation

• Form types in src/Form/ define field structure
• Validation uses #[Assert\*] attributes on entity properties
• Built-in constraints: NotBlank, Email, Length, Valid, UniqueEntity

Essential CLI Commands

Testing in Symfony

// Functional test example
class UserControllerTest extends WebTestCase
{
    public function test_user_page_loads(): void
    {
        $client = static::createClient();
        $client->request('GET', '/users');
        $this->assertResponseIsSuccessful();
    }
}

External References

• Symfony docs: https://symfony.com/doc/current/index.html
• Doctrine ORM: https://www.doctrine-project.org/projects/orm.html
• Twig docs: https://twig.symfony.com/doc/
• Symfony best practices: https://symfony.com/doc/current/best_practices.html

PhpStorm MCP Tools Reference

Detailed usage guide for MCP tools provided by the PhpStorm JetBrains IDE plugin.

get_inspections

Analyze a file using the IDE's inspections. Returns problems with severity, description, location, and available quick fixes.

Parameters

Severity Levels

Note: Most PHP inspections report at WEAK_WARNING level. Use WEAK_WARNING as the default to capture most issues. Use ERROR when you only want critical problems.

Response Format

Each problem includes:

• severity: ERROR, WARNING, WEAK_WARNING, or INFORMATION
• line, column: 1-based location
• description: Human-readable problem description
• quickFixes: Array of available automated fixes (each with name)

Difference from get_file_problems

apply_quick_fix

Apply an automated fix for a specific inspection problem.

Parameters

Workflow

1. Always run `get_inspections` first — you need the exact line, column, and quickFixName values 2. Match `quickFixName` exactly — use the name string as returned by inspections 3. Re-run inspections after applying — verify the fix took effect and didn't introduce new issues

Example

# Step 1: Find problems
get_inspections(filePath: "app/Services/UserService.php", minSeverity: "WARNING")
# Returns: line=15, column=9,
#          quickFixes=[{name: "Safe delete '$temp'"}]

# Step 2: Apply fix
apply_quick_fix(
  filePath: "app/Services/UserService.php",
  line: 15, column: 9,
  quickFixName: "Safe delete '$temp'"
)

# Step 3: Verify
get_inspections(filePath: "app/Services/UserService.php", minSeverity: "WARNING")

search_structural

Search for code patterns using Structural Search and Replace (SSR). Unlike text/regex search, SSR understands code structure semantically.

Parameters

Pattern Syntax

Use $name$ for template variables that match any expression:

Count modifiers (in pattern):

• $a${2,5} — matches 2 to 5 occurrences
• $a$+ — one or more occurrences
• $a$* — zero or more occurrences

Constraints

Constraints refine what template variables can match. Use the variable name without dollar signs as the key:

{
  "a": {
    "regex": "User.*",
    "exprType": "App\\Models\\User"
  },
  "b": {
    "minCount": 1,
    "maxCount": 5
  }
}

Practical Examples

# Find all Eloquent where() calls
search_structural(pattern: "$model$::where($args$)", fileType: "PHP")

# Find all class definitions extending Model
search_structural(pattern: "class $name$ extends Model {}", fileType: "PHP")

# Find all route definitions in routes directory
search_structural(
  pattern: "Route::$method$($args$)",
  fileType: "PHP",
  directoryToSearch: "routes"
)

# Find try-catch blocks with empty catch
search_structural(pattern: "try { $body$ } catch ($e$) { }", fileType: "PHP")

# Find method calls matching a regex on the method name
search_structural(
  pattern: "$a$->$b$()",
  fileType: "PHP",
  constraints: {"b": {"regex": "^get.*"}}
)

Known Limitations

• Some class modifiers (e.g., readonly) may not be matched
• Complex nested patterns with constraints may not work as expected
• Use get_structural_patterns to discover reliably working patterns

get_structural_patterns

List predefined PHP structural search patterns organized by category.

Parameters

Response

Returns categories of patterns with descriptions:

• General: Class, interface, trait definitions and structure
• Expressions: Assignments, method calls, field access, etc.
• Suspicious: Potentially problematic code patterns

Use these predefined patterns as templates — modify them for your specific search needs.

get_composer_dependencies

Return all Composer packages installed in the project with their exact versions. Reads from already-indexed composer.lock data — no disk I/O or network calls.

Parameters

Use Cases

Example

get_composer_dependencies(nameFilter: "laravel/*")
# Returns packages matching the filter with exact versions

get_php_project_config

Return the PHP project configuration as seen by PhpStorm.

Parameters

None required.

Response

Includes:

• PHP language level: The configured target PHP version (may differ from system PHP)
• Interpreter details: Name, path, local/remote
• PHP runtime information: Exact version, loaded extensions, php.ini path, debuggers

Use Cases

• Determine the project's target PHP version before generating code
• Check if specific PHP extensions are available
• Understand if the interpreter is local or remote (Docker/SSH)

get_symbol_info

Retrieve information about a symbol at a specific position in a file. Provides the same information as PhpStorm's Quick Documentation feature.

Parameters

Response

Returns symbol information including name, signature, type, documentation, and declaration code when available.

Use Cases

• Understand what a function/method does without reading the full source
• Check parameter types and return types
• Find where a symbol is declared
• Get PHPDoc documentation for a class or method

rename_refactoring

Rename a symbol (variable, function, class, etc.) across the entire project. Unlike text search-and-replace, this understands code structure and updates all references safely.

Parameters

Use Cases

• Rename a class, method, or variable and update all usages
• Safe refactoring that preserves code integrity
• Always preferred over manual find-and-replace for symbol renaming

get_file_problems

Analyze a file for errors and warnings using IntelliJ's inspections. Lighter than get_inspections — does not return quick fixes.

Parameters

Search Tools

PhpStorm provides multiple search tools optimized for different use cases:

File Operation Tools

Execution Tools

PHP Coding Standards and Language Features

Coding Standards

PER Coding Style (Current Standard)

The latest PHP coding standard, superseding PSR-12.

• Reference: https://www.php-fig.org/per/coding-style/
• 4-space indentation (no tabs)
• 120-character soft line length limit
• Unix LF line endings
• Opening brace on the same line for control structures, next line for classes/methods
• One use import per line, grouped by type (classes, functions, constants)
• declare(strict_types=1) as the first statement after <?php

PSR-12 Extended Coding Style

Still widely used in existing projects.

• Reference: https://www.php-fig.org/psr/psr-12/
• Largely compatible with PER; PER adds clarifications and updates

PSR-4 Autoloading

• Reference: https://www.php-fig.org/psr/psr-4/
• See references/project-detection.md for detailed mapping rules

All PSR Standards

• Reference: https://www.php-fig.org/psr/

PHP Version Detection

Read the require.php field in composer.json:

"require": {
  "php": ">=8.2"
}

Also check config.platform.php which may override the effective version for dependency resolution.

Rule: Never use language features newer than the project's minimum PHP version.

Modern PHP Features by Version

Check the project's PHP version before using any of these features.

PHP 8.0

• Named arguments: htmlspecialchars(string: $s, double_encode: false)
• Match expression: match($status) { 'active' => 1, default => 0 }
• Constructor promotion: public function __construct(private string $name) {}
• Union types: function foo(int|string $value): void
• Nullsafe operator: $user?->getAddress()?->getCity()
• `str_contains()`, `str_starts_with()`, `str_ends_with()`

PHP 8.1

• Enums: enum Status: string { case Active = 'active'; }
• Readonly properties: public readonly string $name
• Fibers: low-level concurrency primitive
• Intersection types: function foo(Countable&Iterator $value): void
• `never` return type: for functions that always throw or exit
• First-class callable syntax: $fn = strlen(...)

PHP 8.2

• Readonly classes: readonly class Point { ... }
• DNF types: (A&B)|null
• `true`, `false`, `null` as standalone types
• Constants in traits
• Deprecated: dynamic properties (use #[AllowDynamicProperties] to opt in)

PHP 8.3

• Typed class constants: const string NAME = 'value';
• `json_validate()` function
• `#[Override]` attribute: verify method actually overrides parent
• Dynamic class constant fetch: $class::{$constName}

PHP 8.4

• Property hooks: public string $name { get => ...; set => ...; }
• Asymmetric visibility: public private(set) string $name
• `new` without wrapping parentheses: new MyClass()->method() (previously required (new MyClass())->method())
• `array_find()`, `array_any()`, `array_all()` functions

Anti-Patterns to Avoid

External References

• PHP-FIG standards: https://www.php-fig.org/psr/
• PHP version lifecycle: https://www.php.net/supported-versions.php
• PHP RFC process: https://wiki.php.net/rfc

Project Detection and Structure

How to understand the structure of any PHP project by reading its configuration files.

composer.json Anatomy

The composer.json file is the single source of truth for a PHP project's structure.

Key Sections

Example

{
  "require": {
    "php": ">=8.2",
    "laravel/framework": "^11.0"
  },
  "require-dev": {
    "phpunit/phpunit": "^11.0",
    "phpstan/phpstan": "^2.0"
  },
  "autoload": {
    "psr-4": {
      "App\\": "app/",
      "Database\\": "database/"
    }
  },
  "autoload-dev": {
    "psr-4": {
      "Tests\\": "tests/"
    }
  },
  "scripts": {
    "test": "phpunit",
    "analyse": "phpstan analyse"
  }
}

PSR-4 Autoloading

PSR-4 maps namespace prefixes to base directories. Understanding this mapping is critical for placing files in the correct location.

How It Works

Given "App\\": "app/":

• Class App\Models\User → file app/Models/User.php
• Class App\Http\Controllers\Api\UserController → file app/Http/Controllers/Api/UserController.php

Rules: 1. The namespace prefix (App\) is replaced by the base directory (app/) 2. Each remaining namespace separator becomes a directory separator 3. The class name becomes the file name with .php extension 4. Case matters — App\Models\User must be in app/Models/User.php, not app/models/user.php

Resolving FQCN to File Path

To find the file for a fully qualified class name (FQCN):

1. Read autoload.psr-4 from composer.json 2. Find the longest matching namespace prefix 3. Replace the prefix with the corresponding directory 4. Convert remaining \ to / and append .php

Example with mapping "App\\": "app/":

• App\Services\Payment\StripeGateway → app/Services/Payment/StripeGateway.php

Common Mistake

Do not confuse the namespace with the directory. The mapping is not always 1:1 with the folder name:

• "Domain\\": "src/Domain/" means Domain\Order\Order → src/Domain/Order/Order.php (not Domain/Order/Order.php)

Common Directory Layouts

Laravel

project-root/
├── app/
│   ├── Console/            # Artisan commands
│   ├── Events/             # Event classes
│   ├── Exceptions/         # Exception handlers
│   ├── Http/
│   │   ├── Controllers/    # Route controllers
│   │   ├── Middleware/      # HTTP middleware
│   │   └── Requests/       # Form request validation
│   ├── Jobs/               # Queue jobs
│   ├── Listeners/          # Event listeners
│   ├── Mail/               # Mailables
│   ├── Models/             # Eloquent models
│   ├── Notifications/      # Notifications
│   ├── Policies/           # Authorization policies
│   ├── Providers/          # Service providers
│   └── Services/           # Business logic (convention)
├── bootstrap/              # Framework bootstrapping
├── config/                 # Configuration files
├── database/
│   ├── factories/          # Model factories for testing
│   ├── migrations/         # Database migrations
│   └── seeders/            # Database seeders
├── public/                 # Web server document root
├── resources/
│   ├── css/                # Stylesheets
│   ├── js/                 # JavaScript
│   └── views/              # Blade templates
├── routes/
│   ├── api.php             # API routes
│   ├── console.php         # Console routes
│   └── web.php             # Web routes
├── storage/                # Logs, cache, uploads
├── tests/
│   ├── Feature/            # Feature/integration tests
│   └── Unit/               # Unit tests
├── .env.example            # Environment template
├── artisan                 # CLI entry point
├── composer.json
└── phpunit.xml(.dist)

Symfony

project-root/
├── bin/
│   └── console             # CLI entry point
├── config/
│   ├── packages/           # Bundle configuration
│   ├── routes/             # Routing configuration
│   ├── bundles.php         # Registered bundles
│   ├── routes.yaml         # Main route config
│   └── services.yaml       # Service container config
├── migrations/             # Doctrine migrations
├── public/
│   └── index.php           # Web entry point
├── src/
│   ├── Command/            # Console commands
│   ├── Controller/         # Route controllers
│   ├── Entity/             # Doctrine entities
│   ├── EventSubscriber/    # Event subscribers
│   ├── Form/               # Form types
│   ├── Repository/         # Doctrine repositories
│   ├── Security/           # Authentication/authorization
│   └── Service/            # Business logic
├── templates/              # Twig templates
├── tests/                  # Test files
├── translations/           # Translation files
├── var/                    # Cache, logs (gitignored)
├── vendor/                 # Dependencies (gitignored)
├── .env                    # Environment variables
├── composer.json
└── phpunit.xml.dist

Generic PHP (No Framework)

project-root/
├── src/                    # Application source code
├── tests/                  # Test files
├── public/                 # Web document root (if applicable)
├── vendor/                 # Dependencies (gitignored)
├── composer.json
└── phpunit.xml(.dist)

Config Files and Their Meaning

Monorepo Detection

In monorepo setups, get_composer_dependencies includes packages from all composer.json sub-projects. If you find packages from different frameworks or conflicting versions, the project is likely a monorepo. Each composer.json represents a sub-project with its own dependencies and autoloading.

When working in a monorepo: 1. Identify which sub-project the target file belongs to 2. Use that sub-project's composer.json for autoloading resolution 3. Be aware that sub-projects may have different PHP version requirements

Static Analysis Tools

PHPStan

Detection

Config files: phpstan.neon, phpstan.neon.dist, or phpstan.neon.local Package: phpstan/phpstan in require-dev

Levels

PHPStan uses levels 0-9, each adding more checks:

Running

./vendor/bin/phpstan analyse              # Analyse with config defaults
./vendor/bin/phpstan analyse src/          # Analyse specific directory
./vendor/bin/phpstan analyse --level=6    # Override level

Baseline

Legacy projects use a baseline file to ignore existing errors:

includes:
    - phpstan-baseline.neon

The baseline captures existing errors so new code is held to a higher standard. Regenerate with ./vendor/bin/phpstan --generate-baseline.

Framework Extensions

Psalm

Detection

Config file: psalm.xml or psalm.xml.dist Package: vimeo/psalm in require-dev

Error Levels

Psalm uses levels 1-8 (1 = strictest, 8 = most permissive — opposite to PHPStan).

Running

./vendor/bin/psalm                # Analyse with config defaults
./vendor/bin/psalm src/           # Analyse specific directory
./vendor/bin/psalm --show-info    # Include informational issues

Baseline

Similar to PHPStan: ./vendor/bin/psalm --set-baseline=psalm-baseline.xml

PHP CS Fixer

Detection

Config files: .php-cs-fixer.php, .php-cs-fixer.dist.php Package: friendsofphp/php-cs-fixer in require-dev

Running

./vendor/bin/php-cs-fixer fix              # Fix all files
./vendor/bin/php-cs-fixer fix src/         # Fix specific directory
./vendor/bin/php-cs-fixer fix --dry-run    # Preview changes without applying
./vendor/bin/php-cs-fixer fix --diff       # Show diff of changes

PHP CodeSniffer

Detection

Config files: phpcs.xml, phpcs.xml.dist, .phpcs.xml Package: squizlabs/php_codesniffer in require-dev

Running

./vendor/bin/phpcs              # Check code style
./vendor/bin/phpcbf             # Auto-fix code style issues
./vendor/bin/phpcs src/         # Check specific directory

Laravel Pint

Detection

Config file: pint.json Package: laravel/pint in require-dev (included by default in Laravel projects)

Running

./vendor/bin/pint              # Fix all files
./vendor/bin/pint --test       # Preview changes without applying

Relationship to PhpStorm Inspections

PhpStorm's built-in inspections and external static analysis tools may report different issues for the same code. They are complementary:

• PhpStorm inspections (get_inspections): Real-time, IDE-integrated, includes quick fixes
• PHPStan/Psalm: Deeper type analysis, framework-specific rules, CI/CD integration

When both are available, use PhpStorm inspections for quick feedback during editing and external tools for comprehensive analysis.

External References

• PHPStan: https://phpstan.org/user-guide/getting-started
• Psalm: https://psalm.dev/docs/
• PHP CS Fixer: https://cs.symfony.com/
• PHP CodeSniffer: https://github.com/PHPCSStandards/PHP_CodeSniffer

PHP Testing Guide

Detecting the Test Framework

Check require-dev in composer.json or use get_composer_dependencies:

Most projects use PHPUnit or Pest. Pest is built on PHPUnit — any PHPUnit assertion works inside Pest tests too.

PHPUnit Patterns

Test Class Structure

<?php

declare(strict_types=1);

namespace Tests\Unit;

use PHPUnit\Framework\TestCase;

class CalculatorTest extends TestCase
{
    public function test_adds_two_numbers(): void
    {
        $calculator = new Calculator();
        $this->assertEquals(4, $calculator->add(2, 2));
    }
}

Conventions:

• File naming: *Test.php (e.g., CalculatorTest.php)
• Class naming: *Test extending TestCase
• Method naming: test_* prefix or @test annotation / #[Test] attribute
• One test class per file

Important: Base Class Selection

Common mistake: Using PHPUnit\Framework\TestCase in a Laravel feature test — this skips the app container and causes Target class [X] does not exist errors.

Common Assertions

Data Providers

Supply multiple test cases to a single test method:

#[DataProvider('additionProvider')]
public function test_addition(int $a, int $b, int $expected): void
{
    $this->assertEquals($expected, $a + $b);
}

public static function additionProvider(): array
{
    return [
        'positive numbers' => [1, 2, 3],
        'negative numbers' => [-1, -2, -3],
        'zero' => [0, 0, 0],
    ];
}

Note: Use #[DataProvider] attribute (PHP 8+) or @dataProvider annotation. The provider method must be static in PHPUnit 10+.

Mocking

$mock = $this->createMock(PaymentGateway::class);
$mock->expects($this->once())
     ->method('charge')
     ->with(100, 'USD')
     ->willReturn(true);

$service = new OrderService($mock);
$result = $service->processPayment(100, 'USD');
$this->assertTrue($result);

Key mocking methods:

• createMock(Class::class) — creates mock with all methods stubbed (returns null)
• createStub(Class::class) — like createMock but does not verify expectations
• expects($this->once()) — verify call count
• willReturn($value) — set return value
• willThrowException(new \Exception()) — simulate errors

Pest Patterns

Test Structure

<?php

use App\Models\User;

it('can create a user', function () {
    $user = User::factory()->create();
    expect($user)->toBeInstanceOf(User::class);
});

test('user has a name', function () {
    $user = User::factory()->create(['name' => 'John']);
    expect($user->name)->toBe('John');
});

`it()` vs `test()`: Both are identical. Convention: it('does something') reads as a sentence; test('something works') is more descriptive.

Expectation API

expect($value)
    ->toBe('exact')           // assertSame
    ->toEqual('loose')        // assertEquals
    ->toBeTrue()              // assertTrue
    ->toBeFalse()             // assertFalse
    ->toBeNull()              // assertNull
    ->toHaveCount(3)          // assertCount
    ->toBeInstanceOf(Foo::class)
    ->toContain('substring')
    ->toBeEmpty()
    ->toBeGreaterThan(5)
    ->toMatchArray(['key' => 'value']);

Lifecycle Hooks

beforeEach(function () {
    $this->calculator = new Calculator();
});

afterEach(function () {
    // cleanup
});

Datasets (Data Providers)

it('adds numbers correctly', function (int $a, int $b, int $expected) {
    expect($a + $b)->toBe($expected);
})->with([
    [1, 2, 3],
    [-1, -2, -3],
    [0, 0, 0],
]);

Running Tests

Commands

Configuration

phpunit.xml(.dist) controls:

• Test suite directories and file patterns
• Environment variables for testing
• Code coverage settings
• Bootstrap file (typically vendor/autoload.php)

Common Mistakes

External References

• PHPUnit docs: https://docs.phpunit.de/
• Pest docs: https://pestphp.com/docs/writing-tests
• PhpStorm test integration: https://www.jetbrains.com/help/phpstorm/php-test-frameworks.html