Contributing

# Fork the framework repository on GitHub, then:
git clone https://github.com/YOUR_USERNAME/framework.git glueful-framework
cd glueful-framework

# Add upstream remote
git remote add upstream https://github.com/glueful/framework.git

composer install

git fetch upstream
git checkout -b fix/bug-description upstream/dev
# or
git checkout -b feature/your-feature-name upstream/dev

# Check code style
composer run phpcs

# Fix code style
composer run phpcbf      # or: composer run format

composer run analyse            # what CI runs
composer run analyse:changed    # only files changed vs main
composer run types:validate     # per-component passes (DI, database, HTTP, cache)

<?php

declare(strict_types=1);

namespace Glueful\Tests\Unit\Support;

use PHPUnit\Framework\TestCase;

final class ExampleTest extends TestCase
{
    public function testExampleFeature(): void
    {
        $result = someFunction();

        $this->assertSame('expected', $result);
    }
}

# All suites
composer test

# One suite
composer run test:unit
composer run test:integration

# One file or test
vendor/bin/phpunit tests/Unit/Support/ExampleTest.php
vendor/bin/phpunit --filter=testExampleFeature

# Coverage (HTML in coverage/)
composer run test:coverage

composer run ci        # composer test + composer run analyse + composer run phpcs

type(scope): subject

body

footer

fix(cache): keep the file cache in the app's storage directory

The file driver resolved a config key no app defines, so entries
landed under vendor/. Resolve the app's storage path instead.

Closes #123

git push origin fix/bug-description

**Describe the bug**
A clear description of what the bug is.

**To Reproduce**
Steps to reproduce:
1. ...
2. ...
3. See error

**Expected behavior**
What you expected to happen.

**Actual behavior**
What actually happened.

**Environment:**
- Glueful version: [e.g. 1.91.0]
- PHP version: [e.g. 8.3.0]
- Database: [e.g. PostgreSQL 16]
- OS: [e.g. Ubuntu 24.04]

**Additional context**
Any other relevant information.

**Code samples**
```php
// Relevant code

## Suggesting Features

### Feature Request Template

```markdown
**Is your feature request related to a problem?**
A clear description of the problem.

**Describe the solution**
How you'd like it to work.

**Describe alternatives**
Alternative solutions you've considered.

**Additional context**
Any other context or examples.

composer create-project glueful/api-skeleton my-app
cd my-app

# In my-app/composer.json, add:
#   "repositories": [{ "type": "path", "url": "../glueful-framework", "options": { "symlink": true } }]
composer require glueful/framework:@dev

php glueful install
php glueful migrate:run

git clone https://github.com/glueful/docs.git
cd docs
pnpm install
pnpm run dev

// ✅ Good - strict types, type hints
declare(strict_types=1);

public function process(string $name, int $age): User
{
    // ...
}

// ❌ Bad - no types
public function process($name, $age)
{
    // ...
}

// ✅ Good - specific exceptions
if ($user === null) {
    throw new UserNotFoundException("User {$id} not found");
}

// ❌ Bad - generic exception
if (!$user) {
    throw new Exception("Error");
}

// ✅ Good - constructor injection; ApplicationContext passed explicitly
public function __construct(
    private ApplicationContext $context,
    private EmailService $email
) {}

// ❌ Bad - hidden global state
public function process()
{
    $users = UserRepository::getInstance();
}

tests/
├── Unit/           # Unit tests, mirroring src/ (Auth, Cache, Database, Extensions, Routing, …)
├── Integration/    # Integration tests across subsystems
├── Feature/        # End-to-end feature tests (CLI, system checks)
├── Core/           # Framework boot, router, and exception-handler tests
├── Performance/    # Benchmarks (own suite)
├── Fixtures/       # Test fixtures
├── Support/        # Shared test helpers
└── bootstrap.php   # PHPUnit bootstrap

// ✅ Good - clear, focused test
public function testCreatesUserWithValidData(): void
{
    $data = ['name' => 'John', 'email' => '[email protected]'];

    $user = $this->userService->create($data);

    $this->assertNotNull($user->id);
    $this->assertSame('John', $user->name);
}

// ❌ Bad - tests multiple things
public function testUserService(): void
{
    // Creates user
    // Updates user
    // Deletes user
    // All in one test
}

/**
 * Process user registration
 *
 * @param  array<string, mixed>  $data  User registration data
 * @return User  The created user
 * @throws ValidationException
 */
public function register(array $data): User
{
    // ...
}