295 lines
8.1 KiB
Markdown
295 lines
8.1 KiB
Markdown
# Route Package Gap Analysis
|
|
|
|
## Overview
|
|
|
|
This document analyzes the gaps between our Route package's actual implementation and Laravel's routing functionality, identifying areas that need implementation or documentation updates.
|
|
|
|
> **Related Documentation**
|
|
> - See [Route Package Specification](route_package_specification.md) for current implementation
|
|
> - See [Laravel Compatibility Roadmap](laravel_compatibility_roadmap.md) for overall status
|
|
> - See [Foundation Integration Guide](foundation_integration_guide.md) for integration patterns
|
|
> - See [Testing Guide](testing_guide.md) for testing approaches
|
|
> - See [Getting Started Guide](getting_started.md) for development setup
|
|
> - See [Pipeline Package Specification](pipeline_package_specification.md) for middleware pipeline
|
|
> - See [Container Package Specification](container_package_specification.md) for dependency injection
|
|
|
|
## Implementation Gaps
|
|
|
|
### 1. Missing Laravel Features
|
|
```dart
|
|
// Documented but not implemented:
|
|
|
|
// 1. Route Model Binding
|
|
class RouteModelBinding {
|
|
// Need to implement:
|
|
void bind(String key, Type type);
|
|
void bindWhere(String key, Type type, Function where);
|
|
void bindCallback(String key, Function callback);
|
|
void scopeBindings();
|
|
}
|
|
|
|
// 2. Route Caching
|
|
class RouteCache {
|
|
// Need to implement:
|
|
Future<void> cache();
|
|
Future<void> clear();
|
|
bool isEnabled();
|
|
Future<void> reload();
|
|
Future<void> compile();
|
|
}
|
|
|
|
// 3. Route Fallbacks
|
|
class RouteFallback {
|
|
// Need to implement:
|
|
void fallback(dynamic action);
|
|
void missing(Function callback);
|
|
void methodNotAllowed(Function callback);
|
|
void notFound(Function callback);
|
|
}
|
|
```
|
|
|
|
### 2. Missing Route Features
|
|
```dart
|
|
// Need to implement:
|
|
|
|
// 1. Route Constraints
|
|
class RouteConstraints {
|
|
// Need to implement:
|
|
void pattern(String name, String pattern);
|
|
void patterns(Map<String, String> patterns);
|
|
bool matches(String name, String value);
|
|
void whereNumber(List<String> parameters);
|
|
void whereAlpha(List<String> parameters);
|
|
void whereAlphaNumeric(List<String> parameters);
|
|
void whereUuid(List<String> parameters);
|
|
}
|
|
|
|
// 2. Route Substitutions
|
|
class RouteSubstitution {
|
|
// Need to implement:
|
|
void substitute(String key, dynamic value);
|
|
void substituteBindings(Map<String, dynamic> bindings);
|
|
void substituteImplicit(Map<String, Type> bindings);
|
|
String resolveBinding(String key);
|
|
}
|
|
|
|
// 3. Route Rate Limiting
|
|
class RouteRateLimiting {
|
|
// Need to implement:
|
|
void throttle(String name, int maxAttempts, Duration decay);
|
|
void rateLimit(String name, int maxAttempts, Duration decay);
|
|
void forUser(String name, int maxAttempts, Duration decay);
|
|
void exempt(List<String> routes);
|
|
}
|
|
```
|
|
|
|
### 3. Missing Group Features
|
|
```dart
|
|
// Need to implement:
|
|
|
|
// 1. Group Attributes
|
|
class RouteGroupAttributes {
|
|
// Need to implement:
|
|
void controller(Type controller);
|
|
void namespace(String namespace);
|
|
void name(String name);
|
|
void domain(String domain);
|
|
void where(Map<String, String> patterns);
|
|
}
|
|
|
|
// 2. Group Middleware
|
|
class RouteGroupMiddleware {
|
|
// Need to implement:
|
|
void aliasMiddleware(String name, Type middleware);
|
|
void middlewarePriority(List<String> middleware);
|
|
void pushMiddlewareToGroup(String group, String middleware);
|
|
List<String> getMiddlewareGroups();
|
|
}
|
|
|
|
// 3. Group Resources
|
|
class RouteGroupResources {
|
|
// Need to implement:
|
|
void resources(Map<String, Type> resources);
|
|
void apiResources(Map<String, Type> resources);
|
|
void singleton(String name, Type controller);
|
|
void apiSingleton(String name, Type controller);
|
|
}
|
|
```
|
|
|
|
## Documentation Gaps
|
|
|
|
### 1. Missing API Documentation
|
|
```dart
|
|
// Need to document:
|
|
|
|
/// Binds route model.
|
|
///
|
|
/// Example:
|
|
/// ```dart
|
|
/// router.bind('user', User, (value) async {
|
|
/// return await User.find(value);
|
|
/// });
|
|
/// ```
|
|
void bind(String key, Type type, [Function? callback]);
|
|
|
|
/// Defines route pattern.
|
|
///
|
|
/// Example:
|
|
/// ```dart
|
|
/// router.pattern('id', '[0-9]+');
|
|
/// router.get('users/{id}', UsersController)
|
|
/// .where('id', '[0-9]+');
|
|
/// ```
|
|
void pattern(String name, String pattern);
|
|
```
|
|
|
|
### 2. Missing Integration Examples
|
|
```dart
|
|
// Need examples for:
|
|
|
|
// 1. Route Model Binding
|
|
router.bind('user', User);
|
|
|
|
router.get('users/{user}', (User user) {
|
|
return user; // Auto-resolved from ID
|
|
});
|
|
|
|
// 2. Route Rate Limiting
|
|
router.middleware(['throttle:60,1'])
|
|
.group(() {
|
|
router.get('api/users', UsersController);
|
|
});
|
|
|
|
// 3. Route Resources
|
|
router.resources({
|
|
'photos': PhotoController,
|
|
'posts': PostController
|
|
});
|
|
```
|
|
|
|
### 3. Missing Test Coverage
|
|
```dart
|
|
// Need tests for:
|
|
|
|
void main() {
|
|
group('Route Model Binding', () {
|
|
test('resolves bound models', () async {
|
|
router.bind('user', User);
|
|
|
|
var response = await router.dispatch(
|
|
Request('GET', '/users/1')
|
|
);
|
|
|
|
expect(response.data, isA<User>());
|
|
expect(response.data.id, equals('1'));
|
|
});
|
|
});
|
|
|
|
group('Route Caching', () {
|
|
test('caches compiled routes', () async {
|
|
await router.cache();
|
|
|
|
var route = router.match(
|
|
Request('GET', '/users/1')
|
|
);
|
|
|
|
expect(route, isNotNull);
|
|
expect(route!.compiled, isTrue);
|
|
});
|
|
});
|
|
}
|
|
```
|
|
|
|
## Implementation Priority
|
|
|
|
1. **High Priority**
|
|
- Route model binding (Laravel compatibility)
|
|
- Route caching (Laravel compatibility)
|
|
- Route constraints
|
|
|
|
2. **Medium Priority**
|
|
- Route substitutions
|
|
- Route rate limiting
|
|
- Group resources
|
|
|
|
3. **Low Priority**
|
|
- Route fallbacks
|
|
- Additional constraints
|
|
- Performance optimizations
|
|
|
|
## Next Steps
|
|
|
|
1. **Implementation Tasks**
|
|
- Add route model binding
|
|
- Add route caching
|
|
- Add route constraints
|
|
- Add group resources
|
|
|
|
2. **Documentation Tasks**
|
|
- Document model binding
|
|
- Document caching
|
|
- Document constraints
|
|
- Add integration examples
|
|
|
|
3. **Testing Tasks**
|
|
- Add binding tests
|
|
- Add caching tests
|
|
- Add constraint tests
|
|
- Add resource tests
|
|
|
|
## Development Guidelines
|
|
|
|
### 1. Getting Started
|
|
Before implementing routing features:
|
|
1. Review [Getting Started Guide](getting_started.md)
|
|
2. Check [Laravel Compatibility Roadmap](laravel_compatibility_roadmap.md)
|
|
3. Follow [Testing Guide](testing_guide.md)
|
|
4. Use [Foundation Integration Guide](foundation_integration_guide.md)
|
|
5. Review [Route Package Specification](route_package_specification.md)
|
|
6. Review [Pipeline Package Specification](pipeline_package_specification.md)
|
|
7. Review [Container Package Specification](container_package_specification.md)
|
|
|
|
### 2. Implementation Process
|
|
For each routing feature:
|
|
1. Write tests following [Testing Guide](testing_guide.md)
|
|
2. Implement following Laravel patterns
|
|
3. Document following [Getting Started Guide](getting_started.md#documentation)
|
|
4. Integrate following [Foundation Integration Guide](foundation_integration_guide.md)
|
|
|
|
### 3. Quality Requirements
|
|
All implementations must:
|
|
1. Pass all tests (see [Testing Guide](testing_guide.md))
|
|
2. Meet Laravel compatibility requirements
|
|
3. Follow integration patterns (see [Foundation Integration Guide](foundation_integration_guide.md))
|
|
4. Match specifications in [Route Package Specification](route_package_specification.md)
|
|
|
|
### 4. Integration Considerations
|
|
When implementing routing features:
|
|
1. Follow patterns in [Foundation Integration Guide](foundation_integration_guide.md)
|
|
2. Ensure Laravel compatibility per [Laravel Compatibility Roadmap](laravel_compatibility_roadmap.md)
|
|
3. Use testing approaches from [Testing Guide](testing_guide.md)
|
|
4. Follow development setup in [Getting Started Guide](getting_started.md)
|
|
|
|
### 5. Performance Guidelines
|
|
Routing system must:
|
|
1. Match routes efficiently
|
|
2. Handle complex patterns
|
|
3. Support caching
|
|
4. Scale with route count
|
|
5. Meet performance targets in [Laravel Compatibility Roadmap](laravel_compatibility_roadmap.md#performance-benchmarks)
|
|
|
|
### 6. Testing Requirements
|
|
Route tests must:
|
|
1. Cover all route types
|
|
2. Test pattern matching
|
|
3. Verify middleware
|
|
4. Check parameter binding
|
|
5. Follow patterns in [Testing Guide](testing_guide.md)
|
|
|
|
### 7. Documentation Requirements
|
|
Route documentation must:
|
|
1. Explain routing patterns
|
|
2. Show group examples
|
|
3. Cover parameter binding
|
|
4. Include performance tips
|
|
5. Follow standards in [Getting Started Guide](getting_started.md#documentation)
|