initial push

.github/workflows/continuous-integration.yml

@@ -0,0 +1,11 @@
+name: "Continuous Integration"
+
+on:
+  pull_request:
+  push:
+    branches:
+    tags:
+
+jobs:
+  ci:
+    uses: laminas/workflow-continuous-integration/.github/workflows/[email protected]

.github/workflows/docs-build.yml

@@ -0,0 +1,16 @@
+name: docs-build
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+
+jobs:
+  build-deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Build Docs
+        uses: dotkernel/documentation-theme/github-actions/docs@main
+        env:
+          DEPLOY_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

.gitignore

@@ -0,0 +1,7 @@
+.idea
+docs/html
+documentation-theme
+
+composer.phar
+composer.lock
+vendor

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 DotKernel
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

composer.json

@@ -0,0 +1,13 @@
+{
+  "name": "dotkernel/admin-documentation",
+  "description": "DotKernel Admin documentation markdown files.",
+  "type": "metapackage",
+  "license": "MIT",
+  "authors": [
+    {
+      "name": "DotKernel Team",
+      "email": "[email protected]"
+    }
+  ],
+  "require": {}
+}

docs/book/index.md

@@ -0,0 +1 @@
+# ../../README.md

docs/book/v5/installation/composer.md

@@ -0,0 +1,27 @@
+# Composer Installation of Packages
+
+## Install dependencies
+
+```shell
+composer install
+```
+
+## Development mode
+
+If you're installing the project for development, make sure you have development mode enabled, by running:
+
+```shell
+composer development-enable
+```
+
+You can disable development mode by running:
+
+```shell
+composer development-disable
+```
+
+You can check if you have development mode enabled by running:
+
+```shell
+composer development-status
+```

docs/book/v5/installation/configuration-files.md

@@ -0,0 +1,16 @@
+# Configuration Files
+
+## Prepare config files
+* duplicate `config/autoload/local.php.dist` as `config/autoload/local.php`
+
+* duplicate `config/autoload/mail.local.php.dist` as `config/autoload/mail.local.php`
+
+### Note
+
+> if your API will send emails, make sure to fill in SMTP connection params
+
+* **optional**: in order to run/create tests, duplicate `config/autoload/local.test.php.dist` as `config/autoload/local.test.php`
+
+### Note
+
+> this creates a new in-memory database that your tests will run on.

docs/book/v5/installation/doctrine-orm.md

@@ -0,0 +1,47 @@
+# Doctrine ORM
+
+## Setup database
+
+Make sure you fill out the database credentials in `config/autoload/local.php` under `$databases['default']`.
+
+Create a new MySQL database - set collation to `utf8mb4_general_ci`
+
+## Running migrations
+
+Run the database migrations by using the following command:
+
+```shell
+php bin/doctrine-migrations migrate
+```
+
+This command will prompt you to confirm that you want to run it.
+
+> WARNING! You are about to execute a migration in database "..." that could result in schema changes and data loss. Are you sure you wish to continue? (yes/no) [yes]:
+
+Hit `Enter` to confirm the operation.
+
+## Executing fixtures
+
+**Fixtures are used to seed the database with initial values and should be executed after migrating the database.**
+
+To list all the fixtures, run:
+
+```shell
+php bin/doctrine fixtures:list
+```
+
+This will output all the fixtures in the order of execution.
+
+To execute all fixtures, run:
+
+```shell
+php bin/doctrine fixtures:execute
+```
+
+To execute a specific fixture, run:
+
+```shell
+php bin/doctrine fixtures:execute --class=FixtureClassName
+```
+
+More details on how fixtures work can be found here: https://github.com/dotkernel/dot-data-fixtures#creating-fixtures

docs/book/v5/installation/getting-started.md

@@ -0,0 +1,13 @@
+# Clone the project
+
+## Recommended development environment
+
+> If you are using Windows as OS on your machine, you can use WSL2 as development environment.
+> Read more here: [PHP-Mariadb-on-WLS2](https://www.dotkernel.com/php-development/almalinux-9-in-wsl2-install-php-apache-mariadb-composer-phpmyadmin/)
+
+Using your terminal, navigate inside the directory you want to download the project files into. Make sure that the
+directory is empty before proceeding to the download process. Once there, run the following command:
+
+```shell
+git clone https://github.com/dotkernel/admin.git .
+```

docs/book/v5/installation/manage-geolite2.md

@@ -0,0 +1,27 @@
+# Manage GeoLite2 database
+
+You can download/update a specific GeoLite2 database, by running the following command:
+
+    php bin/cli.php geoip:synchronize -d {DATABASE}
+
+Where _{DATABASE}_ takes one of the following values: `asn`, `city`, `country`.
+
+You can download/update all GeoLite2 databases at once, by running the following command:
+
+    php bin/cli.php geoip:synchronize
+
+The output should be similar to the below, displaying per
+row: `database identifier`: `previous build datetime` -> `current build datetime`.
+
+> asn: n/a -> 2021-07-01 02:09:34
+>
+> city: n/a -> 2021-07-01 02:09:20
+>
+> country: n/a -> 2021-07-01 02:05:12
+
+Get help for this command by running:
+
+    php bin/cli.php help geoip:synchronize
+
+**Tip**: If you setup the synchronizer command as a cronjob, you can add the `-q|--quiet` option, and it will output
+data only if an error has occurred.

docs/book/v5/installation/test-the-installation.md

@@ -0,0 +1,43 @@
+# Testing (Running)
+
+Note: **Do not enable dev mode in production**
+
+- Run the following command in your project's directory to start PHPs built-in server:
+
+      php -S 0.0.0.0:8080 -t public
+
+> Running command `composer serve` will do the exact same, but the above is faster.
+
+`0.0.0.0` means that the server is open to all incoming connections
+`127.0.0.1` means that the server can only be accessed locally (localhost only)
+`8080` the port on which the server is started (the listening port for the server)
+
+**NOTE:**
+If you are still getting exceptions or errors regarding some missing services, try running the following command
+
+    php bin/clear-config-cache.php
+
+> If `config-cache.php` is present that config will be loaded regardless of the `ConfigAggregator::ENABLE_CACHE`
+> in `config/autoload/mezzio.global.php`
+
+- Open a web browser and visit `http://localhost:8080/`
+
+You should see the `DotKernel admin` login page.
+
+If you ran the migrations you will have an admin user in the database with the following credentials:
+
+- **User**: `admin`
+- **Password**: `dotadmin`
+
+**NOTE:**
+
+- **Production only**: Make sure you modify the default admin credentials.
+- **Development only**: `session.cookie_secure` does not work locally so make sure you modify your `local.php`, as per the following:
+
+      return [
+        'session_config' => [
+            'cookie_secure' => false,
+        ]
+      ];
+
+Do not change this in `local.php.dist` as well because this value should remain `true` on production.

docs/book/v5/introduction/introduction.md

@@ -0,0 +1 @@
+DotKernel web starter package suitable for admin applications.

docs/book/v5/introduction/server-requirements.md

@@ -0,0 +1,36 @@
+# Server Requirements
+
+For production, we highly recommend a *nix based system.
+
+## Webserver
+
+* Apache >= 2.2 **or** Nginx
+* mod_rewrite
+* .htaccess support `(AllowOverride All)`
+
+## PHP >= 8.2
+
+Both mod_php and FCGI (FPM) are supported.
+
+## Required Settings and Modules & Extensions
+
+* memory_limit >= 128M
+* upload_max_filesize and post_max_size >= 100M (depending on your data)
+* mbstring
+* CLI SAPI (for Cron Jobs)
+* Composer (added to $PATH)
+
+## RDBMS
+
+* MariaDB >= 10.11 LTS
+
+## Recommended extensions
+
+* opcache
+* pdo_mysql or mysqli (if using MySQL or MariaDB as RDBMS)
+* dom - if working with markup files structure (html, xml, etc)
+* simplexml - working with xml files
+* gd, exif - if working with images
+* zlib, zip, bz2 - if compessing files
+* curl (required if APIs are used)
+* sqlite3 - for tests

mkdocs.yml

@@ -0,0 +1,26 @@
+docs_dir: docs/book
+site_dir: docs/html
+extra:
+  project: API
+  current_version: v5
+  versions:
+    - v4
+    - v5
+nav:
+  - Home: index.md
+  - v5:
+      - Introduction: v5/introduction/introduction.md
+      - Overview:
+          - "Server Requirements": v5/introduction/server-requirements.md
+      - Installation:
+          - "Getting Started": v5/installation/getting-started.md
+          - "Composer": v5/installation/composer.md
+          - "Configuration Files": v5/installation/configuration-files.md
+          - "Doctrine ORM": v5/installation/doctrine-orm.md
+          - "Manage Geolite2": v5/installation/manage-geolite2.md
+          - "Test the Installation": v5/installation/test-the-installation.md
+site_name: api
+site_description: "DotKernel API"
+repo_url: "https://github.com/dotkernel/api"
+plugins:
+  - search