[RFC]: create a public LLM or stuff in order to have a manual about how to use DK API

[arhimede]

RFC

Q	A
Proposed Version(s)	1.0.0
BC Break?	Yes

Goal

Considerations

Proposal(s)

Appendix

[arhimede]

dotkernel_php_book.md

[arhimede]

Perfect ✅

I’ll now generate a complete beginner-friendly PHP + Dotkernel API book in Markdown format — ready for GitHub, Notion, or to convert into PDF later.

It will include 12+ chapters with practical examples, explanations, and step-by-step instructions.

---

📘 Building APIs in PHP with Dotkernel: A Beginner’s Guide

---

Table of Contents

1. [Introduction](#chapter-1--introduction)
2. [Setting Up Your Environment](#chapter-2--setting-up-your-environment)
3. [Your First Route](#chapter-3--your-first-route)
4. [Understanding Configuration & Dependency Injection](#chapter-4--understanding-configuration--dependency-injection)
5. [Middlewares and Handlers](#chapter-5--middlewares-and-handlers)
6. [Creating Entities and Using Doctrine ORM](#chapter-6--creating-entities-and-using-doctrine-orm)
7. [Building the Articles Module](#chapter-7--building-the-articles-module)
8. [Creating, Updating, and Deleting Data](#chapter-8--creating-updating-and-deleting-data)
9. [Error Handling and Logging](#chapter-9--error-handling-and-logging)
10. [Authentication and Authorization](#chapter-10--authentication-and-authorization)
11. [Testing Your API](#chapter-11--testing-your-api)
12. [Deploying Your API](#chapter-12--deploying-your-api)
13. [Appendices](#appendices)

---

Chapter 1 — Introduction

Welcome to Dotkernel — a modern PHP framework for building APIs on top of Laminas (formerly Zend Framework).

Dotkernel helps you build modular, PSR-compliant REST APIs efficiently and cleanly.

Why Choose Dotkernel?

• ✅ Built on industry standards (PSR-7, PSR-11, PSR-15)
• ✅ Modular architecture
• ✅ Built-in support for middlewares and dependency injection
• ✅ Compatible with Doctrine ORM
• ✅ Open source and actively maintained

What You’ll Learn

By the end of this book, you’ll know how to:

• Install and configure a PHP + Dotkernel environment
• Create API endpoints
• Connect to a database using Doctrine
• Implement authentication and error handling
• Deploy your application to production

---

Chapter 2 — Setting Up Your Environment

Requirements

• PHP 8.2+
• Composer (Dependency manager)
• MySQL or PostgreSQL
• Git (optional)
• A local web server (PHP built-in server works fine)

Installing Dotkernel API Skeleton

composer create-project dotkernel/api my-api
cd my-api

Folder Structure Overview

project/
├── config/
├── data/
├── public/
├── src/
│   └── App/
│       └── Handler/
├── vendor/
└── composer.json

Running the Application

php -S 0.0.0.0:8080 -t public

Visit http://localhost:8080 to confirm it works.

---

Chapter 3 — Your First Route

Step 1: Create a Handler

In src/App/Handler/HelloHandler.php:

<?php

namespace App\Handler;

use Psr\Http\Message\ResponseInterface;
use Psr\Http\Message\ServerRequestInterface;
use Laminas\Diactoros\Response\JsonResponse;

class HelloHandler
{
    public function handle(ServerRequestInterface $request): ResponseInterface
    {
        return new JsonResponse([
            'message' => 'Hello from Dotkernel!',
            'timestamp' => date('Y-m-d H:i:s'),
        ]);
    }
}

Step 2: Register the Route

In src/App/ConfigProvider.php:

[
    'name' => 'api.hello',
    'path' => '/api/hello',
    'middleware' => \App\Handler\HelloHandler::class,
    'allowed_methods' => ['GET'],
],

Step 3: Test It

GET http://localhost:8080/api/hello

You should see:

{
  "message": "Hello from Dotkernel!",
  "timestamp": "2025-10-20 10:00:00"
}

---

Chapter 4 — Understanding Configuration & Dependency Injection

Dotkernel uses ConfigProviders to define services, routes, and dependencies.

Example ConfigProvider

<?php
namespace App;

use App\Handler\HelloHandler;

class ConfigProvider
{
    public function __invoke(): array
    {
        return [
            'dependencies' => [
                'factories' => [
                    HelloHandler::class => function($container) {
                        return new HelloHandler();
                    }
                ],
            ],
        ];
    }
}

---

Chapter 5 — Middlewares and Handlers

Dotkernel follows PSR-15 middleware pattern:

• A middleware receives a request, processes it, and optionally delegates it.
• A handler is the endpoint that produces the response.

Example Middleware Chain:

1. Authentication Middleware
2. Validation Middleware
3. Handler

---

Chapter 6 — Creating Entities and Using Doctrine ORM

Step 1: Install Doctrine ORM

composer require doctrine/orm
composer require dotkernel/dot-doctrine

Step 2: Configure Doctrine

In config/autoload/doctrine.global.php:

return [
    'doctrine' => [
        'connection' => [
            'orm_default' => [
                'driverClass' => \Doctrine\DBAL\Driver\PDOMySql\Driver::class,
                'params' => [
                    'host' => 'localhost',
                    'port' => 3306,
                    'user' => 'root',
                    'password' => '',
                    'dbname' => 'dotkernel_api',
                ],
            ],
        ],
    ],
];

Step 3: Create an Entity

src/Article/Entity/Article.php:

<?php

namespace Article\Entity;

use Doctrine\ORM\Mapping as ORM;

/**
 * @ORM\Entity
 * @ORM\Table(name="articles")
 */
class Article
{
    /** @ORM\Id @ORM\GeneratedValue @ORM\Column(type="integer") */
    private int $id;

    /** @ORM\Column(type="string") */
    private string $title;

    /** @ORM\Column(type="text") */
    private string $content;

    /** @ORM\Column(type="datetime") */
    private \DateTime $createdAt;

    public function __construct(string $title, string $content)
    {
        $this->title = $title;
        $this->content = $content;
        $this->createdAt = new \DateTime();
    }

    // Getters omitted for brevity
}

---

Chapter 7 — Building the Articles Module

Create structure:

src/
 └── Article/
     ├── ConfigProvider.php
     ├── Handler/
     │   └── ListArticlesHandler.php
     └── Entity/
         └── Article.php

ListArticlesHandler.php:

<?php

namespace Article\Handler;

use Psr\Http\Message\ResponseInterface;
use Psr\Http\Message\ServerRequestInterface;
use Doctrine\ORM\EntityManager;
use Laminas\Diactoros\Response\JsonResponse;
use Article\Entity\Article;

class ListArticlesHandler
{
    public function __construct(private EntityManager $em) {}

    public function handle(ServerRequestInterface $request): ResponseInterface
    {
        $articles = $this->em->getRepository(Article::class)->findAll();
        $data = [];

        foreach ($articles as $article) {
            $data[] = [
                'id' => $article->getId(),
                'title' => $article->getTitle(),
                'content' => $article->getContent(),
                'created_at' => $article->getCreatedAt()->format('Y-m-d H:i:s'),
            ];
        }

        return new JsonResponse(['articles' => $data]);
    }
}

---

Chapter 8 — Creating, Updating, and Deleting Data

Create Article (POST /api/articles)

Handler:

<?php

namespace Article\Handler;

use Doctrine\ORM\EntityManager;
use Laminas\Diactoros\Response\JsonResponse;
use Psr\Http\Message\ResponseInterface;
use Psr\Http\Message\ServerRequestInterface;
use Article\Entity\Article;

class CreateArticleHandler
{
    public function __construct(private EntityManager $em) {}

    public function handle(ServerRequestInterface $request): ResponseInterface
    {
        $data = json_decode($request->getBody()->getContents(), true);

        $article = new Article($data['title'], $data['content']);
        $this->em->persist($article);
        $this->em->flush();

        return new JsonResponse(['message' => 'Article created'], 201);
    }
}

---

Chapter 9 — Error Handling and Logging

Install logger:

composer require dotkernel/dot-logger

Add to config:

'log' => [
    'writers' => [
        [
            'name' => 'stream',
            'options' => ['stream' => 'data/log/app.log'],
        ],
    ],
],

Use it inside handlers to record errors.

---

Chapter 10 — Authentication and Authorization

Use JWT for stateless API authentication.

Install:

composer require firebase/php-jwt

Add middleware to validate Authorization: Bearer <token> headers.

---

Chapter 11 — Testing Your API

Install PHPUnit:

composer require --dev phpunit/phpunit

Example test:

<?php
use PHPUnit\Framework\TestCase;

class HelloHandlerTest extends TestCase
{
    public function testResponse()
    {
        $handler = new \App\Handler\HelloHandler();
        $response = $handler->handle(new \Laminas\Diactoros\ServerRequest());
        $this->assertEquals(200, $response->getStatusCode());
    }
}

Run:

vendor/bin/phpunit

---

Chapter 12 — Deploying Your API

Environment Variables

Use .env for secrets and environment-specific settings.

Docker Example

Dockerfile:

FROM php:8.2-apache
COPY . /var/www/html
RUN docker-php-ext-install pdo pdo_mysql

---

Appendices

A. Useful Dotkernel Packages

• dotkernel/dot-auth – Authentication module
• dotkernel/dot-event – Event system
• dotkernel/dot-errorhandler – Error handling
• dotkernel/dot-logger – Logging

B. Dotkernel vs Other Frameworks

• Slim – Minimal, but lacks structure
• Laravel – Powerful, but heavy
• Dotkernel – Lightweight, modular, enterprise-friendly

---

🎯 Next Steps

You now have the foundation to:

• Build modular PHP APIs
• Connect databases with Doctrine
• Implement JWT-based authentication
• Deploy your Dotkernel API confidently

Keep learning by exploring:

• https://github.com/dotkernel
• https://docs.laminas.dev/

---

Would you like me to export this Markdown file (dotkernel_php_book.md) so you can download it?