Skip to content

DEVELOPER_GUIDE.md

Latest commit

 

History

History
534 lines (394 loc) · 12.1 KB

DEVELOPER_GUIDE.md

File metadata and controls

534 lines (394 loc) · 12.1 KB
Raw

🛠️ Developer Guide – Nextcloud Vereins-App

🇩🇪 Deutsch | 🇬🇧 English

Deutsch

Dieses Dokument richtet sich an Entwickler, die zur Vereins-App beitragen oder sie erweitern möchten.

📋 Inhaltsverzeichnis

  1. Voraussetzungen
  2. Entwicklungsumgebung einrichten
  3. Projektstruktur
  4. Architektur
  5. Backend (PHP)
  6. Frontend (Vue 3)
  7. Testing
  8. Deployment
  9. Contributing
  10. Code Style

🔧 Voraussetzungen

Systemanforderungen

Komponente Version Zweck
PHP ≥ 8.0 Backend
Node.js ≥ 18.x Frontend Build
npm ≥ 9.x Package Manager
Composer ≥ 2.x PHP Dependencies
Nextcloud ≥ 28.0 App-Plattform
SQLite/MySQL/PostgreSQL - Datenbank

Empfohlene Tools

  • VS Code mit Extensions: PHP Intelephense, Volar (Vue 3), ESLint
  • Git für Versionskontrolle
  • Postman oder curl für API-Tests

🚀 Entwicklungsumgebung einrichten

1. Repository klonen

cd /path/to/nextcloud/apps
git clone https://github.com/Wacken2012/nextcloud-verein.git verein
cd verein

2. Dependencies installieren

composer install    # PHP Dependencies
npm install         # Frontend Dependencies

3. Frontend bauen

npm run watch       # Watch-Modus (Entwicklung)
npm run build       # Production Build

4. App aktivieren

sudo -u www-data php /var/www/html/nextcloud/occ app:enable verein

📁 Projektstruktur

verein/
├── appinfo/
│   ├── database.xml      # Datenbankschema
│   ├── info.xml          # App-Metadaten
│   └── routes.php        # API-Routen
├── docs/                 # Dokumentation
├── js/
│   ├── components/       # Vue-Komponenten
│   ├── dist/             # Kompilierte Assets
│   ├── App.vue           # Haupt-Vue-App
│   ├── main.js           # Entry Point
│   └── api.js            # API-Client
├── lib/
│   ├── Controller/       # HTTP Controller
│   ├── Db/               # Entities & Mapper
│   ├── Middleware/       # Request Middleware
│   ├── Service/          # Business Logic
│   └── Settings/         # Admin Settings
├── templates/            # PHP Templates
├── tests/                # Unit & Integration Tests
└── vendor/               # Composer Dependencies

🏗️ Architektur

Schichtenmodell

┌─────────────────────────────────────┐
│           Frontend (Vue 3)          │
├─────────────────────────────────────┤
│           Controller (PHP)          │
├─────────────────────────────────────┤
│         Service (Business Logic)    │
├─────────────────────────────────────┤
│           Mapper/DB (ORM)           │
├─────────────────────────────────────┤
│          Nextcloud Core (OCP)       │
└─────────────────────────────────────┘

🐘 Backend (PHP)

Controller erstellen

<?php
namespace OCA\Verein\Controller;

use OCP\AppFramework\Controller;
use OCP\AppFramework\Http\JSONResponse;

class ExampleController extends Controller {
    /**
     * @NoAdminRequired
     * @NoCSRFRequired
     */
    public function index(): JSONResponse {
        return new JSONResponse(['status' => 'ok']);
    }
}

Annotations

Annotation Bedeutung
@NoAdminRequired Nicht-Admins dürfen zugreifen
@NoCSRFRequired Kein CSRF-Token nötig
@PublicPage Öffentlich zugänglich

RBAC-Berechtigungen

use OCA\Verein\Attributes\RequirePermission;

#[RequirePermission('members.create')]
public function create(): JSONResponse {
    // Nur mit members.create Berechtigung
}

⚡ Frontend (Vue 3)

Komponenten-Struktur

<template>
  <NcButton @click="handleClick">
    {{ t('verein', 'Klick mich') }}
  </NcButton>
</template>

<script>
import { NcButton } from '@nextcloud/vue'
import axios from '@nextcloud/axios'
import { generateUrl } from '@nextcloud/router'

export default {
  name: 'ExampleComponent',
  methods: {
    async handleClick() {
      const { data } = await axios.get(generateUrl('/apps/verein/api'))
    }
  }
}
</script>

Notifications

import { success, error } from '../notify.js'

success('Erfolgreich gespeichert')
error('Fehler beim Speichern')

🧪 Testing

# Alle Tests
composer test

# Nur Unit Tests
./vendor/bin/phpunit --testsuite Unit

# Schnelle Tests (Export, Validation)
./vendor/bin/phpunit --testsuite Fast

# Mit Coverage
./vendor/bin/phpunit --coverage-html coverage/

🚢 Deployment

# Deploy Script
./scripts/deploy-to-nextcloud.sh

# Manuell
rsync -av --exclude='node_modules' --exclude='.git' \
  ./ /var/www/html/nextcloud/apps/verein/

🤝 Contributing

  1. Fork & Branch erstellen: git checkout -b feature/mein-feature
  2. Änderungen committen (Conventional Commits)
  3. Pull Request gegen develop Branch

Commit-Format

<type>(<scope>): <description>

feat(members): Add bulk import
fix(export): Correct PDF widths
docs(api): Add OpenAPI spec

📏 Code Style

  • PHP: PSR-12 mit php-cs-fixer
  • JavaScript: ESLint mit Nextcloud-Config
  • Typisierung in PHP (Type Hints, Return Types)
  • Tests für neue Features

English

This document is intended for developers who want to contribute to or extend the Vereins-App.

📋 Table of Contents

  1. Prerequisites
  2. Development Environment Setup
  3. Project Structure
  4. Architecture
  5. Backend (PHP)
  6. Frontend (Vue 3)
  7. Testing
  8. Deployment
  9. Contributing
  10. Code Style

🔧 Prerequisites

System Requirements

Component Version Purpose
PHP ≥ 8.0 Backend
Node.js ≥ 18.x Frontend Build
npm ≥ 9.x Package Manager
Composer ≥ 2.x PHP Dependencies
Nextcloud ≥ 28.0 App Platform
SQLite/MySQL/PostgreSQL - Database

Recommended Tools

  • VS Code with Extensions: PHP Intelephense, Volar (Vue 3), ESLint
  • Git for version control
  • Postman or curl for API testing

🚀 Development Environment Setup

1. Clone Repository

cd /path/to/nextcloud/apps
git clone https://github.com/Wacken2012/nextcloud-verein.git verein
cd verein

2. Install Dependencies

composer install    # PHP Dependencies
npm install         # Frontend Dependencies

3. Build Frontend

npm run watch       # Watch mode (development)
npm run build       # Production build

4. Enable App

sudo -u www-data php /var/www/html/nextcloud/occ app:enable verein

📁 Project Structure

verein/
├── appinfo/
│   ├── database.xml      # Database schema
│   ├── info.xml          # App metadata
│   └── routes.php        # API routes
├── docs/                 # Documentation
├── js/
│   ├── components/       # Vue components
│   ├── dist/             # Compiled assets
│   ├── App.vue           # Main Vue app
│   ├── main.js           # Entry point
│   └── api.js            # API client
├── lib/
│   ├── Controller/       # HTTP controllers
│   ├── Db/               # Entities & mappers
│   ├── Middleware/       # Request middleware
│   ├── Service/          # Business logic
│   └── Settings/         # Admin settings
├── templates/            # PHP templates
├── tests/                # Unit & integration tests
└── vendor/               # Composer dependencies

🏗️ Architecture

Layer Model

┌─────────────────────────────────────┐
│           Frontend (Vue 3)          │
├─────────────────────────────────────┤
│           Controller (PHP)          │
├─────────────────────────────────────┤
│         Service (Business Logic)    │
├─────────────────────────────────────┤
│           Mapper/DB (ORM)           │
├─────────────────────────────────────┤
│          Nextcloud Core (OCP)       │
└─────────────────────────────────────┘

🐘 Backend (PHP)

Creating Controllers

<?php
namespace OCA\Verein\Controller;

use OCP\AppFramework\Controller;
use OCP\AppFramework\Http\JSONResponse;

class ExampleController extends Controller {
    /**
     * @NoAdminRequired
     * @NoCSRFRequired
     */
    public function index(): JSONResponse {
        return new JSONResponse(['status' => 'ok']);
    }
}

Annotations

Annotation Meaning
@NoAdminRequired Non-admins can access
@NoCSRFRequired No CSRF token required
@PublicPage Publicly accessible

RBAC Permissions

use OCA\Verein\Attributes\RequirePermission;

#[RequirePermission('members.create')]
public function create(): JSONResponse {
    // Only with members.create permission
}

⚡ Frontend (Vue 3)

Component Structure

<template>
  <NcButton @click="handleClick">
    {{ t('verein', 'Click me') }}
  </NcButton>
</template>

<script>
import { NcButton } from '@nextcloud/vue'
import axios from '@nextcloud/axios'
import { generateUrl } from '@nextcloud/router'

export default {
  name: 'ExampleComponent',
  methods: {
    async handleClick() {
      const { data } = await axios.get(generateUrl('/apps/verein/api'))
    }
  }
}
</script>

Notifications

import { success, error } from '../notify.js'

success('Successfully saved')
error('Error saving')

🧪 Testing

# All tests
composer test

# Unit tests only
./vendor/bin/phpunit --testsuite Unit

# Fast tests (Export, Validation)
./vendor/bin/phpunit --testsuite Fast

# With coverage
./vendor/bin/phpunit --coverage-html coverage/

🚢 Deployment

# Deploy script
./scripts/deploy-to-nextcloud.sh

# Manual
rsync -av --exclude='node_modules' --exclude='.git' \
  ./ /var/www/html/nextcloud/apps/verein/

🤝 Contributing

  1. Fork & create branch: git checkout -b feature/my-feature
  2. Commit changes (Conventional Commits)
  3. Pull Request against develop branch

Commit Format

<type>(<scope>): <description>

feat(members): Add bulk import
fix(export): Correct PDF widths
docs(api): Add OpenAPI spec

📏 Code Style

  • PHP: PSR-12 with php-cs-fixer
  • JavaScript: ESLint with Nextcloud config
  • Type hints in PHP (Type Hints, Return Types)
  • Tests for new features

📚 Further Resources / Weiterführende Ressourcen

Letzte Aktualisierung / Last updated: 30. November 2025