AI blog · DotApp PHP Framework 2.0

Error handling and return values in DotApp PHP Framework

DotApp PHP Framework does not have one failure style. Guessing the wrong one is the usual source of blank pages and uncaught exceptions. Database execute() uses a callback pair. Cache misses are null. Validator::validate returns true or an array (the array is truthy). resolve(), some Auth calls, and QueryBuilder build errors throw. A missing view is "" plus a log warning — not an exception. This article is the map plus a complete Shop save that guards every shape.

Four failure styles

Fifth trap: some methods return void and only report through callbacks (Entity::save()). Database details: How to use the database. Request form() shapes: Request lifecycle.

Common mistakes

execute() return table

On a cache hit, $execution_data is an empty array — use ?? null. Keys when present: affected_rows, insert_id, num_rows, result, query, bindings.

Complete Shop save with every guard

File: app/modules/Shop/Controllers/Item.php — POST half. Channel form + named RAW + empty view already covered in other articles; this is the failure-shape checklist in one method. crcCheck() appears here once — not also in middleware.

<?php
namespace Dotsystems\App\Modules\Shop\Controllers;

use Dotsystems\App\DotApp;
use Dotsystems\App\Parts\DB;
use Dotsystems\App\Parts\Logger;
use Dotsystems\App\Parts\Validator;

class Item extends \Dotsystems\App\Parts\Controller
{
    public static function save($request)
    {
        try {
            if (!$request->crcCheck()) {
                return DotApp::DotApp()->ajaxReply(['status' => 0, 'message' => 'Bad request'], 400);
            }

            $answer = $request->form(
                ['POST'],
                'saveItem',
                function ($request) {
                    $payload = $request->data(true)['data'] ?? [];
                    $title = trim((string) ($payload['title'] ?? ''));
                    $check = Validator::validate(['title' => $title], ['title' => 'required|min:1']);
                    if ($check !== true) {
                        return ['code' => 200, 'body' => ['status' => 0, 'message' => 'Title required']];
                    }
                    $newId = null;
                    DB::module('RAW')->q(function ($qb) use ($title) {
                        $qb->raw(
                            'INSERT INTO shop_items (title, created_at) VALUES (:title, :created_at)',
                            ['title' => $title, 'created_at' => date('Y-m-d H:i:s')]
                        );
                    })->execute(
                        function ($result, $db, $execution_data) use (&$newId) {
                            $newId = $execution_data['insert_id'] ?? $db->inserted_id();
                        },
                        function ($error) {
                            Logger::use()->error('item save failed', $error);
                        }
                    );
                    if ($newId === null) {
                        return ['code' => 200, 'body' => ['status' => 0, 'message' => 'Save failed']];
                    }
                    DotApp::dotApp()->trigger('shop.item.saved', true, (int) $newId);
                    return ['code' => 200, 'body' => ['status' => 1, 'id' => $newId]];
                },
                function () {
                    return ['code' => 403, 'body' => ['status' => 0, 'message' => 'Invalid signature']];
                }
            );

            if (!is_array($answer) || !isset($answer['body'])) {
                return DotApp::DotApp()->ajaxReply(['status' => 0, 'message' => 'Rejected'], 400);
            }
            return DotApp::DotApp()->ajaxReply($answer['body'], $answer['code']);
        } catch (\Throwable $e) {
            Logger::use()->error('Shop save failed', ['msg' => $e->getMessage()]);
            return DotApp::DotApp()->ajaxReply(['status' => 0, 'message' => 'Server error'], 500);
        }
    }
}
    

Application errors stay HTTP 200 with status 0 so .after() can show them. Envelope failures stay 400/403 and need .onError() in JS. Events: Events and listeners. JSON HTTP (no channel): JSON endpoints.

Quick lookup