mirror of
https://github.com/ivuorinen/phpenv.fish.git
synced 2026-01-26 11:14:07 +00:00
153 lines
4.9 KiB
Markdown
153 lines
4.9 KiB
Markdown
# CLAUDE.md
|
|
|
|
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
|
|
|
## Project Overview
|
|
|
|
phpenv.fish is a PHP version manager for Fish Shell, similar to nvm for Node.js.
|
|
It provides fast PHP version switching, extension management, and automatic version detection from project files.
|
|
|
|
## Development Commands
|
|
|
|
### Testing Changes
|
|
|
|
Since this is a Fish shell plugin, test changes by:
|
|
|
|
```bash
|
|
# Reload the function after changes
|
|
source functions/phpenv.fish
|
|
|
|
# Test commands
|
|
phpenv help
|
|
phpenv versions
|
|
phpenv current
|
|
```
|
|
|
|
### Installation for Development
|
|
|
|
```bash
|
|
# Link the development version to Fish config
|
|
ln -sf $PWD/functions/phpenv.fish ~/.config/fish/functions/phpenv.fish
|
|
ln -sf $PWD/completions/phpenv.fish ~/.config/fish/completions/phpenv.fish
|
|
ln -sf $PWD/conf.d/phpenv.fish ~/.config/fish/conf.d/phpenv.fish
|
|
```
|
|
|
|
## Code Architecture
|
|
|
|
### Core Components
|
|
|
|
1. **Main Dispatcher (`functions/phpenv.fish`)**
|
|
- Entry point function that routes commands to internal functions
|
|
- All subcommands are implemented as `__phpenv_*` functions
|
|
- Version detection logic in `__phpenv_detect_version`
|
|
|
|
2. **Completions (`completions/phpenv.fish`)**
|
|
- Provides tab completions for all commands
|
|
- Fetches available versions dynamically from shivammathur/setup-php
|
|
|
|
3. **Configuration (`conf.d/phpenv.fish`)**
|
|
- Sets up Fish universal variables on load
|
|
- Handles PATH initialization
|
|
|
|
### Key Design Patterns
|
|
|
|
- **Performance Focus**: Direct directory checks instead of `brew list` (100-1000x faster)
|
|
- **Fish Universal Variables**: Used for configuration persistence
|
|
- **Homebrew Integration**: Uses shivammathur taps for PHP/extension installation
|
|
- **Version File Priority**: `.php-version` > `.tool-version` > `composer.json` > global > system
|
|
|
|
### Version Detection Flow
|
|
|
|
1. Check for `.php-version` file (exact version)
|
|
2. Check for `.tool-version` file (parse PHP line)
|
|
3. Check `composer.json` for PHP constraints (semver resolution)
|
|
4. Use global version from Fish universal variable
|
|
5. Fall back to system PHP
|
|
|
|
### Important Implementation Details
|
|
|
|
- All internal functions are prefixed with `__phpenv_`
|
|
- Version resolution supports semver constraints (^8.1, ~8.2.0, etc.)
|
|
- Extension management uses separate Homebrew tap
|
|
- Auto-switching uses Fish's `pwd` event handler
|
|
- Configuration stored in Fish universal variables with `PHPENV_` prefix
|
|
|
|
## Code Style Requirements
|
|
|
|
- Maximum line length: 120 characters (enforced by .editorconfig)
|
|
- Use LF line endings
|
|
- UTF-8 encoding
|
|
- Trim trailing whitespace
|
|
- Insert final newline
|
|
|
|
## PATH and Variable Management
|
|
|
|
### PATH State Tracking
|
|
|
|
- `PHPENV_ORIGINAL_PATH`: Stores initial PATH before any modifications
|
|
- `PHPENV_CURRENT_VERSION`: Tracks currently active PHP version
|
|
- `PHPENV_CURRENT_PATH`: Stores path to current PHP binary
|
|
- Use `phpenv use system` to restore original PATH
|
|
|
|
### Variable Scope Strategy
|
|
|
|
- **Universal variables** (`set -U`): Only `PHPENV_GLOBAL_VERSION` (persists across shells)
|
|
- **Session variables** (`set -g`): Configuration settings (per-shell session)
|
|
- **Local variables** (`set -l`): Function-scoped, automatically cleaned up
|
|
|
|
### Auto-Switch Debouncing
|
|
|
|
- `PHPENV_LAST_SWITCH_TIME`: Prevents excessive PATH changes on rapid directory changes
|
|
- 1-second minimum interval between auto-switches
|
|
- Early exit if already using correct version
|
|
|
|
## Common Tasks
|
|
|
|
### Adding a New Command
|
|
|
|
1. Add case in main `phpenv` function switch statement
|
|
2. Implement `__phpenv_<command>` function
|
|
3. Add completions in `completions/phpenv.fish`
|
|
4. Update help text in `__phpenv_help`
|
|
|
|
### Modifying Version Detection
|
|
|
|
- Edit `__phpenv_detect_version` function
|
|
- Maintain priority order of version sources
|
|
- Test with various project configurations
|
|
|
|
### Working with Homebrew Integration
|
|
|
|
- PHP versions: `shivammathur/php/php@<version>`
|
|
- Extensions: `shivammathur/extensions/<extension>@<php-version>`
|
|
- Check formula existence before operations
|
|
|
|
### Performance Optimizations
|
|
|
|
#### Caching System
|
|
|
|
- `__phpenv_version_cache`: 5-minute cache for API version data
|
|
- `__phpenv_cellar_cache`: Permanent cache for Homebrew Cellar path
|
|
- Reduces network calls and filesystem operations
|
|
|
|
#### Unified Helper Functions
|
|
|
|
- `__phpenv_parse_version_field`: Single function for all jq parsing (eliminates 9+ duplicated calls)
|
|
- `__phpenv_ensure_taps`: Unified Homebrew tap management
|
|
- `__phpenv_get_available_extensions`: Shared extension listing logic
|
|
|
|
### PATH Management Best Practices
|
|
|
|
- Always check `PHPENV_ORIGINAL_PATH` exists before modification
|
|
- Use debouncing for automatic operations
|
|
- Validate PHP paths before setting
|
|
- Provide restoration mechanism (`phpenv use system`)
|
|
- Clean up temporary variables in error cases
|
|
|
|
### Code Organization Principles
|
|
|
|
- Cache expensive operations (API calls, filesystem checks)
|
|
- Unify repeated patterns into helper functions
|
|
- Use session variables instead of universal where possible
|
|
- Minimize network requests and subprocess calls
|