Maxiter

Install Maxiter

git clone https://github.com/maxiter-php/maxiter.git
                                

Clone the framework from GitHub, or create a new project with Composer if that fits your workflow better.

composer create-project maxiter/maxiter:dev-main
                                

cd maxiter
                                

After entering the project directory, serve it from a local web root such as htdocs, www, or a Docker volume.

CLI Entry

php maxiter
                                

The maxiter file is the framework command hub. Use it to scaffold controllers, APIs, models, middleware, views, unit tests, and migration helpers.

Safe Start Tips

LoadModel.php is the central runtime bootstrapper. If you modify bootstrap behavior, validate carefully because classic controllers and API execution may depend on the current load order.

If your project uses Composer, keep the autoload step available. If not, make sure manual class loading still matches the framework conventions.

Two Main Flows

Maxiter has two major request paths:

1. Page routing
2. API routing

Front Controller

The main front controller is index.php. It starts the session when needed, reads $_GET['url'], and decides whether the request should be handled as a classic page or delegated into the API flow.

Framework Style

Maxiter keeps routing file-based and direct. Controllers live in app/controllers, reusable logic stays in app/models, middleware lives in app/middlewares, and pages live under resources/views/pages.

Compatibility Mindset

Backward compatibility matters. Older Maxiter projects may still depend on legacy controller execution patterns, so framework changes should prefer additive behavior over disruptive rewrites.

index.php

Main front controller for page requests and API delegation.

routes/api.php

API bootstrap and dispatcher entrypoint.

routes/api/

Folder that stores API route definition files.

app/controllers/

Classic controllers and API controllers.

app/models/

Core framework models and project business logic.

app/middlewares/

Middleware classes used by the API router.

resources/views/pages/

Page folders, page PHP files, and page-specific CSS and JS assets.

src/template/

Template scaffolding source used by generation workflows.

maxiter

Custom CLI entrypoint.

env.ini

Main framework configuration file. Maxiter uses env.ini, not a modern .env-style setup.

bash.php and gui.html

Local development GUI tooling. Treat them as development helpers, not production runtime files.

Page Routing

Page requests start in index.php. If the first URL segment is not api, Maxiter resolves a page file using the pattern below:

resources/views/pages/<page>/<page>.php
                                

Examples:

/home  -> resources/views/pages/home/home.php
/login -> resources/views/pages/login/login.php
                                

Missing pages are redirected to ./error.

View Conventions

Shared layout fragments usually live in folders such as _header, _footer, _navbar, _sidenav, and _cards.

/resources/views/pages
    /_header
        header.php
    /_footer
        footer.php
    /home
        /css
            home.css
        /js
            home.js
        home.php
                                

Typical Page Bootstrap

<?php require __DIR__ . "/../../../../app/models/LoadModel.php"; ?>
<?php include __DIR__ . "/../_header/header.php"; ?>

<div class="container">
    <h2>Home Page</h2>
</div>

<script src="./resources/views/pages/home/js/home.js"></script>
<?php include __DIR__ . "/../_footer/footer.php"; ?>
                                

New work should keep the page folder pattern because it is part of the framework developer experience.

API Bootstrap Flow

When the first path segment is api, index.php stores the parsed route in $_SESSION['api-route'] and forwards execution to routes/api.php.

ApiModel::reset();
ApiModel::loadRoutesFromDirectory(__DIR__ . '/api');
ApiModel::dispatch($urlParsed);
                                

Route Files

API route definition files live in routes/api/.

ApiModel::controller('ApiTestController', function () {
    ApiModel::get('/info', 'info');
    ApiModel::get('/users/{id}', 'user');
    ApiModel::get('/posts/{postId}/comments/{commentId}', 'postComment');
});
                                

Supported Registration Methods

The API router supports get, post, put, patch, delete, any, match, group, prefix, controller, and middlewareGroup.

Routing Behavior

Dynamic parameters like /users/{id} are supported. Parameters are injected into controller methods by parameter name. Unmatched API routes return a JSON 404.

Legacy Note

ApiModel::route() still exists for compatibility with older code.

env.ini

Maxiter stores application settings in env.ini. Important values commonly include APP_NAME, APP_DESCRIPTION, BEARER_TOKEN, DEFAULT_TIMEZONE, and database sections.

[app]
APP_NAME="Maxiter"
APP_DESCRIPTION="Custom PHP framework"
BEARER_TOKEN="your-token"

[timezone]
DEFAULT_TIMEZONE="America/Sao_Paulo"

[maxiter]
DB="maxiter"
DRIVER="mysql"
PORT="3306"
HOST="localhost"
USER="root"
PASS=""
                                

Read Config Values

echo EnvModel::env("APP_NAME");
                                

Database Usage

$result = DatabaseModel::connection(EnvModel::env("DB"))
    ->execute("SELECT * FROM users WHERE id = :id", array(
        ":id" => 11
    ));

$data = $result->fetch(PDO::FETCH_ASSOC);
ResponseModel::json(true, $data);
                                

Base URL Strategy

Maxiter no longer depends on a manually configured APP_BASE_URL. Base URL, base path, scheme, and host are inferred at runtime by AppUrlModel. New code should prefer AppUrlModel::url() and AppUrlModel::asset().

Maxiter keeps reusable runtime logic in app/models. The models below are the most important ones to understand before changing framework behavior.

LoadModel

LoadModel.php is the framework bootstrapper. It starts the session if needed, loads Composer autoload when present, requires core models, sets the timezone from env.ini, and initializes CORS.

require __DIR__ . "/../models/LoadModel.php";
                                

If you change bootstrapping, review both classic controllers and API requests because they often depend on this file directly.

AuthModel

AuthModel is the framework helper for authentication and authorization. It commonly checks session state and optional authorities.

if (AuthModel::verify()) {
    ResponseModel::json(true, "Authenticated");
}

if (AuthModel::verify(null, array("administrator"))) {
    ResponseModel::json(true, "Authorized");
}
                                

User context can be read through AuthModel::getContext() when login logic stores the expected session data.

AppUrlModel

AppUrlModel dynamically resolves scheme, host, base path, and base URL. It replaced the older hardcoded base URL approach and should be preferred for new links and asset generation.

echo AppUrlModel::baseUrl();
echo AppUrlModel::url("login");
echo AppUrlModel::asset("resources/views/pages/home/css/home.css");
                                

Do not reintroduce a static base URL unless the project explicitly requires that behavior.

ResponseModel

ResponseModel standardizes JSON and HTTP responses in controllers and API endpoints.

ResponseModel::json(true, array("status" => "ok"));
ResponseModel::json(false, "Unauthorized access", 401);
ResponseModel::http(404);
                                

API controllers often return arrays or strings directly, but ResponseModel::json() remains the clearest way to send explicit JSON responses.

Security & Utility

SecureRequestModel protects classic controller requests by validating trusted request origin data such as HTTP_HOST, HTTP_X_FORWARDED_HOST, HTTP_ORIGIN, and HTTP_REFERER.

require __DIR__ . "/../models/LoadModel.php";
require __DIR__ . "/../models/SecureRequestModel.php";
                                

Other important helpers include CorsModel, TreatModel, PagesTitleModel, and LogModel. They keep cross-cutting concerns out of controllers and preserve framework conventions.

CLI Overview

Maxiter ships with a framework CLI accessed through php maxiter. It focuses on file-system-oriented commands and simple developer workflows.

php maxiter new controller NameController

Creates a classic controller in app/controllers/.

php maxiter new controller UsersController
                                

php maxiter new model Name

Creates a new model in app/models/.

php maxiter new model Payments
                                

php maxiter new view Name

Creates a new page/view structure following the framework page conventions.

php maxiter new view Login
                                

php maxiter new log [Database_Name]

Creates a log model example using the informed database connection name.

php maxiter new log maxiter
                                

php maxiter new table [table_name]

Creates a table SQL example in the framework source area for known reference tables.

php maxiter new table users
                                

php maxiter new api NameController

Creates an API controller in app/controllers/ and a route file in routes/api/ with a default route based on the controller name.

php maxiter new api ApiUsersController
                                

php maxiter new middleware Name

Creates a middleware class in app/middlewares/. Middleware classes expose public static function handle().

php maxiter new middleware BearerAuthorizationMiddleware
                                

php maxiter new unittest Controller Method

Generates a unit test scaffold for a controller method.

php maxiter new unittest UsersController userLogin
                                

Server, GUI, and Path Utilities

Useful developer utilities include:

php maxiter server [port]
php maxiter gui
php maxiter pathcheck
                                

The GUI and helper pages are intended for local development workflows.

php maxiter path [url_base_path]

Sets the base path used by the project when you need to define it manually for a local environment.

php maxiter path http://localhost/my-project/
                                

php maxiter new template [template_name]

Applies a template from src/template/[template_name] to the current project structure.

php maxiter new template admin-dashboard
                                

php maxiter gui

Opens the Maxiter GUI helper in the browser for local development tasks and quick project actions.

php maxiter gui
                                

php maxiter testme

Runs the PHPUnit test suite after project dependencies are installed.

composer install
php maxiter testme
                                

php maxiter config prod

Generates a production-oriented ignore configuration and related cleanup guidance for non-production files.

php maxiter config prod
php maxiter deltoprod
php maxiter -f deltoprod
php maxiter -r deltoprod
                                

php maxiter new component [component_name] [template_name]

Generates a reusable component file and can optionally use a template-defined component block.

php maxiter new component searchbox
php maxiter new component searchbox mytemplate
                                

php maxiter autopath [optional: port]

Attempts to detect and configure the application base path automatically for the local environment.

php maxiter autopath
php maxiter autopath 7000
                                

php maxiter mirror [database_name] export|import

Exports or imports database mirror files using the configured connection name from env.ini.

php maxiter mirror maxiter export
php maxiter mirror maxiter import
php maxiter mirror maxiter import 01-01-2001
                                

php maxiter pathcheck

Returns the current path configuration used by the application.

php maxiter pathcheck
                                

php maxiter cro / crn

Switches route/controller execution mode between older and newer project styles when a legacy project requires that behavior.

php maxiter cro
php maxiter crn
                                

[BETA] php maxiter versioning "[PATH]"

Migrates an older Maxiter-based project into the current framework version. It validates the source path, copies pages and controllers, copies middleware when present, copies only missing model files, and backs up overwritten files into src/versioning_backup/<timestamp>/.

php maxiter versioning "C:/legacy-project"
                                

php maxiter codeversion 5.3

Scans models, controllers, and middleware for syntax or features incompatible with the specified PHP version and writes a report to src/codeversion/<version>/verification-<timestamp>.txt.

php maxiter codeversion 5.3
                                

The generated report should list the affected file, affected line, incompatibility reason, and offending code line only.

Template scaffolding source lives in src/template/. Generated pages and front-end assets continue to follow the resources/views and resources/views/pages/<page>/ conventions.

Page Asset Convention

resources/views/pages/<page>/css/
resources/views/pages/<page>/js/
                                

Recommended URL Helpers

For new work, prefer runtime-aware helpers such as AppUrlModel::url() and AppUrlModel::asset() instead of hardcoded paths.

Template Reminder

Keep scaffolding straightforward. Maxiter favors simple developer-facing file patterns over abstraction-heavy template systems.

Legacy-Friendly Code

Compatibility-sensitive internals should stay friendly to older PHP versions, especially when the area is meant to remain compatible with PHP 5.3.

Avoid:
- short arrays []
- ::class
- scalar type hints
- return types
- nullable types
- arrow functions
- typed properties
- enums
                                

Security Model

Classic controller access relies on SecureRequestModel. API security can be extended through middleware such as bearer authorization handlers.

CORS and Runtime Safety

LoadModel initializes CORS. Session startup also needs to remain safe because the API flow depends on session state before dispatching the stored route.

Production-Sensitive Files

Treat gui.html and bash.php as local development tools. Review carefully before exposing them in production environments.

Files to Understand First

index.php
routes/api.php
app/models/LoadModel.php
app/models/ApiModel.php
app/models/AppUrlModel.php
app/models/EnvModel.php
app/models/ResponseModel.php
app/models/AuthModel.php
app/models/SecureRequestModel.php
maxiter
bash.php
gui.html
                                

Good Defaults for Framework Work

Preserve current runtime behavior unless a redesign is explicitly requested. Keep routing file-based, keep scaffolding predictable, and prefer small framework-consistent changes.

When Documenting or Extending Maxiter

Always clarify whether the work affects page routing, API routing, CLI, models, or generated scaffolding. Also call out PHP-version and backward-compatibility impact whenever framework internals are involved.