Skip to content

Commit f2ce024

Browse files
VitexusVitexus
committed
Refines project standards and updates dependencies
Expands Copilot instructions with detailed coding, testing, and integration guidelines to improve code quality and consistency. Updates multiple PHP and Symfony-related dependencies for enhanced compatibility, performance, and security. Corrects validation command option for JSON files and updates Debian changelog author metadata.
1 parent f96c1c2 commit f2ce024

8 files changed

Lines changed: 1141 additions & 966 deletions

‎.github/copilot-instructions.md‎

Lines changed: 146 additions & 55 deletions
Original file line numberDiff line numberDiff line change
@@ -1,56 +1,147 @@
1-
# Copilot Instructions
2-
3-
<!-- Use this file to provide workspace-specific custom instructions to Copilot. For more details, visit https://code.visualstudio.com/docs/copilot/copilot-customization#_use-a-githubcopilotinstructionsmd-file -->
4-
5-
All code comments should be written in English.
6-
7-
All messages, including error messages, should be written in English.
8-
9-
All code should be written in PHP 8.4 or later.
10-
11-
All code should follow the PSR-12 coding standard.
12-
13-
When writing code, always include a docblock for functions and classes, describing their purpose, parameters, and return types.
14-
15-
When writing tests, use PHPUnit and follow the PSR-12 coding standard.
16-
17-
When writing documentation, use MarkDown format.
18-
19-
When writing commit messages, use the imperative mood and keep them concise.
20-
21-
When writing code comments, use complete sentences and proper grammar.
22-
23-
When writing code, always use meaningful variable names that describe their purpose.
24-
25-
When writing code, avoid using magic numbers or strings; instead, define constants for them.
26-
27-
When writing code, always handle exceptions properly and provide meaningful error messages.
28-
29-
When writing code, always include type hints for function parameters and return types.
30-
31-
We are using the i18n library for internationalization, so always use the _() functions for strings that need to be translated.
32-
33-
When writing code, always ensure that it is secure and does not expose any sensitive information.
34-
35-
When writing code, always consider performance and optimize where necessary.
36-
37-
When writing code, always ensure that it is compatible with the latest version of PHP and the libraries we are using.
38-
39-
When writing code, always ensure that it is well-tested and includes unit tests where applicable.
40-
41-
When writing code, always ensure that it is maintainable and follows best practices.
42-
43-
When create new class or update existing class, always create or update its phpunit test files.
44-
45-
46-
All files in the multiflexi/*.app.json directory must conform to the schema available at: https://raw.githubusercontent.com/VitexSoftware/php-vitexsoftware-multiflexi-core/refs/heads/main/multiflexi.app.schema.json
47-
48-
When modifying or creating multiflexi/*.app.json files, always validate them against the schema before making changes. Use tools to check JSON schema compliance.
49-
50-
All produced reports must conform to the schema available at: https://raw.githubusercontent.com/VitexSoftware/php-vitexsoftware-multiflexi-core/refs/heads/main/multiflexi.report.schema.json
51-
52-
When modifying JSON files or creating new multiflexi applications, always verify the JSON syntax and schema compliance as part of the development process.
53-
54-
When writing code that interacts with the IPEX API, always refer to the official documentation at https://restapi.ipex.cz/swagger.json for guidance on endpoints, parameters, and best practices.
55-
1+
# GitHub Copilot Instructions for AbraFlexi-IPEX
2+
3+
<!-- Custom workspace instructions for GitHub Copilot -->
4+
<!-- Learn more: https://docs.github.com/en/copilot/using-github-copilot/prompt-engineering-for-github-copilot -->
5+
6+
## 📋 Project Overview
7+
This is a PHP-based MultiFlexi application that integrates IPEX VoIP services with AbraFlexi accounting system. The application processes call data, generates invoices, and manages customer billing.
8+
9+
## 🔧 Technical Standards
10+
11+
### Language & Framework Requirements
12+
- **PHP Version**: 8.4+ (use modern PHP features like readonly properties, enums, etc.)
13+
- **Coding Standard**: PSR-12 compliance mandatory
14+
- **Architecture**: Follow SOLID principles and clean code practices
15+
- **Framework**: MultiFlexi framework for application structure
16+
17+
### Code Quality Requirements
18+
- **Documentation**: Every class, method, and function MUST have comprehensive DocBlocks with:
19+
- Purpose description
20+
- @param tags with types and descriptions
21+
- @return tags with types and descriptions
22+
- @throws tags for exceptions
23+
- @example tags where helpful
24+
- **Type Safety**: Always use strict typing (`declare(strict_types=1)`) and type hints
25+
- **Error Handling**: Use proper exception handling with meaningful error messages
26+
- **Variables**: Use descriptive, intention-revealing variable names
27+
- **Constants**: Replace magic numbers/strings with named constants or enums
28+
- **Performance**: Consider performance implications, especially for batch operations
29+
30+
### Testing Requirements
31+
- **Framework**: PHPUnit for all tests
32+
- **Coverage**: Every new class MUST have corresponding test files
33+
- **Location**: Tests go in `tests/` directory mirroring `src/` structure
34+
- **Naming**: Test classes should end with `Test` suffix
35+
- **Standards**: Follow PSR-12 in test code as well
36+
37+
- **Standards**: Follow PSR-12 in test code as well
38+
39+
### Internationalization
40+
- **Library**: Use i18n library for all user-facing strings
41+
- **Function**: Wrap translatable strings with `_()` function
42+
- **Language**: All code, comments, and error messages in English
43+
44+
### Security & Performance
45+
- **Security**: Never expose sensitive information in code or logs
46+
- **Validation**: Always validate user inputs and API responses
47+
- **Logging**: Use appropriate log levels and structured logging
48+
- **Optimization**: Profile and optimize database queries and API calls
49+
50+
## 🔍 Development Workflow
51+
52+
### Mandatory Quality Checks
53+
1. **PHP Syntax Check**: After EVERY PHP file edit, run `php -l filename.php`
54+
2. **Schema Validation**: Before committing, validate JSON files against schemas
55+
3. **Test Execution**: Run relevant tests after code changes
56+
4. **Code Review**: Ensure code follows all standards before committing
57+
58+
### Git Commit Standards
59+
- **Format**: Use imperative mood ("Add feature" not "Added feature")
60+
- **Length**: Keep subject line under 50 characters
61+
- **Body**: Include detailed description for complex changes
62+
- **Scope**: Make atomic commits focused on single changes
63+
64+
## 📊 MultiFlexi Application Standards
65+
66+
### JSON Configuration Files
67+
All `multiflexi/*.app.json` files MUST conform to the official schema:
68+
- **Schema URL**: https://raw.githubusercontent.com/VitexSoftware/php-vitexsoftware-multiflexi-core/refs/heads/main/multiflexi.app.schema.json
69+
- **Validation**: Always validate against schema before modifying
70+
- **Structure**: Follow exact schema requirements for all properties
71+
- **Environment Variables**: Use proper types (string, int, bool) and meaningful descriptions
72+
73+
### Report Generation
74+
Generated reports MUST conform to the MultiFlexi report schema:
75+
- **Schema URL**: https://raw.githubusercontent.com/VitexSoftware/php-vitexsoftware-multiflexi-core/refs/heads/main/multiflexi.report.schema.json
76+
- **Format**: JSON format with proper structure
77+
- **Content**: Include all required fields (timestamp, status, summary, etc.)
78+
79+
### Validation Commands
80+
```bash
81+
# JSON syntax validation
82+
find multiflexi/ -name "*.json" -exec python3 -m json.tool {} \; -print
83+
84+
# Schema validation (requires: pip install jsonschema requests)
85+
python3 -c "
86+
import json, requests, jsonschema, glob
87+
schema = requests.get('https://raw.githubusercontent.com/VitexSoftware/php-vitexsoftware-multiflexi-core/refs/heads/main/multiflexi.app.schema.json').json()
88+
[jsonschema.validate(json.load(open(f)), schema) or print(f'✅ {f} is valid') for f in glob.glob('multiflexi/*.json')]
89+
"
90+
```
91+
92+
## 🔌 API Integration Standards
93+
94+
### IPEX API Integration
95+
- **Documentation**: Always refer to https://restapi.ipex.cz/swagger.json
96+
- **Authentication**: Use proper API credentials management
97+
- **Error Handling**: Handle API timeouts, rate limits, and error responses
98+
- **Data Validation**: Validate all API responses before processing
99+
- **Caching**: Implement appropriate caching for frequently accessed data
100+
101+
### AbraFlexi Integration
102+
- **SDK**: Use official AbraFlexi PHP SDK
103+
- **Transactions**: Wrap related operations in transactions
104+
- **Error Recovery**: Implement proper error recovery mechanisms
105+
- **Data Integrity**: Ensure data consistency between systems
106+
107+
## 🎯 Code Generation Guidelines
108+
109+
When generating code:
110+
111+
1. **Start with interfaces/contracts** before implementations
112+
2. **Use dependency injection** for better testability
113+
3. **Implement proper logging** at appropriate levels
114+
4. **Add configuration validation** for environment variables
115+
5. **Include comprehensive error handling** with user-friendly messages
116+
6. **Write tests first** (TDD approach preferred)
117+
7. **Document complex business logic** with inline comments
118+
8. **Use meaningful method/class names** that express intent
119+
120+
## 🚫 Avoid These Patterns
121+
122+
- Hard-coded values (use configuration/environment variables)
123+
- Silent failures (always log errors appropriately)
124+
- Overly complex methods (follow single responsibility principle)
125+
- Missing type declarations (always use strict typing)
126+
- Inadequate error messages (provide context and solutions)
127+
- Tight coupling between classes (use dependency injection)
128+
- Direct database queries in business logic (use repositories/services)
129+
130+
## 📚 Helpful Context
131+
132+
### Project Structure
133+
- `src/` - Main application code
134+
- `tests/` - PHPUnit test files
135+
- `multiflexi/` - MultiFlexi application configurations
136+
- `bin/` - Executable scripts
137+
- `debian/` - Debian packaging files
138+
139+
### Key Dependencies
140+
- AbraFlexi PHP SDK
141+
- MultiFlexi Core Framework
142+
- mPDF for PDF generation
143+
- Monolog for logging
144+
- PHPUnit for testing
145+
146+
This project integrates VoIP call data from IPEX with AbraFlexi accounting system to automate billing processes for telecommunications services.
56147

‎WARP.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -77,7 +77,7 @@ Environment variables defined in `.env.example`:
7777
Project includes MultiFlexi application definitions in `multiflexi/`:
7878
- JSON schema validation required (see rule about schema compliance)
7979
- Each `.app.json` must conform to MultiFlexi application schema
80-
- Validate with: `multiflexi-cli application validate-json --json multiflexi/[filename].app.json`
80+
- Validate with: `multiflexi-cli application validate-json --file multiflexi/[filename].app.json`
8181

8282
### Debian Packaging
8383
Full Debian packaging support in `debian/` directory with:

0 commit comments

Comments
 (0)