Skip to content

Commit 8514d2d

Browse files
CopilotKevinrob
Copilot
and
Kevinrob
authored
✨ Add GitHub Copilot instructions for repository (#205)
* Initial plan * Add GitHub Copilot instructions for repository Co-authored-by: Kevinrob <4509277+Kevinrob@users.noreply.github.com> * Update .github/copilot-instructions.md --------- Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com> Co-authored-by: Kevinrob <4509277+Kevinrob@users.noreply.github.com> Co-authored-by: Kevin Robatel <kevinrob2@gmail.com>
1 parent adf8c1d commit 8514d2d

File tree

1 file changed

+163
-0
lines changed

1 file changed

+163
-0
lines changed

‎.github/copilot-instructions.md‎

Lines changed: 163 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,163 @@
1+
# GitHub Copilot Instructions for guzzle-cache-middleware
2+
3+
This repository contains a HTTP cache middleware for Guzzle 6+, implementing RFC 7234 compliance for HTTP caching.
4+
5+
## Language and Communication
6+
- **Primary Language**: English should be used for all code, comments, documentation, issues, and pull requests
7+
- All variable names, function names, and comments must be in English
8+
- Documentation and README updates should be in English
9+
10+
## Project Overview
11+
This is a PHP library that provides HTTP caching capabilities for Guzzle HTTP client through middleware. Key components:
12+
- `CacheMiddleware`: Main middleware class that handles HTTP caching
13+
- `Storage/`: Various storage adapters (PSR-6, PSR-16, Flysystem, Laravel, WordPress)
14+
- `Strategy/`: Different caching strategies (Private, Public, Greedy, Delegate, Null)
15+
- `CacheEntry`: Represents cached HTTP responses
16+
- `KeyValueHttpHeader`: Utility for handling HTTP headers
17+
18+
## Development Environment
19+
20+
### Setup
21+
Initialize the development environment:
22+
```bash
23+
make init
24+
```
25+
This command builds Docker containers and installs PHP dependencies via Composer.
26+
27+
### Testing
28+
Run the test suite (requires initialization first):
29+
```bash
30+
make test
31+
```
32+
Tests are written using PHPUnit and located in the `tests/` directory.
33+
34+
### Additional Commands
35+
- `make shell`: Enter the Docker container shell for debugging
36+
37+
## Architecture and Code Organization
38+
39+
### Source Structure
40+
- `src/`: Main library code
41+
- `CacheMiddleware.php`: Core middleware implementation
42+
- `Storage/`: Storage backend implementations
43+
- `Strategy/`: Caching strategy implementations
44+
- `tests/`: PHPUnit test suite
45+
- `.docker/`: Docker configuration for development environment
46+
47+
### Key Design Patterns
48+
- **Middleware Pattern**: Used for HTTP request/response interception
49+
- **Strategy Pattern**: Different caching strategies for various use cases
50+
- **Adapter Pattern**: Multiple storage backend implementations
51+
- **PSR Compliance**: Follows PSR-7 (HTTP messages), PSR-6 (caching), PSR-16 (simple cache)
52+
53+
## Coding Standards
54+
55+
### PHP Standards
56+
- **PHP Version**: Requires PHP 8.1+
57+
- **PSR Compliance**: Follow PSR-4 autoloading, PSR-7 HTTP messages
58+
- **Code Style**: Follow the existing code style as defined in `.editorconfig`
59+
- 4 spaces for indentation
60+
- LF line endings
61+
- UTF-8 encoding
62+
- Trim trailing whitespace
63+
64+
### Naming Conventions
65+
- Classes: PascalCase (e.g., `CacheMiddleware`)
66+
- Methods: camelCase (e.g., `getCacheEntry()`)
67+
- Variables: camelCase (e.g., `$cacheEntry`)
68+
- Constants: UPPER_SNAKE_CASE (e.g., `MAX_CACHE_SIZE`)
69+
70+
### Documentation
71+
- Use PHPDoc comments for all public methods and classes
72+
- Include `@param`, `@return`, and `@throws` annotations
73+
- Provide clear descriptions of method purpose and behavior
74+
75+
## Testing Guidelines
76+
77+
### Test Structure
78+
- All tests extend from `BaseTest` class
79+
- Use descriptive test method names (e.g., `testCacheMiddlewareStoresResponseWithCacheControlHeader`)
80+
- Group related tests in appropriate test classes
81+
82+
### Test Categories
83+
- Unit tests for individual components
84+
- Integration tests for middleware functionality
85+
- Strategy-specific tests for different caching behaviors
86+
87+
### Writing Tests
88+
- Mock external dependencies appropriately
89+
- Test both success and error scenarios
90+
- Verify cache behavior matches HTTP caching specifications
91+
- Include edge cases and boundary conditions
92+
93+
## HTTP Caching Implementation
94+
95+
### RFC 7234 Compliance
96+
This library implements HTTP/1.1 caching according to RFC 7234. Key concepts:
97+
- **Cache-Control directives**: Respect HTTP cache control headers
98+
- **Expiration**: Handle TTL and expiration logic
99+
- **Validation**: Support ETags and Last-Modified headers
100+
- **Vary header**: Handle request variation for cache keys
101+
102+
### Supported Features
103+
- Private and public caching
104+
- Greedy caching (ignore server cache headers)
105+
- Multiple storage backends
106+
- Request matching for delegated caching
107+
- Cache invalidation
108+
109+
## Common Tasks
110+
111+
### Adding a New Storage Backend
112+
1. Create new class in `src/Storage/` implementing `CacheStorageInterface`
113+
2. Add corresponding test in `tests/`
114+
3. Update documentation and examples in README
115+
116+
### Adding a New Caching Strategy
117+
1. Create new class in `src/Strategy/` implementing `CacheStrategyInterface`
118+
2. Add corresponding test in `tests/Strategy/`
119+
3. Update documentation with usage examples
120+
121+
### Bug Fixes
122+
1. Write failing test that reproduces the issue
123+
2. Implement fix in minimal, focused changes
124+
3. Ensure all tests pass
125+
4. Update documentation if behavior changes
126+
127+
## Dependencies and Integration
128+
129+
### Core Dependencies
130+
- `guzzlehttp/guzzle`: HTTP client library
131+
- `guzzlehttp/psr7`: PSR-7 HTTP message implementation
132+
- `guzzlehttp/promises`: Promise implementation
133+
134+
### Optional Dependencies
135+
- `league/flysystem`: For filesystem-based caching
136+
- `psr/cache`: For PSR-6 cache implementations
137+
- `illuminate/cache`: For Laravel framework integration
138+
139+
### Compatibility
140+
- Maintain backward compatibility with existing APIs
141+
- Support multiple versions of dependencies where reasonable
142+
- Test against multiple PHP versions (8.1, 8.2, 8.3, 8.4)
143+
144+
## Contribution Guidelines
145+
146+
### Before Contributing
147+
1. Read the README.md for usage examples
148+
2. Run `make init` to set up development environment
149+
3. Run `make test` to ensure current tests pass
150+
4. Check existing issues and pull requests
151+
152+
### Pull Request Process
153+
1. Create feature branch from main
154+
2. Write tests for new functionality
155+
3. Ensure code follows existing style
156+
4. Update documentation as needed
157+
5. All tests must pass before merging
158+
159+
### Performance Considerations
160+
- Cache operations should be efficient
161+
- Minimize memory usage for large responses
162+
- Consider impact on HTTP request latency
163+
- Profile cache hit/miss ratios in benchmarks

0 commit comments

Comments
 (0)