Getting Started

Getting Started

This guide creates an application using the Machinjiri installer, starts its development server, and adds a first route. Commands should be run from the generated application directory unless noted otherwise.

1. Check prerequisites

• PHP 8.4 or newer
• Composer
• A terminal and editor

Database drivers and PHP extensions are needed only when your application uses their related features. Check the app's dependency and configuration files for optional integration requirements.

Confirm your installed versions:

php --version
composer --version

2. Create an application

The installer is separate from the framework package. Install it globally and create a project:

composer global require machinjiri/installer
machinjiri create hello-machinjiri
cd hello-machinjiri

If the shell cannot find machinjiri, add Composer's global vendor/bin directory to your PATH, or invoke the installer through Composer's documented global binary path.

Install the project's dependencies if the installer did not already do so:

composer install

The application structure is determined by the installer version. A typical generated app has route, controller, view, configuration, and public-entrypoint files. Inspect the generated files instead of assuming exact paths from a different release.

3. Start the development server

In the generated app directory:

php artisan run:dev

The README's starter project example serves at http://localhost:3000. Follow the address printed by your app if the port differs. Keep the process running while developing; use Ctrl+C to stop it.

The framework source repository alone does not include an artisan file. This command is supplied by the generated application.

4. Add a route

In your generated routes/web.php, define a GET route:

<?php

use Mlangeni\Machinjiri\Core\Routing\Router;

Router::get('/', function () {
    return '<h1>Hello from Machinjiri!</h1>';
}, 'home');

Router::dispatch();

If the generated route file already calls Router::dispatch(), keep that existing call and add only the route definition. A route maps an HTTP method and URL pattern to a handler; the optional name home can be used to generate a URL later.

Reload the app's local URL. If the route is not found, verify that the generated front controller loads this route file and that routes are dispatched once per request.

5. Move handling into a controller

Create app/Controllers/HomeController.php in an application skeleton that uses this layout:

<?php

namespace App\Controllers;

use Mlangeni\Machinjiri\Core\Artisans\Base\AbstractController;
use Mlangeni\Machinjiri\Core\Http\HttpRequest;
use Mlangeni\Machinjiri\Core\Http\HttpResponse;

class HomeController extends AbstractController
{
    public function index(HttpRequest $request, HttpResponse $response): string
    {
        return $this->view('home', [
            'title' => 'My Machinjiri page',
            'message' => 'The route called a controller.',
        ]);
    }
}

Point the route to that method:

use App\Controllers\HomeController;
use Mlangeni\Machinjiri\Core\Routing\Router;

Router::get('/', [HomeController::class, 'index'], 'home');

AbstractController provides the view() helper. The application must have a working autoloader and view configuration for the generated controller and view locations.

6. Run project tests

composer test

The command runs the test script declared by the application package. A fresh framework checkout may not have application tests or an Artisan entry point; use the commands and test setup present in the project you are working on.

Next steps

• Continue to Routing and Controllers.
• Learn safe template output in Views and Responses.
• See Database before connecting persistent application data.
• Review Security and Authentication before handling user input or credentials.

Common setup issues

Symptom	Check
machinjiri: command not found	Composer's global binary directory is on PATH; the installer is installed globally.
Could not open input file: artisan	You are in the generated app directory, not the framework package checkout.
Composer reports a PHP platform conflict	The framework requires PHP ^8.4; check the CLI PHP selected by Composer.
Route returns 404	Confirm route file loading, method/path, and a single dispatch call.
View cannot be found	Confirm the generated view directory and view-engine configuration.