Document .ini file extension loading feature

Add user-facing and technical documentation for the new feature that
allows loading PHP extensions via .ini files in .bp-config/php/php.ini.d.

README.md changes:
- Add 'PHP Extension Configuration' section
- Explain .ini file syntax with examples
- Compare with .bp-config/options.json alternative
- Document built-in vs PECL extension categories
- Clarify which extensions require explicit loading

ARCHITECTURE.md changes:
- Add detailed implementation documentation
- Document extension parsing flow in both supply and composer phases
- Explain rationale for parsing approach (no duplicate loading)
- Include extension loading flow diagram
- Reference key source files and line numbers
- Document composer build-time PHP installation architecture

Author: ramonskie

ARCHITECTURE.md

@@ -485,6 +485,110 @@ func (c *ComposerExtension) Supply(stager libbuildpack.Stager) error {
 }
 ```
 
+### PHP Extension Configuration
+
+The buildpack supports two methods for specifying PHP extensions to load:
+
+#### Method 1: .ini Files (Standard PHP Format)
+
+Users can create `.ini` files in `.bp-config/php/php.ini.d/` with standard PHP extension directives:
+
+```ini
+[PHP]
+extension=apcu.so
+extension=redis.so
+zend_extension=opcache.so
+```
+
+**Implementation Details:**
+
+During both the **supply phase** (`src/php/supply/supply.go`) and **composer phase** (`src/php/extensions/composer/composer.go`), the buildpack:
+
+1. Walks the `.bp-config/php/php.ini.d/` directory
+2. Parses all `.ini` files looking for `extension=` and `zend_extension=` directives
+3. Extracts extension names (stripping `.so` suffix and quotes)
+4. Adds these extensions to the buildpack context's `PHP_EXTENSIONS` and `ZEND_EXTENSIONS` lists
+5. The buildpack's normal extension configuration mechanism handles loading them
+
+**Key Functions:**
+
+- `loadUserExtensions()` in `src/php/supply/supply.go` (lines 850-945)
+- `loadUserExtensions()` in `src/php/extensions/composer/composer.go` (lines 1254-1341)
+
+**Why This Approach:**
+
+- **No duplicate loading**: Extensions are only configured once through the buildpack mechanism
+- **Consistent**: Works the same way as extensions specified in `.bp-config/options.json`
+- **Build-time and runtime**: Extensions are available during `composer install` and at application runtime
+- **Familiar syntax**: PHP developers already know `.ini` file format
+
+#### Method 2: options.json (Buildpack-Specific Format)
+
+Alternatively, users can specify extensions in `.bp-config/options.json`:
+
+```json
+{
+  "PHP_EXTENSIONS": ["apcu", "redis"],
+  "ZEND_EXTENSIONS": ["opcache"]
+}
+```
+
+Both methods produce the same result and can be used interchangeably.
+
+#### Extension Types
+
+PHP extensions fall into two categories (defined in `manifest.yml`):
+
+1. **Built-in Extensions** - Have empty `version:` field, compiled into PHP binary
+   - Examples: `bz2`, `curl`, `fileinfo`, `gettext`, `openssl`, `sockets`, `zip`
+   - Always available, no explicit loading required
+
+2. **PECL Extensions** - Have version numbers (e.g., `5.1.23`), distributed separately
+   - Examples: `apcu`, `redis`, `mongodb`, `imagick`, `memcached`, `opcache`
+   - Require explicit loading via `.ini` files or `options.json`
+
+#### Composer Build-Time PHP Installation
+
+The composer extension creates a separate PHP installation specifically for running `composer install`:
+
+**Location:** `BUILD_DIR/php/` (temporary, not in final application)
+
+**Why separate?** 
+
+- Composer may have different PHP version requirements than the runtime
+- Allows composer to run with extensions needed for dependency installation
+- Isolated from runtime PHP configuration
+
+**Extension Loading Flow:**
+
+```
+1. Supply Phase (supply.go)
+   ├─► loadUserExtensions()
+   │   └─► Parse .bp-config/php/php.ini.d/*.ini
+   │       └─► Add to ctx.PHP_EXTENSIONS
+   │
+   └─► Install runtime PHP with extensions
+
+2. Composer Phase (composer.go)
+   ├─► loadUserExtensions()
+   │   └─► Parse .bp-config/php/php.ini.d/*.ini
+   │       └─► Add to ctx.PHP_EXTENSIONS
+   │
+   ├─► Install temporary PHP for composer
+   │   └─► Configure with user extensions
+   │
+   ├─► setupPHPConfig()
+   │   └─► Generate php.ini with extension_dir
+   │
+   └─► Run: php composer.phar install
+       └─► Extensions now available during install
+```
+
+**Key Files:**
+
+- `src/php/extensions/composer/composer.go` - Main composer extension logic
+- `src/php/supply/supply.go` - Runtime PHP installation and extension configuration
+
 ## Comparison with Other Buildpacks
 
 ### Go Buildpack

README.md

@@ -139,6 +139,48 @@ This buildpack uses Cloud Foundry's [libbuildpack](https://github.com/cloudfound
    - Monitors all processes
    - If any process exits, terminates all others and restarts the application
 
+### PHP Extension Configuration
+
+The buildpack supports loading PHP extensions using standard `.ini` file syntax. This allows extensions to be available during both build-time (composer install) and runtime.
+
+#### Loading Extensions via .ini Files
+
+Create `.ini` files in `.bp-config/php/php.ini.d/` directory with standard PHP extension directives:
+
+**Example: `.bp-config/php/php.ini.d/custom.ini`**
+```ini
+[PHP]
+extension=apcu.so
+extension=redis.so
+zend_extension=opcache.so
+```
+
+These extensions will be loaded during:
+- **Build-time**: Available during `composer install` execution (if your dependencies require specific extensions)
+- **Runtime**: Available when your application runs
+
+**Alternative Method:** You can also specify extensions in `.bp-config/options.json`:
+```json
+{
+  "PHP_EXTENSIONS": ["apcu", "redis"],
+  "ZEND_EXTENSIONS": ["opcache"]
+}
+```
+
+Both methods are equivalent and produce the same result. Use whichever format you prefer.
+
+#### Available Extensions
+
+Check the `manifest.yml` file for all available extensions. Extensions fall into two categories:
+
+1. **Built-in Extensions** (no version number) - Compiled into PHP, always available:
+   - `bz2`, `curl`, `fileinfo`, `gettext`, `openssl`, `sockets`, `zip`, etc.
+
+2. **PECL Extensions** (with version numbers) - Require explicit loading:
+   - `apcu`, `redis`, `mongodb`, `imagick`, `memcached`, `opcache`, etc.
+
+Only PECL extensions need to be specified in `.ini` files or `options.json`. Built-in extensions are always available.
+
 ### Extensions
 
 The buildpack includes several built-in extensions written in Go: