## Getting Started

### Minimal Setup
1. **Installation**
   Update the package to the latest version for PHP 8.4 compatibility and new namespace conventions:
   ```bash
   composer require --dev atoum/stubs:^2.7.0

Ensure atoum/atoum is installed (minimum version supporting PHP 8.4). Verify compatibility with your Laravel version (tested with Laravel 10+).

Locate Stubs Stubs are now fully reorganized under updated namespaces in vendor/atoum/stubs/src/:
- atoum/stubs/ – Core framework stubs (new namespace structure).
- atoum/stubs/php/ – Generic PHP stubs (unchanged but may reference new namespaces).
- atoum/stubs/laravel/ – Laravel-specific stubs (if included; now aligned with atoum\stubs\laravel\ namespace).
- Templates: Updated templates are in vendor/atoum/stubs/templates/ with PHP 8.4-compatible syntax.
First Use Case Generate a Laravel model test with PHP 8.4-compatible syntax and new namespace conventions:
```
php vendor/bin/atoum --stub="UserTest" --namespace="Tests\Unit" --class="App\Models\User" --laravel
```
Output includes:
- Static assertions (e.g., static::assertSame() instead of deprecated assertSame).
- Laravel facade mocking with PHP 8.4-compatible static::mockery calls.
- Namespace-aware imports (e.g., use atoum\stubs\laravel\LaravelTestCase;).

Implementation Patterns

Workflows

Stub Generation
- PHP 8.4 + Namespace Compliance: All generated stubs now enforce:
  - Static method calls for assertions (e.g., static::assertEquals()).
  - Updated namespace imports (e.g., atoum\stubs\laravel\).
  - Laravel-specific helpers (e.g., static::app()->make()). Example:
```
php vendor/bin/atoum --stub="PostControllerTest" --namespace="Tests\Feature" --methods="store,index" --laravel
```
- Dynamic Stub Customization: Use --template to override defaults with PHP 8.4-compatible templates:
```
php vendor/bin/atoum --stub="CustomTest" --template="tests/Stubs/custom.atoum" --namespace="Tests\Unit"
```
  Ensure templates include:
```
use atoum\stubs\laravel\LaravelTestCase;
static::setLaravelEnvironment('testing');
```

Laravel-Specific Integrations

Facade Mocking: Updated stubs auto-generate PHP 8.4-compatible mockery syntax for Laravel facades:
```
static::mockery->mock('overload:Illuminate\Support\Facades\Cache')
    ->shouldReceive('get')->andReturn(['data' => 'value']);
```
Use --facades="Cache,Auth" to include multiple facades in stubs.

Eloquent Testing: Generate stubs with PHP 8.4-compatible DB assertions:

php vendor/bin/atoum --stub="UserRepositoryTest" --eloquent="App\Models\User" --laravel

Output includes:

static::assertDatabaseHas('users', ['email' => 'test@example.com']);
static::assertDatabaseMissing('users', ['deleted_at' => null]);

Artisan Commands: Stub generation now supports PHP 8.4-compatible Artisan calls:

php vendor/bin/atoum --stub="CommandTest" --artisan="migrate:fresh" --laravel

Generates:

static::artisan()->call('migrate:fresh');

CI/CD Automation

Bulk Stub Generation: Use --stub-all with PHP 8.4 flags:

php vendor/bin/atoum --stub-all --namespace="Tests\\Unit" --directory="app/Models" --laravel

CI Configuration: Ensure your CI pipeline uses PHP 8.4+ and validates stubs against new namespace conventions:

# .github/workflows/test.yml
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: shivammathur/setup-php@v2
        with:
          php-version: '8.4'
      - run: composer require atoum/stubs:^2.7.0
      - run: php vendor/bin/atoum --stub-all --namespace="Tests\\Unit" --laravel

Best Practices

Namespace Alignment: Explicitly define --namespace to match your project (e.g., Tests\Unit or App\Tests\Feature). Avoid conflicts with the new atoum\stubs\laravel\ namespace in stubs.
Partial Updates: Use --append to preserve custom logic when regenerating stubs:
```
php vendor/bin/atoum --stub="UserTest" --append --laravel
```
Template Inheritance: Extend default templates by copying from vendor/atoum/stubs/templates/ to tests/Stubs/ and referencing them. Example template (tests/Stubs/custom.atoum):
```
<?php
namespace Tests\Unit;
use atoum\stubs\laravel\LaravelTestCase;
static::setLaravelEnvironment('testing');
```

Gotchas and Tips

Pitfalls

Namespace Migration Issues
- Problem: Stubs now default to atoum\stubs\laravel\ namespace. Regenerating stubs without --namespace may cause conflicts.
- Solution: Always specify --namespace to match your project:
```
php vendor/bin/atoum --stub="UserTest" --namespace="App\\Tests\\Unit" --laravel
```
  If using custom templates, ensure they reference the correct namespace:
```
// Old (may break)
use atoum\stubs\LaravelTestCase;

// New (required)
use atoum\stubs\laravel\LaravelTestCase;
```
PHP 8.4 Deprecations in Stubs
- Problem: Legacy stubs may still use deprecated syntax (e.g., assertSame() instead of static::assertSame()).
- Solution: Regenerate stubs with --laravel flag to enforce PHP 8.4 compliance. Manually update existing stubs:
```
- assertSame($expected, $actual);
+ static::assertSame($expected, $actual);
```
Facade Mocking Quirks
- Problem: Mocking Laravel facades may fail if the namespace isn’t fully qualified in stubs.
- Solution: Use the --facades flag to auto-generate correct mockery calls:
```
php vendor/bin/atoum --stub="AuthTest" --facades="Auth" --laravel
```
  Output:
```
static::mockery->mock('overload:Illuminate\Auth\Facades\Auth')
    ->shouldReceive('check')->andReturn(true);
```
Template Path Changes
- Problem: Custom templates must now be placed in tests/Stubs/ (not tests/atoum/Stubs/).
- Solution: Move existing templates and update references:
```
mkdir -p tests/Stubs
mv tests/atoum/Stubs/* tests/Stubs/
```
  Reference them with:
```
php vendor/bin/atoum --stub="CustomTest" --template="tests/Stubs/custom.atoum"
```

Debugging

Stub Not Found Errors: Verify the stub exists in vendor/atoum/stubs/src/atoum/stubs/laravel/ (new path). Use --verbose to debug:
```
php vendor/bin/atoum --stub="Test" --verbose --laravel
```

Mockery Failures: Ensure mocks use static::mockery and fully qualified facade names:

// Works
static::mockery->mock('overload:Illuminate\Support\Facades\Cache');

// Fails (deprecated)
$this->mockery->mock('overload:Cache');

Namespace Conflicts: Check for duplicate use statements in generated stubs. Use --namespace to override defaults.

Extension Points

Custom Laravel Test Cases Extend atoum\stubs\laravel\LaravelTestCase by creating a custom stub template:
```
// tests/Stubs/CustomLaravelTestCase.atoum
<?php
```

Stubs Laravel Package