<!-- ============================================================ -->
<!-- android/listen-for-android-install-referrer.md -->
<!-- ============================================================ -->

---
title: "Listen for Android install referrer"
description: "Android market broadcasts an intent containing referrer information at install time, before the app is opened, which can be used for install tracking."
author: "n3vrax"
date_published: "2011-07-24"
canonical_url: "https://www.dotkernel.com/android/listen-for-android-install-referrer/"
category: "Android"
language: "en"
---

# Listen for Android install referrer

## Getting Referrer Data at Install Time

Android market sends information at the moment of app install, delivered as a broadcasted intent by Android market at install time - even before the app is opened for the first time.
This can be used to create custom links to an Android application, including bits of information about the referrer, sent directly to the app for processing at install.
It can be a simple and accurate solution for mobile app install tracking, among other uses.

## FAQ

**Q: Does Android send information when the app is installed?**
A: Yes.
Android market broadcasts an intent containing referrer information at the moment the app is installed.

**Q: When is this referrer information available to the app?**
A: It's delivered as a broadcasted intent at install time, before the app is ever opened.


<!-- ============================================================ -->
<!-- android/multiple-broadcast-receivers-in-the-same-app-for-the-same-action.md -->
<!-- ============================================================ -->

---
title: "Multiple broadcast receivers in the same app, for the same action"
description: "Using multiple broadcast receivers to listen separately for the same intent in the same Android app can lead to unexpected results, since one receiver may consume the broadcast and leave the others with nothing."
author: "n3vrax"
date_published: "2011-07-22"
canonical_url: "https://www.dotkernel.com/android/multiple-broadcast-receivers-in-the-same-app-for-the-same-action/"
category: "Android"
language: "en"
---

# Multiple broadcast receivers in the same app, for the same action

## The problem

When multiple broadcast receivers are registered separately to listen for the same intent within the same Android app, this can lead to unexpected results: one broadcast receiver might consume the broadcasted intent, leaving the others with nothing to receive.
This can happen when using 3rd party libraries that define their own broadcast receivers alongside an app's own receivers.

## The approach

A solution for this kind of problem is a code snippet inspired by the way Admob for Android solves this, as shown in Admob's own documentation, using meta-data in the manifest file.

## FAQ

**Q: What problem does this article address?**
A: When multiple broadcast receivers are registered separately to listen for the same intent in the same Android app, this can lead to unexpected results: one broadcast receiver might consume the broadcasted intent, leaving the others with nothing to receive.

**Q: When is this issue most likely to occur?**
A: This can happen when you use 3rd party libraries that already define their own broadcast receivers alongside your app's own receivers.

## Resources

- [Admob App Download Tracking documentation](http://developer.admob.com/wiki/Android_App_Download_Tracking)


<!-- ============================================================ -->
<!-- architecture/configprovider-bootstrap-modern-php-applications.md -->
<!-- ============================================================ -->

---
title: "ConfigProvider - Bootstrap Modern PHP Applications"
description: "An overview of the ConfigProvider pattern used in Laminas/Mezzio-based applications, including Dotkernel, to bootstrap middleware pipelines and dependency injection."
author: "Florin Bidirean"
date_published: "2025-08-20"
canonical_url: "https://www.dotkernel.com/architecture/configprovider-bootstrap-modern-php-applications/"
category: "Architecture"
language: "en"
---

# ConfigProvider - Bootstrap Modern PHP Applications

## TL;DR

In PHP, a `ConfigProvider` is a class or callable that is part of an application's bootstrap process, returning configuration data that tells the platform which middleware should run, in what order, and under what conditions.
Frameworks like Mezzio, Laminas, Slim, and the Dotkernel Headless Platform use ConfigProviders to declare middleware pipeline configuration, dependency injection mappings, and request handlers, which get merged together automatically during bootstrap (except in Dotkernel, where new ConfigProviders must be registered manually).

## Where Is the ConfigProvider Used?

Mezzio (formerly Zend Expressive), Laminas, Slim, the Dotkernel Headless Platform, and other middleware-based frameworks often have a `ConfigProvider` class.
In Laminas/Mezzio specifically, each module or package may contain a `ConfigProvider` that returns:

- Middleware pipeline configuration:
  - Middleware classes or service names.
  - Error-handling middleware, which should have the lowest priority.
  - Middleware groups or nested arrays.
- Dependency injection mappings.
- Request Handlers.

Example structure used in Dotkernel:

```php
class ConfigProvider
{
    public function __invoke(): array
    {
        return [ /* ... */ ];
    }

    public function getDependencies(): array
    {
        return [
            'factories'  => [ /* ... */ ],
            'invokables' => [ /* ... */ ],
        ];
    }

    public function getTemplates(): array
    {
        return [
            'paths' => [ /* ... */ ],
            'error' => [ /* ... */ ],
        ];
    }
}
```

What each item means:

| Item | Meaning |
|---|---|
| `dependencies` | Used by the dependency injector (e.g. laminas-servicemanager) to construct every requested service. |
| `factories` | The factory builds the service. |
| `invokables` | The service is built with `new` directly. |
| `aliases` | Redirects to another service name. |
| `delegators` | Wraps the original service. |
| `templates` | Defines the paths for the template files. |

## How the ConfigProvider Works

The ConfigProvider is automatically picked up by the framework during application bootstrap:

1. **Merge the global configuration** - All ConfigProviders are merged into one array.
2. **Read the configuration array** - A call similar to `$config = $container->get('config') ?? [];` reads an array of entries.
3. **Resolve item** - `$app->pipe()` is called to resolve one of the following: resolve the service name from the container, wrap the middleware if an array is provided, or call the closure or invokable object.
4. **Handle errors** - The error-handling middleware is the last one in the pipeline, to make sure it can handle any exceptions.
5. **Execute at runtime** - Laminas Stratigility iterates over the pipeline in the order it was registered. Each middleware can handle the request and return a response, or delegate execution to the next middleware in the pipeline, until a `ResponseInterface` is returned to the client.

## Benefits

- **Centralized setup** - Instead of hardcoding bootstrap code, it's declared in a config provider so it's easy to read, change, or extend.
- **Modular** - Each package can ship with its own config without interfering with others.
- **Container-friendly** - Works well with frameworks using DI containers like Laminas ServiceManager, PHP-DI, or Pimple.
- **Standardized service definitions** - Consistent rules for object creation, separate from business logic.
- **Auto-Discovery** - In Laminas/Mezzio, the ConfigAggregator automatically loads and merges all ConfigProviders.
Dotkernel is an exception: new ConfigProviders have to be added manually in `config/config.php`, because all the initial ConfigProviders required to install the applications are already injected.
- **Environment-agnostic** - Returns an array that defines dev, test, or prod environments.
- **Testability** - The consistent, central configuration promotes isolated (e.g. per-module) testing, easier swapping of dependencies, and assertion of pipeline setup (e.g. checking if a config key is present).

## FAQ

**Q: What is a ConfigProvider in PHP?**
A: It is a class that is part of an application's bootstrap process: a class or callable that returns configuration data telling the platform which middleware should run, in what order, and sometimes under what conditions.

**Q: What does the ConfigProvider return in the Laminas/Mezzio ecosystem?**
A: In the Laminas/Mezzio ecosystem, it's literally an array of configuration, settings, or anything else the application needs, and each module or package may contain its own ConfigProvider returning middleware pipeline configuration, dependency injection mappings, and request handlers.

**Q: What is the difference between 'factories' and 'invokables' in the dependencies array?**
A: `factories` will have the factory build the service, while `invokables` will use `new` directly.
You can also use `aliases` to redirect to another service name and `delegators` to wrap the original service.

**Q: How does the ConfigProvider get used during application bootstrap?**
A: It is automatically picked up by the framework during bootstrap: all ConfigProviders are merged into one array, the configuration array is read, each item is resolved via `$app->pipe()`, the error-handling middleware is placed last in the pipeline, and at runtime Laminas Stratigility iterates over the pipeline in the order it was registered.

**Q: Are new ConfigProviders auto-discovered in Dotkernel?**
A: Dotkernel is an exception to the usual auto-discovery rule: new ConfigProviders have to be added manually in `config/config.php`, because all the initial ConfigProviders required to install the applications are already injected.

**Q: What are the benefits of using a ConfigProvider?**
A: Benefits include centralized setup instead of hardcoded bootstrap code, modularity so each package can ship its own config, container-friendliness with DI containers like Laminas ServiceManager, PHP-DI or Pimple, standardized service definitions, environment-agnostic configuration for dev/test/prod, and better testability of the pipeline setup.

## Resources

- [Mezzio Container](https://docs.mezzio.dev/mezzio/v3/features/container/config/)
- [Laminas Config Aggregator](https://docs.laminas.dev/laminas-config-aggregator/config-providers/)
- [PSR-15 (HTTP Server Request Handlers)](https://www.php-fig.org/psr/psr-15/)


<!-- ============================================================ -->
<!-- architecture/request-lifecycle-for-a-mezzio-based-application.md -->
<!-- ============================================================ -->

---
title: "Request Lifecycle for a Mezzio-Based Application"
description: "A step-by-step walkthrough of how Dotkernel Light, a Mezzio-based application, handles an HTTP request from bootstrap through to the emitted response."
author: "Florin Bidirean"
date_published: "2026-05-26"
canonical_url: "https://www.dotkernel.com/architecture/request-lifecycle-for-a-mezzio-based-application/"
category: "Architecture"
language: "en"
---

# Request Lifecycle for a Mezzio-Based Application

## TL;DR

The request lifecycle is the sequence of steps that happen from the moment a user makes an HTTP request until the server sends back a response.
This is illustrated using Dotkernel Light, one of the applications in the Dotkernel Headless Platform suite, walking through entry point setup, routing, handler execution, template rendering, response creation, and the response emitter.

## The Request Lifecycle, Step by Step

### Entry Point

1. **HTTP Request** - Bootstrap the application, load configuration and create the Mezzio application instance.
2. **Service Container** - Register factories, aliases and delegators.
All services are configured and ready to use.
3. **Route Registration** - Read all available routes with their allowed request methods and dynamically register them in the application.
Routes are managed by FastRoute.
Example: `/page/about` -> `GetPageViewHandler`, Method: `GET`, Route name: `page::about`.
4. **Middleware Pipeline** - Loads the predefined order of middleware.
It defines how incoming HTTP requests move through the application and how responses are generated.

### Processing

5. **Routing** - FastRoute matches the URL and method against registered routes.
Match: `GET /page/about`, Handler: `GetPageViewHandler`, Route name: `page::about`.
6. **Handler Invocation** - Extract the matched route name from the request and pass it to the renderer:
   ```php
   $template = $request->getAttribute(RouteResult::class)->getMatchedRouteName();
   // $template = 'page::about';
   ```
7. **Custom Logic Execution in Handler** - Execute the business logic in the handler.
The process can involve services and any custom logic.
8. **Template Rendering** - Twig loads the template, applies the layout, renders blocks and includes partials.
Load: `src/Page/templates/page/about.html.twig`, Extends: `@layout/default.html.twig`, Render blocks: `title`, `content`, Include partials: `alerts.html.twig`, etc., Output: Final HTML.
9. **Response Creation** - An `HtmlResponse` is created with status, headers and the rendered HTML body.
Status: `200 OK`, Content-Type: `text/html; charset=utf-8`, Body: Rendered HTML.
10. **Response Pipeline** - The response flows back through the middleware stack.
Middleware can modify headers, cookies, compress content, etc.

### Exit Point

11. **Response Emitter** - The final response is sent back to the browser.
The page is rendered and sent to the user, as one of `HTTP 20x/30x`, `HTTP 40x`, or `HTTP 50x`.

## FAQ

**Q: What is the request lifecycle?**
A: The request lifecycle is the sequence of steps that happen from the moment a user makes an HTTP request until the server sends back a response.

**Q: What happens at the entry point of a request?**
A: The application bootstraps and loads configuration to create the Mezzio application instance, registers factories, aliases and delegators in the service container, reads all available routes with their allowed request methods and registers them (managed by FastRoute), and loads the predefined order of middleware in the pipeline.

**Q: How does routing work in a Mezzio-based application?**
A: FastRoute matches the incoming URL and method against the registered routes, for example matching a GET request to `/page/about` against the `GetPageViewHandler` handler under the route name `page::about`.

**Q: What happens during handler invocation?**
A: The matched route name is extracted from the request attribute and passed to the renderer, using code similar to `$template = $request->getAttribute(RouteResult::class)->getMatchedRouteName();`, after which the handler executes the custom business logic.

**Q: What happens during template rendering?**
A: Twig loads the matched template file, applies the layout it extends, renders its blocks, and includes any partials, producing the final HTML output.

**Q: How is the response created and returned to the browser?**
A: An `HtmlResponse` is created with a status code, headers, and the rendered HTML body.
It then flows back through the middleware stack in reverse (the response pipeline), where middleware can modify headers, cookies, or compress content, before the response emitter sends the final response back to the browser as HTTP 20x/30x, 40x, or 50x.

## Resources

- [Dotkernel Light on GitHub](https://github.com/dotkernel/light)
- [Dotkernel Light documentation](https://docs.dotkernel.org/light-documentation/)
- [Dotkernel Headless Platform suite on GitHub](https://github.com/dotkernel)


<!-- ============================================================ -->
<!-- architecture/understanding-middleware.md -->
<!-- ============================================================ -->

---
title: "Understanding Middleware"
description: "An introduction to middleware in PHP web applications: what it is, what it's used for, how PSR-15 defines it, and how it's called within an application's pipeline."
author: "Florin Bidirean"
date_published: "2025-05-22"
canonical_url: "https://www.dotkernel.com/architecture/understanding-middleware/"
category: "Architecture"
language: "en"
---

# Understanding Middleware

## TL;DR

Middleware is code that exists between the request and response: it can take an incoming request, act on it, and either complete the response itself or delegate to the next middleware in the queue.
It's used for concerns like authentication, CORS, caching, rate limiting, and more, and in PHP a PSR-15 compliant middleware implements `Psr\Http\Server\MiddlewareInterface` with a single `process()` method.

## The Purpose of Middleware

Middleware makes it easier for software developers to implement communication and input/output, so they can focus on the specific purpose of their application.
In web services, the `Input` represents the `Request` received, and `Output` represents the `Response` to be sent.

## Using Middleware

Middleware can be used for purposes such as, but not limited to:

- A/B Testing
- Debugging
- Caching
- CORS
- Authentication (HTTP Basic Auth, OAuth 2.0, OpenID)
- CSRF Protection
- Rate Limiting
- Referrals
- IP Restriction

## Usage

According to PSR-15: HTTP Server Request Handlers, a component that processes an incoming request and generates a response is a middleware.
To be compliant with the PSR-15 standard, the middleware must implement `Psr\Http\Server\MiddlewareInterface`:

```php
class MyMiddleware implements MiddlewareInterface
```

The middleware class must then implement the `process` method:

```php
public function process(ServerRequestInterface $request, RequestHandlerInterface $handler): ResponseInterface;
```

Example implementation of a middleware which processes the request:

```php
class ExampleMiddleware implements MiddlewareInterface
{
    public function process(ServerRequestInterface $request, RequestHandlerInterface $handler): ResponseInterface
    {
        //process request

        return $handler->handle($request);
    }
}
```

Example implementation of a middleware which processes the response:

```php
class ExampleMiddleware implements MiddlewareInterface
{
    public function process(ServerRequestInterface $request, RequestHandlerInterface $handler): ResponseInterface
    {
        $response = $handler->handle($request);

        //process response

        return $response;
    }
}
```

An approach that processes both the request and response:

```php
class ExampleMiddleware implements MiddlewareInterface
{
    public function process(ServerRequestInterface $request, RequestHandlerInterface $handler): ResponseInterface
    {
        //process request

        $response = $handler->handle($request);

        //process response

        return $response;
    }
}
```

## How Middleware Is Called

The application pipeline defines the execution flow.
The request passes through the middleware in the pipeline, one by one, in the order they are placed in the pipeline.
Each middleware processes the request and/or response and either passes control to the next middleware in the chain or terminates the request and returns a response.

- If control passes through all middleware successfully, execution is eventually passed to the custom code which generates a response of its own.
Execution then passes through the middleware in reverse order and returns the response.
- If execution is terminated before reaching the custom code (e.g. via an exception), the response is generated by the last middleware reached by the execution.

## Middleware in Practice

A simple real world example of middleware usage is the enhancement of a request with the user IP for logging purposes or building reports based on geographical data.
For this example the pipeline has a single middleware.

The flow begins with a request. Execution passes control to the IP middleware, which enhances the request with the user's IP and other relevant data.
Control passes to the custom handler that processes the request and returns a response.
The flow continues in reverse order, back to the IP middleware, which can, if needed, change the output before it gets returned to the user that initiated the request.

## FAQ

**Q: What is middleware?**
A: Middleware is code that exists between the request and response, and which can take the incoming request, perform actions based on it, and either complete the response or pass delegation on to the next middleware in the queue.

**Q: What is the purpose of middleware?**
A: Middleware makes it easier for software developers to implement communication and input/output, so they can focus on the specific purpose of their application.
In web services, the Input represents the Request received, and Output represents the Response to be sent.

**Q: What can middleware be used for?**
A: Middleware can be used for purposes such as A/B testing, debugging, caching, CORS, authentication (HTTP Basic Auth, OAuth 2.0, OpenID), CSRF protection, rate limiting, referrals, and IP restriction.

**Q: What interface must PHP middleware implement to be PSR-15 compliant?**
A: According to PSR-15, a compliant middleware must implement `Psr\Http\Server\MiddlewareInterface`, which requires a `process(ServerRequestInterface $request, RequestHandlerInterface $handler): ResponseInterface` method.

**Q: How does middleware get called within the application pipeline?**
A: The application pipeline defines the execution flow: the request passes through the middleware one by one, in the order they are placed. If control passes through all middleware successfully, execution is passed to your custom code, which generates a response, and execution then passes back through the middleware in reverse order.
If execution is terminated before reaching your custom code (e.g. via an exception), the response is generated by the last middleware reached.

**Q: What is a practical, real-world example of middleware?**
A: A simple example is enhancing a request with the user's IP for logging purposes or geographical reporting.
The request first passes through the IP middleware, which enhances the request with the user's IP and other relevant data, then control passes to the custom handler that processes the request and returns a response.
The flow continues in reverse, back through the IP middleware, which can change the output before it's returned to the user.

## Resources

- [Why Care About PHP Middleware?](https://philsturgeon.uk/php/2016/05/31/why-care-about-php-middleware/)
- [Learn more about Mezzio from the source](https://docs.mezzio.dev/)
- [Laminas components](https://docs.laminas.dev/components/)
- [Dotkernel Light, an implementation of Mezzio using handlers](https://github.com/dotkernel/light)
- [The Slim PHP micro framework](https://www.slimframework.com/)
- [The PHP Framework Interop Group's full list of PSRs](https://www.php-fig.org/psr/)
- [PSR-7: The magical middleware tour](https://vimeo.com/showcase/4061778/video/177154167)
- [From Helpers to Middleware](https://www.youtube.com/watch?v=v1I57-_Rsv0)


<!-- ============================================================ -->
<!-- best-practice/aptana-set-svn-keywords.md -->
<!-- ============================================================ -->

---
title: "Aptana - set SVN keywords"
description: "How to set the svn:keywords property (e.g. Id) for a file in Aptana, so SVN replaces the keyword marker with commit metadata."
author: "Teo"
date_published: "2011-04-04"
canonical_url: "https://www.dotkernel.com/best-practice/aptana-set-svn-keywords/"
category: "Best Practice"
language: "en"
---

# Aptana - set SVN keywords

## Overview

In Aptana it's very simple to set the svn:keywords property for a file.
For example, to set the svn keyword property `Id`:

## Steps

1. In the file where the svn keyword property should be added, write `$Id$`.
2. Right click on the file, then follow Team -> Set Property...
(Note: "Set Property..." will not be active if the file hasn't first been added to SVN via Team -> Add to Version Controller).
3. Select `svn:keywords`, and write `Id` in the text field.

When the SVN commit of the file is made, the `$Id$` keyword will be replaced with text containing the file's SVN metadata, in a specific format.

## FAQ

**Q: How do you set the svn:keywords property for a file in Aptana?**
A: Write the keyword marker (for example `$Id$`) in the file, then right click the file and follow Team -> Set Property..., select `svn:keywords`, and write `Id` in the text field.

**Q: Why is "Set Property..." not active when I right click the file?**
A: Set Property... will not be active if the file hasn't first been added to SVN.
Use Team -> Add to Version Controller before trying to set the property.

**Q: What happens to the $Id$ keyword after an SVN commit?**
A: After the SVN commit of the file, the `$Id$` keyword is replaced with text containing the file's SVN metadata, in a specific format.

## Resources

- [svn:keywords property documentation](http://svnbook.red-bean.com/en/1.4/svn.advanced.props.special.keywords.html)


<!-- ============================================================ -->
<!-- best-practice/basic-security-in-dotkernel-headless-platform.md -->
<!-- ============================================================ -->

---
title: "Basic Security in Dotkernel Headless Platform"
description: "A practical overview of software security practices implemented across the Dotkernel Headless Platform, covering input validation, content negotiation, CORS, RBAC, OAuth2, sessions, dependencies, and more."
author: "Florin Bidirean"
date_published: "2025-10-14"
canonical_url: "https://www.dotkernel.com/best-practice/basic-security-in-dotkernel-headless-platform/"
category: "Best Practice"
language: "en"
---

# Basic Security in Dotkernel Headless Platform

## TL;DR

Software security should always be top of mind for a developer, since ignoring it can lead to major costs, data loss, GDPR fines, or the loss of client trust. The article surveys many facets of software security and walks through the practical measures Dotkernel Headless Platform takes for each: input validation, content negotiation, CORS, RBAC, demo credentials, error reporting, OpenAPI docs, PHP and JavaScript dependencies, OAuth2, session/cookie settings, and CI checks.

## Facets of Software Security

There are many potential ways a hacker can access code or data fraudulently:

- Authentication and access control.
- Data protection.
- Input validation and injection.
- Web and API security.
- Dependency and supply chain risks.
- Configuration and deployment.
- Network and infrastructure security.
- Logging, monitoring and incident response.
- Secure software development lifecycle.
- Human and organizational factors.

## The Tenets of Software Security in Dotkernel Headless Platform

Dotkernel aims to:

- Create code that follows software security guidelines.
- Implement community recommendations related to software security.
- Use 3rd-party code and libraries from trusted sources.
- Constantly monitor software news related to security vulnerabilities and mitigate them as soon as possible.

## Form Input Validation

Never trust that user input is correct by passing it directly into business logic.
By defining the configuration for an input filter, a field's presence and type are both ensured. Dotkernel API uses laminas/laminas-inputfilter for this purpose.
Dotkernel Admin additionally uses laminas/laminas-form, which contains a thin layer of objects representing form elements, an InputFilter for each input (or custom validators), and methods for binding data to and from the form. laminas-form integrates with the Laminas Security Ecosystem: laminas-escaper, laminas-validator, laminas-session, and laminas-filter.

## Content Negotiation

Content negotiation is used in RESTful APIs so client and server agree on the format and language of exchanged data.
Dotkernel API handles this via a middleware configured in `config/autoload/content-negotiation.global.php`, using the `Content-Type` and `Accept` HTTP request headers, and returning `application/json` or `application/hal+json` data formats.

## Cross-Origin Resource Sharing

CORS is a browser security mechanism controlling how web pages can request resources from a different domain.
In Dotkernel API, CORS is handled by mezzio/mezzio-cors and configured in `config/autoload/cors.local.php`.
It starts detecting the proper `cors` configuration whenever it detects a `cors preflight`, validating the call using configuration items: origins, headers, max age, and credentials.

> When configuring your pipeline, make sure to add the CorsMiddleware BEFORE the RouteMiddleware.

## Role-Based Access Control

RBAC manages access to resources by assigning roles to user types, which are in turn assigned to users requiring a certain level of access.
Dotkernel API uses mezzio/mezzio-authorization-rbac for this purpose, with several predefined roles configurable in `config/autoload/authorization.global.php`.

## Demo Credentials

Demo credentials are provided in Dotkernel API for convenience, to allow easy testing of the installation.

> It is important to update or remove these accounts in your production environment.

## Error Reporting Endpoint and ErrorReportingTokens

The error reporting endpoint provides a reliable channel through which 3rd-party developers can report issues directly.
Dotkernel API has a dedicated `/error-report` endpoint for this, using an `ErrorReportingToken` set up in `config/autoload/error-handling.global.php`.

## OpenAPI Documentation

OpenAPI documentation (formerly Swagger) provides a standardized, machine-readable way to describe API requests and responses.
It's critical for developer efficiency (streamlines front/back-end communication, allows mock servers before the backend is implemented), reliability (auto-generated docs, easier testing), and integration (tools like Postman and Codegen libraries).
Dotkernel API implements zircote/swagger-php to provide interactive documentation.

> Do not include sensitive information for your endpoints.
> Do not enable documentation in a production environment.

## PHP Dependencies

Modern PHP projects rely heavily on external packages via Composer, and there is a tangible risk of exposing an application through insecure dependencies.
Dotkernel API has regular checks for vulnerable and outdated packages, including transient dependencies.

> Always use dependencies from reliable sources and keep them updated to their latest version.

## OAuth2 Security

OAuth 2.0 is a secure authorization framework letting one application access resources on behalf of a user without requiring the user's password, an industry standard for web, mobile, and API-based systems. Dotkernel API uses mezzio/mezzio-authentication-oauth2 for OAuth2 authentication.
The package itself is secure, but it must be used properly:

- Replace or update the default `admin` and `frontend` clients on production.
- Update the `access` and `refresh` tokens to match your application's requirements (defaults are one day for access, one month for refresh).
- Never commit any local keys generated by `./vendor/bin/generate-oauth2-keys`, since they verify the transmitted JWTs.

## Session and Cookie Settings

Sessions and cookies store data between HTTP requests, such as login information, preferences, or user behavior tracking.
Dotkernel configures cookies in `config/autoload/session.global.php`, which contains parameters that must be revised and adapted:

- `session_config.cookie_httponly`
- `session_config.cookie_samesite`
- `session_config.cookie_secure`

## JavaScript Dependencies

JavaScript has its own dependencies, usually installed via npm or yarn.
The JavaScript ecosystem has recently been attacked by hackers targeting several widely used npm packages with billions of total uses.
Dotkernel uses npm to handle JavaScript dependencies, monitors the news for security issues, and uses packages from reliable sources.
`npm audit` should still be used regularly to check for vulnerabilities.

## Other Security Considerations

All components of Dotkernel Headless Platform have configuration files named `*.global.php`, `*.php.dist`, and `*.local.php`.
Sensitive information must only go in `*.local.php` files, since they are ignored by the VCS by default.
Development mode enables features like debug mode, cache clear, and error details, which should be hidden from production to avoid exposing sensitive data or code.
The Laminas Continuous Integration GitHub Action is integral to Dotkernel API, running a matrix of static analysis, coding standards checks, and unit tests, most often triggered by commits.

## FAQ

**Q: What are the main facets of software security to consider?**
A: Software security spans many areas: authentication and access control, data protection, input validation and injection, web and API security, dependency and supply chain risks, configuration and deployment, network and infrastructure security, logging/monitoring and incident response, secure software development lifecycle, and human and organizational factors.

**Q: How does Dotkernel handle form input validation?**
A: Dotkernel API uses laminas/laminas-inputfilter to ensure a field is present and of the correct type.
Dotkernel Admin additionally uses laminas/laminas-form, which provides form element objects, an InputFilter for each input (or custom validators), and methods for binding data to and from the form, integrating with laminas-escaper, laminas-validator, laminas-session, and laminas-filter.

**Q: How does Dotkernel API handle content negotiation?**
A: Content negotiation is handled via a middleware configured in the `config/autoload/content-negotiation.global.php` file.
It uses the Content-Type and Accept HTTP request headers to negotiate with the client, returning application/json or application/hal+json data formats.

**Q: How is CORS handled and configured in Dotkernel API?**
A: CORS is handled by mezzio/mezzio-cors and configured in the `config/autoload/cors.local.php` file, validating calls using configuration items like origins, headers, max age, and credentials.
When configuring the pipeline, the CorsMiddleware must be added before the RouteMiddleware.

**Q: What should be done with the demo credentials before going to production?**
A: Demo credentials are provided for convenience during installation testing, but it is important to update or remove these accounts in your production environment.

**Q: What are the security recommendations around OpenAPI documentation?**
A: You should not include sensitive information for your endpoints in the OpenAPI documentation, and you should not enable the documentation in a production environment.

## Resources

- [Basic Security in Dotkernel Admin](https://docs.dotkernel.org/admin-documentation/v6/security/basic-security/)
- [Basic Security in Dotkernel API](https://docs.dotkernel.org/api-documentation/v6/security/basic-security/)
- [Content Negotiation in Dotkernel REST API](https://www.dotkernel.com/dotkernel-api/content-negotiation-in-dotkernel-rest-api/)
- [laminas-form Documentation](https://docs.laminas.dev/laminas-form/v3/intro/)
- [CORS in Dotkernel API](https://docs.dotkernel.org/api-documentation/v6/tutorials/cors/)
- [CORS Policy Setup in Dotkernel](https://www.dotkernel.com/how-to/mezzio-cors-implementation-in-dotkernel/)
- [Error Reporting Endpoint](https://docs.dotkernel.org/api-documentation/v6/core-features/error-reporting/)
- [OpenAPI Documentation](https://docs.dotkernel.org/api-documentation/v6/openapi/introduction/)
- [mezzio/mezzio-authentication-oauth2 Configuration](https://docs.mezzio.dev/mezzio-authentication-oauth2/v1/intro/#configuration)


<!-- ============================================================ -->
<!-- best-practice/golden-rules-of-professional-php-coding.md -->
<!-- ============================================================ -->

---
title: "Golden Rules of Professional PHP Coding"
description: "A short list of practical rules for professional PHP development: error reporting settings, fixing warnings, marking hacks, single-responsibility functions, version control, and IDE usage."
author: "admin"
date_published: "2011-06-12"
canonical_url: "https://www.dotkernel.com/best-practice/golden-rules-of-professional-php-coding/"
category: "Best Practice"
language: "en"
---

# Golden Rules of Professional PHP Coding

## The Rules

1. Always use, in development and in staging, the highest error reporting level, and display_errors ON:
   ```php
   error_reporting(-1);
   ini_set('display_errors', 1);
   ```
2. Fix every warning or notice that occurs.
3. Check regularly the server's error_log for notices/warnings.
4. Identify any temporary hack with a special mark, for example:
   ```php
   #@TODO masterpiece by @smartguy, to quick fix the division by zero
   ```
5. Each function must do a single task.
If it logs in the user and records the login in a stats table, create a separate function for the "record the login" part - maybe even a distinct class for stats.
6. Use a version control system.
SVN is NOT dead.
7. Use an IDE, such as Aptana 2, Aptana 3, Eclipse, or Zend Studio.
8. Know your IDE: code snippets, code assist, integration with Zend Framework, SVN integration, bug tracker integration, and so on.

## FAQ

**Q: What error reporting settings should be used in development and staging?**
A: Always use the highest error reporting level and turn display_errors ON, for example with `error_reporting(-1);` and `ini_set('display_errors', 1);`.

**Q: What should you do about warnings and notices?**
A: Fix every warning or notice that occurs, and regularly check the server's error_log for notices and warnings.

**Q: How should temporary hacks or quick fixes be marked in code?**
A: Identify any temporary hack with a special mark, such as a `#@TODO` comment noting who added it and why.

**Q: What is the rule about what a function should do?**
A: Each function must do a single task.
For example, if you're logging in a user and also recording that login in a stats table, create a separate function (or even a distinct class) for the stats recording, rather than combining both tasks in one function.

**Q: What tools does the article recommend for professional PHP development?**
A: It recommends using a version control system (noting that SVN is not dead) and using an IDE such as Aptana 2, Aptana 3, Eclipse, or Zend Studio, and knowing your IDE's code snippets, code assist, Zend Framework integration, SVN integration, and bug tracker integration.

## Resources

- [Integrated development environment (Wikipedia)](http://en.wikipedia.org/wiki/Integrated_development_environment)
- [Aptana 2 download](http://www.aptana.com/products/studio2/download)
- [Aptana 3 download](http://www.aptana.com/products/studio3/download)
- [Zend Studio](http://www.zend.com/en/products/studio/)


<!-- ============================================================ -->
<!-- best-practice/htaccess-301-redirect-non-www-to-www.md -->
<!-- ============================================================ -->

---
title: "htaccess 301 redirect non-www to www"
description: "How to configure .htaccess RewriteCond/RewriteRule directives to redirect a non-www domain to its www version, or vice versa."
author: "admin"
date_published: "2011-03-14"
canonical_url: "https://www.dotkernel.com/best-practice/htaccess-301-redirect-non-www-to-www/"
category: "Best Practice"
language: "en"
---

# htaccess 301 redirect non-www to www

## Redirect non-www to www

To always redirect users to the www site (for example: `http://dotboost.com` to `http://www.dotboost.com`), add the following lines to `.htaccess`, right after `RewriteEngine On`:

```shell
RewriteCond %{HTTP_HOST} ^dotboost.com
RewriteRule ^(.*)$ http://www.dotboost.com/$1
```

## Redirect www to non-www

If, instead, you want to redirect `http://www.dotboost.com` to `http://dotboost.com`, add the following lines instead:

```shell
RewriteCond %{HTTP_HOST} ^www.dotboost.com
RewriteRule ^(.*)$ http://dotboost.com/$1
```

Replace `dotboost.com` with your site's domain in either case.

## FAQ

**Q: How do I redirect a non-www domain to www using .htaccess?**
A: Add `RewriteCond %{HTTP_HOST} ^dotboost.com` and `RewriteRule ^(.*)$ http://www.dotboost.com/$1` to your .htaccess file, right after `RewriteEngine On`, replacing dotboost.com with your own domain.

**Q: How do I redirect a www domain to non-www instead?**
A: Add `RewriteCond %{HTTP_HOST} ^www.dotboost.com` and `RewriteRule ^(.*)$ http://dotboost.com/$1` instead, again replacing dotboost.com with your own domain.


<!-- ============================================================ -->
<!-- best-practice/insert-update-delete-statements-with-zend-db.md -->
<!-- ============================================================ -->

---
title: "INSERT, UPDATE, DELETE statements with Zend_Db"
description: "How to write INSERT, UPDATE, and DELETE (DML) statements using Zend_Db, alongside their equivalent raw SQL."
author: "Teo"
date_published: "2010-06-16"
canonical_url: "https://www.dotkernel.com/best-practice/insert-update-delete-statements-with-zend-db/"
category: "Best Practice"
language: "en"
---

# INSERT, UPDATE, DELETE statements with Zend_Db

## TL;DR

DML (Data Manipulation Language) statements change data values in database tables.
This article, continuing the Zend_Db series, shows how the three primary DML statements - INSERT, UPDATE, and DELETE - are written in raw SQL and translated into Zend_Db method calls.

## Connecting to the database

```php
$db = Zend_Db::factory('Pdo_Mysql', $dbConnect);
```

## INSERT

SQL:

```sql
INSERT INTO user(email, password, firstName, lastName, active)
       VALUES ('$email', '$password', '$firstName', '$lastName', 1);
```

Zend_Db:

```php
$data = array( 'email' => $email,
            'password' => $password,
            'firstName' => $firstName,
            'lastName' => $lastName,
            'active' => '1');
$db->insert('user', $data);
```

## UPDATE

SQL:

```sql
UPDATE user
   SET password = '$password',
       firstName = '$firstName',
       lastName = '$lastName',
       accountUpdate = (accountUpdate +1)
 WHERE id = '$id'
```

Zend_Db:

```php
$data = array('password' => $password,
              'firstName' => $firstName,
              'lastName' => $vlastname,
              'accountUpdate' => new Zend_Db_Expr('accountUpdate+1'));
$db->update('user', $data, 'id = '.$id);
```

## DELETE

SQL:

```sql
DELETE FROM user WHERE id = '$id'
```

Zend_Db:

```php
$db->delete('user', 'id = '.$id);
```

## FAQ

**Q: What are DML statements?**
A: DML (Data Manipulation Language) statements are statements that change data values in database tables.
There are 3 primary DML statements: INSERT, UPDATE, and DELETE.

**Q: How do you insert a new row with Zend_Db?**
A: Build an associative array of column names to values (e.g. email, password, firstName, lastName, active) and pass it to $db->insert('user', $data), which corresponds to an SQL INSERT INTO ...
VALUES statement.

**Q: How do you update rows with Zend_Db, including incrementing a column?**
A: Build a $data array of the columns to update, using a Zend_Db_Expr for expressions such as incrementing accountUpdate (new Zend_Db_Expr('accountUpdate+1')), then call $db->update('user', $data, 'id = '.$id).

**Q: How do you delete a row with Zend_Db?**
A: Call $db->delete('user', 'id = '.$id), which is equivalent to the SQL statement DELETE FROM user WHERE id = '$id'.

## Resources

- [Zend_Db series](http://www.dotkernel.com/dotkernel/sql-select-zend-db/)


<!-- ============================================================ -->
<!-- best-practice/sql-queries-using-zend-db-select.md -->
<!-- ============================================================ -->

---
title: "SQL queries using Zend_Db – SELECT"
description: "How to write SELECT queries with JOINs and WHERE IN clauses using Zend_Db, alongside their equivalent raw SQL."
author: "Teo"
date_published: "2010-06-15"
canonical_url: "https://www.dotkernel.com/best-practice/sql-queries-using-zend-db-select/"
category: "Best Practice"
language: "en"
---

# SQL queries using Zend_Db – SELECT

## TL;DR

Zend_Db and its related classes provide a simple SQL database interface for Zend Framework.
This article shows how classical SELECT queries with JOINs and WHERE IN clauses are translated into Zend_Db's select() style, and how to debug the generated query.

## Connecting to the database

```php
$db = Zend_Db::factory('Pdo_Mysql', $dbConnect);
```

## SELECT query - WHERE clause

The following two classical SQL queries are equivalent - the first is a simple comma join, the second uses INNER JOIN - but the result is the same:

```sql
SELECT a.id, a.name, b.order_id
FROM users AS a, orders AS b
WHERE a.id = b.user_id
AND a.id = {$userId}
```

```sql
SELECT `a`.`id`, `a`.`name`, `b`.`order_id`
FROM `users` AS `a` INNER JOIN `orders` AS `b` ON a.id = b.user_id
WHERE (a.id = '{$userId}')
```

Translated into Zend_Db style:

```php
$select = $db->select()
             ->from(array('a'=>'users'),
                    array('a.id', 'a.name'))
             ->join(array('b'=>'orders'), 'a.id = b.user_id', array('b.order_id'))
             ->where('a.id = ?', $userId)
```

If no column should be selected from the second table, the 3rd parameter of join() should be an empty string:

```sql
SELECT a.id, a.name
FROM users AS a, orders AS b
WHERE a.id = b.user_id
AND a.id = {$userId}
```

```php
$select = $db->select()
             ->from(array('a'=>'users'),
                    array('a.id', 'a.name'))
             ->join(array('b'=>'orders'), 'a.id = b.user_id', '')
             ->where('a.id = ?', $userId)
```

Note: if the 3rd parameter is not written at all, it will select all the fields from that table:

```sql
SELECT a.id, a.name, b.*
FROM users AS a, orders AS b
WHERE a.id = b.user_id
AND a.id = {$user_id}
```

```php
$select = $db->select()
             ->from(array('a'=>'users'),
                    array('a.id', 'a.name'))
              ->join(array('b'=>'orders'), 'a.id = b.user_id')
              ->where('a.id = ?', $userId)
```

## SELECT query - WHERE IN clause

```sql
SELECT id
FROM users
WHERE aff_id IN ('1','2','3')
```

```php
$select = $db->select()
             ->from('users', array('id'))
             ->where('aff_id IN (?)', array(1,2,3));
```

## Debugging a query

If you are not sure the correct query is being generated, echo it before fetching:

```php
echo $select->__toString();exit;
```

## FAQ

**Q: What does Zend_Db provide?**
A: Zend_Db and its related classes provide a simple SQL database interface for Zend Framework.
To connect to a MySQL database, the Pdo_Mysql adapter is used via Zend_Db::factory('Pdo_Mysql', $dbConnect).

**Q: How do you write a SELECT with a JOIN and a WHERE clause in Zend_Db style?**
A: Use $db->select()->from(array('a'=>'users'), array('a.id','a.name'))->join(array('b'=>'orders'), 'a.id = b.user_id', array('b.order_id'))->where('a.id = ?', $userId), which is equivalent to a classical SQL query using INNER JOIN.

**Q: How do you join a table without selecting any of its columns?**
A: Pass an empty string as the 3rd parameter of the join() method, e.g. ->join(array('b'=>'orders'), 'a.id = b.user_id', '').

**Q: What happens if the 3rd parameter of join() is omitted entirely?**
A: If the 3rd parameter is not written, it will select all the fields from that joined table (equivalent to SELECT ..., b.* in SQL).

**Q: How do you write a WHERE IN clause with Zend_Db?**
A: Use ->where('aff_id IN (?)', array(1,2,3)) on the select object, equivalent to SQL's WHERE aff_id IN ('1','2','3').

**Q: How can you check that a Zend_Db select is generating the correct query?**
A: Before fetching it, echo the query to visualize it: echo $select->__toString();exit;

## Resources

- [Zend_Db](https://docs.laminas.dev/laminas-db/adapter/)
- [What are returning the FETCH functions from Zend_Db](http://www.dotkernel.com/best-practice/sql-fetch-zend-db/)
- [Subqueries with Zend_Db](http://www.dotkernel.com/best-practice/subqueris-with-zend-db/)
- [INSERT, UPDATE, DELETE statements with Zend_Db](http://www.dotkernel.com/best-practice/iud-statements-with-zend-d/)


<!-- ============================================================ -->
<!-- best-practice/subqueries-with-zend-db.md -->
<!-- ============================================================ -->

---
title: "Subqueries with Zend_Db"
description: "How to build a query combining COUNT, LEFT JOIN, and GROUP BY across multiple tables using Zend_Db, including a subquery embedded as a column."
author: "Teo"
date_published: "2010-06-15"
canonical_url: "https://www.dotkernel.com/best-practice/subqueries-with-zend-db/"
category: "Best Practice"
language: "en"
---

# Subqueries with Zend_Db

## TL;DR

Continuing the Zend_Db series, this article shows a more complex query - combining COUNT(), LEFT JOIN, and GROUP BY across 3 tables, with a count taken from 2 different tables - and how to build it, including a nested subquery, using Zend_Db.

## The SQL query

```sql
SELECT a.id,
       a.title,
       (SELECT COUNT(c.track_id)
        FROM track_files AS c
        WHERE c.track_id = a.id
       ) AS `count_files`,
       COUNT(b.track_id) AS count_courses
FROM tracks AS a
LEFT JOIN track_courses AS b ON (a.id = b.track_id)
GROUP BY a.id
```

## Connecting to the database

```php
$db = Zend_Db::factory('Pdo_Mysql', $dbConnect);
```

## Building the query in Zend_Db

```php
$db->select()
   ->from(array('a'=>'tracks'),
         array('id',
              'title',
             'count_files' => new Zend_Db_Expr(
                        '('.$db->select()
                           ->from(array('c'=>'track_files'),
                                     array(new Zend_Db_Expr('COUNT(c.track_id)')))
                           ->where('c.track_id = a.id').')' )
               )
          )
   ->joinLeft(array('b'=>'track_courses'),
         'a.id = b.track_id',
         array('count_courses' => 'COUNT(b.track_id)')
         )
   ->group('a.id');
```

The `count_files` column is built by wrapping a nested `$db->select()` call inside a `Zend_Db_Expr`, correlated back to the outer table via `c.track_id = a.id`.

## FAQ

**Q: What SQL techniques does this subquery example combine?**
A: The example combines COUNT(), LEFT JOIN, and GROUP BY, selecting from 3 tables and counting rows from 2 different tables.

**Q: How do you embed a subquery as a selected column in a Zend_Db select?**
A: Wrap a nested $db->select() call inside a Zend_Db_Expr, building the subquery string with the outer table's correlated WHERE condition (e.g. c.track_id = a.id), as shown for the count_files column.

**Q: How is the LEFT JOIN with a COUNT expressed in Zend_Db?**
A: Use ->joinLeft(array('b'=>'track_courses'), 'a.id = b.track_id', array('count_courses' => 'COUNT(b.track_id)')) followed by ->group('a.id').

## Resources

- [Zend_Db series](http://www.dotkernel.com/dotkernel/sql-select-zend-db/)


<!-- ============================================================ -->
<!-- best-practice/svn-export-in-a-virtual-host.md -->
<!-- ============================================================ -->

---
title: "SVN Export in a virtual host"
description: "How to export the contents of an SVN repository into a virtual host directory using the svn export command."
author: "Adrian"
date_published: "2011-05-30"
canonical_url: "https://www.dotkernel.com/best-practice/svn-export-in-a-virtual-host/"
category: "Best Practice"
language: "en"
---

# SVN Export in a virtual host

## TL;DR

`svn export` lets you export the contents of a repository into a virtual host directory.
The commands should be run in a terminal (e.g. via Putty on Windows) on the target host, ideally using the domain's own user rather than root.

## Steps

1. Make sure Subversion is installed on the host by running `svn --version`.
If you don't get a "command not found" message, it's installed; otherwise, install it.
2. Go to the directory where you want to export the contents of the repository (e.g. `cd /var/www/vhosts/example.com/httpdocs` or `cd /home/sitename/public_html`).
3. Run the export command:

```shell
svn export repositoryUrl repositoryUrl
```

Where:

| Parameter | Meaning |
|---|---|
| `-r revisionNumber` | Optional. Exports a specific revision. By default, the latest revision is used. |
| `repositoryUrl` | The repository URL (e.g. `http://example.com/repos/project-name/trunk/`). Remember to add `/trunk/`, or change it appropriately for a branch or tag. |
| `targetDirectory` - `./` | The current directory. |
| `targetDirectory` - `./project-name` | Exports to the `project-name` subdirectory. |
| `targetDirectory` - `/var/www/vhosts/example.com/httpdocs` | Exports to an absolute path. |
| `--force` | Optional. By default SVN will not export into an existing directory; this overrides that. **Be careful, this option can overwrite files.** |

4. For more information, run `svn help export`.

## Examples

```shell
svn export http://v1.dotkernel.net/svn/trunk ./ --force
svn export -r 423 http://v1.dotkernel.net/svn/trunk ./ --force
svn export http://v1.dotkernel.net/svn/trunk /var/www/vhosts/domain.com/httpdocs/dk
```

## Fixing permissions afterward

If the repository was exported using a different user (e.g. root), change the permissions back as root:

```shell
chown -R siteuser.psacln /var/www/vhosts/example.com/httpdocs
```

## FAQ

**Q: How do you check if Subversion is installed on the host?**
A: Run svn --version.
If you don't get a "command not found" message, Subversion is installed; otherwise, you need to install it.

**Q: What is the basic command to export a repository?**
A: The command is svn export repositoryUrl targetDirectory, run from the host where you want to export the repository, ideally using the domain's user rather than root.

**Q: What does the -r option do?**
A: -r revisionNumber is optional and exports a specific revision; by default, the latest revision is used.

**Q: What does the --force option do, and what is the risk?**
A: By default SVN will not export into an existing directory; --force overrides this.
Be careful, since this option can overwrite files.

**Q: How do you fix file permissions if you exported the repository as a different user?**
A: As root, run chown -R siteuser.psacln /var/www/vhosts/example.com/httpdocs to change the permissions back.


<!-- ============================================================ -->
<!-- best-practice/svn-keywords-setup-in-php-ide-zend-studio.md -->
<!-- ============================================================ -->

---
title: "SVN keywords setup in PHP IDE ( Zend Studio)"
description: "How to set SVN ignore, bug tracker, and svn:keywords properties per project in the Zend Studio PHP IDE."
author: "admin"
date_published: "2013-02-21"
canonical_url: "https://www.dotkernel.com/best-practice/svn-keywords-setup-in-php-ide-zend-studio/"
category: "Best Practice"
language: "en"
---

# SVN keywords setup in PHP IDE ( Zend Studio)

## TL;DR

For better integration between SVN, the Zend Studio PHP IDE, and a bug tracker, a set of SVN properties must be set for each project.
This article lists which properties to set and how.

## Steps

1. Right click on the **project**.
2. Go to **Team -> Set Propriety**.
3. Set `svn:ignore` so local settings aren't committed to the main repository:

```
Name: svn:ignore
Propriety:
*.project
*.prefs
.project
cache
.settings
.buildpath
*.ini
```

4. Set up basic bug tracker integration:

```
Name: bugtracq:label
Propriety: Tracker ID:
```

```
Name: bugtraq:message
Propriety:
```

5. If using a public bug tracker (e.g. Mantis), also set:

```
Name: bugtraq:url
Propriety: http://www.dotkernel.net/view.php?id=%BUGID%
```

For the properties above, apply them **only** to the project folder, **not** recursively.

## Final step (svn:keywords only)

1. Check **Apply property recursively to:**.
2. Select **All resources**.
3. Check **Use filtration by the resource name** and add mask: `*.php`.

## FAQ

**Q: Why set these SVN properties on each project?**
A: They provide better integration of SVN, your PHP IDE (Zend Studio), and a bug tracker of choice, and must be set for each project you have.

**Q: What does the svn:ignore property do here?**
A: It tells SVN to ignore local settings files such as *.project, *.prefs, .project, cache, .settings, .buildpath, and *.ini, since you don't want to commit your local settings to the main repository.

**Q: How do you set up basic bug tracker integration?**
A: Set the bugtracq:label property to "Tracker ID:" and bugtraq:message; if you have a public bug tracker such as Mantis, also set bugtraq:url to a URL pattern like http://www.dotkernel.net/view.php?id=%BUGID%.

**Q: Should these properties be applied recursively?**
A: No. For the properties above, apply them only to the project folder, not recursively.

**Q: How is the svn:keywords property applied differently?**
A: Check "Apply property recursively to:", select "All resources", then check "Use filtration by the resource name" and add the mask *.php.


<!-- ============================================================ -->
<!-- best-practice/using-like-wildcards-with-zend-db.md -->
<!-- ============================================================ -->

---
title: "Using LIKE wildcards with Zend_Db"
description: "How to use the SQL LIKE condition and its _ and % wildcards, including NOT LIKE, with Zend_Db's quoteInto and quoteIdentifier methods."
author: "Teo"
date_published: "2010-09-10"
canonical_url: "https://www.dotkernel.com/best-practice/using-like-wildcards-with-zend-db/"
category: "Best Practice"
language: "en"
---

# Using LIKE wildcards with Zend_Db

## TL;DR

The LIKE condition allows pattern matching in the WHERE clause of SELECT, INSERT, UPDATE, or DELETE statements.
The `_` wildcard matches a single character, and `%` matches any string of any length (including zero).
This article shows how to use LIKE and NOT LIKE with both wildcards in Zend_Db.

## Connecting to the database

```php
$db = Zend_Db::factory('Pdo_Mysql', $dbConnect);
```

## LIKE _

Return all ids that start with '1' and whose second digit is between 0 and 9 (10, 11, 12, ..., 18, 19):

```sql
SELECT * FROM `table` WHERE (`id` LIKE '1_' )
```

```php
$col = $this->db->quoteIdentifier('id');
$where = $this->db->quoteInto("$col LIKE ? ", '1_');
$select = $this->db->select()
    ->from('table')
    ->where($where);
$result = $this->db->fetchAll($select);
```

Return all instances whose name is 4 characters long, starting with 'Fr' and ending with 'd' (Frad, Fred, Frod, etc.):

```sql
SELECT * FROM `table` WHERE (`name` LIKE 'Fr_d' )
```

```php
$col = $this->db->quoteIdentifier('name');
$where = $this->db->quoteInto("$col LIKE ? ", 'Fr_d');
$select = $this->db->select()
    ->from('table')
    ->where($where);
$result = $this->db->fetchAll($select);
```

## LIKE %

Returns all instances that have the 'gallery' string in the `source` field:

```sql
SELECT * FROM `table` WHERE (`source` LIKE '%gallery%' )
```

```php
$col = $this->db->quoteIdentifier('source');
$where = $this->db->quoteInto("$col LIKE ? ", '%gallery%');
$select = $this->db->select()
    ->from('table')
    ->where($where);
$result = $this->db->fetchAll($select);
```

Returns all instances that have the 'gallery' or 'folder' strings in the `source` field:

```sql
SELECT * FROM `table` WHERE (`source` LIKE '%gallery%' OR `source` LIKE ('%folder%') )
```

```php
$col = $this->db->quoteIdentifier('source');
$where = $this->db->quoteInto("$col LIKE ? ", '%gallery%');
$where .= $this->db->quoteInto("OR $col LIKE (?) ", '%folder%');
$select = $this->db->select()
    ->from('table')
    ->where($where);
$result = $this->db->fetchAll($select);
```

## NOT LIKE _

Returns all 2-digit ids that don't start with `1` (20->99) or that don't have exactly 2 digits (1, 2, ..., 8, 9, 100, 101, ...):

```sql
SELECT * FROM `table` WHERE (`id` NOT LIKE '1_' )
```

```php
$col = $this->db->quoteIdentifier('id');
$where = $this->db->quoteInto("$col NOT LIKE ? ", '1_');
$select = $this->db->select()
    ->from('table')
    ->where($where);
$result = $this->db->fetchAll($select);
```

## NOT LIKE %

Returns all instances that don't have 'gallery', 'folder', or 'file' in the `source` field:

```sql
SELECT * FROM `table` WHERE (`source` NOT LIKE ('%gallery%') AND `source` NOT LIKE ('%folder%') AND `source` NOT LIKE ('%file%') )
```

```php
$col = $this->db->quoteIdentifier('source');
$where = $this->db->quoteInto("$col NOT LIKE (?) ", '%gallery%');
$where .= $this->db->quoteInto("AND $col NOT LIKE (?) ", '%folder%');
$where .= $this->db->quoteInto("AND $col NOT LIKE (?) ", '%file%');
$select = $this->db->select()
    ->from('table')
    ->where($where);
$result = $this->db->fetchAll($select);
```

## Other example

```sql
SELECT * FROM `table` WHERE `number` LIKE '_6%'
```

```php
$col = $this->db->quoteIdentifier('number');
$where = $this->db->quoteInto("$col LIKE ? ", '_6%');
$select = $this->db->select()
    ->from('table')
    ->where($where);
$result = $this->db->fetchAll($select);
```

## FAQ

**Q: What do the LIKE wildcards _ and % mean?**
A: The _ wildcard matches a single character, while % matches any string of any length, including zero length.

**Q: Which SQL statements can use the LIKE condition?**
A: LIKE allows pattern matching in the WHERE clause and can be used in any valid SQL statement: SELECT, INSERT, UPDATE, or DELETE.

**Q: How do you build a LIKE query with Zend_Db?**
A: Quote the column with $this->db->quoteIdentifier(), build the condition with $this->db->quoteInto("$col LIKE ?
", $pattern), and pass the resulting $where string into ->where() on a select, then run it with $this->db->fetchAll($select).

**Q: How do you combine multiple LIKE conditions with OR?**
A: Build the first condition with quoteInto, then append further ones with quoteInto("OR $col LIKE (?)
", $pattern), as in the example matching 'gallery' or 'folder' in the source field.

**Q: How does NOT LIKE differ from LIKE?**
A: NOT LIKE negates the pattern match - for example, id NOT LIKE '1_' returns ids that don't start with 1 or don't have exactly 2 digits, and NOT LIKE conditions can be chained with AND to exclude several patterns at once.


<!-- ============================================================ -->
<!-- best-practice/what-are-returning-the-fetch-functions-from-zend-db.md -->
<!-- ============================================================ -->

---
title: "What are returning the FETCH functions from Zend_Db"
description: "A side-by-side comparison of the legacy query()/next_record()/f() row-fetching style with the fetchAll, fetchAssoc, fetchCol, fetchOne, fetchPairs, and fetchRow methods of Zend_Db_Adapter_Abstract."
author: "Teo"
date_published: "2010-06-15"
canonical_url: "https://www.dotkernel.com/best-practice/what-are-returning-the-fetch-functions-from-zend-db/"
category: "Best Practice"
language: "en"
---

# What are returning the FETCH functions from Zend_Db

## TL;DR

Continuing the Zend_Db article series, this article walks through the FETCH methods available on Zend_Db_Adapter_Abstract: fetchAll, fetchAssoc, fetchCol, fetchOne, fetchPairs, and fetchRow.
Each method is shown next to the equivalent old-style code built on query(), next_record(), and f(), so the two approaches can be compared side by side.

## Available FETCH Methods

Continuing the Zend_Db article series, this article stops at the FETCH methods found in Zend_Db_Adapter_Abstract:

```php
array  fetchAll   (string|Zend_Db_Select $sql, ...)
array  fetchAssoc (string|Zend_Db_Select $sql, ...)
array  fetchCol   (string|Zend_Db_Select $sql, ...)
string fetchOne   (string|Zend_Db_Select $sql, ...)
array  fetchPairs (string|Zend_Db_Select $sql, ...)
array  fetchRow   (string|Zend_Db_Select $sql, ...)
```

To make it easier to follow, each example below shows the classical, old-style query first, followed by the equivalent query written in Zend_Db style.

## Connecting to the Database

Initialize the connection to the MySQL database:

```php
$db = Zend_Db::factory('Pdo_Mysql', $dbConnect);
```

## Setting Up the Query

Here is a SQL query that we want to fetch:

```sql
$sql = "SELECT id, title FROM files";
$db->query($sql)
```

Here is the same query written in Zend_Db style:

```php
$select = $db->select()
             ->from('files', array('id', 'title'))
```

Note: the old style of fetching shown below uses an older class.
Here's what you need to know about its methods:

- `query()` is similar to `mysqli_query()` from the Mysqli PHP extension
- `next_record()` is similar to `mysqli_next_result()` from the Mysqli PHP extension
- `f()` retrieves the value of the column specified as a parameter

## fetchAll

Old style:

```php
while($db->next_record())
{
    $a[] = array(
                 'id' => $db->f('id'),
                 'title' => $db->f('title')
                 );
}
```

Zend_Db style:

```php
$a = $db->fetchAll($select);
```

## fetchAssoc

Old style:

```php
while($db->next_record())
{
    $a = array(
                             'id' => $db->f('id'),
                             'title' => $db->f('title')
                            );
}
```

Zend_Db style:

```php
$a = $db->fetchAssoc($select);
```

## fetchCol

Old style:

```php
while($db->next_record())
{
    $a[] = $db->f('id');
}
```

Zend_Db style:

```php
$a = $db->fetchCol($select);
```

## fetchOne

Old style:

```php
$db->next_record();
$a = $db->f('id');
```

Zend_Db style:

```php
$a = $db->fetchOne($select);
```

## fetchPairs

Old style:

```php
while($db->next_record())
{
    $a = $db->f('title');
}
```

Zend_Db style:

```php
$a = $db->fetchPairs($select);
```

## fetchRow

Old style:

```php
$db->next_record();
$a = array(
           'id' => $db->f('id'),
           'title' => $db->f('title')
          );
```

Zend_Db style:

```php
$a = $db->fetchRow($select);
```

## FAQ

**Q: What FETCH methods are available in Zend_Db_Adapter_Abstract?**
A: The article covers fetchAll, fetchAssoc, fetchCol, fetchOne, fetchPairs, and fetchRow.

**Q: What does fetchAll do compared to the old query style?**
A: `$a = $db->fetchAll($select)` replaces the old-style loop that calls `next_record()` repeatedly and builds an array of associative rows using `f()` for each column.

**Q: What does fetchRow return?**
A: `$a = $db->fetchRow($select)` returns a single row as an associative array, replacing a single `next_record()` call followed by `f()` calls for each column.

**Q: What does fetchOne return?**
A: `$a = $db->fetchOne($select)` returns a single value, replacing a single `next_record()` call followed by one `f()` call.

**Q: How do the old-style query(), next_record(), and f() methods relate to Mysqli?**
A: `query()` is similar to `mysqli_query()`, `next_record()` is similar to `mysqli_next_result()`, and `f()` retrieves the value of the column specified as a parameter.


<!-- ============================================================ -->
<!-- best-practice/why-use-current-timestamp-on-a-field-that-record-date-time.md -->
<!-- ============================================================ -->

---
title: "Why use CURRENT_TIMESTAMP on a field that record date/time?"
description: "Why a TIMESTAMP column should default to CURRENT_TIMESTAMP on insert, how ON UPDATE CURRENT_TIMESTAMP keeps it fresh on every update, and how the DEFAULT/ON UPDATE clause combinations behave."
author: "Teo"
date_published: "2010-06-29"
canonical_url: "https://www.dotkernel.com/best-practice/why-use-current-timestamp-on-a-field-that-record-date-time/"
category: "Best Practice"
language: "en"
---

# Why use CURRENT_TIMESTAMP on a field that record date/time?

## TL;DR

On a TIMESTAMP field that records date and time when inserting a new record, it's encouraged to use the CURRENT_TIMESTAMP constant as its DEFAULT value.
This removes the need to set the value manually from PHP or with MySQL's NOW() function, and the ON UPDATE CURRENT_TIMESTAMP clause can additionally keep the field updated automatically on every row update.
Only one TIMESTAMP field per table can be DEFAULT CURRENT_TIMESTAMP.

## Why Use CURRENT_TIMESTAMP as a Default

On a TIMESTAMP field that records date and time when inserting a new record, it is encouraged to use the CURRENT_TIMESTAMP constant as a DEFAULT value.
Because when inserting a new row in the table, there is no need to specifically add the value for the date and time field, either by creating it from PHP code with the Date/Time functions or with MySQL's NOW() function:

```sql
ALTER TABLE `user` CHANGE `dateCreated` `dateCreated` TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP;
```

## Automatically Updating with ON UPDATE CURRENT_TIMESTAMP

CURRENT_TIMESTAMP is also a solution for updating date and time fields.
Use the `ON UPDATE CURRENT_TIMESTAMP` clause if you want the value of the field to be changed automatically each time the row is updated:

```sql
ALTER TABLE `user` CHANGE `dateLogin` `dateLogin` TIMESTAMP ON UPDATE CURRENT_TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP;
```

## DEFAULT and ON UPDATE Clause Combinations

DEFAULT and ON UPDATE clauses can be used together or separately, depending on your needs:

- With both `DEFAULT CURRENT_TIMESTAMP` and `ON UPDATE CURRENT_TIMESTAMP` clauses, the column has the current timestamp for its default value and is automatically updated.
- With neither `DEFAULT` nor `ON UPDATE` clauses, it is the same as `DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP` (only for the first TIMESTAMP field in the table).
- With a `DEFAULT CURRENT_TIMESTAMP` clause and no `ON UPDATE` clause, the column has the current timestamp for its default value but is not automatically updated.
- With no `DEFAULT` clause and with an `ON UPDATE CURRENT_TIMESTAMP` clause, the column has a default of 0 and is automatically updated.
- With a constant `DEFAULT` value, the column has the given default and is not automatically initialized to the current timestamp.
If the column also has an `ON UPDATE CURRENT_TIMESTAMP` clause, it is automatically updated; otherwise, it has a constant default and is not automatically updated.

For more details, check out the [MySQL Manual](https://dev.mysql.com/doc/refman/9.7/en/datetime.html).

Note: only one timestamp field can be `DEFAULT CURRENT_TIMESTAMP` in a table.

## FAQ

**Q: Why use CURRENT_TIMESTAMP as a DEFAULT value for a date/time field?**
A: Because when inserting a new row, there is no need to specifically set the date/time value yourself, either from PHP Date/Time functions or with MySQL's NOW() function.

**Q: How do you make a field update its timestamp automatically on every UPDATE?**
A: Add the ON UPDATE CURRENT_TIMESTAMP clause, for example: `ALTER TABLE `user` CHANGE `dateLogin` `dateLogin` TIMESTAMP ON UPDATE CURRENT_TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP`.

**Q: What happens if a TIMESTAMP column has neither a DEFAULT nor an ON UPDATE clause?**
A: For the first TIMESTAMP field in the table, having neither clause is the same as DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP.

**Q: What happens with a DEFAULT CURRENT_TIMESTAMP clause but no ON UPDATE clause?**
A: The column gets the current timestamp as its default value but is not automatically updated afterward.

**Q: Can more than one TIMESTAMP column default to CURRENT_TIMESTAMP in the same table?**
A: No. Only one timestamp field in a table can be DEFAULT CURRENT_TIMESTAMP.


<!-- ============================================================ -->
<!-- best-practice/zf-is-retired-laminas-mvc-is-retiring-consider-it-solved.md -->
<!-- ============================================================ -->

---
title: "ZF Is Retired. Laminas MVC Is Retiring. Consider It Solved"
description: "What the Laminas MVC retirement announcement means, why legacy MVC platforms are a liability, and how Apidemia helps teams migrate to the Mezzio middleware architecture."
author: "Florin Bidirean"
date_published: "2025-07-17"
canonical_url: "https://www.dotkernel.com/best-practice/zf-is-retired-laminas-mvc-is-retiring-consider-it-solved/"
category: "Best Practice"
language: "en"
---

# ZF Is Retired. Laminas MVC Is Retiring. Consider It Solved

## TL;DR

Laminas MVC is retiring, following Zend Framework and Apigility before it, but this doesn't mean everything with a Laminas logo is going away - Mezzio, built on Laminas components, is the fully-functional successor.
Maintaining legacy MVC platforms is costly and risky long-term, since the architecture of today and tomorrow is middleware-based, and Apidemia offers a proven, phased migration process to move legacy platforms to Mezzio.

## A Bit of History

It all started with the announcement: Laminas MVC Is Retiring.
Some people wrongfully thought everything with a Laminas logo is going away - not so.
Read on for a bit of history about Zend and Laminas, what it means to migrate your platform, and why it's a decision that should not be taken lightly.

Laminas MVC is not even the first framework that has reached its end of life - look at Zend Framework and Apigility.
Letting go of a flagship product is a difficult decision, but it's made easier when you leave a solid alternative in its wake.
The developers who worked on Laminas MVC already had something better and fully-functional in place - the Mezzio microframework, built using Laminas components.
It has itself gone through rigorous development and testing since being released in 2015, when it was known as Zend Expressive, then was renamed into Mezzio to get to its current state.

## What Is the Issue with Legacy Platforms?

Maintaining legacy platforms over the long term is often a costly and time-consuming endeavour.
Every few years, platform owners must consider the viability of migrating to a newer platform.

Newer platforms implement modern architectures, have an active community, and are actively being developed and maintained.
They also offer easier development, expansion, and maintenance, alongside vital security improvements and more reliable dependencies.

Sounds like an easy decision? Sure, but it's a lot of work, and that's when the specialists come into play.

We at Apidemia have been using the Zend Framework, Laminas MVC, and Mezzio for years.
We understand their ins-and-outs intimately, which enables us to analyze and perform the transfer of a legacy platform to Mezzio effectively.
Working with Mezzio ensures faster execution times, increased security, faster development, and long-term reliability from all points of view.
We encourage this change and are ready to offer guidance.

## Pain Points

The MVC architecture is obsolete.
It is yesterday's architecture, fit for monolithic websites.
The architecture of today and tomorrow is based on middleware, building headless platforms, websites, and microservices following the same coding approach.

| Pain Point | Apidemia Solution |
|---|---|
| Legacy framework is deprecated and/or has no long-term support | Apidemia helps migrate to modern middleware architecture (Mezzio microframework with Laminas components) |
| Legacy applications are hard to maintain | Modern architecture improves code quality, testability and performance |
| Migration is risky or expensive | Apidemia uses a proven, phased migration strategy to reduce risk |
| Lack of internal development expertise | Apidemia provides end-to-end guidance, refactoring, training and support |

## How Apidemia Handles Migrations

Apidemia has created a complex process that involves several steps to ensure a smooth migration.
In a nutshell, the current project functionality must be understood, and only then can the move be implemented into the destination platform.
Over the long run, the Apidemia team offers support and training.

This is the simplified task list:

- Code audit & migration strategy - to understand the code and see what goes where.
- Partial or full migration to Laminas or PSR-compliant frameworks, like Mezzio or Symfony - this decision impacts both time to implement and cost, negotiated with the client.
- Refactoring and decoupling legacy modules - the old code must go and be replaced with the new.
- Unit testing and CI/CD pipeline setup - a vital step to ensure things function the same way in the destination platform.
- Post-migration support and team training - this step depends on the level of collaboration between the original developers and the Apidemia team, so the more closely they work together, the easier it is to onboard the devs for the long run.

## FAQ

**Q: What is Laminas MVC being replaced by?**
A: Mezzio microframework, built using Laminas components. It has gone through rigorous development and testing since being released in 2015, when it was known as Zend Expressive, before being renamed Mezzio.

**Q: Why is maintaining legacy platforms a problem?**
A: Maintaining legacy platforms over the long term is often costly and time-consuming, so every few years platform owners must consider migrating to a newer platform that offers modern architecture, an active community, easier development/expansion/maintenance, security improvements, and more reliable dependencies.

**Q: What is the core architectural pain point with legacy MVC platforms?**
A: The MVC architecture is obsolete, fit for monolithic websites. Today's and tomorrow's architecture is based on middleware, building headless platforms, websites, and microservices following the same coding approach.

**Q: What steps does Apidemia's migration process involve?**
A: A simplified task list: code audit & migration strategy; partial or full migration to Laminas or PSR-compliant frameworks like Mezzio or Symfony; refactoring and decoupling legacy modules; unit testing and CI/CD pipeline setup; and post-migration support and team training.

**Q: Who offers this migration guidance?**
A: Apidemia, who has used Zend Framework, Laminas MVC, and Mezzio for years and can analyze and perform the transfer of a legacy platform to Mezzio, offering faster execution times, increased security, faster development, and long-term reliability.

## Resources

- [Dotkernel Headless Platform](https://www.dotkernel.com/headless-platform/dotkernel-headless-platform-the-whats-hows-and-whys/)
- [Shared Core Submodule in Dotkernel Headless Platform](https://www.dotkernel.com/headless-platform/shared-core-submodule-in-dotkernel-headless-platform/)
- [Understanding Middleware](https://www.dotkernel.com/architecture/understanding-middleware/)
- [Dotkernel Light](https://www.dotkernel.com/dotkernel/dotkernel-light-starting-with-mezzio-microframework-and-laminas-components/)
- [Migrate Laminas MVC to Dotkernel](https://www.apidemia.com/services/migrate-laminas-mvc-to-dotkernel/)


<!-- ============================================================ -->
<!-- dotkernel-api/api-client-migration-from-postman-to-bruno.md -->
<!-- ============================================================ -->

---
title: "API Client Migration: From Postman to Bruno"
description: "Why the Dotkernel team is considering switching their API testing client from Postman to the offline-focused, Git-native Bruno."
author: "Florin Bidirean"
date_published: "2026-03-25"
canonical_url: "https://www.dotkernel.com/dotkernel-api/api-client-migration-from-postman-to-bruno/"
category: "Dotkernel API"
language: "en"
---

# API Client Migration: From Postman to Bruno

## TL;DR

The team has used Postman for years but is considering switching to Bruno, a lightweight, offline-first alternative, reflecting a broader PHP community trend toward local-first, Git-native developer tools.
Bruno wins on offline access, version control via Git, performance, and (arguably) security, while Postman still offers a broader feature set for larger, budget-having teams.

## Why We Switched to the Offline-Focused Bruno

Every API developer needs a reliable client for testing and interacting with the API - ideally free, able to store and share endpoint collections easily with a team, fast, and secure.
Postman has been the team's go-to tool for years, but they are now considering Bruno, part of a general trend in the PHP community toward local-first, Git-native developer tools.

## Comparing Postman to Bruno

| Aspect | Postman | Bruno |
|---|---|---|
| Architecture | Free plan limited to one user account | Fully-offline experience via shared `.bru` files; no restriction on number of developers |
| Version control | Handled in the cloud; requires being online (export/import via UI possible) | `.bru` files saved directly in the Git repository, versioned via Git like any other file |
| Feature scope | Complete platform for the API lifecycle (mocking, documentation, CI/CD integration) | Focused mainly on interacting with the API, writing simple tests, and building local collections |
| Performance | Needs to regularly sync with the cloud and store advanced features in RAM, which can introduce delays | Uses much less RAM and is generally faster |
| Security | Offers Single Sign-On (SSO) and Role-Based Access Control (RBAC) | Local files never leave the dev environment, arguably more secure |
| Collection sharing | Limited sharing for multi-member dev teams | Can share via Git, `.zip` file, or a single `.yaml` file; Git is the preferred option |

### Comparison Conclusion

Postman is currently a better fit for larger teams willing to allocate a budget for a more feature-rich platform.
Bruno stores collections in Git, so everything is offline, which the team considers more secure while also being generally faster.

## Alternative API Clients

Bruno is only one of several alternatives to Postman:

- Hoppscotch - runs in the browser or as a PWA
- Insomnia - clear UI and large plugin ecosystem
- HTTPie - focuses on terminal-based workflows
- Thunder Client - built into Visual Studio Code
- Apidog - covers the whole API lifecycle
- Yaak - minimal and fast desktop client

Any of them can get the job done; the decision comes down to choosing a simple, reliable tool for the foreseeable future.

## Bruno for Dotkernel

Bruno currently seems like the best match for the team, offering similar functionality to Postman plus the ability to work completely offline and save endpoint collections to their GitHub accounts.
The offline feature weighed most heavily in the decision.

### Tool Migration

Since most of the team has only worked with Postman, switching tools can affect efficiency at first, and tool migration can have an emotional impact as developers relearn a new tool's ins and outs.
Given Bruno's straightforward approach and reasonable learning curve, the team expects this to be mitigated easily, and views the switch as an expansion of their expertise that avoids getting tied to one tool.

### How Long Will Bruno Last?

The team expects Bruno may eventually restrict developers with paid plans too, just like Postman did, but plans to cross that bridge when they get to it.
For now, Bruno is becoming their de facto API client, and the whole team is being encouraged to adopt it as soon as possible.

## FAQ

**Q: Why is the team considering a switch from Postman to Bruno?**
A: They want a reliable API testing client that is free, stores and shares endpoint collections easily with the team, and is fast and secure.
This reflects a broader trend in the PHP community toward local-first, Git-native developer tools.

**Q: What is the main architectural difference between Postman and Bruno?**
A: Postman's free plan now only allows one user account, while Bruno offers a fully-offline experience based on shared `.bru` files, so there is no restriction on the number of developers using them.

**Q: How does version control differ between the two tools?**
A: Postman stores collections and handles version control in the cloud, forcing developers to stay online (though collections can be exported/imported via its UI).
Bruno's `.bru` files can be saved directly in a Git repository and are version-controlled through Git like any other project file.

**Q: How does performance compare between Postman and Bruno?**
A: Bruno is the clear winner on performance: it uses much less RAM and is generally faster.
Postman needs to regularly synchronize with the cloud and store its advanced features in RAM, which can introduce delays.

**Q: Is Bruno more secure than Postman?**
A: Postman offers Single Sign-On (SSO) and Role-Based Access Control (RBAC), which the team doesn't find useful for its workflow.
Bruno's local files never leave the dev environment, which the article argues makes it more secure, especially for avoiding sharing client files with online tools.

**Q: What's the overall conclusion on Postman versus Bruno?**
A: Postman is currently a better fit for larger teams willing to allocate a budget for a more feature-rich platform.
Bruno stores collections in Git so everything works offline, which the team considers more secure while also being generally faster, and it has become their de facto API client.

## Resources

- [Bruno homepage](https://www.usebruno.com/)
- [Hoppscotch](https://hoppscotch.io/)
- [Insomnia](https://insomnia.rest/)
- [HTTPie](https://httpie.io/)
- [Thunder Client](https://www.thunderclient.com/)
- [Apidog](https://apidog.com/)
- [Yaak](https://yaak.app/)


<!-- ============================================================ -->
<!-- dotkernel-api/api-endpoint-to-collect-client-errors.md -->
<!-- ============================================================ -->

---
title: "API Endpoint to Collect Client Errors"
description: "How Dotkernel API's error-report endpoint lets frontend clients submit and log errors that occur on the user's machine."
author: "kakapiciu"
date_published: "2022-11-07"
canonical_url: "https://www.dotkernel.com/dotkernel-api/api-endpoint-to-collect-client-errors/"
category: "Dotkernel API"
language: "en"
---

# API Endpoint to Collect Client Errors

When a Frontend (e.g. Angular) sits on top of a Dotkernel API, errors can happen - the API's response may have changed overnight, or a variable may simply be `undefined`.
Since the Frontend runs on the user's own client, there's little that can be done about it directly, so an endpoint was created to let clients submit the error message when something goes wrong.

## Usage

Send a POST request to your Dotkernel API on the route:

```
https://api.dotkernel.net/error-report
```

With a body:

```shell
{
    "message": "My awesome error!!!"
}
```

Note: the error message is stored by default in `/log/error-report-endpoint-log.log`, a separate log for Client, and the message is saved together with a timestamp.

## FAQ

**Q: Why was this endpoint created?**
A: When a Frontend client (e.g. Angular) running on the user's machine hits an error against the Dotkernel API - whether from an overnight API response change or a simple undefined variable - there is little that can be done from the client side, so this endpoint lets clients "write down" the error instead.

**Q: How do I submit an error from the client?**
A: Send a simple POST request to your Dotkernel API's `https://api.dotkernel.net/error-report` route, with a body such as `{ "message": "My awesome error!!!" }`.

**Q: Where is the submitted error message stored?**
A: By default, it is stored in a separate log file for Client, `/log/error-report-endpoint-log.log`, with the message saved alongside a timestamp.

## Resources

- [Dotkernel API on GitHub](https://github.com/dotkernel/api)


<!-- ============================================================ -->
<!-- dotkernel-api/content-negotiation-in-dotkernel-rest-api.md -->
<!-- ============================================================ -->

---
title: "Content Negotiation in Dotkernel REST API"
description: "How content negotiation works in RESTful APIs, who decides the data format, and how Dotkernel API implements it."
author: "Florin Bidirean"
date_published: "2024-11-27"
canonical_url: "https://www.dotkernel.com/dotkernel-api/content-negotiation-in-dotkernel-rest-api/"
category: "Dotkernel API"
language: "en"
---

# Content Negotiation in Dotkernel REST API

## TL;DR

Content negotiation lets clients and servers agree on the format and language of exchanged data.
It can be handled server-side or client-side (the latter being more versatile), communicated through HTTP headers or URL patterns, and Dotkernel API implements it out of the box using the `Content-Type` and `Accept` headers.

## What is the Purpose of Content Negotiation?

RESTful resources can support multiple representations, and efficient client-server communication depends on both sides agreeing on the exchanged data format - this agreement is content negotiation.
It ensures:

- **Support for diverse clients**, e.g. `Accept: application/json` or `Accept: application/xml`.
- **Data format flexibility**, e.g. using `Accept: application/msgpack` (a binary serialization) instead of JSON for a smaller, easier-to-transfer response.
- **Language localization**, e.g. `Accept-Language: en-US`, to respond with content translated into the client's preferred language.

## Who Decides the Data Format?

Either the client or the server can decide:

- **Server-side negotiation**: the server decides the format based on various factors.
This can introduce erroneous assumptions and a more complex server-side implementation, and forces the client to adhere to the server's rules.
- **Client-side negotiation**: the client tells the server what format it prefers.
This approach is more versatile and makes more sense.

There are two ways to communicate the preferred data format: HTTP request headers, or resource URI patterns.

### HTTP Request Headers

The `Content-Type` and `Accept` headers determine the data format sent in the request and response.
Examples of types include `text/plain`, `text/html`, `application/json`, `application/zip`, `image/gif`, and `image/jpeg`.

```shell
Content-Type: application/json, text/plain
Accept: application/json
```

If the `Accept` header is not present, the server decides the response format.

### Content Negotiation Using URL Patterns

A preferred format can also be communicated via the URL extension:

```shell
https://www.example-api.com/record/47.xml
https://www.example-api.com/record/47.json
```

or via an extra query parameter:

```shell
https://www.example-api.com/record/47?format=xml
https://www.example-api.com/record/47?format=json
```

## Defining Preferences via a Quality Factor

The `Accept` header can hold multiple values with an added quality value (`q`, between 0 and 1) that defines preference or priority:

```shell
Accept: application/json,application/xml;q=0.9,*/*;q=0.8
```

In this example, the client accepts both JSON and XML, with JSON preferred. If the server can only satisfy XML, it responds with that; if it can satisfy neither, it responds with whatever it can.

## How Does Dotkernel API Handle Content Negotiation?

Out of the box, Dotkernel API uses the `Content-Type` and `Accept` HTTP request headers to handle client-side content negotiation, supporting both `application/json` and `application/hal+json`.
These can be changed as development progresses, and per-route content negotiation is also supported. Configuration lives in its own configuration file, validation is automatic, and several explicit errors are handled based on the supported format.

## FAQ

**Q: What is content negotiation?**
A: It's the act of a client and server agreeing on the format and language of the data they exchange, which is important for RESTful APIs since resources can support multiple representations.

**Q: What does content negotiation ensure?**
A: It ensures support for diverse clients (e.g. `Accept: application/json` or `Accept: application/xml`), data format flexibility for smaller responses (e.g. `Accept: application/msgpack`, a binary serialization), and language localization via headers like `Accept-Language: en-US`.

**Q: Who decides the data format, the client or the server?**
A: Either side technically can.
In server-side negotiation, the server decides based on various factors, which can introduce erroneous assumptions and more complex implementation, forcing the client to adhere to server rules.
In client-side negotiation, the client tells the server what format it prefers, which is more versatile and makes more sense.

**Q: How can the preferred data format be communicated?**
A: Via HTTP request headers (`Content-Type` and `Accept`) or via resource URI patterns, such as a file extension in the URL (e.g. `/record/47.json`) or an extra query parameter (e.g. `/record/47?format=json`).
If the `Accept` header is not present, the server decides the response format.

**Q: How does the quality factor (q) work in the Accept header?**
A: The `Accept` header can list multiple accepted formats with a `q` value between 0 and 1 to express preference, e.g. `Accept: application/json,application/xml;q=0.9,*/*;q=0.8`.
The server responds with the most preferred format it can satisfy, falling back further down the list if needed.

**Q: How does Dotkernel API handle content negotiation?**
A: Out of the box, Dotkernel API uses the `Content-Type` and `Accept` HTTP request headers to handle client-side content negotiation, supporting both `application/json` and `application/hal+json`.
These can be changed as needed, and per-route content negotiation is also supported.

## Resources

- [Content Negotiation in Dotkernel API](https://docs.dotkernel.org/api-documentation/v5/core-features/content-validation/)
- [Content types on iana.org](https://www.iana.org/assignments/media-types/media-types.xhtml)


<!-- ============================================================ -->
<!-- dotkernel-api/dotkernel-api-1-0-0-released.md -->
<!-- ============================================================ -->

---
title: "Dotkernel API 1.0.0 Released"
description: "Announcement of the Dotkernel API 1.0.0 release, a Zend Expressive 3 application for quickly building APIs, including the libraries it uses and the features it offers out of the box."
author: "Alex Karajos"
date_published: "2019-12-15"
canonical_url: "https://www.dotkernel.com/dotkernel-api/dotkernel-api-1-0-0-released/"
category: "Dotkernel API"
language: "en"
---

# Dotkernel API 1.0.0 Released

> Note: Dotkernel API has come a long way since this post was created; a newer version is documented separately.

Dotkernel API 1.0.0 was just released.

## What is Dotkernel API?

It is a Zend Expressive 3 application aiming to help developers quickly and efficiently develop an API.

## How Does It Work?

Under the hood, it uses the following libraries:

- `ezimuel/zend-expressive-api` - skeleton application on which this API is based
- `dotkernel/dot-annotated-services` (^1.1) - for handling dependency injection in your services
- `dotkernel/dot-console` (^0.1.1) - for developing console applications
- `dotkernel/dot-errorhandler` (^1.0) - which provides customizable error logging
- `dotkernel/dot-mail` (^1.0) - for sending emails via SMTP
- `zendframework/zend-expressive-authentication-oauth2` (^1.0) - for OAuth2 authentication
- `zendframework/zend-expressive-authorization-rbac` (^1.0) - for role-based permissions
- `zendframework/zend-expressive-twigrenderer` (^2.4) - for composing email bodies
- `dasprid/container-interop-doctrine` (^1.1) - database abstraction layer
- `tuupola/cors-middleware` (^0.9.4) - for automatically sending CORS headers with each request
- `swagger-api/swagger-ui` (^3.22) - for creating OpenAPI 3 documentation

## What Does It Offer?

Out-of-the-box, Dotkernel API provides the following features:

- Secure authentication via OAuth2
- Two user roles: admin and member
- Admin users are allowed to manage any user account
- Members are allowed to manage only their own accounts
- OpenAPI 3 documentation - also an interactive interface that developers can use to integrate your API

## FAQ

**Q: What is Dotkernel API?**
A: It is a Zend Expressive 3 application aiming to help developers quickly and efficiently develop an API.

**Q: What key libraries does Dotkernel API 1.0.0 use?**
A: Among others, it's built on the `ezimuel/zend-expressive-api` skeleton, and uses `dotkernel/dot-annotated-services` for dependency injection, `dotkernel/dot-console` for console applications, `dotkernel/dot-errorhandler` for error logging, `dotkernel/dot-mail` for SMTP email, `zend-expressive-authentication-oauth2` for OAuth2 authentication, `zend-expressive-authorization-rbac` for role-based permissions, and `swagger-api/swagger-ui` for OpenAPI 3 documentation.

**Q: What features does Dotkernel API 1.0.0 offer out of the box?**
A: Secure authentication via OAuth2, two user roles (admin and member), where admins can manage any user account and members can manage only their own, plus OpenAPI 3 documentation with an interactive interface developers can use to integrate the API.

## Resources

- [Dotkernel API 1.0.0 release on GitHub](https://github.com/dotkernel/api/releases/tag/v1.0.0)
- [ezimuel/zend-expressive-api](https://github.com/ezimuel/zend-expressive-api)
- [dotkernel/dot-annotated-services](https://github.com/dotkernel/dot-annotated-services)
- [dotkernel/dot-console](https://github.com/dotkernel/dot-console)
- [dotkernel/dot-errorhandler](https://github.com/dotkernel/dot-errorhandler)
- [dotkernel/dot-mail](https://github.com/dotkernel/dot-mail)
- [zendframework/zend-expressive-authentication-oauth2](https://github.com/zendframework/zend-expressive-authentication-oauth2)
- [zendframework/zend-expressive-authorization-rbac](https://github.com/zendframework/zend-expressive-authorization-rbac)
- [zendframework/zend-expressive-twigrenderer](https://github.com/zendframework/zend-expressive-twigrenderer)
- [dasprid/container-interop-doctrine](https://github.com/DASPRiD/container-interop-doctrine)
- [tuupola/cors-middleware](https://github.com/tuupola/cors-middleware)
- [swagger-api/swagger-ui](https://github.com/swagger-api/swagger-ui)
- [Newest version of Dotkernel API](https://www.dotkernel.com/headless-platform/version-7-adds-postgresql-native-uuid-and-php-8-5/)


<!-- ============================================================ -->
<!-- dotkernel-api/dotkernel-api-client-side-authorization.md -->
<!-- ============================================================ -->

---
title: "Dotkernel API Client Side Authorization"
description: "How a client application authorizes against a backend built with Dotkernel API, from the authorization request to using the access token."
author: "admin"
date_published: "2019-08-05"
canonical_url: "https://www.dotkernel.com/dotkernel-api/dotkernel-api-client-side-authorization/"
category: "Dotkernel API"
language: "en"
---

# Dotkernel API Client Side Authorization

This article covers the basic authorization of a Client application which uses a backend built using Dotkernel API.

## Authorization Request

Client application users send a POST request to the backend containing the following JSON object:

```shell
{
"grant_type": "password",
"client_id": "{API_CLIENT}",
"client_secret": "{API_CLIENT_SECRET}",
"scope": "{SCOPE}",
"username": "{USERNAME/EMAIL}",
"password": "{PASSWORD}"
}
```

## Authorization Response

If the credentials are correct, the API will return a JSON object containing the authentication data:

```shell
{
"token_type": "Bearer",
"expires_in": 86400,
"access_token": "...",
"refresh_token": "..."
}
```

When sending API requests to an endpoint which requires authorization, an `Authorization` header must be present containing `"Bearer {access_token}"`, where `{access_token}` represents the content of the key with the same name found in the authorization response.

## FAQ

**Q: What does a client send to request authorization?**
A: The client application sends a POST request to the backend with a JSON object containing `grant_type` (set to "password"), `client_id`, `client_secret`, `scope`, `username`/email, and `password`.

**Q: What does the API return when authorization succeeds?**
A: If the credentials are correct, the API returns a JSON object containing `token_type` ("Bearer"), `expires_in` (86400 seconds), an `access_token`, and a `refresh_token`.

**Q: How do I use the access token in subsequent requests?**
A: When sending API requests to an endpoint that requires authorization, include an Authorization header containing `"Bearer {access_token}"`, where `{access_token}` is the value returned in the authorization response.

## Resources

- [Dotkernel API on GitHub](https://github.com/dotkernel/api)


<!-- ============================================================ -->
<!-- dotkernel-api/dotkernel-api-server-side-authorization.md -->
<!-- ============================================================ -->

---
title: "Dotkernel API Server Side Authorization"
description: "How to configure server-side authorization in Dotkernel API, covering no-auth, authentication and authorization access levels, role inheritance, and route permissions."
author: "Alex Karajos"
date_published: "2019-09-05"
canonical_url: "https://www.dotkernel.com/dotkernel-api/dotkernel-api-server-side-authorization/"
category: "Dotkernel API"
language: "en"
---

# Dotkernel API Server Side Authorization

## TL;DR

Dotkernel API endpoints can be protected at three levels: no-auth, authentication, and authorization.
Access is configured in `config/autoload/authorization.local.php` under the `zend-expressive-authorization-rbac` key, using a `roles` section for role inheritance and a `permissions` section for route access.
Authentication endpoints require a valid Bearer token and return `401 Unauthorized` if it's missing, while authorization endpoints additionally check role permissions and return `403 Forbidden`.

This article covers the basic authorization of a Server Side application built using [Dotkernel API](https://github.com/dotkernel/api).

## Protecting an Endpoint

- no-auth: the resource can be accessed without the need of authentication/authorization
- authentication: the resource can be accessed only by authenticated users
- authorization: the resource can be accessed only by authenticated AND authorized users

Configuring access to the endpoints is done by editing the following config file: `config/autoload/authorization.local.php`.

> Note: If this file is missing from your application, locate its dist file `config/autoload/authorization.local.php.dist` and copy it as the above-mentioned `config/autoload/authorization.local.php`.

You should look for the array inside this config key: `zend-expressive-authorization-rbac`.

```php
'zend-expressive-authorization-rbac' => ,
        'member' => ,
        'guest'  => ,
    ],
    'permissions' => ,
    ],
]
```

Under the key roles you can define role inheritance.
In the above example:

- admin inherits from no other role: `'admin' => []`
- member inherits from admin: `'member' =>`
- guest inherits from member: `'guest' =>`

Of course, this setup is just a model, you should not use it in live projects because guests will end up having the same rights as admins.

Under the key permissions you can define which routes are accessible to a role.
In the above example, a member has access to the routes named avatar, users and user.

### 1. No-Auth Endpoints

These endpoints can be accessed without authentication/authorization.
Examples could be: login, register, contact etc.
Creating a route for such an endpoint will use only the handler(s) responsible for returning the content:

```php
$app->get('/users', UserHandler::class, 'users');
```

### 2. Endpoints Requiring Authentication

These endpoints can be accessed only if a valid `Bearer token` is present in the request headers.
Else, the API will return a `401 Unauthorized` response.
Creating a route for such an endpoint will have a structure similar to the following example:

```php
$app->get('/users', , 'users');
```

### 3. Endpoints Requiring Authorization

These endpoints can be accessed only if a valid `Bearer token` is present in the request headers.
Else, the API will return a `403 Forbidden` response.
Creating a route for such an endpoint will have a structure similar to the following example:

```php
$app->get('/users', , 'users');
```

## FAQ

**Q: What are the three access levels for protecting an endpoint?**
A: no-auth, where the resource can be accessed without authentication/authorization; authentication, where only authenticated users can access the resource; and authorization, where only authenticated AND authorized users can access it.

**Q: Where do I configure access to the endpoints?**
A: In `config/autoload/authorization.local.php`.
If that file is missing from your application, locate its dist file `config/autoload/authorization.local.php.dist` and copy it as `config/autoload/authorization.local.php`, then look for the array under the `zend-expressive-authorization-rbac` config key.

**Q: How does role inheritance work under the roles key?**
A: In the article's example, admin inherits from no other role, member inherits from admin, and guest inherits from member.
The article warns this exact setup is just a model and should not be used in live projects, because guests would end up having the same rights as admins.

**Q: How do I control which routes a role can access?**
A: Under the `permissions` key you define which routes are accessible to a role.
In the article's example, a member has access to the routes named avatar, users, and user.

**Q: What response codes are returned for authentication and authorization endpoints?**
A: Endpoints requiring authentication return a 401 Unauthorized response if a valid Bearer token isn't present in the request headers.
Endpoints requiring authorization return a 403 Forbidden response instead under the same condition.


<!-- ============================================================ -->
<!-- dotkernel-api/dotkernel-api-versus-laminas-api-tools.md -->
<!-- ============================================================ -->

---
title: "Dotkernel API versus Laminas API Tools"
description: "A feature-by-feature comparison of Laminas API Tools and Dotkernel API, showing why Dotkernel API is a solid alternative now that Laminas API Tools is archived."
author: "Florin Bidirean"
date_published: "2024-06-03"
canonical_url: "https://www.dotkernel.com/dotkernel-api/dotkernel-api-versus-laminas-api-tools/"
category: "Dotkernel API"
language: "en"
---

# Dotkernel API versus Laminas API Tools

## TL;DR

This article compares the basic features of Laminas API Tools and Dotkernel API side by side, covering architecture, versioning, documentation, authentication, and more.
It highlights that Dotkernel API is a solid alternative now that Laminas API Tools has been archived, since Dotkernel API uses a modern middleware architecture, MIT license, and evolution-based deprecations instead of traditional versioning.

Below is an analysis of the basic features available in Laminas API Tools and Dotkernel API.
It's intended to highlight the differences between the two and also to showcase why Dotkernel API is a good alternative for Laminas API Tools, especially considering the latter's archived status.

> The table below refers to [Dotkernel API V7](https://github.com/dotkernel/api/tree/7.0).

| | API Tools (formerly Apigility) | Dotkernel API |
|---|---|---|
| URL | [api-tools](https://api-tools.getlaminas.org/) | [Dotkernel API](https://www.dotkernel.org) |
| First Release | 2012 | 2018 |
| PHP Version | <= 8.2 | Shown via a dynamic Packagist badge (see the project repository for the current supported version) |
| Architecture | MVC, Event Driven | Middleware |
| OSS Lifecycle | Archived | Shown via a dynamic OSS Lifecycle badge (see the project repository for the current status) |
| Style | REST, RPC | REST |
| Versioning | Yes | Deprecations (API Evolution) * |
| Documentation | Swagger (Automated) | Postman (Manual), OpenAPI 3.0 (Swagger) |
| Content-Negotiation | Custom | Custom |
| License | BSD-3 | MIT |
| Default DB Layer | laminas-db | doctrine-orm 3.x |
| Authorization | ACL | RBAC-guard |
| Authentication | HTTP Basic/Digest OAuth2.0 | OAuth2.0 |
| CI/CD | Yes | Yes |
| Unit Tests | Yes | Yes |
| Code (Endpoint) Generator | Yes | [dot-maker](https://docs.dotkernel.org/dot-maker/v1/overview/) |
| PSR | PSR-7 | PSR-7, PSR-15 |

## Note

- Versioning is replaced by [Deprecations](https://docs.dotkernel.org/api-documentation/v6/tutorials/api-evolution/), using an evolution strategy.

## FAQ

**Q: What is the purpose of this comparison?**
A: It highlights the differences between Laminas API Tools and Dotkernel API, and shows why Dotkernel API is a good alternative now that Laminas API Tools is archived.

**Q: Which version of Dotkernel API does the comparison table refer to?**
A: Dotkernel API V7.

**Q: What architecture does each project use?**
A: Laminas API Tools uses an MVC, event-driven architecture, while Dotkernel API uses a middleware architecture.

**Q: What license does each project use?**
A: Laminas API Tools is licensed under BSD-3, while Dotkernel API is licensed under MIT.

**Q: How does Dotkernel API handle API versioning?**
A: Instead of traditional versioning, Dotkernel API replaces it with Deprecations, using an evolution (API Evolution) strategy.

**Q: What documentation options does each project support?**
A: Laminas API Tools generates Swagger documentation automatically, while Dotkernel API supports manual Postman documentation as well as automated OpenAPI 3.0 (Swagger) documentation.


<!-- ============================================================ -->
<!-- dotkernel-api/error-reporting-endpoint-in-dotkernel-api.md -->
<!-- ============================================================ -->

---
title: "Error reporting endpoint in Dotkernel API"
description: "How the Dotkernel API error reporting endpoint lets frontend applications securely report bugs and data errors back to the API, including server-side and frontend setup."
author: "Florin Bidirean"
date_published: "2024-08-29"
canonical_url: "https://www.dotkernel.com/dotkernel-api/error-reporting-endpoint-in-dotkernel-api/"
category: "Dotkernel API"
language: "en"
---

# Error reporting endpoint in Dotkernel API

## TL;DR

Dotkernel API includes an error reporting endpoint that lets frontend developers securely report bugs and incorrect data processing back to the API, even when no fatal error shows up in the logs.
It works by sending a POST request to `/error-report` with a token in the header; the API validates the request against configured tokens, domains, and IPs before logging the message.
Setup involves generating a token, adding it to `config/autoload/error-handling.global.php`, and having the frontend send the `Error-Reporting-Token` and `Origin` headers.

Dotkernel API has received a lot of love from our developers, with regular updates to the platform for years.
We use Dotkernel API in our projects, so any bugs and issues are addressed as soon as they are found.
Still, it's not unlikely that some hidden issues remain in fringe use cases that we simply haven't explored.
The occurrence of bugs increases when the API is used in a complex frontend project.

Fatal errors are easily found in the API logs, but it's another matter altogether to deal with incorrect data processing that doesn't generate errors in the frontend that interfaces with the API.
The error reporting endpoint was designed to allow the frontend developers of your API to report any bugs they encounter in a secure way that is fully under your control.

## Example Case Usage

- Frontend developed in Angular.
- Frontend developer will use try-catch in the code in order to send frontend errors back to the API.

## How to Use It on the API Side

Error reporting is done by sending a POST request to the `/error-report` endpoint, together with a token in the header.
In the sections below we will detail how to configure error reporting in your API and how the endpoint is used by the frontend developers.

### Generating a Token and Adding It to Your API Config

First you need to generate a token for your request.
This is done by using the below command.

```bash
php ./bin/cli.php token:generate error-reporting
```

The resulting token has this format `0123456789abcdef0123456789abcdef01234567`.
Note: this example is provided just to let you know what to look for.

Copy the generated token in your `config/autoload/error-handling.global.php` file.
It should look similar to the example below.
Your API can have multiple tokens, if needed.

```php
return ,
        ...
    ]
]
```

### Validation Mechanism

Behind the scenes, the API validates your configuration and lets you know if any config items prevent the submission of the error report.
Below are the requirements for an application to be able to send error messages to Dotkernel API.

- Server-side requirements stored in `config/autoload/error-handling.global.php` (these can be set/overwritten in `config/autoload/local.php`):
  - All keys (`enabled`, `path`, `tokens`, `domain_whitelist` and `ip_whitelist`) must exist under `ErrorReportServiceInterface::class`.
  - The error reporting feature must be enabled by setting `ErrorReportServiceInterface::class` . `enabled` to `true`.
  - `ErrorReportServiceInterface::class` . `path` must have a value; if the destination file does not exist, it will be created automatically.
  - `ErrorReportServiceInterface::class` . `tokens` must contain at least one token.
  - At least one of `ErrorReportServiceInterface::class` . `domain_whitelist`/`ip_whitelist` must have at least one value.

Note: In `src/App/src/Service/ErrorReportService.php`, the method `checkRequest()` tries to validate the request by checking matches for `domain_whitelist` with `isMatchingDomain()` and for `ip_whitelist` with `isMatchingIpAddress()`.
If both return `false`, a `ForbiddenException` is thrown and the error message does not get stored.

- Application-side requirements:
  - Send the `Error-Reporting-Token` header with a valid token previously stored in `config/autoload/error-handling.global.php` in the `ErrorReportServiceInterface::class` . `tokens` array.
  - Send the `Origin` header set to the application's URL; this is the application that sends the error message.

Note:

- The tokens under `ErrorReportServiceInterface::class` . `tokens` do not expire.
- The log file stores the token value too, making it easy to identify which application sent the error message.

If your request passes all the checks, the message is saved in the log file specified in `ErrorReportServiceInterface::class` . `path`.

### Tips and Tricks

If there are multiple applications that report errors to your API, you can assign a different error reporting token for each.
The tokens support key-value pairs where:

- The key is an alias relevant to the assigned application that uses it.
- The value is the token itself.

Example:

```php
// ...
return ,
    ],
];
```

The log file will have entries similar to the below:

> Demo error message

The inclusion of the token helps you identify the source of the error message.
In our example, it's the application that uses the `0123456789abcdef0123456789abcdef01234567` token, which is assigned to the application `frontend`.

## How to Use It on the Frontend Side (Angular Example)

The API developer sends a generated token to the frontend developer who will save it in their `environment.staging.ts` and/or `environment.prod.ts`.
From then on, it's the frontend developer's job to set up an error reporting function similar to the one below.

```typescript
postError(body: object): Promise<any> {
     return new Promise((resolve, reject) => {
      return this.http.post(API_ENDPOINT + 'error-report', body , {headers: new HttpHeaders({'Error-Reporting-Token': 'TOKEN', 'Origin': 'https://example.com'})})).subscribe({
        next: (response: any) => {
          resolve(response);
        },
        error: (e: HttpErrorResponse) => reject(e),
        complete: () => console.info('Error on sending error'),
      });
    });
  }
```

Whenever an error is found, the frontend will call `postError()` with a relevant description under `message`.

```typescript
apiService.postError({message: 'ERROR MESSAGE'})
```

## Conclusion

The error reporting feature in Dotkernel API is a secured and highly configurable tool for users of your API to report any unwanted behavior.
More often than not, a detailed error report will help developers understand how to replicate the issue and fix it in due course.

This article is also included in the full API documentation [https://docs.dotkernel.org/api-documentation/v5/core-features/error-reporting](https://docs.dotkernel.org/api-documentation/v5/core-features/error-reporting).

## FAQ

**Q: What is the error reporting endpoint for?**
A: It lets frontend developers of an API report bugs and incorrect data processing back to the API in a secure, controlled way, which is especially useful for issues that don't show up as fatal errors in the API logs.

**Q: How do you generate a token for error reporting?**
A: Run `php ./bin/cli.php token:generate error-reporting`, then copy the resulting token into `config/autoload/error-handling.global.php`.

**Q: What server-side requirements must be met for error reporting to work?**
A: All required keys (`enabled`, `path`, `tokens`, `domain_whitelist`, `ip_whitelist`) must exist under `ErrorReportServiceInterface::class`, the feature must be enabled, `path` must have a value, `tokens` must contain at least one token, and at least one of `domain_whitelist`/`ip_whitelist` must have a value.

**Q: What headers must the frontend application send?**
A: The `Error-Reporting-Token` header with a valid stored token, and the `Origin` header set to the application's URL.

**Q: What happens if a request fails validation?**
A: The `checkRequest()` method checks the domain against `domain_whitelist` and the IP against `ip_whitelist`; if both checks fail, a `ForbiddenException` is thrown and the error message is not stored.

**Q: How is the error reporting endpoint called?**
A: By sending a POST request to the `/error-report` endpoint along with a valid token in the header.


<!-- ============================================================ -->
<!-- dotkernel-api/how-to-implement-mailchimp-in-dotkernel-api.md -->
<!-- ============================================================ -->

---
title: "How to implement MailChimp in Dotkernel API"
description: "A step-by-step guide to integrating MailChimp into a Dotkernel API instance using the drewm/mailchimp-api library, from installation to wiring up a factory in the ConfigProvider."
author: "Alex Karajos"
date_published: "2020-01-04"
canonical_url: "https://www.dotkernel.com/dotkernel-api/how-to-implement-mailchimp-in-dotkernel-api/"
category: "Dotkernel API"
language: "en"
---

# How to implement MailChimp in Dotkernel API

## TL;DR

This is a step-by-step guide to adding MailChimp support to a Dotkernel API instance using the `drewm/mailchimp-api` library.
It covers installing the library, creating a MailChimp config file, building a factory that returns a `DrewM\MailChimp\MailChimp` instance, and registering that factory in `ConfigProvider.php` so it can be injected wherever needed.

This article will walk you through the process of implementing MailChimp into your instance of [Dotkernel API](https://github.com/dotkernel/api) using [drewm/mailchimp-api](https://github.com/drewm/mailchimp-api).

Step 1: Add the library to your application using the following command:

```bash
composer require drewm/mailchimp-api
```

Step 2: Create configuration file `config/autoload/mailchimp.global.php` and paste the following content inside of it:

```php
<?php

declare(strict_types=1);

return
];
```

Step 3: Create factory `src/App/src/MailChimp/Factory/MailChimpFactory.php` which will return an instance of `DrewM\MailChimp`.
Paste the following content inside this file:

```php
<?php

declare(strict_types=1);

namespace Api\App\MailChimp\Factory;

use DrewM\MailChimp\MailChimp;
use Psr\Container\ContainerInterface;

/**
 * Class MailChimpFactory
 * @package Api\App\MailChimp\Factory
 */
class MailChimpFactory
{
    /**
     * @param ContainerInterface $container
     * @return MailChimp
     * @throws \Exception
     */
    public function __invoke(ContainerInterface $container) : MailChimp
    {
        $config = $container->get('config') ?? [];

        return new MailChimp($config ?? '');
    }
}
```

Step 4: Let your application use this factory by adding it to the main ConfigProvider.
To do this, open file `src/App/src/ConfigProvider.php` and locate the method called `getDependencies()`.
Inside this method, locate the key `factories` which points to an array.
Inside this array add the following line:

```php
MailChimp::class => MailChimpFactory::class,
```

Make sure you add the corresponding uses:

```php
use Api\App\MailChimp\Factory\MailChimpFactory;
use DrewM\MailChimp\MailChimp;
```

After this, you can start using the library by @Injecting `MailChimp::class` where it's needed.

## FAQ

**Q: Which library does this tutorial use to add MailChimp to Dotkernel API?**
A: The tutorial uses drewm/mailchimp-api, installed with the command composer require drewm/mailchimp-api.

**Q: Where do you place the MailChimp configuration file?**
A: In config/autoload/mailchimp.global.php, a new configuration file created as part of Step 2.

**Q: What does the MailChimpFactory class do?**
A: It's a factory, created at src/App/src/MailChimp/Factory/MailChimpFactory.php, that reads the config from the container and returns an instance of DrewM\MailChimp\MailChimp.

**Q: Where do you register the MailChimp factory so the application can use it?**
A: In src/App/src/ConfigProvider.php, inside the getDependencies() method's factories array, by mapping MailChimp::class to MailChimpFactory::class, plus adding the corresponding use statements for MailChimp and MailChimpFactory.

**Q: How do you use MailChimp once it's wired up?**
A: By injecting MailChimp::class wherever it's needed, using @Inject.


<!-- ============================================================ -->
<!-- dotkernel-api/openapi-implementation-in-dotkernel-api.md -->
<!-- ============================================================ -->

---
title: "OpenAPI implementation in Dotkernel API"
description: "An overview of the OpenAPI Specification, why it complements tools like Postman, and how Dotkernel API implements OpenAPI documentation across its modules."
author: "Florin Bidirean"
date_published: "2024-07-30"
canonical_url: "https://www.dotkernel.com/dotkernel-api/openapi-implementation-in-dotkernel-api/"
category: "Dotkernel API"
language: "en"
---

# OpenAPI implementation in Dotkernel API

## TL;DR

OpenAPI is a specification for describing an API's structure in a language-agnostic, machine-readable way, offering benefits like standardization, automatic documentation, upfront design, and better collaboration compared to a tool like Postman.
Dotkernel API has full OpenAPI support: each module (Admin, App, User) documents its endpoints in an `OpenAPI.php` file, which `zircote/swagger-php` turns into documentation rendered via Swagger UI or Redoc.
Testing protected endpoints in Swagger UI requires generating an authentication token that matches the endpoint's required privileges.

## What Is OpenAPI?

The OpenAPI Specification provides a consistent way to develop and interact with an API.
It defines API structure and syntax in a universal way, regardless of the programming language used in the API's development.
API specifications typically use YAML or JSON to share and use the specification.
They allow users of the API to quickly discover how it works by describing its elements, e.g. endpoints, request and response formats, security mechanisms and more.

While not mutually exclusive, OpenAPI has several benefits over Postman:

- API standardization: this offers a standard way to describe and document endpoints, request/response models, and other details of your API that enforces design best practices.
Postman has no focus on this topic.
- Automatic generation of API documentation: create comprehensive, machine-readable documentation that helps developers understand how to interact with your API.
Postman is not designed to explain the API's components.
- API design and development: define your API specification, most commonly using YAML and JSON formats, before starting development.
Postman is used only to test an existing, completed endpoint.
- Improved collaboration: this benefits frontend and backend developers, as well as operations teams.
Postman's free tier is aimed more towards individual or small team development.
- API gateways and management: a wide range of tools and platforms that support OpenAPI allow more streamlined monitoring and management of APIs.
Postman has environment management, but primarily on the developer's machine.

Other benefits from using OpenAPI:

- Code generation: automatically generate client code, server stubs, API documentation and even test cases to ensure consistency between the API documentation and implementation.
- Interoperability: standardization using OpenAPI ensures that the API can interface with other systems.
- Testing and validation: the specification can generate tests to catch bugs early on and ensure correct functionality.
- Versioning and change management: keeps track of changes and ensures backward compatibility.

## The Importance of API Documentation

API documentation, in general, is crucial for several reasons.
It serves multiple stakeholders that use the API for development, integration and maintenance.

- Faster developer onboarding, adoption and integration: helps developers understand the API better and reduces the learning curve for adopting and integrating the API into other systems.
The API documentation should be publicly available, especially if the API is public.
It's even more beneficial if the documentation is integrated with a developer portal.
- Better collaboration: promotes consistency and reduces misunderstandings between developers and users.
- Better API quality and maintenance: includes details on how to properly use the API, from its data types and required parameters, to error handling procedures.
This helps maintain existing functionality when changes are implemented.
- Helps troubleshooting: it defines the correct functionality that helps developers and maintainers find and fix bugs more effectively.

## OpenAPI in Dotkernel API

Dotkernel API has full support for OpenAPI, from describing the endpoints and generating the documentation, to rendering and testing the endpoints.

Each module (Admin, App, User) in Dotkernel API contains a file named `OpenAPI.php`.
In this file you must document all of the endpoints from `RoutesDelegator.php`.
The entries in `OpenAPI.php` have several descriptive items, the most important being method, request and response.
These are used to generate a documentation file from the command line.
The static documentation file is rendered using Swagger UI or Redoc in a user-friendly way.
You can read more about this [starting here](https://docs.dotkernel.org/api-documentation/v5/openapi/introduction/) and its subsequent pages.

### Describing OpenAPI Components

All OpenAPI components require a handful of components that are universally valid for a given project.
These are below:

- OA\Info contains basic information on your project, like version and name.
- OA\Server has one or more urls to a target host.
- OA\SecurityScheme describes the protection for the endpoint.
- OA\ExternalDocumentation has a url and description for extended documentation related to an item.
- OA\Schema describes a object (e.g. entity) or collection of objects in your project.

Read more details about the above [here](https://docs.dotkernel.org/api-documentation/v5/openapi/initialized-components/).

Once you have your basic components defined, you can begin work on the endpoints.
The endpoints already made available in Dotkernel API are documented, so you must do the same for the new endpoints you create in your project.
This is done by defining these items:

- the request object (Get, Post, Patch, Put, Delete)
- the path to the resource
- the endpoint's summary and description
- the query/path parameters, if required
- the request body, if required
- the security scheme, if required
- the response

Wherever it's appropriate, schemas should be used to ensure consistency.
The optional 'tags' item can be used to group operations together.
Read more [here](https://docs.dotkernel.org/api-documentation/v5/openapi/initialized-components/).

### Generating the Documentation

The documentation is generated using [zircote/swagger-php](https://github.com/zircote/swagger-php).
It uses the descriptions you added in the `OpenAPI.php` files to build the documentation file.
The documentation contents can be listed in the command line or saved to a file in yaml of json format.
You can read more [here](https://docs.dotkernel.org/api-documentation/v5/openapi/generate-documentation/).

### Alternatives for Rendering the Documentation

Once you have the documentation generated, it can be rendered in two ways:

- Swagger UI allows you to visualize and interact with the API's resources without worrying about the implementation logic.
- Redoc lists the documentation in read-only mode, detailing example requests and responses.

### Handling Authentication for Swagger UI

Most endpoints for your API should be protected, so to access them you are required to generate an authentication token (AuthToken).
The token is related to the user type, so make sure to check the privileges required for the endpoint you are testing.
After you submit the token, you can test the endpoints as an authenticated user.
Clicking on the 'Try it out' button will activate the required parameter input fields and the textarea for the request body.
The 'Execute' button will send the request and return the response, along with its HTTP status code.
You can read more details [here](https://docs.dotkernel.org/api-documentation/v5/openapi/use-documentation/).

## FAQ

**Q: What is the OpenAPI Specification?**
A: A consistent way to develop and interact with an API. It defines API structure and syntax in a universal way, regardless of the programming language used, typically described in YAML or JSON so users can quickly discover endpoints, request/response formats, security mechanisms and more.

**Q: How does OpenAPI compare to Postman?**
A: OpenAPI standardizes how endpoints and request/response models are described, automatically generates machine-readable documentation, lets you define the API specification before development starts, and improves collaboration across teams.
Postman, by contrast, is used mainly to test an already-completed endpoint and has no real focus on standardized documentation or upfront design.

**Q: Where do you document endpoints in Dotkernel API?**
A: Each module (Admin, App, User) contains an OpenAPI.php file, where all endpoints from that module's RoutesDelegator.php must be documented, primarily describing the method, request and response.

**Q: What core components does every OpenAPI description need?**
A: OA\Info (basic project info like version and name), OA\Server (one or more target host URLs), OA\SecurityScheme (endpoint protection), OA\ExternalDocumentation (link and description for extended docs), and OA\Schema (describing an object or collection of objects).

**Q: What generates the documentation file from the OpenAPI.php descriptions?**
A: zircote/swagger-php, which uses the descriptions added in the OpenAPI.php files to build the documentation. The result can be listed in the command line or saved to a file in YAML or JSON format.

**Q: How is the generated documentation rendered, and how do you test protected endpoints?**
A: It can be rendered with Swagger UI, which lets you visualize and interact with the API's resources, or with Redoc, which lists the documentation in read-only mode. Because most endpoints are protected, testing them in Swagger UI requires generating an authentication token (AuthToken) matching the required privileges, then using the 'Try it out' button to fill in parameters/body and 'Execute' to send the request and see the response with its HTTP status code.


<!-- ============================================================ -->
<!-- dotkernel/adding-a-cors-implementation-to-zend-expressive.md -->
<!-- ============================================================ -->

---
title: "Adding a CORS implementation to Zend Expressive"
description: "A guide on how to add a CORS implementation to an existing Dotkernel3 project using Tuupola's Cors Middleware package."
author: "Gabi DJ"
date_published: "2019-04-08"
canonical_url: "https://www.dotkernel.com/dotkernel/adding-a-cors-implementation-to-zend-expressive/"
category: "Dotkernel"
language: "en"
---

# Adding a CORS implementation to Zend Expressive

## TL;DR
When a client-side request is blocked with a "No 'Access-Control-Allow-Origin' header" error, it's because the server isn't sending the header that allows a browser to access its data (most common when fetching JSON to process with JavaScript).
This guide adds CORS support to a Zend Expressive / Dotkernel3 project using Tuupola's Cors Middleware package.

## The issue

If you're facing the error:

> "Access to XMLHttpRequest at 'url' has been blocked by cors policy.
> No 'Access-Control-Allow-Origin header is present on the requested resource."

it means the server didn't send the header that lets you access its data through a local client (e.g. a browser).
This issue is most common when trying to get data (usually JSON) that you want to process using JavaScript.

## The solution

A simple implementation uses [Tuupola's Cors Middleware](https://packagist.org/packages/tuupola/cors-middleware) package.
(This article was inspired by [akrabat.com/implementing-tuupola-cors-in-expressive](https://akrabat.com/implementing-tuupola-cors-in-expressive/).)

### 1. Add the package to your project

```shell
composer require tuupola/cors-middleware
```

At the time of writing, the current package version is 0.9.4.

### 2. Create the CORS config file

Create a `cors.global.php` file in the `config/autoload` directory:

```php
return [
    'cors' => [
        "origin" => [],
        "methods" => [],
        "headers.allow" => [],
        "headers.expose" => [],
        "credentials" => false,
        "cache" => 0,
    ],
    'dependencies' => [],
];
```

### 3. Create a factory for the middleware

The factory extracts the config from the `cors` key (or initializes an empty array) and instantiates the Tuupola CORS middleware:

```php
<?php

namespace App\Cors;

use Tuupola\Middleware\CorsMiddleware;

class CorsMiddlewareFactory
{
    public function __invoke($container)
    {
        $corsConfig = $container->get('config')['cors'] ?? [];
        return new CorsMiddleware($corsConfig);
    }
}
```

### 4. Register the CORS middleware

Back in `cors.global.php`, register the middleware so the factory above is used to create it:

```php
<?php

use App\Cors\CorsMiddlewareFactory;
use Tuupola\Middleware\CorsMiddleware;

return [
    'cors' => [
        "origin" => [],
        "methods" => [],
        "headers.allow" => [],
        "headers.expose" => [],
        "credentials" => false,
        "cache" => 0,
    ],
    'dependencies' => [
        'factories' => [
            CorsMiddleware::class => CorsMiddlewareFactory::class,
        ]
    ]
];
```

### 5. Add the CorsMiddleware to the pipeline

In `config/pipelines.php`:

```php
// don't forget the use statement
use Tuupola\Middleware\CorsMiddleware;

return function (Application $app, MiddlewareFactory $factory, ContainerInterface $container) : void {
    // ...
    $app->pipe(CorsMiddleware::class);
    // ...
};
```

Add the CORS middleware **after** the Error handler and **before** the middleware providing the data you want to access, to make sure everything runs smoothly.
This should get your project working with CORS.

## FAQ

**Q: What causes the "No 'Access-Control-Allow-Origin' header" error?**
A: It means the server didn't send the header that lets a local client, such as a browser, access its data.
This is most common when trying to fetch data (usually JSON) that you want to process using JavaScript.

**Q: What package does the article use to add CORS support?**
A: Tuupola's Cors Middleware package, installed by running `composer require tuupola/cors-middleware` in the project.

**Q: Where does the CORS configuration live?**
A: In a `cors.global.php` file created in the config/autoload directory, containing a "cors" key with settings like origin, methods, headers.allow, headers.expose, credentials, and cache.

**Q: How is the CorsMiddleware wired into the container?**
A: A CorsMiddlewareFactory extracts the "cors" config array (or an empty array if it's not provided) and instantiates Tuupola's CorsMiddleware with it.
That factory is registered under the "dependencies" > "factories" section of cors.global.php.

**Q: Where should the CORS middleware be added in the pipeline?**
A: In config/pipelines.php via `$app->pipe(CorsMiddleware::class)`, placed after the Error handler and before the middleware that provides the data you want to access.

## Resources

- [Tuupola's Cors Middleware package](https://packagist.org/packages/tuupola/cors-middleware)
- [Implementing Tuupola CORS in Expressive (inspiration article)](https://akrabat.com/implementing-tuupola-cors-in-expressive/)


<!-- ============================================================ -->
<!-- dotkernel/adding-a-second-caching-layer-to-wurfl-in-dotkernel-using-apc.md -->
<!-- ============================================================ -->

---
title: "Adding a second caching layer to WURFL in Dotkernel using APC"
description: "How adding a small, custom APC-based caching layer on top of WURFL's own cache cut response time by an order of magnitude."
author: "Adrian"
date_published: "2011-10-14"
canonical_url: "https://www.dotkernel.com/dotkernel/adding-a-second-caching-layer-to-wurfl-in-dotkernel-using-apc/"
category: "Dotkernel"
language: "en"
---

# Adding a second caching layer to WURFL in Dotkernel using APC

## TL;DR
On a high-traffic project using WURFL, profiling showed WURFL's default filesystem cache was costing up to a few hundred milliseconds per request. Adding a small, custom second cache layer on top of WURFL, built on APC, cut response time by an order of magnitude, down to 20-30ms.

## The problem

On one recent project that used WURFL, response time was an important factor.
Profiling revealed that the greatest chunk of response time (up to a few hundred milliseconds) was taken up by WURFL.
The default filesystem cache turned out to be too slow for a relatively high-traffic application.

## How WURFL's caching works

1. The device data is stored at first in a large, zipped XML file, with one entry for each device.
2. When first called, WURFL unzips the file and reads each device entry.
3. It then serializes the data and writes it to the cache, using an MD5 signature for the file name (or key name if the cache is not on the filesystem).
4. When a user agent is looked up, its MD5 signature is computed and then searched in the cache.
5. Because the data is stored as a tree, with each device inheriting the properties of the nodes above it, **each look-up requires a number of files to be read and their capabilities merged** to get all the capabilities of the requested device.

WURFL also has cache providers for APC and memcache, which were tried, but the results weren't impressive.

## The solution

The team realized their approach was wrong for their use case - the WURFL entry for a device has lots of fields that weren't actually used.

The solution was adding a **second cache layer** on top of WURFL's own cache, which only cached the fields that were actually needed. This second layer used **APC**, storing arrays of data in **User Cache Entries**.

This small change (under 10 lines of code) decreased response time by an **order of magnitude**, down to 20-30ms.

## FAQ

**Q: Why was WURFL's default caching too slow for this project?**
A: Profiling revealed that WURFL's default filesystem cache was taking up to a few hundred milliseconds of response time, which was too slow for a relatively high-traffic application.

**Q: How does WURFL's caching work by default?**
A: Device data is stored in a large zipped XML file.
On first use, WURFL unzips the file, serializes each device's data, and writes it to cache using an MD5 signature of the user agent as the key.
Because devices are stored as a tree inheriting properties from parent nodes, each lookup requires reading and merging several files.

**Q: Did WURFL's built-in APC or memcache cache providers solve the problem?**
A: No. The team tried WURFL's existing cache providers for APC and memcache, but the results weren't impressive.

**Q: What was the actual solution?**
A: Adding a second cache layer on top of WURFL's own cache, using APC and storing arrays of only the specific fields they actually needed in User Cache Entries.
The change was under 10 lines of code.

**Q: What performance improvement did this bring?**
A: Response time decreased by an order of magnitude, down to about 20-30ms.


<!-- ============================================================ -->
<!-- dotkernel/adding-composer-support-in-your-dotkernel-project.md -->
<!-- ============================================================ -->

---
title: "Adding Composer support in your Dotkernel project"
description: "The steps needed to add Composer support to a Dotkernel 1.x project, or 'composify' it."
author: "Gabi DJ"
date_published: "2016-04-04"
canonical_url: "https://www.dotkernel.com/dotkernel/adding-composer-support-in-your-dotkernel-project/"
category: "Dotkernel"
language: "en"
---

# Adding Composer support in your Dotkernel project

## TL;DR
Composer is an application-level package manager that auto-loads dependencies (and custom classes) on demand.
This article covers the steps needed to add a composer.json file to a Dotkernel project, run `composer update`, and safely require the generated autoloader so the project works whether or not Composer is present.

## First things first

The Dotkernel project must have a **composer.json** file so that Composer can work.
It should look like this:

```json
{
  "require" : {
    "zendframework/zendframework1" : "1.12.*",
    "mobiledetect/mobiledetectlib" : "2.8.*"
  },
  "require-dev" : {
    "php" : ">=5.4.0"
  }
}
```

Note: `zendframework/zendframework1` may not be necessary if you already have ZendServer running or the Zend Framework folder within `/usr/share/`.

This file makes sure:

- Zend Framework is present and at version > 1.12.*
- MobileDetect is present and at version > 2.8
- The PHP executable is at least at version > 5.4.0 (only for development, because it is not present in the main `require`)

The dependencies provided in the `require` section are also loaded for development purposes if not provided in `require-dev`.

In order to have these components installed, run the following command in your Dotkernel root path:

```shell
composer update
```

If the `vendor` folder is present, Composer will check for updates and update the packages as needed. If the `vendor` folder does not exist, Composer will create it, containing all the requested packages, along with an autoload file used to load the dependencies/packages.

## Adding Composer Support to Dotkernel

The autoload file created by Composer is used to load the packages:

```php
$composerAutoLoaderPath = realpath(APPLICATION_PATH.'/vendor/autoload.php');
require_once($composerAutoLoaderPath);
```

But what if the file does not exist, or Composer is not present?
First make sure the Composer autoload path exists, and only load the dependencies if the autoload file was found:

```php
$composerAutoLoaderPath = realpath('./vendor/autoload.php');

$composerEnabled = file_exists($composerAutoLoaderPath);

if ($composerEnabled == true) {
    require_once($composerAutoLoaderPath);
} else {
    // handle the error gracefully
    // or load fallbacks - if exist
}
```

The variable `$composerEnabled` will be true only if the Composer path exists, so the application behavior can be controlled if Composer is not present.

Later on, the packages can be used like this:

```php
use VendorName\PackageName\ClassName as MyDependency;

$myDependency = new MyDependency($neededArguments);
$myDependency->doSomething();
```

This article works for any **Dotkernel 1.x** version if your server is running **PHP >5.4.0**.

## FAQ

**Q: What does Composer do?**
A: Composer is an application-level package manager.
It auto-loads dependencies on demand and can also auto-load custom classes.

**Q: What must a Dotkernel project have before Composer can be used?**
A: A composer.json file, for example requiring zendframework/zendframework1 at 1.12.* and mobiledetect/mobiledetectlib at 2.8.*, plus PHP >=5.4.0 listed under require-dev.

**Q: What happens when you run composer update?**
A: If the vendor folder already exists, Composer checks for and applies updates to the packages.
If it doesn't exist, Composer creates the vendor folder containing all requested packages, along with an autoload file.

**Q: How do you safely load the Composer autoloader in case Composer isn't present?**
A: Check whether vendor/autoload.php exists using file_exists() before calling require_once() on it, and handle the case gracefully (for example by loading fallbacks) if the path is missing.

**Q: Which Dotkernel versions does this apply to?**
A: The article states it works for any Dotkernel 1.x version, as long as the server is running PHP greater than 5.4.0.

## Resources

- [Composer install / PHP dependency manager tutorial](https://www.codementor.io/php/tutorial/composer-install-php-dependency-manager)


<!-- ============================================================ -->
<!-- dotkernel/adding-windows-10-os-and-browser-detection-in-dotkernel-projects.md -->
<!-- ============================================================ -->

---
title: "Adding Windows 10 OS and Browser detection in Dotkernel projects"
description: "A guide to installing the patch that adds Windows 8, 8.1 and 10 OS icons and the Microsoft Edge browser icon in Dotkernel."
author: "Gabi DJ"
date_published: "2015-09-08"
canonical_url: "https://www.dotkernel.com/dotkernel/adding-windows-10-os-and-browser-detection-in-dotkernel-projects/"
category: "Dotkernel"
language: "en"
---

# Adding Windows 10 OS and Browser detection in Dotkernel projects

## TL;DR
Dotkernel added Windows 8, 8.1 and 10 OS icons and a Microsoft Edge browser icon, shown in the User and Admin login icons.
This article is the upgrade guide for applying that icon patch.

## Upgrade steps

1. Make sure your project is running version **1.5.0** or **newer**.
2. Download the [patch](http://www.dotkernel.com/download/?did=46).
3. Extract the archive into a folder, e.g. `icons_patch`.
4. Create a backup of your project before continuing (recommended).
5. Copy all the files in the `icons_patch` folder into your Dotkernel project.
6. You will be prompted to replace 2 files - replace them and agree to merge the folders' content (other files will be added, not replaced).
7. Clear the cache for changes to take effect, since the OS and browser XMLs are cached (see "Dotkernel Reserved Variable Names for Caching", the "Browser & OS" section).
8. You can now delete the `icons_patch` folder, or keep it to patch another project.

## Affected files

```
M /configs/useragent/browser.xml
M /configs/useragent/os.xml
A /images/browsers/edge.png
A /images/os/windows_metro.png
```

`M` stands for **modify**, `A` stands for **add**.

## FAQ

**Q: What Dotkernel version is required before applying this patch?**
A: Your project must be running version 1.5.0 or newer.

**Q: Which files does the patch modify or add?**
A: It modifies configs/useragent/browser.xml and configs/useragent/os.xml, and adds images/browsers/edge.png and images/os/windows_metro.png.

**Q: Why do you need to clear the cache after applying the patch?**
A: Because the OS and browser XML files are cached, so the new icons won't show up until the cache is cleared.

**Q: Will applying the patch overwrite existing files?**
A: You'll be prompted to replace 2 files (browser.xml and os.xml) and should agree, and also agree to merge the folders' contents since the other files listed are added rather than replaced.

## Resources

- [Icon patch download](http://www.dotkernel.com/download/?did=46)
- [Dotkernel Reserved Variable Names for Caching](http://www.dotkernel.com/dotkernel/dotkernel-reserved-variable-names-for-caching)


<!-- ============================================================ -->
<!-- dotkernel/autologin-using-cookie-remember-me-in-dotkernel.md -->
<!-- ============================================================ -->

---
title: "Autologin using Cookie / Remember Me in Dotkernel"
description: "A step-by-step guide to implementing a Remember Me / autologin feature in Dotkernel Frontend."
author: "SergiuB"
date_published: "2022-07-18"
canonical_url: "https://www.dotkernel.com/dotkernel/autologin-using-cookie-remember-me-in-dotkernel/"
category: "Dotkernel"
language: "en"
---

# Autologin using Cookie / Remember Me in Dotkernel

## TL;DR
This feature automatically logs in a user who checks the "remember me" box at login.
It has been implemented in [Dotkernel Frontend](https://github.com/dotkernel/frontend) starting from Release 3.3.0, and requires changes across the login form, a new entity/migration, a new middleware, config, and the user service/repository/controller.

## Add remember me button to user interface

Navigate to `src/User/templates/user/login.html.twig` and, under the password element, add:

```twig
<div class="checkbox remember-me-checkbox">
     {% set rememberMe = form.get('rememberMe') %}
     {{ formElement(rememberMe) }}
     <p>Remember me</p>
</div>
```

Then navigate to `src/User/src/Form/LoginForm.php` and add the following element to your form:

```php
$this->add([
    'name' => 'rememberMe',
    'type' => 'checkbox',
    'attributes' => [
        'class' => 'tooltips',
        'data-toggle' => 'tooltip',
        'title' => 'Remember me',
    ],
]);
```

Then navigate to `src/User/src/InputFilter/LoginInputFilter.php` and add a filter for the new element:

```php
$this->add([
            'name' => 'rememberMe',
            'filters' => [
                ['name' => 'StringTrim']
            ],
            'validators' => [
                [
                    'name' => 'NotEmpty',
                    'break_chain_on_failure' => true,
                ]
            ]
        ]);
```

To style the button, navigate to `src/App/assets/scss/components/_profile.scss` and add:

```scss
.remember-me-checkbox {
  input {
    display: block;
    float: left;
    margin: 4px 6px 10px 0;
    width: auto;
    height: auto;
  }
}
```

After making the changes, compile the CSS so the button styling takes effect:

```shell
npm run prod
```

## Add functionality to remember me button

1. Navigate to `src/User/src/Entity`, create a new entity named `UserRememberMe.php`, modeled on [UserRememberMe](https://github.com/dotkernel/frontend/blob/3.0/src/User/src/Entity/UserRememberMe.php).
2. Create a migration file for the new table:
   ```shell
   vendor/bin/phinx create --configuration=config/migrations.php  RememberUserSchema
   ```
3. Modify the generated migration file as in [user_remember_schema](https://www.dotkernel.com/dotkernel/autologin-cookie-remember-me-feature/), then run it against the database:
   ```shell
   vendor/bin/phinx migrate --configuration=config/migrations.php
   ```
   The table generated by the migration is used to store data from the cookie, which helps log the user in automatically.
4. Create a new middleware at `src/App/src/Middleware/RememberMeMiddleware.php`, modeled on [RememberMeMiddleware](https://github.com/dotkernel/frontend/blob/3.0/src/App/src/Middleware/RememberMeMiddleware.php).
5. Register the middleware in `config/pipeline.php` as shown in [pipeline](https://github.com/dotkernel/frontend/blob/3.0/config/pipeline.php).
6. To generate the cookie, add a new key to `config/autoload/local.php`:
   ```php
   'rememberMe' => [
            'cookie' => [
                'name' => 'rememberMe',
                'lifetime' => 3600 * 24 * 30,
                'samesite' => 'Lax',
                'secure' => false,
                'httponly' => true
            ]
        ],
   ```
7. Edit `src/User/src/Service/UserService.php`: add two new properties, `$defaultSessionManager` (to get config) and `$repository` (to get repository), then add the methods `getRepository()`, `addRememberMeToken()`, `deleteRememberMeCookie()` as in [UserService](https://github.com/dotkernel/frontend/blob/3.0/src/User/src/Service/UserService.php) (and add the new methods to the interface if needed).
8. Edit `src/User/src/Repository/UserRepository.php` and add the methods `saveRememberUser()`, `getRememberUser()`, `findRememberMeUser()`, `deleteExpiredCookies()`, `removeRememberUser()` as in [UserRepository](https://github.com/dotkernel/frontend/blob/3.0/src/User/src/Repository/UserRepository.php).
9. Edit `src/User/src/Controller/UserController.php`: add a new property called `$config`, and edit `loginAction()` and `logoutAction()` as in [UserController](https://github.com/dotkernel/frontend/blob/3.0/src/User/src/Controller/UserController.php).

## FAQ

**Q: Since which release is Remember Me implemented in Dotkernel?**
A: It's implemented in Dotkernel Frontend starting from Release 3.3.0.

**Q: How do you add the Remember Me checkbox to the login UI?**
A: In src/User/templates/user/login.html.twig, under the password element, render the rememberMe element retrieved via form.get('rememberMe') with formElement().

**Q: What form and validation changes are needed?**
A: A 'rememberMe' checkbox element must be added to src/User/src/Form/LoginForm.php, and a StringTrim filter plus a NotEmpty validator must be added for it in src/User/src/InputFilter/LoginInputFilter.php.

**Q: What backend pieces implement the actual remember-me functionality?**
A: A new UserRememberMe entity, a database migration (created and run with phinx) for its table, a new RememberMeMiddleware registered in config/pipeline.php, a rememberMe cookie configuration block added to config/autoload/local.php, and new methods added to UserService, UserRepository, and UserController (including loginAction() and logoutAction()).

**Q: What does the UserRememberMe table store?**
A: It's used to store data from the cookie, which helps log the user in automatically.

**Q: How do you apply the new remember-me button styles?**
A: Add the CSS to src/App/assets/scss/components/_profile.scss, then run npm run prod to compile the CSS so the button styling takes effect.

## Resources

- [Dotkernel Frontend on GitHub](https://github.com/dotkernel/frontend)
- [UserRememberMe entity example](https://github.com/dotkernel/frontend/blob/3.0/src/User/src/Entity/UserRememberMe.php)
- [Remember user schema migration example](https://www.dotkernel.com/dotkernel/autologin-cookie-remember-me-feature/)
- [RememberMeMiddleware example](https://github.com/dotkernel/frontend/blob/3.0/src/App/src/Middleware/RememberMeMiddleware.php)
- [pipeline.php example](https://github.com/dotkernel/frontend/blob/3.0/config/pipeline.php)
- [UserService example](https://github.com/dotkernel/frontend/blob/3.0/src/User/src/Service/UserService.php)
- [UserRepository example](https://github.com/dotkernel/frontend/blob/3.0/src/User/src/Repository/UserRepository.php)
- [UserController example](https://github.com/dotkernel/frontend/blob/3.0/src/User/src/Controller/UserController.php)


<!-- ============================================================ -->
<!-- dotkernel/avoid-routing-through-bootstrap-of-non-existent-files.md -->
<!-- ============================================================ -->

---
title: "Avoid routing through bootstrap of non existent files"
description: "How to stop missing static files from being routed through the bootstrap and logging out users whose session regenerates on each request."
author: "admin"
date_published: "2013-11-29"
canonical_url: "https://www.dotkernel.com/dotkernel/avoid-routing-through-bootstrap-of-non-existent-files/"
category: "Dotkernel"
language: "en"
---

# Avoid routing through bootstrap of non existent files

In some cases you may encounter missing files: images, CSS, or JS files.
All those missing files are processed by the current bootstrap: `index.php`.

If the session is set to regenerate on each request, as a normal security measure, the currently logged-in user is logged off, because the session ID is different now.

To avoid this, below the following line:

```
RewriteEngine On
```

add the line:

```
RewriteCond %{REQUEST_FILENAME} (\.gif|\.jpg|\.png|\.css|\.js)$
```

Save, and don't forget to test.

## FAQ

**Q: What problem does this fix address?**
A: When missing static files (images, CSS, JS) are routed through the bootstrap (index.php) and the session is set to regenerate on each request, the currently logged-in user gets logged off because the session ID changes.

**Q: What is the fix?**
A: Below the "RewriteEngine On" line, add a RewriteCond matching file extensions like .gif, .jpg, .png, .css, and .js, so requests for those files are not routed through the bootstrap.


<!-- ============================================================ -->
<!-- dotkernel/caching-in-dotkernel-using-zend-framework.md -->
<!-- ============================================================ -->

---
title: "Caching in Dotkernel using Zend Framework"
description: "How Dotkernel's upcoming 1.8 cache layer stores router, ACL, menu and other data between requests, using APC/APCU or file storage."
author: "Gabi DJ"
date_published: "2015-01-29"
canonical_url: "https://www.dotkernel.com/dotkernel/caching-in-dotkernel-using-zend-framework/"
category: "Dotkernel"
language: "en"
---

# Caching in Dotkernel using Zend Framework

## TL;DR
Loading configuration and settings from XML files on every request is expensive, both due to hard-drive latency and XML parsing overhead.
Dotkernel 1.8 implements a cache layer for router, acl_role, menu, options (including seo_xml), browser_xml, os_xml and test data, with a choice of APC/APCU or file-based storage.

## 1. Configuring the cache

The configuration is set from `/configs/application.ini`: whether caching is enabled, how long the cache stays valid, the cache namespace, and the storage provider (File or APC).
The article recommends disabling the cache in development mode.
See [Configuring the Cache in Dotkernel](http://www.dotkernel.com/dotkernel/configuring-the-cache-in-dotkernel/) for more details.

## 2. Using the cache

The cache is automatically loaded during initialization and stored in the Registry - loading it manually is not needed because it's already loaded on kernel initialization (see `Dot_Kernel::initialize($startTime)`).
If you want to use caching outside of that normal initialization, load it with:

```php
Dot_Cache::loadCache();
```

Note: the cache key must match a specific RegEx pattern.

Example of object caching:

```php
$id = 'MyCachedKey';
$obj = new stdClass();
$obj->text = 'I am a cached text';

// saving an object
Dot_Cache::save(obj, $id);

// loading the object
$value = Dot_Cache::load($id);

// checking if we have the object in cache
if ($value !== false) {
     // assuming we only need the text value from the object
     echo $value->text;
} else {
     echo 'no value cached for '. $id ;
}
```

## FAQ

**Q: What data does Dotkernel's cache layer store?**
A: Router, acl_role, menu, options (including seo_xml), browser_xml, os_xml, and test data between requests.

**Q: What storage providers are available for the cache?**
A: Two cache factories to choose from: APC (or APCU for newer PHP installations) and File.

**Q: Where is the cache configured?**
A: In /configs/application.ini, where you can enable or disable caching, set how long the cache stays valid, choose the cache namespace, and pick the storage provider (File or APC).
The article recommends disabling the cache in development mode.

**Q: Do you need to manually load the cache engine?**
A: No, it's automatically loaded during kernel initialization (Dot_Kernel::initialize()).
Manually calling Dot_Cache::loadCache() is only needed if you want to use caching outside of that normal initialization.

**Q: Can you cache PHP objects, not just simple values?**
A: Yes, the article shows an example of saving and loading a stdClass object using Dot_Cache::save() and Dot_Cache::load().

## Resources

- [Dotkernel Reserved Variable Names for Caching](http://www.dotkernel.com/dotkernel/dotkernel-reserved-variable-names-for-caching)
- [Configuring the Cache in Dotkernel](http://www.dotkernel.com/dotkernel/configuring-the-cache-in-dotkernel/)


<!-- ============================================================ -->
<!-- dotkernel/camelcase-table-names-in-mysql-on-windows.md -->
<!-- ============================================================ -->

---
title: "camelCase Table Names in MySQL on Windows"
description: "How to fix MySQL on WAMP/XAMPP lowercasing camelCase table names by setting lower_case_table_names=2 in my.cnf."
author: "admin"
date_published: "2010-03-12"
canonical_url: "https://www.dotkernel.com/dotkernel/camelcase-table-names-in-mysql-on-windows/"
category: "Dotkernel"
language: "en"
---

# camelCase Table Names in MySQL on Windows

If you are using a WAMP stack, like WAMP or XAMPP, and try to create a table in camelCase (example: `adminLogin`), you will notice that camelCase is not working - the table name will be lowercase: `adminlogin`.

In order to fix this, add the following line to your `my.cnf` file:

```
lower_case_table_names=2
```

and restart MySQL.

## FAQ

**Q: What happens when you create a camelCase table name on WAMP or XAMPP?**
A: A table created with a camelCase name, for example adminLogin, ends up stored as all lowercase, e.g. adminlogin, instead.

**Q: How do you fix it?**
A: Add the line `lower_case_table_names=2` to your my.cnf file and restart MySQL.

## Resources

- [MySQL lower_case_table_names documentation](http://dev.mysql.com/doc/refman/4.1/en/server-system-variables.html#sysvar_lower_case_table_names)


<!-- ============================================================ -->
<!-- dotkernel/commitment-to-php-new-zend-certified-engineers-zce-in-our-team.md -->
<!-- ============================================================ -->

---
title: "Commitment to PHP - new Zend Certified Engineers - ZCE - in our team"
description: "Two more team members passed the ZCE exam, bringing the team's total to 5 Zend Certified Engineers."
author: "admin"
date_published: "2012-04-20"
canonical_url: "https://www.dotkernel.com/dotkernel/commitment-to-php-new-zend-certified-engineers-zce-in-our-team/"
category: "Dotkernel"
language: "en"
---

# Commitment to PHP - new Zend Certified Engineers - ZCE - in our team

Another 2 of our team members passed the ZCE exam.
Now we are 5.
That means we are really taking PHP into serious consideration, and at the very least we have good technical skills.

See the [Zend Yellow Pages](http://www.zend.com/store/education/certification/yellow-pages.php#list-cid=0&sid=&certtype_zf=1&certtype_php=1&certtype=&firstname=&lastname=&company=Dotboost%20Technologies&ClientCandidateID=).

## FAQ

**Q: How many Zend Certified Engineers does the team have?**
A: According to the article, 2 more team members passed the ZCE exam, bringing the team's total to 5 Zend Certified Engineers.

## Resources

- [Zend Yellow Pages listing](http://www.zend.com/store/education/certification/yellow-pages.php#list-cid=0&sid=&certtype_zf=1&certtype_php=1&certtype=&firstname=&lastname=&company=Dotboost%20Technologies&ClientCandidateID=)


<!-- ============================================================ -->
<!-- dotkernel/configuring-the-cache-in-dotkernel.md -->
<!-- ============================================================ -->

---
title: "Configuring the Cache in Dotkernel"
description: "A configuration guide for Dotkernel's Zend Framework Cache-based caching layer, covering the main frontend settings and the optional per-backend settings."
author: "Gabi DJ"
date_published: "2015-01-29"
canonical_url: "https://www.dotkernel.com/dotkernel/configuring-the-cache-in-dotkernel/"
category: "Dotkernel"
language: "en"
---

# Configuring the Cache in Dotkernel

## TL;DR

Dotkernel's caching layer is built on Zend Framework Cache and is configured through `cache.*` settings in `application.ini`.
The main frontend settings control whether caching is enabled, which cache service to use, the namespace prefix, and how long entries live.
Optional backend-specific settings (like the file cache directory) are recommended so that separate projects don't accidentally share the same cache.

This article contains the Dotkernel cache layer configuration guide.
The Dotkernel Caching Layer is based on Zend Framework Cache; more configuration options can be found at the following links:

- [Zend Framework Cache Frontends](http://framework.zend.com/manual/1.12/en/zend.cache.frontends.html)
- [Zend Framework Cache Backends](http://framework.zend.com/manual/1.12/en/zend.cache.backends.html)

## Main Cache Settings (Cache Frontend)

The main cache settings within the application.ini file should look like this:

```ini
cache.enable = true
cache.factory = "apc"
cache.lifetime = "86400"
cache.namespace = "dotkernel"
```

The cache.enable option can be used to disable caching, mostly used in the development stage.
The cache.factory value will be the cache service we want to use: file or apc.
The cache.namespace will be the cache variables prefix, and the cache.lifetime value will define how long the cached variables will be usable before they need to be re-cached.

## Individual Cache Settings (Cache Backend)

The individual cache settings are optional, but it's highly recommended that you have these values set, otherwise other projects might use the same cache.

```ini
; file caching settings
cache.file.cache_dir = APPLICATION_PATH "/cache"
cache.file.cache_file_perm = 0600
```

For more settings and caching alternatives, see the Zend Framework Cache links at the beginning of the article.
The setting pattern and sample are below:

```ini
cache.BACKEND_NAME.SETTING = "VALUE"
; example:
cache.file.file_name_prefix = "Dotkernel"
```

## FAQ

**Q: What is Dotkernel's caching layer based on?**
A: It's based on Zend Framework Cache, configured through settings in application.ini, with more configuration options available at the Zend Framework Cache Frontends and Backends documentation links given in the article.

**Q: What does the cache.enable setting do?**
A: It can be used to disable caching, which is mostly useful during the development stage.

**Q: What values can cache.factory take?**
A: The cache.factory value is the cache service to use, and the article lists two options: file or apc.

**Q: Why bother setting the individual/backend cache settings like cache.file.cache_dir?**
A: These settings are optional, but the article highly recommends setting them, otherwise other projects might end up using the same cache.


<!-- ============================================================ -->
<!-- dotkernel/dependency-injection-made-easy-in-laminas-mezzio-applications.md -->
<!-- ============================================================ -->

---
title: "Dependency Injection made easy in Laminas/Mezzio applications"
description: "Introduces Dotkernel's dot-dependency-injection package, which autowires constructor dependencies in Laminas/Mezzio applications via a PHP attribute instead of a hand-written factory per class."
author: "Claudiu Pintiuta"
date_published: "2024-06-20"
canonical_url: "https://www.dotkernel.com/dotkernel/dependency-injection-made-easy-in-laminas-mezzio-applications/"
category: "Dotkernel"
language: "en"
---

# Dependency Injection made easy in Laminas/Mezzio applications

## TL;DR

Dotkernel's dot-dependency-injection package autowires constructor dependencies in Laminas/Mezzio (and other PSR-11) applications, removing the need to write and maintain a custom factory class for every service.
Instead of a bespoke factory, you add an attribute to the class constructor and register a single shared AttributedServiceFactory in your ConfigProvider.
The package requires Doctrine ORM but can still be used in applications that don't integrate Doctrine, and it also supports injecting Doctrine repositories directly instead of fetching them from the EntityManager.

> Note: The package requires Doctrine ORM. Still, it can be used in applications which do not integrate Doctrine.

So, first thing first, the problem.
You have a Laminas / Mezzio application with a bunch of services that you need to use in a, let's say, controller class or in any other class, and you are tired of building, updating, and maintaining factories every time you add a new dependency to your class.

Dotkernel has you covered.
We built a tool to autowire those dependencies in your class.
There is no need for factories for every class you make.
Just use one "factory" class that you tie to your custom class in the config, and that's it.

Sounds easy, right?
Let's finish with the chat and speak some code, first showing the problem and then the solution.

> The examples below are from the [Dotkernel API framework](https://github.com/dotkernel/api), but the pattern applies to all laminas and mezzio applications and to all PSR-11 applications.

```php
class UserHandler implements RequestHandlerInterface
{
    public function __construct(
        protected UserServiceInterface $userService,
        protected array $config,
    ) {
    }
}
```

Above, we have a UserHandler (Controller), and we have the required dependencies: `UserService` and `config`.
Normally, we would build a factory for this to get things from the container and put them in the config provider like this:

```php
class UserHandlerFactory
{
    /**
     * @throws ContainerExceptionInterface
     * @throws NotFoundExceptionInterface
     */
    public function __invoke(ContainerInterface $container)
    {
        $userService = $container->get(UserService::class);
        assert($userService instanceof UserService);

        $config = $container->get('config');

        return new UserHandler($userService, $config);
    }
}
```

And in the config provider, we would have the following:

```php
public function getDependencies(): array
{
    return
    ];
}
```

In one more example, let's look at the real-world required dependencies for `UserService`, the dependency that is required for `UserHandler`.

```php
class UserService implements UserServiceInterface
{
    public function __construct(
        protected UserRoleServiceInterface $userRoleService,
        protected MailService $mailService,
        protected TemplateRendererInterface $templateRenderer,
        protected OAuthAccessTokenRepository $oAuthAccessTokenRepository,
        protected OAuthRefreshTokenRepository $oAuthRefreshTokenRepository,
        protected UserRepository $userRepository,
        protected UserDetailRepository $userDetailRepository,
        protected UserResetPasswordRepository $userResetPasswordRepository,
        protected LoggerInterface $logger,
        protected array $config = [],
    ) {
    }
}
```

Now consider that we need to build the factory for this and update it when we add a new dependency, and so on.
We'd also need to build the logic in the factory to handle any dependencies missing from the container.
Painful, right?

Now let's use Dotkernel's [dot-dependency-injection](https://github.com/dotkernel/dot-dependency-injection) package to inject the required dependency into your class.

After you install the package, your class needs to `use Dot\DependencyInjection\Attribute\Inject`, then you need to add the `#` attribute to the constructor definition to specify which dependencies should be injected.

```php
use Dot\DependencyInjection\Attribute\Inject;

class UserHandler implements RequestHandlerInterface
{
    #
    public function __construct(
        protected UserServiceInterface $userService,
        protected array $config,
    ) {
    }
}
```

Add the `Dot\DependencyInjection\Factory\AttributedServiceFactory` class to your `ConfigProvider`:

```php
public function getDependencies(): array
{
    return
    ];
}
```

That's right, the `AttributedServiceFactory` class is the only one you need to add to your config, so you are ready to go.
This class will "build" the factory for you and will handle all the logic if any dependencies are not found in the container, with appropriate exceptions and messages.

One more time, let's see how the `UserService` will look now.

```php
class UserService implements UserServiceInterface
{
    use Dot\DependencyInjection\Attribute\Inject;

    #
    public function __construct(
        protected UserRoleServiceInterface $userRoleService,
        protected MailService $mailService,
        protected TemplateRendererInterface $templateRenderer,
        protected OAuthAccessTokenRepository $oAuthAccessTokenRepository,
        protected OAuthRefreshTokenRepository $oAuthRefreshTokenRepository,
        protected UserRepository $userRepository,
        protected UserDetailRepository $userDetailRepository,
        protected UserResetPasswordRepository $userResetPasswordRepository,
        protected LoggerInterface $logger,
        protected array $config = [],
    ) {
    }

}
```

## And, That's Not All.

If you use Doctrine and the repository pattern and you don't want to get your repository from `EntityManager` and want to inject it into your service, this package covers that too.
The principle is the same, and for more insight about this, you can check the package documentation at [dot-dependency-injection](https://docs.dotkernel.org/dot-dependency-injection/).

## FAQ

**Q: What problem does dot-dependency-injection solve?**
A: In Laminas/Mezzio applications, developers normally have to build, update, and maintain a factory class for every class that needs dependencies. dot-dependency-injection autowires those dependencies instead, so you don't need a factory for every class.

**Q: Does dot-dependency-injection require Doctrine ORM?**
A: The package requires Doctrine ORM, but the article notes it can still be used in applications that don't integrate Doctrine.

**Q: How do you mark a class's constructor dependencies for injection?**
A: Import Dot\DependencyInjection\Attribute\Inject in the class, then add the attribute to the constructor definition to specify which dependencies should be injected.

**Q: What do you need to add to the ConfigProvider to use this package?**
A: Only the Dot\DependencyInjection\Factory\AttributedServiceFactory class needs to be added to your config's dependencies. It builds the factory for you and handles the logic for dependencies missing from the container, with appropriate exceptions and messages.

**Q: Can this package be used with the Doctrine repository pattern?**
A: Yes. If you don't want to fetch a repository from the EntityManager and instead want to inject it directly into your service, the article says this package covers that too, following the same principle, with more details in the package documentation.


<!-- ============================================================ -->
<!-- dotkernel/detecting-mobile-devices-in-dotkernel-1-6-0.md -->
<!-- ============================================================ -->

---
title: "Detecting Mobile Devices in Dotkernel 1.6.0"
description: "Explains how mobile device detection changed in Dotkernel 1.6.0 with the move to Wurfl Cloud, including the required application.ini settings and sample Dot_UserAgent usage code."
author: "deddu"
date_published: "2012-05-18"
canonical_url: "https://www.dotkernel.com/dotkernel/detecting-mobile-devices-in-dotkernel-1-6-0/"
category: "Dotkernel"
language: "en"
---

# Detecting Mobile Devices in Dotkernel 1.6.0

## TL;DR

Dotkernel 1.6.0 no longer ships with a working built-in mobile detection method, because mobile detection now relies on the new Wurfl Cloud integration and must be configured via a Wurfl Cloud account and API key.
The old Dot_UserAgent_Wurfl class was removed and replaced by Dot_UserAgent_WurflCloud, which uses the Wurfl Cloud API adapter.
The article walks through the application.ini settings and shows sample code for reading device info and redirecting mobile visitors.

The new Dotkernel version 1.6.0 is coming with some changes to how we detect mobile devices; these changes are because of the new Wurfl Cloud integration.
This version of Dotkernel no longer comes with a working built-in method for mobile detection, so first we have to configure it.

- Go to the scientiamobile website and register for a Wurfl Cloud account.
- Choose device_os and mobile_browser for your account and save.
- Go to API Keys and copy the right key into application.ini.

We chose device_os and mobile_browser capabilities because with these two capabilities we can get some extra capabilities (isMobile, isSmartPhone, isIphone, isAndroid, isBlackberry, isSymbian, and isWindowsMobile) using our built-in methods.
Choosing other capabilities from scientiamobile will result in wrong detection of these extra capabilities, but you can get only those capabilities using another method from the Dot_UserAgent_WurflCloud class.

Wurfl Cloud setting in application.ini:

```ini
resources.useragent.wurflcloud.active = TRUE
resources.useragent.wurflcloud.redirect = TRUE
resources.useragent.wurflcloud.cache = TRUE
resources.useragent.wurflcloud.cache_lifetime = 3600
resources.useragent.wurflcloud.cache_namespace = WURFLCLOUD
resources.useragent.wurflcloud.api_key = 000000:XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
resources.useragent.wurflcloud.lib_dir = APPLICATION_PATH "/library/WurflCloud/"
```

- active - used to turn on (TRUE) or off (FALSE) the Wurfl Cloud detection (default: TRUE).
- redirect - if TRUE, visitors from the frontend will be redirected to the mobile module (default: TRUE).
- cache - caches every distinct result to optimize the number of requests to scientiamobile (default: TRUE).
- cache_lifetime - time in seconds to keep the results in cache (default: 3600).
- cache_namespace - the prefix used for cache keys (default: WURFLCLOUD).
- api_key - the API key from your WURFL Cloud account (change this to your own key).
- lib_dir - the Wurfl Cloud library location in Dotkernel (don't change this, unless you want to move the library).

Because of these changes, we removed the old Dot_UserAgent_Wurfl class and added the new Dot_UserAgent_WurflCloud class, which uses the Wurfl Cloud API adapter.

## Example of Dot_UserAgent Usage in Dotkernel

Get Wurfl configuration:

```php
$wurflConf = $registry->configuration->resources->useragent->wurflcloud;
```

Note: you can have more Wurfl configurations if you have more libraries, like the Wurfl Package (GPL).

If Wurfl is active, then get device info:

```php
if($wurflConf->active)
{
    $deviceInfo = Dot_UserAgent :: getDeviceInfo($_SERVER);
    ...
}
```

If the detected device is a mobile device, we save the device info in the database and redirect it to the mobile controller:

```php
if( (0 < count((array)$deviceInfo)) && $deviceInfo->isMobile)
{

    if(!$registry->session->visitId)
    {
        $registry->session->visitId = Dot_Statistic::registerVisit();
    }

    // if the Statistic module is integrate, record the deviceInfo too, and record TRUE
        //in $session->mobile
    if(!$registry->session->mobile)
    {
        $registry->session->mobile =
                Dot_Statistic::registerMobileDetails($registry->session->visitId, $deviceInfo);

        //redirect to mobile controller , only if the session is not set.
        //Otherwise will trap the user in mobile controller
        if($wurflConf->redirect)
        {
            header('location: '.
                        $registry->configuration->website->params->url.'/mobile');
            exit;
        }
    }
}
```

## FAQ

**Q: Why did mobile detection change in Dotkernel 1.6.0?**
A: Because of the new Wurfl Cloud integration. This version no longer ships with a working built-in method for mobile detection, so it must be configured first.

**Q: What are the steps to configure Wurfl Cloud detection?**
A: Go to the scientiamobile website and register for a Wurfl Cloud account, choose the device_os and mobile_browser capabilities for the account and save, then go to API Keys and copy the key into application.ini.

**Q: Why choose the device_os and mobile_browser capabilities specifically?**
A: With these two capabilities, Dotkernel's built-in methods can also derive extra capabilities such as isMobile, isSmartPhone, isIphone, isAndroid, isBlackberry, isSymbian, and isWindowsMobile. Choosing other capabilities from scientiamobile results in wrong detection of these extra capabilities.

**Q: What happened to the old Dot_UserAgent_Wurfl class?**
A: It was removed and replaced with the new Dot_UserAgent_WurflCloud class, which uses the Wurfl Cloud API adapter.

**Q: What does the redirect setting in application.ini control?**
A: When resources.useragent.wurflcloud.redirect is TRUE (the default), visitors from the frontend are redirected to the mobile module the first time a mobile device is detected.


<!-- ============================================================ -->
<!-- dotkernel/disable-wurfl-redirect-for-mobile-browsers.md -->
<!-- ============================================================ -->

---
title: "Disable Wurfl redirect for mobile browsers"
description: "Shows the application.ini setting introduced in revision 408 to control Dotkernel's automatic Wurfl-based redirect of mobile visitors to the mobile site, and the code that checks it."
author: "Adrian"
date_published: "2011-01-31"
canonical_url: "https://www.dotkernel.com/dotkernel/disable-wurfl-redirect-for-mobile-browsers/"
category: "Dotkernel"
language: "en"
---

# Disable Wurfl redirect for mobile browsers

## TL;DR

Dotkernel's example mobile site normally relies on Wurfl to detect mobile browsers and automatically redirect visitors there on their first homepage view, which isn't always desired.
As of revision 408, this behavior is controlled by a single `resources.useragent.wurflapi.redirect` setting in application.ini.
The article shows that setting along with the matching condition in `IndexController.php` that checks it before registering and redirecting a visit.

Dotkernel has an example mobile site at [http://v1.dotkernel.net/mobile](http://v1.dotkernel.net/mobile) that uses [jQuery Mobile](http://jquerymobile.com/).
Wurfl is also used to detect mobile browsers (as discussed in a [previous blog post](http://www.dotkernel.com/dotkernel/wurfl-zend-framework-integration-into-dotkernel/)) and automatically redirect them to the mobile site the first time they view the homepage.
Sometimes this behavior isn't desired (for example when you don't have a mobile site, or you don't plan on using Wurfl at all).

Starting with revision 408, there's an option in application.ini to disable the automatic redirect (by default the redirect is disabled):

```ini
resources.useragent.wurflapi.redirect = false
```

The following condition is also added to Controllers/frontend/IndexController.php (at line 19) to check the configuration:

```php
//if automatic redirect is enabled in application.ini and the browser is mobile and session->mobileHit is not set, register it and redirect
if($config->resources->useragent->wurflapi->redirect && 'mobile' == Dot_Kernel::getDevice()->getType() && !isset($session->mobileHit))
```

## FAQ

**Q: How do you disable the automatic mobile redirect in Dotkernel?**
A: Starting with revision 408, set resources.useragent.wurflapi.redirect = false in application.ini. Per the article, this is also the default state of the redirect option.

**Q: Where in the code is this configuration option checked?**
A: In Controllers/frontend/IndexController.php (around line 19), a condition checks whether the redirect is enabled in application.ini, whether the visiting browser is mobile, and whether session->mobileHit isn't already set, before registering and redirecting the visit.


<!-- ============================================================ -->
<!-- dotkernel/disambiguation-dotkernel-1-and-dotkernel-3.md -->
<!-- ============================================================ -->

---
title: "Disambiguation: Dotkernel 1 and Dotkernel 3"
description: "Clarifies what Dotkernel 1 and Dotkernel 3 are, how they differ architecturally, and which version is meant when someone simply says 'Dotkernel'."
author: "Gabi DJ"
date_published: "2017-04-24"
canonical_url: "https://www.dotkernel.com/dotkernel/disambiguation-dotkernel-1-and-dotkernel-3/"
category: "Dotkernel"
language: "en"
---

# Disambiguation: Dotkernel 1 and Dotkernel 3

## TL;DR

Dotkernel 1 is the original PHP Application Framework built on Zend Framework 1 with an MVC architecture, released in 2010 and now in bugfix-only mode at version 1.8 LTS.
Dotkernel 3 is a newer collection of PSR-7 middleware applications built on the Zend Expressive microframework and Zend Framework 3 components, implementing PSR-1, PSR-2, PSR-4, PSR-7, and PSR-11.
Since Dotkernel 3's release, the unqualified name "Dotkernel" refers to Dotkernel 3, while Dotkernel 1 is always referenced explicitly.

## What Is Dotkernel?

The name Dotkernel symbiotically combines the string Dot, as a representation of the Internet, and Kernel, the quintessence of any IT application.
In other words, Dotkernel wishes to be, with modesty, the central part of Internet development, ensuring increased development productivity and run-time performance.

## What Is Dotkernel 1?

Dotkernel 1 is a PHP Application Framework, built on top of Zend Framework 1 (ZF1).
It had its first public release in July 2010.
It is tightly coupled with Zend Framework 1, and adds a set of custom or external features (such as Router, Template Engine, etc.).
It is composed of Zend Framework 1 and a set of custom or external features (such as Router, Template Engine, etc.).
Dotkernel 1's architecture is based on MVC.

The latest version is 1.8 Long Term Support.
No new version will be released anymore, only bugfixes.

## What Is Dotkernel 3?

A collection of PSR-7 Middleware applications built on top of the [Zend Expressive](https://docs.zendframework.com/zend-expressive/) microframework.
It is composed of a set of custom and extended [Zend Framework 3](https://framework.zend.com/) components.
Dotkernel 3's architecture is based on Middleware.
Dotkernel implements the following PSRs: PSR-1, PSR-2, PSR-4, PSR-7, PSR-11.

Currently there are 2 applications: Frontend and Admin, and a 3rd one is under development: API.

## Dotkernel = Dotkernel 1 or Dotkernel 3?

In posts older than 2017, Dotkernel 1 was referred to as Dotkernel, because it was the only Dotkernel version.
Since the release of Dotkernel 3, it is referred to as Dotkernel 3 or Dotkernel.
All future references to Dotkernel 1 will be explicitly made.

### As of Dotkernel 3 Release:

Dotkernel 1 = Dotkernel 1
Dotkernel 3 = Dotkernel 3

#### Dotkernel = Dotkernel 3

## FAQ

**Q: What does the name "Dotkernel" mean?**
A: It combines "Dot", as a representation of the Internet, with "Kernel", the quintessence of any IT application, reflecting the aim of being a central part of Internet development.

**Q: What is Dotkernel 1?**
A: A PHP Application Framework built on top of Zend Framework 1, first publicly released in July 2010, with an architecture based on MVC. Its latest version is 1.8 Long Term Support, which per the article will not be followed by a new version, only bugfixes.

**Q: What is Dotkernel 3?**
A: A collection of PSR-7 Middleware applications built on top of the Zend Expressive microframework, composed of a set of custom and extended Zend Framework 3 components, with an architecture based on Middleware. It implements PSR-1, PSR-2, PSR-4, PSR-7, and PSR-11.

**Q: How many applications make up Dotkernel 3?**
A: At the time of the article, there were two available applications, Frontend and Admin, with a third one, API, under development.

**Q: When someone writes just "Dotkernel", which version is meant?**
A: In posts older than 2017, "Dotkernel" referred to Dotkernel 1, since it was the only version. Since the release of Dotkernel 3, "Dotkernel" refers to Dotkernel 3, and all future references to Dotkernel 1 are made explicitly.


<!-- ============================================================ -->
<!-- dotkernel/doctrine-cache-using-symfony-cache.md -->
<!-- ============================================================ -->

---
title: "Doctrine cache using symfony/cache"
description: "How to enable and configure the dotkernel/dot-cache component, a wrapper around symfony/cache, to cache Doctrine's result, metadata, query, and hydration data in Dotkernel Admin."
author: "MarioRadu"
date_published: "2024-02-27"
canonical_url: "https://www.dotkernel.com/dotkernel/doctrine-cache-using-symfony-cache/"
category: "Dotkernel"
language: "en"
---

# Doctrine cache using symfony/cache

## TL;DR

Caching stores data the first time it's requested so that later requests can be served from the cache instead of the original, slower source, which improves response times.
This article, a follow-up to an earlier caching article, shows how to enable the dot-cache component, a wrapper around symfony/cache, in Dotkernel Admin.
It covers the array and filesystem storage adapters, configuring Doctrine's four cache types (result, metadata, query, hydration), and marking entities and queries as cacheable.

## Installation

Run the following command in your project directory:

```bash
composer require dotkernel/dot-cache
```

After installing, add the `DotCacheConfigProvider::class` class to your configuration aggregate (config/config.php).
Before continuing with the configuration process, it helps to know a few things about how and where the data is stored.
The [dotkernel/dot-cache](https://packagist.org/packages/dotkernel/dot-cache) component is a wrapper that sits on top of [symfony/cache](https://packagist.org/packages/symfony/cache).
It currently supports two adapters and can store data in two distinct locations:

- array - stores data in-memory
- filesystem - stores data on local disk files

1. Storing data in-memory is the fastest and sometimes the cheapest caching mechanism, but it also comes with down-sides.
Storing everything in RAM memory is not the best idea when your application is running on a low memory system.
In this case you should consider using the filesystem mechanism.

2. The second caching mechanism involves storing data into files on the local disk, known as the filesystem option.
While this option may be slightly slower than the first one, it provides a more persistent storage solution.

Feel free to explore and use other adapters from [symfony/cache](https://packagist.org/packages/symfony/cache) by checking the [official documentation](https://symfony.com/doc/current/components/cache.html#advanced-usage).

## Configuration

In `config/autoload/doctrine.global.php`, in the `doctrine.configuration.orm_default` key add the following entry:

```php
'result_cache'       => 'filesystem',
'metadata_cache'     => 'filesystem',
'query_cache'        => 'filesystem',
'hydration_cache'    => 'array',
'second_level_cache' => ,
],
```

Next, under the `doctrine` key add the following items:

```php
'cache' => ,
    'filesystem' => ,
],
```

The result is that the metadata and query cache will be stored in the `data/cache/doctrine` folder and the hydration cache will be stored in-memory.
Each system is unique, requiring customized configurations.
Make sure to identify the specific configuration requirements for your application.
Doctrine cache is divided into 4 different types:

- `result_cache`
- `metadata_cache`
- `query_cache`
- `hydration_cache`

### Result Cache

The result cache can be used to store the results of your queries, enabling Doctrine to avoid querying the database or hydrating the data again after the initial retrieval.

### Metadata Cache

Parsing your class metadata on every request is inefficient.
Instead, it's advisable to cache this information using one of the available cache adapters.

### Query Cache

In a production environment, it's strongly recommended to cache the resulting DQL query into its SQL equivalent.
Since the query doesn't change unless the DQL query itself changes, it's unnecessary to parse it multiple times.

### Hydration Cache

Doctrine hydration cache is a feature that stores the results of data hydration, which is the process of converting raw database data into usable objects or arrays.
By caching these results, it avoids repeating the hydration process for repeated queries, improving performance.

## How to Use

To enable caching for entities, you need to add the `#` attribute like in the following example:

```php
#
#
#
class Admin extends AbstractEntity implements AdminInterface
{
}
```

For further details about the cache mode please refer to the [official documentation](https://www.doctrine-project.org/projects/doctrine-orm/en/latest/reference/second-level-cache.html).
When querying data, you can have Doctrine cache your results.
You do this by calling the `setCacheable` method on the query builder.

```php
$this->getQueryBuilder()
     ->select('admin')
     ->from(Admin::class, 'admin')
     ->setCacheable(true)
     ->getQuery()
     ->getResult();
```

Caching is not limited to entities alone.
Objects can be cached too.
Check the [basic cache usage](https://symfony.com/doc/current/components/cache.html#basic-usage-psr-6) for this purpose.
In conclusion, cache plays a vital role in optimizing system performance and improving user experience by storing frequently accessed data.
As technology continues to evolve, caching mechanisms will remain an integral part of modern computing architectures, driving faster access to data and smoother user interactions across various digital platforms.

## FAQ

**Q: What component does this article use for caching Doctrine data?**
A: The dotkernel/dot-cache component, a wrapper that sits on top of symfony/cache. It's installed with composer require dotkernel/dot-cache and registered by adding DotCacheConfigProvider::class to the configuration aggregate.

**Q: What storage adapters does dot-cache currently support?**
A: Two: array, which stores data in-memory and is the fastest option but uses more RAM, and filesystem, which stores data in local disk files and is slightly slower but more persistent.

**Q: What are the four types of Doctrine cache covered?**
A: result_cache, metadata_cache, query_cache, and hydration_cache, each configured under the doctrine.configuration.orm_default key.

**Q: What does the result cache do?**
A: It stores the results of queries, letting Doctrine avoid querying the database or hydrating the data again after the initial retrieval.

**Q: Why cache class metadata?**
A: Because parsing class metadata on every request is inefficient, so it's advisable to cache it using one of the available cache adapters.

**Q: How do you mark an entity or a query as cacheable?**
A: To enable caching for entities you add a caching attribute to the entity class; to cache an individual query, call setCacheable(true) on the query builder before getResult().


<!-- ============================================================ -->
<!-- dotkernel/doctrine-enum-implementation-in-dotkernel.md -->
<!-- ============================================================ -->

---
title: "Doctrine enum implementation in Dotkernel"
description: "How Dotkernel adopted Doctrine ORM 3.2's EnumType support to replace loosely-enforced string-based status columns with PHP enums backed by a custom DBAL type."
author: "Florin Bidirean"
date_published: "2024-11-05"
canonical_url: "https://www.dotkernel.com/dotkernel/doctrine-enum-implementation-in-dotkernel/"
category: "Dotkernel"
language: "en"
---

# Doctrine enum implementation in Dotkernel

## TL;DR

Doctrine ORM 3.2.0 added EnumType columns, building on the enum type introduced in PHP 8.1, and Dotkernel now implements this on both the PHP and database sides.
The article contrasts Dotkernel's old string-based flag columns (like `User->Status`) with a new setup that uses custom PHP enums paired with a DBAL type extending `AbstractEnumType`.
The new approach creates an explicit, enforced link between the PHP code and the database column values, at the cost of needing to update both sides whenever the value set changes.

## Doctrine's Approach

The update introduces the detection of `enumType` and `options.values` from a property with `type: Types::ENUM`.
[This PR](https://github.com/doctrine/orm/pull/11666) discusses the update and links to several older relevant issues.

### Old Setup

```php
#
class Card
{
    #
    #
    #
    public int $id;

    #],
    )]
    public Suit $suit;
}
```

### New Setup

```php
#
class Card
{
    #
    #
    #
    public int $id;

    #
    public Suit $suit;
}
```

Note that the type `Types::ENUM` part is still required if we want to have an actual `enum` column in MySQL/MariaDB.
We still default to `Types::STRING` or `Types::INTEGER` for column types with a PHP enum, as this is the more portable solution and the safer default.

## Dotkernel's Approach

### Old Setup

Dotkernel uses flags for columns like `User->Status`, but we resorted to the simpler `string` type.
The obvious disadvantage is that you can't definitively enforce a set of values for a given column.
Sure, the PHP can be set up to only use the agreed-upon set of values, but the database is independent from it.
If you edit a value manually in the database, any string is accepted.

The issue is the same on the side of the PHP code.
If the developer adds a value with a typo, it's supported, but will not work as intended.

The only advantage this setup has is the ability to easily add more values in the value set.
This may be seen as a feature, but it invites bugs in the execution.

Our old implementation defined the values like below, for the `User` entity.

```php
public const STATUS_PENDING = 'pending';
public const STATUS_ACTIVE  = 'active';
public const STATUSES       = ;
```

The column for the ORM was defined like this, as a simple string, with `pending` as its default value:

```php
#
protected string $status = self::STATUS_PENDING;
```

Obviously, the `getStatus` and `setStatus` also work with strings:

```php
public function getStatus(): string
{
    return $this->status;
}

public function setStatus(string $status): self
{
    $this->status = $status;
}
```

### New Setup

Thanks to the update of `doctrine/orm` to version 3.2.0, Dotkernel can now have a proper link between the PHP code and database values.
Now the link between the PHP code and the database is explicit and enforced.

Any update to the value set must be on both the PHP code and the database.

Let's review how the update affects the `User` entity.

In the next example, we show how to implement a value set using a custom enum.

First, we define our custom value set in `src/User/src/Enum/UserStatusEnum.php`.

```php
namespace Api\User\Enum;

enum UserStatusEnum: string
{
    case Active  = 'active';
    case Pending = 'pending';
}
```

We need to create `src/User/src/DBAL/Types/UserStatusEnumType.php` to process the new values for the `status` column.

`AbstractEnumType` must be extended by any future custom enum type.

```php
namespace Api\User\DBAL\Types;

use Api\App\DBAL\Types\AbstractEnumType;
use Api\User\Enum\UserStatusEnum;

class UserStatusEnumType extends AbstractEnumType
{
    public const NAME = 'user_status_enum';

    protected function getEnumClass(): string
    {
        return UserStatusEnum::class;
    }

    public function getName(): string
    {
        return self::NAME;
    }
}
```

If you create your own enum types, make sure to update the `NAME` constant and the value returned by `getEnumClass`.

Let's register the custom type in `config/autoload/doctrine.global.php` under the `types` key:

```php
'types'         =>
    UserStatusEnumType::NAME => UserStatusEnumType::class,

],
```

The filtering is updated in `src/User/src/InputFilter/Input/StatusInput.php`:

```php
$this->getFilterChain()
    ->attachByName(StringTrim::class)
    ->attachByName(StripTags::class)
    ->attach(fn($value) => $value === null ? UserStatusEnum::Active : UserStatusEnum::from($value));

$this->getValidatorChain()
    ->attachByName(InArray::class, , true);
```

The above ensures that the new `UserStatusEnum` class is used for the `status` column updates.

The `User` entity uses the new `UserStatusEnum` class.

```php
#)]
protected UserStatusEnum $status = UserStatusEnum::Pending;
```

The `status` getter and setter are also updated:

```php
public function getStatus(): UserStatusEnum
{
    return $this->status;
}

public function setStatus(UserStatusEnum $status): self
{
    $this->status = $status;
}
```

Dotkernel checks the user status during login in `src/User/src/Repository/UserRepository.php`.
If the user is not activated, the login is rejected.

```php
if ($clientEntity->getName() === 'frontend' && $result !== UserStatusEnum::Active) {
    throw new OAuthServerException(Message::USER_NOT_ACTIVATED, 6, 'inactive_user', 401);
}
```

A new user is created using the `enum` type and `pending` as the default.

```php
$user = (new User())
    ->setDetail($detail)
    ->setIdentity($data)
    ->usePassword($data)
    ->setStatus($data ?? UserStatusEnum::Pending);
```

Note the `status` column in the migration query which now looks like this:

```php
$this->addSql('
CREATE TABLE user (
    uuid BINARY(16) NOT NULL,
    identity VARCHAR(191) NOT NULL,
    password VARCHAR(191) NOT NULL,
    status ENUM(\'active\', \'pending\') DEFAULT \'pending\' NOT NULL,
    isDeleted TINYINT(1) NOT NULL,
    hash VARCHAR(64) NOT NULL,
    created DATETIME NOT NULL,
    updated DATETIME DEFAULT NULL,
    UNIQUE INDEX UNIQ_8D93D6496A95E9C4 (identity), UNIQUE INDEX UNIQ_8D93D649D1B862B8 (hash),
    PRIMARY KEY(uuid)) DEFAULT CHARACTER SET utf8mb4');
```

The difference for the migration query is for the `status` column, highlighted below:

```
old setup: status VARCHAR(20) NOT NULL
new setup: status ENUM(\'active\', \'pending\') DEFAULT \'pending\' NOT NULL
```

## Conclusions

The old setup used in the Dotkernel applications worked fine, but the limitations were clear as day.
There was:

- No enforcement of the value set.
- No link between the PHP code and the database.

The new setup solves both issues, ensuring more consistent flag management for your classes.

## FAQ

**Q: What update triggered this change to Dotkernel's enum handling?**
A: The update of doctrine/orm to version 3.2.0 introduced EnumType columns, building on the enum type introduced in PHP 8.1. Dotkernel implemented this new data type on both the PHP side and the database side.

**Q: What was the limitation of Dotkernel's old approach to columns like User->Status?**
A: The old setup used a simple string type, so the value set couldn't be definitively enforced. A typo in a PHP value would still be accepted, and the database was independent of any values the PHP code allowed, so manually editing a value in the database would accept any string.

**Q: What was the one advantage of the old string-based setup?**
A: It made it easy to add more values to the value set, though the article notes this ease also invites bugs in the execution.

**Q: What do you need to create to add a new custom enum type?**
A: A PHP enum class (like UserStatusEnum) plus a DBAL type class extending AbstractEnumType, which must define a NAME constant and a getEnumClass() method; the new type is then registered under the types key in config/autoload/doctrine.global.php.

**Q: Does Types::ENUM still fall back to a string or integer database column?**
A: The article notes that Doctrine still defaults to Types::STRING or Types::INTEGER for columns backed by a PHP enum, as this is considered the more portable and safer default; Types::ENUM is required if you want an actual enum column in MySQL/MariaDB.

**Q: What must happen when the value set of an enum changes under the new setup?**
A: Any update to the value set must be made on both the PHP code and the database, since the new setup creates an explicit, enforced link between them.

## Resources

- [Dotkernel API Pull Request](https://github.com/dotkernel/api/pull/339/files)
- [Doctrine Pull Request](https://github.com/doctrine/orm/pull/11666)
- [PHP Enumerations](https://www.php.net/manual/en/language.enumerations.overview.php)


<!-- ============================================================ -->
<!-- dotkernel/dotboost-technologies-products-and-services-north-american-relaunch.md -->
<!-- ============================================================ -->

---
title: "DotBoost Technologies : Products and Services North American Relaunch"
description: "Dotboost Technologies announces its North American relaunch, centered on the source release of its in-house Dotkernel framework alongside expanded IT integration and consulting services."
author: "admin"
date_published: "2010-01-28"
canonical_url: "https://www.dotkernel.com/dotkernel/dotboost-technologies-products-and-services-north-american-relaunch/"
category: "Dotkernel"
language: "en"
---

# DotBoost Technologies : Products and Services North American Relaunch

## TL;DR

Dotboost announces its North American relaunch, aimed at better serving clients in Canada and the US.
The relaunch centers on the source release of its in-house Dotkernel framework, along with expanded business IT integration and clearer consulting services.
Founded in 2005, Dotboost describes itself as treating clients as strategic partners rather than as a typical IT vendor.

## The North American Relaunch

A new style and advanced approach to accompany the Dotkernel source release.

Dotboost is pleased to announce our North American Relaunch.
This new phase comes as a result of dedicated research and analysis on how to best serve clients in Canada and the US.

At the heart of our relaunch is the source release for our exclusive inhouse developed Dotkernel framework.
We have also added business IT integration and increased the clarity to our existing consulting services.

## The Dotboost Approach

We're not your average IT organization; we view our customers as strategic partners.
This paradigm allows us to take a comprehensive approach towards creating solutions and gain the competitive advantage.

Founded in 2005, the Dotboost process can incorporate anywhere into your project's life-cycle including concept development, architecture and design, development and integration, and implementation and support.
We use time and distance to our advantage, pushing competitive boundaries and staking our place as a globally efficient organization.

## FAQ

**Q: What is at the heart of Dotboost's North American relaunch?**
A: The source release of Dotboost's exclusive, in-house developed Dotkernel framework, along with added business IT integration and increased clarity around existing consulting services.

**Q: When was Dotboost founded, and at what stages can it join a project?**
A: Dotboost was founded in 2005. Per the article, its process can incorporate anywhere into a project's life-cycle, including concept development, architecture and design, development and integration, and implementation and support.


<!-- ============================================================ -->
<!-- dotkernel/dotkernel-1-2-0-release.md -->
<!-- ============================================================ -->

---
title: "Dotkernel 1.2.0 release"
description: "Release notes for Dotkernel 1.2.0, covering database naming convention changes, the new 'dots' submodule concept, new and updated library classes, and the use of prepared statements for all SQL queries."
author: "Teo"
date_published: "2010-07-05"
canonical_url: "https://www.dotkernel.com/dotkernel/dotkernel-1-2-0-release/"
category: "Dotkernel"
language: "en"
---

# Dotkernel 1.2.0 release

## TL;DR

Dotkernel 1.2.0 has been released, bringing changes since the previous 1.1.2 release.
The database tables were renamed and restructured to follow database naming conventions, and configuration for each "dots" (submodule) now lives in XML files instead of being hard-coded in PHP.
The release also adds new library classes (Dot_Geoip, Dot_Seo), updates existing ones (Dot_Curl, Dot_Session), and confirms that all SQL queries are written as prepared statements.

## Database Naming Conventions

On database, we changed the names and structure of tables to respect database naming convention.
See [http://www.dotkernel.com/dotkernel/dotkernel-database-naming-conventions-for-mysql/](http://www.dotkernel.com/dotkernel/dotkernel-database-naming-conventions-for-mysql/) for details.

## The "Dots" Concept

A new word came into our Dotkernel discussions: dots.
We use this term when talking about a submodule and all its component files.
For example, "user" is a submodule of the frontend module.
Note that one dots can be part of multiple modules (for example, "user" dots belong to both the frontend and admin module).
For each dots, the configuration values have been added to XML files which are stored in the configs/dots folder.
In the previous versions, these values were hard-coded in the PHP files.

Another change made in the configs folder is resource.xml, which contains the configuration values for the controllers of each module.

To be easier to start an application from Dotkernel, in the admin module, there are now the following dots: admin, user and system.

## Library Class Updates

New library classes have been implemented: Dot_Geoip and Dot_Seo, and some of the existing ones have been updated: Dot_Curl and Dot_Session (each module has its own session).

## SQL Prepared Statements

In Dotkernel, all SQL queries are written as prepared statements.
We strongly encourage this practice: [http://www.dotkernel.com/php-development/protection-against-sql-injection-using-pdo-and-zend-framework/](http://www.dotkernel.com/php-development/protection-against-sql-injection-using-pdo-and-zend-framework/)

For more details, see [ChangeLog 1.2.0](http://www.dotkernel.com/changelog/1-2-0/).

## FAQ

**Q: What is a "dots" in Dotkernel, a term introduced in this release?**
A: A term for a submodule and all its component files. For example, "user" is a dots of the frontend module, and one dots can belong to multiple modules, such as "user" belonging to both frontend and admin.

**Q: Where are dots configuration values stored, compared to earlier versions?**
A: They're stored in XML files inside the configs/dots folder. In previous versions, these values were hard-coded in the PHP files.

**Q: What dots does the admin module include by default?**
A: admin, user, and system, to make it easier to start an application from Dotkernel.

**Q: What library classes were added or updated in 1.2.0?**
A: Dot_Geoip and Dot_Seo were newly implemented, while Dot_Curl and Dot_Session were updated, with each module now having its own session.

**Q: How are SQL queries written in Dotkernel?**
A: All SQL queries are written as prepared statements, a practice the article strongly encourages.


<!-- ============================================================ -->
<!-- dotkernel/dotkernel-1-2-2-release.md -->
<!-- ============================================================ -->

---
title: "Dotkernel 1.2.2 release"
description: "Dotkernel 1.2.2 is a bug-fix release closing five issues, including captcha error handling, a pagination bug, and a copyright line update that touched every PHP file."
author: "Teo"
date_published: "2010-07-30"
canonical_url: "https://www.dotkernel.com/dotkernel/dotkernel-1-2-2-release/"
category: "Dotkernel"
language: "en"
---

# Dotkernel 1.2.2 release

## TL;DR

Dotkernel 1.2.2 is a bug-fix release that closes five tracked issues.
Because one of the fixes updated the copyright line, every PHP file in the codebase changed, so the full release or the incremental upgrade package is needed.

## Bug fixes in 1.2.2

- **31** - captcha errors try/catch
- **32** - pagination issue
- **33** - admin wrong link
- **34** - Acunetix scan results from July 24th (notices and one fatal error)
- **35** - update copyright line in files

**Note:** because of bug 35, all PHP files changed in this release.

## Upgrading

To get only the changed files from 1.2.1 to 1.2.2, download the upgrade package (linked in the post) instead of the full distribution.
Full details are available in the ChangeLog 1.2.2, and further changes can be tracked on the Dotkernel Tracker or Dotkernel WebSVN.

Note also that Dotkernel 1.2.1 had been released a few days earlier, on July 22, 2010, with its own ChangeLog and upgrade package.

## FAQ

**Q: What does the Dotkernel 1.2.2 release include?**
A: It's a bug-fix release that closes five issues: captcha error handling (try/catch), a pagination issue, a wrong admin link, notices and a fatal error found by an Acunetix scan, and an update to the copyright line in files.

**Q: Why did all PHP files change in the 1.2.2 release?**
A: Because of the fix for bug 35, which updated the copyright line, every PHP file in the codebase was touched, which is why the note in the post warns that all PHP files have changed.

**Q: How can I upgrade from a previous version to 1.2.2?**
A: You can download just the changed files from 1.2.1 to 1.2.2 using the upgrade package linked in the post, or check the ChangeLog 1.2.2 for full details of what changed.

## Resources

- ChangeLog 1.2.2 (linked in the original post as `../changelog/1-2-2/`)
- Upgrade package for 1.2.2 (linked in the original post as `../download/?did=17`)
- Dotkernel Tracker: http://www.dotkernel.net/
- Dotkernel WebSVN: http://websvn.dotkernel.net/listing.php?repname=Dotkernel+ver.+1
- ChangeLog 1.2.1 (linked in the original post as `../changelog/1-2-1/`)
- Upgrade package for 1.2.1 (linked in the original post as `../download/?did=14`)


<!-- ============================================================ -->
<!-- dotkernel/dotkernel-1-3-0-release.md -->
<!-- ============================================================ -->

---
title: "Dotkernel 1.3.0 release"
description: "Dotkernel 1.3.0 adds an admin skin switcher, a way to protect member-only links, and reorganizes resource.xml into route.xml and dots.xml, at the cost of backward compatibility."
author: "Teo"
date_published: "2010-10-15"
canonical_url: "https://www.dotkernel.com/dotkernel/dotkernel-1-3-0-release/"
category: "Dotkernel"
language: "en"
---

# Dotkernel 1.3.0 release

## TL;DR

Dotkernel 1.3.0 brings a switchable admin skin, a way to protect member-only pages, a rename of Dot_Sessions, and a reorganization of resource.xml into route.xml and dots.xml.
Because of that XML reorganization, 1.3.0 is not backward compatible with earlier versions.

## Highlights

### Admin skin switcher

The admin skin can now be customized. Several ready-made skins are available: blue, brown, gray, and green.
Set the skin by changing the `settings.admin.skin` value (e.g. `settings.admin.skin = green`).

### Protecting member-only links

To protect a link so only logged-in members can access it, add this line in the controller file above the code that should require login:

```php
Dot_Auth::checkIdentity();
```

### XML reorganization

Some XML files from the configs folder were changed. `resource.xml` was deleted and its content was split between two new files, `route.xml` and `dots.xml`.

### Other closed issues

The release also closed a number of other tracked issues, covering: the Dot_Sessions rename, menu issues in Admin and frontend, URL casing consistency, an XSS issue in the forgot-password flow, several security scan results, admin listing/UI fixes, a GeoIP extension listing feature, and formatting cleanup (blank lines, brace placement) across the frontend files.

## Compatibility note

Because of the XML file reorganization, this release is **not compatible** with previous versions.
Further details on what changed are available on the Dotkernel Tracker or Dotkernel WebSVN.

## FAQ

**Q: What is new in the admin interface in Dotkernel 1.3.0?**
A: 1.3.0 adds a skin switcher for the admin, with several ready-made skins (blue, brown, gray, green) that can be set via the settings.admin.skin configuration value.

**Q: How do I protect a page so only logged-in members can access it?**
A: Add the line Dot_Auth::checkIdentity(); in the controller file above the code you want to protect - everything below that line requires the visitor to be logged in.

**Q: What happened to resource.xml in this release?**
A: resource.xml was deleted and its content split between two new files, route.xml and dots.xml.

**Q: Is Dotkernel 1.3.0 backward compatible with earlier versions?**
A: No. Because of the XML file reorganization (bug 69), 1.3.0 is not compatible with previous versions.

## Resources

- Dotkernel 1.3.0 download (linked in the original post as `../download/?did=23`)
- ChangeLog 1.3.0 (linked in the original post as `../changelog/1-3-0/`)
- route.xml documentation (linked in the original post as `../docs/router-xml/`)
- dots.xml documentation (linked in the original post as `../docs/dots-xml/`)
- Dotkernel Tracker: http://www.dotkernel.net/
- Dotkernel WebSVN: http://websvn.dotkernel.net/listing.php?repname=Dotkernel


<!-- ============================================================ -->
<!-- dotkernel/dotkernel-1-3-2-release.md -->
<!-- ============================================================ -->

---
title: "Dotkernel 1.3.2 release"
description: "Dotkernel 1.3.2 is a maintenance release with many bug fixes, a couple of minor features, and some refactoring, released just before the winter holidays."
author: "Teo"
date_published: "2010-12-23"
canonical_url: "https://www.dotkernel.com/dotkernel/dotkernel-1-3-2-release/"
category: "Dotkernel"
language: "en"
---

# Dotkernel 1.3.2 release

## TL;DR

Released just before the winter holidays, Dotkernel 1.3.2 is mainly a maintenance release: it contains many bug fixes, some refactoring, and a few minor features.

## Bug fixes

- CSS issue on the admin phpinfo page
- Warning in the admin dashboard for a file
- WURFL cache issue in admin
- WURFL version issue
- Dot_Paginator bug
- Zend Paginator double-query issue
- Database naming convention issue
- Database normalisation/refactor

## Minor features

- Refactor of validIP in the Dot_Kernel class
- WURFL date and API version shown in admin

## Refactoring

- Zend_Paginator refactoring
- Added a dojo dijit theme to Dotkernel

## FAQ

**Q: What kind of release is Dotkernel 1.3.2?**
A: It's mainly a maintenance release, containing many bug fixes, some refactoring, and a few minor features.

**Q: What bugs were fixed in 1.3.2?**
A: Fixes include a CSS issue on the admin phpinfo page, a warning in the admin dashboard, a WURFL cache issue and WURFL version issue in admin, a Dot_Paginator bug, a Zend Paginator double-query issue, and a database naming convention issue.

**Q: What minor features and refactoring were included?**
A: Minor features include a refactor of validIP in Dot_Kernel and showing the WURFL date and API version in admin.
Refactoring covered Zend_Paginator and added a dojo dijit theme to Dotkernel.

## Resources

- Dotkernel 1.3.2 download: http://www.dotkernel.com/download/?did=27


<!-- ============================================================ -->
<!-- dotkernel/dotkernel-1-5-0-released.md -->
<!-- ============================================================ -->

---
title: "Dotkernel 1.5.0 Released"
description: "Dotkernel 1.5.0 skips version 1.4 entirely and brings a switch from Dojo to jQuery, redesigned admin and frontend, model inheritance via Dot_Model, dashed controller support, and a reorganized Zend Registry."
author: "Adrian"
date_published: "2011-06-15"
canonical_url: "https://www.dotkernel.com/dotkernel/dotkernel-1-5-0-released/"
category: "Dotkernel"
language: "en"
---

# Dotkernel 1.5.0 Released

## TL;DR

After a longer wait than usual and around 250 commits, Dotkernel 1.5.0 was released, skipping 1.4 entirely due to the scale of changes.
Highlights include switching from Dojo to jQuery, a redesigned admin and frontend, model inheritance through a new Dot_Model class, support for dashed controller names, and a reorganized Zend Registry.

## Why skip straight to 1.5.0?

Due to the large amount of changes and the long time spent in development, the team chose to skip 1.4 and go straight to 1.5.0.

## Highlights of 1.5.0

### Switched from Dojo to jQuery

Starting with 1.5.0, Dotkernel switched from using Dojo to jQuery.
Dojo can still be used in your own projects, but only jQuery is used and maintained in the Dotkernel distribution itself.

### New designs

The admin site was redesigned, with new themes and a dropdown menu, along with a new and simpler design for the front-end.

### Model inheritance

Previously there was a lot of code duplication in models - for example, a `getUserById` function might exist separately in both the admin and frontend User models.
To solve this, a `Dot_Model` class was introduced along with a way to define global models inherited by both admin and frontend.
A `User` class in the admin only holds admin-specific methods, a `User` class in the frontend only holds frontend-specific methods, and both inherit a shared `Dot_Model_User` class containing the common code.

### Dashed controllers

The way controller names are parsed was changed so that controllers with multiple words, split with dashes, work without breaking the coding standard.
For example, `www.example.com/search-article` calls `SearchArticleController.php`.

### Zend Registry reorganization

The structure of the registry was changed; more details are covered in a separate blog post on Zend Registry usage in Dotkernel.

## Scale of the release

There were about 250 commits in the SVN repository since the previous release, so the blog post could not cover every change.

## FAQ

**Q: Why did Dotkernel jump from 1.3 straight to 1.5.0?**
A: Because of the large amount of changes and the long time spent in development, the team chose to skip version 1.4 and go straight to 1.5.0.

**Q: Did Dotkernel switch from Dojo to jQuery in 1.5.0?**
A: Yes.
Starting with 1.5.0, Dotkernel switched from Dojo to jQuery for its own distribution, though Dojo can still be used in your own projects.

**Q: What is Dot_Model and why was it introduced?**
A: Dot_Model is a base class introduced to reduce code duplication between admin and frontend models.
Both admin- and frontend-specific model classes (such as User) inherit from a shared Dot_Model_User class that holds the common code.

**Q: How does the "dashed controllers" feature work?**
A: The controller name parsing was changed so a URL like www.example.com/search-article correctly calls SearchArticleController.php, allowing multi-word controller names split with dashes without breaking the coding standard.

**Q: How much changed in the 1.5.0 release?**
A: About 250 commits went into the SVN repository since the previous release, so the blog post only covers the highlights - the full Dotkernel 1.5.0 download is available to try out.

## Resources

- Intro to jQuery: http://www.dotkernel.com/javascript/intro-to-jquery/
- Zend Registry usage in Dotkernel: http://www.dotkernel.com/dotkernel/zend-registry-usage-in-dotkernel/
- Dotkernel 1.5.0 download: http://www.dotkernel.com/download/?did=33


<!-- ============================================================ -->
<!-- dotkernel/dotkernel-1-8-0-lts-released.md -->
<!-- ============================================================ -->

---
title: "Dotkernel 1.8.0 LTS Released"
description: "Dotkernel 1.8.0 (LTS) introduces a plugin architecture, a redesigned mobile-friendly admin and frontend, APC/File caching for speed, a new Dot_Request class, and several security and alerting improvements."
author: "Gabi DJ"
date_published: "2015-06-08"
canonical_url: "https://www.dotkernel.com/dotkernel/dotkernel-1-8-0-lts-released/"
category: "Dotkernel"
language: "en"
---

# Dotkernel 1.8.0 LTS Released

## TL;DR

Dotkernel 1.8.0 (LTS) was released with a new Plugin Architecture, a redesigned and mobile-friendly frontend, APC/File caching for faster response times, a new Dot_Request class, and multiple security and alerting improvements.
Some features (WURFL integration, multiple SMTP transporters) were removed from core and made available as plugins instead.

## What is LTS?

Long-term support (LTS) is a type of special version or edition of software designed to be supported for a longer than normal period.
It's particularly applicable to open-source software projects.
The 1.8.0 LTS release itself contains many bug fixes, some refactoring, and a few minor features.

## Highlights of 1.8.0 (LTS)

### Plugin Architecture

Starting with 1.8.0, Dotkernel uses Plugins to make extending the framework easier.

### New design

The admin module was redesigned and the frontend module is now mobile-friendly, while the separate mobile module remains available.

### Loads faster

The framework now supports APC and File Caching, with all XML and config files cached in order to maximize response speed.

### Easier request handling

A new class, `Dot_Request`, gives control over the request data before use - for example, so that `$_SERVER`, `$_GET`, and `$_POST` are only accessed from within controllers.

### Features added

- API with Rate Limit - a simple API with single-key authentication and a basic rate limit implementation (configurable in `/configs/application.ini`, section `params.api`)
- Cache System - built on Zend_Cache backends, providing caching within Dotkernel and in library code

### Other changes

- Removed WURFL integration - mobile device detection is now handled separately; WURFL can be added as a plugin
- Removed support for multiple SMTP transporters - it can be added as a plugin
- Security scan in the Admin Dashboard, showing recommended (especially security-related) settings
- Admin failed-login notifications are now sent to all developers listed in `devEmails` (within the `settings` table), not just the first admin
- Alert System - alerts can be sent to all developers to notify them if something goes wrong

### Bug fixes

- `seo.xml` caused an error when two modules used the same variable name instead of overwriting it
- Emails were sent twice
- A wrong "unwritable" warning appeared on nginx

## Scale of the release

There were a lot of commits in the SVN repository since the previous release, so the blog post only covers the highlights.

## FAQ

**Q: What does LTS mean for Dotkernel 1.8.0?**
A: LTS stands for Long-term support, a type of special version designed to be supported for longer than normal, which is particularly common for open-source software projects.

**Q: What is the Plugin Architecture introduced in 1.8.0?**
A: Starting with 1.8.0, Dotkernel uses Plugins to make extending the framework easier.

**Q: How does 1.8.0 load faster than previous versions?**
A: It supports APC and File Caching within the framework, so XML files and config files are cached to maximize response speed.

**Q: What is Dot_Request?**
A: Dot_Request is a new class that gives you control over the request data before you use it, so that the variables $_SERVER, $_GET and $_POST are only accessed within controllers.

**Q: What was removed from Dotkernel in 1.8.0?**
A: WURFL integration was removed (mobile device detection is now handled separately, and WURFL can be added as a plugin), and support for multiple SMTP transporters was removed (it can also be added as a plugin).

**Q: What security-related additions does 1.8.0 include?**
A: A security scan in the Admin Dashboard shows recommended settings, admin failed-login notifications are sent to all developers listed in devEmails (not just the first admin), and a new Alert System can notify developers if something goes wrong.

## Resources

- What is LTS: http://www.dotkernel.com/long-term-support
- Caching in Dotkernel using Zend Framework: http://www.dotkernel.com/dotkernel/caching-in-dotkernel-using-zend-framework/
- Dotkernel reserved variable names for caching: http://www.dotkernel.com/dotkernel/dotkernel-reserved-variable-names-for-caching/
- How to use alerts in Dotkernel: http://www.dotkernel.com/dotkernel/how-to-use-alerts-in-dotkernel/
- Dotkernel 1.8.0 (LTS) download: http://www.dotkernel.com/download/?did=41


<!-- ============================================================ -->
<!-- dotkernel/dotkernel-1-8-1-upgrade-from-1-8-0-released.md -->
<!-- ============================================================ -->

---
title: "Dotkernel 1.8.1 + Upgrade from 1.8.0 Released"
description: "Dotkernel 1.8.1 adds Enhanced Cache Support with cache tagging, and ships with a dedicated upgrade package for users coming from 1.8.0."
author: "Gabi DJ"
date_published: "2015-06-11"
canonical_url: "https://www.dotkernel.com/dotkernel/dotkernel-1-8-1-upgrade-from-1-8-0-released/"
category: "Dotkernel"
language: "en"
---

# Dotkernel 1.8.1 + Upgrade from 1.8.0 Released

## TL;DR

Dotkernel 1.8.1 was released with Enhanced Cache Support, allowing cache tags to be used if the hosting environment supports them.
A dedicated upgrade package is available for users coming from 1.8.0.

## What's new

- Enhanced Cache Support - you can use tags in your cache system if the host supports it

## Download links

- Dotkernel 1.8.1 (full package)
- Upgrade from Dotkernel 1.8.0
- Dotkernel 1.8.0 (LTS)

## FAQ

**Q: What's new in Dotkernel 1.8.1?**
A: The main change is Enhanced Cache Support, which means you can use tags in your cache system if the host supports it.

**Q: How do I upgrade from 1.8.0 to 1.8.1?**
A: The post provides a dedicated "Upgrade from Dotkernel 1.8.0" download link, separate from the full Dotkernel 1.8.1 package and the original Dotkernel 1.8.0 (LTS) download.

## Resources

- Dotkernel 1.8.1: http://www.dotkernel.com/download/?did=42
- Upgrade from Dotkernel 1.8.0: http://www.dotkernel.com/download/?did=43
- Dotkernel 1.8.0 (LTS): http://www.dotkernel.com/download/?did=41


<!-- ============================================================ -->
<!-- dotkernel/dotkernel-coding-standard.md -->
<!-- ============================================================ -->

---
title: "Dotkernel Coding Standard"
description: "Dotkernel borrows the Zend Framework coding standard with a few exceptions, covering indentation, class/interface/file naming, and curly brace placement for control statements."
author: "admin"
date_published: "2008-03-28"
canonical_url: "https://www.dotkernel.com/dotkernel/dotkernel-coding-standard/"
category: "Dotkernel"
language: "en"
---

# Dotkernel Coding Standard

## TL;DR

Dotkernel is a "skeleton" of Zend Framework and borrows its coding standard from the ZF Coding Standard, with a small number of exceptions covering indentation, naming conventions, and brace placement.

## Indentation

Indentation is made with tabs, not spaces (per section B.2.2 of the Zend Framework Coding Standard).

## Naming conventions

Dotkernel uses camel naming conventions, with these Dotkernel-specific rules:

| Element | Convention | Example |
|---|---|---|
| Classes | Start with `Dot_` | `Dot_Templates` |
| Interfaces | End with the string "Interface" | `Dot_Db_Interface` |
| Filenames | Always use the `.php` extension, no fancy extensions | `.php`, not `.inc` |

## Control statements - brace placement

Every opening curly brace `{` starts on its own new line after the statement, and its matching closing brace `}` is also placed on its own new line, aligned in the same column as the opening brace, for better indentation of the code.

Example:

```php
if ($a != 2)
{
   $a = 2;
}
```

```php
if ($a != 2)
{
    $a = 2;
    if($a == 2)
    {
       $c = 3;
    }
}
```

## FAQ

**Q: What coding standard does Dotkernel follow?**
A: Dotkernel borrows its coding standard from the Zend Framework Coding Standard, with some exceptions described in this article.

**Q: Tabs or spaces for indentation?**
A: Dotkernel indents with tabs, not spaces.

**Q: How should classes, interfaces, and filenames be named?**
A: Classes start with the prefix Dot_ (e.g. Dot_Templates), interfaces end with the string "Interface" (e.g. Dot_Db_Interface), and all PHP files use the ".php" extension, with no fancy extensions like ".inc".

**Q: How should curly braces be placed for control statements?**
A: Every opening curly brace starts on its own new line after the statement, and its matching closing brace also goes on a new line, aligned in the same column as the opening brace, for better indentation of the code.

## Resources

- Zend Framework: http://framework.zend.com/
- ZF Coding Standard: http://framework.zend.com/manual/en/coding-standard.php-file-formatting.html
- ZF Coding Standard - Indentation: http://framework.zend.com/manual/en/coding-standard.php-file-formatting.html#coding-standard.php-file-formatting.indentation
- ZF Coding Standard - Naming Conventions: http://framework.zend.com/manual/en/coding-standard.naming-conventions.html
- ZF Coding Standard - Classes: http://framework.zend.com/manual/en/coding-standard.naming-conventions.html#coding-standard.naming-conventions.classes
- ZF Coding Standard - Interfaces: http://framework.zend.com/manual/en/coding-standard.naming-conventions.html#coding-standard.naming-conventions.interfaces
- ZF Coding Standard - Filenames: http://framework.zend.com/manual/en/coding-standard.naming-conventions.html#coding-standard.naming-conventions.filenames
- ZF Coding Standard - Control Statements: http://framework.zend.com/manual/en/coding-standard.coding-style.html#coding-standard.coding-style.control-statements


<!-- ============================================================ -->
<!-- dotkernel/dotkernel-database-naming-conventions-for-mysql.md -->
<!-- ============================================================ -->

---
title: "Dotkernel Database Naming Conventions for MySQL"
description: "Dotkernel borrows its database naming conventions from FaZend, covering singular table names, auto-incrementing id columns, foreign key and constraint naming patterns, and camelLetter casing."
author: "admin"
date_published: "2010-03-10"
canonical_url: "https://www.dotkernel.com/dotkernel/dotkernel-database-naming-conventions-for-mysql/"
category: "Dotkernel"
language: "en"
---

# Dotkernel Database Naming Conventions for MySQL

## TL;DR

Dotkernel's database naming conventions are borrowed from FaZend's "Rules of naming of database tables and columns."
Tables use singular, camelLetter names, every table has an auto-increment id, foreign keys are named after the referenced table and column, and SQL keywords are capitalized.

## Database naming conventions for tables and columns

- Singular table names only (e.g. `user`, `category`, `product`, `order`, `orderProduct`)
- Every table must have an auto-incrementing integer column `id`
- ZF-like names of columns and tables (e.g. `user::isAdmin`, `orderProduct::product`)
- Foreign keys must have the same name as the referenced table plus the name of the referenced column.
  Example: table referenced is `admin`, column name `Id`, so the foreign key column will be `adminId`.
- Pattern for CONSTRAINT name: `FK_referencedTableName_tableName`.
  Example: `CONSTRAINT FK_admin_adminLogin`.
- SQL keywords are capitalized (e.g. `SELECT`, `INT`)

## Example of proper SQL file formatting and naming

```sql
CREATE TABLE IF NOT EXISTS `user`
 (
   `id` INT(11) UNSIGNED NOT NULL AUTO_INCREMENT,
   `username` VARCHAR(255) NOT NULL,
   `password` VARCHAR(25) NOT NULL,
   `email` VARCHAR(100) NOT NULL,
   `firstName` VARCHAR(255) NOT NULL,
   `lastName` VARCHAR(255) NOT NULL,
   `dateCreated` TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
   `userType` INT(11) NOT NULL AUTO_INCREMENT
   `isActive` ENUM('0','1') NOT NULL DEFAULT '1',
   PRIMARY KEY  (`id`),
   UNIQUE KEY `username` (`username`),
   UNIQUE KEY `email` (`email`)
   CONSTRAINT `FK_user_userType` FOREIGN KEY(`userTypeId`) REFERENCES `userType`(`id`)
        ON UPDATE CASCADE
        ON DELETE CASCADE
 )
 ENGINE=InnoDB
 DEFAULT CHARSET=latin1
 AUTO_INCREMENT=1 ;
```

## Conclusion

The names of database tables and columns must follow camelLetter naming conventions.

## FAQ

**Q: Where do Dotkernel's database naming conventions come from?**
A: They are borrowed from FaZend's "Rules of naming of database tables and columns," an open-source PHP framework based on Zend Framework.

**Q: Should table names be singular or plural?**
A: Singular table names only, for example user, category, product, order, orderProduct.

**Q: How should foreign key columns be named?**
A: A foreign key column takes the name of the referenced table plus the name of the referenced column.
For example, referencing table admin's Id column produces a column named adminId.

**Q: What naming pattern is used for CONSTRAINT names?**
A: The pattern is FK_referencedTableName_tableName, for example CONSTRAINT `FK_admin_adminLogin`.

**Q: What casing convention applies to table/column names and to SQL keywords?**
A: Table and column names must follow camelLetter naming conventions, while SQL keywords such as SELECT and INT are capitalized.

## Resources

- FaZend: Rules of naming of database tables and columns: http://fazend.com/a/2009-11-DataNaming.html


<!-- ============================================================ -->
<!-- dotkernel/dotkernel-light-starting-with-mezzio-microframework-and-laminas-components.md -->
<!-- ============================================================ -->

---
title: "Dotkernel Light - Starting with Mezzio microframework and Laminas components"
description: "Dotkernel Light is a stripped-down version of Dotkernel Frontend built on Mezzio and Laminas components, keeping only routing, templating, error handling, and tests, for a gentler learning curve."
author: "Florin Bidirean"
date_published: "2024-10-03"
canonical_url: "https://www.dotkernel.com/dotkernel/dotkernel-light-starting-with-mezzio-microframework-and-laminas-components/"
category: "Dotkernel"
language: "en"
---

# Dotkernel Light - Starting with Mezzio microframework and Laminas components

## TL;DR

Dotkernel Light is a version of Dotkernel Frontend that includes only the bare-bones essentials.
It's built on the Mezzio microframework using Laminas components, and is designed as a presentation site, a fast-start introduction to Mezzio, or a clean starting point for a project where you want full control over functionality.

## Goal

Dotkernel Light is designed to be a fast-start example of using the Mezzio microframework, as well as an entry-level version of Dotkernel Frontend.
Its purpose is to present the newbie developer with as few moving parts as possible, while also giving the more advanced developer a starting point with full control of the platform's functionality.

Light retains the modern architecture of Mezzio microframework and several Laminas components used in Dotkernel Frontend.
The low number of out-of-the-box components encourages active exploration of the functionality required by your application - you add only the packages your application needs.

## Components and functionality

Dotkernel Light is a stripped-down version of Dotkernel Frontend.
Like Frontend, it is built on top of Mezzio microframework using Laminas components, but with limited features and a lower number of packages, which makes the learning curve of working with the repo considerably gentler.

### Functionality retained

- Routing
- Templating
- Error handling
- Tests and code quality checks

### Items removed compared to Frontend

- Doctrine and all database-related stuff
- Sessions/Cookies/Flash messages
- Authentication/Authorization
- Dependency Injection
- Mail-related stuff
- Navigation
- CORS
- Forms/Validators/InputFilters
- User module
- Contact module
- Plugin module
- CSS/JS code no longer in use due to the above module removals
- Instructions from README.md that are no longer needed

### Packages no longer required

- dotkernel/dot-authorization
- dotkernel/dot-data-fixtures
- dotkernel/dot-dependency-injection
- dotkernel/dot-flashmessenger
- dotkernel/dot-mail
- dotkernel/dot-navigation
- dotkernel/dot-rbac-guard
- dotkernel/dot-response-header
- dotkernel/dot-session
- laminas/laminas-form
- laminas/laminas-i18n
- mezzio/mezzio-authorization-rbac
- mezzio/mezzio-cors
- ramsey/uuid-doctrine
- roave/psr-container-doctrine
- mezzio/mezzio-tooling
- rector/rector

## FAQ

**Q: What is Dotkernel Light?**
A: Dotkernel Light is a version of Dotkernel Frontend that includes only the bare-bones essentials.
It's suitable as a presentation site, an introduction to the Mezzio microframework architecture, or a starting point for a more complex project where you want full control over functionality.

**Q: What is the goal of Dotkernel Light?**
A: It's designed to be a fast-start example of using the Mezzio microframework as well as an entry-level version of Dotkernel Frontend, presenting the beginner developer with as few moving parts as possible while still letting the more advanced developer have full control of the platform's functionality.

**Q: What functionality does Dotkernel Light retain?**
A: It keeps routing, templating, error handling, and tests and code quality checks.

**Q: What was removed compared to Dotkernel Frontend?**
A: Items removed include Doctrine and all database related stuff, sessions/cookies/flash messages, authentication/authorization, dependency injection, mail related stuff, navigation, CORS, forms/validators/input filters, the User module, the Contact module, the Plugin module, unused CSS/JS code, and outdated README instructions.

**Q: Which packages are no longer required in Dotkernel Light?**
A: Packages such as dotkernel/dot-authorization, dotkernel/dot-mail, dotkernel/dot-session, dotkernel/dot-navigation, dotkernel/dot-flashmessenger, laminas/laminas-form, mezzio/mezzio-cors, and several others used by Frontend are not required.

## Resources

- Dotkernel Light GitHub repository: https://github.com/dotkernel/light
- Working demo of Dotkernel Light: https://light.dotkernel.net/
- Dotkernel Light documentation: https://docs.dotkernel.org/light-documentation/
- Laminas Project: https://getlaminas.org/
- Documentation of Mezzio: https://docs.mezzio.dev/


<!-- ============================================================ -->
<!-- dotkernel/dotkernel-light-the-best-choice-for-your-presentation-site.md -->
<!-- ============================================================ -->

---
title: "Dotkernel Light: the best choice for your presentation site"
description: "A walkthrough of using Dotkernel Light to build a simple presentation site: adding new pages, managing assets, and configuring Twitter/OpenGraph cards, the top menu, and the footer."
author: "Florin Bidirean"
date_published: "2024-10-14"
canonical_url: "https://www.dotkernel.com/dotkernel/dotkernel-light-the-best-choice-for-your-presentation-site/"
category: "Dotkernel"
language: "en"
---

# Dotkernel Light: the best choice for your presentation site

## TL;DR

Dotkernel Light is a lightweight starting point for a project when you want full control over its functionality, and it grows into something more complex as you add packages.
It comes with routing, templating, error handling, and tests/code quality checks out of the box, but strips out everything a presentation site doesn't need - database, sessions/cookies/flash messages, auth, dependency injection, mail, navigation, CORS, forms, the user/contact/plugin modules.

## What's included vs. removed

| Included out of the box | Removed (not needed for a presentation site) |
|---|---|
| Routing | Everything related to the database |
| Templating | Sessions/Cookies/Flash messages |
| Error handling | Authentication/Authorization |
| Tests and code quality checks | Dependency Injection |
| | Mail related stuff |
| | Navigation |
| | CORS |
| | Forms/Validators/InputFilters |
| | User module |
| | Contact module |
| | Plugin module |

## Adding new pages

1. Add an `Action` function for the page in `src/Page/src/Controller/PageController.php`, for example:

```php
public function examplePageAction(): ResponseInterface
{
    return new HtmlResponse(
        $this->template->render('page::example-template')
    );
}
```

   The URL for this example page would be `/page/example-page`.

2. Create the matching template in `src/Page/templates/page/` - for the example above, `src/Page/templates/page/example-template.html.twig`.
Put the page copy inside the `content` block:

```twig
{% extends '@layout/default.html.twig' %}

{% block title %}Page Title{% endblock %}

{% block page_title %}{% endblock %}

{% block content %}
    <div class="page-intro">
        <div class="container">
            <h2>Add title here!</h2>
        </div>
    </div>

    <div>
    Add cool content here!
    </div>
{% endblock %}
```

   Make sure to check the header for any fonts your content requires.

3. Place assets under `src/App/assets/`, in the default folders:
   - `src/App/assets/fonts`
   - `src/App/assets/images`
   - `src/App/assets/js`
   - `src/App/assets/scss`

   Make sure `npm` is installed and running during updates with `npm run watch`, or run `npm run prod` after edits are completed.

## Optional items

### Twitter and OpenGraph cards

To promote pages on other platforms, edit the header section in `src/App/templates/layout/default.html.twig`, where the Twitter (X) and OpenGraph cards are placed. Update all items based on your page content.

- `{{ url('home') }}` generates the homepage URL, and the same pattern is used for other pages, as in the canonical URL block: `{% block canonical %}{{ url(routeName ?? null) }}{% endblock %}` (the `block` is present to handle not-found pages, e.g. mistyped URLs).
- An image referenced as `{{ url('home') }}images/app/My-image.png` is found at `public/images/app/My-image.png`, copied there by the `npm` script from `src/App/assets/images/PHP-REST-API.png`.

```html
<!-- Twitter card -->
<meta name="twitter:card" content="summary_large_image">
<meta name="twitter:site" content="@example">
<meta name="twitter:title" content="Page title">
<meta name="twitter:description" content="Basic description">
<meta name="twitter:image" content="{{ url('home') }}images/app/My-image.png">
<meta name="twitter:image:alt" content="Image alt">

<!-- OpenGraph card -->
<meta property="og:title" content="Page title"/>
<meta property="og:type" content="website"/>
<meta property="og:url" content="{{ url('home') }}"/>
<meta property="og:image" content="{{ url('home') }}images/app/My-image.png"/>
<meta property="og:description" content="Basic description"/>
```

### Top menu

This menu is displayed on all pages, in the header.
Edit it in `src/App/templates/layout/default.html.twig`, under `id="navbarHeader"`:

```html
<div class="menu" id="navbarHeader">
    <ul class="navbar-nav mr-auto">
    <li class="nav-item">
        <a class="nav-link" target="_blank" href="https://first.example.com/">First Link</a>
    </li>
    <li class="nav-item">
        <a class="nav-link" target="_blank" href="https://second.example.com/">Second Link</a>
    </li>
    </ul>
</div>
```

You can replace the `nav-item` class for the `li` elements with `button-border` for a link that looks more like a button.

### Footer

To edit the footer on all pages, search for `<footer class="app-footer">` in `src/App/templates/layout/default.html.twig`.
Its content is usually basic HTML and CSS with twig elements already covered above.

## FAQ

**Q: What is Dotkernel Light designed for?**
A: It's a good starting point for a project when you want full control over its functionality, and it easily grows into something more complex by integrating packages based on your requirements.

**Q: What functionality does Dotkernel Light include out of the box?**
A: Routing, Templating, Error handling, and Tests and code quality checks.

**Q: What features are removed from Dotkernel Light compared to Dotkernel Frontend?**
A: Everything related to the database, Sessions/Cookies/Flash messages, Authentication/Authorization, Dependency Injection, Mail related stuff, Navigation, CORS, Forms/Validators/InputFilters, the User module, the Contact module, and the Plugin module.

**Q: How do you add a new page to a Dotkernel Light site?**
A: Add an Action function for the page (e.g. examplePageAction()) in src/Page/src/Controller/PageController.php that renders a template, then create the matching template file in src/Page/templates/page/ (e.g. example-template.html.twig), with the page copy placed in its content block.

**Q: Where should new page assets like fonts, images, JS, and CSS be placed?**
A: Under src/App/assets/, in its default folders: src/App/assets/fonts, src/App/assets/images, src/App/assets/js, and src/App/assets/scss.
Run npm run watch during edits, or npm run prod once the edits are completed.

**Q: Where do you edit the top menu and footer that appear on every page?**
A: Both live in src/App/templates/layout/default.html.twig: the top menu items are under id="navbarHeader", and the footer content is inside the footer element with class "app-footer".

## Resources

- [dotkernel.org](https://www.dotkernel.org) - a working example
- [Dotkernel Light](https://github.com/dotkernel/light)
- [More from Dotkernel](https://github.com/dotkernel)


<!-- ============================================================ -->
<!-- dotkernel/dotkernel-on-nginx.md -->
<!-- ============================================================ -->

---
title: "Dotkernel on Nginx"
description: "A walkthrough of testing whether Dotkernel runs out of the box on Nginx, and how the Nginx configuration was set up as a substitute for Apache's .htaccess."
author: "admin"
date_published: "2013-06-25"
canonical_url: "https://www.dotkernel.com/dotkernel/dotkernel-on-nginx/"
category: "Dotkernel"
language: "en"
---

# Dotkernel on Nginx

## TL;DR

Since Nginx was becoming the buzzword instead of Apache, this article tests Dotkernel on Nginx and documents the configuration needed: server block settings, a `try_files` directive in place of `.htaccess`, PHP-FPM handling, and protecting the `configs` folder.

## Setup steps

1. Installed on a clean CentOS 6.3 VPS: Nginx 1.4.1, PHP 5.4.16, PHP-FPM.
2. Installed PHP modules: APC, GeoIP, and others.
3. Installed PEAR and Zend Framework from the PEAR ZF channel (`http://code.google.com/p/zend/`).
4. Fine-tuned `php.ini`: date, default charset, include path, etc.
5. Created a MySQL database on a remote server and allowed permissions from the Nginx server's IP to connect to it.
6. Edited the Nginx config (`/etc/nginx/conf.d/default.conf`):
   - Set the server name:
     ```
     server_name  nginx.dotkernel.net;
     ```
   - Set the document root, in the `location /` area:
     ```
     root   /var/www/html;
     ```
   - The equivalent of the main `.htaccess` file, sending all requests to `index.php`:
     ```
     try_files    $uri $uri/ /index.php;
     ```
   - Set the location for the PHP directive:
     ```
     location ~ \.php$ {
                root           /var/www/html;
                fastcgi_pass   127.0.0.1:9000;
                fastcgi_index  index.php;
                fastcgi_param  SCRIPT_FILENAME  /var/www/html$fastcgi_script_name;
                fastcgi_param APPLICATION_ENV staging;
                include        fastcgi_params;
     }
     ```
     `APPLICATION_ENV` can be changed to `production` or `development`.
   - Protect the `configs` folder from web access:
     ```
     #protect folders
     location ~ ^/configs/ {
             deny all;
     }
     ```
7. Exported a Dotkernel copy from SVN:
   ```shell
   svn export --force  http://v1.dotkernel.net/svn/trunk/ /var/www/html
   ```
8. Edited `application.ini` to reflect the current settings, and checked that it was protected.
9. Result: the site was running on Nginx.
Admin login was disabled on the demo for security reasons.

## FAQ

**Q: What server stack was used to test Dotkernel on Nginx?**
A: A clean CentOS 6.3 VPS running Nginx 1.4.1, PHP 5.4.16, and PHP-FPM, with the APC and GeoIP PHP modules installed.

**Q: What is the Nginx equivalent of the main .htaccess file?**
A: The directive `try_files $uri $uri/ /index.php;`, which sends all requests to the index.php file.

**Q: How is the configs folder protected from web access in Nginx?**
A: By adding a location block matching `^/configs/` that returns `deny all;`.

**Q: How was the Dotkernel codebase deployed onto the server?**
A: It was exported directly from SVN using `svn export --force http://v1.dotkernel.net/svn/trunk/ /var/www/html`.

## Resources

- [PEAR ZF Channel](http://code.google.com/p/zend/)
- [application.ini example](http://nginx.dotkernel.net/configs/application.ini)
- [Live Nginx demo](http://nginx.dotkernel.net/)


<!-- ============================================================ -->
<!-- dotkernel/dotkernel-reserved-variable-names-for-caching.md -->
<!-- ============================================================ -->

---
title: "Dotkernel Reserved Variable Names for Caching"
description: "A reference of the variables Dotkernel caches - router, ACL role, menu, options, and browser/OS data - and the cache keys they use."
author: "Gabi DJ"
date_published: "2015-01-29"
canonical_url: "https://www.dotkernel.com/dotkernel/dotkernel-reserved-variable-names-for-caching/"
category: "Dotkernel"
language: "en"
---

# Dotkernel Reserved Variable Names for Caching

## TL;DR

This article is a follow-up to "Caching in Dotkernel Using Zend Framework Cache" and lists the variables Dotkernel caches, along with the exact cache key each one uses.

## Cached variables

| Item | Source | Cache key(s) |
|---|---|---|
| Router | Loads routes (modules, controllers, actions) settings from `router.xml` | `router` |
| Auth / ACL Role | `Dot_Auth`'s `/configs/acl/role.xml`, defining user rights | `acl_role` |
| Menu | `menu.xml` from the current module | `admin_menu`, `frontend_menu` |
| Options | Files found in `/configs/dots/` | `option_MODULE_CONTROLLER`, e.g. `option_admin_Admin`, `option_frontend_Page`, `option_admin_seo` (seo is lowercase) |
| Browser & OS | `browser.xml` and `os.xml` in `/configs/useragent/`, identifying browser/OS name, icon, and type | `browser_xml`, `os_xml` |

## Important note

Be careful when changing the XML files or values that get cached, as they remain cached. If a change appears to have no effect, you must clear the cache or rewrite that value in the cache.

## FAQ

**Q: What cache key is used for the router?**
A: The router, which loads routes settings from router.xml, is cached as `router`.

**Q: What cache key stores the ACL role definitions?**
A: The role.xml file (used by Dot_Auth, from /configs/acl/role.xml, to define user rights) is cached as `acl_role`.

**Q: How is the menu cached?**
A: The menu.xml from the current module is cached as `admin_menu` and `frontend_menu`.

**Q: What naming pattern do cached options use?**
A: `option_MODULE_CONTROLLER`, where MODULE is the current module and CONTROLLER is the current controller or "seo" - for example `option_admin_Admin`, `option_frontend_Page`, and `option_admin_seo` (seo is lowercase).

**Q: What happens if you change browser.xml, os.xml, or other cached config files?**
A: The change won't take effect on its own, since values like browser_xml and os_xml remain cached - you must clear the cache or rewrite that value in cache to see the change take effect.

## Resources

- [Caching in Dotkernel Using Zend Framework Cache](http://www.dotkernel.com/dotkernel/caching-in-dotkernel-using-zend-framework)
- [router.xml documentation](http://www.dotkernel.com/docs/router-xml/)
- [Module Structure](http://www.dotkernel.com/docs/module-structure/)
- [menu.xml documentation](http://www.dotkernel.com/docs/menu-xml/)


<!-- ============================================================ -->
<!-- dotkernel/dotkernel-template-engine.md -->
<!-- ============================================================ -->

---
title: "Dotkernel Template Engine"
description: "Dotkernel Template Engine is an implementation of the PHPLib Template engine for PHP5, separating application code from the presentation layer."
author: "admin"
date_published: "2009-10-02"
canonical_url: "https://www.dotkernel.com/dotkernel/dotkernel-template-engine/"
category: "Dotkernel"
language: "en"
---

# Dotkernel Template Engine

Dotkernel Template Engine is an implementation of the PHPLib Template engine for PHP5.
It has an amazing ability to separate the application code from the presentation layer, separating the manipulation of data (in the database as well as in PHP) from its final format, whether that format is HTML, XML, or a formatted e-mail.
The big advantage is that it allows changing the look and feel of a site quickly without having to delve immediately into a lot of PHP variable assignments and print statements.

## FAQ

**Q: What is the Dotkernel Template Engine based on?**
A: It's an implementation of the PHPLib Template engine for PHP5.

**Q: What is the main benefit of using it?**
A: It separates application code from the presentation layer, and separates data manipulation from its final format (HTML, XML, or a formatted e-mail), letting you change a site's look and feel quickly without delving into a lot of PHP variable assignments and print statements.


<!-- ============================================================ -->
<!-- dotkernel/dotkernel-version-1-0-in-action.md -->
<!-- ============================================================ -->

---
title: "Dotkernel version 1.0 in action"
description: "An overview of Dotkernel 1.0, DotBoost's in-house framework built on Zend Framework, its simplified MVC architecture, and the specific Zend Framework classes it relies on."
author: "admin"
date_published: "2009-10-02"
canonical_url: "https://www.dotkernel.com/dotkernel/dotkernel-version-1-0-in-action/"
category: "Dotkernel"
language: "en"
---

# Dotkernel version 1.0 in action

## TL;DR

Dotkernel is DotBoost's in-house developed framework, built on top of Zend Framework and released under the Open Software License (OSL 3.0).
It uses a simplified MVC architecture, easy to learn for beginner and intermediate programmers, by eliminating much of Zend Framework's complexity through a different approach to handling web requests.
It relies on only a handful of Zend Framework classes.

## Zend Framework classes Dotkernel relies on

| Class | Purpose |
|---|---|
| `Zend_Config` | Provides multiple backends for configuration storage and a simple, intuitive, object-oriented interface for accessing it. Dotkernel stores configuration as simple PHP arrays, wrapped by Zend_Config. |
| `Zend_Db` and `Zend_Db_Table` | A classic implementation of the Table Data Gateway and Row Data Gateway design patterns, for easy and intuitive access to database tables and rows, and an entry point for custom business logic. |
| `Zend_Mail` | Generalized functionality to compose and send text and MIME-compliant multipart e-mail, via the default Zend_Mail_Transport_Sendmail transport or via Zend_Mail_Transport_Smtp. |
| `Zend_Registry` | A container for storing objects and values in the application space, so the same object is always available throughout the application - an alternative to global storage. |
| `Zend_Validate` | Provides a set of commonly needed validators, plus a simple validator chaining mechanism so multiple validators can be applied to a single datum in a user-defined order. |

## FAQ

**Q: Who developed Dotkernel and what is it built on?**
A: Dotkernel is DotBoost's in-house developed framework, built on top of Zend Framework.
At the time of this article it was at version 1.0, released under the Open Software License (OSL 3.0).

**Q: What architecture does Dotkernel use?**
A: A simplified MVC (Model-View-Controller) architecture that's easy to learn for beginner and intermediate level programmers, achieved by eliminating much of Zend Framework's complexity through a different approach to handling web requests.

**Q: What does Zend_Config provide in Dotkernel?**
A: It provides multiple backends for configuration storage and a simple, intuitive, object-oriented interface for accessing it.
Dotkernel stores configuration as simple PHP arrays, which are then wrapped by Zend_Config.

**Q: What role do Zend_Db and Zend_Db_Table play?**
A: Zend_Db_Table is a classic implementation of the Table Data Gateway and Row Data Gateway design patterns, allowing easy and intuitive access to database tables and rows, as well as an entry point for custom business logic surrounding the data.

**Q: What are Zend_Mail and Zend_Registry used for?**
A: Zend_Mail composes and sends both text and MIME-compliant multipart e-mail, via the default Zend_Mail_Transport_Sendmail transport or via Zend_Mail_Transport_Smtp.
Zend_Registry is a container for storing objects and values in the application space, so the same object is always available throughout the application, as an alternative to using global storage.

## Resources

- [DotBoost](http://www.dotboost.com)
- [Open Software License (OSL 3.0)](http://opensource.org/licenses/osl-3.0.php)
- [Zend Framework](http://framework.zend.com/)


<!-- ============================================================ -->
<!-- dotkernel/forcing-utf8-connections-and-character-set-in-mysql.md -->
<!-- ============================================================ -->

---
title: "Forcing UTF8 connections and character set in MySQL"
description: "How to force the MySQL server's character set and collation to UTF8 via my.cnf, so every connecting script uses it regardless of client."
author: "admin"
date_published: "2012-05-09"
canonical_url: "https://www.dotkernel.com/dotkernel/forcing-utf8-connections-and-character-set-in-mysql/"
category: "Dotkernel"
language: "en"
---

# Forcing UTF8 connections and character set in MySQL

## TL;DR

In some situations it may be necessary to force the MySQL server's collation and character set to UTF8, since you can't control all the scripts connecting to your database (for instance the mysql command line or mysqldump).
This is done by editing `my.cnf`.

## Steps

1. Open the `my.cnf` file.
2. Add the following lines to force UTF8 for all connections:

```shell
character_set_server=utf8
skip-character-set-client-handshake
```

3. If you're interested in better performance, also add:

```shell
collation_server=utf8_general_ci
```

4. If you're interested in better sorting order instead, add this line rather than the one above:

```shell
collation_server=utf8_unicode_ci
```

## FAQ

**Q: Why force UTF8 at the MySQL server level instead of relying on each client?**
A: Because you can't control all the scripts that connect to your database (for instance the mysql command line or mysqldump), so forcing the server's collation and character set to UTF8 in my.cnf guarantees it regardless of the connecting client.

**Q: What two lines enable UTF8 for all connections in my.cnf?**
A: `character_set_server=utf8` and `skip-character-set-client-handshake`.

**Q: What's the difference between the two suggested collation settings?**
A: `collation_server=utf8_general_ci` is recommended for better performance, while `collation_server=utf8_unicode_ci` is recommended instead if better sorting order matters more.


<!-- ============================================================ -->
<!-- dotkernel/geoip-city-removed-from-dotkernel.md -->
<!-- ============================================================ -->

---
title: "GeoIP City Removed From Dotkernel"
description: "Why the GeoIP City integration was removed from Dotkernel due to a segmentation fault with GeoIP extension 1.1.0+, and how to remove the affected code if you don't need GeoIP City."
author: "Gabi DJ"
date_published: "2015-02-25"
canonical_url: "https://www.dotkernel.com/dotkernel/geoip-city-removed-from-dotkernel/"
category: "Dotkernel"
language: "en"
---

# GeoIP City Removed From Dotkernel

## TL;DR

The newest Dotkernel version removed the GeoIP City integration because the City database on GeoIP extension version 1.1.0+ was causing a segmentation fault, crashing requests or outputting an error instead of executing the PHP code.
Users on an older Dotkernel version combined with GeoIP >=1.1.0 may hit this.
If you don't need GeoIP City, the affected code can be removed.

## The error

This error occurs because of an incompatibility between the GeoIP extension and the database (dat) file.
On some operating systems, Apache still responds with HTTP Status Code 200 (OK), but with a page containing this text:

```
The server encountered an internal error or
misconfiguration and was unable to complete
your request.
```

The error might not be logged, since it's generated by the GeoIP extension itself rather than by your PHP code.

## How to remove GeoIP City if you don't need it

1. In `Dotkernel/admin/System.php` (the `Admin/System` model), comment or remove the following lines:

```php
if(geoip_db_avail(GEOIP_CITY_EDITION_REV0))
{
    $info = explode(" ",geoip_database_info(GEOIP_CITY_EDITION_REV0));
    $return = $info.' '.Dot_Kernel::TimeFormat($info);
}
```

2. In `library/Dot/GeoIp.php` (the `Dot_GeoIp` class), comment or remove the following lines:

```php
if(function_exists('geoip_db_avail') && geoip_db_avail(GEOIP_CITY_EDITION_REV0)
&& 'unknown' == $country)
{
    //if GeoIPCity.dat file exists
    $record = geoip_record_by_name($ip);
    if(!empty($record))
    {
        $countryCode = $record;
        $countryName = $record;
        $country = $countryCode != false  ? $countryCode : 'unknown';
        $country = $countryName != false  ? $countryName : 'NA';
    }
}
```

These changes were also made in the latest version of Dotkernel.
Use this fix only if you don't intend to use GeoIP City.

## Recommendation

Special coding is recommended for using GeoIP City and the GeoIP extension in general.
Note that GeoIP is an obsolete extension - MaxMind recommends using GeoIP2 instead.

## FAQ

**Q: Why was GeoIP City removed from Dotkernel?**
A: The City database on GeoIP extension version 1.1.0 and above was causing a segmentation fault, which resulted in crashing or outputting an error instead of executing the PHP code.

**Q: Who is affected by this error?**
A: Users running an older Dotkernel version together with GeoIP extension version 1.1.0 or newer, since the error comes from the extension's incompatibility with the database (dat) file.

**Q: How does the error show up to visitors?**
A: On some operating systems, Apache still responds with HTTP Status Code 200 (OK) but with a page containing a generic "internal error or misconfiguration" message, and the error might not be logged since it's generated by the GeoIP extension rather than by the PHP code.

**Q: How can you get rid of the error if you don't need GeoIP City?**
A: Comment out or remove the relevant lines in Dotkernel/admin/System.php (the Admin/System model) and in library/Dot/GeoIp.php (the Dot_GeoIp class).
These changes were also made in the latest version of Dotkernel, but this fix should only be used if you don't intend to use GeoIP City.

**Q: What does the article recommend going forward?**
A: It recommends special coding for GeoIP City and for the GeoIP extension in general, and notes that GeoIP is an obsolete extension, with Maxmind recommending GeoIP2 instead.


<!-- ============================================================ -->
<!-- dotkernel/geoip-ip-address-location-in-dotkernel.md -->
<!-- ============================================================ -->

---
title: "GeoIP: Ip Address Location In Dotkernel"
description: "How Dotkernel's getCountryByIp function in library/Dot/Geoip.php uses MaxMind's GeoIP technology and its .dat files to determine a visitor's country."
author: "Teo"
date_published: "2010-10-19"
canonical_url: "https://www.dotkernel.com/dotkernel/geoip-ip-address-location-in-dotkernel/"
category: "Dotkernel"
language: "en"
---

# GeoIP: Ip Address Location In Dotkernel

## TL;DR

GeoIP is MaxMind's proprietary technology for IP geolocation.
Dotkernel uses it to get user statistics by country, determining a visitor's country, region, city, postal code, or area code in real time.
The logic lives in `library/Dot/Geoip.php`, inside the `getCountryByIp` function, which branches over four cases depending on whether the `mod_geoip` PECL extension and its `.dat` files are available.

## What getCountryByIp does

The function first reads the session variable used to remember possible error messages, and initializes the country as 'unknown' in case it isn't found.
It then runs through four if/else branches:

1. **`mod_geoip` PECL extension is not installed** - it uses the existing `externals/geoip/GeoIP.dat` file bundled with Dotkernel (downloadable from MaxMind if you don't have it).
2. **`mod_geoip` is installed and `GeoIP.dat` exists** (`geoip_db_avail(GEOIP_COUNTRY_EDITION)`) - it uses the built-in PHP functions `geoip_country_code_by_name` and `geoip_country_name_by_name` to get the country code and name.
3. **`mod_geoip` is installed, `GeoIP.dat` doesn't exist, but `GeoIpCity.dat` exists** - it uses the PHP function `geoip_record_by_name` to get the country code and name.
4. **`mod_geoip` is installed, but neither `GeoIP.dat` nor `GeoIPCity.dat` exist** - same behavior as case 1: it uses `externals/geoip/GeoIP.dat` from the Dotkernel framework.

```php
/**
 * Get the country by IP
 * Return an array with : short name, like 'us' and long name, like 'United States'
 * @access public
 * @param string $ip
 * @return array
 */
public function getCountryByIp($ip)
{
    $session = Zend_Registry::get('session');
    $country = array(0 => 'unknown',1 => 'NA');
    if(extension_loaded('geoip') == FALSE)
    {
        // GeoIp extension is not active
        $api = new Dot_Geoip_Country();
        $geoipPath = 'externals/geoip/GeoIP.dat';
        if(file_exists($geoipPath))
        {
            $country = $api->getCountryByAddr($geoipPath, $ip);
        }
        else
        {
            $session->message = $this->option->warningMessage->modGeoIp;
            $session->message = 'warning';
        }
    }
    elseif(geoip_db_avail(GEOIP_COUNTRY_EDITION))
    {
        //if GeoIP.dat file exists
        $country = geoip_country_code_by_name ($ip);
        $country = geoip_country_name_by_name($ip);
    }
    elseif(geoip_db_avail(GEOIP_CITY_EDITION_REV0))
    {
        //if GeoIPCity.dat file exists
        $record = geoip_record_by_name($ip);
        if(!empty($record))
        {
            $country = $record;
            $country = $record;
        }
    }
    else
    {
        // GeoIp extension is not active
        $api = new Dot_Geoip_Country();
        $geoipPath = 'externals/geoip/GeoIP.dat';
        if(file_exists($geoipPath))
        {
            $country = $api->getCountryByAddr($geoipPath, $ip);
        }
        else
        {
            $session->message = $this->option->warningMessage->modGeoIp;;
            $session->message = 'warning';
        }
    }
    return $country;
}
```

## FAQ

**Q: What is GeoIP and what does it let Dotkernel do?**
A: GeoIP is MaxMind's proprietary technology for IP geolocation data.
Dotkernel uses it to get user statistics by country, determining a visitor's country, region, city, postal code, or area code in real time.

**Q: Where does the GeoIP logic live in Dotkernel?**
A: In library/Dot/Geoip.php, inside the getCountryByIp function.

**Q: What does getCountryByIp do when the mod_geoip PECL extension isn't installed?**
A: It falls back to the existing externals/geoip/GeoIP.dat file bundled with Dotkernel (downloadable from MaxMind if not present).

**Q: What happens when mod_geoip is installed and GeoIP.dat exists?**
A: It uses the built-in PHP functions geoip_country_code_by_name and geoip_country_name_by_name to get the country code and name.

**Q: What if GeoIP.dat is missing but GeoIPCity.dat exists, or neither file exists?**
A: If GeoIPCity.dat exists, it uses the PHP function geoip_record_by_name to get the country code and name.
If neither .dat file exists, it behaves the same as when mod_geoip isn't installed, falling back to externals/geoip/GeoIP.dat.

## Resources

- [MaxMind's IP geolocation](http://www.maxmind.com/app/ip-location)
- [library/Dot/Geoip.php source](http://websvn.dotkernel.net/filedetails.php?repname=Dotkernel&path=%2Ftrunk%2Flibrary%2FDot%2FGeoip.php)
- [GeoLite Country database](http://www.maxmind.com/app/geolitecountry)
- [PHP GeoIP functions](http://php.net/manual/en/book.geoip.php)


<!-- ============================================================ -->
<!-- dotkernel/handling-and-logging-errors-with-dot-errorhandler-and-dot-log.md -->
<!-- ============================================================ -->

---
title: "Handling and Logging errors with dot-errorhandler and dot-log"
description: "A guide to using dotkernel/dot-errorhandler alongside dot-log (or zend-log) to log errors in Zend Expressive applications, covering its two handler types, configuration, and how it was tested."
author: "Gabi DJ"
date_published: "2018-11-27"
canonical_url: "https://www.dotkernel.com/dotkernel/handling-and-logging-errors-with-dot-errorhandler-and-dot-log/"
category: "Dotkernel"
language: "en"
---

# Handling and Logging errors with dot-errorhandler and dot-log

## TL;DR

This article is a follow-up to "Logging with dot-log in Zend Expressive and Dotkernel" and explains how to use `dotkernel/dot-errorhandler` together with `dotkernel/dot-log` or `zendframework/zend-log` to log errors in Zend Expressive applications.
It covers how dot-errorhandler was built, how to configure it, and how it was tested.

## The two error handlers

- **The plain `ErrorHandler`** - a copy of Zend Expressive's `Zend\Stratigility\Middleware\ErrorHandler` (copied because that class is `final`).
- **The logging `LogErrorHandler`** - the same as above, but with added logging support via the container.

Both error handlers have factories registered for easier use with the Container.

Install it with:

```shell
composer require dotkernel/dot-errorhandler
```

## The Config Provider

When the dot-errorhandler config provider is invoked, both error handlers' factories are registered, and an alias is added to switch between them.
As a fallback, the plain error handler is selected by default, and this can be overwritten through the config file.

## Configuration

Important notes:

- This assumes the project already has a configured logger, as described in the "Logging with dot-log in Zend Expressive and Dotkernel" article, with the logger named `default_logger` (as used in the package's config example).
- Although the config key is `dot_log`, the dot-log abstract factory responds to the `dot-log` selector - the container key to ask for is `dot-log.default_logger`.
- dot-errorhandler is meant to be a silent logger for staging and production environments.
To test it, development mode should be disabled, otherwise whoops will catch the errors and show them to the developer instead.
Any custom error handler can be used as long as it implements the provided `ErrorHandlerInterface`.

Steps to configure:

1. Add `Dot\ErrorHandler\ConfigProvider` to the project's `config/config.php` file.
2. Write the error handler config.

To use the logging error handler, this config is needed, in `config/autoload/dot-errorhandler.global.php`:

```php
use Dot\ErrorHandler\ErrorHandlerInterface;
use Dot\ErrorHandler\LogErrorHandler;
```

The `logger` key in the dot-errorhandler config should reflect your logger configuration in `config/autoload/log.global.php`.
An out-of-the-box config was provided within the error handler's config directory for using the default logger.

## Usage / Triggering errors

Errors were triggered in the following ways to test the handlers:

- Throwing Exceptions - the most common case.
- Raising errors, such as triggering warning/error messages, for example:
  - dividing numbers by zero (e.g. `16/0`)
  - casting arrays to strings (e.g. `$string = 'hello' . $array`)

## FAQ

**Q: What two kinds of error handlers does dot-errorhandler provide?**
A: A plain ErrorHandler, which is a copy of Zend Expressive's Zend\Stratigility\Middleware\ErrorHandler (copied because that class is final), and a logging LogErrorHandler, which is the same but with added logging support via the container.
Both have factories registered for easier use with the Container.

**Q: How do you install dot-errorhandler?**
A: Run `composer require dotkernel/dot-errorhandler`.

**Q: Which error handler is used by default?**
A: The plain error handler is selected by default as a fallback, and this can be overwritten through the config file, which also registers factories for both handlers plus an alias to switch between them.

**Q: What must already be in place before configuring the logging error handler?**
A: A configured logger as described in the "Logging with dot-log in Zend Expressive and Dotkernel" article, with the logger named default_logger as used in the package's config example.

**Q: Why might whoops interfere when testing dot-errorhandler?**
A: dot-errorhandler is meant to be a silent logger for staging and production environments.
To actually test it, development mode should be disabled, otherwise whoops will catch the errors and show them to the developer instead.

**Q: How were errors triggered to test the error handlers?**
A: By throwing Exceptions, the most common case, and by raising warnings/errors such as dividing a number by zero (e.g. 16/0) or casting an array to a string.

## Resources

- [Logging with dot-log in Zend Expressive and Dotkernel](https://www.dotkernel.com/dotkernel/logging-with-dot-log-in-zend-expressive-and-dotkernel/)


<!-- ============================================================ -->
<!-- dotkernel/highcharts-integration-in-dotkernel-1-6-0.md -->
<!-- ============================================================ -->

---
title: "Highcharts Integration in Dotkernel 1.6.0"
description: "Dotkernel 1.6.0 integrates the Highcharts charting library, adding interactive pie, column and line chart samples to the admin."
author: "deddu"
date_published: "2012-05-18"
canonical_url: "https://www.dotkernel.com/dotkernel/highcharts-integration-in-dotkernel-1-6-0/"
category: "Dotkernel"
language: "en"
---

# Highcharts Integration in Dotkernel 1.6.0

## TL;DR
Dotkernel 1.6.0 integrates the Highcharts charting library, offering a new, intuitive and interactive charting experience.
Sample charts (pie, column and line) were added to the admin, and the library ships in the project's externals directory.

## What was added

The admin includes samples built with Highcharts:

- A pie chart (with a small custom feature)
- A column chart
- A line chart

The Highcharts library itself can be found in the **externals** directory of the project.

## Example: line chart configuration

The article shows a sample of how a line chart is configured with Highcharts, including the chart type, tooltip formatter, axis labels and the `timeActivity` series:

```javascript
chart = new Highcharts.Chart({
    chart: {
        renderTo: elementId,
        type: 'line',
        plotBackgroundColor: null,
        plotBorderWidth: 0,
    },
    credits: {
        enabled: false
    },
    title: {
        text: ''
    },
    colors: colors,
    tooltip: {
        formatter: function() {
            return '<strong>' + this.series.name + ' ' + this.x + '</strong>' + 'Total logins: ' + this.y;
        }
    },
    yAxis: {
        title: {
            text: 'Logins count'
        },
        min: 0
    },
    xAxis: {
        categories: ,
        labels: {
            rotation: -45,
            align: 'right',
            style: {
                font: 'normal 10px Verdana, sans-serif'
            }
        }
    },
    series: timeActivity
});
```

## FAQ

**Q: What charting library was integrated in Dotkernel 1.6.0?**
A: Highcharts was integrated in Dotkernel 1.6.0, offering a new, intuitive and interactive charting experience.

**Q: What sample charts were added to the admin?**
A: The admin includes samples made with Highcharts: a pie chart (with a small custom feature), a column chart, and a line chart.

**Q: Where can the Highcharts library be found in a Dotkernel project?**
A: The Highcharts library is located in the externals directory of the project.


<!-- ============================================================ -->
<!-- dotkernel/how-to-build-this-website-starting-from-dotkernel-light.md -->
<!-- ============================================================ -->

---
title: "How to build this website starting from Dotkernel Light"
description: "How this blog itself came together: starting from the Dotkernel Light starter project, then following the Tutorial 101 to add Doctrine ORM and load real data into the database."
author: "stefan"
date_published: "2026-08-14"
canonical_url: "https://www.dotkernel.com/dotkernel/how-to-build-this-website-starting-from-dotkernel-light/"
category: "Dotkernel"
language: "en"
---

# How to build this website starting from Dotkernel Light

## TL;DR

This project started from the Dotkernel Light starter (Mezzio, Twig, FastRoute, PSR-7 via Laminas Diactoros) as a bare-bones website skeleton.
Following the official Tutorial 101, Doctrine ORM was added on top: entities for posts, categories, authors and tags, migrations to create the schema, and fixtures to load real content into the database.
The result is this: a Dotkernel Light project turned into a fully data-driven site.

## Starting from Dotkernel Light

This blog didn't start as a blog. It started as a bare [Dotkernel Light](https://docs.dotkernel.org/light-documentation/) installation - a minimal starter project built on Mezzio, with Twig for templating, FastRoute for routing, PSR-7 via Laminas Diactoros, and a PSR-11 container using Laminas Service Manager. No database, no posts, just the skeleton for a simple website.

```
git clone https://github.com/dotkernel/light.git dotkernel-light
```

At that point you have routing, templating and a working request lifecycle, but nothing to persist. Dotkernel Light is deliberately unopinionated about storage - it's up to the project to add a persistence layer if it needs one.

## Adding Doctrine, following Tutorial 101

This project needed one: categories, authors, tags, and posts, all queryable and paginated. Rather than wiring Doctrine ORM in from scratch, the official [Tutorial 101](https://docs.dotkernel.org/tutorial-101/v1/introduction/) was followed, which walks through exactly this on top of a fresh Dotkernel Light install:

1. Installing Doctrine ORM and wiring it into the container.
2. Defining entities and generating migrations to create the schema.
3. Loading fixture data and building the repositories/queries needed to list and display it.

Following that path is what turned this project's `Category`, `Author`, `Tag` and `Post` entities, their migrations, and the repositories behind every listing and category page on this site into what they are now.

## Where the data comes from

The actual content - every article, its author, its category and tags - is authored as data in `src/App/src/Fixture/articles_cleaned.json` and loaded into the database with `php bin/doctrine-fixtures`. That file wasn't written from scratch: it was built from what already existed in dotkernel.com's own database, cleaned up and reshaped into fixture data so it could be loaded into this project's schema. Doctrine takes care of turning that into rows; the entities and repositories added while following Tutorial 101 take care of turning those rows back into the pages you're browsing right now.

## FAQ

**Q: What is Dotkernel Light?**
A: A minimal Mezzio-based starter project for building a simple website - routing (FastRoute), templating (Twig) and PSR-7 (Laminas Diactoros) out of the box, without a database layer.

**Q: Why was Doctrine added on top?**
A: Dotkernel Light doesn't include persistence by default. This blog needed categories, authors, tags and posts stored and queried from a database, so Doctrine ORM was added following the official Tutorial 101.

**Q: Where does the article content come from?**
A: From `src/App/src/Fixture/articles_cleaned.json`, loaded into the database via `php bin/doctrine-fixtures`.


<!-- ============================================================ -->
<!-- dotkernel/how-to-group-log-files-by-date-using-dot-log.md -->
<!-- ============================================================ -->

---
title: "How to group log files by date using dot-log"
description: "How dot-log Version 3.1.1 lets you use datetime formatter strings in the stream option of a log writer, so log files get grouped by date."
author: "Alex Karajos"
date_published: "2021-04-26"
canonical_url: "https://www.dotkernel.com/dotkernel/how-to-group-log-files-by-date-using-dot-log/"
category: "Dotkernel"
language: "en"
---

# How to group log files by date using dot-log

## TL;DR
[dot-log](https://github.com/dotkernel/dot-log) is a powerful, easily customizable logging tool.
[Version 3.1.1](https://github.com/dotkernel/dot-log/releases/tag/3.1.1) adds the ability to use datetime formatter strings right in the stream option of a log writer, and fixes an issue where caching dot-log configs caused logs to be written to a single file instead of being grouped by date.

## Prerequisites

- dot-log installed and configured inside your application.
If it's not installed, follow the steps in [Logging with dot-log in Zend Expressive and Dotkernel](https://www.dotkernel.com/dotkernel/logging-with-dot-log-in-zend-expressive-and-dotkernel/).
- Otherwise, make sure you're using the latest version by running:

```shell
composer update dotkernel/dot-log
```

If your application logs messages to a single file with a static name (e.g. `log/dk.log`), you can skip the rest of this guide - logging will work as before.

## Configuring the logger with Dotkernel

Your application should already have a `config/autoload/error-handling.global.php` file similar to:

```php
<?php

return [
    'dot-errorhandler' => [
        'loggerEnabled' => true,
        'logger' => 'dot-log.default_logger'
    ],
    'dot_log' => [
        'loggers' => [
            'default_logger' => [
                'writers' => [
                    'FileWriter' => [
                        'name' => 'stream',
                        'priority' => \Laminas\Log\Logger::ALERT,
                        'options' => [
                            'stream' => sprintf('%s/../../log/error-log-%s.log', __DIR__, date('Y-m-d')),
                            // explicitly log all messages
                            'filters' => [
                                'allMessages' => [
                                    'name' => 'priority',
                                    'options' => [
                                        'operator' => '>=',
                                        'priority' => \Laminas\Log\Logger::EMERG,
                                    ],
                                ],
                            ],
                            'formatter' => [
                                'name' => \Laminas\Log\Formatter\Json::class,
                            ],
                        ],
                    ],
                ],
            ],
        ],
    ],
];
```

1. Locate every log writer by navigating to `dot_log -> loggers -> default_logger -> writers`.
2. For each writer, find the `stream` option containing the path to the log file.
If it looks like:

   ```php
   'stream' => sprintf('%s/../../log/error-log-%s.log', __DIR__, date('Y-m-d'))
   ```

3. Replace it with:

   ```php
   'stream' => __DIR__ . '/../../log/error-log-{Y}-{m}-{d}.log'
   ```

4. Clear the config cache:

   ```shell
   php bin/clear-config-cache.php
   ```

If the log path uses other date format specifiers, adapt them accordingly - the full list is in the [PHP date() manual](https://www.php.net/manual/en/datetime.format.php).

## Configuring the logger without Dotkernel

Locate the dot-log config (probably `/config/autoload/log.global.php`), which should look similar to the Dotkernel example but keyed under a custom logger name (e.g. `my_logger`) and may define multiple writers (e.g. a general file writer, a warnings-only writer, and a warnings-or-higher writer).

1. Locate every writer by navigating to `dot_log -> loggers -> my_logger -> writers`.
2. For each writer, find the `stream` option.
If it looks like:

   ```php
   'stream' => sprintf('%s/../../log/dk-%s.log', __DIR__, date('Y-m-d'))
   ```

3. Replace it with:

   ```php
   'stream' => __DIR__ . '/../../log/error-log-{Y}-{m}-{d}.log',
   ```

4. Make sure you clear your application's config before usage.

As before, adapt any other date format specifiers as needed - see the [PHP date() manual](https://www.php.net/manual/en/datetime.format.php).

## FAQ

**Q: What does dot-log Version 3.1.1 add?**
A: Version 3.1.1 adds the ability to use datetime formatter strings directly in the stream option of your log writer, and it fixes an issue where caching dot-log configs caused logs to be written to the same file instead of being grouped by date.

**Q: How do I make sure I'm using the fix in Version 3.1.1?**
A: Make sure you're using the latest version of dot-log by running `composer update dotkernel/dot-log`.

**Q: Do I need to change anything if my logs are already written to a single static file?**
A: No. If your application logs messages in a single file with a static name (e.g. log/dk.log), you can skip the rest of the article - logging will work as before.

**Q: How do I group log files by date when using Dotkernel?**
A: In `config/autoload/error-handling.global.php`, locate every log writer by navigating to `dot_log->loggers->default_logger->writers` and replace a stream value like `sprintf('%s/../../log/error-log-%s.log', __DIR__, date('Y-m-d'))` with `__DIR__ . '/../../log/error-log-{Y}-{m}-{d}.log'`.

**Q: How do I group log files by date without Dotkernel?**
A: In your dot-log config (e.g. `/config/autoload/log.global.php`), locate every writer under `dot_log->loggers->my_logger->writers` and replace a dynamic stream value with a formatter string using `{Y}-{m}-{d}` placeholders.

**Q: What must I do after changing the stream configuration?**
A: Clear the config cache.
In a Dotkernel application, run `php bin/clear-config-cache.php`; in a non-Dotkernel setup, make sure you clear your application's config before usage.

## Resources

- [dot-log on GitHub](https://github.com/dotkernel/dot-log)
- [dot-log Version 3.1.1 release notes](https://github.com/dotkernel/dot-log/releases/tag/3.1.1)
- [Logging with dot-log in Zend Expressive and Dotkernel](https://www.dotkernel.com/dotkernel/logging-with-dot-log-in-zend-expressive-and-dotkernel/)
- [PHP date() format specifiers](https://www.php.net/manual/en/datetime.format.php)


<!-- ============================================================ -->
<!-- dotkernel/how-to-set-a-persistent-connection-to-database-with-zend-framework-zend-db-adapter.md -->
<!-- ============================================================ -->

---
title: "How to Set a Persistent Connection to Database with Zend Framework Zend_Db adapter"
description: "How to configure a persistent database connection in application.ini using the Zend_Db adapter, and the option that will not work."
author: "admin"
date_published: "2012-02-16"
canonical_url: "https://www.dotkernel.com/dotkernel/how-to-set-a-persistent-connection-to-database-with-zend-framework-zend-db-adapter/"
category: "Dotkernel"
language: "en"
---

# How to Set a Persistent Connection to Database with Zend Framework Zend_Db adapter

From time to time, it may be a good idea to have a persistent connection to the database.
The configuration option should be added to `application.ini` (using Dotkernel as an example).

Do **not** use the following - it will not work:

```ini
database.params.options.PDO::ATTR_PERSISTENT = TRUE
```

Instead, use this line:

```ini
database.params.persistent = TRUE
```

## FAQ

**Q: Where do you configure a persistent database connection in a Dotkernel project?**
A: The option should be added in application.ini, as shown in the Dotkernel approach used as an example in the article.

**Q: What Zend_Db configuration line should NOT be used for a persistent connection?**
A: `database.params.options.PDO::ATTR_PERSISTENT = TRUE` should not be used - the article states that it will not work.

**Q: What's the correct line to enable a persistent connection?**
A: Use `database.params.persistent = TRUE` instead.


<!-- ============================================================ -->
<!-- dotkernel/how-to-use-alerts-in-dotkernel.md -->
<!-- ============================================================ -->

---
title: "How to use Alerts in Dotkernel"
description: "How the Dot_Alert system works in Dotkernel, used to e-mail developers when something goes wrong, illustrated with the failed-email-send use case."
author: "Gabi DJ"
date_published: "2015-04-29"
canonical_url: "https://www.dotkernel.com/dotkernel/how-to-use-alerts-in-dotkernel/"
category: "Dotkernel"
language: "en"
---

# How to use Alerts in Dotkernel

## TL;DR
Alerts (Dot_Alert's) are e-mails usually sent to site developers using PHP's `mail()`, meant only to notify a developer that something is wrong - not for regular mail.
Dot_Alert resembles Dot_Email: it has a sender, subject, destination and message, and can be sent.
This guide walks through Dotkernel's existing example, where an Alert notifies the developer when an e-mail fails to send.

## What Dot_Alert is for

Alerts should only notify a developer: *"Hey, something's wrong here, you might want to know this!"*
The Dot_Alert class resembles Dot_Email - like a mail message, an alert has at least a sender, a subject, a destination and a message, and it can be sent.

## Example: notifying a developer of a failed e-mail send

In Dotkernel, Alerts are used to notify the developer when an e-mail was not sent successfully.

### 1. The message template (dots.xml)

The alert message is kept in the `dots.xml` file:

```xml
<variable option="global">
    <alertMessages>
        <email>
            <subject> SMTP Error on {SITE_NAME} </subject>
            <message>
SMTP Error on {SITE_NAME}
We were unable to send SMTP email
---------------------------------
Caught exception: {E_CLASS}
Message:  {E_MESSAGE}
To Email: {TO_EMAIL}
From Email: {FROM_EMAIL}
Date: {DATE_NOW}
---------------------------------
            </message>
        </email>
    </alertMessages>
</variable>
```

### 2. Fetch the message from the config

```php
$subject = $this->option->alertMessages->email->subject;
$message = $this->option->alertMessages->email->message;
```

### 3. Get the destination recipients

```php
$devEmails = explode(',', $this->settings->devEmails);
```

### 4. Prepare the details that fill the {VARIABLES}

```php
$details = array(
    'e_class' => get_class($e),
    'site_name' => $this->seoOption->siteName,
    'site_url' => $registry->configuration->website->params->url,
    'e_message' => $e->getMessage(),
    'to_email' => implode(',', $this->_to),
    'from_email' => $this->getFrom(),
    'date_now' => date('F dS, Y h:i:s A'),
);
```

`$e` is the caught exception thrown when the e-mail send process fails.

### 5. Create and send the alert

```php
$alert = new Dot_Alert();

$alert->addHeader("From: " . $this->settings->siteEmail);
$alert->addHeader("Reply-To:" . $this->settings->siteEmail);
$alert->addHeader("X-Mailer: PHP/" . phpversion());

$alert->setTo($devEmails);
$alert->setSubject($subject);
$alert->setContent($message);

// replaces the {VARIABLES} in subject/message with real data
$alert->setDetails($details);

$alert->send();
```

## FAQ

**Q: What is a Dot_Alert used for?**
A: Alerts (Dot_Alert's) are e-mails usually sent to the site developers using PHP's mail() function.
They shouldn't be used to send regular mail - they only notify the developer that something is wrong.

**Q: What does the Dot_Alert class resemble, and what does an alert contain?**
A: Dot_Alert resembles Dot_Email.
Like a mail message, an alert has at least a sender, a subject, a destination and a message, and it can be sent.

**Q: What's an example use of Alerts in Dotkernel?**
A: Dotkernel uses Alerts to notify the developer when an email was not sent successfully, with the message kept in the dots.xml file under the alertMessages section.

**Q: How are the {VARIABLES} in an alert message replaced with real data?**
A: A $details array is prepared (e.g. e_class, site_name, site_url, e_message, to_email, from_email, date_now), and the alert's setDetails() method replaces the {VARIABLES} placeholders in the subject and message with that data.

**Q: What are the steps to build and send an alert?**
A: Create a new Dot_Alert(), add headers such as From, Reply-To and X-Mailer, then call setTo(), setSubject() and setContent(), then setDetails() to fill in the placeholders, and finally call send().

## Resources

- [Understanding dots.xml](http://www.dotkernel.com/docs/dots-xml/)


<!-- ============================================================ -->
<!-- dotkernel/implementing-the-new-password-hashing-api-from-php-5-5-in-dotkernel.md -->
<!-- ============================================================ -->

---
title: "Implementing the new Password Hashing API from PHP 5.5 in Dotkernel"
description: "Dotkernel 1.8.0 refactors password handling to use PHP 5.5's Password Hashing API, using the Password Compat library for older PHP, with steps to upgrade existing systems."
author: "admin"
date_published: "2014-06-06"
canonical_url: "https://www.dotkernel.com/dotkernel/implementing-the-new-password-hashing-api-from-php-5-5-in-dotkernel/"
category: "Dotkernel"
language: "en"
---

# Implementing the new Password Hashing API from PHP 5.5 in Dotkernel

## TL;DR
To use the new [Password Hashing](http://www.php.net/manual/en/book.password.php) functions introduced in PHP 5.5 and unify password-related functions for both admin and users, Dotkernel's codebase was refactored in version 1.8.0 (starting from revision 799).
Because those functions require PHP 5.5+, the [Password Compat library](https://github.com/ircmaxell/password_compat) is used for compatibility, and the minimum PHP version to run Dotkernel was raised to 5.3.8.

## Background

See more on the reasoning behind this change [here](http://www.brandonsavage.net/please-stop-hashing-passwords-yourself/).

## Applying this refactor to older Dotkernel systems

1. Change the table structure to handle the new password format:

   ```sql
   ALTER TABLE `admin` CHANGE `password` `password` VARCHAR(255) CHARACTER SET utf8 COLLATE utf8_bin NOT NULL;
   ALTER TABLE `user` CHANGE `password` `password` VARCHAR(255) CHARACTER SET utf8 COLLATE utf8_bin NOT NULL;
   ```

2. Remove the `settings.admin.salt = 5F6WQ9U3YT` variable from `application.ini`.
3. Apply the [patch](http://www.dotkernel.com/download/?did=40).
4. If you have trouble applying the patch, compare the files and see the log/diff in [websvn](http://websvn.dotkernel.net/comp.php?repname=Dotkernel&compare[]=/@796&compare[]=/@797).
5. Run the conversion script - details are in the file `Console/Controller.php`, at line 47.
6. Admin passwords cannot be converted, so they need to be recreated manually.

## FAQ

**Q: Why was Dotkernel refactored to use the new PHP 5.5 Password Hashing API?**
A: To use the new Password Hashing functions introduced in PHP 5.5 and unify all password related functions used for both admin and users, Dotkernel's codebase was refactored in version 1.8.0, starting from revision 799.

**Q: How can PHP versions older than 5.5 use these new hashing functions?**
A: Since the 4 new functions are only available since PHP 5.5, Dotkernel used the Password Compatibility library (ircmaxell/password_compat).

**Q: What is the minimum PHP version required after this change?**
A: The minimum PHP version required to run Dotkernel was raised to PHP 5.3.8.

**Q: What steps are needed to apply this refactor to an older Dotkernel system?**
A: Change the password column definition in the admin and user tables via ALTER TABLE, remove the settings.admin.salt entry from application.ini, apply the provided patch, and run the conversion script described in Console/Controller.php at line 47.

**Q: What happens to existing admin passwords during the upgrade?**
A: Admin passwords cannot be converted automatically, so they need to be recreated manually.

## Resources

- [PHP Password Hashing manual](http://www.php.net/manual/en/book.password.php)
- [Please stop hashing passwords yourself](http://www.brandonsavage.net/please-stop-hashing-passwords-yourself/)
- [Password Compatibility library](https://github.com/ircmaxell/password_compat)
- [Patch download](http://www.dotkernel.com/download/?did=40)
- [websvn diff (revision 796 vs 797)](http://websvn.dotkernel.net/comp.php?repname=Dotkernel&compare[]=/@796&compare[]=/@797)


<!-- ============================================================ -->
<!-- dotkernel/installing-geoip-extension-in-zend-server-5-6-on-windows.md -->
<!-- ============================================================ -->

---
title: "Installing GeoIP extension in Zend Server 5.6 on Windows"
description: "Step-by-step guide to testing, downloading, installing and enabling the php_geoip extension and MaxMind databases on Zend Server 5.6 for Windows."
author: "deddu"
date_published: "2013-07-31"
canonical_url: "https://www.dotkernel.com/dotkernel/installing-geoip-extension-in-zend-server-5-6-on-windows/"
category: "Dotkernel"
language: "en"
---

# Installing GeoIP extension in Zend Server 5.6 on Windows

## TL;DR
Test whether php_geoip is already available, and if not, download the correct php_geoip.dll for your PHP build from windows.php.net, copy it into Zend Server's phpext folder, enable it from the Zend Server GUI, and download the MaxMind GeoIP databases.

## Steps

1. Test if you have the php_geoip extension:

   ```php
   <?php
   var_dump(function_exists('geoip_database_info'));
   ```

   This outputs `true` if the extension is available, or `false` if not.

2. If the output is `false`, download a php_geoip.dll file correctly compiled for your Zend Server version from [http://windows.php.net/downloads/pecl/releases/geoip/1.0.8/](http://windows.php.net/downloads/pecl/releases/geoip/1.0.8/).
There are several files for different architectures and compilers.

3. Find your PHP's architecture and compiler by running `phpinfo();`.
Example values:

   | Field | Value |
   |---|---|
   | Compiler | MSVC9 (Visual C++ 2008) |
   | Architecture | x86 |

4. Copy the downloaded `php_geoip.dll` file into:

   ```
   C:\YOUR_LOCATION\Zend\ZendServer\lib\phpext\
   ```

5. In the Zend Server interface, restart PHP, turn on the geoip extension from **Server Setup -> Extension**, and restart PHP again.

   If you get an error loading the geoip extension, you picked the wrong dll - try one of the others.

   Otherwise, the extension is loaded and the test script from step 1 will output `true`.

6. Download GeoIP databases from MaxMind, as needed:
   - geoIP.dat
   - geoIPCity.dat
   - geoIPOrganization.dat
   - or anything else you need

7. Copy those `.dat` files into:

   ```
   C:\YOUR_LOCATION\Zend\ZendServer\bin\
   ```

You can now use geoip functions on Zend Server 5.6.

## FAQ

**Q: How do you test if the php_geoip extension is available on Zend Server?**
A: Create a PHP file with `var_dump(function_exists('geoip_database_info'));`.
It outputs true if the extension is available, or false if it isn't.

**Q: Where can you download the php_geoip extension for Zend Server 5.6?**
A: From http://windows.php.net/downloads/pecl/releases/geoip/1.0.8/, where several php_geoip.dll files are available for different architectures and compilers.

**Q: How do you know which php_geoip.dll file to download?**
A: You can find your PHP's architecture and the compiler it was built with by running phpinfo().

**Q: Where does the php_geoip.dll file need to be copied?**
A: Into C:\YOUR_LOCATION\Zend\ZendServer\lib\phpext\.

**Q: How do you enable the geoip extension after copying the dll?**
A: Go into the Zend Server interface, restart PHP, turn on the geoip extension from Server Setup -> Extension, and restart PHP again.
If you get an error loading the extension, you picked the wrong dll and should try another one.

**Q: What else is needed besides the extension itself?**
A: You also need to download geoip databases from MaxMind, such as geoIP.dat, geoIPCity.dat, and geoIPOrganization.dat, and copy those .dat files into C:\YOUR_LOCATION\Zend\ZendServer\bin\.

## Resources

- [php_geoip 1.0.8 downloads](http://windows.php.net/downloads/pecl/releases/geoip/1.0.8/)


<!-- ============================================================ -->
<!-- dotkernel/installing-geoip-extension-in-zend-server-6-on-windows.md -->
<!-- ============================================================ -->

---
title: "Installing GeoIP extension in Zend Server 6 on Windows"
description: "Update to the Zend Server 5.6 GeoIP guide, covering how to install and enable php_geoip on Zend Server 6.1 on Windows."
author: "admin"
date_published: "2013-07-31"
canonical_url: "https://www.dotkernel.com/dotkernel/installing-geoip-extension-in-zend-server-6-on-windows/"
category: "Dotkernel"
language: "en"
---

# Installing GeoIP extension in Zend Server 6 on Windows

## TL;DR
As an update to [Installing GeoIP extension in Zend Server 5.6 on Windows](https://www.dotkernel.com/dotkernel/installing-geoip-extension-in-zend-server-5-6-on-windows/), here's how to enable php_geoip on Zend Server 6.1.

## Steps

1. Download the `php_geoip-1.0.8-5.4-nts-vc9-x86.zip` file from [http://windows.php.net/downloads/pecl/releases/geoip/1.0.8/](http://windows.php.net/downloads/pecl/releases/geoip/1.0.8/).
2. From the archive, copy `php_geoip.dll` to `ZEND_PATH\Zend\ZendServer\lib\phpext\`.
3. Open the `php.ini` file, located at `ZEND_PATH\Zend\ZendServer\etc\php.ini`.
4. Add the following line at the end of the file:

   ```ini
   extension=php_geoip.dll
   ```

5. Save the file and click **"Restart PHP"** from the Zend Server GUI.
6. Follow the steps from the previous article to test the GeoIP integration and download the Geoip*.dat files.

## FAQ

**Q: Which php_geoip file should be downloaded for Zend Server 6.1?**
A: Download the php_geoip-1.0.8-5.4-nts-vc9-x86.zip file from http://windows.php.net/downloads/pecl/releases/geoip/1.0.8/.

**Q: Where does the php_geoip.dll go on Zend Server 6.1?**
A: Copy the php_geoip.dll file from the archive to ZEND_PATH\Zend\ZendServer\lib\phpext\.

**Q: How is the extension enabled on Zend Server 6.1?**
A: Open the php.ini file at ZEND_PATH\Zend\ZendServer\etc\php.ini, add the line extension=php_geoip.dll at the end of the file, save it, and click "Restart PHP" from the Zend Server GUI.

**Q: How do you verify GeoIP is working after this setup?**
A: Follow the same steps described in the previous article (Installing GeoIP extension in Zend Server 5.6 on Windows) to test the GeoIP integration and download the Geoip*.dat files.

## Resources

- [Installing GeoIP extension in Zend Server 5.6 on Windows](http://www.dotkernel.com/dotkernel/installing-geoip-extension-in-zend-server-5-6-on-windows/)
- [php_geoip 1.0.8 downloads](http://windows.php.net/downloads/pecl/releases/geoip/1.0.8/)


<!-- ============================================================ -->
<!-- dotkernel/logging-with-dot-log-in-zend-expressive-and-dotkernel.md -->
<!-- ============================================================ -->

---
title: "Logging with dot-log in Zend Expressive and Dotkernel"
description: "How to wire up, configure and use the dot-log component (compatible with zend-log) within Dotkernel, Zend Expressive, or any project using Zend Service Manager."
author: "Gabi DJ"
date_published: "2018-11-13"
canonical_url: "https://www.dotkernel.com/dotkernel/logging-with-dot-log-in-zend-expressive-and-dotkernel/"
category: "Dotkernel"
language: "en"
---

# Logging with dot-log in Zend Expressive and Dotkernel

## TL;DR
This article explains how to use the [dot-log](https://github.com/dotkernel/dot-log) component within Dotkernel, Zend Expressive, or any project that uses Zend Service Manager.
Since dot-log extends `zendframework/zend-log`, the tutorial is mostly compatible with zend-log as well.
See the [zend-log documentation](https://zendframework.github.io/zend-log/) for more detail.

## Adding the config provider

- Open `config/config.php`.
- If there's no entry for the dot-log config provider, add `\Dot\Log\ConfigProvider::class`.
- Make sure it's added before application-specific components, e.g. `Frontend\App\ConfigProvider::class`, `Admin\App\ConfigProvider::class`, `MyProject\ConfigProvider::class`.
- Inside `Dot\Log\ConfigProvider`, the dependencies section registers an abstract factory, `LoggerAbstractServiceFactory::class`.
This class responds to "selectors" instead of class names - instead of requesting `Zend\Log\Logger::class` from the container, you request `dot-log.my_logger` (or just `my_logger` if using zend-log).
- Create a `log.global.php` file within `/config/autoload`, returning an empty array to start.

## Configuring the logger

For this tutorial, the created logger is named **my_logger** (the name is the developer's choice and should reflect its purpose, e.g. `db_error_logger`).

In `log.global.php`:

1. Add a top-level key `dot-log` (or `log` if using zend-log) with an array value.
2. Inside it, add a `loggers` key.
3. Inside that, add the logger name key (`my_logger`) with an empty array.

For the logger to actually log somewhere, a writer is required - without one, log calls are received but there's nowhere to write the message.

## Configuring the writer(s)

Loggers must have at least one writer.
A **writer** is an object that inherits from `Zend\Log\Writer\AbstractWriter`, responsible for recording log data to a storage backend (see the [zend-log writer documentation](https://zendframework.github.io/zend-log/writers/)).

It's possible to separate logs into multiple files using writers and filters (e.g. `warnings.log`, `errors.log`, `all_messages.log`).
In the simplest example, all log messages are written to one file, e.g. `/data/logs/dk.log`, under a `writers` key inside `my_logger`.

Notes on writer configuration:

- The writer key name (e.g. `FileWriter`) is optional - otherwise the writers array would be enumerative instead of associative.
- The writer's `name` key is a developer-provided name for that writer and is **mandatory**.
- The writer's `priority` key doesn't affect which errors get written - it's only a way to organize writers (e.g. 1 - FILE, 2 - SQL, 3 - E-mail), reflecting that writing to a file is the most reliable since SQL or e-mail servers can be external and offline.
The priority key is optional.
- To write to a file, the `stream` key must be present in the writer's `options` array (required only when writing to streams/files).

More writer examples: [Streams](https://zendframework.github.io/zend-log/writers/#writing-to-streams), [Databases](https://zendframework.github.io/zend-log/writers/#writing-to-databases), [FirePHP](https://zendframework.github.io/zend-log/writers/#writing-to-firephp), [ChromePHP](https://zendframework.github.io/zend-log/writers/#writing-to-chromephp), [Mail](https://zendframework.github.io/zend-log/writers/#writing-to-mail), [MongoDB](https://zendframework.github.io/zend-log/writers/#writing-to-mongodb), [Syslog](https://zendframework.github.io/zend-log/writers/#writing-to-syslog), [Zend Monitor](https://zendframework.github.io/zend-log/writers/#writing-to-zend-monitor).

## (Optional) Configuring the filters

A **filter** prevents a message from being written to the log (see the [zend-log filters documentation](https://zendframework.github.io/zend-log/filters/)).

Per [PSR-3](https://www.php-fig.org/psr/psr-3/#5-psrlogloglevel), the log levels, in order of priority/importance, are:

| Level | Priority number |
|---|---|
| emergency | 0 |
| alert | 1 |
| critical | 2 |
| error | 3 |
| warn | 4 |
| notice | 5 |
| info | 6 |
| debug | 7 |

Although the plain Logger in Zend Log is not fully PSR-3 compatible, it provides a way to log all of these message types.
The developer can optionally use keys to name filters.
**Important:** the operator for "more important" messages is `<=`, because a smaller number represents a more important message.

More on filters: [zend-log filters documentation](https://zendframework.github.io/zend-log/filters/).

## (Optional) Configuring the formatter

The logged value isn't limited to a string - arrays can be logged too, and for readability they can be serialized. Zend Log provides String, XML, JSON and FirePHP formatting.

The formatter config accepts:

- `name` - the formatter class (must implement `Zend\Log\Formatter\FormatterInterface`)
- `options` - options passed to the formatter constructor, if required

More on formatters: [Simple](https://zendframework.github.io/zend-log/formatters/#simple-formatting), [JSON](https://zendframework.github.io/zend-log/formatters/#formatting-to-json), [XML](https://zendframework.github.io/zend-log/formatters/#formatting-to-xml), [FirePHP](https://zendframework.github.io/zend-log/formatters/#formatting-to-firephp).

## Full example (described)

A complete configuration, as described in the article, does the following:

- Uses the log through **dot-log**
- Names the logger **my_logger**
- Writes to file: **data/logs/dk.log**
- Explicitly allows **all messages** to be written
- Formats the message as **JSON**

## Usage

Basic usage of the logger:

```php
use Zend\Log\Logger;
```

```php
$logger = $container->get('dot-log.my_logger');

/** @var Logger $logger */
$logger->emerg('0 EMERG');
$logger->alert('1 ALERT');
$logger->crit('2 CRITICAL');
$logger->err('3 ERR');
$logger->warn('4 WARN');
$logger->notice('5 NOTICE');
$logger->info('6 INF');
$logger->debug('7 debug');
$logger->log(Logger::NOTICE, 'NOTICE from log()');
```

## FAQ

**Q: How do I register dot-log's config provider?**
A: In config/config.php, add `\Dot\Log\ConfigProvider::class` if it's not already there, making sure it is added before application-specific components such as Frontend\App\ConfigProvider or Admin\App\ConfigProvider.

**Q: How is a logger retrieved from the container instead of using the plain class name?**
A: Dot\Log\ConfigProvider registers an abstract factory, LoggerAbstractServiceFactory, that responds to "selectors" instead of class names.
Instead of requesting Zend\Log\Logger::class from the container, you request dot-log.my_logger (or just my_logger if using zend-log).

**Q: What is a writer, and how many does a logger need?**
A: A writer is an object that inherits from Zend\Log\Writer\AbstractWriter and is responsible for recording log data to a storage backend.
Loggers must have at least one writer, and the writer's "name" key is mandatory while its "priority" key is optional and only used to organize writers, not to affect which errors get written.

**Q: What does a filter do, and how are log levels ordered?**
A: A filter prevents a message from being written to the log.
Per PSR-3, the log levels in order of priority/importance are emergency (0), alert (1), critical (2), error (3), warn (4), notice (5), info (6), and debug (7) - the operator for "more important" messages is `<=` because a smaller number represents a more important message.

**Q: What does the formatter configuration control?**
A: The formatter accepts a "name" (a class implementing Zend\Log\Formatter\FormatterInterface) and "options" to pass to that formatter's constructor.
Zend Log provides String, XML, JSON and FirePHP formatting, and arrays can be serialized this way for better readability.

**Q: How do you actually write log messages once the logger is configured?**
A: Fetch the logger from the container, e.g. `$logger = $container->get('dot-log.my_logger');`, then call methods such as emerg(), alert(), crit(), err(), warn(), notice(), info(), debug(), or the generic log(Logger::NOTICE, 'message').

## Resources

- [zend-log documentation](https://zendframework.github.io/zend-log/)
- [zend-log writers documentation](https://zendframework.github.io/zend-log/writers/)
- [zend-log filters documentation](https://zendframework.github.io/zend-log/filters/)
- [dot-log on GitHub](https://github.com/dotkernel/dot-log)


<!-- ============================================================ -->
<!-- dotkernel/manual-upgrade-of-wurfl-xml-file-in-dotkernel.md -->
<!-- ============================================================ -->

---
title: "Manual upgrade of WURFL xml file in Dotkernel"
description: "How to manually upgrade the bundled WURFL XML file in Dotkernel now that its license has changed and Dotkernel no longer updates it."
author: "admin"
date_published: "2011-11-22"
canonical_url: "https://www.dotkernel.com/dotkernel/manual-upgrade-of-wurfl-xml-file-in-dotkernel/"
category: "Dotkernel"
language: "en"
---

# Manual upgrade of WURFL xml file in Dotkernel

## TL;DR
Dotkernel Application Framework bundles a WURFL XML file, but it's the last GPL version (from June 2011).
Because of a license change to that WURFL file, Dotkernel will no longer upgrade the bundled file - it must be upgraded manually.

## Steps to manually upgrade

1. Download the `wurfl-2.3.xml.zip` file.
2. Rename it to `wurfl.zip`.
3. Rename the file inside the archive to `wurfl.xml`.
4. Replace `/externals/wurfl/wurfl.zip` with this new `wurfl.zip` file.
5. Download the `web_browsers_patch.xml` file.
6. Replace the `/externals/wurfl/web_browsers_patch.xml` file with this new one.
7. Go to the Admin panel, click on the **empty** wurfl cache link, then rebuild the cache.

Please pay attention to WURFL license changes when performing this upgrade.

## FAQ

**Q: Why does the WURFL xml file need to be manually upgraded in Dotkernel?**
A: Dotkernel bundles an old WURFL XML file (the latest GPL version, from June 2011).
Because of a license change to that WURFL file, the bundled file will no longer be upgraded by Dotkernel, so it must be upgraded manually if you still want to use it.

**Q: What are the main steps to manually upgrade the WURFL file?**
A: Download the wurfl-2.3.xml.zip file, rename it to wurfl.zip, rename the file inside the archive to wurfl.xml, and replace /externals/wurfl/wurfl.zip with this new wurfl.zip file.

**Q: Is there anything else to replace besides wurfl.zip?**
A: Yes.
Download the web_browsers_patch.xml file and replace the /externals/wurfl/web_browsers_patch.xml file with the new one.

**Q: What's the last step after replacing the files?**
A: Go to the Admin panel, click on the "empty" wurfl cache link, then rebuild the cache.


<!-- ============================================================ -->
<!-- dotkernel/migration-of-zend-framework-1-pear-channel.md -->
<!-- ============================================================ -->

---
title: "Migration of Zend Framework 1 PEAR channel"
description: "The unofficial PEAR channel for Zend Framework 1 moved from Google Code to a new dedicated server, with instructions on how to switch to the new channel."
author: "admin"
date_published: "2016-05-11"
canonical_url: "https://www.dotkernel.com/dotkernel/migration-of-zend-framework-1-pear-channel/"
category: "Dotkernel"
language: "en"
---

# Migration of Zend Framework 1 PEAR channel

## TL;DR

The unofficial PEAR channel for Zend Framework 1 was hosted on Google Code, and once Google Code closed, it had to move.
Because the repository is over 1 GB, it could not be migrated to GitHub, so a dedicated server was built to host the PEAR channel long-term at pear.dotkernel.com.

## Why the move was needed

- Zend Framework 1 is still used by a lot of projects in production, is still a viable library collection, and runs on PHP7, even though it is only in maintenance/security-patch mode, so cancelling it completely was not an option.
- The team was unable to migrate the project to github.com because the repository is more than 1 GB in size.
- A special server was built to host only the PEAR channel for Zend Framework 1, with a commitment to keep it live and running for the long term.

## PEAR Channel Migration Guide

Use the PEAR installer to switch to the new channel:

1. Remove the installed pear package:

```shell
pear uninstall zend/zend
```

2. Remove the old Google Code channel:

```shell
pear channel-delete zend.googlecode.com/svn
```

3. Discover the new channel:

```shell
pear channel-discover pear.dotkernel.com/zf1/svn
```

4. Install the package:

```shell
pear install zend/zend
```

## FAQ

**Q: Why did the PEAR channel for Zend Framework 1 need to move?**
A: The unofficial PEAR channel for Zend Framework 1 was hosted on Google Code, and once Google Code was closed the channel was forced to move to a new location.

**Q: Why wasn't the project moved to GitHub instead?**
A: The team was unable to migrate the project to github.com because the repository is more than 1 GB in size, so they built a special server dedicated to hosting only the PEAR channel for Zend Framework 1.

**Q: Is Zend Framework 1 still worth using?**
A: Zend Framework 1 is still used by a lot of projects in production, is still a viable library collection, and runs on PHP7, even though it is only in maintenance/security-patch mode.

**Q: How do I switch to the new PEAR channel?**
A: Using the PEAR installer: remove the installed package with `pear uninstall zend/zend`, remove the old Google Code channel with `pear channel-delete zend.googlecode.com/svn`, discover the new channel with `pear channel-discover pear.dotkernel.com/zf1/svn`, and then reinstall the package with `pear install zend/zend`.

## Resources

- [@dotkernel on Twitter](https://twitter.com/dotkernel)


<!-- ============================================================ -->
<!-- dotkernel/new-features-in-zend-framework-1-12.md -->
<!-- ============================================================ -->

---
title: "New Features in Zend Framework 1.12"
description: "Overview of Zend Framework 1.12.0RC1, covering new components back ported from ZF2, the removal of the WurflApi adapter, and over 200 bug fixes."
author: "admin"
date_published: "2012-06-18"
canonical_url: "https://www.dotkernel.com/dotkernel/new-features-in-zend-framework-1-12/"
category: "Dotkernel"
language: "en"
---

# New Features in Zend Framework 1.12

## TL;DR

Per Matthew Weier O'Phinney's announcement, the Zend Framework team made available the first release candidate of the Zend Framework 1.12 series, 1.12.0RC1.
It back ports several ZF2 components to ZF1, removes the WurflApi adapter due to licensing changes, and fixes over 200 reported issues.

## New Features

| Feature | Description |
|---|---|
| Zend_Loader changes | A number of autoloaders and autoloader facilities were back ported from ZF2, including `Zend_Loader_StandardAutoloader` (improves on `Zend_Loader_Autoloader` by allowing a specific path to be associated with a vendor prefix or namespace), `Zend_Loader_ClassMapAutoloader` (lookup-table based autoloading, typically the fastest method), and `Zend_Loader_AutoloaderFactory` (can create and update autoloaders and register them with `spl_autoload_register()`). Back ported by Matthew Weier O'Phinney. |
| Zend_EventManager | A component that lets you attach and detach listeners to named events, per-instance or via shared collections, trigger events, and interrupt execution of listeners. Back ported by Matthew Weier O'Phinney. |
| Zend_Http_UserAgent_Features_Adapter_Browscap | A features adapter that calls `get_browser()` to discover mobile device capabilities for injection into UserAgent device instances, relying on the Browscap project's `php_browscap.ini` file. Created by Matthew Weier O'Phinney. |
| Zend_Mobile_Push | A component for implementing push notifications across the three major platforms: Apple (APNs), Google (C2DM), and Microsoft (MPNS). Contributed by Mike Willbanks. |
| Zend_Gdata_Analytics | An extension to Zend_Gdata for interacting with Google's Analytics Data Export API; does not change the overall operation of Zend_Gdata components. Contributed by Daniel Hartmann. |

## Removed features

- `Zend_Http_UserAgent_Features_Adapter_WurflApi` was removed due to changes in WURFL's licensing (announced previously).
The team planned to provide the WurflApi adapter directly to ScientiaMobile so WURFL users would still have that option.

## Bug Fixes

Over 200 reported issues in the tracker were fixed, with particular thanks to Adam Lundrigan, Frank Brückner and Martin Hujer, as well as everyone who ran the ZF1 unit tests and reported results.

## FAQ

**Q: What was announced for Zend Framework 1.12?**
A: Matthew Weier O'Phinney announced the immediate availability of the first release candidate of the Zend Framework 1.12 series, 1.12.0RC1.

**Q: What changed in Zend_Loader?**
A: A number of autoloaders and autoloader facilities were back ported from ZF2, including Zend_Loader_StandardAutoloader, Zend_Loader_ClassMapAutoloader, and Zend_Loader_AutoloaderFactory, providing performant alternatives to the autoloading facilities already in the 1.X releases.

**Q: What is Zend_EventManager?**
A: Zend_EventManager is a component, also back ported from ZF2, that lets you attach and detach listeners to named events (per-instance or via shared collections), trigger events, and interrupt execution of listeners.

**Q: Why was the WurflApi adapter removed?**
A: Zend_Http_UserAgent_Features_Adapter_WurflApi was removed due to changes in the licensing of WURFL.
The team planned to provide the WurflApi adapter to ScientiaMobile so WURFL users would still have that option.

**Q: How many bugs were fixed in this release?**
A: Over 200 reported issues in the tracker were fixed, with particular thanks credited to Adam Lundrigan, Frank Brückner and Martin Hujer, as well as everyone who ran the ZF1 unit tests and reported results.

## Resources

- [Matthew Weier O'Phinney's announcement](http://devzone.zend.com/2366/zend-framework-1-12-series-1-12-0rc1-now-available/)
- [Browscap project](http://browsers.garykeith.com/)
- [php_browscap.ini download](http://browsers.garykeith.com/stream.asp?PHP_BrowsCapINI)
- [Prior WurflApi removal announcement](http://www.dotkernel.com/dotkernel/zend-framework-dropped-integration-of-wurfl-adapter/)
- [Complete issue tracker list](http://framework.zend.com/issues/secure/IssueNavigator.jspa?requestId=12877)


<!-- ============================================================ -->
<!-- dotkernel/php-formatter-and-templates-for-zend-studio-10-1.md -->
<!-- ============================================================ -->

---
title: "PHP Formatter and Templates for Zend Studio 10.1"
description: "An updated PHP Formatter plugin and a Dotkernel coding standard templates file for Zend Studio 10.1, along with the required Formatter plugin change."
author: "admin"
date_published: "2013-07-02"
canonical_url: "https://www.dotkernel.com/dotkernel/php-formatter-and-templates-for-zend-studio-10-1/"
category: "Dotkernel"
language: "en"
---

# PHP Formatter and Templates for Zend Studio 10.1

Because Zend donated the Zend Studio Formatter upstream to the PDT project, the Formatter plugin for Zend Studio 10.1 needs to be changed: replace "com.zend.php" with "org.eclipse.php".
The updated file is available as the Dotkernel PHP Formatter for Zend Studio 10.1.

Dotkernel also created a templates file for Zend Studio 10.1, built according to the Dotkernel coding standard.

## FAQ

**Q: Why does the PHP Formatter plugin for Zend Studio 10.1 need to be changed?**
A: Because Zend donated the Zend Studio Formatter upstream to the PDT project, the Formatter plugin needs to be changed by replacing "com.zend.php" with "org.eclipse.php".

**Q: Where can I get Dotkernel's updated Formatter and Templates files for Zend Studio 10.1?**
A: The updated PHP Formatter file for Zend Studio 10.1 and a templates file built according to the Dotkernel coding standard are both available as downloads linked in the article.

## Resources

- [Dotkernel PHP Formatter for Zend Studio 10.1](http://www.dotkernel.com/download/?did=37)
- [About PHP Formatter (Zend Studio docs)](http://files.zend.com/help/Zend-Studio-10/zend-studio.htm#formatter.htm)
- [Templates for Zend Studio](http://www.dotkernel.com/download/?did=38)
- [About Templates in Zend Studio and how to import/export (Zend Studio docs)](http://files.zend.com/help/Zend-Studio-10/zend-studio.htm#templates.htm)


<!-- ============================================================ -->
<!-- dotkernel/protecting-admin-folder-with-htaccess-in-plesk.md -->
<!-- ============================================================ -->

---
title: "Protecting admin folder with .htaccess in Plesk"
description: "How to protect the /admin folder with HTTP Basic Auth in a Plesk vhost.conf file, and how to apply the change and finish setup with .htpasswd."
author: "admin"
date_published: "2011-06-15"
canonical_url: "https://www.dotkernel.com/dotkernel/protecting-admin-folder-with-htaccess-in-plesk/"
category: "Dotkernel"
language: "en"
---

# Protecting admin folder with .htaccess in Plesk

## Steps

1. In `/var/www/vhosts/exampledomain.com/conf/vhost.conf`, add a Location block for /admin:

```shell
<Location /admin>
   AuthType Basic
   AuthName "My Site Admin"
   AuthUserFile /var/www/vhosts/exampledomain.com/conf/.htpasswd
   Require valid-user
</Location>
```

2. Notify the server that vhost.conf has been added/changed:

```shell
/usr/local/psa/admin/sbin/websrvmng -a
```

3. Create the `.htpasswd` file and upload it to `/var/www/vhosts/exampledomain.com/conf/`.

## FAQ

**Q: How do I protect the /admin folder with .htaccess in Plesk?**
A: Add a Location block for /admin to the vhost.conf file (e.g. /var/www/vhosts/exampledomain.com/conf/vhost.conf) using AuthType Basic, an AuthName, an AuthUserFile pointing to a .htpasswd file, and Require valid-user.

**Q: After editing vhost.conf, how do I apply the change and finish setup in Plesk?**
A: Notify the server that vhost.conf has changed by running `/usr/local/psa/admin/sbin/websrvmng -a`, then create the .htpasswd file and upload it to the same conf directory referenced in the AuthUserFile directive.


<!-- ============================================================ -->
<!-- dotkernel/replacing-laminas-mail-with-symfony-mailer-in-dot-mail.md -->
<!-- ============================================================ -->

---
title: "Replacing laminas-mail with Symfony mailer in dot-mail"
description: "Why and how Dotkernel replaced the abandoned laminas/laminas-mail package with symfony/mailer inside dotkernel/dot-mail, including configuration changes and the upgrade path to version 5."
author: "Florin Bidirean"
date_published: "2025-01-08"
canonical_url: "https://www.dotkernel.com/dotkernel/replacing-laminas-mail-with-symfony-mailer-in-dot-mail/"
category: "Dotkernel"
language: "en"
---

# Replacing laminas-mail with Symfony mailer in dot-mail

## TL;DR

The Laminas Technical Steering Committee decided on 2023-12-04 to abandon laminas/laminas-mail.
Dotkernel responded by replacing it with symfony/mailer inside the dotkernel/dot-mail package (version 5), aiming for minimal impact on existing projects - calls to send mail stay the same, though mime and imap related functionality is removed.

## What prompted the change

According to the Laminas Technical Steering Committee minutes of 2023-12-04, laminas/laminas-mail was going to be abandoned: nobody was available to maintain it, and alternatives already existed in the ecosystem:

| Purpose | Package |
|---|---|
| Interacting with IMAP | [ddeboer/imap](https://github.com/ddeboer/imap) |
| Parsing MIME messages | [zbateson/mail-mime-parser](https://github.com/zbateson/mail-mime-parser) |
| Sending mail | [symfony/mailer](https://github.com/symfony/mailer) |

## How Dotkernel handles the issue

The Dotkernel team opted to replace laminas/laminas-mail in the [dotkernel/dot-mail](https://github.com/dotkernel/dot-mail) package.
This meant revising the code, including configuration files, while trying to have minimal impact on existing projects: the calls to send mail remain the same, even though some lesser-used functionality like mime and imap is lost.

## Technical approach

The switch from laminas/laminas-mail to symfony/mailer in dotkernel/dot-mail is covered across these pull requests:

- [dot-mail PR 65](https://github.com/dotkernel/dot-mail/pull/65/files)
- [dot-mail PR 66](https://github.com/dotkernel/dot-mail/pull/66/files)
- [dot-mail PR 67](https://github.com/dotkernel/dot-mail/pull/67/files)
- [dot-mail PR 69](https://github.com/dotkernel/dot-mail/pull/69/files)

> Function definition changes are not covered in the article.

The `mail.global.php` configuration file was revised to remove features that are no longer available and to make it easier to configure.
The mail transport can be any class implementing `Symfony\Component\Mailer\Transport\TransportInterface`; standard aliases are `sendmail` (`Symfony\Component\Mailer\Transport\SendmailTransport`) and `esmtp` (`Symfony\Component\Mailer\Transport\Smtp\EsmtpTransport`), defaulting to `sendmail`.
`smtp_options` are used only when the esmtp adapter is used, and there is a `log` option to log sent emails.

Use ONE of the below transporters, based on your server configuration:

```php
'transport' => 'sendmail',
```

OR

```php
'transport' => 'esmtp',
```

Sendmail is set as the default mail transport.

## How to update dotkernel/dot-mail from version 3 or 4 to version 5

1. Download the new [mail configuration file](https://github.com/dotkernel/dot-mail/blob/5.0/config/mail.global.php.dist).
2. Add the values you configured for your project, focusing on `transport`, `message_options` and `smtp_options`, then replace your old configuration file.
3. In your `composer.json`, update to `"dotkernel/dot-mail": "^5.0.0"` and run `composer update`.

At this point, `mime` and `imap` related functionality is removed.

## FAQ

**Q: Why was laminas/laminas-mail replaced?**
A: The Laminas Technical Steering Committee decided on 2023-12-04 that laminas/laminas-mail would be abandoned because there was nobody to maintain it, and several alternatives were already available in the ecosystem.

**Q: What alternatives were identified for the abandoned laminas-mail package?**
A: The alternatives mentioned are ddeboer/imap for interacting with IMAP, zbateson/mail-mime-parser for parsing MIME messages, and symfony/mailer for sending mail.

**Q: How did Dotkernel handle the removal of laminas-mail in dot-mail?**
A: The Dotkernel team replaced laminas/laminas-mail with symfony/mailer inside the dotkernel/dot-mail package, revising the code and configuration files while aiming for minimal impact on existing projects, so the calls used to send mail stay the same, even though some lesser-used functionality like mime and imap is lost.

**Q: Which mail transport does dot-mail use by default?**
A: The revised mail.global.php configuration defaults the transport to sendmail.
You should use ONE of the transporters, either 'transport' => 'sendmail' or 'transport' => 'esmtp', based on your server configuration; Sendmail was set as the default.

**Q: How do I update dotkernel/dot-mail from version 3 or 4 to version 5?**
A: Download the new mail.global.php.dist configuration file, add the values you configured for your project (focusing on transport, message_options and smtp_options) to replace your old configuration file, then update "dotkernel/dot-mail" to "^5.0.0" in composer.json and run composer update.

**Q: What functionality is lost after switching to symfony/mailer?**
A: At the time of the article, mime and imap related functionality is removed from dot-mail as a result of the switch.

## Resources

- [Laminas Technical Steering Committee minutes, 2023-12-04](https://github.com/laminas/technical-steering-committee/blob/main/meetings/minutes/2023-12-04-TSC-Minutes.md#maintainers-for-laminas-mime-and-laminas-mail)
- [laminas/laminas-mail](https://github.com/laminas/laminas-mail)
- [ddeboer/imap](https://github.com/ddeboer/imap)
- [zbateson/mail-mime-parser](https://github.com/zbateson/mail-mime-parser)
- [symfony/mailer](https://github.com/symfony/mailer)
- [dotkernel/dot-mail](https://github.com/dotkernel/dot-mail)
- [dot-mail PR 65](https://github.com/dotkernel/dot-mail/pull/65/files)
- [dot-mail PR 66](https://github.com/dotkernel/dot-mail/pull/66/files)
- [dot-mail PR 67](https://github.com/dotkernel/dot-mail/pull/67/files)
- [dot-mail PR 69](https://github.com/dotkernel/dot-mail/pull/69/files)
- [New mail.global.php.dist configuration file](https://github.com/dotkernel/dot-mail/blob/5.0/config/mail.global.php.dist)


<!-- ============================================================ -->
<!-- dotkernel/scientia-mobile-licensed-its-wurfl-cloud-php-library-to-dotkernel-1-6.md -->
<!-- ============================================================ -->

---
title: "Scientia Mobile licensed its Wurfl Cloud PHP library to Dotkernel 1.6"
description: "Dotkernel 1.6.0 removed the obsolete GPL'ed WURFL PHP library and replaced it with Scientia Mobile's WURFL Cloud PHP library, under a special license limited to use with the Dotkernel framework."
author: "admin"
date_published: "2012-05-25"
canonical_url: "https://www.dotkernel.com/dotkernel/scientia-mobile-licensed-its-wurfl-cloud-php-library-to-dotkernel-1-6/"
category: "Dotkernel"
language: "en"
---

# Scientia Mobile licensed its Wurfl Cloud PHP library to Dotkernel 1.6

## TL;DR

In Dotkernel 1.6.0, released on May 16th, 2012, the GPL'ed WURFL PHP library was removed because its code was obsolete and the XML file structure had changed. It was replaced by Scientia Mobile's WURFL Cloud PHP library, made available to Dotkernel under a special, restrictive license.

## What changed

- The GPL'ed WURFL PHP library was removed in Dotkernel 1.6.0 (released May 16th, 2012) because the code was obsolete and the structure of the XML file had changed.
- Scientia Mobile's WURFL Cloud PHP library was implemented instead.
- A future plan mentioned in the article was to create a template in the Wurfl Cloud API control panel at Scientia Mobile, ready to be used in Dotkernel implementations.
- Instructions on signing up for a free account and setting up an API key are covered in a separate article, "Detecting Mobile Devices in Dotkernel 1.6".

## License terms

Dotkernel received a special license for the WURFL Cloud PHP library, documented in `dotkernel/library/WurflCloud/LICENSE.txt`:

> License is non-transferable, conditioned, limited to the version received and to the use and distribution of this software only in connection with the Dotkernel software framework, and does not allow making derivative works even when the source code is provided or the language is an interpreted one and regardless of whether the code is not obfuscated.

## FAQ

**Q: Why was the WURFL PHP library removed from Dotkernel 1.6.0?**
A: In Dotkernel 1.6.0, released on May 16th, 2012, the GPL'ed WURFL PHP library was removed because the code was obsolete anyway and the structure of the XML file had changed.

**Q: What replaced the old WURFL PHP library?**
A: Dotkernel implemented Scientia Mobile's WURFL Cloud PHP library instead.

**Q: Where can I find instructions to set up the WURFL Cloud API key?**
A: Instructions on how to sign up for a free account and set up your API key are linked in the article, pointing to the "Detecting Mobile Devices in Dotkernel 1.6" article.

**Q: What are the terms of Dotkernel's special WURFL Cloud license?**
A: The license is non-transferable, conditioned, limited to the version received, and restricted to use and distribution only in connection with the Dotkernel software framework.
It does not allow making derivative works, even when source code is provided or the code is not obfuscated.

## Resources

- [Scientia Mobile](http://www.scientiamobile.com/)
- [Detecting Mobile Devices in Dotkernel 1.6](http://www.dotkernel.com/dotkernel/detecting-mobile-devices-in-dotkernel-1-6/)
- [dotkernel/library/WurflCloud/LICENSE.txt](http://websvn.dotkernel.net/filedetails.php?repname=Dotkernel&path=%2Ftrunk%2Flibrary%2FWurflCloud%2FLICENSE.txt)


<!-- ============================================================ -->
<!-- dotkernel/sending-emails-using-dot-email-component-and-zend-email.md -->
<!-- ============================================================ -->

---
title: "Sending emails using Dot_Email component and Zend_Email"
description: "Dot_Email extends Zend_Mail with two additional methods, setContent() and send(), and this article covers how to use it and which Zend_Mail methods are inherited."
author: "admin"
date_published: "2010-04-28"
canonical_url: "https://www.dotkernel.com/dotkernel/sending-emails-using-dot-email-component-and-zend-email/"
category: "Dotkernel"
language: "en"
---

# Sending emails using Dot_Email component and Zend_Email

## TL;DR

Dot_Email extends Zend_Mail, so all of Zend_Mail's methods are available in it.
Beyond its constructor, Dot_Email itself adds only two methods: setContent() and send().
To send an email you must always call addTo(), setSubject(), one of setBodyText()/setBodyHtml()/setContent(), and finally send().

## Dot_Email overview

Dot_Email is a simple class composed of only two methods (besides the constructor); every other method is inherited from Zend_Mail.

| Method | Description |
|---|---|
| `setContent($content, $format = 'text/plain')` | Sets the body of the email by calling `setBodyText()` if format is "text/plain", or `setBodyHtml()` if format is "text/html". |
| `send()` | Sets the transporter and calls the parent's `send()` method to send the email. |

## Sending an email

For sending the email you MUST use these methods:

```php
$dotEmail = new Dot_Email();
$dotEmail->addTo($email);
$dotEmail->setSubject('Forgot Password');
$dotEmail->setBodyText('Your password is '.$password);
$succeed = $dotEmail->send();
if($succeed)
{
    echo "Message sent!";
}
else
{
    echo "Message failed, not sent!";
}
```

Only if you want to overwrite the default Email and Name, add:

```php
$dotEmail->setFrom($fromEmail, $fromName);
$dotEmail->setReplyTo($fromEmail, $fromName);
```

**NOTE:** you always have to use addTo(), setSubject(), setBodyText() or setBodyHtml() or setContent(), and finally the send() method.

## Methods inherited from Zend_Mail

1. `setBodyText($txt, $charset=null, $encoding=Zend_Mime::ENCODING_QUOTEDPRINTABLE)`
2. `setBodyHtml($html, $charset=null, $encoding=Zend_Mime::ENCODING_QUOTEDPRINTABLE)`
3. `addTo($email, $name='')`
4. `addCc($email, $name='')`
5. `addBcc($email)`
6. `setFrom($email, $name = null)`
7. `setReplyTo($email, $name = null)`
8. `setReturnPath($email)`
9. `setSubject($subject)`
10. `addHeader($name, $value, $append = false)`

## FAQ

**Q: What is Dot_Email?**
A: Dot_Email is a class that extends Zend_Mail, so all methods from Zend_Mail are available in it.
Aside from its constructor, Dot_Email itself is composed of only two methods, with everything else inherited from Zend_Mail.

**Q: What are the two methods that Dot_Email adds on top of Zend_Mail?**
A: setContent($content, $format = 'text/plain') sets the body of the email by calling setBodyText() when the format is "text/plain" or setBodyHtml() when the format is "text/html". send() sets the transporter and calls the parent::send() method to send the email.

**Q: What is the minimal sequence of calls needed to send an email with Dot_Email?**
A: You must always use addTo(), setSubject(), and setBodyText() or setBodyHtml() or setContent(), and finally call send(), as shown in the article's example that creates a new Dot_Email, adds a recipient, sets the subject and body text, then sends it and checks the returned success value.

**Q: How do I override the default From and Reply-To addresses?**
A: Only if you want to overwrite the default Email and Name, add calls to setFrom($fromEmail, $fromName) and setReplyTo($fromEmail, $fromName).

**Q: Which Zend_Mail methods are inherited and usable through Dot_Email?**
A: Inherited methods listed in the article include setBodyText(), setBodyHtml(), addTo(), addCc(), addBcc(), setFrom(), setReplyTo(), setReturnPath(), setSubject(), and addHeader().


<!-- ============================================================ -->
<!-- dotkernel/templating-in-dotkernel3.md -->
<!-- ============================================================ -->

---
title: "Templating in Dotkernel3"
description: "Dotkernel3 replaces its 10-year-old templating engine with Twig, gaining layouts, loops, variables, and escaping while keeping the familiarity of HTML."
author: "Jesper"
date_published: "2017-12-20"
canonical_url: "https://www.dotkernel.com/dotkernel/templating-in-dotkernel3/"
category: "Dotkernel"
language: "en"
---

# Templating in Dotkernel3

## TL;DR

Dotkernel3 moved from its previous, 10-year-old templating engine to the popular Twig Templating Engine, gaining layouts, loops, variables, and escaping, while giving developers the familiarity of HTML with the overview and convenience of PHP.

## Why the switch was made

One of the pain points in the previous version of Dotkernel was the templating engine.
Although it was solid and robust, it was also 10 years old and used techniques that had become slightly outdated.

## What Twig brings to Dotkernel3

Templates can now be written as HTML code with extra Twig tags.
Twig is powerful and includes features such as:

- Layouts
- Loops
- Variables
- Escaping

The templating engine in Dotkernel3 gives the familiarity of HTML with the overview and convenience of PHP.

## FAQ

**Q: Which templating engine does Dotkernel3 use?**
A: Dotkernel3 moved to the popular Twig Templating Engine.

**Q: Why did Dotkernel move away from the previous templating engine?**
A: The previous templating engine, although solid and robust, was also 10 years old and used techniques that had become slightly outdated, and it was one of the pain points in the previous version of Dotkernel.

**Q: What features does Twig bring to Dotkernel3 templates?**
A: Templates can now be written as HTML code with extra Twig tags, and Twig includes features such as layouts, loops, variables, and escaping, giving the familiarity of HTML with the overview and convenience of PHP.

**Q: Where can I read the official Twig templating documentation for Dotkernel?**
A: The official documentation is available at [twig.symfony.com](https://twig.symfony.com/).

## Resources

- [Twig Templating Engine](https://twig.symfony.com/)


<!-- ============================================================ -->
<!-- dotkernel/test-article.md -->
<!-- ============================================================ -->

---
title: "Test article"
description: "This is a test article used for fixture and testing purposes."
author: "admin"
date_published: "2026-08-06"
canonical_url: "https://www.dotkernel.com/dotkernel/test-article/"
category: "Dotkernel"
language: "en"
---

# Test article

## TL;DR

This is a test article added to the dotkernel category for testing purposes. This article is now updated.

## Overview

This is a test article used for fixture and testing purposes.

## FAQ

**Q: What is this article for?**
A: This is a test article added to the Dotkernel category for fixture and testing purposes.


<!-- ============================================================ -->
<!-- dotkernel/using-dotkernel-with-composer-dependencies.md -->
<!-- ============================================================ -->

---
title: "Using Dotkernel with Composer Dependencies"
description: "How to use external Composer dependencies in Dotkernel, demonstrated by rendering a barcode with both the non-namespaced Zend Framework 1 and the namespaced Zend Framework 2."
author: "Gabi DJ"
date_published: "2016-04-04"
canonical_url: "https://www.dotkernel.com/dotkernel/using-dotkernel-with-composer-dependencies/"
category: "Dotkernel"
language: "en"
---

# Using Dotkernel with Composer Dependencies

## TL;DR

This article covers using external dependencies via Composer within Dotkernel applications.
Composer autoloads dependencies automatically, so there is no need to include/require them.
The example renders a Barcode using Zend Framework 1 (non-namespaced) and Zend Framework 2 (namespaced), and applies to any Dotkernel 1.x version running PHP greater than 5.4.0.

## The Composer Dependencies

The ZendFramework 1 Barcode module can only be loaded with ZF1 itself:

```shell
composer require 'zendframework/zendframework1'
```

The ZendFramework 2 Barcode module can be loaded separately:

```shell
composer require 'zendframework/zend-barcode'
```

## Important note

These dependencies can be used anywhere after the `Dot_Kernel::initialize()` function was called.

## Using Non-Namespaced Dependencies (Zend Framework 1)

The class is loaded [PSR-0](http://www.php-fig.org/psr/psr-0/) style, meaning the class name looks like `VendorName_PackageName_ClassName`:

```php
// Only the text to draw is required
$barcodeOptions = array('text' => 'ZEND-FRAMEWORK');

// No required options
$rendererOptions = array();

// Draw the barcode in a new image,
// send the headers and the image
Zend_Barcode::factory(
    'code39', 'image', $barcodeOptions, $rendererOptions
)->render();
```

## Using Namespaced Dependencies (Zend Framework 2)

The class is loaded [PSR-4](http://www.php-fig.org/psr/psr-4/) style, meaning the class name looks like `\VendorName\PackageName\ClassName`:

```php
use Zend\Barcode\Barcode;

// Only the text to draw is required
$barcodeOptions = array('text' => 'ZEND-FRAMEWORK');

// No required options
$rendererOptions = array();

// Draw the barcode in a new image,
// send the headers and the image
Barcode::factory(
    'code39', 'image', $barcodeOptions, $rendererOptions
)->render();
```

### The result

Both examples render the same barcode.

### Tip

The first (ZF1-style) example will work for both namespaced and non-namespaced dependencies if you add this as the first line:

```php
use Zend\Barcode\Barcode as Zend_Barcode;
```

You can then use any of the following to access ZF2's Barcode module:

- `Zend\Barcode\Barcode`
- `Barcode`
- `Zend_Barcode`

## Compatibility

This article works for any Dotkernel 1.x version if your server is running PHP greater than 5.4.0.

## FAQ

**Q: Do I need to manually include or require Composer dependencies in Dotkernel?**
A: No. Composer automatically loads dependencies, so there is no need to include or require them yourself.

**Q: What example does the article use to demonstrate Composer dependencies?**
A: The article renders a Barcode using Zend Framework 1 as the Non-Namespaced dependency (installed with `composer require 'zendframework/zendframework1'`) and Zend Framework 2 as the Namespaced dependency (installed with `composer require 'zendframework/zend-barcode'`).

**Q: When can these Composer dependencies be used in the application?**
A: These dependencies can be used anywhere after the Dot_Kernel::initialize() function has been called.

**Q: How are non-namespaced (Zend Framework 1) classes loaded compared to namespaced (Zend Framework 2) classes?**
A: Non-namespaced ZF1 classes are loaded PSR-0 style, meaning the class name looks like VendorName_PackageName_ClassName (e.g. Zend_Barcode).
Namespaced ZF2 classes are loaded PSR-4 style, meaning the class name looks like \VendorName\PackageName\ClassName (e.g. Zend\Barcode\Barcode).

**Q: Can the same code work for both namespaced and non-namespaced barcode dependencies?**
A: Yes.
If you add "use Zend\Barcode\Barcode as Zend_Barcode;" as the first line, the ZF1-style example will work for both, and you can then reference the module as Zend\Barcode\Barcode, Barcode, or Zend_Barcode.

**Q: What Dotkernel and PHP versions does this article apply to?**
A: This article works for any Dotkernel 1.x version if your server is running PHP greater than 5.4.0.

## Resources

- [Adding Composer support in your Dotkernel project](http://www.dotkernel.com/dotkernel/adding-composer-support-in-your-dotkernel-project)
- [Zend Framework 1 manual](http://framework.zend.com/manual/1.12/en/manual.html)
- [Zend Framework 2 manual](http://framework.zend.com/manual/current/en/index.html)
- [PSR-0](http://www.php-fig.org/psr/psr-0/)
- [PSR-4](http://www.php-fig.org/psr/psr-4/)
- [Zend Framework 1 - Rendering a barcode](http://framework.zend.com/manual/1.12/en/zend.barcode.creation.html#zend.barcode.creation.renderering)
- [Zend Framework 2 - Rendering a barcode](http://framework.zend.com/manual/current/en/modules/zend.barcode.creation.html#rendering-a-barcode)


<!-- ============================================================ -->
<!-- dotkernel/using-utf8-charset-in-dotkernel.md -->
<!-- ============================================================ -->

---
title: "Using UTF8 charset in Dotkernel"
description: "How to enable UTF8 encoding in a Dotkernel-based system, covering both database collation and the application.ini charset setting."
author: "admin"
date_published: "2012-04-07"
canonical_url: "https://www.dotkernel.com/dotkernel/using-utf8-charset-in-dotkernel/"
category: "Dotkernel"
language: "en"
---

# Using UTF8 charset in Dotkernel

## TL;DR

To use UTF8 encoding in a Dotkernel-based system, changes are needed in both the database structure and the application.ini file.
These changes were committed into the Dotkernel 1.6.0 dev codebase.

## Database

Set a proper collation for all tables and columns, either **utf8_general_ci** or **utf8_bin**.

## application.ini

Add the following line to your application.ini file, in the database area:

```ini
database.params.charset = utf8
```

## Differences between utf8_general_ci and utf8_bin

| Collation | Behavior |
|---|---|
| utf8_bin | Compares strings by the binary value of each character in the string |
| utf8_general_ci | Compares strings using general language rules and case-insensitive comparisons |

For example, the following evaluates as true with utf8_general_ci collation, but **not** with utf8_bin collation:

- Ä = A
- Ö = O
- Ü = U

These differences only happen at the **MySQL** level (for instance, in queries using the LIKE operator) and **not** at the **PHP** level (for instance, in `str_replace()` calls).

## FAQ

**Q: What needs to change to use UTF8 encoding in a Dotkernel-based system?**
A: Both the database structure and the application.ini file need changes: all tables and columns must have a proper UTF8 collation (utf8_general_ci or utf8_bin), and application.ini must load the utf8 charset.

**Q: What line should I add to application.ini to enable UTF8?**
A: Add the line `database.params.charset = utf8` to your application.ini file.

**Q: What is the difference between utf8_general_ci and utf8_bin collation?**
A: utf8_bin compares strings by the binary value of each character, while utf8_general_ci compares strings using general language rules with case-insensitive comparisons.
For example, Ä = A, Ö = O, and Ü = U evaluate as true under utf8_general_ci but not under utf8_bin.

**Q: Does the collation choice affect PHP string functions too?**
A: No. These collation differences only happen at the MySQL level, for instance in queries using the LIKE operator, and not at the PHP level, for instance in str_replace() calls.


<!-- ============================================================ -->
<!-- dotkernel/wurfl-cloud-integration-in-dotkernel-1-6-0.md -->
<!-- ============================================================ -->

---
title: "Wurfl Cloud Integration in Dotkernel 1.6.0"
description: "How WURFL Cloud, WURFL's cloud-based device detection service, was integrated as the default mobile detection method in Dotkernel 1.6.0."
author: "deddu"
date_published: "2012-05-18"
canonical_url: "https://www.dotkernel.com/dotkernel/wurfl-cloud-integration-in-dotkernel-1-6-0/"
category: "Dotkernel"
language: "en"
---

# Wurfl Cloud Integration in Dotkernel 1.6.0

## TL;DR

Dotkernel 1.6.0 integrates Wurfl Cloud, WURFL's (Wireless Universal Resource FiLe) new cloud-based way of delivering device detection services, as its default method for detecting mobile devices.

## Where to find it

The Wurfl Cloud library can be found in the library folder of Dotkernel.

## Quick steps to a functional device detection setup

1. Register for a Wurfl Cloud account [here](https://www.scientiamobile.com/register).
2. Choose **device_os** and **mobile_browser** as your capabilities.
3. Copy your API key into application.ini in Dotkernel:

```ini
resources.useragent.wurflcloud.api_key = 000000:XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
```

## Testing it

Change the user agent in your browser to a mobile device and access your project.
You should be redirected to the mobile module.

## FAQ

**Q: What is WURFL Cloud?**
A: WURFL Cloud is a new way that WURFL (Wireless Universal Resource FiLe) delivers its device detection services.
Dotkernel integrated it as the default detection method for mobile devices starting with version 1.6.0.

**Q: How do I get a functional device detection setup with WURFL Cloud?**
A: Register for a Wurfl Cloud account with Scientia Mobile, choose device_os and mobile_browser as your capabilities, then copy your API key into application.ini in Dotkernel.

**Q: What line do I add to application.ini for the API key?**
A: Add a line such as `resources.useragent.wurflcloud.api_key = 000000:XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX`, using your own API key.

**Q: How can I test that mobile detection is working?**
A: Change the user agent in your browser to a mobile device and access your project; you should be redirected to the mobile module.

## Resources

- Register for a Wurfl Cloud account: https://www.scientiamobile.com/register
- Related post - Detecting Mobile Devices in Dotkernel 1.6.0: http://www.dotkernel.com/?p=1465


<!-- ============================================================ -->
<!-- dotkernel/wurfl-php-api-license-incompatible-with-dotkernel.md -->
<!-- ============================================================ -->

---
title: "WURFL PHP API license incompatible with Dotkernel"
description: "The WURFL PHP API's license changed from GNU/GPL to AGPL in version 1.3.0, making it a trial-only library incompatible with keeping Dotkernel free."
author: "admin"
date_published: "2011-06-08"
canonical_url: "https://www.dotkernel.com/dotkernel/wurfl-php-api-license-incompatible-with-dotkernel/"
category: "Dotkernel"
language: "en"
---

# WURFL PHP API license incompatible with Dotkernel

## TL;DR

The WURFL PHP API was integrated into Dotkernel long ago under a GNU/GPL license, compatible with Zend Framework's new BSD license and Dotkernel's OSL 3.0 license.
On June 6th, 2011, WURFL PHP API version 1.3.0 changed its license to AGPL, turning it into a "trial only" library for product evaluation.
Dotkernel had updated to this version in the 1.5.0 release candidate without noticing the license change.

## What happened

We integrated the WURFL PHP API into the Dotkernel code base a long time ago.
At that time its license was GNU/GPL, perfectly compatible with the Zend Framework license (new BSD) and Dotkernel (OSL 3.0).
On June 6th, 2011, the WURFL PHP API library was updated to version 1.3.0, and Dotkernel followed suit in its 1.5.0 release candidate, without noticing that the license had changed from GNU/GPL to AGPL - suddenly turning it into a "trial only" library for "Product evaluation" only.

See the [official announcement](http://www.scientiamobile.com/site/page/view/products#licenses).

## What Dotkernel plans to do

We respect the work of Luca Passani and Steve Kamerman, but we must keep [Dotkernel Application Framework](http://www.dotkernel.com) free, without such license limitations.
The only things to do at this stage are:

- Remove WURFL PHP API library version 1.3.0 from the Dotkernel code base.
- Integrate back version 1.2.1, which is still GNU/GPL.
- Keep collecting device information and contributing to the WURFL XML data, which remains free - this data file is and must be the industry standard.
- Consider forking WURFL PHP API 1.2.1 to a new library.
- Consider changing the library's name to avoid trademark issues.

*Later edit: the correct link to the announcement is [here](http://tech.groups.yahoo.com/group/wmlprogramming/message/34031).*

## FAQ

**Q: Why did the WURFL PHP API license become incompatible with Dotkernel?**
A: The WURFL PHP API used to be licensed under GNU/GPL, compatible with both Zend Framework's new BSD license and Dotkernel's OSL 3.0 license.
On June 6th, 2011, version 1.3.0 of the library changed its license to AGPL, turning it into a trial-only library for product evaluation, which is incompatible with keeping Dotkernel free.

**Q: Which version introduced the license change, and when?**
A: Version 1.3.0 of the WURFL PHP API, released June 6th, 2011, changed the license from GNU/GPL to AGPL.
Dotkernel had updated to this version in its 1.5.0 release candidate without noticing the license change.

**Q: What did Dotkernel do in response to the license change?**
A: Dotkernel planned to remove WURFL PHP API version 1.3.0 from its codebase and reintegrate version 1.2.1, which was still GNU/GPL.
It also intended to keep contributing to the free WURFL XML data, and considered forking the 1.2.1 library and renaming it to avoid trademark issues.

## Resources

- Official announcement of the license change: http://www.scientiamobile.com/site/page/view/products#licenses
- Corrected announcement link: http://tech.groups.yahoo.com/group/wmlprogramming/message/34031
- Dotkernel Application Framework: http://www.dotkernel.com


<!-- ============================================================ -->
<!-- dotkernel/wurfl-zend-framework-integration-into-dotkernel.md -->
<!-- ============================================================ -->

---
title: "WURFL Zend Framework Integration into Dotkernel"
description: "Step-by-step tutorial on integrating WURFL into Dotkernel using the Zend_Http_UserAgent class from Zend Framework 1.11.0rc1."
author: "Teo"
date_published: "2010-10-27"
canonical_url: "https://www.dotkernel.com/dotkernel/wurfl-zend-framework-integration-into-dotkernel/"
category: "Dotkernel"
language: "en"
---

# WURFL Zend Framework Integration into Dotkernel

## TL;DR

[WURFL](http://wurfl.sourceforge.net/) is integrated into Dotkernel using the [Zend_Http_UserAgent](http://framework.zend.com/manual/1.11/en/zend.http.user-agent.html) class from [ZF 1.11.0rc1](http://framework.zend.com/download/latest) (the beta release at the time of the post).
This post walks through the required folders, config files, and code to wire it up.

## Installation steps

1. Download the [WURFL PHP API](http://sourceforge.net/projects/wurfl/files/WURFL%20PHP/1.1/wurfl-php-1.1.tar.gz/download) and unzip it into a folder named `wurfl-php-1.1`.
2. Create the following folders and make them writable by the web server:
   - `cache\wurfl\FILE_CACHE_PROVIDER`
   - `cache\wurfl\FILE_PERSISTENCE_PROVIDER`
3. In the `configs` folder:
   - Copy `wurfl-config.xml` from `wurfl-php-1.1\examples\resources`.
   - Rename `wurfl-config.xml` to `wurfl.xml`.
4. Edit the `configs\application.ini` file and add these lines:

```ini
resources.useragent.wurflapi.wurfl_api_version = "1.1"
resources.useragent.wurflapi.wurfl_lib_dir = APPLICATION_PATH "/library/Wurfl/"
resources.useragent.wurflapi.wurfl_config_file = APPLICATION_PATH "/configs/wurfl.xml"
```

5. Create the folder `externals\wurfl`, and copy the following files into it:
   - `wurfl-php-1.1\examples\resources\web_browsers_patch.xml`
   - `wurfl-php-1.1\examples\resources\wurfl-regression.zip`, renamed to `wurfl.zip` (or download the [latest wurfl zip](http://sourceforge.net/projects/wurfl/files/WURFL/) database and rename it `wurfl.zip`).
6. Copy the contents of the folder `wurfl-php-1.1\WURFL` to `library\Wurfl`.

## Using WURFL in Dotkernel

[WURFL](http://wurfl.sourceforge.net/) is integrated into Dotkernel in the mobile module.
To access WURFL configuration:

```php
$userAgent = new Zend_Http_UserAgent($config->resources->useragent);
$device = $userAgent->getDevice();
```

`$userAgent->getDevice()` returns all the relevant information about the current user agent (`$_SERVER`).

## FAQ

**Q: Which Zend Framework class is used to integrate WURFL into Dotkernel?**
A: WURFL is integrated using the Zend_Http_UserAgent class from Zend Framework 1.11.0rc1 (the beta release at the time of the post).

**Q: What is the first step to integrate WURFL into Dotkernel?**
A: Download the WURFL PHP API and unzip it into a folder named wurfl-php-1.1.

**Q: Which folders need to be created and made writable?**
A: Two folders must be created and made writable by the web server: cache/wurfl/FILE_CACHE_PROVIDER and cache/wurfl/FILE_PERSISTENCE_PROVIDER.

**Q: What needs to be added to application.ini?**
A: Three lines need to be added: resources.useragent.wurflapi.wurfl_api_version = "1.1", resources.useragent.wurflapi.wurfl_lib_dir pointing to APPLICATION_PATH "/library/Wurfl/", and resources.useragent.wurflapi.wurfl_config_file pointing to APPLICATION_PATH "/configs/wurfl.xml".

**Q: How do you access WURFL configuration in code?**
A: Instantiate a Zend_Http_UserAgent with the useragent config, then call getDevice() on it. getDevice() returns all the relevant information about the current user agent.

## Resources

- WURFL: http://wurfl.sourceforge.net/
- Zend_Http_UserAgent manual: http://framework.zend.com/manual/1.11/en/zend.http.user-agent.html
- Zend Framework latest download: http://framework.zend.com/download/latest
- WURFL PHP API 1.1 download: http://sourceforge.net/projects/wurfl/files/WURFL%20PHP/1.1/wurfl-php-1.1.tar.gz/download
- Latest WURFL zip database: http://sourceforge.net/projects/wurfl/files/WURFL/


<!-- ============================================================ -->
<!-- dotkernel/zend-auth-and-zend-acl-integrated-in-dotkernel.md -->
<!-- ============================================================ -->

---
title: "Zend_Auth and Zend_Acl integrated in Dotkernel"
description: "How Zend_Auth and Zend_Acl were integrated into Dotkernel 1.5.0 through the Dot_Auth and Dot_Acl classes for user authentication and access control."
author: "Teo"
date_published: "2011-06-16"
canonical_url: "https://www.dotkernel.com/dotkernel/zend-auth-and-zend-acl-integrated-in-dotkernel/"
category: "Dotkernel"
language: "en"
---

# Zend_Auth and Zend_Acl integrated in Dotkernel

## TL;DR

[Zend_Auth](http://framework.zend.com/manual/en/zend.auth.html) and [Zend_Acl](http://framework.zend.com/manual/en/zend.acl.html) have been integrated into Dotkernel starting with version 1.5.0.
The User and Admin models were completely refactored using the new `Dot_Auth` and `Dot_Acl` classes for authentication and access control.

## Dot_Auth

The `Dot_Auth` class authenticates the user by checking the database, using `Zend_Auth_Adapter_DbTable`:

```php
private function _getAuthAdapter($who)
    {
        $dbAdapter = Zend_Registry::get('database');
        $authAdapter = new Zend_Auth_Adapter_DbTable($dbAdapter);
        $authAdapter->setTableName($who)
            ->setIdentityColumn('username')
            ->setCredentialColumn('password');
        return $authAdapter;
    }
```

## ACL roles and resources

ACL roles (user types) and permissions are configured in the `configs/acl/role.xml` file.
In Dotkernel there are 3 roles: `guest`, `user`, and `admin`.
The resources for ACL are taken from `configs/router.xml` - see the `controllers` tag.

## Dot_Acl

The `Dot_Acl` class:

- Controls user access (ACL - Access Controller Layer).
- Is used for setting and checking the permissions of a user.
- Uses Zend_Acl for checking if a role (user) has access to a resource (controller).

```php
// instantiate Zend_Acl
$this->acl = new Zend_Acl();
```

```php
public function isAllowed($role)
    {
        $resource = $this->requestControllerProcessed;
        $privillege = $this->requestAction;
        if(!$this->acl->has($resource))
        {
            return FALSE;
        }
        else
        {
            return $this->acl->isAllowed($role, $resource, $privillege);
        }
    }
```

`Dot_Auth` calls the `isAllowed` method from `Dot_Acl` which authenticates the user.
`IndexController.php` calls `Dot_Auth`:

```php
$dotAuth = Dot_Auth::getInstance();
$dotAuth->checkIdentity('user');
```

## FAQ

**Q: When were Zend_Auth and Zend_Acl integrated into Dotkernel?**
A: Zend_Auth and Zend_Acl were integrated starting with Dotkernel version 1.5.0, as part of a refactor of the User and Admin models using the new Dot_Auth and Dot_Acl classes.

**Q: How does Dot_Auth authenticate a user?**
A: Dot_Auth authenticates the user by checking the database using Zend_Auth_Adapter_DbTable, setting the table name, the identity column to username, and the credential column to password.

**Q: What roles exist for ACL in Dotkernel?**
A: Dotkernel defines 3 ACL roles (user types): guest, user, and admin.
These roles and their permissions are configured in the configs/acl/role.xml file.

**Q: Where do the ACL resources come from?**
A: The resources for ACL are taken from configs/router.xml, specifically the controllers tag.

**Q: What does the Dot_Acl class do?**
A: Dot_Acl controls user access (Access Controller Layer), is used for setting and checking a user's permissions, and uses Zend_Acl to check whether a role has access to a resource.
Dot_Auth calls the isAllowed method from Dot_Acl to authenticate the user.

## Resources

- Zend_Auth manual: http://framework.zend.com/manual/en/zend.auth.html
- Zend_Acl manual: http://framework.zend.com/manual/en/zend.acl.html


<!-- ============================================================ -->
<!-- dotkernel/zend-console-implementation-in-dotkernel.md -->
<!-- ============================================================ -->

---
title: "Zend_Console implementation in Dotkernel"
description: "How Dotkernel's Console bootstrap lets you run PHP scripts from the command line, including its arguments and bundled example actions."
author: "Adrian"
date_published: "2011-10-13"
canonical_url: "https://www.dotkernel.com/dotkernel/zend-console-implementation-in-dotkernel/"
category: "Dotkernel"
language: "en"
---

# Zend_Console implementation in Dotkernel

## TL;DR

Starting with version 1.5, Dotkernel has a Console bootstrap to easily run PHP scripts from the command line.
The most common use for this is running cron jobs without using wget or going through Apache.

## Where it lives

The bootstrap can be found in `Console/index.php`, and it has one controller in `Controller.php` with two example actions.

## Usage

There are two command line arguments:

| Argument | Meaning |
|---|---|
| `-a` | The name of the action that will be executed |
| `-e` | The environment, as defined in application.ini. Possible values are development, staging, and production. Optional, defaults to production |

Any other arguments set when calling the script will be available in the controller in the `$registry->arguments` array.

The controller bundled with Dotkernel has two example actions: `count-users`, which demonstrates how to interact with models, and `send-newsletter`, which reads the newsletter from the command line.

## Examples

```shell
/var/www/vhosts/example.com/httpdocs/Cron/index.php -e staging -a count-users
```

```shell
/var/www/vhosts/example.com/httpdocs/Cron/index.php -e staging -a send-newsletter "test newsletter"
```

## FAQ

**Q: What is the purpose of the Console bootstrap in Dotkernel?**
A: Starting with version 1.5, Dotkernel has a Console bootstrap to easily run PHP scripts from the command line, most commonly used to run cron jobs without using wget or going through Apache.

**Q: Where is the Console bootstrap located?**
A: The bootstrap is found in Console/index.php, and it has one controller in Controller.php with two example actions.

**Q: What command line arguments does the Console bootstrap support?**
A: There are two arguments: -a, the name of the action to execute, and -e, the environment as defined in application.ini (development, staging, or production), which is optional and defaults to production.

**Q: What happens to extra arguments passed to the script?**
A: Any other arguments set when calling the script will be available in the controller in the registry's arguments array.

**Q: What example actions are bundled with the Console controller?**
A: The bundled controller has two example actions: count-users, which demonstrates how to interact with models, and send-newsletter, which reads the newsletter from the command line.


<!-- ============================================================ -->
<!-- dotkernel/zend-framework-dropped-integration-of-wurfl-adapter.md -->
<!-- ============================================================ -->

---
title: "Zend Framework dropped integration of WURFL adapter"
description: "Zend Framework 1.12.0 drops the WURFL adapter from Zend_Http_UserAgent due to WURFL's licensing change to AGPL; Dotkernel is unaffected since it uses its own WURFL adapter."
author: "admin"
date_published: "2012-03-22"
canonical_url: "https://www.dotkernel.com/dotkernel/zend-framework-dropped-integration-of-wurfl-adapter/"
category: "Dotkernel"
language: "en"
---

# Zend Framework dropped integration of WURFL adapter

## What happened

According to Matthew Weier O'Phinney, Zend Framework Project Leader, the WURFL adapter will be dropped from `Zend_Http_UserAgent` in the next release of ZF, the 1.12.0 branch:

> due to a change in licensing by the WURFL project -- the free version is now AGPL -- we're dropping the WURFL adapter from Zend_Http_UserAgent.
> In discussions with Zend and the CR Team, we feel the AGPL raises too many concerns for end users with regards to how their products must be licensed in order to comply.
> (This is a similar rationale as to why we did not consider ExtJS when looking at JS toolkits to partner with.)
>
> As such, if you relied on the WURFL adapter in the past, you _will_ need to change code when upgrading to ZF 1.12.0, or grab the WURFL adapter from a previous version.

So it's a good moment to check old or current projects, and proceed accordingly.

## Impact on Dotkernel

Dotkernel framework uses its own WURFL adapter, so this change will not affect projects built with it.

## FAQ

**Q: Why did Zend Framework drop the WURFL adapter?**
A: According to Matthew Weier O'Phinney, Zend Framework Project Leader, the WURFL adapter was dropped from Zend_Http_UserAgent in the upcoming 1.12.0 branch due to a change in licensing by the WURFL project: the free version became AGPL, which raised too many concerns for end users regarding how their products must be licensed to comply.

**Q: Does this change affect projects built with Dotkernel?**
A: No. Dotkernel uses its own WURFL adapter, so the removal of the WURFL adapter from Zend_Http_UserAgent in ZF 1.12.0 will not affect projects built with Dotkernel.


<!-- ============================================================ -->
<!-- dotkernel/zend-registry-usage-in-dotkernel.md -->
<!-- ============================================================ -->

---
title: "Zend Registry usage in Dotkernel"
description: "The variables stored in Zend_Registry in Dotkernel and how to read them, either as a full instance or one value at a time."
author: "Adrian"
date_published: "2011-06-01"
canonical_url: "https://www.dotkernel.com/dotkernel/zend-registry-usage-in-dotkernel/"
category: "Dotkernel"
language: "en"
---

# Zend Registry usage in Dotkernel

## TL;DR

In Dotkernel, `Zend_Registry` holds a fixed set of request-scoped variables - from timing and configuration to the database adapter and session object - and can be read either as a full instance or one value at a time.

## Variables stored in Zend_Registry

| Variable | Contents |
|---|---|
| `startTime` | The result of [microtime()](http://php.net/manual/en/function.microtime.php) at the beginning of the request |
| `configuration` | The configuration options loaded from `configs/application.ini` |
| `router` | Routing settings loaded from `configs/router.xml` |
| `database` | The database adapter |
| `settings` | The settings loaded from the database |
| `requestModule, requestController, requestAction` | The module, controller, and action of the current request |
| `request` | Additional request variables |
| `seo` | SEO information loaded from `configs/dots/seo.xml` (site name, default description, keywords, etc.) |
| `option` | The options for the current dot loaded from `configs/dots/<moduleName>.xml` |
| `session` | The session object |

## Reading values from the registry

To use the variables in the registry, first get an instance of the registry object:

```php
$registry = Zend_Registry::getInstance();
//...
echo $registry->startTime;
//...
echo $registry->requestAction;
```

Or, if you only need one variable, get it directly:

```php
$action = Zend_Registry::get('requestAction');
```

## FAQ

**Q: What variables does Zend_Registry contain in Dotkernel?**
A: It contains startTime (the result of microtime() at the beginning of the request), configuration (loaded from configs/application.ini), router (loaded from configs/router.xml), database (the database adapter), settings (loaded from the database), requestModule/requestController/requestAction, request (additional request variables), seo (loaded from configs/dots/seo.xml), option (loaded from configs/dots/<moduleName>.xml), and session (the session object).

**Q: How do you get an instance of the registry?**
A: Use `$registry = Zend_Registry::getInstance();` and then access variables such as `$registry->startTime` or `$registry->requestAction`.

**Q: How do you retrieve just one variable from the registry?**
A: If you only need one variable, you can get it directly using `$action = Zend_Registry::get('requestAction');`.

**Q: What does the "seo" entry in the registry contain?**
A: It contains seo information loaded from configs/dots/seo.xml, such as site name, default description, and keywords.

## Resources

- microtime() PHP manual: http://php.net/manual/en/function.microtime.php
- Zend Framework Documentation on Zend_Registry: http://framework.zend.com/manual/en/zend.registry.using.html


<!-- ============================================================ -->
<!-- dotkernel/zend-session-usage-in-dotkernel-refactor-of-dot-session-class.md -->
<!-- ============================================================ -->

---
title: "Zend_Session usage in Dotkernel - Refactor of Dot_Session class"
description: "A session cookie bug found in IE8/IE9 on Dotkernel 1.5.0, traced to redundant regenerateID()/rememberMe() calls in Dot_Session, and the fix shipped in 1.5.1."
author: "admin"
date_published: "2011-07-28"
canonical_url: "https://www.dotkernel.com/dotkernel/zend-session-usage-in-dotkernel-refactor-of-dot-session-class/"
category: "Dotkernel"
language: "en"
---

# Zend_Session usage in Dotkernel - Refactor of Dot_Session class

## TL;DR

A strange session bug was found on a project running Dotkernel 1.5.0: in IE8 and IE9, the session cookie was sometimes not saved, forcing repeated logins.
Investigation traced it to the `Dot_Session` class calling both `regenerateID()` and `rememberMe()` unnecessarily, generating the session cookie 3 times.
The fix, shipped in Dotkernel 1.5.1, removed the `regenerateID()` call and added two new application.ini settings.

## The bug

We found a strange behaviour of sessions in one of our projects, running Dotkernel version 1.5.0 - similar to [one described here](http://trac.elgg.org/ticket/2677).
In unknown circumstances, and only in IE 8 and IE9, the session cookie is not saved on the client machine, and the user needs to log in over and over again.
It was reproduced once on the staging server, and the only way to fix it at the time was to open a new tab with the same page.

## The investigation

Investigating the `Dot_Session` class showed that the session cookie is generated **3 times**.
See this [bug report](http://www.dotkernel.net/view.php?id=184).

The code used both **regenerateID()** and **rememberMe()** methods of Zend_Session, which is **not necessary**.
Quote from the [ZF documentation](http://framework.zend.com/manual/1.11/en/zend.session.global_session_management.html):

> If you call the rememberMe() function, then don't use regenerateId(), since the former calls the latter.
> If a user has successfully logged into your website, use rememberMe() instead of regenerateId().

## The fix

The **regenerateID()** call was removed, and 2 new settings were added in application.ini related to session:

- **use_only_cookies** - must be **ON** at all times in order to avoid session fixation.
- **remember_me_seconds**.

These bug fixes were included in the new Dotkernel version 1.5.1.

## Tip

If you encounter the same issue in IE8 and IE9, then with all regret, you need to deactivate the **rememberMe()** and **regenerateId()** methods calls.

## FAQ

**Q: What session bug was found in Dotkernel 1.5.0?**
A: In unknown circumstances, and only in IE8 and IE9, the session cookie was not saved on the client machine, forcing the user to log in over and over again.
The only workaround found was to open a new tab with the same page.

**Q: What caused the session cookie to be generated multiple times?**
A: Investigation of the Dot_Session class showed the session cookie was generated 3 times, because the code called both regenerateID() and rememberMe() methods of Zend_Session.
According to the Zend Framework documentation, this is unnecessary: if you call rememberMe(), you should not also call regenerateId(), since rememberMe() already calls it internally.

**Q: What was the fix, and where was it released?**
A: The regenerateID() call was removed, and two new application.ini settings were added: use_only_cookies, which must be ON at all times to avoid session fixation, and remember_me_seconds.
These fixes were included in Dotkernel version 1.5.1.

**Q: What should I do if I still see this issue in IE8/IE9?**
A: If you encounter the same issue in IE8 and IE9, the tip given is to deactivate the rememberMe() and regenerateId() method calls.

## Resources

- Similar issue described on Elgg: http://trac.elgg.org/ticket/2677
- Dotkernel bug report: http://www.dotkernel.net/view.php?id=184
- Zend Framework documentation on global session management: http://framework.zend.com/manual/1.11/en/zend.session.global_session_management.html


<!-- ============================================================ -->
<!-- dotkernel/zend-studio-php-formatter-file-for-dotkernel-coding-standard.md -->
<!-- ============================================================ -->

---
title: "Zend Studio PHP Formatter file for Dotkernel coding standard."
description: "A downloadable XML file for Zend Studio 9.x that configures the PHP code formatter to follow Dotkernel's coding standard."
author: "admin"
date_published: "2012-03-02"
canonical_url: "https://www.dotkernel.com/dotkernel/zend-studio-php-formatter-file-for-dotkernel-coding-standard/"
category: "Dotkernel"
language: "en"
---

# Zend Studio PHP Formatter file for Dotkernel coding standard.

An XML file is provided for download, ready to be imported into Zend Studio, version 9.x.
This file follows Dotkernel's coding standard.

## Installation steps

1. Unzip the file.
2. Go to Zend Studio -> Preferences -> PHP -> Code Style -> Formatter.
3. Import the XML file.

## FAQ

**Q: What is this file for?**
A: It is an XML file, downloadable from the linked page, that can be imported into Zend Studio (version 9.x) to set up the PHP code formatter so it follows Dotkernel's coding standard.

**Q: How do I import the formatter file into Zend Studio?**
A: Unzip the downloaded file, then in Zend Studio go to Preferences -> PHP -> Code Style -> Formatter and import the XML file.

## Resources

- [Dotkernel PHP Formatter download](http://www.dotkernel.com/download/?did=34)


<!-- ============================================================ -->
<!-- dotkernel3/development-report-december-11-2017.md -->
<!-- ============================================================ -->

---
title: "Development Report December 11, 2017"
description: "A short Dotkernel3 documentation update covering new release notes, a Webpack tutorial, and revised API endpoint documentation guidelines."
author: "Gabi DJ"
date_published: "2017-12-15"
canonical_url: "https://www.dotkernel.com/dotkernel3/development-report-december-11-2017/"
category: "Dotkernel 3"
language: "en"
---

# Development Report December 11, 2017

## TL;DR

This report covers updates to the Dotkernel3 documentation: new release notes for the frontend and admin, a Webpack tutorial added to the Prerequisites section, and revisions to the Api Endpoint Documentation Guidelines.
Contributor JapSeyz is thanked for this round of updates.

## Documentation Updates

This report contains updates about the Dotkernel3 documentation.

We have added the release notes for Dotkernel3 frontend and admin: you can now check the Release Notes page.

A Webpack tutorial has been added in the Prerequisites section.

The Api Endpoint Documentation Guidelines were updated as well, a slightly different layout and some corrections were applied.

## Contributors

Thanks to our contributors:

[JapSeyz](https://github.com/JapSeyz)

## FAQ

**Q: What documentation updates does this report cover?**
A: Release notes were added for Dotkernel3 frontend and admin, a Webpack tutorial was added to the Prerequisites section, and the Api Endpoint Documentation Guidelines were updated with a slightly different layout and some corrections.

**Q: Who was credited as a contributor in this report?**
A: JapSeyz was thanked as a contributor.


<!-- ============================================================ -->
<!-- dotkernel3/dotkernel-admin-v4.md -->
<!-- ============================================================ -->

---
title: "Dotkernel Admin V4"
description: "An overview of Dotkernel Admin V4, released 19 July 2022 on Mezzio, covering its demo credentials and key features: PHP 8.1 support, configurability, authorization guards, CLI commands, routing, and its Bootstrap-based frontend."
author: "kakapiciu"
date_published: "2022-07-27"
canonical_url: "https://www.dotkernel.com/dotkernel3/dotkernel-admin-v4/"
category: "Dotkernel 3"
language: "en"
---

# Dotkernel Admin V4

## TL;DR

Dotkernel Admin V4, officially released on 19 July 2022, is Dotkernel's PSR-7 Admin application built on Mezzio for managing and displaying tabular data from one or more databases.
It supports PHP 8.1 (minimum PHP 7.4), offers a config-driven module/middleware/route setup, RBAC-based authorization guards, a Symfony Console-based CLI with a file locker, per-module routing via RoutesDelegator, and a Bootstrap 4.5.0 / Fontawesome 5.0.6 frontend using Bootstrap Table for data listing.

## Getting Started with Dotkernel Admin V4

Dotkernel's PSR-7 Admin is an application based on Mezzio, with the main purpose of managing and displaying tabular data from one or more databases components.

On 19 July 2022, Dotkernel Admin V4 has been officially released.
Dotkernel Admin V4 comes with various interesting features and overall improvement of the core framework.

## Demo

Ready to try it out?

There should be an admin account with the following credentials:

- Username: admin
- Password: dotadmin

Head over to [https://admin7.dotkernel.net/](https://admin7.dotkernel.net/) and see for yourself.

## Dotkernel Admin V4 Features

### PHP 8.1

Dotkernel Admin V4 fully supports PHP 8.1 with a minimum requirement of PHP 7.4.

### Configurability

From managing middleware order to simply adding an API key to your application, the config directory is the way to go.

Want to register a new module? In `config.php` you will find the right place for it, registering its `ConfigProvider.php`.
Got a shiny new middleware? You can put it with the rest of them in `pipeline.php`, where you can even edit in which order they should run.

You can further customize your app within the autoload directory by changing the application name and URL in `app.global.php`, adding freshly created routes into `navigation.global.php`, and much more.

Example adding a simple route to the navigation bar:

```php
[
    'options' => [
        'label' => 'Dashboard',
        'route' => [
            'route_name' => 'dashboard',
        ],
        'icon' => 'fas fa-tachometer-alt',
    ]
]
```

Or a group of 2 or more routes:

```php
[
    'options' => [
        'label' => 'Manage admins',
        'route' => '',
        'icon' => 'fas fa-user-circle',
    ],
    'pages' => [
        [
            'options' => [
                'label' => 'Admins',
                'uri' => '/admin/manage',
                'icon' => 'fas fa-user-circle',
            ],
        ],
        [
            'options' => [
                'label' => 'Logins',
                'uri' => '/admin/logins',
                'icon' => 'fas fa-sign-in-alt',
            ],
        ]
    ]
]
```

### Authorization Guards

The packages responsible for restricting access to certain parts of the application are [dot-rbac-guard](https://github.com/dotkernel/dot-rbac-guard) and [dot-rbac](https://github.com/dotkernel/dot-rbac).
These packages work together to create an infrastructure that is customizable and diversified to manage user access to the platform by specifying the type of role the user has.

The `authorization.global.php` file provides multiple configurations specifying multiple roles as well as the types of permissions to which these roles have access.

```php
//example of a flat RBAC model that specifies two types of roles as well as their permission
'roles' => [
    'superuser' => [
        'permissions' => [
            'authenticated',
            'edit',
            'delete',
            //etc..
        ]
    ],
    'admin' => [
        'permissions' => [
            'authenticated',
            //etc..
        ]
    ]
]
```

The `authorization-guards.global.php` file provides configuration to restrict access to certain actions based on the permissions defined in `authorization.global.php`, so basically the permissions have to be added in the dot-rbac configuration file first to specify the action restriction permissions.

```php
//example of configuration to restrict certain actions of some routes based on the permissions specified in the dot-rbac configuration file
'rules' => [
    [
        'route' => 'account',
        'actions' => [
            //list of actions to apply, or empty array for all actions
            'unregister',
            'avatar',
            'details',
            'changePassword'
        ],
        'permissions' => [
            'authenticated'
        ]
    ],
    [
        'route' => 'admin',
        'actions' => [
            'deleteAccount'
        ],
        'permissions' => [
            'delete'
            //list of roles to allow
        ]
    ]
]
```

### CLI

For registering a new command, first make sure your command class extends `Symfony\Component\Console\Command\Command`, then you can enable the command by registering it in `config/autoload/cli.global.php`.

Here you will also find the brand new file locker configuration, so you can easily turn it on or off (by default: `'enabled' => true`).

Note: the File Locker System will create a `command-{command-default-name}.lock` file which will not let another instance of the same command run until the previous one has finished.

You can list the existing commands by running the following in a terminal:

```bash
php /bin/cli.php list
```

Note: you can take as example `Dot\Cli\Command\DemoCommand`.

### Routing

Each module gets a `RoutesDelegator.php` file for managing existing routes inside that specific module, providing an easy way of adding new ones by specifying the route path, the middleware that the route will use, an array of accepted methods, and the route name.

```php
$app->route(
    '/admin[/{action}[/{uuid}]]',
    AdminController::class,
    [
        RequestMethodInterface::METHOD_GET,
        RequestMethodInterface::METHOD_POST
    ],
    'admin'
 );
```

Note: the optional attributes on the route path are marked between `[]`.

### Frontend

As for the frontend toolkit, we chose to use Bootstrap 4.5.0 in combination with Fontawesome 5.0.6 for a minimalist but efficient design.

For assembling `app.js` and `app.css` along with handling packages from `package.json`, we recommend using npm 7 or up.

Our choice for listing raw data was Bootstrap Table because it is easy to implement and configurable in many ways.

Let's take the admin table as an example:

```html
<table data-toggle="table" data-url="/admin/list" data-click-to-select="true"
       data-mobile-responsive="true" data-min-width="800"
       data-check-on-init="true" data-id-field="uuid"
       data-show-refresh="true" data-show-toggle="true" data-show-columns="true"
       data-search="true" data-pagination="true" data-toolbar="#tableToolbar"
       data-silent-sort="false" data-pagination-loop="false"
       data-side-pagination="server" data-page-list="[10, 30, 50, 100, 200]"
       data-page-size="30" data-single-select="true"
       data-sort-name="created" data-sort-order="desc" id="bsTable">
           <thead>
                <tr>
                     <th data-field="checked" data-checkbox="true">Id</th>
                     <th data-field="identity" data-sortable="true">Identity</th>
                     <th data-field="firstName" data-sortable="true">First Name</th>
                     <th data-field="lastName" data-sortable="true">Last Name</th>
                     <th data-field="roles" data-sortable="false">Roles</th>
                     <th data-field="status" data-sortable="false">Status</th>
                     <th data-field="created" data-sortable="true">Created</th>
                </tr>
           </thead>
</table>
```

Here we can tweak directly in the table data how our table looks, arrange the page, and use a couple of other features like the API URL for pulling data, pagination, allowing multiple row selection, and more.

Note: you'll find in the `#tableToolbar` buttons that toggle a modal for adding/editing/deleting admins.

## FAQ

**Q: When was Dotkernel Admin V4 released, and what is it built on?**
A: Dotkernel Admin V4 was officially released on 19 July 2022. It's Dotkernel's PSR-7 Admin, an application based on Mezzio, mainly for managing and displaying tabular data from one or more database components.

**Q: What are the demo credentials for trying out Dotkernel Admin V4?**
A: Username admin and password dotadmin, on the demo at https://admin7.dotkernel.net/.

**Q: What PHP version does Dotkernel Admin V4 support?**
A: Full support for PHP 8.1, with a minimum requirement of PHP 7.4.

**Q: How do you register a new module or middleware?**
A: Register a module by adding its ConfigProvider.php in config.php. New middleware goes into pipeline.php, where you can also edit the order in which middleware runs.

**Q: What packages provide the authorization guards?**
A: dot-rbac-guard and dot-rbac work together to restrict access based on user role. authorization.global.php defines roles and their permissions, while authorization-guards.global.php restricts specific actions to those permissions.

**Q: What frontend toolkit does Dotkernel Admin V4 use for displaying tables?**
A: Bootstrap 4.5.0 combined with Fontawesome 5.0.6 for the overall design, and Bootstrap Table specifically for listing raw data because it's easy to implement and configurable in many ways.


<!-- ============================================================ -->
<!-- dotkernel3/dotkernel-admin-version-3-launched.md -->
<!-- ============================================================ -->

---
title: "Dotkernel Admin version 3 launched"
description: "Announcement of Dotkernel Admin version 3, a Bootstrap and Doctrine based admin panel built on Mezzio, including its GitHub source, live demo, and version 3 changelog requirements."
author: "admin"
date_published: "2020-07-30"
canonical_url: "https://www.dotkernel.com/dotkernel3/dotkernel-admin-version-3-launched/"
category: "Dotkernel 3"
language: "en"
---

# Dotkernel Admin version 3 launched

## TL;DR

Dotkernel Admin version 3 has launched as a basic admin panel built on Bootstrap ^4.5.0 and Doctrine, performing CRUD operations over a database on top of the Mezzio microframework and Laminas components.
The source is available on GitHub, with a live demo running at admin7.dotkernel.net.
Branch 3.0 is now the default branch, requiring Mezzio ^3.2, PHP ^7.4, Doctrine 2.7.x, Twig 3.x, and Bootstrap 4.5, with dot-* packages limited to version 3.x and above.

## Dotkernel Admin PHP Application Version 3 Was Launched

Dotkernel is a collection of PSR-7 Middleware applications built on top of the [Mezzio microframework and using Laminas components](https://getlaminas.org/).
Dotkernel Admin is a basic admin panel, based on Bootstrap ^4.5.0, using Doctrine and performing basic CRUD operations over a database.
You can clone it from [GitHub](https://github.com/dotkernel/admin).
Live demo: [admin7.dotkernel.net](https://admin7.dotkernel.net)

### Changelog

Branch 3.0 is the current and default branch, and:

- Require Mezzio ^3.2
- Require PHP ^7.4
- Require Doctrine 2.7.x
- Require Twig 3.x
- Require Bootstrap 4.5
- Limited dot-* packages to version 3.x and above

## FAQ

**Q: What is Dotkernel Admin?**
A: A basic admin panel based on Bootstrap ^4.5.0, using Doctrine to perform basic CRUD operations over a database, built as a collection of PSR-7 Middleware applications on top of Mezzio and Laminas components.

**Q: Where can you see a live demo of version 3?**
A: At admin7.dotkernel.net.

**Q: What are the core requirements listed in the version 3 changelog?**
A: Mezzio ^3.2, PHP ^7.4, Doctrine 2.7.x, and Twig 3.x, plus Bootstrap 4.5, with dot-* packages limited to version 3.x and above.


<!-- ============================================================ -->
<!-- dotkernel3/dotkernel-api-architecture-and-components.md -->
<!-- ============================================================ -->

---
title: "Dotkernel API: architecture and components"
description: "An overview of Dotkernel API's architecture and core components, covering Doctrine ORM, documentation, HAL, CORS, OAuth 2.0, email, configuration, routing, commands, the file locker, PSR standards, and testing."
author: "kakapiciu"
date_published: "2023-03-29"
canonical_url: "https://www.dotkernel.com/dotkernel3/dotkernel-api-architecture-and-components/"
category: "Dotkernel 3"
language: "en"
---

# Dotkernel API: architecture and components

## TL;DR

Dotkernel API is built on the Mezzio microframework and Laminas components, based on Enrico Zimuel's Zend Expressive API skeleton and implementing PSR-3, PSR-4, PSR-7, PSR-11, and PSR-15.
Its core components include Doctrine ORM for persistence, mezzio-hal for API payloads, mezzio-cors for CORS handling, and mezzio-authentication-oauth2 for OAuth 2.0 authentication, alongside Postman-based documentation, configurable routing and commands, a file locker system, and a factory-made test suite.

> This article refers to Dotkernel API v5. Checkout out the new additions for [Dotkernel API v6](https://www.dotkernel.com/headless-platform/dotkernel-api-v6-the-root-of-dotkernel-headless-platform/) to stay up-to-date.

Based on Enrico Zimuel's [Zend Expressive API - Skeleton example](https://github.com/ezimuel/zend-expressive-api), Dotkernel API runs on [Mezzio](https://github.com/mezzio) microframework and [Laminas](https://github.com/laminas) components and implements standards like PSR-3, PSR-4, PSR-7, PSR-11 and PSR-15.
Here is a list of the core components:

- Mezzio Microframework ([mezzio/mezzio](https://github.com/mezzio/mezzio))
- Error Handler ([dotkernel/dot-errorhandler](https://packagist.org/packages/dotkernel/dot-errorhandler))
- Problem Details ([mezzio/mezzio-problem-details](https://docs.mezzio.dev/mezzio-problem-details/))
- CORS ([mezzio/mezzio-cors](https://docs.mezzio.dev/mezzio-cors/))
- Routing ([mezzio/mezzio-fastroute](https://github.com/mezzio/mezzio-fastroute))
- Authentication ([mezzio/mezzio-authentication](https://docs.mezzio.dev/mezzio-authentication/))
- Authorization ([mezzio/mezzio-authorization](https://docs.mezzio.dev/mezzio-authorization/))
- Config Aggregator ([laminas/laminas-config-aggregator](https://github.com/laminas/laminas-config-aggregator))
- Container ([roave/psr-container-doctrine](https://github.com/Roave/psr-container-doctrine))
- Annotations ([dotkernel/dot-annotated-services](https://packagist.org/packages/dotkernel/dot-annotated-services))
- Input Filter ([laminas/laminas-inputfilter](https://github.com/laminas/laminas-inputfilter))
- Doctrine 2 ORM ([doctrine/orm](https://github.com/doctrine/orm))
- Hydrator ([laminas/laminas-hydrator](https://github.com/laminas/laminas-hydrator))
- Paginator ([laminas/laminas-paginator](https://github.com/laminas/laminas-paginator))
- HAL ([mezzio/mezzio-hal](https://docs.mezzio.dev/mezzio-hal/))
- CLI ([dotkernel/dot-cli](https://packagist.org/packages/dotkernel/dot-cli))
- TwigRenderer ([mezzio/mezzio-twigrenderer](https://github.com/mezzio/mezzio-twigrenderer))
- Fixtures ([dotkernel/dot-data-fixtures](https://packagist.org/packages/dotkernel/dot-data-fixtures))
- UUID ([ramsey/uuid-doctrine](https://github.com/mezzio/mezzio-twigrenderer))

## Doctrine 2 ORM

For the persistence in a relational database management system we chose [Doctrine ORM](https://www.doctrine-project.org/projects/doctrine-orm/en/2.14/index.html) (object-relational mapper).
The benefit of Doctrine for the programmer is the ability to focus on the object-oriented business logic and worry about persistence only as a secondary priority.

## Documentation

Our documentation is [Postman](https://www.postman.com/) based.
We use the following files in which we store information about every available endpoint ready to be tested:

- `documentation/Dotkernel_API.postman_collection.json`
- `documentation/Dotkernel_API.postman_environment.json`

## Hypertext Application Language

For our API payloads (a value object for describing the API resource, its relational links and any embedded/child resources related to it) we chose [mezzio-hal](https://docs.mezzio.dev/mezzio-hal/).

## CORS

By using `MezzioCorsMiddlewareCorsMiddleware`, the CORS preflight will be recognized and the middleware will start to detect the proper CORS configuration.
The Router is used to detect every allowed request method by executing a route match with all possible request methods.
Therefore, for every preflight request, there is at least one Router request.

## OAuth 2.0

OAuth 2.0 is an authorization framework that enables applications to obtain limited access to user accounts on your Dotkernel API.
We are using [mezzio/mezzio-authentication-oauth2](https://docs.mezzio.dev/mezzio-authentication-oauth2/) which provides OAuth 2.0 authentication for Mezzio and PSR-7/PSR-15 applications by using the [league/oauth2-server](https://oauth2.thephpleague.com/) package.

## Email

It is not unlikely for an API to send emails depending on the use case.
Here is another area where Dotkernel API shines.
Using `DotMailServiceMailService` provided by [dotkernel/dot-mail](https://packagist.org/packages/dotkernel/dot-mail) you can easily send custom email templates.

## Configuration

From authorization at request route level to API keys for your application, you can find every configuration variable in the config directory.
Registering a new module can be done by including its `ConfigProvider.php` in `config.php`.
Brand new middlewares should go into `pipeline.php`.
Here you can edit the order in which they run and find more info about the currently included ones.
You can further customize your API within the autoload directory where each configuration category has its own file.

## Routing

Each module has a `RoutesDelegator.php` file for managing existing routes inside that specific module.
It also allows a quick way of adding new routes by providing the route path, Middlewares that the route will use and the route name.
You can allocate permissions per route name in order to restrict access for a user role to a specific route in `config/autoload/authorization.global.php`.

## Commands

For registering new commands first make sure your command class extends `SymfonyComponentConsoleCommandCommand`.
Then you can enable it by registering it in `config/autoload/cli.global.php`.

## File Locker

Here you will also find our brand new file locker configuration so you can easily turn it on or off (by default: `'enabled' => true`).
Note: The File Locker System will create a `command-{command-default-name}.lock` file which will not let another instance of the same command run until the previous one has finished.

## PSR Standards

- [PSR-3: Logger Interface](https://www.php-fig.org/psr/psr-3/) - the application uses `LoggerInterface` for error logging
- [PSR-4: Autoloader](https://www.php-fig.org/psr/psr-4/) - the application locates classes using an autoloader
- [PSR-7: HTTP message interfaces](https://www.php-fig.org/psr/psr-7/) - the handlers return `ResponseInterface`
- [PSR-11: Container interface](https://www.php-fig.org/psr/psr-11/) - the application is container-based
- [PSR-15: HTTP Server Request Handlers](https://www.php-fig.org/psr/psr-15/) - the handlers implement `RequestHandlerInterface`

## Tests

One of the best ways to ensure the quality of your product is to create and run functional and unit tests.
You can find factory-made tests in the `tests/AppTest/` folder, and you can also register your own.

## FAQ

**Q: What is Dotkernel API based on?**
A: It's based on Enrico Zimuel's Zend Expressive API - Skeleton example, and runs on the Mezzio microframework and Laminas components, implementing PSR-3, PSR-4, PSR-7, PSR-11 and PSR-15.

**Q: What ORM does Dotkernel API use for persistence, and why?**
A: Doctrine ORM (object-relational mapper), chosen because it lets the programmer focus on the object-oriented business logic and treat persistence only as a secondary priority.

**Q: How is Dotkernel API documented?**
A: The documentation is Postman-based, using two files that store information about every available endpoint ready to be tested: documentation/Dotkernel_API.postman_collection.json and documentation/Dotkernel_API.postman_environment.json.

**Q: How does CORS handling work in Dotkernel API?**
A: MezzioCorsMiddlewareCorsMiddleware recognizes the CORS preflight request and detects the proper CORS configuration. The Router is used to detect every allowed request method by executing a route match with all possible request methods, so there's at least one Router request for every preflight request.

**Q: How do you register a new module or add new middleware?**
A: Registering a new module is done by including its ConfigProvider.php in config.php. Brand new middleware should go into pipeline.php, where you can also edit the order in which middleware runs.

**Q: What does the File Locker System do?**
A: It's enabled by default and creates a command-{command-default-name}.lock file, which prevents another instance of the same command from running until the previous one has finished.


<!-- ============================================================ -->
<!-- dotkernel3/dotkernel-frontend-version-3-launched.md -->
<!-- ============================================================ -->

---
title: "Dotkernel Frontend version 3 launched"
description: "Announcement of Dotkernel Frontend version 3, a Mezzio-based PHP application, including its GitHub source, live demo, and version 3 changelog requirements."
author: "admin"
date_published: "2020-05-19"
canonical_url: "https://www.dotkernel.com/dotkernel3/dotkernel-frontend-version-3-launched/"
category: "Dotkernel 3"
language: "en"
---

# Dotkernel Frontend version 3 launched

## TL;DR

Dotkernel Frontend version 3 has launched as part of the Dotkernel collection of PSR-7 Middleware applications, built on the Mezzio microframework using Laminas components.
The source is available on GitHub, with a live demo running at v3.dotkernel.net.
Branch 3.0 is now the default branch, requiring Mezzio ^3.2, PHP ^7.4, Doctrine 2.7.x, and Twig 3.x, with dot-* packages limited to version 3.x and above.

## Dotkernel Frontend PHP Application Version 3 Was Launched

Dotkernel is a collection of PSR-7 Middleware applications built on top of the [Mezzio microframework and using Laminas components](https://getlaminas.org/).
You can clone it from [GitHub](https://github.com/dotkernel/frontend).
Live demo: [v3.dotkernel.net](https://v3.dotkernel.net)

### Changelog

Branch 3.0 is the current and default branch, and:

- Require Mezzio ^3.2
- Require PHP ^7.4
- Require Doctrine 2.7.x
- Require Twig 3.x
- Limited dot-* packages to version 3.x and above

## FAQ

**Q: What is Dotkernel Frontend built on?**
A: It's part of the Dotkernel collection of PSR-7 Middleware applications, built on top of the Mezzio microframework using Laminas components.

**Q: Where can you see a live demo of version 3?**
A: At v3.dotkernel.net.

**Q: What are the changelog requirements for version 3?**
A: Requires Mezzio ^3.2, PHP ^7.4, Doctrine 2.7.x, and Twig 3.x, with dot-* packages limited to version 3.x and above.


<!-- ============================================================ -->
<!-- dotkernel3/dotkernel3-stable-release-version-1-0.md -->
<!-- ============================================================ -->

---
title: "Dotkernel3 - Stable Release version 1.0"
description: "Dotkernel3's stable 1.0 release adds Zend Expressive 3 and PSR-15 middleware support, listing what's new, what changed for existing middleware, and every package updated or removed."
author: "Gabi DJ"
date_published: "2018-06-27"
canonical_url: "https://www.dotkernel.com/dotkernel3/dotkernel3-stable-release-version-1-0/"
category: "Dotkernel 3"
language: "en"
---

# Dotkernel3 - Stable Release version 1.0

## TL;DR

Dotkernel3 1.0 updates the core packages to support Zend Expressive 3 and PSR-15 middleware, making both frontend (1.0.0) and admin (1.0.1) easier to migrate.
No functional changes were made to the core code, though projects using the old http-interop/http-middleware package must migrate to the psr/http-server-middleware interfaces.
Existing Dotkernel 3 (Expressive 2) projects can follow a separate guide to move to Zend Expressive 3.

## Release Overview

Dotkernel was updated to support Zend Expressive 3 alongside PSR-15 middleware.

We have updated the core packages to support PSR-15 Middleware.

By updating the core packages, both frontend and admin are easier to migrate.

The new versions are:
frontend -> 1.0.0
admin -> 1.0.1

If your project is a Dotkernel 3 instance (based on Expressive 2), you can migrate your project to Zend Expressive 3 by following this guide.

## What's New

- Runs on Zend Stratigility / Zend Expressive 3.0
- Middleware is now PSR-15 compliant
- PHP >=7.1 Support

## Changes

- No functional changes were made in the core code
- If your middleware code is based on the dotkernel/dot-controller package, no middleware migration is needed
- If your middleware code is based on the http-interop/http-middleware, migration must be made to implement interfaces in psr/http-server-middleware

## Packages Updated

- dotkernel/dot-authentication-service:^1.0
- dotkernel/dot-authentication-web:^1.0.1
- dotkernel/dot-authentication:^1.0
- dotkernel/dot-controller:^1.0
- dotkernel/dot-controller-plugin-authentication:^1.0
- dotkernel/dot-controller-plugin-authorization:^1.0
- dotkernel/dot-controller-plugin-flashmessenger:^1.0
- dotkernel/dot-controller-plugin-forms:^1.0
- dotkernel/dot-controller-plugin-mail:^1.0
- dotkernel/dot-controller-plugin-session:^1.0
- dotkernel/dot-flashmessenger:^1.0
- dotkernel/dot-helpers:^1.0
- dotkernel/dot-log:^1.1.1
- dotkernel/dot-mail:^1.0
- dotkernel/dot-mapper:^1.0
- dotkernel/dot-navigation:^1.0
- dotkernel/dot-rbac:^0.2.1
- dotkernel/dot-rbac-guard:^1.0
- dotkernel/dot-session:^3.0
- dotkernel/dot-twigrenderer:^1.1
- dotkernel/dot-user:^1.0

## Zend Packages (Support) Updated

- psr/http-server-middleware:^1.0
- psr/http-server-handler:^1.0
- zendframework/zend-expressive-helpers:^5.0
- zendframework/zend-expressive-twigrenderer:^2.0
- zendframework/zend-expressive-template:^2.0
- zendframework/zend-expressive:^3.0
- zendframework/zend-expressive-fastroute:^3.0
- zendframework/zend-expressive-tooling:^1.0
- zendframework/zend-expressive-router:^3.0
- zendframework/zend-stratigility:^3.0
- zendframework/zend-component-installer:^2.0

## Packages Removed

- http-interop/http-middleware
- webimpress/http-middleware-compatibility

## FAQ

**Q: What is the headline change in this stable release?**
A: Dotkernel was updated to support Zend Expressive 3 alongside PSR-15 middleware, with the core packages updated to support PSR-15 Middleware, making both frontend and admin easier to migrate.

**Q: What are the new component versions in this release?**
A: frontend 1.0.0 and admin 1.0.1.

**Q: What PHP version does this release require?**
A: PHP >= 7.1.

**Q: Do you need to migrate your middleware code for this release?**
A: If your middleware code is based on the dotkernel/dot-controller package, no migration is needed. If it's based on http-interop/http-middleware, you must migrate it to implement the interfaces in psr/http-server-middleware.

**Q: What packages were removed in this release?**
A: http-interop/http-middleware and webimpress/http-middleware-compatibility.


<!-- ============================================================ -->
<!-- dotkernel3/php-8-3-support-in-dotkernel-admin.md -->
<!-- ============================================================ -->

---
title: "PHP 8.3 support in Dotkernel Admin"
description: "A rundown of the backward incompatibilities and dependency updates involved in adding PHP 8.3 support to Dotkernel Admin, released in version 4.3.1."
author: "Florin Bidirean"
date_published: "2024-02-06"
canonical_url: "https://www.dotkernel.com/dotkernel3/php-8-3-support-in-dotkernel-admin/"
category: "Dotkernel 3"
language: "en"
---

# PHP 8.3 support in Dotkernel Admin

## TL;DR

Dotkernel Admin added PHP 8.3 support in release 4.3.1, dropping PHP 8.1 and now supporting only PHP 8.2 and PHP 8.3.
The update brought numerous dependency bumps across dotkernel/*, laminas/*, and mezzio/* packages, removed PhpFileCache-related cache configuration because doctrine/cache dropped its implementation classes, and removed doctrine/doctrine-module due to a conflict, which may affect packages that depended on it.
The `AdminService::logAdminVisit` method was also updated to no longer return `AddressNotFoundException`.

With the release of PHP 8.3, the Dotkernel team has been working on updating the dependencies in our packages.
Eventually, this allowed us to update our applications as well, starting with the [Admin](https://github.com/dotkernel/admin), in release 4.3.1.
There were some issues and backward incompatibilities that we will list below.
The full list of file changes is [here](https://github.com/dotkernel/admin/pull/218/files).

- Supports only PHP 8.2 and PHP 8.3
  - Removed support for PHP 8.1
  - Updated workflows - removed PHP 8.1
  - Commits [#1](https://github.com/dotkernel/admin/commit/12d46e671ea430d93e4f4a38ba10e74d375ca944) and [#2](https://github.com/dotkernel/admin/commit/5233c9dabe5264553956df29a66ddfd5808a283b)
- Updated dependencies
  - require
    - `"dotkernel/dot-cli": "^3.4.2"`
    - `"dotkernel/dot-controller": "^3.4.3"`
    - `"dotkernel/dot-data-fixtures": "^1.1.3"`
    - `"dotkernel/dot-errorhandler": "^3.3.2"`
    - `"dotkernel/dot-flashmessenger": "^3.4.2"`
    - `"dotkernel/dot-geoip": "^3.5.3"`
    - `"dotkernel/dot-helpers": "^3.4.2"`
    - `"dotkernel/dot-mail": "^4.1.1"`
    - `"dotkernel/dot-navigation": "^3.4.2"`
    - `"dotkernel/dot-rbac-guard": "^3.4.2"`
    - `"dotkernel/dot-session": "^5.4.2"`
    - `"dotkernel/dot-twigrenderer": "3.4.3"`
    - `"dotkernel/dot-user-agent-sniffer": "^3.3.3"`
    - `"friendsofphp/proxy-manager-lts": "^1.0.16"`
    - `"laminas/laminas-component-installer": "^3.4.0"`
    - `"laminas/laminas-config-aggregator": "^1.14.0"`
    - `"laminas/laminas-i18n": "^2.26.0"`
    - `"laminas/laminas-math": "^3.7.0"`
    - `"mezzio/mezzio": "^3.18.0"`
    - `"mezzio/mezzio-authorization-rbac": "^1.7.0"`
    - `"mezzio/mezzio-cors": "^1.11.1"`
    - `"mezzio/mezzio-fastroute": "^3.11.0"`
    - `"ramsey/uuid-doctrine": "^2.0.0"`
    - `"roave/psr-container-doctrine": "^4.1.0"`
  - require-dev
    - `"filp/whoops": "^2.15.4"`
    - `"laminas/laminas-development-mode": "^3.12.0"`
    - `"laminas/laminas-http": "^2.19.0"`
    - `"mezzio/mezzio-tooling": "^2.9.0"`
    - `"phpunit/phpunit": "^10.5.9"`
    - `"vimeo/psalm": "^5.20.0"`
  - Commit [#1](https://github.com/dotkernel/admin/commit/a4cfb4f8873e18e100ed089a7ccfed0b3e8603fc)
- Added `"laminas/laminas-http": "^2.19.0"` to composer.json require-dev (required for tests)
  - Commit [#1](https://github.com/dotkernel/admin/commit/b47119e7cbd1c96648cac2d1781fb227f3c12cc9)
- Updated `src/Admin/src/Service/AdminService.php`, function `logAdminVisit`
  - Note: No longer returns `AddressNotFoundException`
  - Commit [#1](https://github.com/dotkernel/admin/commit/b47119e7cbd1c96648cac2d1781fb227f3c12cc9)
- Removed parameter from configuration files and uses for class `PhpFileCache` (required by cache)
  - Removed `use Doctrine\Common\Cache\PhpFileCache;` from local.php.dist (local.php) and doctrine.global.php
  - Removed the parameters used by cache configuration from local.php.dist (local.php) and cache from doctrine.global.php
  - Commits [#1](https://github.com/dotkernel/admin/commit/73c79dd707e8575adec013ae1cd85f87c01787f1) and [#2](https://github.com/dotkernel/admin/commit/6585a39c0077763e55161b8749f19ac2a846f5df)
- Updated `dotkernel/dot-twigrenderer` dependencies
  - Removed `doctrine/doctrine-module` because of conflict
  - Other packages that don't get installed because of removing `doctrine/doctrine-module` - make sure to check if their functionality is used in your project
    - `doctrine/doctrine-laminas-hydrator`
    - `laminas/laminas-cache-storage-adapter-filesystem`
    - `laminas/laminas-cache-storage-adapter-memory`
    - `laminas/laminas-mvc`
    - `laminas/laminas-paginator`

Updating to PHP 8.3 has not been as streamlined as in previous updates, but the advantages of doing so outweigh the extra work on the custom code to remove potential incompatibilities.
The Dotkernel team is focused on the cache that has been removed in the current version because `doctrine/cache` deleted their cache implementation classes.
We are also updating our existing projects to PHP 8.3 and testing the changes on live environments to iron out any other issues.

## FAQ

**Q: Which Dotkernel Admin release added PHP 8.3 support?**
A: Release 4.3.1.

**Q: Which PHP versions does this release support?**
A: Only PHP 8.2 and PHP 8.3 - support for PHP 8.1 was removed, including from the workflows.

**Q: Did the logAdminVisit function change?**
A: Yes. src/Admin/src/Service/AdminService.php's logAdminVisit function was updated and no longer returns AddressNotFoundException.

**Q: Why were cache-related parameters removed from the configuration files?**
A: The PhpFileCache class and its related parameters were removed from local.php.dist (local.php) and doctrine.global.php because doctrine/cache deleted their cache implementation classes.

**Q: Are there side effects from updating the dot-twigrenderer dependencies?**
A: Yes. doctrine/doctrine-module was removed because of a conflict, which means other packages that depended on it - such as doctrine/doctrine-laminas-hydrator, laminas-cache-storage-adapter-filesystem, laminas-cache-storage-adapter-memory, laminas-mvc and laminas-paginator - may no longer get installed, so you should check whether your project actually relies on them.


<!-- ============================================================ -->
<!-- dotkernel3/php-8-3-support-in-dotkernel-api.md -->
<!-- ============================================================ -->

---
title: "PHP 8.3 support in Dotkernel API"
description: "Dotkernel API (now v4.2.1) was updated to support PHP 8.2 and PHP 8.3, dropping PHP 8.1, updating dependencies, and replacing the removed PhpFileCache with the new dot-cache package."
author: "Florin Bidirean"
date_published: "2024-04-03"
canonical_url: "https://www.dotkernel.com/dotkernel3/php-8-3-support-in-dotkernel-api/"
category: "Dotkernel 3"
language: "en"
---

# PHP 8.3 support in Dotkernel API

## TL;DR

Dotkernel API, now at v4.2.1, is the last remaining Dotkernel application updated to support PHP 8.3, following the same approach used for the Frontend update.
The update drops PHP 8.1 support, updates a large set of dependencies, removes the `PhpFileCache`-based configuration in favor of the new `dot-cache` package, and requires a small query change (`useQueryCache()` to `setCacheable()`).

## Supported PHP versions

Dotkernel API now supports only PHP 8.2 and PHP 8.3.
Support for PHP 8.1 was removed, and the project's CI workflows were updated accordingly.

## Updated dependencies

### require

- `dotkernel/dot-annotated-services`: ^4.1.7
- `dotkernel/dot-cli`: ^3.5.0
- `dotkernel/dot-data-fixtures`: ^1.1.3
- `dotkernel/dot-doctrine-metadata`: ^3.2.2
- `dotkernel/dot-errorhandler`: ^3.3.2
- `dotkernel/dot-mail`: ^4.1.1
- `dotkernel/dot-response-header`: ^3.2.3
- `laminas/laminas-component-installer`: ^3.4.0
- `laminas/laminas-config`: ^3.9.0
- `laminas/laminas-config-aggregator`: ^1.14.0
- `laminas/laminas-http`: ^2.19.0
- `laminas/laminas-hydrator`: ^4.15.0
- `laminas/laminas-inputfilter`: ^2.29.0
- `laminas/laminas-paginator`: ^2.18.0
- `laminas/laminas-stdlib`: ^3.19.0
- `laminas/laminas-text`: ^2.11.0
- `mezzio/mezzio`: ^3.19.0
- `mezzio/mezzio-authentication-oauth2`: ^2.8.0
- `mezzio/mezzio-authorization-acl`: ^1.10.0
- `mezzio/mezzio-authorization-rbac`: ^1.7.0
- `mezzio/mezzio-cors`: ^1.11.1
- `mezzio/mezzio-fastroute`: ^3.11.0
- `mezzio/mezzio-problem-details`: ^1.13.1
- `mezzio/mezzio-twigrenderer`: ^2.15.0
- `ramsey/uuid-doctrine`: ^2.0.0
- `roave/psr-container-doctrine`: ^4.1.0
- `symfony/filesystem`: ^7.0.3

### require-dev

- `laminas/laminas-coding-standard`: ^2.5
- `laminas/laminas-development-mode`: ^3.12.0
- `mezzio/mezzio-tooling`: ^2.9.0
- `phpunit/phpunit`: ^10.5.10
- `roave/security-advisories`: dev-latest
- `vimeo/psalm`: ^5.22.0

## Caching changes

The `PhpFileCache` class (previously required for cache configuration) and its related parameters were removed from `config/autoload/doctrine.global.php`, including the `use Doctrine\Common\Cache\PhpFileCache` import and the cache-related configuration parameters.

In its place, the `dot-cache` package was added, with corresponding updates made to `composer.json`, `config/autoload/doctrine.global.php`, and `config/config.php`.

## Upgrade notes

- When upgrading from an older version of Dotkernel API (before PHP 8.3 support), you may need to run `composer update` and/or install Sodium, for example via `sudo dnf install php-sodium.x86_64`.
- Update your queries: replace `useQueryCache()` with `setCacheable()` wherever it is used.

## FAQ

**Q: What PHP versions does Dotkernel API support after this update?**
A: Dotkernel API, now at v4.2.1, supports only PHP 8.2 and PHP 8.3.
Support for PHP 8.1 was removed, including from the project's workflows.

**Q: What changed with caching in Dotkernel API?**
A: The PhpFileCache class and its related parameters were removed from config/autoload/doctrine.global.php, which previously required it for cache configuration.
The dot-cache package was added instead, with corresponding updates to composer.json, config/autoload/doctrine.global.php, and config/config.php.

**Q: Do I need to update my Doctrine queries after this update?**
A: Yes.
Wherever useQueryCache() is used in your queries, it should be replaced with setCacheable().

**Q: What should I do when upgrading an older Dotkernel API installation to this version?**
A: When upgrading from a version of Dotkernel API older than the PHP 8.3 support, you may need to run composer update and/or install Sodium, for example by running sudo dnf install php-sodium.x86_64.

**Q: Where can I find the full list of changes for this update?**
A: The full list of file changes is available in the linked pull request on GitHub for the dotkernel/api repository, and the steps taken mirror those used for the PHP 8.3 update of the Dotkernel Frontend.

## Resources

- [Dotkernel API on GitHub](https://github.com/dotkernel/api)
- [Dotkernel Frontend on GitHub](https://github.com/dotkernel/frontend)
- [Full list of file changes (PR #222)](https://github.com/dotkernel/api/pull/222)


<!-- ============================================================ -->
<!-- dotkernel3/php-8-3-support-in-dotkernel-frontend.md -->
<!-- ============================================================ -->

---
title: "PHP 8.3 support in Dotkernel Frontend"
description: "The Dotkernel team updated the Frontend application to version 4.2.0 to support PHP 8.3, dropping PHP 8.1 and the PhpFileCache class along the way."
author: "Florin Bidirean"
date_published: "2024-02-14"
canonical_url: "https://www.dotkernel.com/dotkernel3/php-8-3-support-in-dotkernel-frontend/"
category: "Dotkernel 3"
language: "en"
---

# PHP 8.3 support in Dotkernel Frontend

## TL;DR

To take advantage of PHP 8.3 support in the newest packages, the Dotkernel team updated the [Frontend](https://github.com/dotkernel/frontend) application to version 4.2.0.
As with the earlier Admin update, this required dropping support for PHP 8.1 and for the no-longer-available `PhpFileCache` class, until a replacement is implemented.

## What changed

- **Supports only PHP 8.2 and PHP 8.3**
  - Removed support for PHP 8.1
  - Updated CI workflows to remove PHP 8.1
- **Updated dependencies** in `composer.json` (`require` and `require-dev`), including packages such as `dotkernel/dot-annotated-services`, `dotkernel/dot-controller`, `dotkernel/dot-mail`, `mezzio/mezzio`, `phpunit/phpunit`, `rector/rector`, and `vimeo/psalm`.
- **Updated npm dependencies** in `packagist.json` - recommended to use npm v10.0.4 and Node.js v20.11.0.
- **Removed `PhpFileCache` usage** from configuration files (required due to the class no longer being available):
  - Updated `doctrine.global.php`
  - Removed the `use Doctrine\Common\Cache\PhpFileCache;` statement
  - Removed the parameters used by the `configuration` and `cache` cache settings
- **Fixed Psalm and PHPCS issues** - updated type hints and indentation.

Next on the roadmap: implementing these changes in the Dotkernel Frontend live projects and processing the feedback.

## FAQ

**Q: What update adds PHP 8.3 support to Dotkernel Frontend?**
A: The Dotkernel team updated the Frontend application to version 4.2.0 so it can take advantage of PHP 8.3 support in the newest packages.

**Q: Which PHP versions does Dotkernel Frontend 4.2.0 support?**
A: Version 4.2.0 supports only PHP 8.2 and PHP 8.3.
Support for PHP 8.1 was removed, similar to the earlier Admin update.

**Q: What changed with caching in this update?**
A: The no-longer-available PhpFileCache class is no longer supported until a replacement is implemented. The related parameters were removed from configuration files, including removing the `use Doctrine\Common\Cache\PhpFileCache;` statement and the configuration and cache parameters in `doctrine.global.php`.

**Q: What npm and Node.js versions are recommended for this update?**
A: Alongside updated npm dependencies in packagist.json, it is recommended to use npm v10.0.4 and Node.js v20.11.0.

**Q: Where can I find the full list of file changes for this update?**
A: The full list of file changes is linked in the article, pointing to the corresponding pull request on the Dotkernel Frontend GitHub repository.

## Resources

- [Dotkernel Frontend on GitHub](https://github.com/dotkernel/frontend)
- [Full list of file changes (pull request)](https://github.com/dotkernel/frontend/pull/417)


<!-- ============================================================ -->
<!-- headless-platform/complementary-admin-in-dotkernel-headless-platform.md -->
<!-- ============================================================ -->

---
title: "Complementary Admin in Dotkernel Headless Platform"
description: "Overview of Dotkernel Admin, the independent, first-party admin application designed to pair seamlessly with Dotkernel API in the Dotkernel Headless Platform."
author: "Florin Bidirean"
date_published: "2025-08-06"
canonical_url: "https://www.dotkernel.com/headless-platform/complementary-admin-in-dotkernel-headless-platform/"
category: "Headless Platform"
language: "en"
---

# Complementary Admin in Dotkernel Headless Platform

## TL;DR

The Dotkernel Headless Platform's core components are Dotkernel API and Dotkernel Queue, but the suite also offers a fully separate, complementary **Admin** application designed to pair seamlessly with Dotkernel API.
Admin is an independent app built on the same Mezzio + Laminas foundation, sharing a unified tech stack with the API so the two form a cohesive, consistent system.

## What is Dotkernel Admin?

Dotkernel Admin lives in its own separate repository and is a fully-functional, independent application.
It's built on top of the same Mezzio + Laminas foundation as Dotkernel API, and comes with a built-in UI including authentication, user management and a web interface.

### Installation

1. Clone the repository into your folder of choice:
   ```shell
   git clone https://github.com/dotkernel/admin.git .
   ```
2. Follow the step-by-step [installation guide](https://docs.dotkernel.org/admin-documentation/v5/installation/getting-started/) to configure the database credentials and run the migrations and fixtures that create and populate the database.
This takes only a few minutes and results in a ready-to-use admin panel.

> Make sure to change the default credentials when in production.

## Features & Architecture

Dotkernel Admin comes with several useful features out of the box:

- **Role-Based Access Control** using [dot-rbac](https://docs.dotkernel.org/dot-rbac/) and [dot-rbac-guard](https://docs.dotkernel.org/dot-rbac-guard/) to manage permissions, routes and handler-level security.
- **OpenAPI** annotations included in each module via `OpenAPI.php`, making admin endpoints documented and testable.
- **Frontend tooling** using [Twig](https://twig.symfony.com/) and [NodeJS/NPM](https://www.npmjs.com/) for client-side assets, including `build` and `watch` scripts to manage JavaScript/CSS bundling.

The file architecture features a modular design with several functional modules:

| Module | Responsibility |
|---|---|
| Admin module | Manages administrator users |
| App module | Houses core functions like authentication and error reporting |
| Setting module | Stores and manages display or application settings for various report pages |

## How They Work Together

- The [REST API](https://github.com/dotkernel/api) is designed to serve JSON endpoints for clients, services and mobile apps alike.
- The [Admin UI](https://github.com/dotkernel/admin) is a web-based interface that communicates with the database via its own endpoints to manage data, users and settings.

One of the greatest benefits to using both Dotkernel API and Admin is the **unified tech stack**.
Both use the [Mezzio microframework](https://docs.mezzio.dev/), [Laminas components](https://docs.laminas.dev/), [Doctrine ORM](https://www.doctrine-project.org/) for database storage and object mapping, [PHP FIG's PSR standards](https://www.php-fig.org/), and share modules like authentication and `dot-rbac`.

Put together, these ensure consistency across backend and admin tooling, while also making it easier to switch between developing one or the other.
The similar architecture normally means fewer developers are needed to manage the codebases.

## Summary

Dotkernel Admin is a complementary admin panel that provides effective reporting out of the box and is a good starting point for admin requirements.
It's not bundled by default, but is provided as a first-party, installable package designed to work seamlessly alongside the API.

Together, the two applications form a cohesive system: you normally start with the API backend and add the rich administrative interface to complete your admin platform.
Both are built with the same underlying file architecture and implement the same PHP standards - [PSR-7 (HTTP messages)](https://www.php-fig.org/psr/psr-7/) and [PSR-15 (middleware)](https://github.com/php-fig/http-server-handler).

Benefits of both components:

- Fully open-source and in active development.
- Highly configurable to suit exact requirements.
- Guarantee a future-proof system using the best practices recommended by the PHP community.

## FAQ

**Q: What is Dotkernel Admin?**
A: Dotkernel Admin is a fully-functional, independent application that lives in its own separate repository.
It's built on the same Mezzio + Laminas foundation as Dotkernel API and includes a built-in UI with authentication, user management and a web interface.

**Q: How do I install Dotkernel Admin?**
A: Install it via Git into the folder of your choice with `git clone https://github.com/dotkernel/admin.git .`, then follow the step-by-step installation guide to configure the database credentials and run the migrations and fixtures that create and populate the database.
Be sure to change the default credentials before going to production.

**Q: What features does Dotkernel Admin include out of the box?**
A: It ships with Role-Based Access Control powered by dot-rbac and dot-rbac-guard to manage permissions, routes and handler-level security; OpenAPI annotations in each module for documented and testable admin endpoints; and frontend tooling built on Twig and NodeJS/NPM, including build and watch scripts for JavaScript/CSS bundling.

**Q: What modules make up Dotkernel Admin's architecture?**
A: The file architecture is modular, featuring an Admin module that manages administrator users, an App module that houses core functions like authentication and error reporting, and a Setting module that stores and manages display or application settings for various report pages.

**Q: How do Dotkernel API and Admin work together?**
A: The REST API serves JSON endpoints for clients, services and mobile apps, while the Admin UI is a web-based interface that communicates with the database via its own endpoints to manage data, users and settings.
Both share a unified tech stack - Mezzio, Laminas components, Doctrine ORM and PHP FIG's PSR standards - plus shared modules like authentication and dot-rbac, which keeps backend and admin tooling consistent and lets fewer developers manage both codebases.

## Resources

- [Dotkernel Admin full documentation](https://docs.dotkernel.org/admin-documentation/)
- [Dotkernel Admin Installation](https://docs.dotkernel.org/admin-documentation/v5/installation/getting-started/)
- [Dotkernel Repositories](https://github.com/dotkernel)
- [PHP Framework Interop Group Standards](https://www.php-fig.org/)


<!-- ============================================================ -->
<!-- headless-platform/dotkernel-api-v6-the-root-of-dotkernel-headless-platform.md -->
<!-- ============================================================ -->

---
title: "Dotkernel API v6: The root of Dotkernel Headless Platform"
description: "Overview of what changed in Dotkernel API v6 since the original architecture and components article, covering new features, the Core module, composer updates, and testing/configuration changes."
author: "Florin Bidirean"
date_published: "2025-07-22"
canonical_url: "https://www.dotkernel.com/headless-platform/dotkernel-api-v6-the-root-of-dotkernel-headless-platform/"
category: "Headless Platform"
language: "en"
---

# Dotkernel API v6: The root of Dotkernel Headless Platform

## TL;DR

Dotkernel API has evolved significantly since its original architecture and components article, adding Content Negotiation, standardized error responses via mezzio-problem-details, a shareable Core module, a custom templating solution replacing Twig, and a leaner handler dependency setup.
Packages were updated across the board, the test suite switched from Psalm to PHPStan at a stricter rule level, and the roadmap for v6.1 targets Service Manager 4 and PHP 8.4/8.5 support.

## New Features

- **Content Negotiation** makes it possible for diverse systems to work seamlessly together, defining the communication parameters between client and server so both sides agree on how the data exchange takes place.
- **Standardized error codes**, implemented via [mezzio-problem-details](https://github.com/mezzio/mezzio-problem-details), returning problem details responses based on either PHP primitives or exceptions/throwables to help error reporting system-wide.
- A new **Core module** holding common logic, making it easier to share that functionality with other Dotkernel applications.
To reuse it, the Core module is saved as a separate Git repository, which can then be added as a submodule to any Dotkernel application.
- **Custom templating solution** replacing Twig, avoiding the use of [mezzio-twigrenderer](https://github.com/mezzio/mezzio-twigrenderer).
This offers more reliable template handling, at the small cost of some features that are normally not used in APIs.
- Refactored **handle delegators** and **injected InputFilters**, reducing the number of dependencies in handlers.

Smaller changes:

- Added OpenAPI documentation for all endpoints.
- Added `.gitattributes` to set some git properties based on path and filename.
- Implemented enums in the database, where relevant, mostly as a proof of concept.

## Coming Soon

| | Currently supported | Planned for v6.1 |
|---|---|---|
| Service Manager | Version 3 (restricted because of constraints from some dependencies) | Version 4 |
| PHP | 8.3 | 8.4 and 8.5 |

## Composer Updates

All packages were updated to their most recent versions that still allow for an installable set of dependencies.

One package that stands out is [ramsey/uuid](https://github.com/ramsey/uuid).
UUID version 7 is already being used in ramsey/uuid version 4, so it will be available with no additional code changes once ramsey/uuid version 5 is released.

## Tweaked Configuration and Testing

Alongside smaller changes related to cache configuration for Doctrine and route grouping, the test suite has been revised: [Psalm](https://psalm.dev/) has been replaced with [PHPStan](https://phpstan.org/), a decision made to remain in line with developers from popular projects like Doctrine and Composer, who have also made the switch recently.
A separate upgrade increased the rule level to 8, enabling stricter static analysis and revealing more potential errors.

## FAQ

**Q: What are the main new features in Dotkernel API v6?**
A: Dotkernel API v6 adds Content Negotiation for smoother communication between client and server, standardized error codes via mezzio-problem-details, a new Core module that centralizes common logic for easier sharing across Dotkernel applications, a custom templating solution that replaces Twig/mezzio-twigrenderer, and refactored handle delegators and injected InputFilters that reduce the number of dependencies in handlers.

**Q: Why was common logic moved into a Core module?**
A: Moving the shared logic into a Core module makes it easier to reuse that functionality across other Dotkernel applications.
The Core module can be saved as a separate Git repository and then added as a submodule to any Dotkernel application.

**Q: Why did Dotkernel API replace Twig with a custom templating solution?**
A: Twig was replaced to avoid depending on mezzio-twigrenderer.
The custom solution offers more reliable template handling, at the small cost of some features that are normally not used in APIs anyway.

**Q: What is planned for Dotkernel API v6.1?**
A: Dotkernel API currently supports Service Manager version 3, restricted because of constraints from some dependencies, and PHP 8.3.
The next version on the roadmap, v6.1, is planned to add support for Service Manager 4 as well as PHP 8.4 and 8.5.

**Q: Why was Psalm replaced with PHPStan in the test suite?**
A: Psalm was replaced with PHPStan to remain in line with developers from popular projects like Doctrine and Composer, who have also made the switch.
A separate upgrade also increased the rule level to 8, enabling stricter static analysis and revealing more potential errors.

## Resources

- [Dotkernel API architecture and components (original article)](https://www.dotkernel.com/dotkernel3/dotkernel-api-architecture-components/)
- [mezzio-problem-details on GitHub](https://github.com/mezzio/mezzio-problem-details)
- [mezzio-twigrenderer on GitHub](https://github.com/mezzio/mezzio-twigrenderer)
- [ramsey/uuid on GitHub](https://github.com/ramsey/uuid)
- [Psalm](https://psalm.dev/)
- [PHPStan](https://phpstan.org/)


<!-- ============================================================ -->
<!-- headless-platform/dotkernel-headless-platform-the-whats-hows-and-whys.md -->
<!-- ============================================================ -->

---
title: "Dotkernel Headless Platform - The Whats, Hows and Whys"
description: "Overview of the Dotkernel Headless Platform architecture, its two main components (Dotkernel API and Dotkernel Admin), how to use them together or separately, and the benefits of the combined setup."
author: "Florin Bidirean"
date_published: "2025-06-13"
canonical_url: "https://www.dotkernel.com/headless-platform/dotkernel-headless-platform-the-whats-hows-and-whys/"
category: "Headless Platform"
language: "en"
---

# Dotkernel Headless Platform - The Whats, Hows and Whys

## TL;DR

A Headless Platform decouples the frontend (UI) from the backend services, with responses consumed by another system such as a website or mobile app. The Dotkernel Headless Platform is made up of Dotkernel API (a REST API based on the Mezzio skeleton) and Dotkernel Admin (a backend management interface), which can be installed separately or together.
Using both together, sharing a common Core module, gives consistent entities and queries, an easy-to-maintain shared file structure, and an architecture that scales from small microservices to enterprise-grade APIs.

## Components of the Dotkernel Headless Platform

The Dotkernel Headless Platform contains two major components:

- [Dotkernel API](https://www.dotkernel.org) - a REST API based on the [Mezzio skeleton](https://github.com/mezzio/mezzio-skeleton).
- [Dotkernel Admin](https://github.com/dotkernel/admin) - a complementary component aimed at quickly setting up a backend for your platform.

The Admin is not bundled by default but is available as a first-party, installable application designed to work seamlessly alongside your API.
Together, they form a cohesive system: an API-first backend paired with a rich administrative interface, both built on the same underlying architecture and standards.

Both components use a PSR-compliant middleware stack, implementing [PSR-7](https://www.php-fig.org/psr/psr-7) and [PSR-15](https://www.php-fig.org/psr/psr-15) as defined by the [PHP Framework Interop Group](https://www.php-fig.org/), promoting a lean, modular architecture.

Rather than relying on elements built into the framework, business logic is built from scratch - from handlers to dependencies - giving full control over business logic and data architecture.

## How to Use the Dotkernel Headless Platform

Dotkernel API and Admin can be installed separately or together, based on business requirements.
They are normally designed to complement each other:

- Dotkernel **Admin** manages the data (create, edit, delete).
- Dotkernel **API** exposes the content to 3rd-party frontends or backends.

A simple project can be designed around one of the two at first, then expand to the other:

- **Start with Dotkernel Admin** to populate your database, then later use Dotkernel API to present the data to other frontends written in any programming language, integrating with 3rd-party applications for full control over how data is presented.
- **Start with Dotkernel API** and integrate it into an existing platform.
The API can manage access permissions to keep data secure - admins create and edit data for the backend, while users read data for the frontend.
Admin can be added later for its simple table-based approach, reports, and graphs.

The recommendation is to use both API and Admin from the start.

## Benefits of the Dotkernel Headless Platform Architecture

Using both API and Admin together brings several benefits:

### Common code between applications

The file structure can be configured to use a **Core** module - a common code repository shared between API and Admin, ensuring entities and queries stay consistent.
Entities (products, articles, etc.) are the building blocks of the application, and queries handle CRUD interactions with them.

### Implement only the handlers you need

Having many entities in the Core doesn't require implementing handlers for each one in both API and Admin.
Each application only handles what it needs - for example, a shop may need to edit orders in Admin but only build monthly sales reports via the API.

### Shared file structure

API and Admin share a file structure, so becoming familiar with one makes the other easy to pick up.
This means onboarding is easy and the applications can be maintained by fewer developers - potentially a single developer, at least initially.
By contrast, an API+Angular approach often needs two developers working together to implement a new feature.

### Can satisfy any application size

Thanks to the shared Core module, API and Admin evolve together, forming a good starting point for anything from microservices to enterprise-grade APIs.
A large number of packages are available for integration, and developers decide exactly what modules to include, keeping the finished application lightweight and preventing bloat and long-term technical debt.

### Versatile architecture

The Dotkernel architecture aims to support several architectural designs:

- **Clean Architecture** - software components are organized into concentric layers, with code dependencies flowing from outer to inner layers, improving testability and independence from libraries, UI, and databases.
- **Domain-Driven Design (DDD)** - the focus is on custom solutions for business logic; rather than building reusable services for a Service Oriented Architecture (SOA), only the specific components needed to satisfy requirements are implemented.
- **Hexagonal Architecture** - divides a system into several loosely-coupled, interchangeable components (application core, database, user interface, test scripts, interfaces with other systems), as an alternative to traditional layered architecture.

### Supported by an active community

The Dotkernel development team actively investigates and implements recommended design patterns.
Dotkernel applications and packages continue to receive updates with bugfixes, improvements, and recommendations from the PHP community.
Some updates may break backward compatibility, but this is typically highlighted in companion articles that may include step-by-step tutorials.
The Dotkernel team is available to help with issues related to Dotkernel and Laminas apps and components.

## FAQ

**Q: What is a Headless Platform?**
A: A Headless Platform decouples the User Interface (frontend) from the backend services.
The responses from the platform are then used by another system, such as a website or mobile app.

**Q: What are the two main components of the Dotkernel Headless Platform?**
A: The Dotkernel Headless Platform contains two major components: Dotkernel API, a REST API based on the Mezzio skeleton, and Dotkernel Admin, a complementary component aimed at quickly setting up a backend.
The Admin is not bundled by default but is available as a first-party, installable application designed to work alongside the API.

**Q: Can Dotkernel API and Admin be installed separately?**
A: Yes.
They can be installed separately or together, based on your business requirements.
You can start with Dotkernel Admin to populate your database and later add Dotkernel API to present the data to other frontends, or start with Dotkernel API and integrate it into your existing platform, adding Admin later for its table-based approach, reports, and graphs.

**Q: What benefits come from using both API and Admin together?**
A: Using both together lets you share a common Core module containing the same entities and queries between the two applications, implement only the handlers you actually need, and benefit from a shared file structure that makes onboarding easy and can be maintained by fewer developers.
This setup can also satisfy any application size, from microservices to enterprise-grade APIs.

**Q: What architectural patterns does the Dotkernel Headless Platform follow?**
A: The architecture is designed to be versatile, following Clean Architecture (concentric layers with dependencies flowing from outer to inner layers), Domain-Driven Design (implementing only the specific components needed for your business logic rather than generic reusable services), and Hexagonal Architecture (dividing the system into loosely-coupled, interchangeable components).

## Resources

- [Dotkernel API](https://github.com/dotkernel/api)
- [Dotkernel Admin](https://github.com/dotkernel/admin)
- [Dotkernel repositories](https://github.com/dotkernel)
- [Dotkernel documentation](https://docs.dotkernel.org/)
- [Headless CMS vs. Traditional CMS: What's Right for PHP Apps?](https://www.zend.com/blog/headless-cms-vs-traditional-cms)
- [Laminas GitHub discussions](https://github.com/orgs/laminas/discussions)
- [Dotkernel Discussions](https://github.com/orgs/dotkernel/discussions)


<!-- ============================================================ -->
<!-- headless-platform/dotkernel-queue-asynchronous-execution-in-dotkernel-headless-platform.md -->
<!-- ============================================================ -->

---
title: "Dotkernel Queue - Asynchronous Execution in Dotkernel Headless Platform"
description: "Overview of Dotkernel Queue, a Symfony Messenger based component for running time-consuming or resource-intensive operations asynchronously via background workers in the Dotkernel Headless Platform."
author: "Florin Bidirean"
date_published: "2025-09-04"
canonical_url: "https://www.dotkernel.com/headless-platform/dotkernel-queue-asynchronous-execution-in-dotkernel-headless-platform/"
category: "Headless Platform"
language: "en"
---

# Dotkernel Queue - Asynchronous Execution in Dotkernel Headless Platform

## TL;DR

Dotkernel Queue is a component built on Symfony Messenger (via the netglue/laminas-messenger adapter) that lets time-consuming or resource-intensive operations run asynchronously on background workers instead of inside the normal PHP request-response cycle.
An active daemon listens for TCP connections, stores incoming messages in Redis, and processes them in FIFO order, with logging, IP-whitelisting security, a configurable retry mechanism, reporting metrics, and a Dead Letter Queue for messages that fail.
Priorities and parallel execution are planned future features.

## What Dotkernel Queue Is

Dotkernel Queue is a component based on Symfony Messenger that is used to queue asynchronous tasks. netglue/laminas-messenger is an adapter that integrates Symfony Messenger with the Laminas Service Manager container for Mezzio/Laminas applications.

Some everyday operations are time-consuming and resource-intensive, so it's best if they run on separate machines, decoupled from the regular request-response cycle.
Asynchronous execution performed by background workers ensures these operations are not lost, terminated by PHP timeouts, or interrupted by new requests.
The main benefit is preventing the main platform from overloading, so it can return a response and remain responsive to new requests while the heavy lifting is scheduled to run later.

The main goal for the queue is to not have the main platform wait for a response, because the queue executes the task sometime in the future.
The regular request-response cycle is completed swiftly by the main platform, possibly with a confirmation message; afterward, the main platform can check with the queue regularly to see if the requested task was completed.

## Why Use Dotkernel Queue?

Instead of going straight to Symfony Messenger, using Dotkernel Queue offers several benefits:

- It uses the Symfony Messenger mechanisms at its heart, so it stays updated as Symfony Messenger releases updates.
- netglue/laminas-messenger turns the component into middleware compatible with Mezzio/Laminas.
- It is seamlessly compatible with the Dotkernel Headless Platform, sharing the same file structure and the same Core submodule used across the Dotkernel application suite (Frontend, API, Admin), ensuring consistency across the platform.
- Dotkernel Queue is a standalone application in its own right, so it can be added more easily to an existing platform.
- The implemented queue features are used in the team's own projects, so their worth is guaranteed in live projects.

## Why Decouple Operations from the HTTP Request-Response Cycle?

By default, PHP settings impose a maximum execution time of 30 seconds via the `max_execution_time` parameter.
Extending the interval isn't practical up to hours or days for a simple request, and even 30 seconds is unreasonably long for a website that normally expects a response in a few seconds or under 1 second.
The solution is to delegate the execution of those tasks to an outside system specifically designed for this purpose.

## What Are Tasks with Long Execution?

Tasks delegated to the queue typically:

- Take extended periods of time to execute and may be interrupted by PHP limitations.
- Are external calls that introduce delays from authentication, awaiting responses from potentially multiple interrogations, or may fail because the 3rd party server is offline.
- Are not part of the main PHP request-response cycle.

Categories of tasks that can take an extended time to finish:

- **Data Processing** - big data analytics, scientific simulations, or mathematical computations.
- **File Handling & Media Processing** - video and image processing, or compression/decompression of large files.
- **Networking** - sending email, newsletters, notifications using 3rd party providers.
- **Database Operations** - imports/exports or migrations.
- **System & Infrastructure Tasks** - OS updates, software compilation, CI pipelines.

Reasons for long execution times include: data size (gigabytes, terabytes, etc.), complex algorithms, hardware limitations (CPU speed, memory, storage, network bandwidth), and external dependencies (waiting on APIs or human input).

## How the Dotkernel Queue Works

The queue system has an active daemon that listens for TCP connections on a specific port and stores incoming messages into Redis.
This supports a large number of requests per second without overloading.
Operations are then scheduled for execution when resources are available, using the FIFO (First-In, First-Out) method, where the oldest request is processed first, followed by newer requests.

## Main Features

The following features are already implemented and have been tried and tested extensively in the team's live projects.

### Logging

Logging allows developers to monitor operations and investigate issues, helping pinpoint the cause of an error for faster bug fixes and less downtime.
Detailed queue logs ensure the execution of long operations is maintainable and allows debugging, though project-specific core logic must still be coded to satisfy business requirements.

### Security

Access control is secured by a firewall that only allows requests from whitelisted IPs, keeping the queue as fast as possible without delays from generating and authenticating dynamic tokens.
A more secure setup is to keep the Dotkernel Queue server accessible only via the internal network, which removes the need for the firewall and simplifies initial queue setup.

### Retry Mechanism

If message processing fails, an internal retry feature guarantees reliable and stable execution.
The system can be configured to retry failing tasks a certain number of times, logging the cause each time, before giving up and reporting a failure.
After configuring the number of retries, additional handling of failed messages is left to the developer: some failures (e.g. an invalid email address) won't fix themselves on retry, while others (e.g. a temporarily overloaded database with valid queries) just need to run later.

### Reporting

Logs enable developers to investigate metrics via console commands, including:

- Queue length - how many jobs are in the to-do list.
- Processing time per job.
- Error rates - how many messages failed.
- Throughput - jobs/sec processed.

### Dead Letter Queue (DLQ)

A Dead-Letter Queue is a separate message queue that temporarily stores messages that failed execution due to errors - for example, incomplete messages, or a 3rd party receiver unable to process the request or unavailable.
Certain errors may move messages into the DLQ on the first try, keeping the main queue from being overwhelmed or blocked by messages that will never be processed in their current state.
It also gives troubleshooters a central location to identify causes of errors, apply fixes, and then either manually push the messages back into the main queue or delete them.

## Future Features

Ways to improve Dotkernel Queue are being explored, with new features added as needed in the field.

### Priorities

Currently the queue works on the FIFO method described above.
Priorities would determine how soon a task begins execution - immediately or delayed - since certain tasks may be fast enough to handle as they come in, while others are purposefully pushed further down the line.
Priorities are set to be integrated into Dotkernel Queue in the near future.

### Parallel Execution

Execution is currently made for each task one at a time.
Parallel execution of operations via multiple workers is being investigated, where applicable - for example, preprocessing a report could run in parallel with sending emails, since they are separate systems (email processing is external, while the report uses data from the internal database).

## FAQ

**Q: What is Dotkernel Queue?**
A: Dotkernel Queue is a component based on Symfony Messenger used to queue asynchronous tasks.
It uses the netglue/laminas-messenger adapter to integrate Symfony Messenger with the Laminas Service Manager container for Mezzio/Laminas applications.

**Q: Why use Dotkernel Queue instead of using Symfony Messenger directly?**
A: Dotkernel Queue builds on Symfony Messenger's mechanisms so it stays updated as Symfony Messenger evolves, uses netglue/laminas-messenger to work as Mezzio/Laminas-compatible middleware, shares the same file structure and Core submodule as the Dotkernel Headless Platform for seamless compatibility, works as a standalone application that can be added to an existing platform, and includes features already tried and tested in the team's own live projects.

**Q: Why should long-running operations be decoupled from the HTTP request-response cycle?**
A: By default, PHP imposes a maximum execution time of 30 seconds via the max_execution_time parameter, which is too long for a typical request. Instead of extending that limit, the solution is to delegate such tasks to an outside system designed for this purpose, so the main platform can return a response quickly and stay responsive to new requests.

**Q: How does the Dotkernel Queue process messages?**
A: An active daemon listens for TCP connections on a specific port and stores incoming messages into Redis, which supports a large number of requests per second without overloading.
Messages are then scheduled for execution using the FIFO (First-In, First-Out) method, so the oldest request is processed first.

**Q: What happens when a queued message fails to process?**
A: A configurable retry mechanism retries failing tasks a set number of times, while logging the cause, before giving up and reporting a failure.
Messages that ultimately fail can be moved into a Dead Letter Queue, a separate store for failed messages, where troubleshooters can identify the cause, apply a fix, and either push the message back into the main queue or delete it.

**Q: What features is Dotkernel Queue planning to add in the future?**
A: Two features are being investigated: Priorities, which would let tasks begin execution sooner or later instead of strictly following FIFO order, and Parallel Execution, which would let independent operations run at the same time via multiple workers, such as preprocessing a report in parallel with sending emails.

## Resources

- [Dotkernel Queue Documentation](https://docs.dotkernel.org/queue-documentation/v1/overview/)
- [Dotkernel Repository](https://github.com/dotkernel/)
- [Symfony Messenger Documentation](https://symfony.com/doc/current/messenger.html)
- [Symfony Messenger systemd](https://jolicode.com/blog/symfony-messenger-systemd)
- [How To Prioritize Messages When Building Asynchronous Applications With Symfony Messenger](https://sensiolabs.com/blog/2025/how-to-prioritize-messages-when-building-asynchronous-applications-with-symfony-messenger)
- [Dotkernel Queue on GitHub](https://github.com/dotkernel/queue)
- [Symfony Messenger on GitHub](https://github.com/symfony/messenger)
- [netglue/laminas-messenger on GitHub](https://github.com/netglue/laminas-messenger)
- [Laminas Service Manager Documentation](https://docs.laminas.dev/laminas-servicemanager/)


<!-- ============================================================ -->
<!-- headless-platform/dotmaker-generate-common-code-in-dotkernel.md -->
<!-- ============================================================ -->

---
title: "DotMaker - Generate common code in Dotkernel"
description: "Overview of dotkernel/dot-maker, the CLI tool that generates project files and directories matching the Dotkernel file structure, and how to use it to scaffold modules and individual code items."
author: "Florin Bidirean"
date_published: "2025-09-12"
canonical_url: "https://www.dotkernel.com/headless-platform/dotmaker-generate-common-code-in-dotkernel/"
category: "Headless Platform"
language: "en"
---

# DotMaker - Generate common code in Dotkernel

## TL;DR

DotMaker (`dotkernel/dot-maker`) programmatically generates project files and directories matching the Dotkernel file structure inspired by Mezzio.
It boosts productivity and enforces consistency and standardization compared to creating modules and files by hand, and it can tell the difference between Dotkernel applications (Api, Admin, Frontend) to create the files each one requires.

## Why use dot-maker?

Creating a new module manually requires a relatively large number of files and folders.
Doing this by hand leaves too many opportunities for mistakes that generate errors and delay development.
DotMaker was built to handle this heavy lifting.

DotMaker is inspired by the [Symfony Maker Bundle](https://github.com/symfony/maker-bundle) in terms of functionality.
Mezzio has its own [CLI Tooling](https://docs.mezzio.dev/mezzio/v3/reference/cli-tooling/) that performs similar actions, but DotMaker uses a more opinionated naming pattern and is designed specifically for Dotkernel applications.

## The file structure for a module

Example file structure for a `Book` module and the related files it uses from the `Core` module:

```
.
└── src/
    ├── Book/
    │   └── src/
    │       ├── Collection/
    │       │   └── BookCollection.php
    │       ├── Handler/
    │       │   ├── GetBookCollectionHandler.php
    │       │   ├── GetBookResourceHandler.php
    │       │   └── PostBookResourceHandler.php
    │       ├── InputFilter/
    │       │   ├── Input/
    │       │   │   ├── AuthorInput.php
    │       │   │   ├── NameInput.php
    │       │   │   └── ReleaseDateInput.php
    │       │   └── CreateBookInputFilter.php
    │       ├── Service/
    │       │   ├── BookService.php
    │       │   └── BookServiceInterface.php
    │       ├── ConfigProvider.php
    │       └── RoutesDelegator.php
    └── Core/
        └── src/
            └── Book/
                └── src/
                    ├── Entity/
                    │   └── Book.php
                    ├── Repository/
                    │   └── BookRepository.php
                    └── ConfigProvider.php
```

This example is for a Dotkernel API project, so it has a Collection but is missing the Form and template files that Dotkernel Admin requires.
DotMaker can tell the difference between Dotkernel applications and will create the required files for each.

## How dot-maker works

To create a new module:

1. Run `./vendor/bin/dot-maker module`.
2. Follow the prompted list of steps that create each relevant item, from entities and repositories to handlers and services.
3. DotMaker automatically creates the module's `ConfigProvider.php` and tells you how to register it in `config/config.php` and `composer.json`.
4. DotMaker generates documentation in an `OpenApi.php` file and tells you what command to run to generate migrations for the new module.
5. Once the files are created, manually configure the authorization for the new module based on the platform's requirements.

Authorization is configured in different files between Dotkernel applications:

| Application | Authorization file |
|---|---|
| Dotkernel Api | `config/autoload/authorization.global.php` ([docs](https://docs.dotkernel.org/api-documentation/v6/core-features/authorization/)) |
| Dotkernel Admin | `config/autoload/authorization-guards.global.php` ([docs](https://docs.dotkernel.org/admin-documentation/v6/how-to/authorization/)) |
| Dotkernel Frontend | `config/autoload/authorization-guards.global.php` ([docs](https://docs.dotkernel.org/frontend-documentation/v5/how-to/authorization/)) |

### Generating individual items

DotMaker can also create individual items related to a module, like an entity, a form, a new command, or a middleware, instead of a whole module.
These commands work only after the basic command is added to `composer.json`.

| Command | Effect |
|---|---|
| `composer make collection` / `./vendor/bin/dot-maker collection` | Creates a Collection for an existing module |
| `composer make command` / `./vendor/bin/dot-maker command` | Creates a Command for an existing module |
| `composer make entity` / `./vendor/bin/dot-maker entity` | Creates an Entity and its associated Repository (skips the Repository if it already exists) |
| `composer make form` / `./vendor/bin/dot-maker form` | Creates a Form for an existing module |
| `composer make handler` / `./vendor/bin/dot-maker handler` | Creates a Handler for an existing module |
| `composer make input` / `./vendor/bin/dot-maker input` | Creates an Input for an existing module |
| `composer make input-filter` / `./vendor/bin/dot-maker input-filter` | Creates an InputFilter for an existing module (prompts for create, edit, or replace type) |
| `composer make middleware` / `./vendor/bin/dot-maker middleware` | Creates a Middleware for an existing module |
| `composer make module` / `./vendor/bin/dot-maker module` | Creates a Module and its predefined files (entity, repository, service, handler, etc.) |
| `composer make repository` / `./vendor/bin/dot-maker repository` | Creates a Repository and its Entity (skips the Entity if it already exists) |
| `composer make service` / `./vendor/bin/dot-maker service` | Creates a Service and its associated ServiceInterface (skips the ServiceInterface if it already exists) |
| `composer make service-interface` / `./vendor/bin/dot-maker service-interface` | Creates a ServiceInterface and its associated Service (skips the Service if it already exists) |

DotMaker won't do all the work, but after running through the maker process you have a solid foundation ready to accept custom code.

## FAQ

**Q: What does the DotMaker library do?**
A: DotMaker (dotkernel/dot-maker) programmatically generates project files and directories that match the Dotkernel file structure inspired by Mezzio, giving a productivity boost and promoting consistency and standardization compared to creating everything manually.

**Q: What inspired DotMaker and how is it different from Mezzio's own CLI tooling?**
A: DotMaker is inspired by the Symfony Maker Bundle in terms of functionality.
Mezzio has its own CLI Tooling that performs similar actions, but DotMaker uses a more opinionated naming pattern and is designed specifically for Dotkernel applications.

**Q: How do I create a new module with DotMaker?**
A: Run ./vendor/bin/dot-maker module and follow the prompts that walk you through creating each relevant item, from entities and repositories to handlers and services.
DotMaker also automatically creates the module's ConfigProvider.php, tells you how to register it in config/config.php and composer.json, generates documentation in an OpenApi.php file, and tells you what command to run to generate migrations.

**Q: Does DotMaker configure authorization for the new module?**
A: No, authorization must be configured manually after the files are created, and the location differs between Dotkernel applications: Dotkernel Api uses config/autoload/authorization.global.php, while Dotkernel Admin and Dotkernel Frontend use config/autoload/authorization-guards.global.php.

**Q: Can DotMaker generate individual items instead of a whole module?**
A: Yes.
DotMaker provides individual commands to create items such as a collection, command, entity, form, handler, input, input-filter, middleware, repository, service, or service-interface for an existing module.
For example, ./vendor/bin/dot-maker entity creates an Entity and its associated Repository, skipping the Repository if it already exists.

**Q: Do the composer make shortcuts work right away?**
A: No, commands like composer make entity only work after the basic command has been added to composer.json; the equivalent ./vendor/bin/dot-maker form is available regardless.

## Resources

- [DotMaker full documentation](https://docs.dotkernel.org/dot-maker/v1/overview/)
- [Implementing a book module in Dotkernel API using DotMaker](https://docs.dotkernel.org/api-documentation/v6/tutorials/create-book-module-via-dot-maker/)
- [API file structure](https://docs.dotkernel.org/api-documentation/v6/introduction/file-structure/)
- [Symfony Maker Bundle Documentation](https://symfony.com/bundles/SymfonyMakerBundle/current/index.html)


<!-- ============================================================ -->
<!-- headless-platform/evolution-pattern-versus-api-versioning.md -->
<!-- ============================================================ -->

---
title: "Evolution Pattern versus API Versioning"
description: "How Dotkernel weighs an evolution pattern against API versioning when changing an API, and the sunsetting mechanism used in Dotkernel API to announce breaking changes."
author: "Florin Bidirean"
date_published: "2025-12-09"
canonical_url: "https://www.dotkernel.com/headless-platform/evolution-pattern-versus-api-versioning/"
category: "Headless Platform"
language: "en"
---

# Evolution Pattern versus API Versioning

## TL;DR

An Evolution Pattern keeps the same codebase and evolves it gradually (for example via sunsetting), while API versioning maintains multiple parallel versions of an API so existing clients aren't broken.
The two are not mutually exclusive.
Dotkernel API favors an evolution pattern with a sunsetting mechanism, reserving full versioning for major, format-level changes.

## Definitions

- **Evolution Pattern**: A reusable, high-level strategy for modifying or evolving existing software systems over time, keeping software relevant for old and new users as new needs arise.
- **Versioning**: The practice of assigning unique version numbers to different releases of a software platform to track changes, improvements, bug fixes, compatibility, and evolution.
API versioning specifically assigns versions to an API so it can change without breaking existing clients.
- **Sunsetting**: A mechanism for announcing that an API's old functionality will be phased out on a given date, via response headers, documentation, and public announcements.

## When to use an Evolution Pattern versus Versioning

Technically, the two concepts are not in conflict - an evolution pattern keeps the same codebase and announces breaking changes via mechanisms like sunsetting, while API versioning maintains multiple versions of an API so that changes don't affect clients using older versions.
A platform can use both strategies together if it suits its needs. The responsibility falls on the team to decide where to invest development and maintenance costs.

| Problem | Potential Solution | Strategy |
|---|---|---|
| Fix a typo in the parameter name | Sunsetting / do nothing (it's only a typo) | Evolution pattern. Versioning is overkill. |
| Add a new parameter | Make it optional, so it doesn't break existing implementations | Evolution pattern |
| Implement a backward-compatibility-breaking update that clients must adhere to | Announce it in time to allow clients to adapt | Evolution pattern |
| Implement a major update to an endpoint | Add a `v2` for only that endpoint, not the whole API, and encourage clients to migrate | Evolution pattern + Versioning |
| Return responses in a totally different format (e.g. GraphQL vs REST APIs) | Keep both versions active | Versioning |

## Practical example from Dotkernel API

Dotkernel avoids full rewrites, considering them too risky, costly, and often not the best solution.
Software evolution should instead be gradual and organic, adapting to new requirements with as little impact to the codebase and clients as possible.

For Dotkernel API, an evolution pattern with a sunsetting mechanism was chosen: the codebase stays the same, and new requirements are implemented in a targeted manner.

To enhance an endpoint, Dotkernel distinguishes between calls based on their payload.
For example, on the `/user` endpoint:

- A request with only an `email` uses the older functionality and returns the response currently working for existing clients.
- A request with both `email` and `name` returns an enhanced response, requiring clients to update their own code to handle the new response structure.

### Announcing deprecation

Deprecation is announced by including an updated response header via handler attributes, with customizable values for `sunset`, `link`, and `deprecationReason`.
A deprecated endpoint's response includes headers similar to:

```
HTTP/1.1 200 OK
Host: 0.0.0.0:8080
Date: Mon, 1 Dec 2025 10:10:10 GMT
Connection: close
X-Powered-By: PHP/6.4.20
Content-Type: application/json
Permissions-Policy: interest-cohort=()
Sunset: 2026-01-01
Link: https://docs.dotkernel.org/api-documentation/v7/tutorials/api-evolution/;rel="sunset";type="text/html"
Vary: Origin
```

Developers must read and understand this header so they can plan an update before the sunset date.
New functionality is normally kept alongside the old functionality for a reasonable period.
Once the sunset date is reached, the old functionality is removed and only the new one remains in production:

- An endpoint may return `404 Not Found`.
- A property may be removed from the response.

Dotkernel uses multiple channels to announce impactful, backward-incompatible updates:

- **API headers** include the deprecation header.
- **Documentation pages** detail the change and recommended code updates.
- **Public portal** announcements, like blog articles and newsletters.

Notifications should go out early enough to reach developers of third-party software using the API, so they can plan and implement updates with little or no downtime.

## Conclusions

An evolution pattern requires good planning, including allocating enough time for clients to be aware of updates and implement them, ideally with no downtime for either side.
Versioning remains a valid strategy but is best reserved for impactful architectural changes rather than smaller changes like fixing a typo or adding a field.
Ultimately, the best approach depends on the specific use case.

## FAQ

**Q: What is the difference between an Evolution Pattern and API versioning?**
A: An Evolution Pattern is a reusable, high-level strategy for modifying or evolving existing software systems over time while keeping the same codebase, often using mechanisms like sunsetting.
API versioning instead maintains multiple versions of an API so that changes do not affect clients relying on older versions.
The two concepts are not in conflict, and a platform can use both strategies if it suits its needs.

**Q: When should you use an evolution pattern instead of versioning?**
A: Small changes, like fixing a typo in a parameter name or adding a new optional parameter, are best handled with an evolution pattern, since versioning would be overkill.
Backward-compatible-breaking updates should be announced in time via an evolution pattern.
A major update to a single endpoint can combine an evolution pattern with versioning, for example by adding a v2 for just that endpoint.
Only when responses need to be returned in a totally different format, such as GraphQL versus REST, is versioning the better fit.

**Q: How does Dotkernel API announce endpoint deprecations?**
A: Dotkernel API distinguishes calls based on payload (for example, an older response for a request with only an email, versus an enhanced response when both email and name are supplied).
Deprecation is announced by including an updated response header via handler attributes, with customizable values for sunset, link, and deprecationReason.
These updates are also communicated through documentation pages and public portal channels like blog articles and newsletters.

**Q: What happens once an endpoint's sunset date is reached?**
A: The old functionality is removed and only the new functionality remains in production.
In practice this means an endpoint may start returning 404 Not Found, or a property may be removed from the response.

## Resources

- [What is the HTTP Sunset header?](https://sophiabits.com/blog/what-is-the-http-sunset-header)
- [Deprecating Resources and Properties](https://api-platform.com/docs/core/deprecations)
- [API Evolution for REST/HTTP APIs](https://philsturgeon.com/api-evolution-for-rest-http-apis)
- [Just say no - to versioning APIs](https://www.hmeid.com/blog/just-say-no-to-versioning)
- [Ways to version your API, Part 2](https://urthen.github.io/2013/05/16/ways-to-version-your-api-part-2)


<!-- ============================================================ -->
<!-- headless-platform/implementing-time-based-one-time-password-totp-in-dotkernel.md -->
<!-- ============================================================ -->

---
title: "Implementing Time-based One-Time Password (TOTP) in Dotkernel"
description: "Tutorial on installing and using dot-totp to add two-factor authentication (2FA) with time-based one-time passwords to Dotkernel Admin, including required files, database changes, and the resulting user flow."
author: "Florin Bidirean"
date_published: "2026-04-03"
canonical_url: "https://www.dotkernel.com/headless-platform/implementing-time-based-one-time-password-totp-in-dotkernel/"
category: "Headless Platform"
content_type: "tutorial"
language: "en"
entities:
  - name: "dot-totp"
    type: "SoftwareSourceCode"
    url: "https://github.com/dotkernel/dot-totp"
  - name: "Dotkernel Admin"
    type: "SoftwareApplication"
    url: "https://github.com/dotkernel/admin"
prerequisites:
  - "Dotkernel Admin installed (the steps apply similarly to any middleware-based application)"
  - "An Authenticator app on a mobile device (for end users enabling TOTP)"
keywords: ["TOTP", "time-based one-time password", "2FA", "two-factor authentication", "dot-totp", "Dotkernel Admin", "PHP", "Mezzio", "middleware", "recovery codes", "QR code", "authenticator app"]
official_docs: "https://docs.dotkernel.org/admin-documentation/v7/tutorials/install-dot-totp/"
code_examples: "https://github.com/dotkernel/admin-documentation/tree/main/code_examples/totp"
---

# Implementing Time-based One-Time Password (TOTP) in Dotkernel

## TL;DR

`dot-totp` adds two-factor authentication (2FA) to Dotkernel Admin using time-based one-time passwords.
Users authenticate with their password plus a 6-digit code from an Authenticator app that refreshes every 30 seconds.
Installation is one Composer command plus a set of forms, handlers, middleware, and templates from the official code examples, applying a `TotpTrait` to the relevant entity, migrating three new database columns, and registering routes/pipeline/ConfigProvider updates.

## Definitions

- **TOTP (Time-based One-Time Password)**: A security algorithm used as part of two-factor authentication.
Generates temporary, unique 6-digit codes that change every 30 seconds, via an Authenticator app.
- **2FA (Two-Factor Authentication)**: Requires both a password and an additional one-time code, to protect against account attacks.
- **dot-totp**: The Dotkernel package that integrates the TOTP mechanism into Dotkernel applications.
- **Recovery codes**: Single-use backup codes generated during TOTP activation, usable for login when the mobile device is unavailable.

## Key facts

| Fact | Value |
|---|---|
| Package | `dotkernel/dot-totp` |
| Install command | `composer require dotkernel/dot-totp` |
| Target application | Dotkernel Admin (applies similarly to any middleware-based application) |
| Code format | 6-digit numeric code |
| Code lifetime | 30 seconds |
| Recovery codes | Single-use each; must be saved in a secure location |
| Entity integration | `TotpTrait` applied to any entity requiring 2FA |
| New database columns | `totpSecret`, `totp_enabled`, `recovery_codes` |
| Official tutorial | https://docs.dotkernel.org/admin-documentation/v7/tutorials/install-dot-totp/ |
| Code examples | https://github.com/dotkernel/admin-documentation/tree/main/code_examples/totp |

## 2FA with TOTP: authentication flow

1. User submits username and password (unchanged from standard login).
2. Since TOTP is activated, the application also asks for the code from the user's Authenticator app.
3. User submits the current 6-digit code, or alternatively a single-use recovery code.
4. If the code is valid, the user is logged in.

## Installation steps

### Step 1 - Install the package

Prerequisite: a working Dotkernel Admin installation.

```shell
composer require dotkernel/dot-totp
```

### Step 2 - Add the integration files

Following the Dotkernel file structure, add the files below (downloadable from the [official code examples](https://github.com/dotkernel/admin-documentation/tree/main/code_examples/totp)):

Forms:
- `src/Admin/src/Form/RecoveryForm.php`
- `src/Admin/src/Form/TotpForm.php`

Handlers (in `src/Admin/src/Handler/Account/`):
- `GetDisableTotpFormHandler.php`
- `GetEnableTotpFormHandler.php`
- `GetRecoveryFormHandler.php`
- `GetTotpHandler.php`
- `PostDisableTotpHandler.php`
- `PostEnableTotpHandler.php`
- `PostValidateRecoveryHandler.php`
- `PostValidateTotpHandler.php`

Templates:
- `src/Admin/templates/admin/recovery-form.html.twig`

Middleware:
- `src/App/src/Middleware/CancelUrlMiddleware.php`
- `src/App/src/Middleware/TotpMiddleware.php`

### Step 3 - Apply the entity trait and migrate the database

Apply the trait at `src/Core/src/App/src/Entity/TotpTrait.php` to any entity that requires 2FA, then migrate the new columns onto that entity's table: `totpSecret`, `totp_enabled`, and `recovery_codes`.

### Step 4 - Register the remaining snippets

The `_misc` folder in the code examples contains four required additions:

| Snippet | Destination |
|---|---|
| Enable/disable 2FA button (`totp-append-view-account.html.twig`) | `view-account.html.twig`, or a new page |
| Routes updates (`totp-append-routes.php`) | `src/Admin/src/RoutesDelegator.php` |
| Pipeline updates (`totp-append-Pipeline.php`) | `config/pipeline.php`, after `$app->pipe(AuthMiddleware::class);` |
| ConfigProvider updates (`totp-append-ConfigProvider.php`) | `src/Admin/src/ConfigProvider.php` |

## Using TOTP in Dotkernel Admin (end-user flow)

### Enabling TOTP

1. Navigate to the account profile (top-right image in Dotkernel Admin).
A TOTP box with an "Enable TOTP" button is shown.
2. Click "Enable TOTP".
A QR code is displayed. An Authenticator app on a mobile device is required.
3. Scan the QR code with the mobile device.
4. Enter the 6-digit code generated by the Authenticator app. The code refreshes every 30 seconds.
5. Save the recovery codes shown during activation in a secure location - each is usable only once.
6. If the code is valid, the user is logged in and TOTP is activated for the account.

### Logging in with TOTP enabled

1. Enter username and password as before.
2. Submit the current code from the Authenticator app, or alternatively a recovery code.
3. On success, the user is logged in.

## FAQ

**Q: What is a Time-based One-Time Password (TOTP)?**
A: A Time-based One-Time Password (TOTP) is a security algorithm used as part of two-factor authentication (2FA) that requires both a password and an additional one-time code generated by an Authenticator app. In Dotkernel, this is implemented through the dot-totp package.

**Q: Can dot-totp be used outside of Dotkernel Admin?**
A: Yes.
Although this tutorial installs dot-totp in Dotkernel Admin, the installation steps work similarly in any middleware-based PHP application.

**Q: What happens if I lose access to my authenticator app?**
A: You can log in using one of the recovery codes generated when you activated TOTP.
Each recovery code is usable only once, so make sure to save them in a secure location.

**Q: How often does the TOTP code change?**
A: The code generated by your Authenticator app refreshes every 30 seconds.

**Q: What database changes are required to support dot-totp?**
A: You need to migrate three new columns onto the entity that uses the TotpTrait: totpSecret, totp_enabled, and recovery_codes.

## Resources

- dot-totp on GitHub: https://github.com/dotkernel/dot-totp
- Dotkernel Admin on GitHub: https://github.com/dotkernel/admin
- Official tutorial - Installing dot-totp into Dotkernel Admin: https://docs.dotkernel.org/admin-documentation/v7/tutorials/install-dot-totp/
- Complete code examples: https://github.com/dotkernel/admin-documentation/tree/main/code_examples/totp


<!-- ============================================================ -->
<!-- headless-platform/shared-core-submodule-in-dotkernel-headless-platform.md -->
<!-- ============================================================ -->

---
title: "Shared Core Submodule in Dotkernel Headless Platform"
description: "An explanation of the Core submodule pattern in Dotkernel's Headless Platform, and step-by-step instructions for extracting it into a shared Git submodule."
author: "Florin Bidirean"
date_published: "2025-07-04"
canonical_url: "https://www.dotkernel.com/headless-platform/shared-core-submodule-in-dotkernel-headless-platform/"
category: "Headless Platform"
language: "en"
---

# Shared Core Submodule in Dotkernel Headless Platform

## TL;DR

Dotkernel's Headless Platform is composed of Dotkernel API, Admin, and Queue, and can share a common Core submodule that holds the database entities and services used consistently across all of them.
The article walks through creating the Core submodule with `git submodule add`, committing changes from within the Core folder, and initializing/updating it with `git submodule init` and `git submodule update`.
Sharing a Core module brings design flexibility, scalability, and easier bugfixes and onboarding as the platform grows.

Dotkernel has implemented a Headless solution made up of these applications:

- [Dotkernel API](https://github.com/dotkernel/api) - a REST API, the root of the platform.
- [Dotkernel Admin](https://github.com/dotkernel/admin) - (optional) complementary backend management.
- [Dotkernel Queue](https://github.com/dotkernel/queue) - (optional) queue management microservice.

This is effectively a Headless CMS architecture where the Dotkernel Admin manages the data via the database.
The same data is independently exposed by Dotkernel API and used by Dotkernel Queue.

## What Is the Core Submodule?

The Core submodule is a common codebase set up to be used by the applications you added to your project.
It can just as well work for any project setup, e.g. two APIs, one Admin, 3 Frontends.
By having a common module in your Dotkernel applications, you ensure that each of them uses entities and services in the same way.
Thus, rather than making e.g. an update in each application's services, you only update the relevant service in the Core once and sync it in each application.

> The golden rule for the Core codebase is that it is the only place which manages the database entities.
> As much as possible, all Doctrine entities must reside in Core.
> The current location of the Core submodule is `src/Core`.

## How Do I Create a Core Submodule?

The full steps for creating a submodule are described in [Git Tools - Submodules](https://git-scm.com/book/en/v2/Git-Tools-Submodules).

> There is already a Core module in some of the Dotkernel applications, but it works like any other module (App, Page or User). The Core modules are designed to be a starting point for the module's transformation into a Git submodule.

First create a new Git repository that will contain the Core code.
To create the submodule in an application, you need to have Git create the `.gitmodules` file in the root of the main repository by running the command below.
Use the url from the new repository you just created instead of `<url>`:

```bash
git submodule add <url>
```

> You can have multiple submodules, but for this article we will only create the Core submodule.

The `.gitmodules` file maps the submodule and its corresponding local directory within the main project (e.g. src/Core).
This allows Git to manage the submodule correctly, from cloning, to updating, to tracking its changes.

> None of the Dotkernel applications have the `.gitmodules` file out of the box. Only after isolating the Core into a Git submodule and pushing it to a separate Git repository does it become available to be included into any Dotkernel application.

From now on, any changes to the Core submodule must be committed from within the Core folder, like for any other Git repository, using these commands (simplified version, provided as an example):

```bash
cd <path/to/submodule>
git add .
git commit -m "comment"
git push
```

Whenever you clone the project, you simply need to init and update the submodule with these commands:

```bash
git submodule init
git submodule update
```

> Do not forget to delete the existing Core module before adding the submodule to other applications.

## How Do I Use the Core Submodule?

Once the shared Core submodule is separated and imported into each application, your platform will look something like this:

- API + Core
- Admin + Core
- Queue + Core

> Each box in the image is a different Git repository.

Whenever work begins on a new feature or update, the devs should normally have the most recent Core in their development environment.
So in total you have four code bases which will be kept in four separate repositories.
The Dotkernel applications include various entities to get you started quickly.
This is not a complete list, but it should help you understand what each application is aimed toward:

- The admin has admins, admin logins and settings entities.
- The api has both users and admins, as well as authentication entities.

There are already shared entities which are identical, so the best place for them is within the Core submodule.
Whenever you create new shared code, you should add it in the Core submodule and make sure to keep it updated in all your applications.

> This does not mean that all new code should be in Core, as there are plenty of instances when certain functionality is designed to only be used by one application.

## Why the Core Submodule Is Effective

This design pattern ensures:

- Design flexibility.
- Scalability based on future requirements.
- Consistent, enterprise-level growth, while also being suited for smaller applications.
- The ability to split the work to multiple developers.
- Easier bugfixes and onboarding.

As your platform expands, each new application connects to the Dotkernel Headless Platform via the central API which services everything the other applications require.
This ensures consistency throughout your platform, while allowing any number of outside connections as requirements arise.

## FAQ

**Q: What is the Core submodule in Dotkernel's Headless Platform?**
A: The Core submodule is a common codebase shared by the applications in your project (for example API, Admin and Queue). It ensures each application uses entities and services in the same way, so rather than updating each application separately, you update the relevant service in Core once and sync it across applications.

**Q: What is the golden rule for the Core codebase?**
A: The Core codebase is the only place which manages the database entities. As much as possible, all Doctrine entities must reside in Core, whose current location is `src/Core`.

**Q: How do I create a Core submodule?**
A: First create a new Git repository to hold the Core code. Then, in the main application repository, run `git submodule add <url>` using that new repository's URL. This generates the `.gitmodules` file, which maps the submodule to a local directory such as `src/Core`. From then on, changes to Core must be committed from within the Core folder like any other Git repository.

**Q: How do I get the Core submodule when cloning a project?**
A: Run `git submodule init` followed by `git submodule update`. Remember to delete the existing Core module before adding the submodule to other applications.

**Q: Which entities live in Admin and API versus the shared Core?**
A: The admin application includes admins, admin logins and settings entities, while the API includes both users and admins, as well as authentication entities. Entities that are identical across applications should instead be kept in the shared Core submodule and synced whenever they change.

## Resources

- [Dotkernel Git Repositories](https://github.com/dotkernel)
- [Core in Dotkernel Headless Platform](https://docs.dotkernel.org/headless-documentation/v1/core/introduction/)


<!-- ============================================================ -->
<!-- headless-platform/version-7-adds-postgresql-native-uuid-and-php-8-5.md -->
<!-- ============================================================ -->

---
title: "Version 7 adds PostgreSQL, Native UUID and PHP 8.5"
description: "Overview of Dotkernel API and Admin's v7 release, which adds native UUID v7 support, PostgreSQL compatibility, PHP 8.5/8.4 support, and drops MySQL support."
author: "Florin Bidirean"
date_published: "2025-12-12"
canonical_url: "https://www.dotkernel.com/headless-platform/version-7-adds-postgresql-native-uuid-and-php-8-5/"
category: "Headless Platform"
language: "en"
---

# Version 7 adds PostgreSQL, Native UUID and PHP 8.5

## TL;DR

Dotkernel API v7 adds support for native UUID v7, PostgreSQL, PHP 8.5 (8.4 for Admin), database table prefixes, and improved database configuration, while replacing the `binary` data type for `id` columns with `uuid`.
It drops the Evolution pattern's Method Deprecation support and MySQL, since MySQL doesn't support the UUID data type.
UUIDs are generated with the ramsey/uuid package, previously `uuid`-named table columns are now called `id`, and PostgreSQL or MariaDB v10.7+ is required for UUID support.

The Dotkernel Headless Platform has seen new releases for both API and Admin.
The Admin codebase has received an overall facelift, as well as updates to retain compatibility with API v7.
The release for Dotkernel API v7 has several added features, as well as a few that are removed.

New features are:

- Support for `UUID` v7 using the native `UUID` data type.
- Support for PostgreSQL.
- Support for PHP 8.5 for API and 8.4 for Admin.
- Support for database table prefix (string prepended to the name of every table in a database).
- Improved database configuration.
- The replacement of the `binary` data type for `id` (index) columns, in favor of `uuid`.

And these are the features that have been removed:

- Evolution pattern: Support for Method Deprecation.
- Support for MySQL, primarily because it doesn't support UUID as a data type.

## Support for UUID v7

The most important change in v7 is the introduction of support for native UUID.
We use the package [ramsey/uuid](https://github.com/ramsey/uuid) to generate the uuid and then store it in the database.
In this way we have full control over the UUID version in use.
This solution means you don't depend on extensions or a particular version of the database.

> To ensure you have support for the `UUID` data type, you must use PostgreSQL or MariaDB v10.7 or later.

This also brings along a less-impactful change that still deserves mentioning: the table columns named `uuid` have been renamed to `id`.

## Database Configuration

Based on new scenarios in our own projects, we decided to clarify the instructions regarding multiple database connections.
With this update, these aspects should become more obvious:

- Which database connection is the default.
- How to switch to another database connection.

## FAQ

**Q: What new features does Dotkernel API v7 introduce?**
A: v7 adds support for UUID v7 using the native UUID data type, support for PostgreSQL, support for PHP 8.5 (API) and 8.4 (Admin), support for a database table prefix, improved database configuration, and replaces the binary data type for id (index) columns in favor of uuid.

**Q: What features were removed in v7?**
A: v7 removes the Evolution pattern's support for Method Deprecation, and drops support for MySQL, primarily because MySQL doesn't support UUID as a data type.

**Q: What package generates the UUIDs, and why?**
A: Dotkernel uses the ramsey/uuid package to generate the UUID before storing it in the database. This gives full control over the UUID version in use, so the application doesn't depend on extensions or a particular database version.

**Q: Which databases support the UUID data type required by v7?**
A: You must use PostgreSQL or MariaDB v10.7 or later to have support for the UUID data type.

**Q: What else changed alongside the move to native UUID?**
A: Table columns previously named `uuid` have been renamed to `id`. The database configuration was also clarified so it's more obvious which connection is the default and how to switch to another database connection.


<!-- ============================================================ -->
<!-- how-to/cors-policy-setup-in-dotkernel-using-mezzio-cors.md -->
<!-- ============================================================ -->

---
title: "CORS policy setup in Dotkernel using mezzio-cors"
description: "A walkthrough of fixing the classic 'No Access-Control-Allow-Origin header' CORS error in a Dotkernel application by installing and configuring the mezzio-cors package."
author: "Alex Karajos"
date_published: "2021-04-28"
canonical_url: "https://www.dotkernel.com/how-to/cors-policy-setup-in-dotkernel-using-mezzio-cors/"
category: "How to's"
language: "en"
---

# CORS policy setup in Dotkernel using mezzio-cors

## TL;DR

This article explains how to fix the common "No 'Access-Control-Allow-Origin' header is present" browser error by installing and configuring the mezzio-cors package.
It covers registering the package's ConfigProvider and middleware, then creating a CORS configuration file.
The configuration supports a permissive mode, where any origin is allowed, and a restrictive mode, where only specific listed origins are allowed.
It also shows how to verify each mode is working correctly.

## Error Message

> Access to fetch at RESOURCE_URL from origin ORIGIN_URL has been blocked by CORS policy: No 'Access-Control-Allow-Origin' header is present on the requested resource.

Most developers have encountered this error when interacting with APIs.
In this article we will run through the steps required to fix it.
Cross-Origin Resource Sharing ([CORS](https://developer.mozilla.org/en-US/docs/Glossary/CORS)) is an [HTTP](https://developer.mozilla.org/en-US/docs/Glossary/HTTP)-header based mechanism that allows a server to indicate any other [origins](https://developer.mozilla.org/en-US/docs/Glossary/Origin) (domain, scheme, or port) than its own from which a browser should permit loading of resources.
The library we are going to use is [Mezzio CORS](https://docs.mezzio.dev/mezzio-cors/).

## Setup

### Install Package Mezzio CORS

Run the following command in your application's root directory:

```bash
composer require mezzio/mezzio-cors
```

### Register ConfigProvider

Open your application's `config/config.php` file and add the following lines to the `$aggregator` variable:

`Laminas\Diactoros\ConfigProvider::class,`

`Mezzio\Cors\ConfigProvider::class,`

### Register Middleware

Open your application's `config/pipeline.php` file and add the following line (preferably between `ErrorHandlerInterface::class` and the handler/middleware that will return your response):

`$app->pipe(CorsMiddleware::class);`

Don't forget to add the corresponding use at the top of the file:

`use Mezzio\Cors\Middleware\CorsMiddleware;`

### Create Config File

Create and open the file `config/autoload/cors.local.php` and add the following code inside it:

```php
<?php

declare(strict_types=1);

use Mezzio\Cors\Configuration\ConfigurationInterface;

return [
    ConfigurationInterface::CONFIGURATION_IDENTIFIER => [
        'allowed_origins' => [
            ConfigurationInterface::ANY_ORIGIN
        ],
        'allowed_headers' => ['Accept', 'Content-Type', 'Authorization'],
        'allowed_max_age' => '600',
        'credentials_allowed' => true,
        'exposed_headers' => [],
    ],
];
```

Note the value `ConfigurationInterface::ANY_ORIGIN` stored under `allowed_origins`.
Leaving this value as is makes your application accessible by any origin (permissive mode).
To restrict access, replace it with a list of origins that should have access to your application (restrictive mode), for example:

```php
'allowed_origins' => ['https://example.com'],
```

Don't forget to make a distributable version of your `config/autoload/cors.local.php` and add that to your repository.

## Testing

Make sure your application sends the Origin header and it is set to the correct value, for example `example.com`.
In your `config/autoload/cors.local.php`:

- when in permissive mode, you should see the expected response from the resource
- when in restrictive mode, if the request origin is not listed under `allowed_origins`, you should see a 403 Not authorized response

## FAQ

**Q: What causes the CORS error described in this article?**
A: It appears when a browser blocks access to a resource on another origin because the server's response doesn't include an 'Access-Control-Allow-Origin' header, per the browser's CORS (Cross-Origin Resource Sharing) policy.

**Q: What package solves CORS handling in Dotkernel?**
A: Mezzio CORS, installed by running `composer require mezzio/mezzio-cors` in the application's root directory.

**Q: What are the setup steps needed to enable CORS?**
A: Register both `Laminas\Diactoros\ConfigProvider::class` and `Mezzio\Cors\ConfigProvider::class` in `config/config.php`, add `$app->pipe(CorsMiddleware::class);` to `config/pipeline.php` (preferably between the error handler and the handler/middleware returning your response), and create a `config/autoload/cors.local.php` file with your CORS configuration.

**Q: What's the difference between permissive and restrictive mode?**
A: In permissive mode, `allowed_origins` is set to `ConfigurationInterface::ANY_ORIGIN`, making the application accessible from any origin.
In restrictive mode, you replace that value with a list of the specific origins that should have access.

**Q: How do you test whether CORS is configured correctly?**
A: Make sure your application sends the Origin header set to the correct value.
In permissive mode you should see the expected response from the resource; in restrictive mode, if the request origin isn't listed under `allowed_origins`, you should see a 403 Not authorized response.


<!-- ============================================================ -->
<!-- how-to/creating-admin-accounts-in-dotkernel-api.md -->
<!-- ============================================================ -->

---
title: "Creating admin accounts in Dotkernel API"
description: "How to create admin accounts in Dotkernel API v3 and later, using either the protected POST /admin endpoint or the admin:create terminal command."
author: "Alex Karajos"
date_published: "2021-07-09"
canonical_url: "https://www.dotkernel.com/how-to/creating-admin-accounts-in-dotkernel-api/"
category: "How to's"
language: "en"
---

# Creating admin accounts in Dotkernel API

## TL;DR

Starting with version 3, Dotkernel API supports dedicated admin accounts.
They can be created either through a protected API endpoint, which lets you assign one or more admin roles and optional names, or through a terminal command, which is quicker but always assigns the default admin role.
Both methods leave you with a ready-to-use admin account.

## Method 1: Using API Endpoint

This action can be performed only by an authenticated admin/superuser.
Once authenticated, call the protected endpoint `POST /admin` with the following JSON body:

```json
{
    "identity": "{IDENTITY}",
    "password": "{PASSWORD}",
    "passwordConfirm": "{PASSWORD}",
    "firstname": "{FIRSTNAME}",
    "lastname": "{LASTNAME}",
    "roles": ["{ROLE_UUID}"]
}
```

after replacing:

- {IDENTITY} with a valid username OR email address
- {PASSWORD} with a valid password
- {ROLE_UUID} with a valid admin role UUID (you can get a list of admin roles by calling the protected endpoint `GET /admin/role`)
- {FIRSTNAME} and {LASTNAME} are optional

Note: you can specify multiple admin roles under the roles key.
If the submitted data is valid, the response will be similar to the below:

```json
{
    "uuid": "d436b044-be36-11eb-9eb1-78f29ef45f43",
    "identity": "Letha_Runolfsson96",
    "firstName": "Oswald",
    "lastName": "Swift",
    "status": "active",
    "roles": ["{ROLE_UUID}"],
    "created": {
        "date": "2021-05-26 17:27:06.194613",
        "timezone_type": 3,
        "timezone": "Europe/Berlin"
    },
    "updated": {
        "date": "2021-05-26 17:27:06.279705",
        "timezone_type": 3,
        "timezone": "Europe/Berlin"
    },
    "_links": {
        "self": {
            "href": "http://localhost:8080/admin/d436b044-be36-11eb-9eb1-78f29ef45f43"
        }
    }
}
```

The new admin account is ready to use.

## Method 2: Using Terminal Command

Run the following command in your application's root directory:

```bash
php ./bin/cli.php admin:create -i {IDENTITY} -p {PASSWORD}
```

or

```bash
php ./bin/cli.php admin:create --identity {IDENTITY} --password {PASSWORD}
```

after replacing:

- {IDENTITY} with a valid username OR email address
- {PASSWORD} with a valid password

Note:

- if the specified identity or password contain special characters, make sure you surround them with double quote signs
- this method does not allow specifying an admin role - newly created accounts will have the role of admin

If the submitted data is valid, the outputted response is:

```
Admin account has been created.
```

The new admin account is ready to use.
You can get more help with this command by running:

```bash
php ./bin/cli.php help admin:create
```

## FAQ

**Q: What are the two ways to create an admin account in Dotkernel API?**
A: You can either call the protected API endpoint `POST /admin` with a JSON body, or run the terminal command `php ./bin/cli.php admin:create`.

**Q: Who can create an admin account via the API endpoint?**
A: This action can be performed only by an authenticated admin/superuser, calling the protected `POST /admin` endpoint.

**Q: What data does the POST /admin request body need?**
A: identity, password, passwordConfirm, and roles (one or more valid admin role UUIDs, obtainable via the protected `GET /admin/role` endpoint).
firstname and lastname are optional.

**Q: What role does an admin get when created via the terminal command?**
A: The terminal command doesn't allow specifying an admin role, so newly created accounts are given the role of admin.

**Q: How do I get more help with the admin:create command?**
A: Run `php ./bin/cli.php help admin:create`.
Also note that if the identity or password contain special characters, they must be surrounded with double quote signs.


<!-- ============================================================ -->
<!-- how-to/database-migrations-and-how-to-use-them.md -->
<!-- ============================================================ -->

---
title: "Database migrations and how to use them"
description: "An overview of using database migrations and seeders in the Dotkernel stack via the 'php dot' command, covering setup, workflow best practices, and the difference between migrations and seeders."
author: "Jesper"
date_published: "2017-08-28"
canonical_url: "https://www.dotkernel.com/how-to/database-migrations-and-how-to-use-them/"
category: "How to's"
language: "en"
---

# Database migrations and how to use them

## TL;DR

Database migrations track schema changes so teams can collaborate without ad hoc, convoluted database change messages and can keep column types consistent across the team.
A package for the Dotkernel stack adds migrations and seeders to the application via a new `php dot` command.
The article walks through adopting migrations in an existing project, running and naming them, and explains how seeders differ from migrations by adding data rather than changing schema.

## Migrations, the Superhero Your Database Deserves

Migrations ease the process of working together on projects, as well as deploying the database changes.
A newly released [package](https://github.com/JapSeyz/Dot-migrations) for the Dotkernel stack integrates migrations and seeders into the application.
This is all done via the newly introduced "php dot" command that's available in the Dotkernel stack.
This article assumes that you're familiar with the basic concepts of migrations.
If you're not, there's an excellent article available [here](https://medium.com/@JapSeyz/database-migrations-and-why-you-should-use-them-11bfde52d7c2).
To recap the article above, a database migration is a change in the database schema.

## Benefits

By using migrations and seeders, you ensure a better workflow for teams, as changes to the database no longer require convoluted messages.
It also ensures that all team members use the same types with the same limits on each column, and someone doesn't have VARCHAR(50) while another has VARCHAR(150).
It keeps the database synchronised throughout the team with minimal effort.
When pushing to production, the deployment script will automatically run the migrations and keep the database schema in sync with the codebase.
It requires no manual SSH'ing into production servers and no risky manual changes to production databases.

## Getting Started

To setup migrations, simply follow the installation instructions in the package provided for Dotkernel.
After the package has been successfully setup, you're ready to go.
To see the available commands, simply write `php dot` in a console that's located in your project root.

## How to Use Migrations in My Project?

Migrations are very easily adapted to any project.

- Existing projects should start by creating a new migration, and mirror the current database design in that file.
  - Backup the database, in case anything unforeseen should happen.
  - After the design has been mirrored, the existing tables should be deleted, and the migrations can be run.

1. Whenever you would normally manually touch the database, make a migration for doing it instead (`php dot make:migration <name>`).
2. Give the migrations reasonable names, so it's easy to see their action, and the DB progression, in the project tree.
3. Run the migrate command, and watch the database automatically generate and run the SQL to update the tables and columns as configured.
4. Enjoy a safe and worry free database that won't suffer from manually touching it.

Notice: migrations are stored in version control, so whenever you pull an update, quickly run `php dot migrate`, as it will only ever migrate new files, and leave out the ones that have been run already.

## Seeders

If you need to add some data to a table, e.g. adding a default admin profile on a fresh installation, this can be done via seeders.
Migrations manage the database layouts, seeders add data to the database.
Seeders can be configured to run every time a certain migration is run, so no matter when you or how you reset your database, it'll make sure that there's always a default admin profile when the CreateAdminTableMigration is run.
Seeders are created the same way as migrations, and also benefit hugely from being given reasonable names that explain what they do.

1. Create the required seeders, one for each table is the best practice, so you can have a "UserTableSeeder" and a "CarTableSeeder" etc.
2. Setup when these seeders should run:
   - When running a migration
   - Via a console command, this is used to seed x amount of rows of (random) data to the database for testing.

## FAQ

**Q: What is a database migration?**
A: A database migration is a change to the database schema.
The Dotkernel stack integrates migrations (and seeders) via a package that adds the "php dot" command to the application.

**Q: What are the benefits of using migrations and seeders?**
A: They keep the database synchronised across the team with minimal effort, so column types and limits stay consistent instead of drifting (e.g. one dev using VARCHAR(50) and another VARCHAR(150)).
Deployment scripts can also run migrations automatically in production, avoiding manual SSH access and risky manual database changes.

**Q: How do I create a new migration?**
A: Run `php dot make:migration <name>`, giving the migration a reasonable name so its action and the database's progression are easy to follow in the project tree.

**Q: What's the difference between migrations and seeders?**
A: Migrations manage the database layout/schema, while seeders add data to the database, such as adding a default admin profile on a fresh installation.

**Q: What happens when I run php dot migrate more than once?**
A: Since migrations are stored in version control, running `php dot migrate` will only ever run new migration files, leaving out the ones that have already been run.

## Acknowledgements

The images in the article show screenshots from [MySQL Workbench](https://www.mysql.com/products/workbench/), and the migration package used is [Phinx](https://phinx.org/).


<!-- ============================================================ -->
<!-- how-to/doctrine-cache-in-mezzio-and-dotkernel.md -->
<!-- ============================================================ -->

---
title: "Doctrine Cache in Mezzio and Dotkernel"
description: "How to configure Doctrine's metadata, query, and result caches (via PhpFileCache) in a Mezzio/Dotkernel application, with usage examples on a query builder and a Doctrine Paginator-based collection."
author: "admin"
date_published: "2020-09-22"
canonical_url: "https://www.dotkernel.com/how-to/doctrine-cache-in-mezzio-and-dotkernel/"
category: "How to's"
language: "en"
---

# Doctrine Cache in Mezzio and Dotkernel

## TL;DR

Running Doctrine ORM in production without any caching strategy wastes CPU cycles regenerating metadata and queries on every request.
This article configures Doctrine's `metadata_cache`, `query_cache`, and `result_cache` through psr/container, using `PhpFileCache` and a default result cache lifetime of 3600 seconds.
It walks through enabling these caches both directly on a query and on a Doctrine Paginator-based collection, with real examples from Dotkernel Admin.
Note: a 2024 follow-up article covers the same topic using Symfony Cache instead.

## Doctrine Caching in Dotkernel

> Following version 2 of doctrine/cache, in 2024 we published an update to this article here: [https://www.dotkernel.com/dotkernel/doctrine-cache-using-symfony-cache/](https://www.dotkernel.com/dotkernel/doctrine-cache-using-symfony-cache/)

Using an ORM in production without any sort of cache strategy is a very bad move.
The database server chokes; lots of CPU cycles wasted only to generate metadata and queries over and over again at each request; the system slows down and so on.
Following [Doctrine documentation](https://www.doctrine-project.org/projects/doctrine-orm/en/latest/reference/caching.html#integrating-with-the-orm), we choose to configure the Doctrine cache system through psr/container.
The main parts we are going to use are `query_cache`, `metadata_cache` and `result_cache`.
As cache type we choose `PhpFileCache` and for result cache we are setting a lifetime of 3600 seconds.

## Configuration

In the file `config/autoload/doctrine.global.php` add the below entry:

```php
'doctrine' =>
        ]
    ],
'resultCacheLifetime' => 3600
```

In the file `config/autoload/local.php` add the below entry in the `doctrine` section:

```php
    'configuration' =>
    ],
```

## Metadata Cache

Your class metadata is being parsed on each request.
Instead of parsing this information we should cache it using one of the cache drivers.
We enabled this by adding the following `metadata_cache` key to our doctrine configuration:

```php
'doctrine' =>
        ]
    ]
```

## Query Cache

It is highly recommended that in a production environment you cache the transformation of a DQL query to its SQL counterpart.
It doesn't make sense to do this parsing multiple times as it doesn't change unless you alter the DQL query.
We enabled this by adding the following `query_cache` key to our doctrine configuration:

```php
'doctrine' =>
        ]
    ]
```

### Usage

```php
$query = $em->createQuery('select u from \Entities\User u');
$query->useQueryCache(true);
```

## Result Cache

The result cache can be used to cache the results of your queries so that doctrine doesn't have to query the database or hydrate the data again after the first time.
We enabled this by adding the following `result_cache` key to our doctrine configuration:

```php
'doctrine' =>
        ]
    ]
```

### Usage

```php
$query = $em->createQuery('select u from \Entities\User u');
$query->enableResultCache();
```

Note: you can set a `lifetime` for how long the result cache should live before it will be rewritten by simply passing the value as the first argument:

```php
$query->enableResultCache($resultCacheLifetime);
```

Note: you can set a custom `ID` for the result cache, which is automatically generated for you if you don't set a custom ID yourself:

```php
$query->enableResultCache($resultCacheLifetime, 'my_custom_id');
```

## Dotkernel Admin Example

Below is the code used in [Dotkernel Admin](https://github.com/dotkernel/admin) in order to [list all Admins](https://github.com/dotkernel/admin/blob/3.0/src/User/src/Repository/AdminRepository.php#L78).
It uses both `query_cache` and `result_cache`.

```php
$qb = $this->getEntityManager()->createQueryBuilder();
$qb->select('admin')
->from(Admin::class, 'admin');

if (!is_null($search)) {
$qb->where($qb->expr()->like('admin.identity', ':search'))
->setParameter('search', '%' . $search . '%');
}

$qb->setFirstResult($offset)
->setMaxResults($limit);
$qb->orderBy('admin.' . $sort, $order);

return $qb->getQuery()->useQueryCache(true)->enableResultCache($this->getCacheLifetime())->getResult();
```

## How to Return Collections

For returning collections that extend Doctrine Paginator (`Doctrine\ORM\Tools\Pagination\Paginator`), just enable result and/or query cache before passing the query builder to the collection:

```php
$qb = $this->getEntityManager()->createQueryBuilder();
$qb->select('collection')
->from(MyCollection::class, 'collection');

$qb->setFirstResult($offset)
->setMaxResults($limit);

$qb->getQuery()->enableResultCache($this->getCacheLifetime())->useQueryCache(true);

return new MyCollection($qb);
```

and the MyCollection class looks like:

```php
<?php

use Doctrine\ORM\Tools\Pagination\Paginator;

/**
* Class MyCollection
* @package Core\Collection
*/
class MyCollection extends Paginator
{
}
```

## FAQ

**Q: Is this article still current?**
A: The article notes that following version 2 of doctrine/cache, an updated version of this article covering Doctrine cache using Symfony Cache was published in 2024.

**Q: Which three Doctrine cache types does this configure?**
A: query_cache, metadata_cache and result_cache, configured through psr/container using PhpFileCache as the cache type.

**Q: What is the default result cache lifetime?**
A: A lifetime of 3600 seconds, set via `resultCacheLifetime` in `config/autoload/doctrine.global.php`.

**Q: How do I enable query cache and result cache in code?**
A: Call `$query->useQueryCache(true)` and `$query->enableResultCache()` on the query object.
`enableResultCache()` can also take a lifetime as its first argument and a custom cache ID as a second argument, otherwise one is auto-generated.

**Q: How should caching be enabled for a Doctrine Paginator-based collection?**
A: Enable result and/or query cache on the query builder's query before passing the query builder into the collection (a class extending `Doctrine\ORM\Tools\Pagination\Paginator`).

## Resources

- [Doctrine Advanced Configuration](https://www.doctrine-project.org/projects/doctrine-orm/en/latest/reference/advanced-configuration.html)
- [Doctrine Caching Documentation](https://www.doctrine-project.org/projects/doctrine-orm/en/latest/reference/caching.html)


<!-- ============================================================ -->
<!-- how-to/generating-a-doctrine-migration-without-dropping-custom-tables.md -->
<!-- ============================================================ -->

---
title: "Generating a doctrine migration without dropping custom tables"
description: "How to run doctrine-migrations diff without generating DROP TABLE statements for unmapped custom tables, using the --filter-expression option."
author: "Alex Karajos"
date_published: "2021-07-29"
canonical_url: "https://www.dotkernel.com/how-to/generating-a-doctrine-migration-without-dropping-custom-tables/"
category: "How to's"
language: "en"
---

# Generating a doctrine migration without dropping custom tables

## TL;DR

When an application has custom, unmapped database tables, running `doctrine-migrations diff` will try to drop them, since no Doctrine entity describes them.
This article shows how to prevent that using the `--filter-expression` option, including how to filter multiple table prefixes at once.
It also flags a Windows PowerShell quirk where the caret in the regex gets stripped, and how to work around it.

## Usage

If your application needs to hold some custom (unmapped) tables in the database, then generating migrations with `doctrine-migrations diff` will try to drop the custom tables.
This article provides a solution on how to avoid dropping those tables.
Run the following command in your application's root directory:

```bash
vendor/bin/doctrine-migrations diff
```

If you have mapping modifications, this will create a new migration file under the `data/doctrine/migrations/` directory.
Opening the migration file, you will notice that it contains some queries that will drop your `oauth_*` tables because they are unmapped (there is no doctrine entity describing them).
You should delete your latest migration with the DROP queries in it, as we will create another one, without the DROP queries in it.
In order to avoid dropping these tables, you need to add a parameter called filter-expression.
The command to be executed without dropping these tables looks like this:

On Windows (use double quotes):

```bash
vendor/bin/doctrine-migrations diff --filter-expression="/^(?!oauth_)/"
```

On Linux/macOS (use single quotes):

```bash
vendor/bin/doctrine-migrations diff --filter-expression='/^(?!oauth_)/'
```

## Filtering Multiple Unmapped Table Patterns

If your database contains multiple unmapped table groups, then the pattern in `filter-expression` should hold all table prefixes concatenated by the pipe character (`|`).
For example, if you need to filter tables prefixed with `foo_` and `bar_`, then the command should look like this:

On Windows:

```bash
vendor/bin/doctrine-migrations diff --filter-expression="/^(?!foo_|bar_)/"
```

On Linux/macOS:

```bash
vendor/bin/doctrine-migrations diff --filter-expression='/^(?!foo_|bar_)/'
```

## Troubleshooting

On Windows, running the command in PowerShell might still add the `DROP TABLE oauth_*` queries to the migration file.
This happens because for PowerShell the caret (`^`) is a special character, so it gets dropped (`"/^(?!oauth_)/"` becomes `"/(?!oauth_)/"` when it reaches your command).
Escaping it will not help either.
In this case, we recommend running the command:

- directly from your IDE
- using Linux shell
- from the Command Prompt

## Help

You can get more help with this command by running:

```bash
vendor/bin/doctrine-migrations help diff
```

## FAQ

**Q: Why does doctrine-migrations diff try to drop custom tables?**
A: Because those tables are unmapped (there's no Doctrine entity describing them), so diff generates queries that drop them when it creates a new migration file.

**Q: How do I avoid dropping unmapped tables when generating a migration?**
A: Delete the migration containing the DROP queries, then re-run the diff command with a filter-expression parameter, e.g. `vendor/bin/doctrine-migrations diff --filter-expression='/^(?!oauth_)/'` on Linux/macOS (single quotes) or with double quotes on Windows.

**Q: How do I filter multiple unmapped table prefixes at once?**
A: Concatenate the table prefixes in the filter-expression pattern with a pipe character, for example `--filter-expression='/^(?!foo_|bar_)/'` to exclude tables prefixed with foo_ and bar_.

**Q: Why might Windows PowerShell still drop the tables even with a filter expression?**
A: PowerShell treats the caret (^) as a special character and strips it, turning "/^(?!oauth_)/" into "/(?!oauth_)/" by the time it reaches the command, and escaping it doesn't help.
The recommended workaround is to run the command from your IDE, a Linux shell, or the Command Prompt instead.


<!-- ============================================================ -->
<!-- how-to/implementation-of-seo-friendly-url-in-an-generic-laminas-mezzio-app.md -->
<!-- ============================================================ -->

---
title: "Implementation of SEO friendly URL in an generic Laminas Mezzio app"
description: "How to add human-readable, SEO-friendly URL slugs to a Mezzio/Doctrine application using the gedmo/doctrine-extensions package."
author: "MarioRadu"
date_published: "2023-06-30"
canonical_url: "https://www.dotkernel.com/how-to/implementation-of-seo-friendly-url-in-an-generic-laminas-mezzio-app/"
category: "How to's"
language: "en"
---

# Implementation of SEO friendly URL in an generic Laminas Mezzio app

## TL;DR

Human-readable URL slugs improve readability, SEO, and shareability compared to raw numeric IDs in URLs.
This article shows how to add slug support to a Mezzio application using the gedmo/doctrine-extensions package.
It covers installing the package via Composer, registering its SluggableListener with Doctrine, and adding a slug column generated from an existing field (such as identity) via the `@Gedmo\Slug` annotation.

Prerequisites:

- [Mezzio App](https://docs.mezzio.dev/)
- [Doctrine](https://www.doctrine-project.org/)

In the vast digital landscape of the internet, where websites compete for attention, having a well-crafted URL can make a significant difference.
By incorporating human-readable slugs into website URLs, we can enhance user experience, improve search engine optimization (SEO), and foster better engagement.
In this article, we discuss the importance, benefits and how to implement human-readable URLs.
The first 3 reasons why we should consider implementing slugs:

- Readability and User-Friendly Experience
- Search Engine Optimization (SEO)
- Shareability and Trustworthiness

## How to Implement Slugs into Dotkernel, a Practical Example

Let's consider we want to implement a feature that gives users the possibility to view other users' profiles.
When viewing another user's profile we have this URL: website.com/user/11, and this doesn't look so appealing, am I right?
So, the solution is to format the URL in a human-readable way, like this: website.com/user/john-doe.
To implement slugs into our codebase we are going to use a popular package, [gedmo/doctrine-extensions](https://packagist.org/packages/gedmo/doctrine-extensions).
First, we need to install the package via composer by running:

```bash
composer require gedmo/doctrine-extensions
```

After installing, we need to register the package's event listener into doctrine.
To do this, add the following code block in your doctrine global configuration.
In our case it would be in the `doctrine.global.php` file.

```php
'doctrine' => [
    'event_manager' => [
        'orm_default' => [
            'subscribers' => [
                Gedmo\Sluggable\SluggableListener::class,
            ]
        ]
    ],
]
```

This is all the configuration you will need, the next step is to create a new database column that will be our slug.
We will add the column in the `src/User/src/Entity/User.php` entity and run the migrations.

```php
use Gedmo\Mapping\Annotation as Gedmo;

...

/**
 * @ORM\Column(name="identity", type="string", length=64, nullable=false, unique=true)
 */
protected string $identity;

/**
 * @ORM\Column(name="slug", type="string", length=64, nullable=false, unique=true)
 * @Gedmo\Slug(fields={"identity"})
 */
protected string $slug;
```

When generating the slug we can specify what field(s) to be used; in our case the slug will be generated using the 'identity' field.
Now you can create a new user and see that the slug column was autocompleted.
To wrap things up, human-readable URLs are a must nowadays, thanks to their swift implementation and multiple benefits.

## FAQ

**Q: What are the benefits of human-readable slugs cited in this article?**
A: Readability and a more user-friendly experience, better search engine optimization (SEO), and improved shareability and trustworthiness of the URL.

**Q: What package is used to generate slugs in this example?**
A: gedmo/doctrine-extensions, installed by running `composer require gedmo/doctrine-extensions`.

**Q: How is the slug listener registered with Doctrine?**
A: By adding `Gedmo\Sluggable\SluggableListener::class` under the `doctrine.event_manager.orm_default.subscribers` configuration, e.g. in `doctrine.global.php`.

**Q: How is the slug field configured on the entity in this example?**
A: A new slug column is added (e.g. to `src/User/src/Entity/User.php`) annotated with `@Gedmo\Slug(fields={"identity"})`, so the slug is generated automatically from the identity field, for example when a new user is created.


<!-- ============================================================ -->
<!-- how-to/installing-almalinux-10-in-wsl2-php-mariadb-composer-phpmyadmin.md -->
<!-- ============================================================ -->

---
title: "Installing AlmaLinux 10 in WSL2: PHP, MariaDB, Composer, PhpMyadmin"
description: "A recipe for setting up a full PHP development environment on AlmaLinux 10 under WSL2, covering installation, requirements, and running applications directly or via virtual hosts."
author: "Florin Bidirean"
date_published: "2025-06-19"
canonical_url: "https://www.dotkernel.com/how-to/installing-almalinux-10-in-wsl2-php-mariadb-composer-phpmyadmin/"
category: "How to's"
language: "en"
---

# Installing AlmaLinux 10 in WSL2: PHP, MariaDB, Composer, PhpMyadmin

## TL;DR

With the release of AlmaLinux OS 10, Dotkernel created a new WSL2 development environment recipe offering performance, security, and hardware improvements over AlmaLinux 9.
The recipe sets up WSL2, AlmaLinux 10, PHP, Apache, MariaDB, Git, Composer, Node.js, and PhpMyAdmin.
It also covers the OS/hardware requirements, installing the distro, and running PHP projects directly or via virtual hosts.

## What You Get

Like for AlmaLinux 9, the WSL recipe sets up the development environment with all the components a regular PHP developer needs:

- WSL2 - Windows Subsystem for Linux.
- AlmaLinux 10 - Free and open source Linux distribution.
- PHP - General-purpose scripting language geared towards web development.
- Apache - Free and open-source cross-platform web server software.
- MariaDB - Community-developed, commercially supported fork of the MySQL relational database management system.
- Git - Distributed version control system.
- Composer - Application-level dependency manager.
- Node.js - JavaScript runtime environment.
- PhpMyAdmin - Open source administration tool for MySQL and MariaDB.

## Requirements

Make sure that you have the [minimum requirements for running WSL2](https://learn.microsoft.com/en-us/windows/wsl/install#prerequisites).
OS-wise you must be running:

- Windows 10:
  - For x64 systems: Version 1903 or later with Build 18362.1049 or later.
  - For ARM64 systems: Version 2004 or later with Build 19041 or later.
- or Windows 11.

Hardware-wise, you need virtualization support.
On some older hardware that supports this feature, it may be disabled from the BIOS.

WSL2 needs the Virtual Machine Platform feature enabled.
You can enable it via PowerShell running as an Administrator:

```bash
dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart
```

## Installing the Distro

Start by downloading and installing the Linux distro with this command:

```bash
wsl --install -d AlmaLinux-10
```

If everything ran ok, you are asked to enter a password at the end.
Next, run each of the [ansible playbook commands](https://docs.dotkernel.org/development/v2/setup/setup-packages/) to install the development components.

## Using WSL2 with AlmaLinux 10

You can start AlmaLinux 10 by executing this command in the Windows Terminal:

```bash
wsl -d AlmaLinux-10
```

Our PHP projects can be run by navigating into the root project folder and running this command:

```bash
php -S 0.0.0.0:8080 -t public
```

Then you need to navigate to `http://localhost:8080` in your preferred browser.

### Running the Application via Virtual Hosts

An easier way to run your applications is via virtual hosts.
The full instructions to set up your virtual hosts are in the [Create virtualhosts page](https://docs.dotkernel.org/development/v2/virtualhosts/create-virtualhost/).

After you set up your virtual hosts and install your project in e.g. the `/var/www/example.localhost/html` folder, you can run the application in the browser by accessing `example.localhost`.

If you run into any issues, make sure to first check the [FAQ page](https://docs.dotkernel.org/development/v2/faq/).
If all else fails, [create an issue](https://github.com/dotkernel/development/issues) with details so the team can help.

## FAQ

**Q: What does this WSL recipe set up?**
A: It sets up a full PHP development environment: WSL2, AlmaLinux 10, PHP, Apache, MariaDB, Git, Composer, Node.js and PhpMyAdmin.

**Q: What are the OS and hardware requirements?**
A: Windows 10 (Version 1903+ / Build 18362.1049+ for x64, or Version 2004+ / Build 19041+ for ARM64) or Windows 11, plus hardware virtualization support.
If needed, enable the Virtual Machine Platform feature via `dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart` in an administrator PowerShell.

**Q: How do I install AlmaLinux 10 via WSL2?**
A: Run `wsl --install -d AlmaLinux-10`, set a password when prompted, then run each of the Ansible playbook commands from the Dotkernel docs to install the development components.

**Q: How do I run a PHP project after setup?**
A: Either run `php -S 0.0.0.0:8080 -t public` from the project root and browse to http://localhost:8080, or, more easily, set up virtual hosts per the Dotkernel docs and access the project at its configured hostname (e.g. example.localhost).

**Q: What should I do if I run into issues during setup?**
A: First check the Dotkernel FAQ page.
If that doesn't resolve it, create an issue on the dotkernel/development GitHub repository with details.

## Resources

- [Full AlmaLinux 10 Installation Instructions](https://docs.dotkernel.org/development/v2/setup/installation/)
- [AlmaLinux 9 in WSL2 with PHP, Mariadb, Composer, PhpMyadmin instructions](https://www.dotkernel.com/php-development/almalinux-9-in-wsl2-install-php-apache-mariadb-composer-phpmyadmin/)


<!-- ============================================================ -->
<!-- how-to/list-available-endpoints-in-dotkernel-api-using-dot-cli.md -->
<!-- ============================================================ -->

---
title: "List available endpoints in Dotkernel API using dot-cli"
description: "How to use dot-cli's route:list command to display, and filter, all available endpoints in a Dotkernel API 3 application."
author: "Alex Karajos"
date_published: "2021-06-29"
canonical_url: "https://www.dotkernel.com/how-to/list-available-endpoints-in-dotkernel-api-using-dot-cli/"
category: "How to's"
language: "en"
---

# List available endpoints in Dotkernel API using dot-cli

## TL;DR

Starting from version 3, Dotkernel API uses the dot-cli package to list all of its available endpoints via the `route:list` command.
The command's output can be filtered by route name, path, or HTTP method, and filters are case-insensitive and combinable.

## Displaying Dotkernel API Endpoints Using dot-cli

Starting from version 3, Dotkernel API uses [dot-cli](https://github.com/dotkernel/dot-cli) to display a list of available endpoints.

## Usage

Run the following command in your application's root directory:

```bash
php ./bin/cli.php route:list
```

The command runs through all routes and extracts endpoint information in realtime.
The output should be similar to the following:

```
+--------+---------------------------------+--------------------------------+
| Method | Name                            | Path                           |
+--------+---------------------------------+--------------------------------+
| PATCH  | account.activate                | /account/activate/{hash}       |
| POST   | account.activate.request        | /account/activate              |
| PATCH  | account.modify-password         | /account/reset-password/{hash} |
| POST   | account.recover-identity        | /account/recover-identity      |
| POST   | account.register                | /account/register              |
| POST   | account.reset-password.request  | /account/reset-password        |
| GET    | account.reset-password.validate | /account/reset-password/{hash} |
| POST   | admin.create                    | /admin                         |
| DELETE | admin.delete                    | /admin/{uuid}                  |
| GET    | admin.list                      | /admin                         |
| PATCH  | admin.my-account.update         | /admin/my-account              |
| GET    | admin.my-account.view           | /admin/my-account              |
| GET    | admin.role.list                 | /admin/role                    |
| GET    | admin.role.view                 | /admin/role/{uuid}             |
| PATCH  | admin.update                    | /admin/{uuid}                  |
| GET    | admin.view                      | /admin/{uuid}                  |
| POST   | error.report                    | /error-report                  |
| GET    | home                            | /                              |
| POST   | security.generate-token         | /security/generate-token       |
| POST   | security.refresh-token          | /security/refresh-token        |
| POST   | user.activate                   | /user/{uuid}/activate          |
| POST   | user.avatar.create              | /user/{uuid}/avatar            |
| DELETE | user.avatar.delete              | /user/{uuid}/avatar            |
| GET    | user.avatar.view                | /user/{uuid}/avatar            |
| POST   | user.create                     | /user                          |
| DELETE | user.delete                     | /user/{uuid}                   |
| GET    | user.list                       | /user                          |
| DELETE | user.my-account.delete          | /user/my-account               |
| PATCH  | user.my-account.update          | /user/my-account               |
| GET    | user.my-account.view            | /user/my-account               |
| POST   | user.my-avatar.create           | /user/my-avatar                |
| DELETE | user.my-avatar.delete           | /user/my-avatar                |
| GET    | user.my-avatar.view             | /user/my-avatar                |
| GET    | user.role.list                  | /user/role                     |
| GET    | user.role.view                  | /user/role/{uuid}              |
| PATCH  | user.update                     | /user/{uuid}                   |
| GET    | user.view                       | /user/{uuid}                   |
+--------+---------------------------------+--------------------------------+
```

## Filtering Results

The following filters can be applied when displaying the routes list:

- Filter routes by name, using: `-i|--name`
- Filter routes by path, using: `-p|--path`
- Filter routes by method, using: `-m|--method`

The filters are case-insensitive and can be combined.

### Example

Let's find which path should one call to register their user account.
For this we will list routes where method is POST and name contains the string register:

```bash
php ./bin/cli.php route:list --method=post --name=register
```

The output is the following:

```
+--------+------------------+-------------------+
| Method | Name             | Path              |
+--------+------------------+-------------------+
| POST   | account.register | /account/register |
+--------+------------------+-------------------+
```

You can get more help with this command by running:

```bash
php ./bin/cli.php route:list --help
```

## FAQ

**Q: What tool does Dotkernel API use to list available endpoints?**
A: Starting from version 3, Dotkernel API uses dot-cli to display a list of available endpoints.

**Q: Which command lists all routes?**
A: Run `php ./bin/cli.php route:list` in your application's root directory.
It runs through all routes and extracts endpoint information in realtime, outputting a table with Method, Name and Path columns.

**Q: How can the route list be filtered?**
A: You can filter routes by name using `-i|--name`, by path using `-p|--path`, or by method using `-m|--method`.
The filters are case-insensitive and can be combined.

**Q: How would you find the endpoint used to register a user account?**
A: By combining the method and name filters: `php ./bin/cli.php route:list --method=post --name=register`, which returns the account.register route mapped to /account/register.

**Q: How do you get more help on this command?**
A: Run `php ./bin/cli.php route:list --help` to get more information about the command.


<!-- ============================================================ -->
<!-- how-to/migrating-dotkernel-3-from-zend-expressive-2-to-zend-expressive-3.md -->
<!-- ============================================================ -->

---
title: "Migrating Dotkernel 3 from Zend Expressive 2 to Zend Expressive 3"
description: "A walkthrough of migrating a Dotkernel 3 application with controller-based middleware from Zend Expressive 2 to Zend Expressive 3, covering dependency, configuration, and pipeline changes."
author: "Gabi DJ"
date_published: "2018-06-13"
canonical_url: "https://www.dotkernel.com/how-to/migrating-dotkernel-3-from-zend-expressive-2-to-zend-expressive-3/"
category: "How to's"
language: "en"
---

# Migrating Dotkernel 3 from Zend Expressive 2 to Zend Expressive 3

## TL;DR

This guide covers migrating a Dotkernel 3 instance from Zend Expressive 2 to Zend Expressive 3, for projects that only contain controller-based middleware.
Old middleware must first be refactored to the `psr/http-server-middleware` interfaces, since Delegates become RequestHandlers.
The steps then cover updating `composer.json` dependencies, registering new ConfigProviders, wrapping `routes.php` and `pipeline.php` in callables, and replacing the old `pipeRoutingMiddleware()`/`pipeDispatchMiddleware()` calls with their PSR-15 equivalents.

## Packages

In `composer.json` replace the matching repositories with the following:

```json
"dotkernel/dot-authentication-service":"^1.0",
"dotkernel/dot-authentication-service":"^1.0",
"dotkernel/dot-authentication-web":"^1.0.1",
"dotkernel/dot-authentication":"^1.0",
"dotkernel/dot-authorization":"^0.1.2",
"dotkernel/dot-controller":"^1.0",
"dotkernel/dot-controller-plugin-authentication":"^1.0",
"dotkernel/dot-controller-plugin-authorization":"^1.0",
"dotkernel/dot-controller-plugin-forms":"^1.0",
"dotkernel/dot-controller-plugin-flashmessenger":"^1.0",
"dotkernel/dot-controller-plugin-mail":"^1.0",
"dotkernel/dot-controller-plugin-session":"^1.0",
"dotkernel/dot-form":"^1.1.1",
"dotkernel/dot-filter":"^1.1.1",
"dotkernel/dot-flashmessenger":"^1.0",
"dotkernel/dot-helpers":"^1.0",
"dotkernel/dot-inputfilter":"^1.1",
"dotkernel/dot-mail":"^1.0",
"dotkernel/dot-mapper":"^1.0",
"dotkernel/dot-navigation":"^1.0",
"dotkernel/dot-rbac-guard":"^1.0",
"dotkernel/dot-session":"^3.0",
"dotkernel/dot-twigrenderer":"^1.1",
"dotkernel/dot-user":"^1.0",
"dotkernel/dot-rbac":"^0.2.1",
"dotkernel/dot-validator":"^1.1",

"zendframework/zend-escaper":"^2.6",
"zendframework/zend-expressive-helpers":"^5.0",
"zendframework/zend-expressive-twigrenderer":"^2.0",
"zendframework/zend-expressive-template":"^2.0",
"zendframework/zend-expressive":"^3.0",
"zendframework/zend-expressive-fastroute":"^3.0",
"zendframework/zend-expressive-tooling":"^1.0",
"zendframework/zend-expressive-router":"^3.0",
"zendframework/zend-stratigility":"^3.0",
"zendframework/zend-component-installer":"^2.0
```

Also update require-dev dependencies:

```json
"zendframework/zend-expressive-tooling:": "^1.0",
"zendframework/zend-component-installer": "^2.0",
```

Remove packages:

- `http-interop/http-middleware`
- `webimpress/http-middleware-compatibility`

## Configurations

### Main Configuration

In `config/config.php` add the following config providers:

```php
// zend expressive & middleware factory
\Zend\Expressive\ConfigProvider::class,

// router config
\Zend\Expressive\Router\ConfigProvider::class,
\Zend\Expressive\Router\FastRouteRouter\ConfigProvider::class,

\Zend\Expressive\Twig\ConfigProvider::class,
\Zend\Expressive\Helper\ConfigProvider::class,

// handler runner
\Zend\HttpHandlerRunner\ConfigProvider::class,
```

Make sure they are the first ConfigProviders or before cached config (`ArrayProvider`).

### Routing

Wrap routing from `config/routes.php` in a callable with the following format:

```php
return function (Application $app, MiddlewareFactory $factory, ContainerInterface $container) : void {
    /** @var \Zend\Expressive\Application $app */
    $app->route('/', , , 'home');
};
```

Add the following use statements and make sure the names are not duplicate:

```php
use Psr\Container\ContainerInterface;
use Zend\Expressive\Application;
use Zend\Expressive\MiddlewareFactory;
```

### Pipeline

Wrap routing from `config/pipeline.php` in a callable with the following format:

```php
return function (Application $app, MiddlewareFactory $factory, ContainerInterface $container) : void {
    /** @var \Zend\Expressive\Application $app */
    $app->route('/', , , 'home');
};
```

Add the following use statements and make sure the names are not duplicate:

```php
use Psr\Container\ContainerInterface;
use Zend\Expressive\Application;
use Zend\Expressive\MiddlewareFactory;
```

#### Routing Middleware Migration

Add the following use statements:

```php
use Zend\Expressive\Router\Middleware\RouteMiddleware;
use Zend\Expressive\Router\Middleware\DispatchMiddleware;
```

Replace the following lines to reflect the changes:

- `$app->pipeRoutingMiddleware();` becomes `$app->pipe(RouteMiddleware::class);`
- `$app->pipeDispatchMiddleware();` becomes `$app->pipe(DispatchMiddleware::class);`

You can check the complete guides and example files from the following links:

- [Migration guide for Dotkernel Frontend](https://github.com/dotkernel/frontend/tree/master/docs)
- [Migration guide for Dotkernel Admin](https://docs.dotkernel.org/admin-documentation/) (the old `github.com/dotkernel/admin/tree/master/docs` folder has since moved to this documentation site)

## FAQ

**Q: What should you read before starting the migration?**
A: For a better understanding of the migration and how it affects support, it's recommended to read Zend Expressive's article on migration regarding HTTP interop.

**Q: What happens to old middleware during the migration?**
A: If a project contains old middleware, it must be refactored to reflect the interfaces provided in the psr/http-server-middleware package.
As part of this, Delegates become RequestHandlers, using interfaces from the psr/http-server-handler package.

**Q: Which packages should be removed during migration?**
A: `http-interop/http-middleware` and `webimpress/http-middleware-compatibility` should be removed from `composer.json`.

**Q: What needs to be added to the main configuration file?**
A: In `config/config.php`, several ConfigProviders need to be added - for Zend Expressive, the router, FastRoute router, Twig, helpers, and the handler runner - and they must be the first ConfigProviders or placed before the cached config (`ArrayProvider`).

**Q: How do the routes.php and pipeline.php files change?**
A: Routing from `config/routes.php` and the pipeline from `config/pipeline.php` both need to be wrapped in a callable of the form `function (Application $app, MiddlewareFactory $factory, ContainerInterface $container)`, with the corresponding use statements added.

**Q: What replaces pipeRoutingMiddleware() and pipeDispatchMiddleware()?**
A: `$app->pipeRoutingMiddleware();` becomes `$app->pipe(RouteMiddleware::class);`, and `$app->pipeDispatchMiddleware();` becomes `$app->pipe(DispatchMiddleware::class);`.


<!-- ============================================================ -->
<!-- how-to/replacing-dot-console-with-dot-cli-based-on-laminas-cli.md -->
<!-- ============================================================ -->

---
title: "Replacing dot-console with dot-cli based on laminas-cli"
description: "How to install and configure dot-cli, Dotkernel's laminas-cli based replacement for the abandoned dot-console package, including its built-in FileLocker locking system."
author: "Alex Karajos"
date_published: "2021-06-09"
canonical_url: "https://www.dotkernel.com/how-to/replacing-dot-console-with-dot-cli-based-on-laminas-cli/"
category: "How to's"
language: "en"
---

# Replacing dot-console with dot-cli based on laminas-cli

## TL;DR

Dotkernel's dot-cli package replaces dot-console, which was abandoned after Laminas dropped the laminas-console package it was based on.
Setting it up involves requiring the package via Composer, registering its ConfigProvider, and copying its bootstrap and config files into the application.
It also ships with FileLocker, a built-in, enabled-by-default locking system that prevents overlapping calls to the same command.

## Implementing dot-cli in Your Application

Dotkernel's [dot-cli](https://github.com/dotkernel/dot-cli) package comes as a replacement for [dot-console](https://github.com/dotkernel/dot-console), which was abandoned after Laminas abandoned their [laminas-console](https://github.com/laminas/laminas-console) package, that dot-console was based on.

## Setup

### Install Package

Run the following command in your application's root directory:

```bash
composer require dotkernel/dot-cli
```

### Register ConfigProvider

Open your application's `config/config.php` file and add `Dot\Cli\ConfigProvider::class,` under the DK packages comment.

### Create Bootstrap File

Locate the provided `vendor/dotkernel/dot-cli/bin/cli.php` and copy it into your application's `bin` directory.
This is the file you will execute your commands through.

### Create Config File

Locate the provided `vendor/dotkernel/dot-cli/config/autoload/cli.global.php` and copy it into your application's `config/autoload` directory.
This file already contains a sample command (`demo:command`), that serves as an example on creating and registering new commands.
For more information on configuring/chaining commands, see the [laminas-cli documentation](https://docs.laminas.dev/laminas-cli/).

## Usage

Run the following command in your application's root directory:

```bash
php ./bin/cli.php
```

The output should look similar to this, containing information on how to start using dot-cli:

```
Dotkernel CLI 1.0.0

Usage:
  command

Options:
  -h, --help            Display help for the given command. When no command is given display help for the list command
  -q, --quiet           Do not output any message
  -V, --version         Display this application version
      --ansi            Force ANSI output
      --no-ansi         Disable ANSI output
  -n, --no-interaction  Do not ask any interactive question
  -v|vv|vvv, --verbose  Increase the verbosity of messages: 1 for normal output, 2 for more verbose output and 3 for debug

Available commands:
  help          Display help for a command
  list          List commands
 demo
  demo:command  Demo command description.
```

## Set Up Command as Cronjob

Open your crontab and add the following line:

```bash
* * * * {PATH_TO_PHP_EXECUTABLE} {PATH_TO_APPLICATION}/bin/cli.php demo:command
```

Where {PATH_TO_PHP_EXECUTABLE} needs to be replaced with the full path to the PHP executable and {PATH_TO_APPLICATION} with the full path to your application's root directory.

## FileLocker

dot-cli has a built-in locking system, called FileLocker, enabled by default.
This feature prevents multiple calls to the same command overlapping each other by making sure the latter calls won't run until the former one is finished.
You can toggle this by modifying the previously created `config/autoload/cli.global.php` under `FileLockerInterface::class -> enabled`.

## FAQ

**Q: Why was dot-console replaced by dot-cli?**
A: dot-console was abandoned after Laminas abandoned its laminas-console package, which dot-console was based on, so dot-cli was created as its replacement.

**Q: How do you install dot-cli in an application?**
A: Run `composer require dotkernel/dot-cli` in the application's root directory, then register `Dot\Cli\ConfigProvider::class,` in `config/config.php`, and copy the provided `bin/cli.php` bootstrap file and `config/autoload/cli.global.php` config file into the application.

**Q: What does the provided cli.global.php config file contain?**
A: It already contains a sample command (`demo:command`) that serves as an example on how to create and register new commands.

**Q: How do you run a dot-cli command as a cronjob?**
A: Add a line to your crontab such as `* * * * {PATH_TO_PHP_EXECUTABLE} {PATH_TO_APPLICATION}/bin/cli.php demo:command`, replacing the placeholders with the full path to the PHP executable and the full path to the application's root directory.

**Q: What is FileLocker?**
A: FileLocker is a built-in locking system in dot-cli, enabled by default, that prevents multiple calls to the same command from overlapping by making sure later calls won't run until the earlier one finishes.
It can be toggled in `config/autoload/cli.global.php` under `FileLockerInterface::class -> enabled`.


<!-- ============================================================ -->
<!-- how-to/using-postman-for-documentation-in-dotkernel-api-3.md -->
<!-- ============================================================ -->

---
title: "Using Postman for documentation in Dotkernel API 3"
description: "A walkthrough of using Postman to create, maintain, and export API documentation for Dotkernel API 3, including collections, environments, requests, and built-in security features."
author: "Alex Karajos"
date_published: "2021-06-14"
canonical_url: "https://www.dotkernel.com/how-to/using-postman-for-documentation-in-dotkernel-api-3/"
category: "How to's"
language: "en"
---

# Using Postman for documentation in Dotkernel API 3

## TL;DR

Starting from version 3.0, Dotkernel API documents its endpoints using Postman, via a provided collection and environment file that get imported into the tool.
Postman organizes work into a Workspace, Collections, Environments, and Requests, and the Dotkernel API collection ships with built-in security: global Bearer Token authorization inherited from the collection root, and automatic ACCESS_TOKEN/REFRESH_TOKEN storage on the Admin/Security and User/Security folders.
After making changes, the collection and environment files can be re-exported to overwrite the application's documentation files.

## Using Postman Documentation in Dotkernel API 3

Starting from version 3.0 Dotkernel API provides its documentation using [Postman](https://www.postman.com/).
In this article we will go into the details of creating and maintaining your application's documentation.

## Prerequisites

In order to follow the steps, you will need the following:

- a working installation of Dotkernel API 3
- download and install Postman from their [download page](https://www.postman.com/downloads/)

TIP: If you don't have a Postman account, we recommend you to create one.
This way Postman is able to backup your workspace in the cloud and synchronize it across multiple devices.

## Introduction

For better understanding on how Postman works, we need to run through the "building blocks" of Postman:

- Workspace: is the main container that holds all your collections, APIs, environments etc
- Collection: holds all requests and dependencies of a project (for example Dotkernel API's collection containing all requests)
- Environment: holds a set of environment-specific variables (for example Dotkernel API's environment file containing the application URL specific to the development environment)
- Request: the definition of an API endpoint, including request method, name, description, URL, body, parameters and an example

There are more terms to cover, like Mock servers, Monitors etc but they are not relevant yet in our case.

### Importing Documentation Files

Open Postman (and log in if you have an account), then follow the below steps:

- open the import modal by clicking `File` -> `Import` (or `Ctrl + O`)
- inside the modal, make sure you're on the `File` tab, then click `Upload files`
- navigate to `documentation` directory of your Dotkernel API 3 application and select both of the following files:
  - Dotkernel_API.postman_collection.json
  - Dotkernel_API.postman_environment.json
- after clicking `Open` the modal should show the following:

```
Select files to import . 2/2 selected
NAME                 FORMAT                         IMPORT AS
Dotkernel_API        Postman Collection v2.1        Collection
Dotkernel_API        Postman Environment            Environment
```

- at the bottom of the import modal, clicking `Import` will import the selected files and close the modal.

Under My Workspace you should see a tab called Collections.
Clicking on it should display all your collections, one of them called `Dotkernel_API`.
This collection holds all of the provided requests and serves as the documentation of your application.
Dotkernel API 3 collection and environment files are now imported and ready to use.
For more information on importing files into Postman, please consult their [docs](https://learning.postman.com/docs/getting-started/importing-and-exporting-data/).

### Interacting with the Environment

On the top right corner of Postman, you'll see the Environment quick look button (it looks like an eye).
On its left side, there's a dropdown with all available environments, one of them being called `Dotkernel_API` - click on it to set it as the active environment.
After this, clicking the Environment quick look button will bring up a modal containing all variables found in the environment:

```
Dotkernel_API                                                                              Edit
VARIABLE               INITIAL VALUE                CURRENT_VALUE
APPLICATION_URL        http://localhost:8080        http://localhost:8080
```

If your application runs on a different host/port, click the Edit button to modify the initial/current value of the `APPLICATION_URL` variable.
Once in Edit mode, you can also create new variables.
You only have to enter the variable name and its initial value - current value will be automatically filled in when the variable is used.

## Usage

### Creating a New Request

Inside the collection, right-click on any folder and click `Add Request`.
The new request is automatically opened in a new tab, where you will:

- enter request name by replacing New Request with a short and descriptive name
- enter request description (first button under the Environment quick look button)
- enter request URL - you should use the already existing variable `APPLICATION_URL` by wrapping it in double curly braces, then append the request path.
Example: `{{ APPLICATION_URL }}/test` becomes `http://localhost:8080/test` when you send the request.
- select request method
- (optionally) inspect tabs:
  - Params: manage query parameters
  - Authorization: select authorization type
  - Headers: manage request headers
  - Body: manage request body
  - Pre-request script: provide JavaScript that Postman should run before sending the request
  - Tests: provide JavaScript that Postman should run after receiving the response
  - Settings: manage miscellaneous request settings
- save the request using the Save button (or `Ctrl + S`)

### Sending a Request

Once opened, you can immediately send a request by clicking the Send button.
Optionally, you can save the response as an example (click on Save Response, then select Save as example), so other developers will have a visual representation of the response without making a request.
This opens a new tab, where you can manage the example.

## Features

The collection provided by Dotkernel API 3 comes with some built-in security features.

### Global Security

Due to the hierarchy of the Collection, all requests are children of the Collection's root folder, so they automatically inherit its Authorization settings.
If you edit the Collection's root folder, you will find the following tabs:

- Authorization
  - Type is set to `Bearer Token`
  - Token reads the environment variable `ACCESS_TOKEN`
- Pre-request Script: here you can add JavaScript that should run on ALL requests before they run
- Tests: here you can add JavaScript that should run on ALL requests after their response is returned
- Variables: here you can manage global variables

To disable this feature globally, set Authorization Type to `No Auth` or whatever value suits your application's requirements.
To disable this feature at folder/request level, edit the folder/request and set Type to `No Auth` under the Authorization tab.

### Automatic Token Storage

Once an authorization token is re/generated, two environment variables are set/updated:

- `ACCESS_TOKEN`: the token that gets sent in the Authorization header
- `REFRESH_TOKEN`: the token required to regenerate an ACCESS_TOKEN

This is achieved by applying the following modifications to both Admin/Security and User/Security folders:

- setting Type to `No Auth` under the Authorization tab (because the child requests under these folders should not send Authorization header)
- adding a script under the Tests tab, that reads the response and - if successful - set/updates the above mentioned environment variables

## Exporting Documentation

TIP: You can inspect your application's documentation at any moment by clicking on the three horizontal dots (you will find them on hover next to your collection's name) then click on View documentation.

### Exporting Collection

Click on the same three horizontal dots, then select Export.
You will be presented an Export collection modal asking you to choose the format of the export.
Unless specified, choose the recommended version, then click Export.
When asked to save the exported file, choose to overwrite your application's collection file (documentation/Dotkernel_API.postman_collection.json).

### Export Environment

This step is optional.
It is needed only if you made modifications to the environment, else you can skip it.
Start by clicking on the Environment quick look button, then click Edit.
Once the edit environment tab opens, locate the three horizontal dots next to the Share button on the right of the Postman window.
Click them and select Export.
When asked to save the exported file, choose to overwrite your application's environment file (documentation/Dotkernel_API.postman_environment.json).

## FAQ

**Q: What are Postman's main "building blocks"?**
A: Workspace (the main container holding all collections, APIs and environments), Collection (holds all requests and dependencies of a project, such as Dotkernel API's collection), Environment (holds environment-specific variables, like the application URL), and Request (the definition of an API endpoint, including method, name, description, URL, body, parameters and an example).

**Q: How do you import Dotkernel API's documentation files into Postman?**
A: Open the import modal via `File -> Import` (or `Ctrl + O`), go to the `File` tab, click `Upload files`, then select both `Dotkernel_API.postman_collection.json` and `Dotkernel_API.postman_environment.json` from the application's `documentation` directory, and click `Import`.

**Q: What variable controls which host/port the requests target?**
A: The `APPLICATION_URL` environment variable, found under the `Dotkernel_API` environment, defaults to `http://localhost:8080` and can be edited via the Environment quick look button if the application runs on a different host/port.

**Q: What built-in security features does the collection provide?**
A: Global security: all requests inherit Bearer Token authorization (reading the `ACCESS_TOKEN` environment variable) from the Collection's root folder, which can be disabled globally or per folder/request.
Automatic token storage: the Admin/Security and User/Security folders use Test scripts to set/update the `ACCESS_TOKEN` and `REFRESH_TOKEN` environment variables whenever a token is re/generated.

**Q: How do you export the collection after making changes?**
A: Click the three horizontal dots next to the collection's name, select Export, choose the recommended format, click Export, and overwrite the application's collection file (documentation/Dotkernel_API.postman_collection.json).


<!-- ============================================================ -->
<!-- how-to/using-the-urlgenerator-work-in-fastroute.md -->
<!-- ============================================================ -->

---
title: "Using the URLGenerator work in FastRoute"
description: "A how-to on avoiding FastRoute's slash-suffix quirk when declaring routes in Dotkernel 3, and on referencing routes by name via the URLGenerator in controllers and Twig views."
author: "Jesper"
date_published: "2017-09-04"
canonical_url: "https://www.dotkernel.com/how-to/using-the-urlgenerator-work-in-fastroute/"
category: "How to's"
language: "en"
---

# Using the URLGenerator work in FastRoute

## TL;DR

Dotkernel 3 uses FastRoute under the hood, which is fast but has a quirk around slash-suffixes that a wrong route setup can trigger, leading to hard-to-diagnose errors.
Optional slashes must be kept inside the optional block of a route definition, or the URLGenerator ends up producing the wrong route.
Every named route can then be referenced instead of hard-coded, using `$this->url()` in controllers or the `path()` function in Twig views.

## Declaring Routes

When defining routes in the `routes.php` file, they need to follow a specific pattern, a usual route would look like this:

```php
$app->route('/page', , , 'page');
```

> Notice the '/page' part, as this is crucial. FastRoute cannot handle a slash-suffix, which means that /page will give you the indexAction, whereas /page/ will give you a 404.

To prevent the URLGenerator from adding a slash-suffix, we need to make sure that the optional slash is included in the optional block.
The above example is correct; if we instead wrote it like this, it'd be woefully bad:

```php
$app->route('/page/', , , 'page');
```

> Notice that the slash has changed places and is now outside the optional block. This would generate a /page/ route for the index action, which is bad, so always include any optional parts, even slashes, in the optional block.

## Referencing Routes

Developers are used to hand-write and hard-code URLs into anchor tags, but this is a bad idea, as a URL may change and then you'd have to go through the entire app to find every single reference for it.
Instead, every route we define has a name that can be used to reference it in the URLGenerator.

```php
$app->route('/page', , , 'page');
```

> That very last part there, that's the route name, which can be referenced in any view or controller to generate a route to a specific route in the app.

To use it in a controller, you have access to `$this->url();`, which takes the route name, in this case, 'page', as the first parameter, and then any optional blocks as the second parameter.
A controller redirect may then look like this:

```php
return new RedirectResponse($this->url('contact', ));
```

Using the URLGenerator in views is approximately the same, since you have access to the global `path()` method.
The path method works the same way as the `url()` method, and takes the route name as the first parameter, and any optional blocks as its second parameter.
This is of course done in Twig, so we need to put curly brackets around it since it's dynamic and not static HTML.
It could look like this:

```
{{ path(name: 'page', parameters: {action: 'thank-you'}, relative: false) }}
```

## FAQ

**Q: What is a common quirk to watch out for when declaring routes in FastRoute?**
A: FastRoute cannot handle a slash-suffix: for a route defined as `/page`, requesting /page works, but /page/ gives a 404.
Any optional part, including slashes, needs to be included inside the optional block, not appended outside it - otherwise the URLGenerator ends up producing the wrong route for the index action.

**Q: Why should route names be used instead of hard-coded URLs?**
A: Hand-writing and hard-coding URLs into anchor tags is a bad idea because a URL may change and then every reference throughout the app would need to be updated.
Instead, every defined route has a name that can be referenced through the URLGenerator.

**Q: How do you generate a URL from a route name inside a controller?**
A: Use `$this->url()`, passing the route name as the first parameter and any optional blocks as the second parameter, for example in a redirect: `return new RedirectResponse($this->url('contact'));`.

**Q: How do you generate a URL from a route name inside a Twig view?**
A: Use the global `path()` function, which works the same way as `url()`, taking the route name as the first parameter and any optional blocks as the second parameter, wrapped in curly brackets since it's dynamic Twig code.


<!-- ============================================================ -->
<!-- how-to/what-is-cross-origin-token-redemption.md -->
<!-- ============================================================ -->

---
title: "What is cross origin token redemption?"
description: "An explanation of cross-origin token redemption, the technique for securely verifying and redeeming a token issued on one domain when it's used on another, including how JWT and OAuth 2.0 implement it."
author: "Alex Karajos"
date_published: "2023-01-27"
canonical_url: "https://www.dotkernel.com/how-to/what-is-cross-origin-token-redemption/"
category: "How to's"
language: "en"
---

# What is cross origin token redemption?

## TL;DR

Cross-origin token redemption verifies the security and authenticity of a token issued on one domain but used on another, which is common when a logged-in user needs to access resources on a different site.
The receiving domain checks the token's signature and decrypts it before trusting it.
JWT and OAuth 2.0 are two standards that implement this pattern, each with a different verification flow.

Cross-origin token redemption is a technique used to ensure the security and authenticity of a token that is issued by one website or domain, but intended for use on a different website or domain.
This process is commonly used in situations where a user needs to access resources from multiple domains, such as when a user is logged in to one website and needs to access resources from another website.
When a token is issued from one domain, it is typically encrypted and signed to prevent tampering and ensure that it can only be used by the intended recipient.
When the token is redeemed on a different domain, the receiving domain must first verify the authenticity of the token by checking the signature and decrypting the token.

## JSON Web Token (JWT)

One common method of cross-origin token redemption is to use the JWT standard.
JWTs are a compact, URL-safe means of representing claims to be transferred between two parties.
They consist of three parts:

- `header`: it contains information about the token, including the algorithm used to sign it
- `payload`: it contains the claims, which are the pieces of information that the token is intended to convey
- `signature`: is used to verify that the token has not been tampered with

In order to redeem a JWT on a different domain, the receiving domain must first verify the signature using the algorithm specified in the header and the secret key that was used to sign the token.
Once the signature is verified, the domain can then read the claims from the payload to determine if the user is authorized to access the requested resources.

## OAuth 2.0

Another method of cross-origin token redemption is to use the OAuth 2.0 standard.
OAuth 2.0 is an open standard for authorization that enables a third-party application to obtain limited access to an HTTP service.
In this method, when a user is logged in to one website and wants to access resources from another website, the first website will redirect the user to the second website and pass a token.
The second website will then validate the token and provide the user with access to the requested resources.

In summary, cross-origin token redemption is a technique used to ensure the security and authenticity of a token that is issued by one website or domain, but intended for use on a different website or domain.
This is achieved by verifying the signature of the token and decrypting it and by using standards like JWT or OAuth 2.0.

## FAQ

**Q: What is cross-origin token redemption?**
A: It is a technique used to ensure the security and authenticity of a token that is issued by one website or domain but intended for use on a different website or domain, commonly used when a user needs to access resources from multiple domains.

**Q: What are the three parts of a JSON Web Token (JWT)?**
A: A JWT consists of a header (information about the token, including the signing algorithm), a payload (the claims, i.e. the pieces of information the token conveys), and a signature (used to verify the token has not been tampered with).

**Q: How does a receiving domain verify a JWT?**
A: The receiving domain first verifies the signature using the algorithm specified in the header and the secret key used to sign the token, then reads the claims from the payload to determine if the user is authorized to access the requested resources.

**Q: How does OAuth 2.0 handle cross-origin token redemption?**
A: OAuth 2.0 is an open standard for authorization enabling a third-party application limited access to an HTTP service. When a user logged in to one website wants to access resources on another, the first website redirects the user to the second and passes a token, which the second website validates before granting access.


<!-- ============================================================ -->
<!-- how-to/what-is-psr-7-and-how-to-use-it.md -->
<!-- ============================================================ -->

---
title: "What is PSR-7 and how to use it"
description: "A practical reference to PSR-7's HTTP message interfaces and a cheatsheet-style walkthrough of working with headers and message bodies using Zend Diactoros."
author: "Gabi DJ"
date_published: "2017-05-15"
canonical_url: "https://www.dotkernel.com/how-to/what-is-psr-7-and-how-to-use-it/"
category: "How to's"
language: "en"
---

# What is PSR-7 and how to use it

## TL;DR

PSR-7 defines a set of common interfaces from the PHP Framework Interop Group for representing HTTP messages and URIs, and any application built on those interfaces is a PSR-7 application.
This article lists the PSR-7 interfaces as a cheatsheet, then walks through practical examples using Zend Diactoros: adding, appending, reading, and removing HTTP headers, and reading, writing, appending, and prepending content to a PSR-7 message body via its stream interface.

PSR-7 is a set of common interfaces defined by PHP Framework Interop Group.
These interfaces are representing HTTP messages, and URIs for use when communicating trough HTTP.
Any web application using this set of interfaces is a PSR-7 application.
More about interfaces and interfaces examples can be found [here](http://php.net/manual/language.oop5.interfaces.php).

## Interfaces

In this section the Interfaces methods will be listed.
The purpose of this list is to help in finding the methods when working with PSR-7.
This can be considered as a cheatsheet for PSR-7 interfaces.
The interfaces defined in PSR-7 are the following:

| Class Name | Description |
|---|---|
| [`Psr\Http\Message\MessageInterface`](http://www.php-fig.org/psr/psr-7/#psrhttpmessagemessageinterface) | Representation of a HTTP message |
| [`Psr\Http\Message\RequestInterface`](http://www.php-fig.org/psr/psr-7/#psrhttpmessagerequestinterface) | Representation of an outgoing, client-side request. |
| [`Psr\Http\Message\ServerRequestInterface`](http://www.php-fig.org/psr/psr-7/#psrhttpmessageserverrequestinterface) | Representation of an incoming, server-side HTTP request. |
| [`Psr\Http\Message\ResponseInterface`](http://www.php-fig.org/psr/psr-7/#psrhttpmessageresponseinterface) | Representation of an outgoing, server-side response. |
| [`Psr\Http\Message\StreamInterface`](http://www.php-fig.org/psr/psr-7/#psrhttpmessagestreaminterface) | Describes a data stream |
| [`Psr\Http\Message\UriInterface`](http://www.php-fig.org/psr/psr-7/#psrhttpmessageuriinterface) | Value object representing a URI. |
| [`Psr\Http\Message\UploadedFileInterface`](http://www.php-fig.org/psr/psr-7/#psrhttpmessageuploadedfileinterface) | Value object representing a file uploaded through an HTTP request. |

## Working with PSR-7

The following examples will illustrate how basic operations are done in PSR-7.
Zend Diactoros is an implementation for PSR-7 interfaces.
It will be used to illustrate these examples.
Installation guide for Zend Diactoros: [Zend Diactoros Documentation – Installation](https://zendframework.github.io/zend-diactoros/install/)

> All other PSR-7 implementations should have the same behaviour.

Alternative [PSR-7 implementations](https://packagist.org/search/?q=psr7%20implementation).

To use the `Zend Diactoros` classes add this at the beggining of the php file:

```php
use Zend\Diactoros\ServerRequestFactory;
use Zend\Diactoros\Response;
// autoloading
$request = ServerRequestFactory::fromGlobals($_SERVER, $_GET, $_POST, $_COOKIE, $_FILES);
$response = new Response();
```

> Note: The article applies to all PSR-7 implementations from this point forward.

## Working with HTTP Headers

#### Adding Headers to Response

```php
$response->withHeader('My-Custom-Header', 'My Custom Message');
```

#### Appending Values to Headers

```php
$response->withAddedHeader('My-Custom-Header', 'The second message');
```

#### Checking if Header Exists

```php
$response->hasHeader('My-Custom-Header'); // will return true
```

> Note: My-Custom-Header was only added in the Response

#### Getting Comma-Separated Values from a Header (Also Applies to Request)

```php
// getting value from request headers
$request->getHeaderLine('Content-Type'); // will return: "text/html; charset=UTF-8"
// getting value from response headers
$response->getHeaderLine('My-Custom-Header'); // will return:  "My Custom Message; The second message"
```

#### Getting Array of Value from a Header (Also Applies to Request)

```php
// getting value from request headers
$request->getHeader('Content-Type'); // will return:
// getting value from response headers
$response->getHeader('My-Custom-Header'); // will return:
```

#### Removing Headers from HTTP Messages

```php
// removing a header from Request, removing deprecated "Content-MD5" header
$request->withoutHeader('Content-MD5');
// removing a header from Response
// effect: the browser won't know the size of the stream
// the browser will download the stream till it ends
$response->withoutHeader('Content-Length');
```

## Working with HTTP Message Body

When working with the PSR-7 there are two methods of implementation:

#### 1. Getting the Body Separately

> This method makes the body handling easier to understand and is useful when repeatedly calling body methods. (You only call `getBody()` once). Using this method mistakes like `$response->write()` are also prevented.

```php
$body = $response->getBody();
// operations on body, eg. read, write, seek
// ...
// replacing the old body
$response->withBody($body);
// this last statement is optional as we working with objects
// in this case the "new" body is same with the "old" one
// the $body variable has the same value as the one in $request, only the reference is passed
```

#### 2. Working Directly on Response

> This method is useful when only performing few operations as the `$request->getBody()` statement fragment is required

```php
$response->getBody()->write('hello');
```

## Getting the Body Contents

The following snippet gets the contents of a stream contents.

> Note: Streams must be rewinded, if content was written into streams, it will be ignored when calling `getContents()` because the stream pointer is set to the last character, which is end of stream.

```php
$body = $response->getBody();
$body->rewind(); // or $body->seek(0);
$bodyText = $body->getContends();
```

> Note: If `$body->seek(1)` is called before `$body->getContents()`, the first character will be ommited as the starting pointer is set to `1`, not `0`. This is why using `$body->rewind()` is recommended.

## Append to Body

```php
$response->getBody()->write('Hello'); // writing directly
$body = $request->getBody(); // which is a `StreamInterface`
$body->write('xxxxx');
```

## Prepend to Body

Prepending is different when it comes to streams.
The content must be copied before writing the content to be prepended.
The following example will explain the behaviour of streams.

```php
// assuming our response is initially empty
$body = $repsonse->getBody();
// writing the string "abcd"
$body->write('abcd');
// seeking to start of stream
$body->seek(0);
// writing 'ef'
$body->write('ef'); // at this point the stream contains "efcd"
```

#### Prepending by Rewriting Separately

```php
// assuming our response body stream only contains: "abcd"
$body = $response->getBody();
$body->rewind();
$contents = $body->getContents(); // abcd
// seeking the stream to beginning
$body->rewind();
$body->write('ef'); // stream contains "efcd"
$body->write($contents); // stream contains "efabcd"
```

> Note: `getContents()` seeks the stream while reading it, therefore if the second `rewind()` method call was not present the stream would have resulted in `abcdefabcd` because the `write()` method appends to stream if not preceeded by `rewind()` or `seek(0)`.

#### Prepending by Using Contents as a String

```php
$body = $response->getBody();
$body->rewind(); // or $body->seek(0);
$bodyText = $body->getContends();
```

More information can be found in the [PSR-7 article](https://www.php-fig.org/psr/psr-7/) in Dotkernel3 documentation portal.

Sources: [PSR-7: HTTP messages](http://www.php-fig.org/psr/psr-7/), [zend-diactoros](https://zendframework.github.io/zend-diactoros/)

## FAQ

**Q: What is PSR-7?**
A: PSR-7 is a set of common interfaces defined by the PHP Framework Interop Group, representing HTTP messages and URIs for use when communicating through HTTP. Any web application using this set of interfaces is a PSR-7 application.

**Q: What interfaces does PSR-7 define?**
A: PSR-7 defines MessageInterface (representation of an HTTP message), RequestInterface (an outgoing, client-side request), ServerRequestInterface (an incoming, server-side HTTP request), ResponseInterface (an outgoing, server-side response), StreamInterface (a data stream), UriInterface (a URI value object), and UploadedFileInterface (a file uploaded through an HTTP request).

**Q: What implementation is used to illustrate the PSR-7 examples?**
A: Zend Diactoros is used as the PSR-7 implementation for the examples, though the article notes that all other PSR-7 implementations should have the same behaviour.

**Q: How do you add or check headers on a response?**
A: Use `$response->withHeader('My-Custom-Header', 'My Custom Message')` to add a header, `$response->withAddedHeader(...)` to append another value to it, and `$response->hasHeader('My-Custom-Header')` to check whether it exists.

**Q: Why must a stream be rewound before reading its contents?**
A: If content was written into a stream, calling `getContents()` without first calling `$body->rewind()` (or `$body->seek(0)`) will return nothing, because the stream pointer is left at the end of the stream after writing.


<!-- ============================================================ -->
<!-- javascript/codelobster-php-edition-free-php-html-css-javascript-editor-ide.md -->
<!-- ============================================================ -->

---
title: "Codelobster PHP Edition - Free PHP, HTML, CSS, JavaScript editor (IDE)"
description: "An overview of Codelobster PHP Edition, a free multi-language code editor with autocompletion, debugging, SQL and FTP tools, and plugins for popular PHP frameworks and CMS platforms."
author: "Stas"
date_published: "2013-09-26"
canonical_url: "https://www.dotkernel.com/javascript/codelobster-php-edition-free-php-html-css-javascript-editor-ide/"
category: "Javascript"
language: "en"
---

# Codelobster PHP Edition - Free PHP, HTML, CSS, JavaScript editor (IDE)

## TL;DR

Codelobster PHP Edition is a free, lightweight IDE that highlights and autocompletes mixed PHP, HTML, CSS, and JavaScript code, including HTML5 and CSS3.
It also bundles an HTML/CSS inspector, a PHP debugger, an SQL manager, FTP support, and a portable mode that needs no installation.
On top of that, it ships plugins for popular CMS platforms and PHP frameworks such as Drupal, Joomla, CakePHP, CodeIgniter, Symfony, Yii, WordPress, and Smarty.

## Free PHP, HTML, CSS, JavaScript Editor (IDE) - Codelobster PHP Edition

For valuable work on creation of sites you need a good comfortable editor necessarily.
There are many requiring paid products for this purpose, but we would like to select free of charge very functional and at the same time of simple in the use editor - [Codelobster PHP Edition](http://www.codelobster.com/).

Let us consider some important possibilities and advantages of this program:

- All code highlights depending on a type, the also mixed code is thus supported, so the area of HTML will be highlighted as HTML, PHP as PHP, and Javascript as Javascript in a the same file.
Thre is possibility of choice from color schemes, including popular IDEs.
- Powerful autocompletion for HTML, PHP, CSS and Javascript, including HTML5 and CSS3.
For PHP the structure of project is fully recognized, and the complete list of methods falls out in the proper places.
- HTML/CSS inspector on the type of Firebug, which allows easily to correlate the selected elements of page with a code and proper style.
- Context help on all supported languages.
By pressing F1 key the page with detailed description for current tag, attribute or function will be opened.
- PHP debugger. PHP debugger allows to execute PHP scripts incrementally, watching the values of all variables in every line.
- SQL manager allows to produce all necessary actions with a database - to add, delete, edit a structure and records in tables, to export data, execute SQL queries.
Highlighting and autocompletion works for SQL files also.
- Support of FTP allows to work straight with a remote server and to do all necessary changes with files.
- The portable option allows to use editor without the preliminary installation.
- Other useful utilities: pair highlighting, possibility of blocks selection, collapsing, tooltips, navigation on descriptions of functions and included files at withholding of the key of CTRL, viewing of structure of files and project, preview in a browser, book-marks, and all other standard possibilities for work with a code.

### Also There Are Special Plugins for Work With

- CMS: Drupal, Joomla
- PHP frameworks: CakePHP, CodeIgniter, Symfony, Yii
- JavaScript libraly: JQuery
- WordPress blogging engine
- Smarty template engine

[http://www.codelobster.com](http://www.codelobster.com)

## FAQ

**Q: What kind of code highlighting does Codelobster PHP Edition support?**
A: It highlights code depending on its type, even within a mixed file, so HTML, PHP and Javascript sections are each highlighted according to their own language, with a choice of color schemes including those of popular IDEs.

**Q: What frameworks and CMS does Codelobster PHP Edition have plugins for?**
A: There are plugins for the Drupal and Joomla CMS, the CakePHP, CodeIgniter, Symfony and Yii PHP frameworks, the JQuery JavaScript library, the WordPress blogging engine, and the Smarty template engine.

**Q: What other tools does the editor include besides autocompletion and highlighting?**
A: It includes an HTML/CSS inspector similar to Firebug, context help (F1 opens documentation for the current tag, attribute or function), a PHP debugger for incremental execution with variable watching, an SQL manager for database operations, FTP support for working directly on a remote server, and a portable option that requires no installation.


<!-- ============================================================ -->
<!-- javascript/intro-to-jquery.md -->
<!-- ============================================================ -->

---
title: "Intro to jQuery"
description: "A short introduction to jQuery basics for early Dotkernel developers switching from Dojo, covering the jQuery object, selectors, DOM manipulation, events, and Ajax."
author: "Adrian"
date_published: "2011-06-01"
canonical_url: "https://www.dotkernel.com/javascript/intro-to-jquery/"
category: "Javascript"
language: "en"
---

# Intro to jQuery

## TL;DR

Starting with Dotkernel's 1.5 release, the framework switched from Dojo to jQuery, and this post is a quick primer on jQuery basics.
It covers the jQuery (`$`) object and CSS-style selectors, chaining methods to manipulate matched elements, binding events like click, and making Ajax calls with `$.get()` and `$.getJSON()`.

Starting with the 1.5 release, Dotkernel will make the switch from Dojo to jQuery.
On jQuery's website, there's an excellent "[Getting started with jQuery tutorial](http://docs.jquery.com/Tutorials:Getting_Started_with_jQuery)", as well as a extensive [documentation](http://api.jquery.com/) for the framework, so I'll just go over a few basic concepts and common examples.

## The jQuery Object

jQuery is the global object that contains all of jQuery's functionality.
You will probably want to use $ instead which is a synonim of the same object, only faster to type.
It contains a few useful methods such as [jQuery.map](http://api.jquery.com/jQuery.map/), but it's mostly used with a selector parameter to retrieve a set of matched elements.

## Selectors

jQuery supports the same selectors as CSS (note: all selectors will work even in browsers that don't actually have CSS support for them)

### Examples

```javascript
// the element that matches an id
$("#someId");
// all elements with a certain class
$(".someClass")
// all odd rows from a certain table
$("table#monthlyStats tbody tr:nth-child(odd)")
```

The results of these expressions is a jQuery object that contains one, more, or no matched elements.

## Manipulating Matched Elements

There are a number of functions that can be applied to a jQuery object, for example:

```javascript
$("input#username").addClass("error")
```

Since most of these functions will also return the same jQuery object, they can be chained.
For example, the following expression will set the text of the #errors element and fade it in:

```javascript
$("#errors").text("The was an eror").fadeIn()
```

## Events

Adding events in Javascript instead of using "onclick" attributes in HTML means that the markup is much cleaner, and you get better support for more events in all browsers.
In the following example, a click event is attached to an element.
The function that will be called when the event is fired (callback) is passed as an argument to the click function

```javascript
$("#helpButton").click(function(){
    $("#helpMessage").show()
});
```

## Ajax

jQuery has [many ajax helper functions](http://api.jquery.com/category/ajax/), here is a simple example that will replace the contents of an element with data loaded from the server:

```javascript
$.get("get-news.php", function(result){
   $("#news").html(result)
})
```

## Putting It All Together

The following snippet can be used on a registration form to check whether the username already exists, before the form is submitted.

```javascript
$(document).ready(
  $("input#username").blur(function(){
    $.getJSON(
      "/check-username.php",
      {
         username:$("input#username").val()
      },
      function(data){
        if (data.taken === true){
          $("input#username").addClass("taken")
        }else{
          $("input#username").removeClass("taken")
        }
      }
  });
);
```

## FAQ

**Q: Why is Dotkernel switching to jQuery?**
A: Starting with the 1.5 release, Dotkernel makes the switch from Dojo to jQuery.

**Q: What is the jQuery object, and what is $?**
A: jQuery is the global object that contains all of jQuery's functionality. $ is a synonym for the same object that's faster to type, and is mostly used with a selector parameter to retrieve a set of matched elements.

**Q: What selectors does jQuery support?**
A: jQuery supports the same selectors as CSS, and these selectors work even in browsers that don't natively support them, for example `$("#someId")`, `$(".someClass")`, or `$("table#monthlyStats tbody tr:nth-child(odd)")`.

**Q: How do you attach a click event to an element?**
A: Pass a callback function to the `click` function on a jQuery selection, for example: `$("#helpButton").click(function(){ $("#helpMessage").show() });`. This keeps markup cleaner than using "onclick" attributes in HTML.

**Q: How does jQuery handle Ajax requests?**
A: jQuery provides ajax helper functions such as `$.get()` and `$.getJSON()`, for example loading data from the server and replacing an element's contents with `$.get("get-news.php", function(result){ $("#news").html(result) })`.


<!-- ============================================================ -->
<!-- javascript/javascript-email-validator.md -->
<!-- ============================================================ -->

---
title: "Javascript: Email Validator"
description: "A regex-based fix for email validation that allows the plus (+) and dash (-) characters in the appropriate parts of an email address."
author: "admin"
date_published: "2008-10-03"
canonical_url: "https://www.dotkernel.com/javascript/javascript-email-validator/"
category: "Javascript"
language: "en"
---

# Javascript: Email Validator

## Problem

Email validation should allow the dash (-) character anywhere in an email address or domain, and the plus (+) character in the username (many people use it for categorization, especially on Gmail).

## Solution

```javascript
var regex = new RegExp("^+(\.+)*@+(\.+)*\.({2,})$","i");
```

This will also validate emails like `username1+username2@gmail-domain.co.uk`.

## FAQ

**Q: What problem does this email validator solve?**
A: Common email regex patterns fail to allow the plus (+) character in the username and the dash (-) character anywhere in the address or domain, even though both are commonly used (plus for categorization on Gmail, dash in domain names).

**Q: What is the suggested regex solution?**
A: The regular expression `^+(\.+)*@+(\.+)*\.({2,})$` (case-insensitive) that permits both characters in the appropriate parts of the address.

**Q: What kind of email addresses does this regex validate?**
A: Addresses like `username1+username2@gmail-domain.co.uk`, combining a plus-separated username with a dashed domain.


<!-- ============================================================ -->
<!-- licensing/mit-versus-lgpl-in-practice-dotkernel-case.md -->
<!-- ============================================================ -->

---
title: "MIT versus LGPL in practice: Dotkernel case"
description: "How Dotkernel handled discovering an LGPL v3 dependency in one of its MIT-licensed packages."
author: "Florin Bidirean"
date_published: "2024-04-15"
canonical_url: "https://www.dotkernel.com/licensing/mit-versus-lgpl-in-practice-dotkernel-case/"
category: "Licensing"
language: "en"
---

# MIT versus LGPL in practice: Dotkernel case

## TL;DR

Dotkernel discovered that an upstream dependency, matomo/device-detector, was licensed under LGPL v3 - a more restrictive license than the MIT license Dotkernel uses for its own projects.
Because the more restrictive license would have to apply to the whole application, Dotkernel implemented a workaround: it stopped bundling that dependency by default and documented the licensing implications.

## Detailing the problem

The package in question, [matomo/device-detector](https://github.com/matomo-org/device-detector), requires developers to share their derivative code publicly (LGPL v3).
This conflicted with Dotkernel's contractual obligations to keep client code business and enterprise friendly, and risked legal issues.

## The solution

Dotkernel decided to discard the use of third-party packages licensed under LGPL v3.
The matomo/device-detector package had been used in [dotkernel/dot-user-agent-sniffer](https://github.com/dotkernel/dot-user-agent-sniffer) to identify the user agent and use the results in internal reports.

All of [Dotkernel's](https://github.com/dotkernel) packages are licensed under MIT, which has no restrictions on the source code other than keeping the license and copyright notice in a file within each package.
Other non-restrictive licenses deemed acceptable (used by some dependencies instead of MIT) include Apache-2.0, BSD-2-Clause, BSD-3-Clause, ISC, MPL-2.0 and OSL-3.0.

## The resolution

Starting with version 3.4.0, the dotkernel/dot-user-agent-sniffer package must follow the LGPL v3 license.
The [admin application](https://github.com/dotkernel/admin) will not use the features from matomo/device-detector, but will contain instructions on how to add the package for developers who intend to use it.

## Important note

Any application using dotkernel/dot-user-agent-sniffer with a version lower than 3.4.0 is still a legal liability.
Dotkernel will not abandon the issue, and is looking into a solution to bring back the device detector functionality in the future under a less restrictive license.
For now, dotkernel/dot-user-agent-sniffer is not included in any Dotkernel application by default.

## FAQ

**Q: Why did Dotkernel need a workaround for this package?**
A: An analysis found that matomo/device-detector was licensed under LGPL v3, which requires sharing derivative code publicly.
Since Dotkernel projects use MIT, the more restrictive license would have to apply to the whole application, conflicting with contractual obligations to keep client code business friendly.

**Q: Where was the LGPL v3 package being used?**
A: In Dotkernel's dot-user-agent-sniffer package, to identify the user agent and use the results in internal reports.

**Q: What solution did Dotkernel adopt?**
A: Discarding the use of third-party LGPL v3 packages.
All Dotkernel packages are MIT licensed, and other acceptable non-restrictive licenses include Apache-2.0, BSD-2-Clause, BSD-3-Clause, ISC, MPL-2.0 and OSL-3.0.

**Q: What changed in dot-user-agent-sniffer as a result?**
A: Starting with version 3.4.0 it must follow LGPL v3.
The admin application will not use matomo/device-detector's features, but will document how to add it for developers who want it.

**Q: Is it still risky to use an older version of dot-user-agent-sniffer?**
A: Yes - any application using a version lower than 3.4.0 is still a legal liability.
Dotkernel will not include the package in its applications by default while it looks for a less restrictive replacement.

## Resources

- [LGPL v3 license](https://opensource.org/license/lgpl-3-0)
- [MIT license](https://opensource.org/license/mit)
- [matomo/device-detector](https://github.com/matomo-org/device-detector)
- [dotkernel/dot-user-agent-sniffer](https://github.com/dotkernel/dot-user-agent-sniffer)
- [Dotkernel GitHub organization](https://github.com/dotkernel)
- [Dotkernel admin application](https://github.com/dotkernel/admin)
- [Rob Allen: Check the licenses of your Composer dependencies](https://akrabat.com/check-licenses-of-composer-dependencies/)


<!-- ============================================================ -->
<!-- middleware/dotkernel-light-improvements-psr-15-handlers-vite-phpstan.md -->
<!-- ============================================================ -->

---
title: "Dotkernel Light improvements: PSR-15 Handlers, Vite, PHPStan"
description: "An overview of recent improvements to Dotkernel Light: migrating to PSR-15 handlers, adopting Vite, switching to PHPStan, and other smaller updates."
author: "Florin Bidirean"
date_published: "2025-05-02"
canonical_url: "https://www.dotkernel.com/middleware/dotkernel-light-improvements-psr-15-handlers-vite-phpstan/"
category: "Middleware"
language: "en"
---

# Dotkernel Light improvements: PSR-15 Handlers, Vite, PHPStan

## TL;DR

[Dotkernel Light](https://github.com/dotkernel/light) is a PSR-15 compliant application built on Mezzio and Laminas, aimed at simple websites like presentation sites.
Since its last update, it has moved from controllers to PSR-15 handlers, adopted Vite as its bundler, replaced Psalm with PHPStan, and picked up several smaller improvements.

## Migrating from controllers to handlers

dotkernel/dot-controller isn't going away, but Dotkernel Light has switched to PSR-15 handlers instead.
PSR-7 defines the request handler as an individual component that processes a request and produces a response; since the request can be filtered or augmented in a middleware architecture by the time it reaches custom code, handlers split code into more manageable chunks and a cleaner file structure, and make it easier to understand an application's functionality.

## Implementing PSR-15 compatible handlers

PSR-15, defined by the PHP Framework Interop Group, specifies common interfaces for HTTP server request handlers and middleware that use HTTP messages as described by PSR-7.
The MVC design pattern is considered obsolete by respected members of the PHP community, so Dotkernel Light is replacing it with the middleware and HTTP message design pattern.

## Adopting a naming pattern for PSR-15 handlers

A naming pattern was devised for PSR-15 handlers that highlights the method, resource, and action for each file, so navigation and onboarding are easier.

## Implementing Vite

[Vite](https://vite.dev/) replaces [webpack](https://webpack.js.org) as the static modules bundler.
It concatenates and compresses `.css` and `.js` files for faster downloads, and preprocesses `.scss` files into `.css`.
Vite was configured to work similarly to webpack for existing Light developers; the migration was justified by easier dependency management and execution speed, and it's highly recommended by the PHP community.

## Replacing Psalm with PHPStan

Both Psalm and PHPStan are respected, widely-used static analysis tools.
Some big names in the PHP ecosystem made the same switch, so Dotkernel followed suit.
Functionality is similar to the previous tool, but growing interest and improved detection quality made PHPStan the better choice.
PHPStan is configured to run at rule level 8 to help prevent bugs and write better code.

## Other updates

- Adding support for PHP 8.4.
- Enabling PHPStan and Qodana to run for PHP 8.4 as well.
- Cleaning up and adapting the error configuration file to make use of the latest features.
- Updating laminas/laminas-coding-standard to the latest major version.
- Updating composer.json to be up-to-date with the latest releases for each dependency, and removing obsolete items.
- Implementing a more reliable and efficient post-install script.
- Removing dotkernel/dot-twigrenderer in favor of a direct implementation of mezzio/mezzio-twigrenderer.

## FAQ

**Q: Why did Dotkernel Light switch from controllers to handlers?**
A: Handlers split code into more manageable chunks and a cleaner file structure, and make it easier to understand an application's functionality, especially given that requests can be filtered or augmented by middleware before reaching custom code.

**Q: What naming pattern is used for the new PSR-15 handlers?**
A: One that highlights the method, resource, and action for each handler file, so file names reflect functionality at a glance.

**Q: Why was Vite adopted instead of webpack?**
A: For easier dependency management and execution speed, and because it's highly recommended by the PHP community; it was configured to work similarly to webpack for existing developers.

**Q: Why was Psalm replaced with PHPStan?**
A: Growing interest and improved detection quality, following the lead of other big names in the PHP ecosystem; PHPStan runs at rule level 8.

**Q: What other smaller updates were made to Dotkernel Light?**
A: PHP 8.4 support, PHPStan/Qodana running on PHP 8.4, error configuration cleanup, an updated coding standard, refreshed composer.json dependencies, a more reliable post-install script, and removal of dot-twigrenderer in favor of mezzio-twigrenderer directly.

## Resources

- [Dotkernel Light Git](https://github.com/dotkernel/light)
- [Dotkernel Light demo](https://light.dotkernel.net/)
- [Dotkernel Light documentation](https://docs.dotkernel.org/light-documentation/)
- [PHP Framework Interop Group](https://www.php-fig.org/)
- [PSR-15: HTTP Server Request Handlers](https://www.php-fig.org/psr/psr-15/)
- [Static Analysis – Replacing Psalm with PHPStan](https://www.dotkernel.com/php-development/static-analysis-replacing-psalm-with-phpstan/)


<!-- ============================================================ -->
<!-- middleware/handling-dynamic-routing-using-fastroute-in-dotkernel.md -->
<!-- ============================================================ -->

---
title: "Handling dynamic routing using FastRoute in Dotkernel"
description: "How Dotkernel moved from static, hard-coded route declarations to a dynamic, centralized routing configuration."
author: "Florin Bidirean"
date_published: "2025-02-26"
canonical_url: "https://www.dotkernel.com/middleware/handling-dynamic-routing-using-fastroute-in-dotkernel/"
category: "Middleware"
language: "en"
---

# Handling dynamic routing using FastRoute in Dotkernel

## TL;DR

This article, the first in a series about switching from controllers to PSR-15 compliant handlers, explains how Dotkernel replaced its static, hard-coded route declarations with a centralized, dynamic configuration in `local.php`.
The change is aimed at static pages only - any method other than GET (post, put, delete) returns a 405 status code.

## The old way of doing things

Routes were declared in a `RoutesDelegator.php` file present in the `src` folder of each module, with entries like:

```php
$app->get('/page', , 'page');
```

This route serves urls like `/page/about` or `/page/who-we-are`.
Each entry required:

- A **method**, such as `get`, aimed at static pages.
- A **path** used to direct execution to a handler, such as `/page`, which also uses the optional `action` parameter.
- A **handler** to execute, such as `GetPageViewHandler`, designed to display static pages out of the box but expandable as needed.
- A unique **route name**, such as `page`, referenceable for redirects or authorization.

In a live application the route list can grow to many entries across areas like product list, product details, checkout, contact us, reports, order history, and blog - grouped into modules, meaning a routing error could require digging through multiple RoutesDelegators.

## The new approach

The update centralizes route configuration in `config/autoload/local.php`, under a `routes` array.
`RoutesDelegator.php` reads this configuration and generates the routes, so it doesn't need to be touched most of the time:

```php
$routes = $container->get('config') ?? [];
foreach ($routes as $prefix => $moduleRoutes) {
    foreach ($moduleRoutes as $routeUri => $templateName) {
    $app->get(
        sprintf('/%s/%s', $prefix, $routeUri),
        GetPageViewHandler::class,
        sprintf('%s::%s', $prefix, $templateName)
    );
    }
}
```

Under the `routes` array: the module name (e.g. `page`) is the top-level key, the key (e.g. `about`) builds the page's path, and the value (e.g. `about`) is the template file.
This supports `/page/about` and `/page/who-we-are`.

## Advanced configuration

The same versatility as before is retained:

1. **Change the template**: replace `$template = $request->getAttribute(RouteResult::class)->getMatchedRouteName();` with a fixed template, like `$template = 'my-template';`.
2. **Change the URL for SEO** (e.g. `/page/about` to `/about`): remove the `$moduleName` parameter from `sprintf('/%s/%s', $moduleName, $routeUri)`, making it `sprintf('/%s', $routeUri)` - carefully, to avoid breaking other routes.
3. **Change the URL segment**: edit `'about' => 'about',` to `'about-us' => 'about',` in `local.php`, changing the url to `/page/about-us` while still using the `about` template.
4. **Add a dynamic parameter**: edit `'about' => 'about',` to `'about/{id}' => 'about',`, supporting urls like `/page/about/us`, `/page/about/company`, `/page/about/123`, and read the value in the handler with `$request->getAttribute('id')`.

## FAQ

**Q: What is the goal of this dynamic routing update?**
A: To replace static, hard-coded route declarations with a more dynamic, centralized implementation that is easier to set up and review.

**Q: How were routes configured in the old, static approach?**
A: In a per-module `RoutesDelegator.php` file, with hard-coded entries specifying a method, path, handler, and route name.

**Q: How does the new approach centralize route configuration?**
A: Route data moves into a `routes` array in `config/autoload/local.php`, which `RoutesDelegator.php` reads to generate routes automatically.

**Q: What do the entries under the routes array represent?**
A: The module name, the URL path segment (key), and the template file to render (value).

**Q: Can routes still be customized beyond the default setup?**
A: Yes - templates, URL structure, URL segments, and dynamic parameters can all still be adjusted.

**Q: Does this update support methods other than GET?**
A: No - it targets static pages only; other HTTP methods return a 405 status code.

## Resources

- [Dotkernel Light](https://github.com/dotkernel/light)
- [Dotkernel Light Routing How-to](https://docs.dotkernel.org/light-documentation/v1/how-tos/routing/)
- [FastRoute](https://github.com/nikic/FastRoute)


<!-- ============================================================ -->
<!-- middleware/replacing-controllers-with-psr-15-compliant-handlers-in-dotkernel-light.md -->
<!-- ============================================================ -->

---
title: "Replacing controllers with PSR-15 compliant handlers in Dotkernel Light"
description: "Why and how Dotkernel Light replaced its controllers with PSR-15 compliant handlers, including a worked GetPageViewHandler example."
author: "Florin Bidirean"
date_published: "2025-03-03"
canonical_url: "https://www.dotkernel.com/middleware/replacing-controllers-with-psr-15-compliant-handlers-in-dotkernel-light/"
category: "Middleware"
language: "en"
---

# Replacing controllers with PSR-15 compliant handlers in Dotkernel Light

## TL;DR

The goal of this update is to implement [PSR-15](https://www.php-fig.org/psr/psr-15/) handlers into [Dotkernel Light](https://github.com/dotkernel/light), keeping the application up-to-date with recommended design guidelines, secure, and aligned with standards widely adopted by the PHP community.

## What makes handlers better than controllers?

Handlers split code into manageable chunks instead of one large controller file with several actions, following the first SOLID principle (Single-responsibility).
SOLID stands for:

- S - Single-responsibility Principle
- O - Open-closed Principle
- L - Liskov Substitution Principle
- I - Interface Segregation Principle
- D - Dependency Inversion Principle

With single-responsibility, handlers separate each action into its own class, which makes them easier to maintain, refactor, and test. Expanding an application is easier too - rather than searching for a place to fit new code into a controller, you simply create a new handler.
Refactoring is simpler because there's less code to worry about breaking, and tests only need to inject or bind mocks for a single action per handler instead of covering multiple branches.

## How to implement the Page handler

Replacing controllers with handlers in Dotkernel Light means the `dot-controller` package is no longer needed and can be removed, along with any existing Controllers.

For Dotkernel Light, most of the old Controller's actions were combined under a single Handler, `GetPageViewHandler`, since they all performed the same task - displaying static content.
The only exception is `IndexHandler.php`, which was kept separate but is set up similarly.

Handlers are registered in each module's `ConfigProvider`, mapping factories under `getDependencies()`.
Add `GetPageViewHandler` under the `factories` key and remove any reference to `PageController`:

```php
public function getDependencies(): array
{
    return [
        ...,
        'factories'  => [ ... ],
        'aliases'    => [ ... ],
    ];
}
```

`GetPageViewHandlerFactory.php` adds the template renderer as a dependency, making it available in the handler.
`PageControllerFactory.php` is no longer needed and can be deleted:

```php
<?php

declare(strict_types=1);

namespace Light\Page\Factory;

use Light\Page\Handler\GetPageViewHandler;
use Mezzio\Template\TemplateRendererInterface;
use Psr\Container\ContainerExceptionInterface;
use Psr\Container\ContainerInterface;
use Psr\Container\NotFoundExceptionInterface;

use function assert;

class GetPageViewHandlerFactory
{
    /**
     * @param class-string $requestedName
     * @throws NotFoundExceptionInterface
     * @throws ContainerExceptionInterface
     */
    public function __invoke(ContainerInterface $container, string $requestedName): GetPageViewHandler
    {
        $template = $container->get(TemplateRendererInterface::class);
        assert($template instanceof TemplateRendererInterface);

        return new GetPageViewHandler($template);
    }
}
```

`GetPageViewHandler.php` determines the template file name from the route name and displays it.
No dynamic elements are included, since it deals only with static pages.
`PageController.php` can be deleted:

```php
<?php

declare(strict_types=1);

namespace Light\Page\Handler;

use Laminas\Diactoros\Response\HtmlResponse;
use Mezzio\Router\RouteResult;
use Mezzio\Template\TemplateRendererInterface;
use Psr\Http\Message\ResponseInterface;
use Psr\Http\Message\ServerRequestInterface;
use Psr\Http\Server\RequestHandlerInterface;

class GetPageViewHandler implements RequestHandlerInterface
{
    public function __construct(
        protected TemplateRendererInterface $template,
    ) {
    }

    public function handle(ServerRequestInterface $request): ResponseInterface
    {
        $template = $request->getAttribute(RouteResult::class)->getMatchedRouteName();

        return new HtmlResponse(
            $this->template->render($template)
        );
    }
}
```

These are the bare essentials to get started with handlers for a website that displays static pages.

## FAQ

**Q: What is the goal of replacing controllers with PSR-15 handlers?**
A: Keeping Dotkernel Light up-to-date with recommended design guidelines, secure, and aligned with PHP community standards.

**Q: What makes handlers better than controllers?**
A: They apply the Single-responsibility Principle, splitting actions into their own classes, which makes them easier to maintain, refactor, expand, and test.

**Q: Do you still need the dot-controller package?**
A: No - it can be removed along with any existing Controllers once handlers replace them.

**Q: How is GetPageViewHandler set up?**
A: Registered as a factory in the module's ConfigProvider (replacing PageController), with GetPageViewHandlerFactory injecting the template renderer, and the handler resolving the template from the matched route name.

**Q: Does every action need its own separate handler?**
A: Not necessarily - in Dotkernel Light most static-page actions were combined into one handler, with only IndexHandler.php kept separate; other applications may need to split actions across multiple handlers.

## Resources

- [PSR-15](https://www.php-fig.org/psr/psr-15/)
- [Dotkernel Light](https://github.com/dotkernel/light)
- [PR for replacing controllers with handlers](https://github.com/dotkernel/light/pull/33)
- [Mezzio features](https://docs.mezzio.dev/mezzio/v3/getting-started/features/)


<!-- ============================================================ -->
<!-- php-development/almalinux-9-in-wsl2-install-php-apache-mariadb-composer-phpmyadmin.md -->
<!-- ============================================================ -->

---
title: "AlmaLinux 9 in WSL2 : install PHP, Apache, MariaDB, Composer, PhpMyadmin"
description: "A step-by-step guide to installing AlmaLinux 9 under Windows Subsystem for Linux (WSL2) and provisioning it with Ansible to run PHP, Apache, MariaDB, Composer, and phpMyAdmin."
author: "Alex Karajos"
date_published: "2022-12-14"
canonical_url: "https://www.dotkernel.com/php-development/almalinux-9-in-wsl2-install-php-apache-mariadb-composer-phpmyadmin/"
category: "PHP Development"
language: "en"
---

# AlmaLinux 9 in WSL2 : install PHP, Apache, MariaDB, Composer, PhpMyadmin

## TL;DR

This guide shows how to install AlmaLinux 9 through Windows Subsystem for Linux (WSL2) and provision it with an Ansible-driven installer script that sets up PHP, Apache, MariaDB, Composer, and phpMyAdmin.
It covers verifying WSL2 readiness, installing the AlmaLinux 9 distribution from the Microsoft Store, running the two-step Ansible installer (with a required restart in between), and confirming the setup through Apache's homepage, a PHP info page, and phpMyAdmin.

In this article we will demonstrate how we install AlmaLinux 9 using Windows Subsystem for Linux (WSL2).
First, you need to check if your machine is ready for using WSL2.
Open Windows Terminal and execute the following command:

```bash
wsl -v
```

The output should look similar to this:

```
WSL version: 2.2.4.0
Kernel version: 5.15.153.1-2
WSLg version: 1.0.61
MSRDC version: 1.2.5326
Direct3D version: 1.611.1-81528511
DXCore version: 10.0.26091.1-240325-1447.ge-release
Windows version: 10.0.22631.3737
```

If instead of the above output, you get an error, it means that WSL is not (completely) installed on your machine.
In this case, please follow the instructions found in [this guide](https://docs.dotkernel.org/development/v1/setup/installation/), then return to this page and continue with the next step.

## Download and Install AlmaLinux 9

Open Microsoft Store and search for `AlmaLinux`.
From the results, select `AlmaLinux 9` and install it.
Once installed, clicking on *Open* will open it in Windows Terminal.

The installer will prompt you for your *username*, your *password* and *password confirmation*.

## Setup AlmaLinux 9

While still in the AlmaLinux 9 terminal, start executing the following commands.

Install required packages:

```bash
sudo dnf install epel-release dnf-utils http://rpms.remirepo.net/enterprise/remi-release-9.rpm -y
```

Update installed packages:

```bash
sudo dnf upgrade -y
```

Install Ansible:

```bash
sudo dnf install ansible -y
```

Clone our development environment setup package:

```bash
git clone https://github.com/dotkernel/development.git
```

Navigate to the directory with the Ansible recipes:

```bash
cd ~/development/wsl/
```

Using your preferred text editor, open config.yml where you must fill in the empty fields.
Save and close the file.

Run Step 1 of the installer script (it will prompt you for the password you entered during the installation process):

```bash
ansible-playbook -i hosts install.yml --ask-become-pass
```

Restart AlmaLinux 9:

- press `Control` + `d`
- Open Windows Terminal
- stop AlmaLinux 9 by executing `wsl -t AlmaLinux9`
- start AlmaLinux 9 by executing `wsl -d AlmaLinux9`

Navigate back to the directory with the Ansible recipes:

```bash
cd ~/development/wsl/
```

Run Step 2 of the installer script (once again, it will prompt you for the password you entered during the installation process):

```bash
ansible-playbook -i hosts install.yml --ask-become-pass
```

Once finished, the installation is complete, your AlmaLinux 9 development environment is ready to use.

## Test AlmaLinux 9

Check if everything works by opening in your browser:

- http://localhost/ - Apache's default home page
- http://localhost/info.php - PHP info page
- http://localhost/phpmyadmin/ - PhpMyAdmin (login with username root + the root password you configured in config.yml under mariadb -> root_password)

The complete guide with additional features is available [here](https://docs.dotkernel.org/development/).

## FAQ

**Q: How do I check if my machine is ready for WSL2?**
A: Open Windows Terminal and run `wsl -v`. If it returns version information (WSL, Kernel, WSLg, MSRDC, Direct3D, DXCore, Windows versions), WSL2 is installed. If you get an error instead, WSL is not completely installed and you need to follow the linked setup guide first.

**Q: How do I download and install AlmaLinux 9?**
A: Open Microsoft Store, search for AlmaLinux, select AlmaLinux 9 from the results, and install it. Once installed, clicking Open launches it in Windows Terminal, where the installer prompts for your username, password, and password confirmation.

**Q: What are the main setup steps inside AlmaLinux 9?**
A: Install epel-release, dnf-utils and the Remi repository RPM, upgrade installed packages, install Ansible, clone the dotkernel/development Git repository, navigate to its wsl directory, fill in the empty fields in config.yml, then run the installer script's Step 1 with `ansible-playbook -i hosts install.yml --ask-become-pass` (it will prompt for the password set during installation).

**Q: Why do I need to restart AlmaLinux 9 partway through setup?**
A: After Step 1 of the installer script, you press Control+D, open Windows Terminal, stop AlmaLinux 9 with `wsl -t AlmaLinux9`, and start it again with `wsl -d AlmaLinux9`. Then you navigate back to the Ansible recipes directory and run Step 2 of the installer script (again with `ansible-playbook -i hosts install.yml --ask-become-pass`), which prompts for the password again. Once Step 2 finishes, the AlmaLinux 9 development environment is ready.

**Q: How do I verify the installation worked?**
A: Check three URLs in your browser: http://localhost/ for Apache's default home page, http://localhost/info.php for the PHP info page, and http://localhost/phpmyadmin/ for PhpMyAdmin, logging in with username root and the root password configured in config.yml under mariadb -> root_password.


<!-- ============================================================ -->
<!-- php-development/aptana-php-installation-in-aptana-2-x.md -->
<!-- ============================================================ -->

---
title: "Aptana PHP installation in Aptana 2.x"
description: "A quick fix for restoring PHP support in Aptana 2.x after the bundled Aptana PHP plugin was discontinued in favor of PDT, plus adding SVN support via Subclipse."
author: "admin"
date_published: "2009-12-01"
canonical_url: "https://www.dotkernel.com/php-development/aptana-php-installation-in-aptana-2-x/"
category: "PHP Development"
language: "en"
---

# Aptana PHP installation in Aptana 2.x

## TL;DR

Aptana discontinued its bundled Aptana PHP plugin in Aptana 2.x in favor of PDT, but PDT is missing major features needed for professional PHP development.
This article shows how to manually reinstall the Aptana PHP plugin through Aptana's update site, and how to add SVN support via Subclipse if it isn't already installed.

As all [aptana](http://www.aptana.org/) fans know, [Aptana PHP](http://www.aptana.org/php) plugin was discontinued in Aptana 2.x, in favor of PDT.
But PDT is a joke, not suitable for professional PHP development, major features are missing.
So if you want to continue using Aptana PHP, that's what need to be done:

1. Aptana -> Help -> Install New Software
2. Add http://update.aptana.com/install/php
3. Then select Aptana PHP and install it.

In case you don't have yet a SVN plugin, go to

1. Aptana -> Help -> Install Aptana Features
2. Others -> Subclipse
3. Follow the instructions

## FAQ

**Q: Why isn't the Aptana PHP plugin available by default in Aptana 2.x?**
A: It was discontinued in Aptana 2.x, in favor of PDT.

**Q: Why not just use PDT instead of Aptana PHP?**
A: PDT is not suitable for professional PHP development, since major features are missing.

**Q: How do I reinstall the Aptana PHP plugin?**
A: Go to Aptana -> Help -> Install New Software, add the update site http://update.aptana.com/install/php, then select Aptana PHP and install it.

**Q: How do I add SVN support in Aptana?**
A: Go to Aptana -> Help -> Install Aptana Features, choose Others -> Subclipse, and follow the instructions.

**Q: Do I need an SVN plugin to use Aptana PHP?**
A: Not specifically for Aptana PHP, but if you don't already have an SVN plugin, Subclipse can be installed separately through Aptana's Install Aptana Features menu.


<!-- ============================================================ -->
<!-- php-development/better-unicode-support-in-mysql-5-5-utf8mb4.md -->
<!-- ============================================================ -->

---
title: "Better Unicode Support in MySQL 5.5 UTF8MB4"
description: "How Dotkernel adopted MySQL 5.5's utf8mb4 character set for fuller Unicode support, and the config and column-length changes that switch requires."
author: "admin"
date_published: "2014-05-06"
canonical_url: "https://www.dotkernel.com/php-development/better-unicode-support-in-mysql-5-5-utf8mb4/"
category: "PHP Development"
language: "en"
---

# Better Unicode Support in MySQL 5.5 UTF8MB4

## TL;DR

MySQL 5.5 introduced the utf8mb4 character set for fuller Unicode support, and Dotkernel's sample dk.sql file was updated to use it.
Switching to utf8mb4 means VARCHAR(255) columns can hit MySQL's 767-byte max key length error, so VARCHAR(150) is used instead, and the connection charset must be updated in both the application config and my.cnf.

Beginning with version 5.5 of MySQL, utf8mb4 character set was introduced, in order to better support Unicode.
Further reading: [MySQL and Unicode](http://mzsanford.com/blog/mysql-and-unicode/), also directly related to [PHP](http://www.phptherightway.com/#php_and_utf8).

Sample dk.sql file, part of Dotkernel framework, was updated in [revision 793](http://websvn.dotkernel.net/filedetails.php?repname=Dotkernel&path=%2Ftrunk%2Fdot_kernel.sql&rev=793&peg=793).

Only one downside, is not possible to use anymore VARCHAR(255), as you will get the error:

```
#1071 - Specified key was too long; max key length is 767 bytes
```

Explanation [here](http://stackoverflow.com/questions/1814532/1071-specified-key-was-too-long-max-key-length-is-767-bytes); so we use instead VARCHAR(150).

Now we should change the connection charset.
In config/application.ini file, edit the below line:

```ini
database.params.charset = utf8mb4
```

Other changes that can be made in my.cnf file are all related to replacing the string utf8_* with utf8mb4_*.

```ini
character_set_server=utf8mb4
```

```ini
collation_server=utf8mb4_general_ci
```

```ini
collation_server=utf8mb4_unicode_ci
```

## FAQ

**Q: What is utf8mb4 and why was it introduced?**
A: utf8mb4 is a character set introduced in MySQL 5.5 to provide better support for Unicode.

**Q: What error do I get if I keep VARCHAR(255) columns after switching to utf8mb4?**
A: You get `#1071 - Specified key was too long; max key length is 767 bytes`, so VARCHAR(150) is used instead.

**Q: How do I change the connection charset for the application?**
A: Edit the config/application.ini file and set `database.params.charset = utf8mb4`.

**Q: What changes are needed in my.cnf?**
A: Replace the string utf8_* with utf8mb4_*, for example `character_set_server=utf8mb4` and `collation_server=utf8mb4_general_ci` or `collation_server=utf8mb4_unicode_ci`.

**Q: Was Dotkernel's own sample SQL updated for utf8mb4?**
A: Yes, the sample dk.sql file, part of the Dotkernel framework, was updated for utf8mb4 in revision 793.


<!-- ============================================================ -->
<!-- php-development/database-seeding-doctrine-data-fixtures-vs-phinx.md -->
<!-- ============================================================ -->

---
title: "Database seeding: Doctrine data fixtures vs Phinx"
description: "Why Dotkernel moved database seeding from Phinx to doctrine/data-fixtures, the CLI package built to fill Doctrine's missing command-line interface, and how to install, use, and order fixtures."
author: "MarioRadu"
date_published: "2022-08-31"
canonical_url: "https://www.dotkernel.com/php-development/database-seeding-doctrine-data-fixtures-vs-phinx/"
category: "PHP Development"
language: "en"
---

# Database seeding: Doctrine data fixtures vs Phinx

## TL;DR

Dotkernel 3 previously used cakephp/phinx for seeding the database, but the team wanted more flexibility and switched to doctrine/data-fixtures since Doctrine is already the ORM in use.
Because doctrine/data-fixtures has no CLI interface, Dotkernel built the dotkernel/dot-data-fixtures package to add one, and this article covers installing it, creating and executing fixtures, and ordering them by explicit order or by declared dependencies.

## Database Seeding: Doctrine Data Fixtures vs Phinx

Seeding the database means populating the database with initial values, it's commonly used for seeding the user roles and user accounts.
Seeding the database the right way is no easy feat, and we will see why.

Previous versions of Dotkernel 3 used [cakephp](https://github.com/cakephp)/[phinx](https://github.com/cakephp/phinx) for seeding the database.
While the package did a great job at populating the database, we wanted more.
We wanted more flexibility - so we started to search for alternatives.

Because we are using Doctrine as our database abstraction layer, the obvious choice was to give [doctrine/data-fixtures](https://github.com/doctrine/data-fixtures) a shot and use it as our database seeder, instead of phinx - but there's a catch.

## The Catch

Using the [doctrine/data-fixtures](https://github.com/doctrine/data-fixtures) package provides a concrete implementation of data fixtures, without a CLI interface.
We need a way to interact with the fixtures, so we created a package ([dotkernel/dot-data-fixtures](https://github.com/dotkernel/dot-data-fixtures)) to provide a CLI interface.
While there are alternatives that can achieve this out-of-the-box we wanted something slim (in terms of dependencies) and easy to use.

### Note

The package [dotkernel/dot-data-fixtures](https://github.com/dotkernel/dot-data-fixtures) does NOT depend on other Dotkernel packages.
The only dependency is Doctrine.

## Installation

Run the following command in your project directory:

```bash
composer require dotkernel/dot-data-fixtures
```

Register the package's `ConfigProvider.php` in `config/config.php`.

```php
\Dot\DataFixtures\ConfigProvider::class,
```

In `doctrine.global.php` (or your custom doctrine config file) add a new key `fixtures`, in the `doctrine` array, the value should be a valid path to a folder where your fixtures can be found.

```php
return [
    'dependencies' => [ ... ],
    'doctrine' => [
        ...,
        'fixtures' => getcwd() . '/data/doctrine/fixtures',
    ],
];
```

Make sure the path is valid before proceeding to the next step.
The fixtures can be found in the `/data/doctrine/fixtures` folder, but you can create a custom folder for them.
We choose this location because the migrations live in the `/data/doctrine/migrations` folder.

The last step is to register 2 commands.
We will register the commands to work with the doctrine default CLI but you can register them as normal commands also.
Create a new php file `bin/doctrine` if you don't have it already and paste the below code block.

```php
<?php

use Doctrine\ORM\Tools\Console\ConsoleRunner;
use Doctrine\ORM\Tools\Console\EntityManagerProvider\SingleManagerProvider;

require_once 'vendor/autoload.php';

$container = require getcwd() . '/config/container.php';

$entityManager = $container->get(\Doctrine\ORM\EntityManager::class);

$commands = [
    $container->get(Dot\DataFixtures\Command\ExecuteFixturesCommand::class),
    $container->get(Dot\DataFixtures\Command\ListFixturesCommand::class),
];

ConsoleRunner::run(
    new SingleManagerProvider($entityManager),
    $commands
);
```

The installation is complete, we can verify it by running the following command in our terminal.

```bash
php bin/console
```

It should print out all the doctrine CLI commands available, including our fixtures commands.

## Usage

### List All Available Fixtures, by Order of Execution

```bash
php bin/doctrine fixtures:list
```

By using this command you can check the execution order of your fixtures before executing them.

### Executing Fixtures

To execute all fixtures run: `php bin/doctrine fixtures:execute`
To run a specific fixture run: `php bin/doctrine fixtures:execute --class={FixtureClassName}`
Example:

```bash
php bin/console fixtures:execute --class=RoleLoader
```

## Creating Fixtures

When creating fixtures, we need to:

- Create the fixture in the configured folder (`/data/doctrine/fixtures`).
- Implement `Doctrine\Common\DataFixtures\FixtureInterface` interface.

Example:

```php
<?php

namespace Frontend\Fixtures;

use Doctrine\Common\DataFixtures\FixtureInterface;
use Doctrine\Persistence\ObjectManager;
use Frontend\User\Entity\UserRole;

/**
 * Class RoleLoader
 * @package Frontend\Fixtures
 */
class RoleLoader implements FixtureInterface
{
    public function load(ObjectManager $manager): void
    {
        $adminRole = new UserRole();
        $adminRole->setName('admin');

        $userRole = new UserRole();
        $userRole->setName('user');

        $guestRole = new UserRole();
        $guestRole->setName('guest');

        $manager->persist($adminRole);
        $manager->persist($userRole);
        $manager->persist($guestRole);

        $manager->flush();
    }
}
```

## Ordering Fixtures

We can order fixtures using 2 methods:

1. By Order - you can specify the order of execution, by implementing `OrderedFixtureInterface` interface.
2. By dependencies - lets you specify dependency fixtures, chaining fixtures and executing them in the right order.

Practical example:
Requirements: Seed the database with a new admin user.

We will use the second method to order fixtures and need 2 fixtures to achieve this, one of them will create a new user and the other will create a new admin role.
In this case the order matters, we can't create the admin user without having an admin role.

Create new php file in `data/doctrine/fixtures` with the name `RoleLoader.php`.
This fixture will be executed first and create our user roles.

```php
<?php

namespace Frontend\Fixtures;

use Doctrine\Common\DataFixtures\FixtureInterface;
use Doctrine\Persistence\ObjectManager;
use Frontend\User\Entity\UserRole;

/**
 * Class RoleLoader
 * @package Frontend\Fixtures
 */
class RoleLoader implements FixtureInterface
{
    public function load(ObjectManager $manager): void
    {
        $adminRole = new UserRole();
        $adminRole->setName('admin');

        $userRole = new UserRole();
        $userRole->setName('user');

        $guestRole = new UserRole();
        $guestRole->setName('guest');

        $manager->persist($adminRole);
        $manager->persist($userRole);
        $manager->persist($guestRole);

        $manager->flush();
    }
}
```

The second fixture is `UserLoader.php` and will contain the following code:

```php
<?php

namespace Frontend\Fixtures;

use Doctrine\Common\DataFixtures\DependentFixtureInterface;
use Doctrine\Common\DataFixtures\FixtureInterface;
use Doctrine\Persistence\ObjectManager;
use Frontend\User\Entity\User;
use Frontend\User\Entity\UserDetail;
use Frontend\User\Entity\UserRole;

class UserLoader implements FixtureInterface, DependentFixtureInterface
{
    public function load(ObjectManager $manager): void
    {
        $user = new User();
        $user->setIdentity('admin@test.com');
        $user->setPassword(password_hash('admin', PASSWORD_DEFAULT));
        $user->setIsDeleted(false);
        $user->setHash('hash');

        $userDetail = new UserDetail();
        $userDetail->setUser($user);
        $userDetail->setFirstName('Admin');

        $user->setDetail($userDetail);

        $roleRepository = $manager->getRepository(UserRole::class);

        /** @var UserRole $adminRole */
        $adminRole = $roleRepository->findOneBy(['name' => UserRole::ROLE_ADMIN]);

        $user->addRole($adminRole);

        $manager->persist($user);

        $manager->flush();
    }

    public function getDependencies(): array
    {
        return [
           RoleLoader::class
        ];
    }
}
```

Notice how `UserLoader.php` implements 2 interfaces, `FixtureInterface` and `DependentFixtureInterface`.
The method `getDependencies()` returns an array containing the dependencies (fixtures) that need to be executed prior to the current one.
After running all the fixtures using `php bin/doctrine fixtures:execute` the output should look like this:
`RoleLoader` was executed before `UserLoader` because `UserLoader` had `RoleLoader` as a dependency.

To wrap things up, we implemented a database seeder and saw a practical example of how to use it.
More details about Fixtures in this blogpost: [https://matthiasnoback.nl/2018/07/about-fixtures/](https://matthiasnoback.nl/2018/07/about-fixtures/).

## FAQ

**Q: Why did Dotkernel move from Phinx to doctrine/data-fixtures for seeding?**
A: Previous versions of Dotkernel 3 used cakephp/phinx for seeding, but the team wanted more flexibility, so they evaluated doctrine/data-fixtures since Doctrine is already used as the database abstraction layer.

**Q: What's the catch with doctrine/data-fixtures?**
A: It provides a concrete implementation of data fixtures, but without a CLI interface, so Dotkernel built the dotkernel/dot-data-fixtures package to add one.

**Q: Does dotkernel/dot-data-fixtures depend on other Dotkernel packages?**
A: No, its only dependency is Doctrine.

**Q: How do you install dotkernel/dot-data-fixtures?**
A: Run `composer require dotkernel/dot-data-fixtures`, register its ConfigProvider in `config/config.php`, add a `fixtures` key pointing to your fixtures folder in your doctrine config, and register the ExecuteFixturesCommand and ListFixturesCommand in a `bin/doctrine` CLI file.

**Q: How do you list and execute fixtures?**
A: Use `php bin/doctrine fixtures:list` to see the execution order, `php bin/doctrine fixtures:execute` to run all fixtures, or `php bin/doctrine fixtures:execute --class={FixtureClassName}` to run a specific one.

**Q: How can fixtures be ordered?**
A: Either by implementing `OrderedFixtureInterface` to specify an explicit order, or by implementing `DependentFixtureInterface` and its `getDependencies()` method to declare which fixtures must run first.


<!-- ============================================================ -->
<!-- php-development/end-of-support-for-php-5-2-x-branch.md -->
<!-- ============================================================ -->

---
title: "End of Support for PHP 5.2.x Branch"
description: "PHP 5.2.14 marks the end of active support for the PHP 5.2 branch, with PHP 5.3.3 released and ready for upgrade."
author: "admin"
date_published: "2010-07-22"
canonical_url: "https://www.dotkernel.com/php-development/end-of-support-for-php-5-2-x-branch/"
category: "PHP Development"
language: "en"
---

# End of Support for PHP 5.2.x Branch

## TL;DR

PHP 5.2.14 was just released, marking the end of active support for the PHP 5.2.x branch.
PHP 5.3.3 was released at the same time, and projects and servers are encouraged to upgrade to the 5.3.x branch.

## The announcement

PHP 5.2.14 was just released, and this is the end of support for the 5.2.x branch of PHP.

> **NOTE:** This release marks the end of the active support for PHP 5.2.
> Following this release the PHP 5.2 series will receive no further active bug maintenance.
> Security fixes for PHP 5.2 might be published on a case by case basis.
> All users of PHP 5.2 are encouraged to upgrade to PHP 5.3

PHP 5.3.3 was also just released, so it is time to upgrade every project to the PHP 5.3.x branch, and also upgrade all servers to 5.3.x.

## FAQ

**Q: What does the release of PHP 5.2.14 mean for the 5.2.x branch?**
A: PHP 5.2.14 marks the end of active support for the PHP 5.2 branch.
After this release, PHP 5.2 will receive no further active bug maintenance, though security fixes might still be published on a case-by-case basis.

**Q: What should users of PHP 5.2 do?**
A: All users of PHP 5.2 are encouraged to upgrade to PHP 5.3.

**Q: Which PHP version was just released alongside the end of 5.2.x support?**
A: PHP 5.3.3 was just released, so it is time to upgrade every project to the PHP 5.3.x branch and also upgrade all servers to 5.3.x.

## Resources

- [PHP 5.2.14 changelog](http://www.php.net/ChangeLog-5.php#5.2.14)
- [PHP 5.3.3 changelog](http://www.php.net/ChangeLog-5.php#5.3.3)


<!-- ============================================================ -->
<!-- php-development/floating-point-arithmetic-why-is-int-0-7-0-1-10-7.md -->
<!-- ============================================================ -->

---
title: "Floating-Point Arithmetic - Why is (int)((0.7+0.1)*10) = 7 ?"
description: "An explanation of why PHP's floating-point arithmetic and int casting can produce unexpected results like (int)((0.7+0.1)*10) = 7 instead of 8."
author: "Gabi DJ"
date_published: "2016-01-26"
canonical_url: "https://www.dotkernel.com/php-development/floating-point-arithmetic-why-is-int-0-7-0-1-10-7/"
category: "PHP Development"
language: "en"
---

# Floating-Point Arithmetic - Why is (int)((0.7+0.1)*10) = 7 ?

## TL;DR

This applies to PHP 5.x and PHP 7.
Floating-point arithmetic doesn't always produce the results you'd expect, especially when casting values to int, because numbers like 0.7 and 0.1 cannot be represented exactly in binary.
The result is that `(int)((0.7+0.1)*10)` evaluates to 7 instead of the mathematically expected 8.

## The problem

While using floating-point arithmetic you might have noticed that not all calculation results are as expected - this can usually be observed when casting values.

The output for `(0.7 + 0.1) * 10` is:

```php
var_dump((0.7+0.1)*10); # float(8)
var_dump(intval((0.7+0.1)*10)); # int(7)
```

The same thing happens with 0.6 instead of 0.7:

```php
var_dump((0.6+0.1)*10); # float(7)
var_dump(intval((0.6+0.1)*10)); # int(7)
```

## How does the CPU understand these numbers?

The CPU makes calculations in binary; floating-point numbers are represented as follows:

| Format | Size | Sign | Exponent | Mantissa |
|---|---|---|---|---|
| IEEE Short Real (single precision) | 32 bits | 1 bit | 8 bits | 23 bits |
| IEEE Long Real (double precision) | 64 bits | 1 bit | 11 bits | 52 bits |

Numbers that can easily be represented in binary are 1/(2^1), 1/(2^2), 1/(2^3), 1/(2^4), etc., because they have a mantissa equal to 1 (encoded as 0).

A number's value can only be represented exactly if it can be expressed by the formula **exponent * mantissa**.
The mantissa is the number the exponent is multiplied by, and its value is 1 + 1/rb, where rb is the reverse binary interpretation.

For example, take the number 3.5: 3.5 = sign(1) * exponent(2) * mantissa(1.75).

Mantissa: 1 + 11000000000000000000000 -> 1/(2^0) + 1/(2^1) + 1/(2^2) + 0*(2^3) + ... + 0*(2^23) -> 1 + 0.5 + 0.25 -> 1.75

Some numbers cannot be represented exactly (such as 0.99999999).

## Why does this happen?

Using an IEEE 754 converter, it turns out that:

- 0.7 is actually represented as 0.699999988079071
- 0.1 is actually represented as 0.10000000149011612

Adding these two values gives 0.7999999895691871.
Multiplying by 10 gives 7.999999895691871, which when cast to int is 7 - the same way 3.5 is 3 when cast to int.

The 0.6 example still shows 7 because 0.6 is actually represented as 0.6000000238418579, and (0.6000000238418579 + 0.10000000149011612) * 10 is 7.00000025331974.

## But still ...

If you use echo and var_dump, or apply mathematical operations, PHP automatically adjusts the values - but intval and casting to int work on the underlying bits before those values were adjusted:

```php
var_dump((0.7+0.1)*10); # float(8)
var_dump(intval( ((0.7+0.1)*10) ) );   # int(7)
var_dump(intval( ((0.7+0.1)*10)+1 ) ); # int(9)
```

If these values are important for your project, you can get correct results by using the BCMath PHP Extension.

## FAQ

**Q: Why does (int)((0.7+0.1)*10) return 7 instead of 8?**
A: Because 0.7 is actually represented internally as 0.699999988079071 and 0.1 as 0.10000000149011612.
Adding them gives 0.7999999895691871, and multiplying by 10 gives 7.999999895691871, which truncates to 7 when cast to int.

**Q: Does the same rounding issue happen with 0.6 instead of 0.7?**
A: Yes.
0.6 is represented as 0.6000000238418579, and (0.6000000238418579 + 0.10000000149011612) * 10 equals about 7.00000025331974, which also truncates to int(7).

**Q: Why do var_dump and echo show the expected value while intval/int casting does not?**
A: When using echo, var_dump, or mathematical operations, PHP automatically adjusts the displayed values.
However, intval and casting to int operate on the underlying bits before those values were adjusted, which is why they can produce a different (truncated) result.

**Q: How are floating-point numbers represented at the CPU level?**
A: The CPU performs calculations in binary.
IEEE Short Real (single precision) uses 32 bits: 1 sign bit, 8 exponent bits, and 23 mantissa bits.
IEEE Long Real (double precision) uses 64 bits: 1 sign bit, 11 exponent bits, and 52 mantissa bits.
A number can only be represented exactly if it can be expressed as exponent * mantissa; numbers like 0.99999999 cannot be represented exactly.

**Q: Is there a way to get accurate results for calculations like this in PHP?**
A: If precise values matter for your project, the article recommends using the BCMath PHP Extension to get correct results.

## Resources

- [Floating point tutorial (kipirvine.com)](http://kipirvine.com/asm/workbook/floating_tut.htm)
- [IEEE 754 converter (h-schmidt.net)](http://www.h-schmidt.net/FloatConverter/IEEE754.html)
- [BCMath PHP Extension documentation](http://php.net/manual/en/book.bc.php)
- [What Every Computer Scientist Should Know About Floating-Point Arithmetic](http://docs.oracle.com/cd/E19957-01/806-3568/ncg_goldberg.html)


<!-- ============================================================ -->
<!-- php-development/how-to-upgrade-wamp-to-php-5-3-4.md -->
<!-- ============================================================ -->

---
title: "How To Upgrade Wamp to PHP 5.3.4"
description: "Step-by-step instructions for upgrading a WAMP server's PHP version to 5.3.4."
author: "admin"
date_published: "2010-12-13"
canonical_url: "https://www.dotkernel.com/php-development/how-to-upgrade-wamp-to-php-5-3-4/"
category: "PHP Development"
language: "en"
---

# How To Upgrade Wamp to PHP 5.3.4

## TL;DR

A step-by-step guide to manually upgrading the PHP version used by a WAMP server to PHP 5.3.4, by downloading the VC6 Thread Safe build, copying over configuration files, and switching the active PHP version in WAMP.

## Steps

1. Stop the WAMP server.
2. Go to [windows.php.net](http://windows.php.net/download/) and download the latest ZIPPED package for PHP 5.3.4.
Make sure it is the **VC6 Thread Safe build** - do not download the installer.
3. Create a folder `php5.3.4` inside `wamp/bin/php`.
4. Extract the downloaded zip into the newly created `php5.3.4` folder.
5. Copy the files `php.ini`, `phpForApache.ini`, and `wampserver.conf` from your existing PHP 5.3 folder (e.g. `wamp/bin/php/php5.3.3`) to the new `php5.3.4` folder.
6. Open the files `php.ini` and `phpForApache.ini` and search/replace the string `5.3.3` with `5.3.4`.
7. Go to `wamp/bin/apache/apache/apache2.2.11/bin` and delete the file called `php.ini`.
8. Restart the WAMP server.
9. Choose PHP version 5.3.0.
10. Restart the WAMP server.
11. Now choose PHP version 5.3.4.
12. Check that the PEAR path is correct in `php.ini`, and modify accordingly.
13. Restart the WAMP server.
14. Enjoy.

## FAQ

**Q: Where do I download the PHP 5.3.4 package for WAMP?**
A: Download the latest ZIPPED package for PHP 5.3.4 from windows.php.net.
Make sure it is the VC6 Thread Safe build, and do not download the installer.

**Q: Where should the downloaded PHP 5.3.4 files be extracted?**
A: Create a folder named php5.3.4 inside wamp/bin/php, then extract the downloaded zip into that newly created folder.

**Q: Which configuration files need to be copied and edited when upgrading?**
A: Copy php.ini, phpForApache.ini, and wampserver.conf from the existing php5.3 folder (e.g. wamp/bin/php/php5.3.3) into the new php5.3.4 folder.
Then, in php.ini and phpForApache.ini, search and replace the string 5.3.3 with 5.3.4.

**Q: Is there anything to remove from the Apache folder before restarting WAMP?**
A: Yes.
Go to wamp/bin/apache/apache/apache2.2.11/bin and delete the file called php.ini, then restart the WAMP server.

**Q: How do I actually switch WAMP to the new PHP version after restarting?**
A: After restarting WAMP, choose PHP version 5.3.0, restart WAMP server again, and then choose PHP version 5.3.4.
Also check that the PEAR path is correct in php.ini and modify it accordingly, then restart WAMP server once more.

## Resources

- [windows.php.net downloads](http://windows.php.net/download/)


<!-- ============================================================ -->
<!-- php-development/mezzio-app-development-in-wsl2.md -->
<!-- ============================================================ -->

---
title: "Mezzio app development in WSL2"
description: "A step-by-step guide to installing a Mezzio application (Dotkernel API) inside WSL2, running it on Ubuntu 20.04 LTS."
author: "Alex Karajos"
date_published: "2022-09-08"
canonical_url: "https://www.dotkernel.com/php-development/mezzio-app-development-in-wsl2/"
category: "PHP Development"
language: "en"
---

# Mezzio app development in WSL2

## TL;DR

This article runs through the steps of installing a Mezzio application (Dotkernel API) in WSL2 and running it on Ubuntu 20.04 LTS, from installing WSL2 itself to configuring PHPStorm to work with the WSL2 file system.

## Steps

1. Make sure WSL2 is installed on your machine, following the [WSL2 installation guide](https://github.com/dotkernel/development/blob/main/wsl/README.md).
2. Install Ubuntu 20.04 LTS inside WSL2, as described in the [Ubuntu 20 setup guide](https://docs.dotkernel.org/development/v2/running/) (the current version of this guide covers AlmaLinux 9, the distro the WSL setup has since moved to).
3. Create a virtual host for your project using the [virtual hosts guide](https://docs.dotkernel.org/development/v2/virtualhosts/create-virtualhost/).
4. Using your terminal, move into the virtual host directory you just created:

   ```shell
   cd /home/your-username/projects/your-virtualhost
   ```

Install Dotkernel API by following the [Dotkernel API guide](https://github.com/dotkernel/api).
Make sure the `data` and `log` directories are writable by changing their permissions, as described in the [common permission issues guide](https://docs.dotkernel.org/development/v2/faq/#how-do-i-fix-common-permission-issues).
5. Set up PHPStorm to work with WSL2 files, as described in the [JetBrains WSL development environment article](https://www.jetbrains.com/help/phpstorm/how-to-use-wsl-development-environment-in-product.html).

## Note

There is a guide for AlmaLinux 8 as well, but it is not fully functional because of a well-known issue regarding running systemd inside WSL2.

## FAQ

**Q: What does this guide help you accomplish?**
A: It walks you through installing a Mezzio application (Dotkernel API) using WSL2 and running it on Ubuntu 20.04 LTS.

**Q: What do you need before installing Ubuntu inside WSL2?**
A: You first need WSL2 installed on your machine, which you can set up by following the linked WSL2 installation guide, before installing Ubuntu inside it.

**Q: How do you set up a virtual host for the project?**
A: After Ubuntu is installed inside WSL2, you create a virtual host for your project by following the linked virtual-host creation guide.

**Q: How do you install Dotkernel API once the virtual host is ready?**
A: Using your terminal, move into the virtual host directory you created (for example, `cd /home/your-username/projects/your-virtualhost`), then install Dotkernel API by following its guide.
Afterward, make sure the `data` and `log` directories are writable by changing their permissions, as described in the linked permission-fix guide.

**Q: How do you get PHPStorm to work with the WSL2 project files?**
A: You set up PHPStorm to work with WSL2 files by following the linked JetBrains article on using a WSL development environment in the product.

**Q: Does this guide also work for AlmaLinux instead of Ubuntu?**
A: There is a guide for AlmaLinux 8 as well, but it is not fully functional because of a well-known issue regarding running systemd inside WSL2.

## Resources

- [WSL2 installation guide](https://github.com/dotkernel/development/blob/main/wsl/README.md)
- [Ubuntu 20 setup inside WSL2](https://docs.dotkernel.org/development/v2/running/)
- [Create virtual hosts guide](https://docs.dotkernel.org/development/v2/virtualhosts/create-virtualhost/)
- [Dotkernel API installation guide](https://github.com/dotkernel/api)
- [Fix common permission issues](https://docs.dotkernel.org/development/v2/faq/#how-do-i-fix-common-permission-issues)
- [Using WSL development environment in PHPStorm](https://www.jetbrains.com/help/phpstorm/how-to-use-wsl-development-environment-in-product.html)


<!-- ============================================================ -->
<!-- php-development/php-5-3-6-released-no-upgrade-possible-for-wampserver.md -->
<!-- ============================================================ -->

---
title: "PHP 5.3.6 released. No upgrade possible for WampServer."
description: "PHP 5.3.6 dropped Visual Studio C++ 6 Windows builds, making an in-place WampServer upgrade impossible since WampServer itself is built with VC++ 6."
author: "admin"
date_published: "2011-03-18"
canonical_url: "https://www.dotkernel.com/php-development/php-5-3-6-released-no-upgrade-possible-for-wampserver/"
category: "PHP Development"
language: "en"
---

# PHP 5.3.6 released. No upgrade possible for WampServer.

PHP 5.3.6 was released, but it comes with bad news for WampServer users.
The release notes state:

> Windows users: please mind that we do no longer provide builds created with Visual Studio C++ 6

Since WampServer is built using VC++ 6, an upgrade isn't possible without a rewrite of the entire WampServer package from scratch.

## FAQ

**Q: Why can't WampServer users upgrade to PHP 5.3.6?**
A: PHP 5.3.6 no longer provides builds created with Visual Studio C++ 6 for Windows users.
Since WampServer is built using VC++ 6, upgrading isn't possible without rewriting the entire WampServer package from scratch.

**Q: Where can WampServer users find more details about this issue?**
A: More details are available on the WampServer forum, linked in this article.

## Resources

- [WampServer forum discussion](http://www.wampserver.com/phorum/read.php?2,72243)


<!-- ============================================================ -->
<!-- php-development/php-environment-development-staging-production.md -->
<!-- ============================================================ -->

---
title: "PHP Environment : Development Staging Production"
description: "An overview of the development, staging and production server environments used to improve the development, testing and release process of client-server applications."
author: "Teo"
date_published: "2010-07-30"
canonical_url: "https://www.dotkernel.com/php-development/php-environment-development-staging-production/"
category: "PHP Development"
language: "en"
---

# PHP Environment : Development Staging Production

## TL;DR

In hosted software development, an environment is a server tier designated to a specific stage of a release process.
The three most common environments are Development, Staging and Production, and applications are typically moved between them using Subversion source control.

## Development

This is where the software is developed - it's the working environment for individual developers or small teams. Its purpose is for the developer to work on local host, separate from the rest of the team, allowing them to make changes without worrying that it may alter the work of other team members.

## Staging

Staging is used to assemble, test and review the application before it goes into production.
It usually tries to simulate the production environment as much as possible, both hardware- and software-wise.
Normally, before releasing an update to the production environment, the update must be tested on staging first. This environment can also be used as a demonstration or training environment.

## Production

Production is the "live" environment, where the final application goes out to the world and becomes active.

## Switching between environments

To switch from one environment to another, the article recommends using Subversion (SVN) source code.
The "Using SVN on Aptana" article explains how to set up a development environment on a local computer and then move it to a staging environment.

## FAQ

**Q: What is a "server environment" in hosted software development?**
A: It refers to a server tier designated to a specific stage in a release process.
The purpose of using different environments is to improve the development, testing and release processes in client-server applications.

**Q: What is the development environment used for?**
A: It's the working environment for individual developers or small teams, where the developer works on local host, separate from the rest of the team, allowing changes to be made without worrying about altering the work of other team members.

**Q: What is the staging environment used for?**
A: It's used to assemble, test and review the application before it goes into production, and it usually tries to simulate the production environment as closely as possible, both hardware- and software-wise.
Before releasing an update to production, it must normally be tested on staging first, which can also serve as a demonstration or training environment.

**Q: What is the production environment?**
A: It's the "live" environment, where the final application goes out to the world and becomes active.

**Q: How do you switch an application from one environment to another?**
A: The article recommends using Subversion source code to switch from one environment to another, and points to the "Using SVN on Aptana" article for details on setting up a development environment locally and then moving it to a staging environment.

## Resources

- [Software development practice](http://dltj.org/article/software-development-practice/)


<!-- ============================================================ -->
<!-- php-development/php-support-back-in-aptana-3-0.md -->
<!-- ============================================================ -->

---
title: "PHP support back in Aptana 3.0"
description: "Aptana PHP support is coming back and will be integrated directly into the Studio 3 core rather than as a separate plugin."
author: "admin"
date_published: "2010-06-11"
canonical_url: "https://www.dotkernel.com/php-development/php-support-back-in-aptana-3-0/"
category: "PHP Development"
language: "en"
---

# PHP support back in Aptana 3.0

## TL;DR

Aptana 3.0, then in beta, was set to bring PHP support back - and this time it would be built directly into the Studio 3 core rather than shipped as a separate plugin.
A PHP debugger was also announced, to arrive as a separate set of plugins a few weeks later.

## The announcement

Aptana 3.0 was in beta stage at the time of writing, available for download from the official Aptana site.

The good news, based on an announcement from Aptana's own forum, was that Aptana PHP support was coming back - and would be integrated into Studio 3 core, not delivered as a separate plugin.

Aptana's Shalom G. shared the following in the forum announcement:

> Aptana PHP is coming back.
> We are in the process of developing and integrating it into the Studio 3.
> The debugger will also be introduced, but it will take a few weeks till you'll be able to get it.
>
> At the moment, the idea is to provide the PHP debugger as a separate set of plugins that you will be able to grab from the Studio.
> The majority of the PHP editing capabilities will be integrated into, and delivered with, the Studio core.
>
> Cheers,
> -Shalom G

## FAQ

**Q: Is Aptana 3.0 available yet, and where can it be downloaded?**
A: Aptana 3.0 is in beta stage and can be downloaded from the official Aptana site.

**Q: Will PHP support in Aptana 3.0 be a separate plugin?**
A: No. According to an announcement on Aptana's forum, PHP support is coming back and is being developed and integrated directly into the Studio 3 core, rather than delivered as a separate plugin.

**Q: What about the PHP debugger?**
A: The debugger will also be introduced, but it will take a few weeks to become available.
The plan is to provide the PHP debugger as a separate set of plugins you can grab from the Studio, while the majority of the PHP editing capabilities will be integrated into and delivered with the Studio core.

## Resources

- [Aptana Studio 3 official product page](http://www.aptana.com/products/studio3)
- [Aptana forum announcement thread](https://aptanastudio.tenderapp.com/discussions/questions/419-php-in-studio-3)


<!-- ============================================================ -->
<!-- php-development/protection-against-sql-injection-using-pdo-and-zend-framework-part-2.md -->
<!-- ============================================================ -->

---
title: "Protection against SQL Injection using PDO and Zend Framework - part 2"
description: "A closer look at Zend_Db's query, fetchAll, insert, update, and delete methods, and where SQL injection can still slip through even with prepared statements."
author: "Teo"
date_published: "2010-06-18"
canonical_url: "https://www.dotkernel.com/php-development/protection-against-sql-injection-using-pdo-and-zend-framework-part-2/"
category: "PHP Development"
language: "en"
---

# Protection against SQL Injection using PDO and Zend Framework - part 2

## TL;DR

Following up on the earlier SQL Injection article, this part digs into the specific methods of Zend_Db (and related classes Zend_Db_Statement, Zend_Db_Select, Zend_Db_Tables) to show exactly when their use of prepared statements does, and does not, protect against SQL injection - and offers a quick type-casting tip for WHERE clauses.

## Zend_Db and related classes

Zend_Db is the primary class used for accessing the database, but there is more: Zend_Db_Statement, Zend_Db_Select and Zend_Db_Tables.

## What you should know about their methods

| Method | Behavior |
| --- | --- |
| `query(mixed $sql, ...)` | Uses prepared statements internally, but SQL Injection is still possible if `$sql` is dynamically created. |
| `fetchAll(string\|Zend_Db_Select $sql, ...)` | All the fetch methods use prepared statements internally, but SQL Injection is still possible if `$sql` is dynamically created. |
| `insert(mixed $table, $bind)` | Uses prepared statements internally, so SQL Injection is not possible. |
| `update(mixed $table, $bind, ...)` | Uses prepared statements internally, but SQL Injection may be possible if `$where` is created dynamically. |
| `delete(mixed $table, ...)` | SQL Injection may be possible if `$where` is created dynamically. |

**Note:** even if you use prepared statements via Zend_Db methods, SQL Injection is still possible if the `WHERE` and `ORDER BY` clauses are wrongly written, so pay attention to them.

## A quick tip for WHERE clauses

A short tip: you can use type casting to avoid SQL Injection in a WHERE clause where possible.

```php
$sql = 'SELECT * FROM table WHERE id = ' . (int)$_POST;
```

## FAQ

**Q: What is the focus of this article?**
A: Following the earlier article about SQL Injection, this article makes a stronger argument for using Zend Framework to handle database access.
Zend_Db is the primary class used for accessing the database, but there is more to it: Zend_Db_Statement, Zend_Db_Select, and Zend_Db_Tables.

**Q: Does Zend_Db's query() method protect against SQL injection?**
A: query() uses prepared statements internally, but SQL Injection is still possible if the $sql parameter passed to it is dynamically created.

**Q: What about fetchAll() and the other fetch methods?**
A: All of the fetch methods use prepared statements internally, but SQL Injection is still possible if the $sql is dynamically created.

**Q: Is insert() safe from SQL injection?**
A: Yes. insert() uses prepared statements internally, so SQL Injection is not possible with it.

**Q: What about update() and delete()?**
A: update() uses prepared statements internally, but SQL Injection may be possible if the $where clause is created dynamically.
Likewise, with delete(), SQL Injection may be possible if $where is created dynamically.

**Q: Even with prepared statements, when can SQL injection still happen, and what tip helps avoid it in WHERE clauses?**
A: Even when using prepared statements via Zend_Db methods, SQL Injection is still possible if the WHERE and ORDER BY clauses are wrongly written, so these deserve special attention.
A short tip mentioned is to use type casting to avoid SQL Injection in a WHERE clause where possible, for example: `$sql = 'SELECT * FROM table WHERE id = ' . (int)$_POST;`

## Resources

- [Protection against SQL Injection using PDO and Zend Framework (part 1)](http://www.dotkernel.com/php-development/protection-against-sql-injection-using-pdo-and-zend-framework/)
- [Secure Programming with the Zend Framework (Stefan Esser slides)](http://www.suspekt.org/downloads/DPC_Secure_Programming_With_The_Zend_Framework.pdf)
- [PHP Type Casting](https://www.w3schools.com/php/php_casting.asp)


<!-- ============================================================ -->
<!-- php-development/protection-against-sql-injection-using-pdo-and-zend-framework.md -->
<!-- ============================================================ -->

---
title: "Protection against SQL Injection using PDO and Zend Framework"
description: "An overview of what SQL injection is, what PDO provides, and how prepared statements in Zend Framework help - but don't fully guarantee - protection against SQL injection."
author: "admin"
date_published: "2010-06-16"
canonical_url: "https://www.dotkernel.com/php-development/protection-against-sql-injection-using-pdo-and-zend-framework/"
category: "PHP Development"
language: "en"
---

# Protection against SQL Injection using PDO and Zend Framework

## TL;DR

SQL injection exploits unfiltered user input passed into SQL statements.
PDO (PHP Data Objects) is a standardized database access layer that provides a data-access abstraction (not a database abstraction) and offers several benefits, including help protecting against SQL injection.
In Zend Framework, prepared statements are encouraged since they handle parameter escaping, but they are not a complete guarantee against SQL injection - especially with PDO_MySQL, and with WHERE IN / ORDER BY clauses.

## What is SQL injection?

SQL injection is a technique that exploits a security vulnerability occurring in the database layer of an application.
Usually, user input is not filtered by the script and is passed into a SQL statement.

## What is PDO?

PDO - PHP Data Objects - is a database access layer providing a standardized method of access to multiple databases.
PDO provides a data-access abstraction layer, meaning that regardless of which database you're using, you apply the same functions to issue queries and fetch data.
PDO does not provide a database abstraction; it doesn't rewrite SQL or emulate missing features.

Among PDO's benefits are:

- Access methods that allow complete control over how attributes are read and written
- Validation on a per-record and per-attribute level
- Easier fetching of objects from related tables
- Reusable logic - the same codebase is much easier to maintain
- Cleaner code by using object-oriented code
- Fewer errors from SQL query generation
- Protection against SQL injection

## Prepared statements in Zend Framework

In Zend Framework, database access methods usually support prepared statements.
Dynamic SQL queries are allowed, but all parameters must be escaped, otherwise SQL injection is possible.
Because of this, prepared statements are encouraged, since they handle escaping parameters for you.

Most people believe that using prepared statements makes them 100% protected from SQL injection, but this is not true.
Input data should always be validated and sanitized, and PDO should be seen as another line of defense.
PDO does not protect against other security vulnerabilities like XSS (cross-site scripting), but it does help protect an application against SQL injection.

## The PDO_MySQL risk

A problem can occur in Zend Framework where SQL injection is possible even while using PDO_MySQL.
PDO_MySQL is more dangerous than traditional MySQL applications: traditional MySQL allows only a single SQL query, while PDO_MySQL has no such limitation, so there is a risk of being injected with multiple queries.
To avoid this, use the correct prepared statements provided by Zend Framework.
Also pay attention when your SQL query has `WHERE IN` and `ORDER BY` clauses, since these cannot normally be handled correctly by prepared statements - in this case, escape the data instead.

Zend_Db provides two escaping methods for this purpose: `quote()` and `quoteIdentifier()`.
Both handle strings by putting them between single quotes.

## FAQ

**Q: What is SQL injection?**
A: SQL injection is a technique that exploits a security vulnerability occurring in the database layer of an application.
Usually, user input is not filtered by the script and is passed directly into a SQL statement.

**Q: What is PDO and what kind of abstraction does it provide?**
A: PDO (PHP Data Objects) is a database access layer providing a standardized method of access to multiple databases.
It provides a data-access abstraction layer, meaning you apply the same functions to issue queries and fetch data regardless of which database you're using.
However, PDO does not provide a database abstraction - it doesn't rewrite SQL or emulate missing database features.

**Q: What are the benefits of using PDO?**
A: Among the benefits are: access methods that allow complete control over how attributes are read and written, validation on a per-record and per-attribute level, easier fetching of objects from related tables, reusable logic that makes the codebase easier to maintain, cleaner code through object-oriented programming, fewer errors from SQL query generation, and protection against SQL injection.

**Q: Does using prepared statements in Zend Framework fully protect against SQL injection?**
A: Not entirely.
Zend Framework's database access methods usually support prepared statements, which are encouraged because they handle escaping parameters for you, but dynamic SQL queries are still allowed and any parameters must be escaped manually or SQL injection becomes possible.
Many people believe prepared statements offer 100% protection, but this isn't true - input data should always be validated and sanitized, with PDO treated as another line of defense.
PDO also does not protect against other vulnerabilities such as XSS (cross-site scripting).

**Q: Why can PDO_MySQL be riskier than traditional MySQL usage, and how can this be avoided?**
A: Traditional MySQL allows only a single SQL query at a time, but PDO_MySQL has no such limitation, meaning there is more risk of being injected with multiple queries.
To avoid this, you should use the correct prepared statements from Zend Framework, and pay particular attention to WHERE IN and ORDER BY clauses, since they aren't normally handled correctly by prepared statements - in these cases you should escape the data yourself.

**Q: What escaping methods does Zend_Db provide?**
A: Zend_Db has two escaping methods that can be used: quote() and quoteIdentifier().
Both of these methods handle strings by putting them between single quotes.


<!-- ============================================================ -->
<!-- php-development/remote-connections-to-mysql-server-on-plesk-based-servers.md -->
<!-- ============================================================ -->

---
title: "Remote connections to MySQL server on Plesk based servers"
description: "How to fix remote MySQL connection failures on Plesk-based Linux servers caused by the default old_passwords flag, by creating a user with a modern password hash."
author: "admin"
date_published: "2011-10-18"
canonical_url: "https://www.dotkernel.com/php-development/remote-connections-to-mysql-server-on-plesk-based-servers/"
category: "PHP Development"
language: "en"
---

# Remote connections to MySQL server on Plesk based servers

## TL;DR

Plesk-based Linux servers default to `old_passwords=1`, which forces MySQL to use the old, pre-4.1 password storage style even on MySQL 5.5+, breaking remote PDO connections.
The fix is to create a new database user, grant it privileges, disable old_passwords, and reset its password so a newer, longer password hash is stored in mysql.user.

By default, MySql servers on Linux machines where Plesk is installed, have the old_passwords=1 or ON flag.
That mean even if you have MySQL 5.5+ version, it still use old style of password storage, pre-mysql 4.1+.
If you try to connect remote, from your local development machine, you will get an ugly error, like:

```
Fatal error: Uncaught exception 'PDOException' with message 'SQLSTATE  mysqlnd
cannot connect  to MySQL 4.1+ using the old insecure authentication. Please use an administration
tool to reset your password with the command SET PASSWORD = PASSWORD('your_existing_password').
This will store a new, and more secure, hash value in mysql.user.
If this user is used in other scripts executed by PHP 5.2 or earlier you might need to remove
the old-passwords flag from your my.cnf file' in
```

How to fix that:

1. Create a new database user, someuser for instance directly in command line.
2. Grant priviledges to that user to the database you want to connect to.
3. Now run the below SQL statements:

```sql
SET old_passwords = 0;
UPDATE mysql.user SET Password = PASSWORD('somepassword') WHERE User = 'someuser' limit 1;
SELECT LENGTH(Password) FROM mysql.user WHERE User = 'someuser';
FLUSH PRIVILEGES;
```

Now you can remotely connect to that server, using the user: someuser and password: somepassword.

NOTE: if you browse the table mysql.user, you will note that the password field contain many more characters for the user someuser compared to the others.

## FAQ

**Q: Why can't I connect remotely to MySQL on a Plesk-based server?**
A: By default, MySQL servers on Linux machines with Plesk installed have the old_passwords flag set to 1 (ON). Even on MySQL 5.5+, this means the old, pre-4.1 password storage style is still used, which causes a PDOException error when connecting remotely.

**Q: What error message indicates this old-passwords problem?**
A: You get a fatal error mentioning "cannot connect to MySQL 4.1+ using the old insecure authentication," suggesting you reset the password using SET PASSWORD = PASSWORD('your_existing_password') to store a newer, more secure hash.

**Q: How do you fix the old-passwords issue?**
A: Create a new database user (e.g. someuser) from the command line, grant it privileges on the target database, then run: SET old_passwords = 0; UPDATE mysql.user SET Password = PASSWORD('somepassword') WHERE User = 'someuser' limit 1; SELECT LENGTH(Password) FROM mysql.user WHERE User = 'someuser'; FLUSH PRIVILEGES;. You can then connect remotely using that user and password.

**Q: How can you tell the fix worked by looking at the mysql.user table?**
A: If you browse the mysql.user table, you'll notice the password field for the fixed user (someuser) contains many more characters than the password fields for the other, unfixed users.


<!-- ============================================================ -->
<!-- php-development/static-analysis-replacing-psalm-with-phpstan.md -->
<!-- ============================================================ -->

---
title: "Static Analysis - Replacing Psalm with PHPStan"
description: "Why Dotkernel replaced Psalm with PHPStan for static analysis, and a walkthrough of updating composer.json, CI, and configuration files to run PHPStan checks."
author: "Florin Bidirean"
date_published: "2024-11-22"
canonical_url: "https://www.dotkernel.com/php-development/static-analysis-replacing-psalm-with-phpstan/"
category: "PHP Development"
language: "en"
---

# Static Analysis - Replacing Psalm with PHPStan

## TL;DR

Dotkernel is replacing Psalm with PHPStan for static analysis, following a broader PHP community shift (including projects like Doctrine and Composer) toward PHPStan's faster-growing ecosystem, full-time maintainer, PHPStorm-based stubs, and stronger detection.
This article explains what static analysis is, why the switch makes sense, and walks through updating composer.json, the CI workflow, and the phpstan.neon configuration to run PHPStan checks in place of Psalm.

## What Is Static Analysis

Static analysis (static code analysis or source code analysis) applies a set of coding rules to debug source code before a program is run.
Applied in the early phase of code development, the goals of static analysis are:

- Catch and fix errors like type-related errors which can occur especially in dynamically-typed programming languages like PHP.
- Confirm coding standards to ensure readability and maintainability for large projects that need a consistent coding style.
- Identify code that needs refactoring and recommend improvements to improve complex or 'smelly' code.
- Enhance security by detecting potential code injection in PHP, cross-site scripting (XSS) and open redirect vulnerabilities.

The top static analysis tools are:

- PHPStan
- Psalm
- Snyk
- Sonarqube
- Scrutinizer
- PHPCheckstyle

## Why Switch from Psalm to PHPStan?

Dotkernel has been using [psalm](https://psalm.dev/) for a while now and the results have always been positive.
A large part of the PHP community, especially developers in widely-used projects like Doctrine and Composer, have opted for [PHPStan](https://phpstan.org/) instead.
For most use cases, psalm and PHPStan have identical findings, so it isn't really justified to use both.

PHPStan has some advantages to psalm:

- A faster growing ecosystem.
- Better social media presence.
- A fulltime contributor (author [@ondrejmirtes](https://github.com/ondrejmirtes)).
- Uses PHP stubs from PHPStorm.
- Better quality and depth of detection.

Thus, the better choice becomes PHPStan.

## Updating Your Project to Use PHPStan

First, remove the references to psalm:

- update the `require` in your `composer.json` file
  - remove `vimeo/psalm`
  - add these packages
    - "phpstan/phpstan": "^2.0"
    - "phpstan/phpstan-doctrine": "^2.0"
    - "phpstan/phpstan-phpunit": "^2.0",
- update the `scripts` in your `composer.json` file
  - replace `"static-analysis": "psalm --shepherd --stats",` with `"static-analysis": "phpstan analyse --memory-limit 1G",`
- run `composer update` to install the new packages
- delete `psalm-baseline.xml` and `psalm.xml`
- create file `.github/workflows/static-analysis.yml` with the content below to configure the environment and the steps for PHPStan

```
on:
  - push

name: Run PHPStan checks

jobs:
  mutation:
    name: PHPStan ${{ matrix.php }}-${{ matrix.os }}

    runs-on: ${{ matrix.os }}

    strategy:
      matrix:
        os:
          - ubuntu-latest

        php:
          - "8.2"
          - "8.3"

    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Install PHP
        uses: shivammathur/setup-php@v2
        with:
          php-version: "${{ matrix.php }}"
          coverage: pcov
          ini-values: assert.exception=1, zend.assertions=1, error_reporting=-1, log_errors_max_len=0, display_errors=On
          tools: composer:v2, cs2pr

      - name: Determine composer cache directory
        run: echo "COMPOSER_CACHE_DIR=$(composer config cache-dir)" >> $GITHUB_ENV

      - name: Cache dependencies installed with composer
        uses: actions/cache@v4
        with:
          path: ${{ env.COMPOSER_CACHE_DIR }}
          key: php${{ matrix.php }}-composer-${{ hashFiles('**/composer.json') }}
          restore-keys: |
            php${{ matrix.php }}-composer-
      - name: Install dependencies with composer
        run: composer install --prefer-dist --no-interaction --no-progress --optimize-autoloader --ansi

      - name: Setup project
        run: |
          mv config/autoload/local.php.dist config/autoload/local.php
          mv config/autoload/mail.local.php.dist config/autoload/mail.local.php
          mv config/autoload/local.test.php.dist config/autoload/local.test.php
      - name: Run static analysis with PHPStan
        run:  vendor/bin/phpstan analyse
```

- create the file `phpstan.neon` with the content below to configure the extensions, the rule level and the ignore rules

```
includes:
    - vendor/phpstan/phpstan-doctrine/extension.neon
    - vendor/phpstan/phpstan-phpunit/extension.neon
parameters:
    level: 5
    paths:
        - src
        - test
    treatPhpDocTypesAsCertain: false
    ignoreErrors:
        -
            message: '#Call to an undefined method.*setAllowOverride#'
            path: test/Functional/AbstractFunctionalTest.php
```

## Running the PHPStan Checks

To run the checks, use this command:

```bash
composer static-analysis
```

`composer.json` is currently set up to run this command which sets up the memory limit to a higher amount than that from the `php.ini` file in PHP (128M).

```bash
vendor/bin/phpstan analyse --memory-limit 1G
```

If you still get the error below, try increasing the memory limit further, e.g. 2G or 4G.

```
Child process error: PHPStan process crashed because it reached configured PHP memory limit: 128M
```

## Summary

In this article we revisited the theoretical meaning of static analysis and focused on the change from psalm to PHPStan.
It's highly recommended to use a static analysis tool in your project and, while both psalm and PHPStan perform similar functions, the latter has recently stepped ahead of the former.

## FAQ

**Q: What is static analysis and why is it used?**
A: Static analysis (or source code analysis) applies coding rules to debug source code before a program is run. It's used to catch and fix type-related errors, confirm coding standards, identify code that needs refactoring, and enhance security by detecting issues like code injection, XSS, and open redirect vulnerabilities.

**Q: Why did Dotkernel switch from Psalm to PHPStan?**
A: Dotkernel had used Psalm with positive results, but much of the PHP community, including projects like Doctrine and Composer, moved to PHPStan instead. Since the two tools have largely identical findings, using both wasn't justified, and PHPStan has a faster growing ecosystem, better social media presence, a fulltime contributor (@ondrejmirtes), PHP stubs from PHPStorm, and better quality and depth of detection.

**Q: What are the main steps to migrate a project from Psalm to PHPStan?**
A: Remove vimeo/psalm from composer.json and add phpstan/phpstan, phpstan/phpstan-doctrine and phpstan/phpstan-phpunit, replace the "static-analysis" composer script with "phpstan analyse --memory-limit 1G", run composer update, delete psalm-baseline.xml and psalm.xml, then add a .github/workflows/static-analysis.yml workflow and a phpstan.neon configuration file.

**Q: What does the phpstan.neon configuration file do in this setup?**
A: It includes the phpstan-doctrine and phpstan-phpunit extensions, sets the analysis rule level (level 5 in the example), specifies the paths to scan (src and test), sets treatPhpDocTypesAsCertain to false, and can list ignoreErrors patterns to suppress specific known findings.

**Q: How do you run the PHPStan checks, and what if you hit a memory error?**
A: Run composer static-analysis, which is configured to call vendor/bin/phpstan analyse --memory-limit 1G (higher than PHP's default 128M). If you still see "PHPStan process crashed because it reached configured PHP memory limit," try increasing the memory limit further, e.g. to 2G or 4G.


<!-- ============================================================ -->
<!-- php-development/using-aptana-to-connect-to-dotkernel-tracker-mantis.md -->
<!-- ============================================================ -->

---
title: "Using Aptana to connect to Dotkernel tracker (Mantis)"
description: "A step-by-step guide to integrating the Aptana IDE with Dotkernel Tracker, a Mantis-based bug tracker, using the Mylyn plugin's Mantis connector."
author: "Teo"
date_published: "2010-10-18"
canonical_url: "https://www.dotkernel.com/php-development/using-aptana-to-connect-to-dotkernel-tracker-mantis/"
category: "PHP Development"
language: "en"
---

# Using Aptana to connect to Dotkernel tracker (Mantis)

## TL;DR

This guide explains how to connect the Aptana IDE to Dotkernel Tracker, the Mantis-based bug tracker used for the Dotkernel application framework, via the Mylyn plugin's Mantis connector.
It walks through installing Aptana and Mylyn, adding Dotkernel Tracker as a task repository, and validating the connection so tickets can be managed directly from the IDE.

## Overview

Dotkernel Tracker is a Mantis web-based bugtracking system where bugs are reported, new features are announced, and other general tickets are added.
To simplify the development of Dotkernel, the Aptana IDE was integrated with the Dotkernel Tracker bugtracking system.
Screenshots for the steps below are available in the Downloads section, under [Using Aptana with the Mylyn connector for Mantis](https://www.dotkernel.com/download/?did=24).

## Steps

1. Install Aptana 2.0.5 by following the steps at [http://www.dotkernel.com/php-development/aptana-php-installation-in-aptana-2-x/](https://www.dotkernel.com/php-development/aptana-php-installation-in-aptana-2-x/).
2. Install the Mylyn plugin.
Go to Aptana -> Help -> Software Update.
Add the update site: [http://download.eclipse.org/tools/mylyn/update/e3.4/](http://download.eclipse.org/tools/mylyn/update/e3.4/).
3. In Aptana, go to Windows -> Show View -> Other -> Task Repository.
4. Right click and select Add Task Repository -> Install More Connectors.
5. Select Mantis, then Finish.
6. Install the Mylyn Connector for Mantis.
7. From the Task Repository window, right click and select Add Task Repository -> Mantis -> Next.
Server: [http://www.dotkernel.net/api/soap/mantisconnect.php](http://www.dotkernel.net/api/soap/mantisconnect.php).
Label: Dotkernel Tracker (or a custom string).
User ID: your username from [http://www.dotkernel.net/](http://www.dotkernel.net/) - if you don't have an account, [sign up here](http://www.dotkernel.net/signup_page.php).
8. To check if your connection works, click Validate Settings, then Finish.
9. A popup will ask if you want to create a query; click Yes.
10. Select project: Dotkernel.
Select filter: Latest Dot Kernel tasks.
Query Title: change the title if desired (optional).
Click Finish.

## FAQ

**Q: What is Dotkernel Tracker?**
A: Dotkernel Tracker is a Mantis-based, web-based bugtracking system used by the Dotkernel application framework, where bugs are reported, new features are announced, and other general tickets are added.

**Q: How is Aptana integrated with Dotkernel Tracker?**
A: Aptana, the web development IDE used for Dotkernel development, is integrated with Dotkernel Tracker via the Mylyn plugin's Mantis connector, so tickets can be managed directly from within the IDE.

**Q: What plugin do you need to install in Aptana before connecting to Mantis?**
A: You need to install the Mylyn plugin via Aptana -> Help -> Software Update, adding the update site http://download.eclipse.org/tools/mylyn/update/e3.4/, and then install the Mylyn Connector for Mantis.

**Q: What information is needed to add Dotkernel Tracker as a task repository?**
A: You need the server URL (http://www.dotkernel.net/api/soap/mantisconnect.php), a label of your choosing (e.g. "Dotkernel Tracker"), and your User ID, which is your username from dotkernel.net (you can sign up if you don't already have an account).


<!-- ============================================================ -->
<!-- php-development/using-php-7-express-in-zend-studio-13.md -->
<!-- ============================================================ -->

---
title: "Using PHP 7 Express in Zend Studio 13"
description: "A walkthrough of Zend Studio 13's PHP 7 Express feature, covering test-project setup, PHP interpreter selection, adding Zend Framework 1, and running a PHP7 compatibility check."
author: "Gabi DJ"
date_published: "2015-12-24"
canonical_url: "https://www.dotkernel.com/php-development/using-php-7-express-in-zend-studio-13/"
category: "PHP Development"
language: "en"
---

# Using PHP 7 Express in Zend Studio 13

## TL;DR

Zend Studio 13 introduces PHP 7 Express, a feature that checks whether pre-PHP7 code will run cleanly on a PHP7 server.
This article walks through setting up a test project with the correct PHP version, verifying the PHP Interpreter setting, adding Zend Framework 1 to the project, and running PHP 7 Express to surface compatibility issues.

## What Is PHP 7 Express?

PHP 7 Express is the newest feature added in Zend Studio, starting with version 13.
This feature is very useful for checking if your pre-PHP7 code will work on a PHP7 server.

## The Project Creation

If you already have the project backup and you are sure you can modify your project, you can skip this step.
If you want to create a new project for testing instead of modifying the original project, make sure the PHP Version is set to PHP 5.6, or whichever PHP version you use in the project.
Choosing the PHP 7 option will hide the PHP 7 Express feature, because Zend Studio assumes a PHP 7 project doesn't need compatibility checks, but if the project is actually using a different version of PHP, compatibility issues might appear.
Long story short: use the exact PHP version your project is using at project creation.

## The 'PHP Interpreter' Selection

If the PHP 7 Express feature won't show up, the issue might be the PHP Interpreter selected.
To check and modify the PHP Interpreter:

- Right click the project.
- Type "interpreter".
- The PHP -> Interpreter option should show up.
- If you only need a specific interpreter for a specific project, check "Enable Project specific settings" - this way you won't affect the other projects in the current workspace.

The PHP 7 Express feature should now show up.

## Project Preparation

As an example, a local project named zend-framework-test is used, and the latest Zend Framework 1 version is added to it.

- Right click on the project.
- Create a new folder named library.
- Download the latest Zend Framework 1 version from [here](http://framework.zend.com/downloads/latest#ZF1), making sure to choose the Full option, not the Full Package one.
- Extract the archive and browse the library folder.
- Copy the Zend folder into your project's library folder.
- If the drag and drop didn't work and you had to manually copy the folder into your project, click the project folder in Zend Studio and press F5 (Refresh).

## Using PHP 7 Express - Testing Zend Framework 1

Using PHP 7 Express is very easy:

- Right-click the project, not a folder or a file, because the feature won't show up.
- Click "Run PHP 7 Express...".
- A confirmation prompt will be displayed.

After the analysis is done, the PHP 7 Express view (or tab) appears in the bottom pane in Zend Studio, depending on the perspective.

## FAQ

**Q: What is PHP 7 Express in Zend Studio?**
A: PHP 7 Express is a feature added in Zend Studio starting with version 13. It's useful for checking whether pre-PHP7 code will work correctly on a PHP7 server.

**Q: What PHP version should you select when creating a test project?**
A: Use the exact PHP version your project actually uses (e.g. PHP 5.6), not PHP 7. Choosing PHP 7 at project creation hides the PHP 7 Express feature, because Zend Studio assumes a PHP 7 project doesn't need compatibility checks.

**Q: What should you check if the PHP 7 Express feature doesn't show up?**
A: Check the PHP Interpreter selected for the project: right click the project, type "interpreter" to find the PHP -> Interpreter option, and optionally enable "Enable Project specific settings" so the change only affects that project.

**Q: How do you run PHP 7 Express once it's available?**
A: Right-click the project itself (not a folder or file, or the feature won't show up), click "Run PHP 7 Express...", and confirm the prompt. After the analysis finishes, results appear in the PHP 7 Express view/tab in the bottom pane.


<!-- ============================================================ -->
<!-- php-development/version-control-ignore-patterns-in-zend-studio.md -->
<!-- ============================================================ -->

---
title: "Version Control Ignore Patterns in Zend Studio"
description: "How to configure global 'Ignored Resources' patterns in Zend Studio so they apply across all projects, instead of setting them individually per project."
author: "admin"
date_published: "2013-04-10"
canonical_url: "https://www.dotkernel.com/php-development/version-control-ignore-patterns-in-zend-studio/"
category: "PHP Development"
language: "en"
---

# Version Control Ignore Patterns in Zend Studio

## TL;DR

Zend Studio lets you manage "Ignored Resources" patterns globally, under Window -> Preferences -> Team -> Ignored Resources, instead of configuring them separately for each project.
This is especially handy when a workspace mixes Git and SVN projects, though any given project can still opt to use its own specific patterns instead of the global ones.

## Managing Global Ignored Resources

In order to globally manage the [Ignored Resources](https://www.dotkernel.com/best-practice/svn-keywords-setup-in-php-ide-zend-studio/) patterns in Zend Studio for all projects, instead of manually adding them to each project, you can do the following:

1. Go to Window -> Preferences.
2. Team -> Ignored Resources.
3. Using Add Pattern, add each ignored pattern one by one, or remove some of the already existing patterns.

This is especially useful when you have both Git and SVN projects in your workspace, and also when you tend to be less careful about your code and workspace.
Also, on each project, you can use either the global ignored patterns or specific ones.

## FAQ

**Q: How do you set global ignored resource patterns in Zend Studio?**
A: Go to Window -> Preferences, then Team -> Ignored Resources. From there, use Add Pattern to add ignored patterns one by one, applying them globally to all projects instead of adding them manually to each project, or remove existing patterns.

**Q: When is this global ignore configuration especially useful?**
A: It's especially useful when you have both Git and SVN projects in the same workspace, and also when you tend to be less careful about your code and workspace. On each project you can still choose to use either the global ignored patterns or specific ones.


<!-- ============================================================ -->
<!-- php-development/welcome-to-the-10th-zend-certified-engineer-in-dotboost-team.md -->
<!-- ============================================================ -->

---
title: "Welcome to the 10th Zend Certified Engineer in Dotboost Team"
description: "Announcement that the 10th member of the Dotboost Technologies team has passed the Zend Certified Engineer exam, plus the team's next certification goals."
author: "admin"
date_published: "2013-11-25"
canonical_url: "https://www.dotkernel.com/php-development/welcome-to-the-10th-zend-certified-engineer-in-dotboost-team/"
category: "PHP Development"
language: "en"
---

# Welcome to the 10th Zend Certified Engineer in Dotboost Team

## TL;DR

Dotboost Technologies Inc. announces that the 10th member of its team has passed the Zend Certified Engineer exam, part of its commitment to top-level PHP development and quality assurance for clients.
Next up: adopting Zend Framework 2 best practices, pursuing the Zend Framework 2 Certified Architect exam, and, starting in 2014, making Zend Certification mandatory for every developer on the team.

## Milestone Announcement

Today is a major milestone for [Dotboost Technologies Inc.](http://www.dotboost.com)
The company is announcing that the 10th member of the team has passed the Zend Certified Engineer exam.
See the [Zend Yellow Pages](http://bit.ly/dotboost-zce) listing.

This is part of the company's commitment to ensure that clients have access to top level PHP development as standard practice, and it allows the team to follow a strong quality assurance program.
The next step is to implement Zend Framework 2 best practices and to take the upcoming Zend Framework 2 Certified Architect exam.
Beginning 2014, a Zend Certification will become mandatory for every developer in the team.

## FAQ

**Q: What milestone is this article announcing?**
A: Dotboost Technologies Inc. is announcing that the 10th member of its team has passed the Zend Certified Engineer (ZCE) exam, a milestone the company highlights as part of its commitment to top-level PHP development for clients.

**Q: What are the team's next certification-related plans?**
A: The next step is to implement Zend Framework 2 best practices and to pursue the Zend Framework 2 Certified Architect exam. Additionally, starting in 2014, Zend Certification will become mandatory for every developer on the team.


<!-- ============================================================ -->
<!-- php-development/zend-server-5-5-quick-setup-on-windows.md -->
<!-- ============================================================ -->

---
title: "Zend Server 5.5 Quick Setup on Windows"
description: "Three quick configuration steps to make a fresh Zend Server 5.5 install on Windows 7 ready for development: enabling mod_rewrite, tuning PHP directives, and enabling APC."
author: "admin"
date_published: "2011-09-07"
canonical_url: "https://www.dotkernel.com/php-development/zend-server-5-5-quick-setup-on-windows/"
category: "PHP Development"
language: "en"
---

# Zend Server 5.5 Quick Setup on Windows

## TL;DR

A fresh Zend Server 5.5.0 install on Windows 7 needs a few quick tweaks before it's ready for development: enabling mod_rewrite in Apache, adjusting a handful of PHP directives, and fixing APC so it actually works even though it's shown as enabled.

## Quick Setup Steps

In order to make a fresh installation of Zend Server 5.5.0 on Windows 7 usable and ready for development, a few quick steps are required.

1. Enable mod_rewrite.
   - Open the file ZEND_INSTALATION_PATH/Apache2/conf/httpd.conf and change the AllowOverride directive from None to All.
   - Restart the Apache service.
2. PHP fine tunes.
   - Go to the Zend Server administration interface at [http://localhost:10081/ZendServer/](http://localhost:10081/ZendServer/), then Server Setup -> Directives, and change the following.
   - Set timezone: set date to America/New_York.
   - Set error reporting: display_errors to on, and error_reporting to -1.
3. Enable APC.
   - APC is listed as enabled in the Zend Server admin interface, but the app dll file is missing, so APC isn't actually working.
   - Download the latest php_apc dll file from [here](http://windows.php.net/downloads/pecl/releases/apc/) - at the time of writing, php_apc-3.1.5-5.3-nts-vc9-x86.zip was the latest non-thread-safe VC9 build available.
   - Extract php_apc.dll to ZEND_INSTALATION_PATH/ZendServer/lib/phpext/.
   - Open the php.ini file from ZEND_INSTALATION_PATH/ZendServer/etc/php.ini and add the line extension=php_apc.dll.
   - Restart the Apache service.

## FAQ

**Q: How do you enable mod_rewrite after a fresh Zend Server 5.5 install on Windows?**
A: Open ZEND_INSTALATION_PATH/Apache2/conf/httpd.conf, change the AllowOverride directive from None to All, then restart the Apache service.

**Q: What PHP directive changes are recommended in the Zend Server admin interface?**
A: In the Zend Server administration interface (http://localhost:10081/ZendServer/), under Server Setup -> Directives, set the date timezone to America/New_York, set display_errors to on, and set error_reporting to -1.

**Q: How do you enable APC when it's listed as enabled but not actually working?**
A: Download the php_apc dll file (e.g. php_apc-3.1.5-5.3-nts-vc9-x86.zip, the latest non-thread-safe VC9 build at the time), extract php_apc.dll into ZEND_INSTALATION_PATH/ZendServer/lib/phpext/, add the line extension=php_apc.dll to the php.ini file in ZEND_INSTALATION_PATH/ZendServer/etc/php.ini, and restart the Apache service.


<!-- ============================================================ -->
<!-- php-troubleshooting/fix-installing-pear-packages-with-php-7-2.md -->
<!-- ============================================================ -->

---
title: "[FIX] Installing PEAR packages with PHP 7.2"
description: "How to fix the 'Cannot use result of built-in function in write context' PEAR error on PHP 7.2 by patching Archive_Tar's func_get_args() call, and how to reinstall the affected packages afterward."
author: "Gabi DJ"
date_published: "2018-05-18"
canonical_url: "https://www.dotkernel.com/php-troubleshooting/fix-installing-pear-packages-with-php-7-2/"
category: "PHP Troubleshooting"
language: "en"
---

# [FIX] Installing PEAR packages with PHP 7.2

## TL;DR

On PHP 7.2, installing PEAR packages such as PHP Code Sniffer fails with a "Cannot use result of built-in function in write context" error in Archive_Tar's Tar.php, because a function is called by reference.
The fix is to edit the offending line in Tar.php to drop the by-reference call, then reinstall Archive_Tar and the target package.

## The Issue

If installing a pear package (for instance PHP Code Sniffer), when running:

```bash
pear install PHP_CodeSniffer
```

this error is shown:

```
PHP Fatal error: Cannot use result of built-in function in write context in ...\php\pear\Archive\Tar.php on line 639
Fatal error: Cannot use result of built-in function in write context in ...\pear\Archive\Tar.php on line 639
```

This error is shown because the function is called by reference.
More details about this issue can be found in [this Pull Request](https://github.com/pear/Archive_Tar/pull/18).

## The Solution

You might be tempted to execute the following:

```bash
pear install Archive_Tar
```

which will result in the same error.
Go to the line indicated in the error (639 in this case) and replace:

```php
$v_att_list = &func_get_args();
```

with:

```php
$v_att_list = func_get_args();
```

The above means func_get_args() isn't called by reference anymore.

## Our Recommendation

The above does fix the problem, but it's recommended to also install Archive_Tar again so you have the latest working version.
Run the following command:

```bash
pear install Archive_Tar
```

This will update your Archive_Tar PEAR package.
And to install the code sniffer, run:

```bash
pear install PHP_CodeSniffer
```

## FAQ

**Q: What error occurs when installing PEAR packages with PHP 7.2?**
A: Running a command like pear install PHP_CodeSniffer produces the fatal error "Cannot use result of built-in function in write context" in Archive/Tar.php on line 639, because the function is called by reference.

**Q: How do you fix the "Cannot use result of built-in function in write context" error?**
A: Go to the line indicated in the error (line 639) and replace "$v_att_list = &func_get_args();" with "$v_att_list = func_get_args();", so func_get_args() is no longer called by reference.

**Q: Does running pear install Archive_Tar directly fix the problem?**
A: No, running pear install Archive_Tar on its own results in the same error, since the underlying Archive_Tar.php file still has the by-reference function call.

**Q: What is the recommended full fix sequence?**
A: After manually fixing the func_get_args() line, it's recommended to run pear install Archive_Tar again to get the latest working version of the package, and then run pear install PHP_CodeSniffer to install the code sniffer.


<!-- ============================================================ -->
<!-- php-troubleshooting/where-is-the-intl-php-extension-problem-solved.md -->
<!-- ============================================================ -->

---
title: "Where is the intl PHP extension? Problem solved!"
description: "Common causes of 'missing intl PHP extension' errors and step-by-step fixes for installing or enabling the Intl extension on Linux and Windows PHP setups."
author: "Gabi DJ"
date_published: "2016-12-14"
canonical_url: "https://www.dotkernel.com/php-troubleshooting/where-is-the-intl-php-extension-problem-solved/"
category: "PHP Troubleshooting"
language: "en"
---

# Where is the intl PHP extension? Problem solved!

## TL;DR

Errors like "requires intl PHP extension" or "extension intl is missing" happen because the PHP Intl extension isn't installed or enabled.
This article explains what Intl is used for, why it might be missing depending on whether you have a bundled or unbundled PHP install, and gives step-by-step fixes for both Linux and Windows servers.

## Problem

PHP packages, frameworks, libraries, and scripts might require different PHP extensions.
In this case, the Intl extension is needed to work with Internationalization Functions.
See [What is Internationalization?](https://www.w3.org/International/questions/qa-i18n) for background.
Have you seen any of these error messages?

- Zend InputFilter requires intl PHP extension
- The requested PHP extension intl is missing from your system

This happened because the PHP Intl extension isn't installed or enabled.
Parts of this tutorial can also serve as a guide for installing or enabling other extensions.

## What Is PHP Intl?

> Internationalization extension (further referred to as Intl) is a wrapper for the ICU library, enabling PHP programmers to perform various locale-aware operations including but not limited to formatting, transliteration, encoding conversion, and calendar operations.

Source: [PHP Documentation](https://www.php.net/manual/en/book.intl.php)

> This extension may be installed using the bundled version as of PHP 5.3.0, or as a PECL extension as of PHP 5.2.0. In other words, there are two methods to install the intl extension.

Source: [PHP Documentation](http://php.net/manual/en/intl.installation.php)

## Cause

If you have installed the unbundled PHP version, the extension is not installed on the system, unless you've installed it separately.
If you have the bundled PHP version, the extension might exist but not be enabled.

## Solutions

### For Linux-Based Server (Assuming You Have Root Access)

- Make sure the php_intl.so file exists within your PHP extensions directory.
Find the extensions directory by using `phpinfo()`, or by running: `php -r "echo ini_get('extension_dir');"` - both options get the extension_dir right from the PHP runtime configuration.
- If the file exists:
  - Search for the config file (php.ini, usually /etc/php.ini) and open it.
  - Make sure the line "extension=php_intl.so" exists and is not commented out.
  - Restart the web server (usually `sudo service httpd restart`).
  - Check if the extension is enabled using `phpinfo()`.
- If the file doesn't exist:
  - Check your PHP version by running the `php -v` command.
  - For PHP 5, install the php-intl package using your [package manager](https://en.wikipedia.org/wiki/Package_manager#Front-ends_for_locally_compiled_packages) - most commonly `apt-get install php-intl` (Ubuntu-based) or `yum install php-intl` (CentOS).
  - For PHP 7, install the php7.x-intl package (depending on your PHP version).
  - Repeat the steps for the case in which the file exists.

For projects hosted on a shared hosting platform, you must ask your hosting provider to install/enable the PHP Intl extension.

### For Windows-Based Server

- Make sure the php_intl.dll file exists within your PHP extensions directory:
  - For a separately installed PHP: C:\path\to\php\ext\
  - For XAMPP: C:\path\to\xampp\php\ext
  - Note: your drive letter might be different.
- If the file exists:
  - Search for the config file (php.ini, usually in the same folder as the PHP executable) and open it.
  - Make sure the line "extension=php_intl.dll" exists and is not commented out.
  - Restart the web server (usually Apache).
  - Check if the extension is enabled using `phpinfo()`.
- If the file doesn't exist:
  - Check your PHP version by running the `php -v` command.
  - Download the PHP version that corresponds to yours from the [PHP Downloads Page](http://windows.php.net/download/) (TS/NTS, x86/x64).
To find thread safety for your PHP, run `php -i | findstr "Thread"`.
  - Search for the php_intl.dll file in the ext folder of that downloaded version and copy it into your php\ext folder.
  - Repeat the steps for the case in which the file exists.

Edit: changed php7.0 occurrences with php7.x, as the version may vary.

## FAQ

**Q: What errors indicate the PHP Intl extension is missing?**
A: Typical errors include "Zend InputFilter requires intl PHP extension" and "The requested PHP extension intl is missing from your system." These happen because the PHP Intl extension isn't installed or enabled.

**Q: What is the PHP Intl extension used for?**
A: Intl (Internationalization extension) is a wrapper for the ICU library that lets PHP programmers perform locale-aware operations, including formatting, transliteration, encoding conversion, and calendar operations. It can be installed bundled since PHP 5.3.0, or as a separate PECL extension since PHP 5.2.0.

**Q: How do you find your PHP extensions directory?**
A: You can find the extension_dir either by calling phpinfo() or by running the command php -r "echo ini_get('extension_dir');" - both read the value straight from the PHP runtime configuration.

**Q: How do you enable the Intl extension on a Linux server if the file already exists?**
A: Confirm php_intl.so exists in your extensions directory, open the php.ini config file (usually /etc/php.ini), make sure the line "extension=php_intl.so" exists and isn't commented out, restart the web server (e.g. sudo service httpd restart), and verify with phpinfo().

**Q: What if the php_intl.so or php_intl.dll file doesn't exist at all?**
A: On Linux, check your PHP version with php -v, then install the php-intl package (PHP 5) or php7.x-intl package (PHP 7) via your package manager, e.g. apt-get install php-intl on Ubuntu-based systems or yum install php-intl on CentOS; on shared hosting, ask your provider to install/enable it. On Windows, download the matching PHP version (checking TS/NTS and x86/x64, with thread safety found via php -i | findstr "Thread") from the PHP Downloads page and copy php_intl.dll from its ext folder into your php\ext folder.


<!-- ============================================================ -->
<!-- phpstorm/code-quality-how-to-setup-phpcs-in-phpstorm.md -->
<!-- ============================================================ -->

---
title: "Code Quality: How to setup phpcs in PHPStorm"
description: "A step-by-step guide to configuring PHP_CodeSniffer (phpcs) in PHPStorm, both when cloning a new project and when fixing an existing project that isn't yet reporting code quality issues."
author: "Alex Karajos"
date_published: "2024-01-05"
canonical_url: "https://www.dotkernel.com/phpstorm/code-quality-how-to-setup-phpcs-in-phpstorm/"
category: "PHPStorm"
language: "en"
---

# Code Quality: How to setup phpcs in PHPStorm

## TL;DR

PHP_CodeSniffer (phpcs) needs to be configured correctly in PHPStorm under PHP > Quality Tools > PHP_CodeSniffer, with the Custom coding standard pointed at your project's phpcs.xml file.
This article gives separate setup steps for a freshly cloned project versus an existing one that isn't reporting issues yet, and explains how to read the resulting inline error and warning indicators in the editor.

PHP_CodeSniffer or phpcs is a tool that helps developers maintain a specific standard in the way they write code.
In order to be able to provide relevant information, phpcs needs to be configured correctly in PHPStorm (see image).
Whether you just cloned or you are already working on a project, follow the below guide on how to prepare your environment.

## When Cloning a Project

1. Windows Terminal: Move to the directory where you want to clone the project.
2. Windows Terminal: Clone the project.
3. PHPStorm: install composer dependencies.
4. PHPStorm: restart.
5. PHPStorm: Open Settings (File -> Settings) and go to PHP -> Quality Tools -> PHP_CodeSniffer:
    - Make sure that the inspection button is ON.
    - Coding standard is set to Custom and the field next to it contains the path to your project's phpcs.xml file.

## For an Existing Project

1. PHPStorm: Open Settings (File -> Settings) and go to PHP -> Quality Tools -> PHP_CodeSniffer.
There, if Coding standard is set to Custom and the field next to it contains the path to your project's phpcs.xml file, then PHPStorm is configured correctly to use phpcs - NO need to continue with the next steps.
2. PHPStorm: delete (if exists) the vendor directory.
3. PHPStorm: install composer dependencies.
4. PHPStorm: restart.
5. Go to Step 1.

After you have the above configurations, you should start seeing information in the top-right corner of the editor.
Once PHPStorm has finished analyzing the opened file, you should see either a green tick (meaning no errors) or a count of all the errors, warnings, and typos.
Clicking on them will open a section where you get detailed information on each item, their location, and recommendations on how to fix them.

## FAQ

**Q: What is phpcs and why do you need to configure it in PHPStorm?**
A: PHP_CodeSniffer (phpcs) is a tool that helps developers maintain a specific standard in the way they write code. In order for it to provide relevant information, it needs to be configured correctly in PHPStorm.

**Q: What are the steps to set up phpcs in PHPStorm when cloning a new project?**
A: Move to the directory where you want to clone the project, clone the project, install composer dependencies in PHPStorm, restart PHPStorm, then open Settings (File -> Settings) and go to PHP -> Quality Tools -> PHP_CodeSniffer, making sure the inspection button is ON and the Coding standard is set to Custom with the field pointing to your project's phpcs.xml file.

**Q: How do you check whether phpcs is already configured correctly for an existing project?**
A: Open Settings (File -> Settings) and go to PHP -> Quality Tools -> PHP_CodeSniffer. If Coding standard is already set to Custom and the field points to your project's phpcs.xml file, PHPStorm is configured correctly and there's no need to continue with the next steps.

**Q: What should you do if phpcs is not configured correctly on an existing project?**
A: Delete the vendor directory if it exists, install composer dependencies, restart PHPStorm, and then go back and repeat the check from Step 1 of the existing-project process.

**Q: How do you know phpcs is working once configured?**
A: After the above configuration, you should start seeing information in the top-right corner of the editor: a green tick means no errors, while a count indicates errors, warnings, or typos. Clicking on them opens a section with detailed information on each item, its location, and recommendations on how to fix it.


<!-- ============================================================ -->
<!-- zend-framework/scienta-zf-debug-bar-a-very-helpfull-zf-debug-tool.md -->
<!-- ============================================================ -->

---
title: "Scienta ZF Debug Bar: A very helpfull ZF debug tool"
description: "A short note on discovering the Scienta ZF Debug Bar and Dotkernel's decision to replace its own basic debug bar with it."
author: "admin"
date_published: "2009-03-31"
canonical_url: "https://www.dotkernel.com/zend-framework/scienta-zf-debug-bar-a-very-helpfull-zf-debug-tool/"
category: "Zend Framework"
language: "en"
---

# Scienta ZF Debug Bar: A very helpfull ZF debug tool

## TL;DR

The author came across the Scienta ZF Debug Bar, a debugging tool for Zend Framework applications.
Dotkernel had been relying on its own basic debug bar, which only showed queries, time spent, and memory used.
Finding Scienta far more complex and polished than their internal tool, the Dotkernel team decided to switch to it and integrate it into the Dotkernel code base.

Just found today a very interesting and helpful debug tool: [Scienta](http://jokke.dk/software/scientadebugbar).

We at Dotkernel used some very basic debug bar: queries, time spent, memory used.
But this Scienta is way more complex and nicer than our internal code, so we switch to it and integrate it in Dotkernel code base.

## FAQ

**Q: What is the Scienta ZF Debug Bar?**
A: It's a debug tool for Zend Framework that the author found interesting and helpful, available at jokke.dk/software/scientadebugbar.

**Q: Why did Dotkernel switch from its own debug bar to Scienta?**
A: Dotkernel had been using a very basic debug bar showing queries, time spent, and memory used, but found Scienta to be way more complex and nicer than their internal code, so they switched to it and integrated it into the Dotkernel code base.


<!-- ============================================================ -->
<!-- zend-framework/sunsetting-pear-channel-for-zend-framework-1.md -->
<!-- ============================================================ -->

---
title: "Sunsetting PEAR Channel for Zend Framework 1"
description: "Dotkernel announces the sunsetting of its unofficial PEAR channel for Zend Framework 1, citing PHP 8 compatibility issues and aging server infrastructure."
author: "admin"
date_published: "2022-11-11"
canonical_url: "https://www.dotkernel.com/zend-framework/sunsetting-pear-channel-for-zend-framework-1/"
category: "Zend Framework"
language: "en"
---

# Sunsetting PEAR Channel for Zend Framework 1

## TL;DR

Dotkernel is sunsetting its unofficial PEAR channel for Zend Framework 1, which was created in 2016 when PEAR was still widely used.
The main reasons are that upgrading PEAR to work with PHP 8 is too painful, and the channel currently runs on an LXC container with CentOS 7, which doesn't work on the latest Proxmox version, making the upgrade to AlmaLinux not worth the effort.
The post closes by thanking PEAR for its historical contribution to the PHP ecosystem.

The unofficial PEAR channel for Zend Framework 1 was created in [2016](https://www.dotkernel.com/dotkernel/migration-of-zend-framework-1-pear-channel/), at the time when [PEAR](https://pear.php.net/) was still used a lot.

Due to the fact that it is a pain to upgrade PEAR to work with PHP 8, we must sunset the channel.

Another reason for sunsetting is that it currently runs on an LXC container with CentOS 7, which does not work on the latest Proxmox version, and the upgrade to AlmaLinux is too much of a pain.

Thank you PEAR for your contribution to the PHP ecosystem, it was a major part of PHP infrastructure.

## FAQ

**Q: When was the PEAR channel for Zend Framework 1 created?**
A: The unofficial PEAR channel for Zend Framework 1 (pear.dotkernel.com) was created in 2016, at a time when PEAR was still used a lot.

**Q: Why is the PEAR channel for Zend Framework 1 being sunset?**
A: Because it's a pain to upgrade PEAR to work with PHP 8, the channel had to be sunset.

**Q: What other reason is given for sunsetting the channel?**
A: The channel was running on an LXC container with CentOS 7, which doesn't work on the latest Proxmox version, and upgrading to AlmaLinux was too much of a pain.


<!-- ============================================================ -->
<!-- zend-framework/wurfl-php-api-libraries-gpl-versions.md -->
<!-- ============================================================ -->

---
title: "WURFL PHP API libraries , GPL versions"
description: "A brief announcement of GPL-licensed WURFL PHP API library versions, including which one Zend Framework's Zend_Http_UserAgent component uses, with a later edit noting the download's removal."
author: "admin"
date_published: "2011-06-14"
canonical_url: "https://www.dotkernel.com/zend-framework/wurfl-php-api-libraries-gpl-versions/"
category: "Zend Framework"
language: "en"
---

# WURFL PHP API libraries , GPL versions

## TL;DR

GPL versions of the WURFL PHP API libraries were made available: version 1.1, the one integrated into Zend Framework's Zend_Http_UserAgent component, and version 1.2.1, the latest released under the GPL license.
A later edit notes the download was removed because an AGPL version is available (which readers need to get themselves), and as a favor to Luca Passani.

GPL versions of WURFL PHP API libraries are ready to be downloaded from here.

Version 1.1 is the one integrated in Zend Framework Zend_Http_UserAgent component.

Version 1.2.1 is the latest released under GPL license.

*Later Edit: removed because A) AGPL version is available, but you'll need to download it for yourself and B) removed to make Luca Passani a favor :-).*

## FAQ

**Q: Which WURFL PHP API library versions were made available under GPL?**
A: Version 1.1, which is the one integrated in Zend Framework's Zend_Http_UserAgent component, and version 1.2.1, described as the latest released under the GPL license.

**Q: Why was the download later removed, according to the post's edit?**
A: Per the "Later Edit," it was removed because an AGPL version is available (which readers need to download for themselves), and to make Luca Passani a favor.


<!-- ============================================================ -->
<!-- zend-framework/zend-framework-1-12-4-released-with-security-fixes.md -->
<!-- ============================================================ -->

---
title: "Zend Framework 1.12.4 Released with Security Fixes"
description: "Matthew Weier O'Phinney announces Zend Framework 1.12.4, 2.1.6, and 2.2.6 with security updates, plus a follow-up 1.12.5 release fixing a backward compatibility issue."
author: "admin"
date_published: "2014-03-06"
canonical_url: "https://www.dotkernel.com/zend-framework/zend-framework-1-12-4-released-with-security-fixes/"
category: "Zend Framework"
language: "en"
---

# Zend Framework 1.12.4 Released with Security Fixes

## TL;DR

Matthew Weier O'Phinney announced the release of Zend Framework 1.12.4, along with 2.1.6 and 2.2.6, all containing security updates, and the ZF PEAR channel was updated to the latest 1.12.4 release.
A March 7, 2014 edit notes that Zend Framework 1.12.5 was subsequently released to fix a backward compatibility issue introduced in the 1.12.4 release.

[Matthew Weier O'Phinney](http://mwop.net/) just announced the release of ZF 1.12.4, 2.1.6, and 2.2.6 with Security Updates.

For more information, please read the official release announcement: [Zend Framework Released](http://framework.zend.com/blog/zend-framework-1-12-4-2-1-6-and-2-2-6-released.html)

Also, the ZF PEAR channel was updated to latest 1.12.4 release.

[pear upgrade zend/zend](http://code.google.com/p/zend/)

March 7, 2014 EDIT:

Zend Framework 1.12.5 was released, in order to fix a backward compatibility issue introduced in 1.12.4 release.

[Release Announcement](http://framework.zend.com/blog/zend-framework-1-12-5-released.html)

## FAQ

**Q: Who announced the release of Zend Framework 1.12.4, and what other versions were released alongside it?**
A: Matthew Weier O'Phinney announced the release of ZF 1.12.4, along with 2.1.6 and 2.2.6, all with security updates.

**Q: Was the ZF PEAR channel updated for this release?**
A: Yes, the ZF PEAR channel was updated to the latest 1.12.4 release, upgradable via "pear upgrade zend/zend".

**Q: Was there a follow-up issue after the 1.12.4 release?**
A: Yes - per the March 7, 2014 edit, Zend Framework 1.12.5 was released in order to fix a backward compatibility issue introduced in the 1.12.4 release.


<!-- ============================================================ -->
<!-- zend-framework/zend-framework-1-7-0-released.md -->
<!-- ============================================================ -->

---
title: "Zend Framework 1.7.0 Released"
description: "Short announcement of the Zend Framework 1.7.0 release, highlighting its new support for Adobe's Action Message Format (AMF) protocol in PHP 5 applications."
author: "admin"
date_published: "2008-11-17"
canonical_url: "https://www.dotkernel.com/zend-framework/zend-framework-1-7-0-released/"
category: "Zend Framework"
language: "en"
---

# Zend Framework 1.7.0 Released

## TL;DR

Zend Framework 1.7.0 has been released, and its headline feature is support for Adobe's Action Message Format (AMF) protocol in PHP 5 applications.
The release is available directly from the official Zend Framework download page.

At first glance, the biggest news is AMF support.
This brings [Adobe's Action Message Format protocol to your PHP 5 application](http://framework.zend.com/manual/1.12/en/zend.amf.server.html).
You can [download the latest ZF](http://framework.zend.com/download/latest) release directly.

## FAQ

**Q: What is described as the biggest news in the Zend Framework 1.7.0 release?**
A: AMF support - bringing Adobe's Action Message Format protocol to PHP 5 applications.

**Q: How can readers get this release?**
A: Via the "Download latest ZF" link provided in the post, pointing to the official Zend Framework download page.


<!-- ============================================================ -->
<!-- zend-framework/zend-framework-1-end-of-life.md -->
<!-- ============================================================ -->

---
title: "Zend Framework 1 End-of-Life"
description: "Announcement that Zend Framework 1 has reached End-of-Life (EOL) status following the release of Zend Framework 3, with security updates continuing only until 28 September 2016."
author: "admin"
date_published: "2016-06-28"
canonical_url: "https://www.dotkernel.com/zend-framework/zend-framework-1-end-of-life/"
category: "Zend Framework"
language: "en"
---

# Zend Framework 1 End-of-Life

## TL;DR

Zend Framework 1 has officially entered End-of-Life (EOL) status now that Zend Framework 3 has been released.
Security updates for Zend Framework 1 continued only until 28 September 2016, three months after the announcement.

The End-of-Life (EOL) term was just announced.
Only up until Sept. 28, 2016, will Zend Framework 1 receive security updates.

"With the release of Zend Framework 3, it's time to halt development on Zend Framework 1.
As such, we hereby announce that Zend Framework 1 reaches its End of Life (EOL) three months from today, on 28 September 2016."

Read the [official announcement](https://framework.zend.com/blog/2016-06-28-zf1-eol.html).

## FAQ

**Q: What does EOL mean for Zend Framework 1?**
A: EOL stands for End-of-Life, meaning Zend Framework 1 has reached the end of its official support and development lifecycle.

**Q: Until when did Zend Framework 1 keep receiving security updates?**
A: Only up until 28 September 2016, three months after the EOL announcement was made.

**Q: Why was Zend Framework 1 being discontinued?**
A: Because Zend Framework 3 had been released, and it was time to halt development on Zend Framework 1.

**Q: Where was this announced?**
A: In an official Zend Framework blog post announcing that Zend Framework 1 reaches its End of Life (EOL) on 28 September 2016.


<!-- ============================================================ -->
<!-- zend-framework/zend-framework-as-pear-accessible-repository-on-plesk-server.md -->
<!-- ============================================================ -->

---
title: "Zend Framework as PEAR accessible repository on Plesk server"
description: "How to install Zend Framework as a PEAR-accessible repository on a Plesk server, so it doesn't need to be copied into every project and can be updated centrally."
author: "admin"
date_published: "2008-10-03"
canonical_url: "https://www.dotkernel.com/zend-framework/zend-framework-as-pear-accessible-repository-on-plesk-server/"
category: "Zend Framework"
language: "en"
---

# Zend Framework as PEAR accessible repository on Plesk server

## TL;DR

Rather than copying all of Zend Framework's many files into every project, this article shows how to install ZF as a PEAR-accessible repository on a Plesk server.
This makes it easier to track which ZF version is installed on which server and avoids manually updating each project, though it can introduce backward compatibility concerns in future ZF releases.

Why we want to install ZF as PEAR?
Because it's too boring and time consuming to move all ZF files up and down for each script you want to install, and there are a lot of files.

Also that way we can forget about the need to update ZF at latest versions, and keep track of which version and on which server we have ZF.
Of course, backward compatibility can be an issue in future ZF releases (like the 2.0 branch for PHP > 5.3).

1. Install PEAR if it is not installed already.
2. Follow the instructions for [ZF PEAR](http://code.google.com/p/zend/).
Then simply use: `pear install zend/zend`
3. Create a vhosts.conf file in /var/www/vhosts/dotkernel.com/conf or wherever your vhost configuration folder is located.
4. In that file, remove the open_basedir:

```ini
>php_admin_value open_basedir "/var/www/vhosts/dotkernel.com/httpdocs:/tmp:/usr/share/pear"
```

5. Rebuild all vhosts: /usr/local/psa/admin/sbin/websrvmng -a
6. Restart httpd
7. Call directly the preloader:

```php
> require_once 'Zend/Loader/Autoloader.php';
```

## FAQ

**Q: Why install Zend Framework as a PEAR-accessible repository?**
A: Because manually moving all ZF files up and down for each script you want to install is boring and time consuming, given the large number of files involved.
It also lets you avoid manually updating ZF to the latest version in every project, and keep track of which version is installed on which server.

**Q: What is a potential downside of this approach?**
A: Backward compatibility can be an issue in future ZF releases, such as the 2.0 branch built for PHP > 5.3.

**Q: What is the first step to set this up?**
A: Install PEAR if it isn't installed already, then follow the instructions for ZF PEAR and run `pear install zend/zend`.

**Q: What needs to change in the vhosts configuration?**
A: Create a vhosts.conf file in your vhost configuration folder (e.g. /var/www/vhosts/dotkernel.com/conf), remove the open_basedir restriction, rebuild all vhosts with websrvmng -a, and restart httpd.

**Q: How do you load Zend Framework classes after this setup?**
A: By calling the preloader directly, e.g. `require_once 'Zend/Loader/Autoloader.php';`


<!-- ============================================================ -->
<!-- zend-framework/zend-mail-and-zend-http-security-fixes-in-zend-framework-1-12-12.md -->
<!-- ============================================================ -->

---
title: "Zend_Mail and Zend_Http Security Fixes in Zend Framework 1.12.12"
description: "Zend Framework 1.12.12 was released with security fixes for the Zend_Mail and Zend_Http components, and a follow-up 1.12.13 release soon after fixed a regression."
author: "admin"
date_published: "2015-05-19"
canonical_url: "https://www.dotkernel.com/zend-framework/zend-mail-and-zend-http-security-fixes-in-zend-framework-1-12-12/"
category: "Zend Framework"
language: "en"
---

# Zend_Mail and Zend_Http Security Fixes in Zend Framework 1.12.12

## TL;DR

Zend Framework 1.12.12 was released with security fixes for the Zend_Mail and Zend_Http components.
Consumers of these components, including Dotkernel which relies heavily on Zend_Mail, were strongly urged to upgrade immediately via PEAR or by applying the patch directly.
A follow-up release, 1.12.13, was issued shortly after to fix a regression introduced in 1.12.12.

The release of ZF 1.12.12 was just announced, with security updates especially on the Zend_Mail and Zend_Http components.
For more information, please read the official release announcement: [Zend Framework 1.12.12 Released](http://bit.ly/1Hr0K6e).

Also, the ZF PEAR channel was updated to the latest 1.12.12 release.

pear upgrade zend/zend

We strongly recommend that consumers of the Zend_Http and Zend_Mail components upgrade immediately.
Also, Dotkernel Application Framework uses the Zend_Mail component intensively.

If you cannot, you can download the patch separately and apply it to your ZF install: [ZF2015-04 patch for ZF1](https://packages.zendframework.com/releases/ZendFramework-1.12.12/0001-ZF2015-04-Fix-CRLF-injections-in-HTTP-and-Mail.patch).

May 20, 2015 EDIT:

Zend Framework 1.12.13 was released, in order to fix a regression issue introduced in the 1.12.12 release.
See the [Release Announcement](http://framework.zend.com/blog/zend-framework-1-12-13-released.html).

## FAQ

**Q: What security issue did Zend Framework 1.12.12 address?**
A: It fixed security issues in the Zend_Mail and Zend_Http components.

**Q: How can you get the fixed version?**
A: By upgrading via the ZF PEAR channel using `pear upgrade zend/zend`, or by downloading and applying the ZF2015-04 patch separately if you cannot upgrade.

**Q: Why was this update particularly important for Dotkernel users?**
A: Because Dotkernel Application Framework uses the Zend_Mail component intensively, consumers of Zend_Http and Zend_Mail were strongly urged to upgrade immediately.

**Q: Was there a follow-up release after 1.12.12?**
A: Yes, Zend Framework 1.12.13 was released on May 20, 2015, to fix a regression issue introduced in the 1.12.12 release.

**Q: Where can you read the official announcements for these releases?**
A: The 1.12.12 announcement is linked as "Zend Framework 1.12.12 Released", and the 1.12.13 regression fix announcement is linked as "Release Announcement".


<!-- ============================================================ -->
<!-- md-pages/about.md -->
<!-- ============================================================ -->

---
title: "About us | The team behind Dotkernel"
description: "Dotkernel is built by the dev team at Apidemia - a team that reviews every change together, gives its work back to the PHP community under MIT, and puts guardrails around the tools it adopts."
canonical_url: "https://www.dotkernel.com/about/"
language: "en"
---

# The team behind Dotkernel

About us . Apidemia

Dotkernel started as an internal tool for handling complex architectures, built because we needed it ourselves.
We released it under MIT because the PHP community gave us the components it stands on.
Everything here is made by a team that has to live with its own decisions.

- [Talk to us](https://www.dotkernel.com/contact/)
- [View on GitHub](https://github.com/dotkernel)
- [Join the discussion](https://github.com/orgs/dotkernel/discussions)

| | |
| --- | --- |
| Team | Apidemia |
| License | MIT |
| Released continuously since | 2018 |

## How a change ships

Propose (plan before code) -> Build (house structure) -> Review (another pair of eyes) -> QA gate (cs . PHPStan . tests) -> Document (for the next person) -> Release (MIT, in public).

## A team that shares the whole codebase

Nobody here owns a private corner of the code.
Every module follows the same structure, every handler is named the same way, and every application is assembled from the same explicit wiring - so any developer on the team can open any part of the platform and know where they are.
That is a deliberate design choice, and it is what makes reviewing each other's work possible rather than polite.

Getting better at this is part of the job, not something we hope happens after hours.
Our developers read the upstream source of the components we depend on, write the documentation the next person will need, and turn every repeated mistake into a written rule instead of a reprimand.
When a review catches the same thing twice, that is a gap in what we have written down - and we fix the writing.

Extending the power of Mezzio by Laminas.

- Every change reviewed by someone else
- One structure across every application
- Learning time counted as real work
- Decisions written down, not remembered

## Six things we are not willing to trade

None of these are aspirations we printed on a wall.
Each one shows up somewhere you can check - in a repository, in a license, in a config file, or in the way a release is handled.

### Better together than alone - How we work . Teamwork

The codebase is the team's, not a collection of territories.

Work is planned out loud before it is written, reviewed before it is merged, and documented before it is called done.
Consistency is what makes that cheap: because a module in one application looks like a module in every other, a reviewer spends their attention on the decision being made rather than on finding their way around.

### Developers who keep growing - People . Improvement

Nobody stays where they started.

Our developers learn by reading the source of the components they build on, by writing the guides and reference docs the rest of the team relies on, and by taking the review notes that come back to them as material rather than criticism.
Every breaking change we publish ships with the article explaining it - writing that explanation is how we make sure we actually understood the change.

### Giving back to PHP - Community . Open source

MIT licensed, and answered in public.

Dotkernel stands on Mezzio, Laminas and Doctrine, so our work goes back out under a permissive license with nothing held behind a paid tier.
The team answers questions on our own components and on the Laminas ones underneath them, publishes the support status of every `dot-*` package instead of leaving it to guesswork, and keeps the discussion where anyone can read it.

- [Packages lifecycle](https://www.dotkernel.com/dotkernel-packages-oss-lifecycle/)
- [Discussions](https://github.com/orgs/dotkernel/discussions)

### Every need you can imagine - Customers . Delivery

The unglamorous requirement is the one that decides a project.

Our skeletons come out of real client work, which is why they answer questions nobody asks in a demo: sharing a database with an application that was there first, running several connections at once, anonymizing an account instead of deleting the row, hearing about a bug that never threw an exception.
We would rather carry that detail for you than let you discover it in your second sprint.

### AI with guardrails on - Tooling . Responsible AI

Adopted everywhere, trusted nowhere by default.

AI assistance runs through every part of how we work, under rules we wrote down first.
Secrets are never loaded rather than merely redacted, so credentials and signing keys stay out of the context window entirely.
Sessions start by proposing a plan instead of editing files.
Linters report and never rewrite.
A package is never named from memory - it is verified against what is actually installed.
And a human reviews every diff, because accountability does not delegate.

- [How we do it](https://www.dotkernel.com/dotboost/)

### Best product, best tools - Craft . Quality

Chosen for what they will still be worth in three years.

We build on interfaces from the PHP Framework Interop Group so a component from one vendor can be replaced by another, keep static analysis at a strict level, ship the test suite with the skeleton rather than promising it later, and stay current with the PHP versions our dependencies support.
When a tool stops being the right answer, we say so - publicly, with a migration path.

- [See the architecture](https://www.dotkernel.com/architecture/)

## Where you can check any of this

### The QA gate

Coding standards, static analysis at a strict rule level and the test suite all run before a change is merged - and "make the checker quiet" is never an accepted fix.

### Documentation as a deliverable

A feature is not finished until the next developer can pick it up from what is written, which is why [docs.dotkernel.org](https://docs.dotkernel.org/) is maintained alongside the code.

### Deprecations, not surprises

Endpoints announce their own retirement through response headers, so a client finds out from the API rather than from a changelog nobody read.

### Support status in public

Every package publishes where it sits in its lifecycle, so choosing one is never a bet on whether it is still maintained.

### Secrets stay out of the tooling

Local configuration, environment files and OAuth keys are unreadable to our AI tooling by configuration, not by convention.

### Supported by JetBrains

Our open-source tooling is supported through the [JetBrains open source programme](https://jb.gg/OpenSourceSupport) - one of the ways this work stays sustainable.

[Work with us ->](https://www.dotkernel.com/contact/)

## Open source, in production

Built by a team that has to live with its own decisions.

Dotkernel is developed and led by the dev team at Apidemia.
If you are weighing up a platform, hiring a team, or just want to argue about middleware, we would rather have the conversation than the brochure.

[Talk to us ->](https://www.dotkernel.com/contact/)


<!-- ============================================================ -->
<!-- md-pages/admin.md -->
<!-- ============================================================ -->

---
title: "Dotkernel Admin | Open-source PHP admin application"
description: "Dotkernel Admin is an open-source admin application (skeleton) built on Mezzio, Laminas and Doctrine. Table-based record management, RBAC guards, CSRF-protected forms and 2FA, over the same Core as Dotkernel API."
canonical_url: "https://www.dotkernel.com/admin/"
language: "en"
---

# Dotkernel Admin

Admin application . Server-rendered

An open-source application skeleton for standing up the administration site behind your platform.
A fast, reliable way to manage the records in your database with a simple table-based approach, and to build the reports and graphs that let you monitor what is happening - with the graphical components for an intuitive experience already in place.

- [Read the docs](https://docs.dotkernel.org/admin-documentation/)
- [View on GitHub](https://github.com/dotkernel/admin)
- [Live demo](https://admin7.dotkernel.net/)

| | |
| --- | --- |
| Runtime | Mezzio + Laminas |
| Templating | Twig |
| License | MIT |

## Request lifecycle

Session (`dot-session`) -> Router (`dot-router`) -> Authentication (`laminas-authentication`) -> RBAC guard (`dot-rbac-guard`) -> Your handler (PSR-15) -> Response (Twig template).

## The back office, not a framework to learn

Dotkernel Admin is the complementary application of the Dotkernel Headless Platform: an independent app built on the same Mezzio and Laminas foundation as Dotkernel API, sharing the same tech stack so the two form one consistent system rather than two codebases that merely talk to each other.

Authentication, role-based access control, CSRF-protected forms, validation, navigation and a dashboard are already assembled.
What you add is your own screens for your own entities.

Extending the power of Mezzio by Laminas.

- Table-based record management
- Every shipped form validated and CSRF-guarded
- Shares the Core module with API
- Twig templates, npm asset pipeline

## The unglamorous parts, already done

Everything below works in a fresh install.
The default modules are configured; your custom functionality needs the same configuration entries, and the docs say exactly which ones.

### RBAC guards - Security . Access control

Permissions declared in config, enforced per route handler.

`dot-rbac` and `dot-rbac-guard` work together: roles and their permissions live in `authorization.global.php`, while `authorization-guards.global.php` maps each route handler to the permissions it requires.
Add a route, add its rule - access control never drifts into your handlers.

### TOTP two-factor - Security . 2FA

A password plus a code that expires in 30 seconds.

`dot-totp` adds time-based one-time passwords following the industry standard: administrators authenticate with their password and a 6-digit code from an authenticator app.
Installation is a documented set of forms, handlers, middleware and three new columns.

- [Install guide](https://docs.dotkernel.org/admin-documentation/v7/tutorials/install-dot-totp/)

### CSRF protection - Security . Forms

A fresh token per render, on every form that ships.

Built from the `laminas-form` CSRF element, the `laminas-session` CSRF validator and the `formElement` view helper.
Tokens are not reusable between forms and expire after a configurable timeout, defaulting to one hour.

### Forms & input filters - Input . Validation

Validation rules that live beside the form, not in the handler.

`laminas-form` bridges your domain models and the view layer, while `laminas-inputfilter` normalizes and validates the submitted set.
Every form in the skeleton has its inputs filtered, so your own forms have a pattern to copy.

### Doctrine ORM - Data . Persistence

Migrations and fixtures, both driven from the CLI.

Doctrine ORM 3 and DBAL 4 over MariaDB or PostgreSQL, with UUID identifiers via `ramsey/uuid-doctrine`.
Generate a migration with `doctrine-migrations diff`, apply it with `migrate`, then seed the tables with `bin/doctrine fixtures:execute`.

### Attribute injection - Wiring . DI

Constructor injection declared where the constructor is.

`dot-dependency-injection` reads an `#[Inject]` attribute on the constructor and resolves each listed dependency - including values from a configuration key, by dot notation.
Register the class against `AttributedServiceFactory` and you are done writing factories by hand.

### Menus & UI components - Interface . Navigation

Configuration-driven menus, ready-made interface pieces.

`dot-navigation` defines and parses the top menu from `navigation.global.php`.
The `Page` module carries reusable dropdowns, modal popups, error displays and tooltips; the `Dashboard` module holds the landing page layout and its widgets.

### Commands & lock files - Operations . CLI

Cron-safe console commands out of the box.

`dot-cli` builds the console application on top of laminas-cli, writing lock files into `data/lock` so a scheduled command cannot overlap with itself.
GeoLite2 databases sync through `bin/cli.php geoip:synchronize`, quiet mode included for cron jobs.

### Mail and error handling - Operations . Mail & logs

Transactional mail configured in one file, errors in another.

`dot-mail` handles sendmail or SMTP delivery, sender identity and CC lists from `mail.global.php`.
`dot-errorhandler` writes daily log files to `log/`, with the format set in `error-handling.global.php`.

## Modules you can name before you read them

Admin follows PSR-4, with one folder per module.
Each module keeps its handlers, input filters and services together, plus a `ConfigProvider` and a `RoutesDelegator` - so the second module you write looks like the first.

### Shared domain layer

`Core\Admin` `Core\App` `Core\Security` `Core\Setting` `Core\User`

The Core module is a common codebase shared with the other applications in your project.
Each submodule holds its entities, repositories and its own ConfigProvider, so a user means the same thing to the admin screen and to the API endpoint.

### `Admin`

Managing the users that hold the `admin` role - the accounts stored in the `admin` database table.

### `User`

Managing the platform's own users, stored separately in the `user` table.
Two audiences, two models, no overloaded role column.

### `App`

Core application functionality: authentication, rendering and error reporting.

### `Dashboard`

The default landing page - its layout, widgets and rendering logic.

### `Page`

Reusable interface elements: dropdowns, modals, error displays, tooltips.

### `Setting`

Saving and reading display settings for the administration interface.

## From clone to login page

The full walkthrough, with expected output for every command, is in the documentation.
This is the shape of it.

### 1 . Clone the project

Into an empty directory of your choosing.

```shell
git clone https://github.com/dotkernel/admin.git .
```

### 2 . Install dependencies

Run it from the CLI so the setup prompts stay interactive.
Decline the ConfigProvider injection - Dotkernel ships its own.

```shell
composer install
```

### 3 . Enable development mode

For local work only.
`composer development-status` tells you where you stand, and it must stay off in production.

```shell
composer development-enable
```

### 4 . Configure the database

Fill in the credentials in `config/autoload/local.php`.
Both a MariaDB and a PostgreSQL connection are pre-declared; one is active at a time.

### 5 . Migrate and seed

Migrations build the schema; fixtures populate the default roles, OAuth clients and accounts.

```shell
php ./vendor/bin/doctrine-migrations migrate
php ./bin/doctrine fixtures:execute
```

### 6 . Build the assets

`npm run watch` recompiles while you work; `npm run prod` minifies for release.

```shell
npm install && npm run prod
```

Open the virtual host in your browser and the Dotkernel Admin login page is waiting.
If the fixtures ran, sign in with user `admin` and password `dotadmin` - the same credentials as the public demo, and the first thing to change before going live.

## What the server needs

| Component | Requirement |
| --- | --- |
| Operating system | A \*nix based system is strongly recommended for production. |
| PHP | 8.2 or newer, mod_php or FCGI (FPM). `memory_limit` at least 128M; `upload_max_filesize` and `post_max_size` at least 100M depending on your data. |
| Web server | Apache 2.2+ with `mod_rewrite` and `.htaccess` support (`AllowOverride All`) - a default `.htaccess` ships in `public/`. On Nginx, translate it into server configuration. |
| Database | MariaDB 10.7, 10.11 LTS, 11.4 LTS and 11.8 LTS, or PostgreSQL 13 and above. **MySQL is not supported**, as it has no UUID support. |
| Required extensions | `mbstring`, the CLI SAPI for cron jobs, and Composer available on `$PATH`. |
| Recommended extensions | `opcache`; `pdo_mysql`, `pdo_pgsql` or `mysqli` to match your database; `dom` and `simplexml` for markup; `gd` and `exif` for images; `zlib`, `zip`, `bz2` for compression; `curl` when calling APIs; `sqlite3` for the test suite. |

On Windows, WSL2 is the recommended development environment - Dotkernel provides an AlmaLinux distro implementation and an install script for the whole local stack.

## The checklist nobody writes down

Admin gives you the tools to build a safe application, and the documentation is explicit that some of them are yours to apply.
These are the ones worth checking off before the first deploy.

- [Security guide](https://docs.dotkernel.org/admin-documentation/v7/security/basic-security/)

### Before you go to production

- Change or remove the demo admin account - its identity and password are public.
- Review `cookie_httponly`, `cookie_samesite` and `cookie_secure` in `session.global.php`.
- Confirm development mode is off with `composer development-status`.
- Set your allowed origins in `cors.global.php`.
- Keep secrets in `*.local.php` - the `*.global.php` and `*.php.dist` files are committed.
- Add CSRF fields and authorization rules to every form and route you add.
- Watch dependencies on both sides: Composer advisories and `npm audit`.

## Upgrades you can read before you run them

Admin does not ship an automatic upgrade path, and that is deliberate: you implement the modifications listed for each release, in a codebase you already understand, instead of handing a migration script control over your customizations.

A `CHANGELOG.md` in the project root lists implemented features in reverse chronological order, so it doubles as your version marker.
From version 6.2 onward, the procedure is documented version to version, and releases are also published as an RSS feed.

- [Releases](https://github.com/dotkernel/admin/releases)
- [Upgrade guide](https://docs.dotkernel.org/admin-documentation/v7/upgrading/upgrading/)

### Coming from Admin 6.x?

Version 7 bumped dependencies, synchronised the Core module and refreshed the codebase to stay compatible with Dotkernel API v7 - the release that moved identifiers to native database UUIDs and dropped MySQL.

Work through the pull requests listed for 7.0, then copy the release notes into your own changelog so your project keeps tracking upstream.

## Better with an API in front of it

Admin installs and runs on its own.
Paired with Dotkernel API over the same `Core` namespaces, Admin manages the data while the API exposes it to third-party frontends and backends - and neither one disagrees about what an entity is.
The rest of the ecosystem is below.

### API - Pair with . HTTP surface

Expose the data you manage here to any client.

A REST API on a PSR-15 middleware pipeline, with OAuth 2.0, RBAC, HAL payloads and an OpenAPI 3.0 specification wired up on install.

- [Read more](https://www.dotkernel.com/api/)
- [GitHub](https://github.com/dotkernel/api)
- [Demo](https://api.dotkernel.net/)

### Queue - Pair with . Async work

Queue a bulk operation from an admin screen.

Background workers on Symfony Messenger - a TCP listener, Valkey streams, retries and a dead letter queue for what still fails.

- [Read more](https://www.dotkernel.com/queue/)
- [GitHub](https://github.com/dotkernel/queue)

### Frontend - Instead . Public-facing

The site your users log into, not your staff.

A web starter skeleton - user accounts, a contact form, sessions and RBAC-guarded controller actions, rendered on the server.

- [Read more](https://www.dotkernel.com/frontend/)
- [Demo](https://v5.dotkernel.net/)

### Light - Smaller . Minimal

No records to manage, just pages.

The smallest complete Mezzio application - routing, pipeline and Twig, six direct dependencies and no database layer.

- [Read more](https://www.dotkernel.com/light/)
- [Demo](https://light.dotkernel.net/)

### Dotboost - Tooling . AI context

Teach your AI tools this architecture.

Drop-in Claude Code configuration - ten commands, seventeen skills and permission guardrails that keep your secrets out of the context window.

- [Read more](https://www.dotkernel.com/dotboost/)
- [GitHub](https://github.com/dotkernel/dotboost)

New modules start with [dot-maker](https://docs.dotkernel.org/dot-maker/v1/overview/), which knows which files an Admin needs versus an API.
Support status for every layer is on the [packages lifecycle](https://www.dotkernel.com/dotkernel-packages-oss-lifecycle/) page.

## Open source, in production

Try it with the demo, keep it under MIT.

Sign in to the public demo with `admin` / `dotadmin` to see the interface before you install anything.
Dotkernel Admin is developed and led by the dev team at Apidemia, and released as open source for the community.

[Talk to us ->](https://www.dotkernel.com/contact/)


<!-- ============================================================ -->
<!-- md-pages/api.md -->
<!-- ============================================================ -->

---
title: "Dotkernel API | Open-source REST API skeleton for PHP"
description: "Dotkernel API is an open-source REST API skeleton built on Mezzio, Laminas and Doctrine. OAuth2, RBAC, HAL, problem details and OpenAPI 3.0 come wired together on install. MIT licensed."
canonical_url: "https://www.dotkernel.com/api/"
language: "en"
---

# Dotkernel API

REST API skeleton . PSR-15 middleware

An open-source REST API skeleton for PHP, built on the Mezzio microframework and Laminas components over a Doctrine domain layer.
OAuth 2.0, RBAC authorization, HAL payloads, standardized error responses and an OpenAPI 3.0 specification are assembled on install - not left as decisions for your first sprint.

- [Read the docs](https://docs.dotkernel.org/api-documentation/)
- [View on GitHub](https://github.com/dotkernel/api)
- [Live demo](https://api.dotkernel.net/)

| | |
| --- | --- |
| Runtime | Mezzio + Laminas |
| Persistence | Doctrine ORM |
| License | MIT |

## Request lifecycle

CORS (`mezzio-cors`) -> Router (FastRoute) -> Authentication (OAuth 2.0) -> RBAC guard (per route name) -> Your handler (PSR-15) -> Response (HAL / problem+json).
[All 19 stages](https://www.dotkernel.com/architecture/)

## A REST API you own from the first commit

Dotkernel API is the root of the Dotkernel Headless Platform: a REST API based on the Mezzio skeleton, using a PSR-compliant middleware stack as defined by the PHP Framework Interop Group.
Rather than relying on elements built into a framework, business logic is built explicitly - from handlers to dependencies - so you keep full control over your business logic and data architecture.

It scales down to a single microservice and up to an enterprise-grade API, and it has been developed and released continuously since 2018.

Extending the power of Mezzio by Laminas.

- Doctrine ORM, not Active Record
- Explicit wiring, no runtime magic
- Auth, docs and errors on install
- MIT licensed, actively maintained

## The parts every API needs, already connected

Each of these is configured and working in a fresh install.
Nothing here is a placeholder you have to research and assemble before you can serve your first authenticated endpoint.

### OAuth 2.0 - Security . Authentication

Bearer tokens, issued and validated by the API itself.

Authentication runs on `mezzio-authentication-oauth2`, which wraps `league/oauth2-server` to provide OAuth 2.0 for PSR-7 / PSR-15 applications.
Endpoints marked as authenticated require a valid Bearer token and answer `401 Unauthorized` without one.

### RBAC per route - Security . Authorization

Three levels of protection: none, authenticated, authorized.

Roles and their permissions are declared in configuration and allocated per route name, with role inheritance supported.
An authenticated request that lacks the required permission gets a `403 Forbidden` - decided by config, not scattered through your handlers.

### OpenAPI 3.0 - Contract . Documentation

A machine-readable contract, generated from the code that serves it.

Every module documents its endpoints in an `OpenAPI.php` file, which `zircote/swagger-php` turns into a specification rendered through Swagger UI or Redoc.
A Postman collection and environment ship alongside it, so every endpoint is ready to call by hand.

### Doctrine ORM - Data . Persistence

Your domain in entities, not in the query layer.

Doctrine ORM handles persistence, so you can focus on object-oriented business logic and treat storage as a secondary concern.
Migrations, fixtures via `dot-data-fixtures`, and multiple database connections are part of the setup.

### HAL & problem details - Contract . Responses

One predictable shape for resources, one for failures.

Payloads are built with `mezzio-hal`, describing each resource together with its relational links and embedded child resources.
Errors return problem details responses via `mezzio-problem-details`, giving clients standardized error codes system-wide.

### Content negotiation - Contract . Negotiation

Client and server agree on format and language up front.

Content negotiation is implemented out of the box through the `Content-Type` and `Accept` headers, so diverse systems can consume the same API without custom glue on either side.
CORS preflight requests are recognized and configured by `mezzio-cors`.

### Error reporting endpoint - Operations . Feedback

A channel for the bugs that never reach your logs.

Frontend developers can report incorrect behaviour by posting to `/error-report` with a token header.
The API validates the request against configured tokens, domains and IPs before logging it - useful precisely when nothing fatal was thrown.

### Commands & file locker - Operations . CLI

Scheduled work that refuses to trample itself.

Console commands are registered through `dot-cli` on top of Symfony Console, and `php ./bin/cli.php route:list` prints every endpoint the application exposes.
The file locker, enabled by default, writes a lock file per command so a second instance cannot start while the previous run is still going - the safeguard cron jobs usually lack.

### Transactional email - Operations . Mail

Account mail that works before you configure anything.

`dot-mail` wraps Symfony Mailer with templated messages, so account activation and password reset send out of a fresh install.
It joins the request flow only where it is needed - the rest of the pipeline is unchanged whether a route sends mail or not.

### dot-maker - Productivity . Scaffolding

New modules that already match the house style.

`dot-maker` generates project files and directories following the Dotkernel structure, and knows which files each application type needs.
It replaces hand-copied boilerplate with consistent, standardized scaffolding.

- [Docs](https://docs.dotkernel.org/dot-maker/v1/overview/)

## What version 7 changed

The latest release moves identifiers to native database UUIDs and broadens platform support.

### Native UUID v7

Identifier columns use the database's `uuid` type instead of `binary`, with values generated by `ramsey/uuid`.
You keep full control of the UUID version without depending on database extensions.

### PostgreSQL support

PostgreSQL joins the supported databases.
Because native UUID is required, you need PostgreSQL or MariaDB 10.7 or later; MySQL is no longer supported, as it has no UUID data type.

### PHP 8.5

The API targets PHP 8.5, with Dotkernel Admin on 8.4.
Dependencies are kept current, and the ecosystem's own packages track the versions Laminas and Doctrine support.

### Table prefixes

A configurable string can be prepended to every table name - the practical requirement when an API shares a database with an existing application.

### Clearer database configuration

Multi-connection setups spell out which connection is the default and how to switch to another, based on scenarios from real projects.

### Shared Core module

Common logic lives in a Core module kept as its own Git repository, which can be added as a submodule to any Dotkernel application so entities and queries stay consistent.

## Evolution, not a wall of versions

Dotkernel API favours an evolution pattern with a sunsetting mechanism over maintaining parallel API versions.
The same codebase evolves gradually and clients are given notice, instead of every change forking into another branch you have to keep alive.

The mechanism is `DeprecationMiddleware`: mark a handler with the `#[ResourceDeprecation]` attribute and the response carries `sunset` and `link` headers, so a client learns an endpoint is retiring from the endpoint itself rather than from a changelog it never read.

Full versioning stays reserved for major, format-level changes - the cases where it genuinely earns its maintenance cost.
The two approaches are not mutually exclusive.

- [API evolution guide](https://docs.dotkernel.org/api-documentation/v6/tutorials/api-evolution/)
- [Where it sits in the pipeline](https://www.dotkernel.com/architecture/)

### Coming from Laminas API Tools?

API Tools (formerly Apigility) is archived.
Dotkernel API is an actively maintained alternative with a middleware architecture, a permissive MIT license and a Doctrine data layer.

The comparison below is drawn from the full side-by-side write-up on our blog.

## Dotkernel API vs Laminas API Tools

| Feature | API Tools (formerly Apigility) | Dotkernel API |
| --- | --- | --- |
| First release | 2012 | 2018 |
| Architecture | MVC, event driven | Middleware |
| OSS lifecycle | Archived | Active |
| PHP version | ≤ 8.2 | See the PHP version badge for `dotkernel/api` |
| Style | REST, RPC | REST |
| Change management | Versioning | Deprecations (API evolution) |
| Documentation | Swagger (automated) | OpenAPI 3.0 (Swagger) and Postman (manual) |
| License | BSD-3 | MIT |
| Default DB layer | laminas-db | doctrine-orm 3.x |
| Authorization | ACL | RBAC guard |
| Authentication | HTTP Basic / Digest, OAuth 2.0 | OAuth 2.0 |
| Endpoint generator | Yes | dot-maker |
| PSR standards | PSR-7 | PSR-7, PSR-15 |

Comparison drawn against Dotkernel API v7.
Read the reasoning behind each row in [Dotkernel API versus Laminas API Tools](https://www.dotkernel.com/dotkernel-api/dotkernel-api-versus-laminas-api-tools/).

## Runs alone, or as one of three

Dotkernel API is a complete application on its own.
When you add Admin or Queue, all three declare the same `Core` namespaces, so a `User` means the same thing to the endpoint that creates it, the admin screen that moderates it, and the worker that emails it.
The rest of the ecosystem is below.

### Shared domain layer

`Core\App` `Core\Admin` `Core\User` `Core\Security` `Core\Setting`

One set of entities and repositories, committed in each repository so a single-component start just works.
Having many entities in Core does not oblige you to implement handlers for all of them - each application handles only what it needs.

### Admin - Pair with . Back office

Manage the same data your API serves.

Table-based record management with RBAC guards, CSRF-protected forms and 2FA, over the same Core module.
Start with either one and add the other later.

- [Read more](https://www.dotkernel.com/admin/)
- [GitHub](https://github.com/dotkernel/admin)
- [Demo](https://admin7.dotkernel.net/)

### Queue - Pair with . Async work

Move slow work off the request cycle.

Background workers on Symfony Messenger - a TCP listener, Valkey streams, retries and a dead letter queue for what still fails.

- [Read more](https://www.dotkernel.com/queue/)
- [GitHub](https://github.com/dotkernel/queue)

### Frontend - Instead . Server-rendered

When your users want pages, not payloads.

A web starter skeleton - user accounts, a contact form, sessions and RBAC-guarded controller actions, rendered on the server.

- [Read more](https://www.dotkernel.com/frontend/)
- [Demo](https://v5.dotkernel.net/)

### Light - Smaller . Minimal

A presentation site with no API behind it.

The smallest complete Mezzio application - routing, pipeline and Twig, six direct dependencies and no database layer.

- [Read more](https://www.dotkernel.com/light/)
- [Demo](https://light.dotkernel.net/)

### Dotboost - Tooling . AI context

Teach your AI tools this architecture.

Drop-in Claude Code configuration - ten commands, seventeen skills and permission guardrails that keep your secrets out of the context window.

- [Read more](https://www.dotkernel.com/dotboost/)
- [GitHub](https://github.com/dotkernel/dotboost)

Every layer is also available on its own - see the [packages lifecycle](https://www.dotkernel.com/dotkernel-packages-oss-lifecycle/) for the support status of each `dot-*` package.

## Built on interfaces, checked on every change

### [PSR-15 & PSR-7](https://www.php-fig.org/psr/psr-15/)

Handlers implement `RequestHandlerInterface` and return `ResponseInterface`.
The whole request path is middleware you can read top to bottom.

### [PSR-11 & PSR-4](https://www.php-fig.org/psr/psr-11/)

The application is container-based, with dependencies declared in each module's `ConfigProvider`, and classes located by autoloader.

### [PSR-3 logging](https://www.php-fig.org/psr/psr-3/)

Errors are logged through `LoggerInterface` via `dot-errorhandler`, centralizing how failures are recorded.

### [PHPStan at level 8](https://phpstan.org/)

Static analysis runs at a strict rule level, in line with the choice made by projects like Doctrine and Composer.

### Functional & unit tests

The skeleton ships with a test suite you extend rather than start, so new endpoints have somewhere to be tested from day one.

### An active community

Updates arrive with bugfixes and improvements from the PHP community, and breaking changes come with companion articles and upgrade steps.

[Join the discussion ->](https://github.com/orgs/dotkernel/discussions)

## Install it and call an endpoint

Create the project with Composer, point it at PostgreSQL or MariaDB 10.7+, run the migrations, and you have an authenticated REST API with a browsable OpenAPI specification.

- [Installation guide](https://docs.dotkernel.org/api-documentation/)
- [Try the demo](https://api.dotkernel.net/)

### composer create-project dotkernel/api

The installer walks through database credentials and the initial configuration.
Follow the installation guide for the exact command and post-install steps for your target version, then use `dot-maker` to scaffold your first module.

Questions along the way go to [Dotkernel Discussions](https://github.com/orgs/dotkernel/discussions) - the team answers issues on both Dotkernel and Laminas components.

## Open source, in production

An API foundation you can read, audit and keep.

Dotkernel API is developed and led by the dev team at Apidemia - built first as an internal tool for handling complex architectures, released under MIT as our way of giving back to the community.

[Talk to us ->](https://www.dotkernel.com/contact/)


<!-- ============================================================ -->
<!-- md-pages/architecture.md -->
<!-- ============================================================ -->

---
title: "Architecture | How a request moves through a Dotkernel application"
description: "The PSR-15 middleware pipeline behind Dotkernel API, stage by stage: error boundary, routing, content negotiation, deprecation headers, OAuth 2.0, RBAC and dispatch - plus the library flow underneath it."
canonical_url: "https://www.dotkernel.com/architecture/"
language: "en"
---

# How a request moves through a Dotkernel application

Architecture . PSR-15 pipeline

Every Dotkernel application is a stack of PSR-15 middleware with no framework runtime hidden underneath it.
A request enters at the error boundary, passes through routing, negotiation, authentication and authorization, and reaches your handler - and you can read every layer it crossed on the way.

- [Read the docs](https://docs.dotkernel.org/api-documentation/)
- [See pipeline.php](https://github.com/dotkernel/api/blob/7.0/config/pipeline.php)
- [Dotkernel API](https://www.dotkernel.com/api/)

| | |
| --- | --- |
| Contract | PSR-7 + PSR-15 |
| Container | PSR-11 |
| Logging | PSR-3 |

## Five phases, 19 stages

Error boundary (1 stage) -> Request preparation (4 stages) -> Routing (4 stages) -> Contract & headers (4 stages) -> Identity (2 stages) -> Dispatch & fallback (4 stages).

## Framework-less, not framework-free

Dotkernel is an opinionated, framework-less tool aimed at intermediate-to-advanced programmers.
Framework-less does not mean nothing is underneath: Mezzio and Laminas components are there, and they are excellent.
It means there is no framework runtime deciding things on your behalf.
The pipeline is a list you wrote, in a file you can open, executed top to bottom.

That is the whole trade.
You give up the convenience of conventions you never have to look at, and you get an application where every layer between the socket and your handler is named, ordered and yours to reorder.

Extending the power of Mezzio by Laminas.

- Gradual learning curve
- Fine-tuned security
- KISS, YAGNI, DRY
- Long-term support

## Nineteen stages, in the order they run

This is the default pipeline of Dotkernel API, unedited.
Each stage receives the request, may hand it onward, and may alter the response on the way back out - which is why the error boundary is first in and last out.

Legend: Mezzio / Laminas component . Dotkernel.

### Error boundary

#### 01 . ProblemDetailsMiddleware - mezzio/mezzio-problem-details

The outermost layer, deliberately.
Anything thrown deeper in the stack is handed to `dot-errorhandler` for logging and comes back as a problem details response, so a failure reaches the client as a documented error shape rather than a stack trace.

### Request preparation

#### 02 . MalformedRequestBodyMiddleware - dotkernel/api

Rejects a body that is not valid JSON up front, before any later stage tries to read it and fails in a less legible place.

#### 03 . BodyParamsMiddleware - mezzio/mezzio-helpers

Parses the raw request body into the parsed body according to its `Content-Type`.

#### 04 . ServerUrlMiddleware - mezzio/mezzio-helpers

Seeds the server URL helper with the current scheme and host, so anything generating a URL later produces an absolute one.

#### 05 . CorsMiddleware - mezzio/mezzio-cors

Recognises preflight requests and answers them, and attaches the configured CORS headers to everything else.
It sits before routing so a preflight never needs a matched route.

### Routing

#### 06 . RouteMiddleware

*mezzio/mezzio-router* - Route

Matches the request against the route table and registers the `RouteResult` attribute.
Everything below this line can ask which route was matched - and most of it does.

#### 07 . ImplicitHeadMiddleware - mezzio/mezzio-router

Answers `HEAD` for routes that only declare `GET`.

#### 08 . ImplicitOptionsMiddleware - mezzio/mezzio-router

Answers `OPTIONS` with the methods the matched path actually allows.

#### 09 . MethodNotAllowedMiddleware - mezzio/mezzio-router

Returns `405 Method Not Allowed` when the path matched but the method did not.
Order matters here: it has to sit after both implicit handlers, or it would answer the requests they exist to serve.

### Contract & headers

#### 10 . ContentNegotiationMiddleware - dotkernel/api

Reconciles the client's `Accept` and `Content-Type` with what the matched route is configured to serve, so diverse consumers share one API without custom glue.

#### 11 . DeprecationMiddleware - dotkernel/api

The mechanism behind API evolution.
It reads the `#[ResourceDeprecation]` attribute off the handler and, when one is present, sets the `sunset` and `link` response headers - the client learns an endpoint is going away from the endpoint itself, rather than from a migration guide.

#### 12 . ResponseHeaderMiddleware - dotkernel/dot-response-header

Applies the headers you configure application-wide to every outgoing response, in one place instead of per handler.

#### 13 . UrlHelperMiddleware - mezzio/mezzio-helpers

Seeds the URL helper with the routing result, so handlers and HAL links can be generated relative to the route that was actually matched.

### Identity

#### 14 . AuthenticationMiddleware

*dotkernel/api* - 401

Validates the OAuth 2.0 Bearer token.
Routes declared as authenticated answer `401 Unauthorized` without a valid one, and never reach the handler.

#### 15 . AuthorizationMiddleware

*dotkernel/api* - 403

Checks the authenticated identity's role against the permissions allocated to the matched route name, and returns `403 Forbidden` when it falls short.
The decision lives in configuration, not scattered through handlers.

### Dispatch & fallback

#### 16 . ResourceProviderMiddleware - dotkernel/api

Reads the `#[Resource]` attribute on the handler's `handle()` method and loads the named entity through Doctrine using the route placeholder.
The handler receives a resource rather than an identifier, and a record that does not exist becomes a `404` before your code runs.

#### 17 . DispatchMiddleware - mezzio/mezzio-router

Hands the request to the matched PSR-15 handler.
This is your code - everything above was getting the request into a state where your handler only has to do its own job.

#### 18 . ProblemDetailsNotFoundHandler - mezzio/mezzio-problem-details

Reached only when nothing above returned a response: emits `404` in problem details form.

#### 19 . GetNotFoundResourceHandler - dotkernel/api

The last stage in the pipeline, shaping the not-found response for API clients.

## The packages underneath, in the same order

The same journey seen one level down - which library owns each step.
The second column shows how little changes when a feature is added: sending an email inserts one package and leaves the rest of the flow alone.

### Default flow

A request that reads or writes data and returns a resource.

1. Request
2. mezzio/mezzio-problem-details
3. dotkernel/dot-errorhandler
4. mezzio/mezzio-cors
5. mezzio/mezzio-router
6. dotkernel/dot-response-header
7. mezzio/mezzio-helpers
8. mezzio/mezzio-authentication
9. mezzio/mezzio-authorization
10. mezzio/mezzio-router *dispatch*
11. laminas/laminas-diactoros *not found*
12. dotkernel/dot-dependency-injection
13. doctrine/orm
14. mezzio/mezzio-hal
15. laminas/laminas-diactoros
16. psr/http-message
17. Response

### Flow for sending an email

Identical until the domain layer, where `dot-mail` joins in.

1. Request
2. mezzio/mezzio-problem-details
3. dotkernel/dot-errorhandler
4. mezzio/mezzio-cors
5. mezzio/mezzio-router
6. dotkernel/dot-response-header
7. mezzio/mezzio-helpers
8. mezzio/mezzio-authentication
9. mezzio/mezzio-authorization
10. mezzio/mezzio-router *dispatch*
11. laminas/laminas-diactoros *not found*
12. dotkernel/dot-dependency-injection
13. doctrine/orm
14. dotkernel/dot-mail *added*
15. mezzio/mezzio-hal
16. laminas/laminas-diactoros
17. psr/http-message
18. Response

## Built on interfaces from the Framework Interop Group

Dotkernel applications are collections of PSR-7 middleware.
The standards below are not badges - they are the reason a package from one vendor drops into a pipeline built by another.

### [PSR-7](https://www.php-fig.org/psr/psr-7/)

HTTP messages are immutable value objects.
Every stage above receives a request and returns a response, and neither is a global you have to guard.

### [PSR-15](https://www.php-fig.org/psr/psr-15/)

Middleware and request handlers share one interface, which is what makes the pipeline a plain ordered list rather than a framework-specific event graph.

### [PSR-11](https://www.php-fig.org/psr/psr-11/)

The application is container-based, with each module declaring its dependencies in a `ConfigProvider`.

### [PSR-4](https://www.php-fig.org/psr/psr-4/)

Classes are located by autoloader from their namespace, so where a file lives is never a question of configuration.

### [PSR-3](https://www.php-fig.org/psr/psr-3/)

Errors are logged through `LoggerInterface` via `dot-errorhandler`, reached from the error boundary at stage one.

### Why it matters

You can delete any stage in the pipeline, or write your own and pipe it in, without asking a framework's permission.
That is the practical payoff of standardising on interfaces.

[All PSR standards ->](https://www.php-fig.org/psr/)

## One pipeline shape, three applications

The stages differ where the job differs - Admin adds sessions and CSRF-protected forms, Queue swaps HTTP dispatch for a message consumer - but the pattern is constant, and all three declare the same `Core` namespaces underneath.

### Shared domain layer

`Core\App` `Core\Admin` `Core\User` `Core\Security` `Core\Setting`

Kept as its own Git repository and added as a submodule, so an entity means the same thing to the endpoint that creates it, the admin screen that moderates it and the worker that emails it.

### [API](https://www.dotkernel.com/api/)

The pipeline documented above, in full.

### [Admin](https://www.dotkernel.com/admin/)

Same shape, plus sessions, CSRF-protected forms and 2FA in the identity phase.

### [Queue](https://www.dotkernel.com/queue/)

The same middleware thinking applied to messages instead of requests.

## The pipeline is one file

Everything on this page comes from `config/pipeline.php` - about ninety lines, most of them comments explaining where to add your own middleware.
There is no generated layer between that file and what runs.

- [Installation guide](https://docs.dotkernel.org/api-documentation/)
- [Try the demo](https://api.dotkernel.net/)

### php ./bin/cli.php route:list

Once the pipeline has routed a request, the route table is the other half of the picture.
This command lists every endpoint the application exposes, which is the fastest way to review an API you have just inherited.

Database migrations are generated and run the same way, through the Doctrine console commands registered by `dot-cli`.

## Open source, in production

No layer you are not allowed to read.

Dotkernel is developed and led by the dev team at Apidemia - built first as an internal tool for handling complex architectures, released under MIT as our way of giving back to the community.

[Talk to us ->](https://www.dotkernel.com/contact/)


<!-- ============================================================ -->
<!-- md-pages/dotboost.md -->
<!-- ============================================================ -->

---
title: "dotboost | Claude Code configuration for Dotkernel projects"
description: "dotboost is a drop-in .claude/ directory that teaches Claude Code the conventions of any Dotkernel application - ten commands, seventeen skills, six hooks, and permission guardrails that keep secrets out of the context."
canonical_url: "https://www.dotkernel.com/dotboost/"
language: "en"
---

# Dotboost

Developer tooling . AI context

Drop-in configuration that teaches Claude Code the conventions of any Dotkernel application - API, Admin, Frontend, Light, Queue, or a project derived from one of them.
Every skill detects the variant first and applies the matching dialect, so generated code follows your architecture instead of guessing at it.

- [View on GitHub](https://github.com/dotkernel/dotboost)
- [Claude Code docs](https://docs.claude.com/en/docs/claude-code/overview)

| | |
| --- | --- |
| Payload | One .claude/ directory |
| Commands | Ten /dk-* |
| Skills | Seventeen |

## What happens in a session

Session start (variant briefing) -> Skill loads (by description) -> Plan mode (proposes first) -> Guard hooks (Edit . Bash) -> Normalise (BOM . CRLF . EOF) -> Lint (`php -l` . markdown).

## Not an application - a configuration payload

Dotboost is not itself a Dotkernel application.
Its entire payload is the `.claude/` directory: settings, hooks, a status line, a review subagent, ten `/dk-*` commands and seventeen skills.
You install it by copying that directory into the Dotkernel project you are working on.

There is no routing table telling Claude which skill to pick - each one loads from its own description.
Ask where a new Doctrine entity goes and it should reach for the module-structure skill rather than answering from general framework knowledge.

Maintained by **Borsan Sergiu**.

- Detects the variant before it answers
- Secrets never enter the context window
- Guards catch compound commands globs miss
- Copy it in - nothing to build or install

## The reason to adopt the file

The permission rules in `settings.json` fall into four tiers.
The first one is the headline: these are `Read` denies, not write protection, so the contents never enter the context window at all.

### Your secrets - Tier . Never read

Not redacted - never loaded.

`.env`, every `*.local.php`, `config/autoload/local.php`, `local.test.php` and `data/oauth/`.
Database credentials, OAuth signing keys and environment secrets stay out of the transcript.

### Generated & vendored - Tier . Never written

The files a diff should never touch by accident.

Dependency manifests - `composer.json`, `composer.lock`, `package.json`, `package-lock.json` - plus `vendor/`, `node_modules/`, `data/`, `log/`, `public/uploads/` and anything under `Migration/`.

### Installs & destructive git - Tier . Never run

Commands that change your tree without a diff.

`composer require`, `remove`, `update`, `install`, `global`; the npm, yarn and pnpm install verbs; `git push`, `reset --hard`, `clean`, `submodule`; and `rm -rf`.

### Your call - Tier . Ask & allow

Preference, not policy - override per machine.

**Ask**: migrations, `bin/doctrine`, database clients, git commits and merges, pipeline and authorization config, the QA config files.
**Allow**: the Composer QA scripts, `vendor/bin` tools, `php -l`, and read-only git.
Layer changes in `settings.local.json`, never the shared file.

### Where globs cannot see - Hooks . Six

Path patterns miss what a shell can hide.

`guard-bash.sh` inspects the command itself, so `cd src && composer require foo` is caught where a path-based rule would let it through.
`guard-protected-paths.sh` covers edits, and redirects a blocked `*.local.php` edit to its `.dist` template.

### Linters that do not rewrite - Hooks . Report only

Deliberately no `phpcbf`, no `--fix`.

`php-lint.sh` and `markdown-lint.sh` report and stop, because reformatting a file right after it is written invalidates the in-memory copy and breaks the next targeted edit.
Bulk formatting belongs at the end of a task.
Both skip silently when their tool is missing.

`settings.json` is a committed file carrying opinions, not only guardrails: sessions start in **plan mode**, the terminal UI is full screen, the theme is dark, and Composer runs without a memory ceiling.
Know what you are adopting.

## Where the hooks overrule the tiers

Some commands marked *ask* in `settings.json` are refused outright by `guard-bash.sh`, because the hook sees compound commands the permission globs cannot.
The prompt you would expect never appears - you get a refusal.
This is deliberate, and worth knowing before it surprises you.

| Command | settings.json says | guard-bash.sh does |
| --- | --- | --- |
| git rebase | ask | blocks |
| doctrine-migrations migrate / execute | ask | blocks |
| fixtures:execute, schema:drop, schema:update | ask, via bin/cli.php | blocks |
| composer development-enable / -disable | - | blocks |
| pip install, git checkout --, git filter-branch | - | blocks |

Everything else under *ask* - commits, database clients, the config and QA files - prompts as documented.
To get a blocked command back you edit the hook; relaxing `settings.local.json` will not reach it.

## Ten `/dk-*` commands

Each one runs only when you ask for it.

| Command | What it does |
| --- | --- |
| /dk-bootstrap | Fresh clone to a running install. |
| /dk-module | Plan a new module - dot-maker first. |
| /dk-route | Add a fully wired endpoint or page. |
| /dk-trace | Trace a request through pipeline, handler and response. |
| /dk-test | Write and run tests. |
| /dk-document | Write or update a feature doc. |
| /dk-check | Run and fix the QA gate. |
| /dk-deprecate | Make an evolution-pattern breaking change. |
| /dk-review | Pre-PR convention review - read-only by design. |
| /dk-hygiene | Encoding and line-ending audit. |

## Seventeen skills, loaded on demand

Sixteen `dotkernel-*` skills plus `dependency-policy`.
Each is a living document - when a review turns up the same mistake twice, that is a missing line in a skill.

| Skill | Covers |
| --- | --- |
| application-variants | Detecting API vs Admin vs Frontend vs Light vs Queue. |
| module-structure | Where code goes: application module vs Core, and the wiring. |
| handler-naming | Both naming dialects, routes, authorization keys. |
| doctrine-entities | Entities, enums and DBAL types, repositories, migrations. |
| input-validation | InputFilters, Inputs, forms, CSRF, query whitelisting. |
| responses | HAL and collections, or templates and redirects; errors. |
| openapi | swagger-php attributes, for apps that publish OpenAPI. |
| feature-docs | Feature docs: template, where they live, staleness. |
| testing | Unit and functional patterns, test config, coverage matrix. |
| evolution-pattern | Sunset headers instead of versioning. |
| security | Auth, authorization, secrets, CORS, dependencies. |
| dot-maker | `composer make …` and the manual steps after it. |
| core-submodule | Core layering rules and git submodule mechanics. |
| psr-standards | PSR-1/3/4/6/7/11/12/15/16/17 as applied here. |
| qa-gate | cs-check, static analysis, tests, and forbidden "fixes". |
| troubleshooting | A symptom to cause table. |
| dependency-policy | The ladder from installed packages to hand-rolled code, and the proposal format. |

A review subagent, `dotkernel-reviewer`, runs the convention review in its own context so the main one stays clean.

## Never name a package from memory

The ladder is: already in `composer.lock`, then `dotkernel/*`, then `laminas/*` and `mezzio/*`, then a vetted community package, and only then hand-rolled code.
Stop at the first hit.

A skill's description decides whether it *can* load, not whether Claude stops to think before naming a package.
The rule that makes it reach for the skill has to be always loaded - which means it lives in your project's own `CLAUDE.md`, not in the skill.

- [The block to paste](https://github.com/dotkernel/dotboost#add-this-to-your-projects-claudemd)

### Three things about how that behaves

- The `dotkernel/*` manifest is generated on first use, not shipped - the first package question runs the sync script itself. It needs `curl`, `jq` and network; without them Claude is told to call a package name **unverified** rather than assert it.
- Neither that script nor `composer show --available` is in the allow or deny list, so both prompt. That is deliberate - expect a prompt the first time.
- "How do I send mail from here?" is a package question. Implicit ones count.

## Copy one directory into your project

The payload has to sit at the root of your project.
Two routes to the same files - pick whichever suits the machine you are on.

### 1 . Clone it inside the project

Shallow, because only the current state of `main` is any use in a target project.
The clone goes away right after the copy.

```shell
git clone --depth 1 \
  https://github.com/dotkernel/dotboost.git .dotboost
cp -r .dotboost/.claude .claude
rm -rf .dotboost
```

### 1b . Or download the zip

No git needed, which is the point.
The archive unpacks to `dotboost-main/` and does carry the dotfiles.

```shell
curl -L -o dotboost.zip https://github.com/\
dotkernel/dotboost/archive/refs/heads/main.zip
unzip -q dotboost.zip
cp -r dotboost-main/.claude .claude
```

### 2 . Restore the executable bits

Nothing is committed executable, and a zip extracted on Windows carries no permission bits at all.
The sync script is the one called by its own name.

```shell
chmod +x .claude/hooks/*.sh .claude/statusline.sh \
  .claude/skills/dependency-policy/scripts/*.sh
```

### 3 . Keep local overrides out of git

Then copy the example file if you want personal settings that survive an update.

```shell
echo '.claude/settings.local.json' \
  >> .git/info/exclude
```

### 4 . Optional: markdown linting

Not bundled - install it yourself, globally or as a project devDependency.
Until the binary resolves, the hook exits silently.

```shell
npm install -g markdownlint-cli2
```

### 5 . Paste the CLAUDE.md block

The dependency policy and, if you want feature docs actually read, the feature-docs block alongside it.

If the project already has its own `.claude/settings.json` or `.claude/commands/`, merge by hand rather than running `cp -r` blind - same-named files are overwritten.
To update later, run the whole install again over the top; anything you changed in the project's copy is lost, which is exactly why personal changes belong in `settings.local.json`.

## The parts you notice on day two

### Feature documentation - Docs . /dk-document

The part a cleared session cannot reconstruct from `src/`.

One markdown file per feature - what it does, why, the routes and the roles that reach them, the data added, how to exercise it.
Where it lands is detected, not assumed: `documentation/features/` when that directory exists, `docs/features/` otherwise, never a second documentation root beside an existing one.
The frontmatter is load-bearing - `/dk-review` greps `routes:` and `handlers:` to decide whether a new route in the diff is documented.

### Real usage, not guesses - Status line

The same numbers `/usage` reports.

5h and 7d account usage in the status bar, read from the rate-limit payload Claude Code 2.1+ passes on stdin.
Pure bash and awk - no `jq`, no python, no transcript scanning or guessed token budgets, so it works in Git Bash on Windows.

### A briefing, every time - Session start

What it detected, before you ask anything.

Which variant, the root namespace, the authorization style, the branch, which config files are still missing - and a CRLF warning when it finds one.
The same hook prints the feature-docs directory and a doc count, so the files are discoverable even without the CLAUDE.md block.

### CRLF, handled - Windows . Line endings

Dotkernel repos ship `* text eol=lf`.

Belt and braces, configure the client so nothing converts: `core.autocrlf false`, `core.eol lf`, `core.safecrlf warn`.
Already committed CRLF? Renormalise once with `git add --renormalize .`.
`normalize-file.sh` keeps new writes clean.

## Every variant, one payload

The application-variants skill detects which Dotkernel application it is looking at - including a project derived from one - and every other skill applies the matching dialect.
Handler naming, response shape and authorization keys all differ between them, which is the whole reason the detection runs first.

### Detected variants

`API` `Admin` `Frontend` `Light` `Queue`

Before adapting the skills to a new Dotkernel application, the advice from its maintainer is to spend an hour reading that repo and correcting them against what is actually there.
A skill written from framework docs rather than the codebase produces confident wrong answers, which is worse than no skill.

### API - Variant . Detected

Handlers, HAL collections, OpenAPI attributes.

A REST API on a PSR-15 middleware pipeline, with OAuth 2.0, RBAC, HAL payloads and an OpenAPI 3.0 specification wired up on install.

- [Read more](https://www.dotkernel.com/api/)
- [GitHub](https://github.com/dotkernel/api)

### Admin - Variant . Detected

Forms, CSRF, route-name authorization keys.

Table-based record management with RBAC guards, CSRF-protected forms and 2FA, over the shared Core module.

- [Read more](https://www.dotkernel.com/admin/)
- [GitHub](https://github.com/dotkernel/admin)

### Frontend - Variant . Detected

Action controllers and action-level guards.

A web starter skeleton - user accounts, a contact form, sessions and RBAC-guarded controller actions, rendered on the server.

- [Read more](https://www.dotkernel.com/frontend/)
- [GitHub](https://github.com/dotkernel/frontend)

### Light - Variant . Detected

Minimal modules, config-declared template routes.

The smallest complete Mezzio application - routing, pipeline and Twig, six direct dependencies and no database layer.

- [Read more](https://www.dotkernel.com/light/)
- [GitHub](https://github.com/dotkernel/light)

### Queue - Variant . Detected

Message handlers and background workers.

Background workers on Symfony Messenger - a TCP listener, Valkey streams, retries and a dead letter queue for what still fails.

- [Read more](https://www.dotkernel.com/queue/)
- [GitHub](https://github.com/dotkernel/queue)

## Open source, in production

Context your AI tools do not have to guess at.

Dotboost is maintained by Borsan Sergiu and released as open source alongside the rest of the Dotkernel ecosystem.
Treat the skills as living documents - the repository is where corrections belong.

[Read the full README ->](https://github.com/dotkernel/dotboost)


<!-- ============================================================ -->
<!-- md-pages/frontend.md -->
<!-- ============================================================ -->

---
title: "Dotkernel Frontend | Server-rendered PHP web starter"
description: "Dotkernel Frontend is a web starter skeleton on Mezzio and Laminas - user accounts, a contact form, RBAC guards, CSRF-protected forms, flash messages and GDPR account anonymization, server-rendered in Twig."
canonical_url: "https://www.dotkernel.com/frontend/"
language: "en"
---

# Dotkernel Frontend

Web starter . Server-rendered

A web starter skeleton on the Mezzio microframework and Laminas components, for the applications people log into.
User accounts, a working contact form and a content page ship as proof of concept - real, running features whose only job is to show you where your own code goes.

- [Read the docs](https://docs.dotkernel.org/frontend/)
- [View on GitHub](https://github.com/dotkernel/frontend)
- [Live demo](https://v5.dotkernel.net/)

| | |
| --- | --- |
| Runtime | Mezzio + Laminas |
| Pattern | Action controllers |
| Templating | Twig |

## Request lifecycle

Session (`dot-session`) -> Router (FastRoute) -> Authentication (User identity) -> RBAC guard (route + action) -> Controller action (`dot-controller`) -> Response (Twig + flash).

## The web application half of the stack

Frontend is the skeleton for a server-rendered application with users in it.
Where Light gives you pages, Frontend gives you the machinery around them: sessions, authentication, registration, validated forms, flash messages between redirects, and role-based access to individual controller actions.

The shipped features - contact us, a generic content page, user accounts - are deliberately presented as building blocks rather than a finished product.
They exist to showcase the file architecture and to be copied.

Extending the power of Mezzio by Laminas.

- User accounts, from register to unregister
- Action controllers, not request handlers
- CSRF and reCAPTCHA on public forms
- GDPR anonymization out of the box

## Everything a logged-in site needs first

These are the parts you would otherwise spend your first two weeks assembling, already working together in a fresh install.

### Registration & login - Users . Accounts

The whole account lifecycle, already routed.

Login, registration and account management, including avatar upload, password change and unregistering.
Password reset and account activation emails are part of the flow, which is why the skeleton stores a name and an email address and nothing more.

### Guards per action - Security . Access control

Permissions applied to individual controller actions.

`dot-rbac-guard` and `dot-rbac` read roles and permissions from `authorization.global.php`, then `authorization-guards.global.php` maps rules onto a route and a named list of its actions - or an empty list to cover all of them.
Fine-grained without being scattered.

### CSRF tokens - Security . Forms

A new token per render, validated on submit.

Built from the `laminas-form` CSRF element, a `laminas-session` CSRF validator in the input filter, and the `formElement` view helper in the template.
Tokens expire after a configurable timeout - one hour by default - and are never reusable between forms.

### Contact form with reCAPTCHA - Public . Contact

A public form that does not become a spam relay.

The contact form uses Google reCAPTCHA, with the site and secret keys read from local configuration and the message recipients - `to` and any number of `cc` addresses - configured alongside them.
Whitelist `localhost` while developing, and take it out again for production.

### Flash messages - UX . Feedback

The message survives the redirect.

`dot-flashmessenger` carries session messages across redirects - the small piece that makes post-then-redirect flows feel finished.
`dot-session` extends laminas-session underneath, configured in `session.global.php`.

### Attribute injection - Wiring . DI

Constructor injection declared on the constructor.

`dot-dependency-injection` reads an `#[Inject]` attribute and resolves each listed dependency - a service, the whole `config` array, or a single key by dot notation.
Register the class against `AttributedServiceFactory` and stop writing factories.

### Doctrine ORM - Data . Persistence

Migrations and fixtures, driven from the CLI.

Doctrine through `roave/psr-container-doctrine`, with UUIDs as a field type via `ramsey/uuid-doctrine`.
Migrations live in `data/doctrine/migrations`; `bin/doctrine fixtures:execute` seeds the default roles.

### Headers & CORS - Delivery . HTTP

Response headers declared per route.

`dot-response-header` sets custom headers per route from `response-header.global.php`, while `mezzio-cors` handles origins, headers and cookies from `cors.global.php`.

### Menus, templates, i18n - Content . Presentation

Navigation from configuration, translation when you need it.

`dot-navigation` defines and parses menus inside templates from configuration.
`dot-twigrenderer` adds Dotkernel's Twig extensions, and `laminas-i18n` is present for a complete translation suite.
The `Plugin` module carries dynamic forms and templates.

## Account anonymization, not just deletion

Under the GDPR, a company recording personal data from EU citizens must delete it on request - or anonymize it, which the European Commission accepts as an alternative.
Frontend implements the second option, because deleting a user row is rarely what your foreign keys want.

The skeleton stores only what it needs to run those flows: first name, last name and the email address used as the identity, for password reset and account activation.
Anonymizing replaces exactly those.

- [Anonymization reference](https://docs.dotkernel.org/frontend-documentation/v5/reference/account-anonymization/)

### What anonymization changes

- First and last name become `anonymous` plus the current UNIX timestamp - for example `anonymous1725980747`.
- The email becomes the same value plus whatever you set in `userAnonymizeAppend` - `anonymous1725980747@example.com`.
- The avatar image and its database record are deleted.

Point `userAnonymizeAppend` at a domain you control and it doubles as a catch-all address, if your mail provider supports one.
Leave it empty and the local part stands alone.

## Five modules, PSR-4 throughout

Each module keeps its controllers, entities, repositories and services together, alongside a `ConfigProvider` and a `RoutesDelegator` - so a new feature has an obvious shape before you write it.

### `User`

Login, registration and account management - the largest module, and the one worth reading first.

### `App`

Core functionality: authentication, rendering and error reporting.

### `Contact`

The contact us form, from validation through to the outgoing mail.

### `Page`

Displaying a page - the minimal case, for static copy.

### `Plugin`

Plugin functionality for dynamic forms and templates.

### Module contents

`Controller`, `Entity`, `Repository` and `Service` folders, plus `InputFilter`, `EventListener`, `Helper`, `Command` or `Factory` as needed.

## From clone to welcome page

The documentation walks through every command with its expected output.
This is the sequence.

### 1 . Clone into an empty folder

Git refuses a non-empty directory, and you need write permissions on it.

```shell
git clone https://github.com/dotkernel/frontend.git .
```

### 2 . Install dependencies

From the CLI, so the prompts stay interactive.
Decline the config provider injection - Frontend ships its own.

```shell
composer install
```

### 3 . Enable development mode

Sets debug on, configuration caching off, and clears any existing cache.

```shell
composer development-enable
```

### 4 . Prepare the config files

Copy the `.dist` files into place - `local.php`, `development.local.php`, `mail.local.php`, `debugbar.local.php` - then fill in the database, SMTP and reCAPTCHA details.

### 5 . Migrate and seed

Migrations build the schema and are logged so none runs twice; the fixtures populate the default user roles.

```shell
php vendor/bin/doctrine-migrations migrate
php bin/doctrine fixtures:execute
```

### 6 . Fix permissions and open it

Three writable paths cover almost every first-run error.

```shell
chmod -R 777 data log public/uploads
```

Two local-only notes worth keeping: `session.cookie_secure` has to be `false` in your own `local.php` - never in `local.php.dist`, where it stays `true` for production - and a stale `data/cache/config-cache.php` is loaded regardless of `ConfigAggregator::ENABLE_CACHE`, so clear it with `bin/clear-config-cache.php` when services go missing.
Duplicating `local.test.php.dist` gives your tests an in-memory database.

## What the server needs

| Component | Requirement |
| --- | --- |
| Operating system | A \*nix based system is strongly recommended for production. |
| PHP | 8.2 or newer, mod_php or FCGI (FPM). `memory_limit` at least 128M; `upload_max_filesize` and `post_max_size` at least 100M depending on your data. |
| Web server | Apache 2.2+ with `mod_rewrite` and `.htaccess` support (`AllowOverride All`); a default `.htaccess` ships in `public/`. On Nginx, translate it into server configuration. |
| Database | Tested with MariaDB 10.11 LTS and 11.4 LTS, and with MySQL 8.4 LTS. For MySQL 8.4, `my.cnf` needs `mysql_native_password=ON`. |
| Required extensions | `mbstring`, the CLI SAPI for cron jobs, and Composer on `$PATH`. |
| Recommended extensions | `opcache`; `pdo_mysql` or `mysqli`; `dom` and `simplexml` for markup; `gd` and `exif` for images; `zlib`, `zip`, `bz2` for compression; `curl` when calling APIs; `sqlite3` for the test suite. |

Note that Frontend still supports MySQL - unlike API and Admin v7, which require native UUID support and therefore PostgreSQL or MariaDB 10.7+.

## Where Frontend sits

Frontend stands on its own, outside the Headless Platform.
It is the right starting point when your users log in and your pages are rendered on the server - and the wrong one in both directions from there.

### Light - Smaller . Minimal

No users, no database, no forms to protect.

The smallest complete Mezzio application - routing, pipeline and Twig, six direct dependencies.
Right for a presentation site.

- [Read more](https://www.dotkernel.com/light/)
- [Demo](https://light.dotkernel.net/)

### API - Different . HTTP surface

Your frontend is someone else's framework.

A REST API on a PSR-15 middleware pipeline, with OAuth 2.0, RBAC, HAL payloads and an OpenAPI 3.0 specification wired up on install.

- [Read more](https://www.dotkernel.com/api/)
- [Demo](https://api.dotkernel.net/)

### Admin - Bigger . Platform

You need a back office over a shared domain.

Table-based record management with RBAC guards, CSRF-protected forms and 2FA, over a Core module shared with API and Queue.

- [Read more](https://www.dotkernel.com/admin/)
- [Demo](https://admin7.dotkernel.net/)

### Queue - Alongside . Async work

Move the registration email off the request.

Background workers on Symfony Messenger - a TCP listener, Valkey streams, retries and a dead letter queue for what still fails.

- [Read more](https://www.dotkernel.com/queue/)
- [GitHub](https://github.com/dotkernel/queue)

### Dotboost - Tooling . AI context

Teach your AI tools this architecture.

Drop-in Claude Code configuration - ten commands, seventeen skills and permission guardrails that keep your secrets out of the context window.

- [Read more](https://www.dotkernel.com/dotboost/)
- [GitHub](https://github.com/dotkernel/dotboost)

## Open source, in production

Accounts, forms and compliance - already handled.

Dotkernel Frontend is developed and led by the dev team at Apidemia and released as open source for the community.
Try the demo to see the account flows before you install anything.

[Talk to us ->](https://www.dotkernel.com/contact/)


<!-- ============================================================ -->
<!-- md-pages/index.md -->
<!-- ============================================================ -->

---
title: "Dotkernel - A Headless Platform for Modern Web Applications"
description: "Dotkernel is a collection of open-source PHP application skeletons built on Mezzio and Laminas, ranging from a minimal presentation-site skeleton to a full headless platform (API, Admin, Queue) for enterprise-grade applications."
url: "https://www.dotkernel.com/"
language: "en"
entities:
  - name: "Dotkernel API"
    type: "SoftwareApplication"
    url: "https://github.com/dotkernel/api"
  - name: "Dotkernel Admin"
    type: "SoftwareApplication"
    url: "https://github.com/dotkernel/admin"
  - name: "Dotkernel Queue"
    type: "SoftwareApplication"
    url: "https://github.com/dotkernel/queue"
  - name: "Dotkernel Light"
    type: "SoftwareApplication"
    url: "https://github.com/dotkernel/light"
  - name: "Dotkernel Frontend"
    type: "SoftwareApplication"
    url: "https://github.com/dotkernel/frontend"
  - name: "Mezzio"
    type: "SoftwareFramework"
    url: "https://github.com/mezzio/mezzio-skeleton"
  - name: "Dotkernel Development Environment"
    type: "SoftwareApplication"
    url: "https://github.com/dotkernel/development"
  - name: "Dotboost"
    type: "SoftwareApplication"
    url: "https://github.com/dotkernel/dotboost"
standards: ["PSR-7", "PSR-11", "PSR-15"]
keywords: ["headless platform", "PHP", "Mezzio", "Laminas", "PSR-15 middleware", "REST API", "admin panel", "task queue", "open source"]
---

# Dotkernel

## TL;DR

Dotkernel is a collection of open-source PHP application skeletons built on Mezzio and Laminas, licensed MIT.
Its headless platform combines three components - **API**, **Admin**, and **Queue** - that can be adopted separately or together.
Two additional skeletons, **Light** and **Frontend**, stand outside the platform for simpler or frontend-only use cases.

## Key facts

| Fact | Value |
|---|---|
| Runtime | Mezzio + Laminas |
| Standards | PSR-7, PSR-11, PSR-15 |
| License | MIT |
| Router | FastRoute |
| Response | Diactoros |
| Maintainer | Apidemia |

## Request lifecycle

Router (FastRoute) -> Authentication (dot-authentication) -> RBAC guard (dot-rbac-guard) -> your PSR-15 handler -> Response (Diactoros).

## The headless platform: three applications, one platform

API, Admin, and Queue are designed to integrate into a single, unified headless platform - better together than the sum of their parts.

| Component | Role | Repository |
|---|---|---|
| **API** | REST APIs on a readable PSR-15 middleware pipeline - no kernel, no facades, no runtime magic. OAuth2, RBAC, and OpenAPI included | https://github.com/dotkernel/api |
| **Admin** | Table-based backend for managing platform records, plus tools to build reports and dashboards | https://github.com/dotkernel/admin |
| **Queue** | Background job processing for the platform - dispatch work from API or Admin and run it in a separate worker, built on Symfony Messenger | https://github.com/dotkernel/queue |

## Skeletons outside the platform

Not every project needs a headless platform - these two stand on their own.

| Skeleton | Purpose | Repository |
|---|---|---|
| **Light** | The smallest complete Mezzio application - PSR-15 pipeline, routing, and templating, nothing to strip out. A real starting point for a simple site | https://github.com/dotkernel/light |
| **Frontend** | A web starter skeleton for full-stack applications on Mezzio and Laminas - server-rendered Twig views, forms, sessions, and RBAC-guarded routes | https://github.com/dotkernel/frontend |

## Developer tooling

A production-like environment on your machine, and the context your AI tools need to write Dotkernel code.

| Tool | Purpose | Repository |
|---|---|---|
| **Development Environment** | AlmaLinux on WSL2 for a RHEL-compatible local stack. One install script configures PHP, Apache, MariaDB, Git, Composer, Node.js, and phpMyAdmin | https://github.com/dotkernel/development |
| **Dotboost** | Dotkernel context for AI coding tools - current standards, architectural patterns, and framework idioms, so generated code matches the ecosystem instead of guessing at it | https://github.com/dotkernel/dotboost |

## Components (dot-* packages)

Small, independent packages - pull in what you need. Grouped by concern: authentication (dot-authentication, dot-auth-social), authorization (dot-authorization, dot-rbac, dot-rbac-guard), controllers (dot-controller), forms (laminas-form), session (dot-session, dot-flashmessenger, dot-cache), logging & error handling (dot-log, dot-errorhandler), emailing (dot-mail), backend/database abstraction (doctrine/orm, doctrine/dbal, dot-data-fixtures), navigation (dot-navigation), templating (dot-twigrenderer), and supporting tools (dot-annotated-services, dot-event, dot-helpers, dot-cli, dot-doctrine-metadata, dot-response-header, dot-user-agent-sniffer, dot-debugbar, dot-geoip).

Full package list and lifecycle/support status: https://www.dotkernel.com/dotkernel-packages-oss-lifecycle/

## About

Dotkernel is an open-source project created and led by the dev team at Apidemia - built first as an internal tool for handling complex architectures, now freely shared with the community.

## Resources

- Documentation: https://docs.dotkernel.org
- GitHub organization: https://github.com/dotkernel
- Blog: https://www.dotkernel.com/blog/
- Categories: https://www.dotkernel.com/categories/
- Contact: https://www.dotkernel.com/contact/


<!-- ============================================================ -->
<!-- md-pages/light.md -->
<!-- ============================================================ -->

---
title: "Dotkernel Light | Minimal PSR-15 site skeleton for PHP"
description: "Dotkernel Light is a minimal PSR-15 application skeleton on Mezzio and Laminas, for presentation sites and small services. Six direct dependencies, Twig templating, Vite assets, no database layer."
canonical_url: "https://www.dotkernel.com/light/"
language: "en"
---

# Dotkernel Light

Minimal skeleton . PSR-15

A PSR-15 compliant application skeleton on the Mezzio microframework and Laminas components, designed as a minimal project for generating a simple website - a presentation site, a landing page, a small service.
Six direct dependencies, two modules, and nothing to delete before you start.

- [Read the docs](https://docs.dotkernel.org/light-documentation/)
- [View on GitHub](https://github.com/dotkernel/light)
- [Live demo](https://light.dotkernel.net/)

| | |
| --- | --- |
| Runtime | Mezzio + Laminas |
| Templating | Twig |
| Direct deps | Six |

## Request lifecycle

`index.php` (bootstrap) -> Container (factories . aliases) -> Routing (FastRoute) -> Pipeline (`pipeline.php`) -> Handler (PSR-15) -> Twig (layout . blocks) -> Emitter (HtmlResponse).

## The smallest complete Mezzio application

Light is what remains when you take a real PSR-15 application and remove everything a presentation site does not need.
There is no ORM, no authentication stack, no admin scaffolding - not disabled, simply not installed.
What you get is routing, a middleware pipeline, Twig, and error logging.

That makes it two things at once: a genuine starting point for a small site, and the clearest way to read how a Mezzio application is put together, because there is almost nothing else in the way.

Extending the power of Mezzio by Laminas.

- Six direct dependencies
- No database layer to configure
- A new page is one config line and one template
- Twig layout, Vite asset pipeline

## Six packages, and you can name all of them

This is the entire direct dependency list.
Every one of them is doing a job you would have had to solve anyway.

### [mezzio/mezzio](https://github.com/mezzio/mezzio)

The PSR-15 middleware microframework the whole application runs on.

### [mezzio-fastroute](https://github.com/mezzio/mezzio-fastroute)

FastRoute integration - matches the URL and method against your registered routes.

### [mezzio-twigrenderer](https://github.com/mezzio/mezzio-twigrenderer)

Twig integration for Mezzio.
Every template is a `.html.twig` file.

### [dot-errorhandler](https://github.com/dotkernel/dot-errorhandler)

Logging error handler for middleware applications - daily log files, configured in one place.

### [laminas-config-aggregator](https://github.com/laminas/laminas-config-aggregator)

Collects and merges configuration from every source into one array.

### [laminas-component-installer](https://github.com/laminas/laminas-component-installer)

The Composer plugin that injects modules and config providers during installation.

Two modules ship in `src/`: `App` for core functionality - rendering and error reporting - and `Page` for displaying a page.
Each module keeps its `Handler`, `Factory` and `Service` folders next to a `ConfigProvider` and a `RoutesDelegator`, following PSR-4.

## A request, end to end

Eleven steps from the browser to the rendered page, with nothing hidden behind a kernel.
This is the sequence you can follow in the source.

| # | Step | What happens |
| --- | --- | --- |
| 1 | HTTP request | `public/index.php` bootstraps the application, loads configuration, and creates the Mezzio application instance. |
| 2 | Service container | Factories, aliases and delegators are registered; every service is configured and ready to use. |
| 3 | Route registration | All available routes and their allowed methods are read and registered dynamically, managed by FastRoute. |
| 4 | Middleware pipeline | `config/pipeline.php` defines the order middleware runs in, and so how requests travel and responses come back. |
| 5 | Routing | FastRoute matches the URL and method against the registered routes to find the handler. |
| 6 | Handler invocation | The matched route name is pulled off the request and passed to the renderer - `page::about` becomes the template to render. |
| 7 | Custom logic | Your business logic runs in the handler, calling whatever services it needs. |
| 8 | Template rendering | Twig loads the template, applies the layout, renders the blocks and includes the partials. |
| 9 | Response creation | An `HtmlResponse` is built with status, headers and the rendered HTML body. |
| 10 | Response pipeline | The response flows back out through the middleware stack, which can still change headers, cookies or compression. |
| 11 | Response emitter | The final response is sent to the browser. |

Handlers, not controllers - that is what keeps the application PSR-15 compliant.
Each module's `RoutesDelegator` reads the route config from the container and registers the routes it finds, so adding a page never means touching the framework.

## Adding a page is two files

Routes live in configuration as `slug => template` pairs.
Append a line, create the matching Twig template in `src/Page/templates/page/`, and add a link to the menu in the layout.
The handler works out which template to render from the matched route name, so there is no handler to write.

Want your templates in more than one folder?
Add another entry under `paths` in the Page module's `ConfigProvider` - the key does not have to match the folder name.

- [Creating pages](https://docs.dotkernel.org/light-documentation/v1/how-tos/create-pages/)

### One route, one template

In `config/autoload/local.php`, under the `routes` -> `page` key:

```php
'example-page' => 'example-template',
```

Then create the template it names:

```text
src/Page/templates/page/example-template.html.twig
```

The key is the page slug, the value is the template.
Your new page answers at `/page/example-page`, under the route name `page::example-template`.

## Assets, menus and social cards

The parts you actually edit on a presentation site, and where each of them lives.

### Asset pipeline - Build . Vite

One command while you work, one before you ship.

Vite concatenates and compresses CSS and JavaScript, preprocesses SCSS, and copies fonts and images - avoiding the network bottleneck of many separate files.
`npm run watch` recompiles on change; `npm run build` compiles once.
Node.js v20 is the minimum supported version.

### assets -> public - Build . Source of truth

Edit the source, never the output.

Images, fonts, JavaScript and SCSS live in `src/App/assets/`.
The build deletes and rebuilds `css`, `js`, `fonts` and `images` under `public/` - anything you edit there by hand is lost on the next run.
Everything else in `public/` is left alone.

### Cache busting - Build . Caching

The oldest bug in web deployment, solved in one character.

Browsers cache your built CSS and JS, so a deploy can leave visitors on the old file.
Add a version parameter to the asset URL in the layout - `app.css?v=3` - and increment it whenever you commit a change to that file.

### Menu and footer - Content . Navigation

Plain Twig in one layout file.

The top menu is the list under `id="navbarHeader"` in `src/App/templates/layout/default.html.twig`; each `li` is one item, and items can be grouped into dropdowns or styled as buttons.
The footer is the `app-footer` element in the same file.

### Twitter & OpenGraph - Content . Sharing

Cards for when your pages get posted elsewhere.

Add the card meta tags to the layout head, generating URLs with the same helper the canonical block uses - `{{ url(routeName ?? null) }}` - which also keeps mistyped URLs from breaking the page.

### Errors and logs - Operations . Logs

A log file per day, from the first request.

`dot-errorhandler` writes daily files into `log/`, in the format set under the `stream` key of `error-handling.global.php`.
Development mode adds the error handlers you want locally and nowhere else.

## Running in minutes, honestly

No database to create, no fixtures to seed.
Clone, install, set a URL, open it.

### 1 . Clone into an empty folder

Git refuses a directory that is not empty, and you need write permissions on it.

```shell
git clone https://github.com/dotkernel/light.git .
```

### 2 . Install dependencies

Run it from the CLI so the prompts stay interactive.
Decline the config provider injection - Light already includes its own.

```shell
composer install
```

### 3 . Enable development mode

Local work only.
`composer development-status` reports where you stand.

```shell
composer development-enable
```

### 4 . Set the base URL

Point `$baseUrl` in `config/autoload/local.php` at your virtual host.

### 5 . Fix the writable folders

The two directories the application writes to.
Most first-run errors are this and nothing else.

```shell
chmod -R 777 ./data ./log
```

### 6 . Open it in a browser

The Dotkernel Light welcome page is waiting.
Errors about missing services usually mean a stale config cache.

```shell
php ./bin/clear-config-cache.php
```

A cached `data/cache/config-cache.php` is loaded regardless of the `ConfigAggregator::ENABLE_CACHE` setting - which is exactly why clearing it fixes so much.
On Windows, WSL2 with AlmaLinux is the recommended development environment.

## What the server needs

| Component | Requirement |
| --- | --- |
| Operating system | A \*nix based system is strongly recommended for production. |
| PHP | 8.2, 8.3 or 8.4, with mod_php or FCGI (FPM). `memory_limit` at least 128M. |
| Web server | Apache 2.2+ with `mod_rewrite` and `.htaccess` support (`AllowOverride All`); a default `.htaccess` ships in `public/`. On Nginx, translate it into server configuration. |
| Database | None. Light has no persistence layer - which is the point. |
| Required extensions | `mbstring`, plus Composer available on `$PATH`. |
| Recommended extensions | `opcache`; `dom` and `simplexml` for markup; `gd` and `exif` for images; `zlib`, `zip`, `bz2` for compression; `curl` if you call APIs. |

## When Light is the wrong answer

Light sits outside the Headless Platform on purpose.
It has no sessions, no forms, no authentication and no database - so the moment you need those, start from a skeleton that already has them rather than growing them here.

### Frontend - Instead . Full-stack web

You need logins, forms and sessions.

A server-rendered web starter on Mezzio and Laminas - Twig views, forms, sessions and RBAC-guarded routes, still standing on its own outside the platform.

- [Read more](https://www.dotkernel.com/frontend/)
- [GitHub](https://github.com/dotkernel/frontend)
- [Demo](https://v5.dotkernel.net/)

### API - Instead . HTTP surface

You are serving clients, not pages.

A REST API on a PSR-15 middleware pipeline, with OAuth 2.0, RBAC, HAL payloads and an OpenAPI 3.0 specification wired up on install.

- [Read more](https://www.dotkernel.com/api/)
- [GitHub](https://github.com/dotkernel/api)

### Admin - Instead . Back office

You need to manage records, not publish copy.

Table-based record management with RBAC guards, CSRF-protected forms and 2FA, over a Core module shared with the rest of the platform.

- [Read more](https://www.dotkernel.com/admin/)
- [GitHub](https://github.com/dotkernel/admin)

### Queue - Instead . Async work

You have work that outlives a request.

Background workers on Symfony Messenger - a TCP listener, Valkey streams, retries and a dead letter queue for what still fails.

- [Read more](https://www.dotkernel.com/queue/)
- [GitHub](https://github.com/dotkernel/queue)

### dotboost - Tooling . AI context

Teach your AI tools this architecture.

Drop-in Claude Code configuration - ten commands, seventeen skills and permission guardrails that keep your secrets out of the context window.

- [Read more](https://www.dotkernel.com/dotboost/)
- [GitHub](https://github.com/dotkernel/dotboost)

## Open source, in production

Small enough to read, real enough to ship.

Dotkernel Light is developed and led by the dev team at Apidemia, and released as open source for the community.
If you want to see the whole application before you commit to it, that is the entire promise of this skeleton.

[Talk to us ->](https://www.dotkernel.com/contact/)


<!-- ============================================================ -->
<!-- md-pages/queue.md -->
<!-- ============================================================ -->

---
title: "Dotkernel Queue | Asynchronous task queue for PHP"
description: "Dotkernel Queue runs time-consuming work on background workers instead of inside the request cycle. A Swoole TCP daemon, Valkey streams and Symfony Messenger, with retries, a dead letter queue and reporting commands."
canonical_url: "https://www.dotkernel.com/queue/"
language: "en"
---

# Dotkernel Queue

Background workers . Symfony Messenger

Some operations are time-consuming and resource-intensive, and they have no business inside a request.
Dotkernel Queue accepts them over a TCP connection, stores them, and runs them on background workers - so your platform answers the next request instead of waiting for a video to finish encoding.

- [Read the docs](https://docs.dotkernel.org/queue-documentation/)
- [View on GitHub](https://github.com/dotkernel/queue)

| | |
| --- | --- |
| Listener | Swoole on TCP |
| Store | Valkey streams |
| Worker | Symfony Messenger |

## Message lifecycle

Your application (JSON payload) -> TCP :8556 (IP whitelisted) -> Swoole daemon (accepts & stores) -> messages stream (Valkey . FIFO) -> Messenger worker (your handler) -> failed stream (after 3 retries).

## A separate machine for the slow work

Dotkernel Queue is built on **Symfony Messenger**, integrated into Mezzio and Laminas applications through the `netglue/laminas-messenger` adapter for the Laminas Service Manager container.
Work runs decoupled from the regular request-response cycle, on background workers that can live on their own hardware.

The main platform returns its response and stays responsive to new requests.
Tasks with long execution times are scheduled to run when resources are available, oldest first.

Extending the power of Mezzio by Laminas.

- High request rate without overloading
- FIFO - the oldest message runs first
- Retries with exponential backoff
- Failures parked, never blocking the queue

## Work that should never block a response

Tasks suited to the queue take extended periods to execute and may be interrupted by PHP limits such as `max_execution_time`; depend on external systems that add authentication delays, slow replies, or fail outright when a server is offline; or simply are not part of the PHP response at all.

### Data processing

Big data analytics, scientific simulations, mathematical computations - anything where the data size or the algorithm sets the clock.

### File & media processing

Video and image processing, compressing and decompressing large files.

### Networking

Uploading and downloading large files, where bandwidth rather than your code is the limit.

### Database operations

Imports, exports and migrations that would otherwise hold a web request open.

### System & infrastructure

OS updates, software compilation, CI pipelines triggered from your application.

### Transactional email

The classic case: hand the message to the queue and let the worker compose and send it while the server moves to the next task.

[Sending emails ->](https://docs.dotkernel.org/queue-documentation/v2/how-to/send-emails/)

## Two daemons, one stream

A listener that accepts messages fast, and a worker that processes them carefully.
They are separate systemd services, so you can restart either one without losing the other.

### The TCP listener - Ingest . Swoole

Accepts connections and gets out of the way.

An active daemon listens for TCP connections on a port - 8556 by default - and stores incoming messages immediately.
This supports a large number of requests per second without overloading, because accepting a message is all it does.

### The messages stream - Store . Valkey

An open-source key/value datastore built for this shape of work.

Messages land in the `messages` stream, the main queue.
The worker consumes from it in FIFO order - the oldest request first, then newer ones - and processes each according to your application logic.
Valkey is BSD-licensed and handles caching, message queues, and primary datastore workloads.

### The worker - Process . Messenger

Your handler, running outside the request cycle.

A Messenger worker consumes the stream and hands each message to your handler.
Because it is a separate service on a separate machine if you want one, a slow job costs you worker time rather than user-facing latency.

### Dead letter queue - Resilience . DLQ

Failures get parked, not retried forever.

Each transport defines a retry strategy.
When a message exceeds its allowed retries it is forwarded automatically to the failure transport and stored in the `failed` stream - so a message that cannot succeed never blocks the ones behind it.

### Whitelisted senders - Security . Firewall

The port is open to your servers, not to the internet.

The documented setup adds a firewall rich rule that accepts traffic on the queue's port only from the source addresses you name.
Fast to evaluate, and a small attack surface for a service that takes instructions.

### Metrics you can query - Observability . Logs

Logging that answers the operational questions.

Processed and failed messages are logged, which is what makes the reporting commands possible: queue length, processing time per job, error rates, and throughput in jobs per second.

## Backoff, configured in one place

The transport's `retry_strategy` decides how hard the worker tries before a message is handed to the dead letter queue.
These are the shipped defaults.

| Setting | Default | What it controls |
| --- | --- | --- |
| `max_retries` | 3 | Attempts before the message moves to the failure transport. |
| `delay` | 1000 | Initial wait before retrying a failed message, in milliseconds. |
| `multiplier` | 2 | Each retry's delay is multiplied by this factor - exponential backoff. |
| `max_delay` | 0 | Ceiling on the wait between retries; 0 means unlimited or default behaviour. |
| `failure_transport` | `failed` | Where messages go once they exceed the retry limit. |

Both transports are Redis-protocol DSNs pointing at a stream - `messages` for new work, `failed` for what could not be processed - with the serializer configurable per transport.

## Console commands, over CLI or TCP

The same three commands answer from the shell on the queue server or from a socket on another machine.
Every flag is optional; when both `--start` and `--end` are given, `--limit` is ignored.

| Command | Returns | Invocation |
| --- | --- | --- |
| `failed` | Log entries for messages that failed to process. | `php bin/cli.php failed --start="yyyy-mm-dd" --end="yyyy-mm-dd" --limit=int` |
| `processed` | Log entries for messages processed successfully. | `php bin/cli.php processed --start="yyyy-mm-dd" --end="yyyy-mm-dd" --limit=int` |
| `inventory` | Everything currently queued in the `messages` stream. | `php bin/cli.php inventory` |
| `control` | A test message, logged as processed - the quickest end-to-end check. | `echo "control" \| socat -t1 - TCP:host:port` |

Valkey itself stays inspectable: `valkey-cli` gives you `PING`, `INFO`, `KEYS *`, and stream commands such as `XRANGE streamName - +` to read entries oldest to newest, or `XTRIM streamName MAXLEN 0` to empty a stream while keeping the key.

## Two ways to hand over a message

The **procedural** approach opens a TCP connection, writes the JSON payload, and closes the socket.
It is simple and quick to implement - and harder to reuse as the project grows.
Make sure the message ends with a newline, or the server will keep waiting for the rest of it.

The **object-oriented** approach wraps the queue in a service - a small `NotificationSystem` module under Core, built on `clue/socket-raw`, with its connection details injected from configuration.
Handlers then inject the service and call a method that describes the intent, not the transport.

- [Integration guide](https://docs.dotkernel.org/queue-documentation/v2/how-to/communication-with-queue/)

### Smoke-test the listener

From your local machine, with the daemon running and your IP whitelisted:

```shell
echo "Hello" | socat -T1 - TCP:SERVER-IP:8556
```

The `-T1` timeout is optional but wise: without it, a server that never replies leaves `socat` waiting indefinitely.

## A queue server, from a bare box

The documented path is AlmaLinux 9 or 10 with root access, adapted accordingly for other operating systems.
Everything runs as a non-root user.

### 1 . Prepare the server

Update the OS, create a user with sudo permissions, and install the utilities you will need - including `socat` for testing.

```shell
dnf update -y && useradd dotkernel
```

### 2 . Install the runtime

PHP from the Remi repository, plus the Swoole and Redis PECL extensions.
Verify both are loaded before moving on.

```shell
dnf module enable php:remi-8.5
dnf install php-pecl-swoole6 php-pecl-redis
```

### 3 . Install Valkey

Enable and start the service, then confirm it answers.

```shell
dnf install valkey
valkey-cli ping
```

### 4 . Clone and configure

Clone the queue branch, then copy each `.dist` configuration file into place - local, log, messenger and swoole - and fill them in.

```shell
git clone -b default-queue https://github.com/dotkernel/queue.git
composer install --no-dev
```

### 5 . Register the daemons

Set the paths in the shipped unit files, copy them into `/etc/systemd/system/`, then enable and start both.

```shell
systemctl enable --now swoole.service
systemctl enable --now messenger.service
```

### 6 . Close the door

Allow SSH before starting the firewall, then permit the queue port only from the addresses that should reach it.

```shell
firewall-cmd --permanent --add-rich-rule='rule family="ipv4" source address="YOUR_IP" port port="8556" protocol="tcp" accept'
```

Full commands, expected output and the reasoning behind each step are in the [server setup](https://docs.dotkernel.org/queue-documentation/v2/server-setup/) and [installation](https://docs.dotkernel.org/queue-documentation/v2/installation/) guides.

## The third deployable

Queue processes work produced by the rest of the platform.
Share the `Core` module with it - copied in or added as a submodule - and your worker has the same entities, services and mail configuration as the application that queued the job.

### Shared domain layer

`Core\Admin` `Core\App` `Core\Security` `Core\Setting` `Core\User`

Keep Core in sync between the main project and the queue and every class, service and configuration needed for message processing is already there - which is what makes a worker able to compose an email from your own templates.

### API - Pair with . HTTP surface

Dispatch work from an endpoint, answer immediately.

A REST API on a PSR-15 middleware pipeline, with OAuth 2.0, RBAC, HAL payloads and an OpenAPI 3.0 specification wired up on install.

- [Read more](https://www.dotkernel.com/api/)
- [GitHub](https://github.com/dotkernel/api)

### Admin - Pair with . Back office

Queue a bulk operation from an admin screen.

Table-based record management with RBAC guards, CSRF-protected forms and 2FA, over the same Core module.

- [Read more](https://www.dotkernel.com/admin/)
- [GitHub](https://github.com/dotkernel/admin)

### Frontend - Pair with . Public-facing

Queue the email your signup form triggers.

A web starter skeleton - user accounts, a contact form, sessions and RBAC-guarded controller actions, rendered on the server.

- [Read more](https://www.dotkernel.com/frontend/)
- [Demo](https://v5.dotkernel.net/)

### Light - Smaller . Minimal

A site with nothing to run in the background.

The smallest complete Mezzio application - routing, pipeline and Twig, six direct dependencies and no database layer.

- [Read more](https://www.dotkernel.com/light/)
- [Demo](https://light.dotkernel.net/)

### Dotboost - Tooling . AI context

Teach your AI tools this architecture.

Drop-in Claude Code configuration - ten commands, seventeen skills and permission guardrails that keep your secrets out of the context window.

- [Read more](https://www.dotkernel.com/dotboost/)
- [GitHub](https://github.com/dotkernel/dotboost)

The queue's own dependencies are the same small `dot-*` components the rest of the platform uses - each publishing its own support status on the [packages lifecycle](https://www.dotkernel.com/dotkernel-packages-oss-lifecycle/) page.

## Open source, in production

Let the slow work happen somewhere else.

Dotkernel Queue is developed and led by the dev team at Apidemia - built to keep real platforms responsive under real load, and released as open source for the community.

[Talk to us ->](https://www.dotkernel.com/contact/)


<!-- ============================================================ -->
<!-- md-pages/wsl2.md -->
<!-- ============================================================ -->

---
title: "Development Environment | AlmaLinux 10 on WSL 2"
description: "AlmaLinux 10 on WSL 2 for a RHEL-compatible local stack. One Ansible playbook installs PHP, Apache, MariaDB, Composer, Node.js and phpMyAdmin, and provisions a virtualhost for every project you add."
canonical_url: "https://www.dotkernel.com/wsl2/"
language: "en"
---

# Development Environment

Development environment . AlmaLinux 10 . WSL2

Dotkernel's local environment runs AlmaLinux 10 - inside WSL 2 on Windows, or on bare metal with no WSL at all.
One Ansible playbook installs PHP, Apache, MariaDB, Composer, Node.js and phpMyAdmin, and every project gets its own `*.localhost` virtualhost without touching a hosts file.

- [Read the docs](https://docs.dotkernel.org/development/v2/terminal/)
- [View on GitHub](https://github.com/dotkernel/development/tree/alma-linux-10)

| | |
| --- | --- |
| Distro | AlmaLinux 10 |
| Provisioning | Ansible |
| Host | WSL 2 or bare metal |

## Terminal to running stack

Terminal -> WSL 2 -> AlmaLinux -> Ansible -> Ready.

## The same OS family your servers run

AlmaLinux is a RHEL-compatible distribution, so the packages, package manager and service conventions you use locally - `dnf`, `systemd` and the rest - are the ones you will see again in staging and production.
WSL 2 puts that distro on a Windows machine without a second computer or a Windows-native rebuild of every tool.

Everything here also runs the same way without WSL, directly on a bare AlmaLinux 10 host - the Ansible playbooks do not know or care which one they are provisioning.

- RHEL-compatible, matches production
- One playbook, the whole stack
- Virtualhosts without touching hosts file
- Aliases for switching PHP & Node versions

## Three steps to a running shell

Each step runs in a different place - Windows Terminal for the first two, the AlmaLinux 10 shell for the third.
The full walkthrough, prompts and all, is in the docs.

### 1 . Terminal & requirements

Install Windows Terminal, then confirm WSL 2 is enabled - Hyper-V, Virtual Machine Platform and Windows Subsystem for Linux, all turned on in Windows features.

```shell
wsl -v
```

### 2 . Install AlmaLinux 10

Stop any other running distro, then install AlmaLinux 10 and create your Unix username and password when prompted.

```shell
wsl --install -d AlmaLinux-10
```

### 3 . Setup packages

Clone `dotkernel/development`, fill in `config.yml` with your Git identity and MariaDB root password, and let Ansible provision the rest.

```shell
ansible-playbook -i hosts install.yml --ask-become-pass
```

Not using WSL? Skip straight to Setup Packages on a bare AlmaLinux 10 host - the same playbook runs there unchanged.

## What one playbook installs

`install.yml` reads `config.yml` once and provisions every one of these - safe to re-run if a step fails partway through.

| Component | What you get |
| --- | --- |
| Web server | Apache, with virtualhosts routed automatically under `*.localhost`. |
| Database | MariaDB 11.4 LTS, plus phpMyAdmin for browsing it. |
| PHP | 8.4 by default via the Remi repository; `php81` … `php85` aliases switch versions. |
| Node.js | 22 by default via NodeSource; `node18` … `node24` aliases switch versions. |
| Git & Composer | Your Git identity from `config.yml`, and the latest Composer, kept current with `composer self-update`. |
| Ansible | `community.general` and `community.mysql` collections - the same tool that just installed itself. |

## Every project, its own subdomain

`api.dotkernel.localhost` and `frontend.dotkernel.localhost` can point at two different projects on the same machine, and Apache routes both without a single edit to the Windows hosts file - any `*.localhost` domain is routed automatically.

List the domains you want under `config.yml`'s `virtualhosts` key and run the playbook.
Existing entries are left untouched, so you keep adding to the same file as your project grows.

- [Read the virtualhosts docs](https://docs.dotkernel.org/development/v2/virtualhosts/overview/)

### One playbook, every domain

In `development/wsl/config.yml`, under `virtualhosts`:

```text
api.dotkernel.localhost
```

Then provision it:

```shell
ansible-playbook -i hosts create-virtualhost.yml --ask-become-pass
```

Files go under `/var/www/api.dotkernel.localhost/html`, with the document root at `html/public`.

## Common questions

The short version of the full FAQ - see the docs for the rest.

### How do I switch PHP versions?

Run `sudo dnf module switch-to php:remi-{major}.{minor} -y`, or use one of the predefined aliases: `php81`, `php82`, `php83`, `php84` or `php85`.

### How do I switch Node.js versions?

Use one of the predefined aliases - `node18`, `node20`, `node22` or `node24` - which reinstall Node.js from NodeSource at that major version.

### How do I fix permission issues?

Local development only: `chmod -R 777 data`, `log` or `public/uploads`, whichever directory the error names.

### Where are the error logs?

Apache: `/var/log/httpd/error_log`. PHP-FPM: `/var/log/php-fpm/error.log` and `www-error.log`.

### How do I update Composer?

`sudo /usr/local/bin/composer self-update`, then confirm with `composer --version`.

### How do I create command aliases?

Add `alias name="command"` to `.bash_profile` in your home directory, then run it like any other command.

### How do I delete a virtualhost?

Remove its folder under `/var/www/`, its Apache config and enabled-site symlink, then `sudo systemctl restart httpd`.

### Can I run this without WSL?

Yes - every instruction here works the same way on a bare AlmaLinux 10 host.

## Provision once, match production everywhere.

Built for how the platform ships.

The WSL 2 + AlmaLinux 10 setup is maintained by the same team behind the rest of the Headless Platform, so the local environment stays in step with what actually runs in production - not a Docker approximation of it.

[Talk to us ->](https://www.dotkernel.com/contact/)