Refactor code structure for improved readability and maintainability
This commit is contained in:
292
custom/docs/tools/VALIDATION_TOOLS.md
Normal file
292
custom/docs/tools/VALIDATION_TOOLS.md
Normal file
@@ -0,0 +1,292 @@
|
||||
# Validierungstools für EspoCRM Custom-Entwicklung
|
||||
|
||||
## Installierte Tools
|
||||
|
||||
### 1. PHP-CLI (v8.2.29)
|
||||
**Zweck:** Validierung von PHP-Syntax
|
||||
|
||||
**Installation:**
|
||||
```bash
|
||||
sudo apt install -y php-cli
|
||||
```
|
||||
|
||||
**Verwendung im Script:**
|
||||
```bash
|
||||
php -l /pfad/zur/datei.php
|
||||
```
|
||||
|
||||
**Validiert:**
|
||||
- PHP-Syntax-Fehler
|
||||
- Parse-Fehler
|
||||
- Fehlende Klammern/Semikolons
|
||||
- Ungültige Funktionsdeklarationen
|
||||
|
||||
---
|
||||
|
||||
### 2. CSSLint (v1.0.4)
|
||||
**Zweck:** CSS-Validierung und Best-Practice-Checks
|
||||
|
||||
**Installation:**
|
||||
```bash
|
||||
sudo apt install -y nodejs npm
|
||||
sudo npm install -g csslint
|
||||
```
|
||||
|
||||
**Verwendung im Script:**
|
||||
```bash
|
||||
csslint --format=compact --quiet /pfad/zur/datei.css
|
||||
```
|
||||
|
||||
**Validiert:**
|
||||
- CSS-Syntax-Fehler
|
||||
- Ungültige Properties
|
||||
- Vendor-Prefix-Probleme
|
||||
- Performance-Probleme
|
||||
- Kompatibilitätsprobleme
|
||||
|
||||
**Konfiguration:**
|
||||
Das Script verwendet standardmäßig alle csslint-Regeln. Für custom Rules kann eine `.csslintrc` Datei erstellt werden.
|
||||
|
||||
---
|
||||
|
||||
### 3. JSHint (v2.13.6)
|
||||
**Zweck:** JavaScript-Code-Qualität und Syntax-Validierung
|
||||
|
||||
**Installation:**
|
||||
```bash
|
||||
sudo npm install -g jshint
|
||||
```
|
||||
|
||||
**Verwendung im Script:**
|
||||
```bash
|
||||
jshint --config=/dev/null /pfad/zur/datei.js
|
||||
```
|
||||
|
||||
**Validiert:**
|
||||
- JavaScript-Syntax-Fehler
|
||||
- Potenzielle Bugs
|
||||
- Code-Style-Probleme
|
||||
- Ungültige Variablen-Deklarationen
|
||||
- Scope-Probleme
|
||||
|
||||
**Konfiguration:**
|
||||
Aktuell nutzt das Script minimale Konfiguration. Für erweiterte Checks kann eine `.jshintrc` Datei erstellt werden:
|
||||
|
||||
```json
|
||||
{
|
||||
"esversion": 6,
|
||||
"browser": true,
|
||||
"jquery": true,
|
||||
"unused": true,
|
||||
"undef": true
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Integration im Validierungsscript
|
||||
|
||||
Das Script `custom/scripts/validate_and_rebuild.py` nutzt diese Tools automatisch:
|
||||
|
||||
### Automatische Erkennung
|
||||
```python
|
||||
# Prüft ob Tool verfügbar ist
|
||||
try:
|
||||
subprocess.run(['csslint', '--version'], capture_output=True)
|
||||
use_csslint = True
|
||||
except FileNotFoundError:
|
||||
use_csslint = False
|
||||
# Fallback auf Basis-Validierung
|
||||
```
|
||||
|
||||
### Fallback-Mechanismus
|
||||
Falls ein Tool nicht verfügbar ist, verwendet das Script eine Basis-Validierung:
|
||||
|
||||
- **CSS:** Klammer-Matching, Attribut-Selektoren
|
||||
- **JavaScript:** Klammer-Matching (rund, eckig, geschweift)
|
||||
- **PHP:** Übersprungen mit Warnung
|
||||
|
||||
---
|
||||
|
||||
## Validierungsebenen
|
||||
|
||||
### Kritische Fehler (Rebuild wird abgebrochen)
|
||||
- JSON-Syntax-Fehler
|
||||
- PHP-Syntax-Fehler
|
||||
- CSS-Syntax-Fehler (schwerwiegend)
|
||||
- JavaScript-Syntax-Fehler
|
||||
- Fehlende Relationship-Definitionen
|
||||
|
||||
### Warnungen (Rebuild wird fortgesetzt)
|
||||
- CSS-Best-Practice-Verletzungen
|
||||
- Fehlende i18n-Übersetzungen
|
||||
- Code-Style-Probleme
|
||||
- Performance-Hinweise
|
||||
|
||||
---
|
||||
|
||||
## Manuelle Verwendung der Tools
|
||||
|
||||
### CSS prüfen
|
||||
```bash
|
||||
# Einzelne Datei
|
||||
csslint client/custom/css/my-styles.css
|
||||
|
||||
# Alle CSS-Dateien
|
||||
find client/custom/css -name "*.css" -exec csslint {} \;
|
||||
|
||||
# Mit spezifischen Regeln
|
||||
csslint --errors=errors,duplicate-properties client/custom/css/
|
||||
```
|
||||
|
||||
### JavaScript prüfen
|
||||
```bash
|
||||
# Einzelne Datei
|
||||
jshint client/custom/src/views/my-view.js
|
||||
|
||||
# Alle JS-Dateien
|
||||
find client/custom/src -name "*.js" -exec jshint {} \;
|
||||
|
||||
# Mit Konfiguration
|
||||
jshint --config .jshintrc client/custom/src/
|
||||
```
|
||||
|
||||
### PHP prüfen
|
||||
```bash
|
||||
# Einzelne Datei
|
||||
php -l custom/Espo/Custom/Classes/MyClass.php
|
||||
|
||||
# Alle PHP-Dateien
|
||||
find custom/Espo -name "*.php" -exec php -l {} \; | grep -v "No syntax errors"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Zusätzliche empfohlene Tools (optional)
|
||||
|
||||
### 1. ESLint (moderne Alternative zu JSHint)
|
||||
```bash
|
||||
sudo npm install -g eslint
|
||||
eslint --init # Erstellt .eslintrc Konfiguration
|
||||
```
|
||||
|
||||
### 2. Stylelint (moderne Alternative zu CSSLint)
|
||||
```bash
|
||||
sudo npm install -g stylelint stylelint-config-standard
|
||||
# Benötigt .stylelintrc Konfiguration
|
||||
```
|
||||
|
||||
### 3. PHPStan (statische PHP-Analyse)
|
||||
```bash
|
||||
composer require --dev phpstan/phpstan
|
||||
vendor/bin/phpstan analyse custom/Espo
|
||||
```
|
||||
|
||||
### 4. PHP_CodeSniffer (PHP Code-Style)
|
||||
```bash
|
||||
sudo apt install -y php-codesniffer
|
||||
phpcs --standard=PSR12 custom/Espo/
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Tool nicht gefunden
|
||||
```bash
|
||||
# Prüfe Installation
|
||||
which csslint
|
||||
which jshint
|
||||
which php
|
||||
|
||||
# Installiere fehlende Tools
|
||||
sudo apt update
|
||||
sudo apt install -y nodejs npm php-cli
|
||||
sudo npm install -g csslint jshint
|
||||
```
|
||||
|
||||
### Validierung zu streng
|
||||
Bearbeite das Script und passe die Tool-Parameter an:
|
||||
```python
|
||||
# Weniger strikte CSS-Validierung
|
||||
result = subprocess.run(
|
||||
['csslint', '--format=compact', '--errors=errors', str(css_file)],
|
||||
...
|
||||
)
|
||||
```
|
||||
|
||||
### Performance-Probleme
|
||||
Für große Projekte mit vielen Dateien:
|
||||
```python
|
||||
# Parallele Validierung mit ThreadPoolExecutor
|
||||
from concurrent.futures import ThreadPoolExecutor
|
||||
|
||||
with ThreadPoolExecutor(max_workers=4) as executor:
|
||||
results = executor.map(validate_css_file, css_files)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Best Practices
|
||||
|
||||
1. **Vor jedem Commit:** Führe Validierung aus
|
||||
```bash
|
||||
python3 custom/scripts/validate_and_rebuild.py --dry-run
|
||||
```
|
||||
|
||||
2. **Automatisierung:** Integriere in Git pre-commit hook
|
||||
```bash
|
||||
# .git/hooks/pre-commit
|
||||
#!/bin/bash
|
||||
python3 custom/scripts/validate_and_rebuild.py --dry-run
|
||||
if [ $? -ne 0 ]; then
|
||||
echo "Validierung fehlgeschlagen. Commit abgebrochen."
|
||||
exit 1
|
||||
fi
|
||||
```
|
||||
|
||||
3. **CI/CD Integration:** Nutze in Build-Pipeline
|
||||
```yaml
|
||||
# .gitlab-ci.yml / .github/workflows/
|
||||
validate:
|
||||
script:
|
||||
- python3 custom/scripts/validate_and_rebuild.py --dry-run
|
||||
```
|
||||
|
||||
4. **IDE Integration:** Konfiguriere Editor für Live-Feedback
|
||||
- VSCode: ESLint/Stylelint Extensions
|
||||
- PHPStorm: Built-in PHP/JS/CSS Validierung
|
||||
|
||||
---
|
||||
|
||||
## Maintenance
|
||||
|
||||
### Updates der Tools
|
||||
```bash
|
||||
# System-Packages
|
||||
sudo apt update && sudo apt upgrade
|
||||
|
||||
# NPM-Packages
|
||||
sudo npm update -g csslint jshint
|
||||
|
||||
# Prüfe Versionen
|
||||
php --version
|
||||
csslint --version
|
||||
jshint --version
|
||||
```
|
||||
|
||||
### Entfernung
|
||||
```bash
|
||||
# NPM-Tools
|
||||
sudo npm uninstall -g csslint jshint
|
||||
|
||||
# APT-Packages
|
||||
sudo apt remove php-cli nodejs npm
|
||||
sudo apt autoremove
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
**Letzte Aktualisierung:** Januar 2026
|
||||
**Maintainer:** Custom Scripts Team
|
||||
**Dokumentation:** `custom/scripts/VALIDATION_TOOLS.md`
|
||||
Reference in New Issue
Block a user