# PSR-4 Autoloading

This document describes the PSR-4 autoloading configuration for the BuyerKiosk application.

## Overview

The BuyerKiosk application uses PSR-4 autoloading via Composer. All application classes are automatically loaded based on their namespace, eliminating the need for manual `include` or `require` statements.

## Configuration

### Composer PSR-4 Setup

The PSR-4 autoload configuration in `composer.json`:

```json
{
  "autoload": {
    "psr-4": {
      "BuyerKiosk\\": "src/BuyerKiosk/"
    },
    "files": [
      "src/BuyerKiosk/Compatibility/LegacyAliases.php"
    ],
    "classmap": [
      "controllers",
      "auth/",
      "models/"
    ]
  }
}
```

### How PSR-4 Works

1. **Namespace-to-Directory Mapping**: The namespace `BuyerKiosk\` maps to the directory `src/BuyerKiosk/`
2. **Class Resolution**: `BuyerKiosk\Core\Store` resolves to `src/BuyerKiosk/Core/Store.php`
3. **Automatic Loading**: When a class is referenced, Composer's autoloader finds and loads the file

## Adding New Classes

To add a new class:

1. **Create the file** in the appropriate directory:
   ```
   src/BuyerKiosk/Feature/MyNewClass.php
   ```

2. **Add the namespace declaration**:
   ```php
   <?php
   namespace BuyerKiosk\Feature;

   class MyNewClass
   {
       // ...
   }
   ```

3. **Use the class anywhere**:
   ```php
   use BuyerKiosk\Feature\MyNewClass;

   $instance = new MyNewClass();
   ```

No need to edit any include files or regenerate the autoloader!

## Legacy Compatibility

### Class Aliases

For backward compatibility, legacy class names are aliased to their new namespaced versions. This is handled by `LegacyAliases.php`, which is loaded via Composer's `files` autoload.

```php
// Legacy usage (still works, but deprecated)
$store = new Store($typeNum);

// Preferred usage
use BuyerKiosk\Core\Store;
$store = new Store($typeNum);
```

### Deprecation Warnings

Legacy class names trigger deprecation notices:

```
Class "Store" is deprecated since PSR-4 migration, use "BuyerKiosk\Core\Store" instead.
```

These warnings help identify code that should be updated to use the new namespaces.

## Regenerating the Autoloader

After making changes to composer.json's autoload configuration:

```bash
cd userfrosting
composer dump-autoload
```

For production deployments, use the optimized autoloader:

```bash
composer dump-autoload -o
```

## Performance

The PSR-4 autoloader is highly efficient:

- **Resolution Time**: ~0.04 microseconds per class
- **On-Demand Loading**: Classes are only loaded when used
- **No Classmap Regeneration**: New classes work immediately

## Troubleshooting

### Class Not Found

1. **Check namespace**: Ensure the namespace matches the directory structure
2. **Check filename**: Filename must match class name (case-sensitive)
3. **Run composer dump-autoload**: Regenerate the autoloader
4. **Check for typos**: Namespace backslashes, class name spelling

### Legacy Class Not Found

If a legacy class name doesn't work:

1. Check `LegacyAliases.php` for the mapping
2. Ensure the target class exists in the new location
3. Verify Composer's files autoload includes LegacyAliases.php

## Best Practices

1. **Always use namespaces**: Never create non-namespaced classes
2. **Follow PSR-4 structure**: Directory matches namespace
3. **Use `use` statements**: Import classes at the top of files
4. **Migrate legacy code**: Update old class references when touching files
5. **Run tests**: Verify autoloading works after changes