phpEZ v0.3.0

API Documentation

Table of Contents

Interfaces

Parsable
Interface for custom serialization/deserialization of values.

Classes

Unique
Attribute to mark a database field as UNIQUE.
UniqueMulti
Attribute to create a composite (multi-column) UNIQUE constraint.
Index
Attribute to create a database index on a field.
CustomType
Attribute to override the default database column type.
OnUpdate
Attribute to specify ON UPDATE behavior for a database column.
DbDefault
Attribute to specify a default value for a database column.
NotNull
Attribute to mark a field as NOT NULL in the database.
Foreign
Attribute to create a foreign key constraint on a field.
DataException
Base exception for database operation failures.
DuplicateException
Exception for database constraint violations (e.g., unique, foreign key).
Database
Central database connection manager for PHPEz.
Model
Base ORM model class for database-backed entities.
DBDateTime
DateTime serializer for database operations.
HTTPException
Base exception class for HTTP API errors.
NotFoundException
Exception for missing resources (HTTP 404).
HTTPSrv
HTTP server utility class for request context.
Get
Query parameter accessor for GET requests.
Post
Body parameter accessor for POST requests.
BoolGet
Boolean query parameter accessor for GET requests.
Api
Represents a single API endpoint with smart request handling.
JSONDateTime
DateTime serializer for JSON responses.
CustomResponse
Base class for custom response types with specific Content-Type handling.
StringHTMLContent
Base class for custom response types with specific Content-Type handling.
Redirect
Base class for custom response types with specific Content-Type handling.
App
Central API application router and orchestrator.
ObjAttribute
Base class for property-level attributes in the PHPEz framework.
ObjDef
Base class for class-level attributes in the PHPEz framework.
OmitEmpty
Attribute to omit uninitialized properties from serialization.
ArrayOf
Attribute specifying the element type of an array property.
DoNotSerialize
Attribute to exclude a property from serialization.
DoNotDeserialize
Attribute to exclude a property from deserialization.
Obj
Base class for serializable/deserializable API data objects.
SerializableDateTime
Base class for serializable DateTime objects.
Sex
Session management helper for PHPEz.

Traits

CachableModel
Trait for models supporting instance caching by ID.
SoftDelete
Trait adding soft-delete support to a Model.

Enums

DbThen
Foreign key constraint actions enum.
SoftDeleteFilter
Filter option for querying soft-deleted rows.
HTTP
HTTP request method enum.
HTTPCode
HTTP response status codes enum.

Constants

BASE_PATH  : mixed = \realpath(__DIR__) . \DIRECTORY_SEPARATOR
Absolute path to the framework base directory.

Functions

glb()  : mixed
Safely retrieve a global variable by name.
rmbasepath()  : mixed
Convert a file path to relative, human-readable form.
excClean()  : mixed
Clean and format a stack trace entry for JSON output.
final_json()  : never
Sends a final JSON response and terminates the request.
require_blank_ctx()  : void
Load a PHP file in a clean context with access to the App instance.
html()  : StringHTMLContent
Helper function to create a StringHTMLContent response.
redirect()  : Redirect
Helper function to create a Redirect response.

Constants

BASE_PATH

Absolute path to the framework base directory.

public mixed BASE_PATH = \realpath(__DIR__) . \DIRECTORY_SEPARATOR

Used for relative path rendering in debug output (converted to ~/). Prevents exposing full server paths in error responses.

Tags
const

string

Functions

glb()

Safely retrieve a global variable by name.

glb(string $vname[, mixed $default = null ]) : mixed

Avoids PHP notices for undefined globals and provides a consistent interface for accessing framework globals like $debug.

Usage:

$debug = glb('debug', false);      // Get $debug or default to false
$startup = glb('_startup');         // Get $_startup or null
Parameters
$vname : string

The variable name (without $).

$default : mixed = null

Default value if the global is not set. Defaults to null.

Return values
mixed —

The global variable value or $default.

rmbasepath()

Convert a file path to relative, human-readable form.

rmbasepath(mixed $r) : mixed

Replaces BASE_PATH with '~/' to hide absolute paths in error output and logs. Non-string values are returned unchanged.

Usage (internal):

rmbasepath('/var/www/html/calendula/api/sys/db.php')
// Returns: ~/api/sys/db.php
Parameters
$r : mixed

The path or value to process.

Return values
mixed —

The path with BASE_PATH replaced by '~/', or original value if not a string.

excClean()

Clean and format a stack trace entry for JSON output.

excClean(mixed $e) : mixed

Extracts the most relevant information from a trace entry and obscures absolute paths for security. Produces a compact, debuggable format.

Processing:

  1. Returns original entry if no file information (incomplete trace)
  2. Formats as: "~/path/to/file.php:123"
  3. Includes function/class information
  4. Sanitizes argument paths

Output format:

[
  "~/api/sys/db.php:156" => [
    "fun" => "Model::save",
    "args" => [ "~/api/claz/User.php" ]
  ]
]
Parameters
$e : mixed

A trace entry from Exception::getTrace().

Return values
mixed —

The cleaned trace entry, or original if no file info.

final_json()

Sends a final JSON response and terminates the request.

final_json(array<string|int, mixed>|object $out) : never

This is the standardized output function for the PHPEz API. It ensures only one JSON response is sent, appends request processing time, and halts execution.

If called multiple times, subsequent calls will dump to output with "FATAL:" prefix to indicate a logic error.

The response format is:

{
  "success": true,
  "data": {...},
  "x-time-ms": 42.5
}
Parameters
$out : array<string|int, mixed>|object

The response data to encode and send as JSON. Will have 'success' and 'x-time-ms' fields added by callers.

Return values
never —

This function always terminates script execution.

require_blank_ctx()

Load a PHP file in a clean context with access to the App instance.

require_blank_ctx(string $path, App $APP) : void

Used internally to load route definition files. Each loaded file receives the App instance as $APP, allowing route registration via closures.

This pattern avoids polluting the global namespace while keeping route definitions in separate files for organization.

Parameters
$path : string

Absolute path to the PHP file to include.

$APP : App

The application instance for route registration.

Tags
example 
// In api/root/user.php:
$APP->get('/user/{id:i}', function(int $id) { ... });

html()

Helper function to create a StringHTMLContent response.

html(string $html) : StringHTMLContent
Parameters
$html : string

The HTML content to send in the response.

Return values
StringHTMLContent —

A custom response object with the given HTML.

redirect()

Helper function to create a Redirect response.

redirect(string $url[, int $statusCode = 302 ]) : Redirect
Parameters
$url : string

The URL to redirect to.

$statusCode : int = 302

The HTTP status code for the redirect (default 302).

Return values
Redirect —

A custom response object that performs the redirect.

On this page

Search results