Merge pull request #238 from dotkernel/issue-228

Documentation

.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/continuous-integration.yml@1.x

.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 }}

.laminas-ci/pre-run.sh

@@ -0,0 +1,15 @@
+JOB=$3
+PHP_VERSION=$4
+COMMAND=$(echo "${JOB}" | jq -r '.command')
+
+echo "Running $COMMAND"
+
+if [[ ${COMMAND} =~ phpunit ]];then
+
+  apt-get install php"${PHP_VERSION}"-sqlite3
+
+  cp config/autoload/local.php.dist config/autoload/local.php
+  cp config/autoload/mail.local.php.dist config/autoload/mail.local.php
+  cp config/autoload/local.test.php.dist config/autoload/local.test.php
+
+fi

README.md

@@ -10,28 +10,27 @@ Based on Enrico Zimuel's [Zend Expressive API - Skeleton example](https://github
 [![GitHub stars](https://img.shields.io/github/stars/dotkernel/api)](https://github.com/dotkernel/api/stargazers)
 [![GitHub license](https://img.shields.io/github/license/dotkernel/api)](https://github.com/dotkernel/api/blob/4.0/LICENSE.md)
 
-[![Build Static](https://github.com/dotkernel/api/actions/workflows/static-analysis.yml/badge.svg?branch=4.0)](https://github.com/dotkernel/api/actions/workflows/static-analysis.yml)
+[![Build Static](https://github.com/dotkernel/api/actions/workflows/continuous-integration.yml/badge.svg?branch=4.0)](https://github.com/dotkernel/api/actions/workflows/continuous-integration.yml)
 [![Build Static](https://github.com/dotkernel/api/actions/workflows/run-tests.yml/badge.svg?branch=4.0)](https://github.com/dotkernel/api/actions/workflows/run-tests.yml)
 [![codecov](https://codecov.io/gh/dotkernel/api/graph/badge.svg?token=53FN78G5CK)](https://codecov.io/gh/dotkernel/api)
 [![Qodana](https://github.com/dotkernel/api/actions/workflows/qodana_code_quality.yml/badge.svg)](https://github.com/dotkernel/api/actions/workflows/qodana_code_quality.yml)
 
 [![SymfonyInsight](https://insight.symfony.com/projects/7f9143cc-5e3c-4cfc-992c-377a001fde3e/big.svg)](https://insight.symfony.com/projects/7f9143cc-5e3c-4cfc-992c-377a001fde3e)
 
-
 ## Getting Started
 
-### Step 1: Clone the project
+## Step 1: Clone the project
+
 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:
 
     git clone https://github.com/dotkernel/api.git .
 
-
-### Step 2: Install project's dependencies
+## Step 2: Install project's dependencies
 
     composer install
 
+## Step 3: Development mode
 
-### Step 3: Development mode
 If you're installing the project for development, make sure you have development mode enabled, by running:
 
     composer development-enable
@@ -44,22 +43,21 @@ You can check if you have development mode enabled by running:
 
     composer development-status
 
+## Step 4: Prepare config files
 
-### Step 4: Prepare config files
 * duplicate `config/autoload/cors.local.php.dist` as `config/autoload/cors.local.php` <- if your API will be consumed by another application, make sure configure the `allowed_origins`
 * duplicate `config/autoload/local.php.dist` as `config/autoload/local.php`
 * duplicate `config/autoload/mail.local.php.dist` as `config/autoload/mail.local.php` <- if your API will send emails, make sure you 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` <- this creates a new in-memory database that your tests will run on
 
+## Step 5: Setup database
 
-### Step 5: Setup database
+## Running migrations
 
-#### Running migrations:
 * create a new MySQL database - set collation to `utf8mb4_general_ci`
 * fill out the database connection params in `config/autoload/local.php` under `$databases['default']`
 * run the database migrations by using the following command:
 
-
     php vendor/bin/doctrine-migrations migrate
 
 This command will prompt you to confirm that you want to run it:
@@ -68,16 +66,17 @@ This command will prompt you to confirm that you want to run it:
 
 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.** 
+## Executing fixtures
 
-To list all the fixtures, run: 
+**Fixtures are used to seed the database with initial values and should be executed after migrating the database.**
+
+To list all the fixtures, run:
 
     php bin/doctrine fixtures:list
 
 This will output all the fixtures in the order of execution.
 
-To execute all fixtures, run: 
+To execute all fixtures, run:
 
     php bin/doctrine fixtures:execute
 
@@ -87,22 +86,22 @@ To execute a specific fixture, run:
 
 More details on how fixtures work can be found here: https://github.com/dotkernel/dot-data-fixtures#creating-fixtures
 
-### Step 6: Test the installation
+## Step 6: Test the installation
 
     php -S 0.0.0.0:8080 -t public
 
-Sending a GET request to the [home page](http://localhost:8080/) should output the following message:
-```json
-{
-  "message": "Welcome to DotKernel API!"
-}
-```
+Sending a GET request to the [home page](http://0.0.0.0:8080/) should output the following message:
 
+    {
+    "message": "Welcome to DotKernel API!"
+    }
 
 ## Documentation
+
 In order to access DotKernel API documentation, check the provided [readme file](documentation/README.md).
 
 Additionally, each CLI command available has it's own documentation:
+
 * [Create admin account](documentation/command/admin-create.md)
 * [Generate database migrations](documentation/command/migrations-diff.md)
 * [Display available endpoints](documentation/command/route-list.md)

composer.json

@@ -44,6 +44,7 @@
     "require": {
         "php": "~8.2.0 || ~8.3.0",
         "ext-json": "*",
+        "ext-gd": "*",
         "dotkernel/dot-annotated-services": "^4.1.7",
         "dotkernel/dot-cache": "^4.0",
         "dotkernel/dot-cli": "^3.5.0",

docs/book/index.md

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

docs/book/v4/introduction/file-structure.md

@@ -0,0 +1,54 @@
+# File structure
+
+It is a good practice to standardize the file structure of projects. This way it’s easier to keep a clean overview of multiple projects, and less time is wasted trying to find the correct class.
+
+When using DotKernel API the following structure is recommended:
+
+## Main directories
+
+* `src` - should contain the source code files
+* `templates` - should contain the page templates and layouts
+* `data` - should contain project-related data (AVOID storing sensitive data on VCS)
+* `docs` - should contain project-related documentation
+
+These directories reside in one of the following directories:
+
+* if the Module is a composer package where the directories above are stored in the package’s root path, eg.: `/vendor/my-name/my-project-name/`
+* if the Module is an extension/component for the project, eg.: `/src/MyProjectName`
+
+## The `src` directory
+
+This directory contains all source code related to the Module. It should contain following directories, if they’re not empty:
+
+* Handler - Action classes (similar to Controllers but can only perform one action)
+* Entity - For database entities
+* Service - Service classes
+* Collection - Database entities collections
+* Repository - Entity repository folder
+
+> The above example is just some of the directories a project may include, but these should give you an idea of how the structure should look like.
+
+Other classes in the `src` directory may include `InputFilter`, `EventListener`, `Helper`, `Command`, `Factory` etc.
+
+The `src` directory should also contain 2 files:
+
+* `ConfigProvider.php` - Provides configuration data
+* `RoutesDelegator.php` - Module main routes entry file
+
+## The `templates` directory
+
+This directory contains the template files, used for example to help render e-mail templates.
+
+> DotKernel API uses twig as Templating Engine. All template files have the extension .html.twig
+
+## The `data` directory
+
+This directory contains project-related data (such as cache, file uploads)
+
+We recommend using the following directory structure:
+
+* `data/cache` - location where caches are stored
+* `data/oauth` - encryption, private and public keys needed for authentication.
+* `data/lock` - folder where lock files generated by commands are stored, if enabled
+* `data/doctrine/fixtures` - folder for doctrine data fixtures
+* `data/doctrine/migrations` - folder for doctrine migrations

docs/book/v4/introduction/getting-started.md

@@ -0,0 +1,5 @@
+# Clone the project
+
+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:
+
+    git clone https://github.com/dotkernel/api.git .