README

A comprehensive PHP application framework for building modern web applications with multi-module architecture, complete user management, and enterprise-grade features.

Features
Requirements
Installation
Architecture
Core Components
Configuration
Usage Examples
Development
Testing
Release Management

Features

The Baukasten Framework provides a complete application foundation with:

Core Features

User Authentication & Authorization - Complete auth system with roles, permissions, and session management
MVC-like Architecture - Clean separation of concerns with Controllers, Services, Repositories, and Entities
Multi-module Support - Built-in support for admin, api, website, app, tasks, and worker modules
Database ORM - Annotation-based entity mapping with repository pattern
Attribute-based Routing - Modern PHP 8+ attribute routing for controllers

Advanced Features

REST API Support - Full webservice/API endpoint capabilities
Cron Job & Task Scheduling - Background job processing and scheduled tasks
Analytics & Logging - Application analytics, query logs, and user activity tracking
Push Notifications - Web push notification service with subscriber management
Email Services - Complete mail service with templates and authentication emails
Image Generation & Optimization - Template-based image generation and optimization
PDF Generation - HTML to PDF conversion capabilities
Social Integration - OAuth2 support for Facebook, Instagram, Google, LinkedIn, Twitter, Reddit
Payment Processing - Stripe integration for commerce and subscriptions
Resource Management - CSS/JS dependency injection, minification, and optimization
Internationalization - Built-in i18n support (German and English included)
SEO Features - Redirects management, sitemaps, and analytics tracking
Component System - Pre-built UI components for forms, tables, dialogs, and admin interfaces

Requirements

Runtime Requirements

PHP: ^8.2
PHP Extensions:
- DOM, libxml
- curl, simplexml
- GD, exif
- JSON, fileinfo
- openssl, mysqli
- mbstring

Dependencies

Core Baukasten Packages

{
  "baukasten/core": "^0.4",
  "baukasten/orm": "^0.1",
  "baukasten/cache": "^0.0",
  "baukasten/components": "^0.0",
  "baukasten/webservice": "^0.1"
}

Development Dependencies

PHPUnit ^9 - Testing framework
Mockery 1.6.11 - Mocking library
vfsStream 1.6.11 - Virtual filesystem for tests

Installation

Using Composer

composer require baukasten/framework

Development Installation

For development with extended dependencies:

COMPOSER=composer-dev.json composer update --ignore-platform-reqs

This installs additional development dependencies including OAuth providers, payment gateways, and more.

Architecture

The Baukasten Framework follows MVC + Service + Repository Pattern with clean architecture principles.

Modules

The framework supports multiple application modules for different contexts:

admin - Administrative backend interface
api - REST API endpoints
website - Public-facing website
app - User application area
tasks - Scheduled task execution
worker - Background worker processes

Each module has its own:

Page classes for rendering
Controllers for request handling
Services for business logic
Module-specific initialization

Design Patterns

Request Flow for Web Pages

Request → Controller → Service → Page → Response
                         ↓
                    Repository → Entity → Database

Example:

// Controller handles request
AdminController → UserService → AdminUserPage

// Service fetches data
UserService → UserRepository → User Entity → Database

Request Flow for API Endpoints

Request → Controller → Service → Repository → Entity → Database
                         ↓
JSON Response ← Service ← Repository

Directory Structure

src/
├── AsyncHandler/          # Asynchronous request handlers
├── Builder/               # Builder pattern implementations
├── Component/             # UI components (forms, dialogs, tables)
├── Config/                # Configuration classes
├── Controller/            # Request controllers
│   ├── Admin/             # Admin-specific controllers
│   └── App/               # App-specific controllers
├── Cronjob/               # Scheduled task definitions
├── Entity/                # ORM entities (26 entities)
├── Enum/                  # Enumeration types
├── Helper/                # Helper classes
├── Middleware/            # Request middleware
├── Model/                 # Data models
├── Modules/               # Module handlers
├── Pages/                 # Page rendering classes
│   ├── Admin/             # Admin pages
│   └── App/               # Application pages
├── PageStructure/         # Abstract page structures
├── Repository/            # Data access layer (24 repositories)
├── Routing/               # Route configuration
├── Scaffolding/           # Code generation
├── Service/               # Business logic (50+ services)
│   ├── Admin/             # Admin services
│   ├── App/               # App services
│   └── RolePermission/    # Authorization services
├── Shortcode/             # Shortcode processing
├── Task/                  # Background tasks
└── Worker/                # Worker base classes

resources/
├── i18n/                  # Translations (de.json, en.json)
├── js/                    # JavaScript utilities
├── css/                   # Stylesheets
├── component/             # Component-specific resources
└── migration/             # Database migrations

Core Components

Authentication & Authorization

User Management

use Baukasten\Framework\Service\UserService;
use Baukasten\Framework\Service\UserAuthService;

// User authentication
$authService = new UserAuthService($userRepository);
$user = $authService->authenticate($email, $password);

// User management
$userService = new UserService($userRepository);
$user = $userService->createUser($email, $password, $role);

Role-Based Access Control

use Baukasten\Framework\Middleware\HasPermission;
use Baukasten\Framework\Middleware\IsAdmin;

// Controller with middleware
#[HasPermission('user.edit')]
public function editUser() { }

#[IsAdmin]
public function adminDashboard() { }

Available Middleware

IsLoggedIn - Requires authenticated user
IsAdmin - Requires admin role
HasPermission - Requires specific permission
HasTablePermission - Requires table-level permission

Database & ORM

Entity Definition

use Baukasten\Framework\Entity\Entity;

#[Entity("users")]
class User {
    #[PrimaryKey]
    #[Column]
    public int $id;

    #[Column]
    public string $email;

    #[Column]
    public string $password;
}

Repository Pattern

use Baukasten\Framework\Repository\UserRepository;

class UserRepository extends Repository {
    public function findByEmail(string $email): ?User {
        return $this->findOne(['email' => $email]);
    }
}

Available Entities

User, UserRole, UserSession
ApplicationAnalytics
Bouncer, BouncerCondition
PushNotification, PushSubscriber
Cronjob, CronjobLog
Redirect, ShortUrl
And 15+ more

Controllers & Routing

Attribute-Based Routing

use Baukasten\Framework\Controller\Controller;

class AdminController extends Controller {
    #[Get('/admin/users')]
    public function listUsers() {
        $users = $this->userService->getAllUsers();
        return new AdminUsersPage($users);
    }

    #[Post('/admin/users')]
    public function createUser() {
        $data = $this->request->getPost();
        $user = $this->userService->createUser($data);
        return $this->json(['success' => true, 'user' => $user]);
    }
}

Services & Business Logic

Services contain business logic and coordinate between controllers and repositories:

use Baukasten\Framework\Service\Service;

class UserService extends Service {
    public function __construct(
        private UserRepository $userRepository,
        private MailService $mailService
    ) {}

    public function createUser(array $data): User {
        $user = new User();
        $user->email = $data['email'];
        $user->password = password_hash($data['password'], PASSWORD_DEFAULT);

        $this->userRepository->save($user);
        $this->mailService->sendWelcomeEmail($user);

        return $user;
    }
}

Available Services

User: UserService, UserAuthService, UserSessionService
Communication: MailService, PushNotificationService, AuthMailService
Content: FileService, ImageService, ImageGeneratorService
Analytics: ApplicationAnalyticsService, QueryLogService
Admin: Various admin-specific services
Background: CronjobService, TaskService
And 40+ more specialized services

UI Components

The framework includes pre-built UI components:

use Baukasten\Framework\Component\Form\FormComponent;
use Baukasten\Framework\Component\Table\TableComponent;
use Baukasten\Framework\Component\Dialog\DialogComponent;

// Form component
$form = new FormComponent();
$form->addTextField('email', 'Email Address');
$form->addPasswordField('password', 'Password');
$form->addSubmitButton('Login');

// Table component
$table = new TableComponent();
$table->addColumn('email', 'Email');
$table->addColumn('created_at', 'Created');
$table->setData($users);

// Dialog component
$dialog = new DialogComponent('Confirm', 'Are you sure?');

Configuration

Framework Configuration

use Baukasten\Framework\Config\BaukastenConfig;

class AppConfig extends BaukastenConfig {
    public function getDatabaseConfig(): array {
        return [
            'host' => 'localhost',
            'database' => 'app_db',
            'username' => 'user',
            'password' => 'pass'
        ];
    }
}

Environment Setup

Use the BaukastenEnvHelper for environment-specific configuration:

use Baukasten\Framework\Helper\BaukastenEnvHelper;

$env = BaukastenEnvHelper::getEnvironment();
$debug = BaukastenEnvHelper::isDebugMode();

Usage Examples

Creating a New Page

use Baukasten\Framework\Pages\Page;

class DashboardPage extends Page {
    public function __construct(
        private array $stats
    ) {
        parent::__construct();
    }

    public function render(): string {
        return $this->template('dashboard', [
            'stats' => $this->stats
        ]);
    }
}

Scheduling a Cronjob

use Baukasten\Framework\Cronjob\AbstractCronjob;

class DailySummary extends AbstractCronjob {
    public function execute(): void {
        $users = $this->userRepository->findAll();
        foreach ($users as $user) {
            $this->mailService->sendDailySummary($user);
        }
    }

    public function getSchedule(): string {
        return '0 9 * * *'; // Daily at 9 AM
    }
}

Creating a Background Task

use Baukasten\Framework\Task\AbstractTask;

class ProcessUploads extends AbstractTask {
    public function execute(array $params): void {
        $fileId = $params['file_id'];
        $file = $this->fileRepository->find($fileId);
        $this->imageService->optimize($file);
    }
}

Using Push Notifications

use Baukasten\Framework\Service\PushNotificationService;

$pushService = new PushNotificationService($pushRepo, $subscriberRepo);

// Send notification
$pushService->sendNotification(
    $userId,
    'New Message',
    'You have a new message!',
    '/messages'
);

OAuth Integration

use Baukasten\Framework\Controller\OAuthController;

// OAuth flow is handled by OAuthController
// Supports: Facebook, Instagram, Google, LinkedIn, Twitter, Reddit

Analytics Tracking

use Baukasten\Framework\Service\ApplicationAnalyticsService;

$analyticsService->trackPageView($userId, $page);
$analyticsService->trackEvent($userId, 'purchase', $metadata);

Development

Project Setup

Clone the repository

Install dependencies:

COMPOSER=composer-dev.json composer install --ignore-platform-reqs

Configure your database
Run migrations:
```
php src/DatabaseMigrationRunner.php
```

Code Generation

Use scaffolding to generate boilerplate code:

use Baukasten\Framework\Scaffolding\EntityScaffold;

$scaffold = new EntityScaffold();
$scaffold->generateEntity('Product', ['name', 'price', 'description']);

Dependency Management

Use the DependencyHelper for managing CSS/JS resources:

use Baukasten\Framework\Helper\DependencyHelper;

DependencyHelper::addScript('app.js');
DependencyHelper::addStyle('app.css');
DependencyHelper::addDependency('jquery');

Testing

Running Tests

Execute the test suite using PHPUnit:

/bin/bash .run-phpunit.sh

Or directly:

./vendor/bin/phpunit

Test Configuration

Tests are configured in phpunit.xml with:

Coverage reporting
Bootstrap autoloading
Test suite definitions

Writing Tests

use PHPUnit\Framework\TestCase;
use Mockery;

class UserServiceTest extends TestCase {
    public function testCreateUser() {
        $repo = Mockery::mock(UserRepository::class);
        $service = new UserService($repo);

        $user = $service->createUser([
            'email' => 'test@example.com',
            'password' => 'secure123'
        ]);

        $this->assertInstanceOf(User::class, $user);
    }
}

Release Management

Semantic Versioning

The project uses semantic versioning with automated releases via GitLab CI/CD.

Setup Release Tokens

Create a Personal Access Token at https://gitlab.com/-/user_settings/personal_access_tokens
Add token as CUSTOM_PUSH_TOKEN CI/CD variable in your GitLab project
Configure .releaserc.json for release rules

Version History

0.0.27 - Current version
Regular updates and dependency maintenance
See commit history for detailed changelog

Displaying Webpages

The recommended pattern for displaying webpages:

Controller → Service → Page

Example:

class AdminController {
    #[Get('/admin/dashboard')]
    public function dashboard() {
        $stats = $this->statsService->getDashboardStats();
        return new AdminDashboardPage($stats);
    }
}

Interacting with the Database

The recommended pattern for database interaction:

Service → Repository → Entity